HOOPS for C/C++ Developers

C/C++ Defines

To have access to function prototypes for the HC_ routines that comprise the HOOPS Visualize API, users of HOOPS Visualize include the file hc.h in their programs. Users of HOOPS I.M. additionally include hic.h to have access to the intermediate mode routines. The intermediate mode routines are NOT a layer on top of Visualize. The intermediate mode routines directly access the data and procedures used by HOOPS Visualize itself. Inclusion of hic.h automatically includes hoops.h for the user. The conventions and coding style for Visualize itself are embodied in hoops.h. This coding style is easily identifiable by viewing driver source code. The following words are defined in hoops.h:

• null

• countof

• true, false

• forever

• until

• global, globaldata

• local

• nobreak

• stack

Don’t use these words in HOOPS I.M. programs.

Routine Names: Prefixes

Each routine name, such as Insert_Polyline, in your Visualize program must have a prefix before the name will actually be usable on your computer system. The prefix varies depending on which language you’re calling from, and sometimes depending on the brand of the language you’re calling from. When calling from C and C++, users must preface the routines with HC_ as in Reset_System.

Common Names

All HOOPS Visualize routine names follow a standard pattern: the first part of the name is an active verb indicating what’s to be done, and the second part is a descriptive noun. The most common verbs are:

• Define: Changes a global system status, or adds something to a system-wide table.

• Insert: Incorporates a new picture element into the current segment and returns a reference to the element.

• DInsert: Double precision version of insert. Pass doubles instead of floats.

• Edit: Changes the definition of an existing picture element.

• DEdit: Double precision version of edit. Pass doubles instead of floats.

• Set: Loads an explicit new value for an attribute.

• UnSet: Undoes a Set. (Allows an attribute value to be inherited once again from a higher level.)

• Show: Retrieves an item of information from the system.

• DShow: Double precision version of show. Returns doubles instead of floats.

• Begin: Initializes a database information search.

• Find: Steps an information search along.

• End: Completes an information search.

Please note that there are a number of miscellaneous verbs that arise from the various state-modifying routines, such as Dolly_Camera and Rename_Segment. These less frequently occurring verbs are usually self explanatory.

The most common nouns include the following:

• Segment: The routine works with a graphics segment (a place for storing picture elements) as one element.

• Camera: The routine positions or moves the viewing camera.

• Object: The routine works with the “real” objects (as organized into segments) from which your scene is composed.

• Text: The routine affects the text labels appearing in the scene.

Data Type Names and Language Declarations in C/C++

HC Conventions

The datatypes used by the HC_ subroutines translate as follows:

Because the bit pattern used by HOOPS might not be identical to the bit pattern of your TRUE macro, avoid an explicit comparison of a Boolean to “TRUE”. Instead, rely on the C property of “not equal to zero”. If the routine definition specifies Passed by reference, your argument in C must be either a simple variable preceded by an “&” or a pointer value. If the routine definition specifies a returns clause, you can ignore the return value in C. This might not be true in other languages. If an actual parameter which is a string is specified as Passed by reference. Returned to user, you must provide the address of a simple variable large enough to hold what might be returned. (A call to Define_System_Options can be used to specify the maximum C string length that HOOPS should return.)

HIC Conventions

The additional data types used by the HIC_ subroutines translate as follows:

HIC_Marker, HIC_Point, HIC_Polygon, HIC_Polyline, and HIC_Text

Structures containing the defining information and some derived information for a 3D geometry primitive (as inserted by an application into the database). The defining vertices of these primitives are given with respect to object coordinates. You can create new instances of these structures with the HIC_New_(geometry) functions. You can determine the defining parameters (e.g., vertex count and vertex arrays) of given instances with the HIC_Show_... functions.

HIC_Geometry

A union type incorporating all the HOOPS geometry types. including HIC_Marker, HIC_Point, HIC_Polygon, HIC_Polyline, HIC_Text, and the other geometry types not directly relevant to the HOOPS I.M. programmer.

HIC_Segment_Info

A complex structure containing information describing a particular segment. It is passed as an argument to a small set of segment-dependent methods. There is not much you can do with it but pass it on to the segment-dependent HIC_... functions that you might call.

HIC_Window_Info

A complex type describing a window. In intermediate mode, it occurs only as an argument to the “select windows”; callback.

HIC_Rendition

A large structure type containing a complete set of values of all HOOPS attributes. Every method for which there is a callback point takes a rendition as one of its arguments, the net rendition nr, giving all the attribute values in effect at that callback point. Most of the HIC_... functions take a rendition argument. You can query the current values of attributes in a rendition by calling the HIC_Show_..._(attribute) functions. You can create new renditions with HIC_New_Rendition, and you can set attribute values in a new rendition with the HIC_Set_(attribute) functions.

HIC_Text_Info

A complex type that contains information about a particular text string at an intermediate stage in the rendering pipeline. You can query the relevant parameters of an instance of this type with the HIC_Show_Text_(parameters) functions. Example:

typedef struct point {float x,y,z; } HIC_Point;
typedef struct dc_point {float x,y,z;} HIC_DC_Point;
typedef struct vector {float x,y,z;} HIC_Vector;

While these three types have the same declaration, they are used to distinguish device coordinates from object coordinates and points from vectors.

Rectangle Types

Example:

typedef struct int_rectangle {
   int left, right, bottom, top;
} HIC_Int_Rectangle;

typedef struct clip_rectangle {
        struct clip_rectangle *next;
        int left, right, bottom, top;
} HIC_Clip_Rectangle;

The linking pointer next in HIC_Clip_Rectangle is for internal use, and of no concern to the I.M. programmer.

Color Types

Example:

typedef struct HIC_rgb {
  float red, green, blue;
} HIC_RGB;

typedef struct HIC_rgba {
        float red, green, blue, alpha;
} HIC_RGBA;

These are most commonly used for specifying a color as three/four floats for the RGB/RGBA components. In the HIC_RGB and HIC_RGBA types, the components are generally all between 0 and 1.

Internally, HOOPS also uses a four-byte color type, HIC_RGBAS32. The ordering of the components as defined by PREFERRED_RGB32 however, depends on the CPU, specifically on its byte-ordering convention or its endian-ness:

typedef union HIC_rgbas32 {
        HIC_Integer32 whole_thing;
        struct {
                /*
                 The ordering of HIC_RGB for 32 bits is system dependent. We define
                 the HIC_RGB ordering correctly here and in phedron.h for local display
                 or display on same-vendor hardware. If the display is across the
                 network to different-vendor hardware, then the Drivers must check
                 the ordering of HIC_RGB and rearrange it if necessary.
                */

                unsigned char PREFERRED_RGB32;
        } rgb;
} HIC_RGBAS32;

Thus, when dealing with a color variable color of this type, you can refer to all four components as color.whole_thing. You also can safely reference, say, the red component as color.rgb.r. But, if you want your code to be platform-independent, then you cannot make assumptions as to which physical byte this represents.

Stand-Alone Example Programs in C

Stand-alone HOOPS Visualize programs are located in the <VISUALIZE>/demo/common/standard directory and in the <VISUALIZE>/demo/common/tutorial directory. The C programs demonstrate usage of most HOOPS/3dGS routines and are useful in understanding the basic syntax of the API as well as for test purposes. Executables can be built with the supplied makefile.