Intermediate Mode Routines


What is HOOPS I.M.?
Why use HOOPS I.M.?
Overview of the Update Cycle
Callback Points
Setting Callbacks
HOOPS I.M. Functions
Data Types


What is HOOPS I.M.?

HOOPS I.M. routines complement the classic HOOPS library and provide for traversal-time modifications of an object hierarchy (segment tree). HOOPS is a retained graphics database system. You create a scene by inserting geometry and setting attributes in a segment tree maintained by HOOPS. When you call Update_Display (or you request input), the system traverses the segment tree and draws the picture on the display device. With the classic HOOPS library, additions and modifications to the segment tree cannot be made while HOOPS is traversing the tree. The I.M. library provides a means for the application to trap the HOOPS update cycle at certain points in the rendering pipeline, by means of a callback mechanism. When you trap the traversal at a callback point, you can make decisions about what and how something is drawn, or even abort the traversal process itself. In addition to the callback mechanism, the HOOPS I.M. library provides a set of functions you can call from your callback functions to draw to the display in an "immediate mode" style and to query the graphics database and the device characteristics.
The HOOPS selection feature also involves a traversal of the graphics database contained in the segment tree. However, the selection traversal does not draw on the display. Rather, it computes the screen positions of objects in the database to determine which objects have been hit by selection events. HOOPS I.M. provides callback points at which you can trap the selection traversal as well as the update traversal.

Why use HOOPS I.M.?

You would use HOOPS I.M. when you want your application to be able to make traversal-time decisions about the rendering or selection process, or to accomplish special processing that is not provided by the built-in HOOPS traversal process. Here are some examples of situations for I.M. use:

Overview of the Update Cycle

To perform a display update, HOOPS clears the screen, then traverses (walks) the segment tree. Each segment can contain a list of inserted geometry elements, some attribute settings, and possibly a list of pointers to owned segments.
Attributes are inherited down the tree (and some are inherited upwards). Some attributes, such as the net modelling matrix, are accumulated down the tree. The traversal process keeps track of the current values of the attributes as it walks the tree. A rendition is a structure that contains a value for each of the defined HOOPS attributes. The net rendition is the set of attribute values that apply to a particular segment when it is processed by the traversal.
Geometry stored in the segment is specified in terms of the 3D object coordinates that the application uses in inserting primitives. At each segment, the HOOPS system processes the list of geometry elements, and passes each geometry element through a rendering pipeline to produce the pixels that are written to the screen (possibly subject to a Z-buffer test). These rendering computations include a transformation pipeline that applies the net modelling transformation to map the geometry to world coordinates, and then applies the viewing transformations and screen transformations (which are defined by the camera attributes) to map the geometry to the device coordinates that place objects on the display surface. (More details on the definition of device coordinates are given below).
We can describe the traversal process and rendering pipeline in terms of a hierarchy of methods. At the top level is the method that walks the tree. A submethod of the tree walk is "draw segment", which processes all the geometry in a segment, and recursively processes its subsegments. "draw segment" is the highest level method that you can trap with HOOPS I.M.
HOOPS geometry elements are of several types--polygon, polyline, circle, circular arc, text, marker, mesh, shell, etc. (See the discussion of HIC_Show_Geometry_Type in the reference section for the complete list of geometry types). The "draw segments" method traverses a segment's list of geometry elements and applies a method "draw 3d ..." to each geometry element according to its type "..."
Each "draw 3d ..." method must perform the necessary modelling and viewing transformations and eventually call on lower-level "draw dc ..." drawing methods, which draw primitives specified in device coordinates. For some of the geometry types, the "draw 3d ..." method must decompose the object into smaller objects of one or more types. Thus, a mesh or shell will be decomposed into multiple faces and edges and so give rise to a number of "draw dc ... " calls.
For the text primitives, HOOPS I.M. offers the ability to trap the pipeline at an intermediate level, "draw text", between the "draw 3d text" and "draw dc text" levels of the method hierarchy. In addition, there is a provision for trapping the method "draw windows", which paints a window background and the method "draw window frame", which draws a frame around a window.
The next section presents in detail the set of methods that you can trap with HOOPS I.M. callbacks.

