To have access to function prototypes for the HC_ routines that comprise the HOOPS API, users of HOOPS 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 HOOPS. The intermediate mode routines make direct access to the data and procedures used by HOOPS itself. Inclusion of hic.h automatically includes hoops.h for the user. The conventions and coding style for HOOPS 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:
Don't use these words in HOOPS I.M. programs.
Each routine name, such as Insert_Polyline,
in your HOOPS 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 "HC_Reset_System()").
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 into the scene.
KInsert Incorporates a new picture element and returns a reference key to the element.
QInsert Quickly opens a different segment. Inserts a new picture element and closes the segment
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.
QSet Quickly opens a different segment. Sets and closes the segment.
UnSet Undoes a Set. (Allows an attribute value to be inherited once again from a higher level.)
QUnSet Quickly opens a different segment. UnSets and closes the segment.
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.
The datatypes used by the HC_ subroutines translate as follows:
HOOPS | HOOPS (HC) type |
'HC_KEY' | HC_KEY |
'integer' | int |
'boolean' | int |
'short' | short |
'float' | float |
'string' | char * (zero terminated) |
'single point' | struct {float x,y,z;} or float [3] |
'point vector' | struct {float x,y,z;} [n] or float [n][3] |
'array of 4 floats' | float [4] |
'4 ¥ 4 array of floats' | float [4][4] |
'vector of short integers' | short [n] |
'vector of long integers' | long [n] |
'2-D array of short integers' | short [r][c] |
'vector of integers' | int [n] |
The additional datatypes used by the HIC_ subroutines translate as follows:
Structures containing the defining information and some derived information for a 3D geometry primitive (as Insert_ ed 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.
A union type incorporating all the HOOPS geometry types. including HT_Marker, HT_Point, HT_Polygon, HT_Polyline, HT_Text, and the other geometry types not directly relevant to the HOOPS I.M. programmer.
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.
A complex type describing a window. In HOOPS I.M. it occurs only as an argument to the "select windows" callback.
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.
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.
typedef struct point {float x,y,z; } HT_Point;
typedef struct dc_point {float x,y,z;} HT_DC_Point;
typedef struct vector {float x,y,z;} HT_Vector;
While these three types have the same declaration, they are used to distinguish device coordinates from object coordinates and points from vectors.
typedef struct int_rectangle {
int left, right, bottom, top;
} HT_Int_Rectangle;
typedef struct clip_rectangle {
struct clip_rectangle *next;
int left, right, bottom, top;
} HT_Clip_Rectangle;
(The linking pointer next in HT_Clip_Rectangle is for internal use, and of no concern to the I.M. programmer.)
typedef struct ht_rgb {
float red, green, blue;
} HT_RGB;
typedef struct ht_rgba {
float red, green, blue, alpha;
} HT_RGBA;
These are most commonly used for specifying a color as three/four floats for the RGB/RGBA components. In the HT_RGB and HT_RGBA types, the components are generally all between 0 and 1.
Internally, HOOPS also uses a four-byte color type, HT_RGBAS32. The ordering of the components as defined by PREFERRED_RGB32 however, depends on the CPU, specifically on its byte-ordering convention ("endian-ness"):
typedef union ht_rgbas32 {
HT_Integer32 whole_thing;
struct {
/**
* The ordering of HT_RGB for 32 bits is system dependent. We define
* the HT_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 HT_RGB and rearrange it if necessary.
**/
unsigned char PREFERRED_RGB32;
} rgb;
} HT_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.