Callback Points

HOOPS I.M. provides the following set of callback points at which you can trap the traversal process. These are entry points to methods in the rendering pipeline for which you can define callbacks. Here they are listed in order of higher to lower levels (with respect to their level in the rendering pipeline), along with a brief description of the standard default behavior of the method.
draw segment
Called at the beginning of processing each segment for which it is in effect. As for all but the callback points, a "draw segment" callback is inherited by all the subsegments of the segment on which it is set.
draw segment tree
Like "draw segment", except that the callback is not inherited by subsegments of the segment on which it is set. This is the one exception to the rule that callbacks are inherited by subsegments. It is provided because it is frequently the case that a callback function can make a decision about the processing of the subsegment hierarchy below a given segment when the given segment is first encountered in the traversal and so does not need to be called back for every descendent segment.
draw window
Called to fill in the segment's window with the background pattern, subject to the current hard clip limits
draw window frame
Called to draw a frame around a segment's window.
draw 3d marker
draw 3d polyline
draw 3d polygon
draw 3d text
draw 3d tristrip
draw 3d polyedge
draw 3d polymarker

These callback points allow you to trap specifically the "draw 3d ..." methods for each of the geometry types: marker, polyline, polygon, text, tristrip, polyedge, and polymarker (HOOPS Isolines are trapped by setting a callback on HT_Polyedge). The first three of these essentially apply the transformations needed to map object coordinates to device coordinates, then call on the corresponding "draw dc ..." method. Text processing is somewhat more complex. See the discussion of "draw text" below for more information on the work of the "draw 3d text" method. The last 3 (tristrip, polyedge, and polymarker) are associated with HOOPS shells.
draw 3d geometry
This callback point allows you to trap the "draw 3d ..." method for all of the HOOPS 3D geometry types, including those for which there is no type-specific callback point (ellipses, circles, arcs, etc). If you set a callback both at "draw 3d geometry" and at one of the type-specific callback points "draw 3d marker", "draw 3d polyline", "draw 3d polygon", or "draw 3d text", then the latter prevails and your "draw 3d geometry" callback will not be called for geometry elements of that type.
draw text
This method is at an intermediate level of the text processing, below the level of "draw 3d text". Like "draw 3d text", the "draw text" method is called once for each inserted text string. The higher level passes to "draw text" an intermediate text information structure, which contains the results of certain computations that apply to the string as a whole.
The computations performed by the "draw 3d text" level include the effects on the text reference point of modelling transformation, camera, text font size, text spacing, extra space, text alignment, text path, text rotation, and text slant attributes. Finally, the intermediate text information structure will contain some intermediate results, which depend on the coordinate transformations and the text attributes, and which might be needed to apply the per-character transformations as required by the text font transformability attribute.
The work of the standard "draw text" method is to reconcile the text attributes called for by the application with the capabilities of the requested font, and to complete the computations needed to draw the text. In particular, the "draw text" method is responsible for applying the per character transformations when appropriate and for applying atmospheric attenuation (fog) to text when it is called for.
If the text is finally to be drawn in a font provided by the hardware, the window system, or the driver, then "draw text" eventually calls on a driver-level "draw dc text" method, which does not have an I.M callback point. Otherwise, "draw text" causes the text to be stroked out, using the ordinary geometry drawing provisions, through "draw 3d text strokes" and "draw 3d text areas" when per-character transformations are in effect, or directly through "draw dc text stroke" and "draw dc text area" otherwise.
draw 3d text area
draw 3d text stroke

These are effectively entry points to the "draw 3d polygon" and "draw 3d polyline" methods respectively, when the latter are called from the "draw text" level in the process of drawing characters of transformable stroked text, both the built-in stroked fonts and the user defined fonts.
draw dc marker
draw dc polyline
draw dc line
draw dc edge
draw dc face
draw dc triangle

These are used to draw the respective objects, specified in device coordinates, subject to the relevant attribute values in the net rendition. Device coordinates are 3D floating-point coordinates. The x and y device coordinates are in pixel units, with origin at the lower left. When the graphics platform has a windowing system, the xy origin of the device coordinates may be at the lower left of the screen or at the lower left of the outer window, which is the window-system window that contains the HOOPS picture. The device driver determines which origin is used. In any case, at traversaltime, you can determine the location of the device coordinate origin with respect to your HOOPS window by calling HIC_Show_Window_Extent . The device z coordinate is relevant only when Z-buffering is in effect.
The standard method for "draw dc edge" is exactly the same as "draw dc polyline", except that it uses the edge attributes in the net rendition rather than the line attributes. "draw dc line" is a special case of "draw dc polyline", specialized to the two-vertex polyline (line segment). It is called only from "draw dc colorized line", after the latter has changed the line color attribute according to its argument.
Note on cutting planes:
When cutting planes are present, some callbacks such as "draw dc face" will not be called. When cutting planes are involved, faces are triangulated, and they need a "draw dc triangle" callback instead.
draw dc colorized marker
draw dc colorized line
draw dc colorized face
draw dc colorized triangle

These are used to draw the respective objects with an RGB color passed as an argument to the method, rather than with the color specified by the rendition. These are called typically in the processing of geometry elements of a constant color, when the color has been computed by HOOPS, as in the case of lighting or fog. Each of the standard "draw dc colorized ..." methods changes the relevant color attributes in the rendition and then calls on the corresponding "draw dc ..." method.
draw dc cut line
The software path for drawing cut lines from cutting planes adds a lot of overhead, resulting in poor performance. To offset this, a "draw dc cut line" callback has been added. Using this, a program can "compute" the cutting lines by drawing the scene with them visible, storing the cut lines, turning the visibility of cut lines back off (restoring the fast path drawing), and inserting the stored lines as real geometry.
draw dc gouraud line
draw dc gouraud triangle

These are used to draw the respective objects with color interpolated from vertex colors passed as arguments.
driver startup
driver shutdown
These are called when the HOOPS driver instances are created and destroyed. As callback points they provide hooks in case the application needs to do something special. However, these points DO NOT CORRESPOND to any existing HIC functions. Therefore developers must make sure that their callback functions return, so that HOOPS can continue startup or shutdown normally.
finish picture
This is called when the HOOPS driver finishes drawing to a device. Can be used to access device-specific data using device-native functions. An example would be a frame buffer grab from OpenGL using glReadPixels.
hlr polyline
hlr marker
hlr hidden polyline
hlr hidden marker

These callback points will be executed when hidden line is the active hidden surface removal algorithm. In this case the visible lines and markers will be accessible through the 'hlr polyline' and 'hlr marker' callbacks, while the hidden geometry can be accessed through the 'hlr hidden polyline' and 'hlr hidden marker' callbacks.
select segment
select segment tree
select window
select text
select 3d geometry
select 3d marker
select 3d polyline
select 3d polygon
select 3d text

These are called for processing the respective database elements in the course of a selection traversal. Setting a callback for "select geometry" causes the callback function to be called for all the other geometry elements for which a specific "select ..." callback has not been set.
"select segment tree" behaves for selection just as "draw segment tree" does for drawing, that is, it is only called on the segment that specifies it, not inherited and called on every subsegment the way "select segment" (and "draw segment") are.
Selection traversal is initiated by a Get_Selection , Show_Selection, or Compute_Selection call. Given the locator screen coordinates for a selection event (or in the arguments of a Compute_Selection call), the system traverses the database and performs essentially the same computations as when updating the display, but draws nothing on the screen. Rather, the screen locations covered by each selectable geometry item are tested against the specified locator coordinates for hits. Hit criteria include proximity, area intersection, or volume intersection.
During selection traversal the system keeps a list of selected elements, i.e. those encountered elements that are selectable according to the selectability attribute, and which are hit according to the hit criteria. The list of selected elements is ordered by proximity and by z coordinate. Its length is limited by the "related selection limit" heuristic. At the end of the selection traversal, the application can examine the selected elements with the various Show_Selection_... functions and Find_Related_Selection.
The following diagram indicates the hierarchy of drawing methods.

Setting Callbacks

To trap (or override) one of the methods, you set callbacks using the classic HOOPS function HC_Set_Callback . When you have set a callback on one of the callback points from the method list given above, then whenever the update cycle calls that method, control will be transferred to the callback function that you provide and specify in the HC_Set_Callback call. Callbacks are treated much like other attributes. You set a callback on a particular segment, and it is inherited by the descendants of that segment in the segment tree (except for "draw segment tree" callbacks, as mentioned above). Before setting a callback, you must register your callback function with HOOPS by calling HC_Define_Callback_Name .
In more detail,

HC_Define_Callback_Name (name, function)

name

 

string

 

The name by which you will identify your callback function to HC_Set_Callback . Passed by reference.

function

 

pointer

 

Pointer to your callback function.

This function identifies and registers your callback function with the system. The next function is what you use to set the callback at a defined callback point.
HC_Set_Callback (callbacks)

callbacks

 

string

 

List of callbacks.

The list of callbacks is a comma-separated list of expressions of the form "callback point = name", where "callback point" is one of the callback points listed in the preceding section, and "name" is the name you used in registering the callback function with HC_Define_Callback_Name . This function sets the specified callbacks in the attribute information for the currently open segment. For each of the callback points whose name is a plural form, e.g. "draw 3d polyline", the singular form, e.g. "draw 3d polyline", is equally acceptable for "callback point".
When the system calls one of your callback functions, it passes a list of arguments, which is the argument list for the respective method, and which depends on the callback point. The next section indicates the argument list for each callback point, and you can find complete declarations of the argument types in the reference section for the corresponding standard methods.

HOOPS I.M. Functions

HOOPS I.M. provides a library of functions that you can call from your callback functions to access the services of the HOOPS system. Presently, these functions are available only from callback functions written in C or C++. Their names all begin with HIC_ . You should refrain from calling most of the functions of classic HOOPS from your HOOPS I.M. callback functions. There are some exceptions; in particular, it is generally all right to call the classic Compute_... functions. But calling classic HOOPS functions that alter or query the database can have unpredictable results.
For each callback point, there is a HOOPS I.M. function HIC_... that you can call to pass control back to the standard default method for that callback point. The argument list of the callback is indicated with the HIC_... function. You can find the declarations of the argument types on the reference pages for the HIC_ ... functions. Here is the correspondence between callback points and the standard default functions.
draw segment
 
HIC_Draw_Segment (nr, seg_info)
draw segment tree
 
HIC_Draw_Segment (nr, seg_info)
 
 
 
draw 3d marker
 
HIC_Draw_3D_Marker (nr, marker)
draw 3d polyline
 
HIC_Draw_3D_Polyline (nr, polyline)
draw 3d polygon
 
HIC_Draw_3D_Polygon (nr, polygon)
draw 3d text
 
HIC_Draw_3D_Text (nr, text)
draw 3d geometry
 
HIC_Draw_3D_Geometry (nr, geometry)
draw 3d text stroke
 
HIC_Draw_3D_Polyline (nr, polyline)
draw 3d text area
 
HIC_Draw_3D_Polygon (nr, polygon)
 
 
 
draw 3d polyedge
 
HIC_Draw_3D_Polyedge (nr, polyedge)
draw 3d polymarker
 
HIC_Draw_3D_Polymarker (nr, polymarker)
draw 3d tristrip
 
HIC_Draw_3D_Tristrip (nr, tristrip)
 
 
 
draw text
 
HIC_Draw_Text (nr, text_info)
 
 
 
draw dc marker
 
HIC_Draw_DC_Marker (nr, point)
draw dc polyline
 
HIC_Draw_DC_Polyline (nr, count, points)
draw dc edge
 
HIC_Draw_DC_Polyline (nr, count, point)
draw dc face
 
HIC_Draw_DC_Face (nr, count, points)
draw dc colorized face
 
HIC_Draw_DC_Colorized_Face (nr, count, points, color)
draw dc colorized marker
 
HIC_Draw_DC_Colorized_Marker (nr, point, color)
draw dc line
 
HIC_Draw_DC_Line (nr, points)
draw dc colorized line
 
HIC_Draw_DC_Colorized_Line (nr, points, color)
draw dc gouraud line
 
HIC_Draw_DC_Gouraud_Line (nr, points, colors)
draw dc triangle
 
HIC_Draw_DC_Triangle (nr, points)
draw dc colorized triangle
 
HIC_Draw_DC_Colorized_Triangle (nr, points, color)
draw dc gouraud triangle
 
HIC_Draw_DC_Gouraud_Triangle (nr, points, colors)
draw dc text stroke
 
HIC_Draw_DC_Polyline (nr, count, points)
draw dc text area
 
HIC_Draw_DC_Face ( nr, count, points)
draw window
 
HIC_Draw_Window (nr, extent)
draw window frame
 
HIC_Draw_Window_Frame (nr, extent frame, calc)
 
 
 
driver startup
driver shutdown
 
No corresponding HIC functions. User callback MUST return for normal startup and shutdown to continue.
 
 
 
finish picture
 
HIC_Finish_Picture (nr, swap_buffers)
 
 
 
hlr polyline 
 
HIC_Draw_DC_Polyline(nr, count, points)  
hlr marker 
 
HIC_Draw_DC_Marker(nr, point)  
hlr hidden polyline 
 
HIC_Draw_DC_Polyline(nr, count, points)  
hlr hidden marker 
 
HIC_Draw_DC_Marker(nr, point)  
 
 
 
select 3d marker
 
HIC_Select_Geometry (nr, marker)
select 3d polyline
 
HIC_Select_Geometry (nr, polyline )
select 3d polygon
 
HIC_Select_Geometry (nr, polygon)
select text
select 3d text
 
HIC_Select_Geometry (nr, text)
select 3d geometry
 
HIC_Select_Geometry (nr, geometry)
select window
 
HIC_Select_Window (nr, wind_info)
select segment
select segment tree
 
HIC_Select_Segment (nr, seg_info)

 

Data Types

The HOOPS I.M. programmer will encounter several new data types beyond those used in classic HOOPS argument lists.
HT_Marker, HT_Point, HT_Polygon, HT_Polyline, and HT_Text are structures each 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.
HT_Geometry is 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.
HT_Segment_Info is 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.
HT_Window_Info, is a complex type describing a window. In HOOPS I.M. it occurs only as an argument to the "select windows" callback.
HT_Rendition is 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.
HT_Text_Info is 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.
Common types include the following:
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.
Two different rectangle types occur in the HOOPS I.M. functions,
typedef struct int_rectangle {
int left, right, bottom, top;
} HT_Int_Rectangle;

and
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.
The I.M. programmer will encounter two different color types. First
typedef struct rgb {
float red, green, blue;
} HT_RGB;

is most commonly used for specifying a color as three floats for the RGB components. In the HT_RGB type, the components are generally all between 0 and 1.
Internally, HOOPS also uses a four-byte color type, HT_RGB32. The ordering of the components, however, depends on the CPU, specifically on its byte-ordering convention ("endian-ness"). The effective declaration of this type is either
typdedef union rgb32 {
Integer32 whole_thing;
struct{
unsigned char a, r, g, b;
} HT_RGB32

or
typdedef union rgb32 {
Integer32 whole_thing;
struct{
unsigned char a, r, g, b;
} rgb;
} HT_RGB32

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.