Overview of Update Cycle
Datatypes in HOOPS I.M.
Outline of what this section contains
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.
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:
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.
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. 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 markers, polylines, polygons, and text as well as the other geometry types for which there is no type-specific callback point for the "draw 3d ..." method. 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. The "draw 3d text" level will also have applied soft clipping, in that it will have removed from the text string those characters that lie entirely outside the visible window. 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.
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 gouraud line
draw dc gouraud triangle
These are used to draw the respective objects with color interpolated from vertex colors passed as arguments.
select segment
select window
select geometry
select marker
select polyline
select polygon
select 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.
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.
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. 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) select marker HIC_Select_Geometry (nr, marker) select polyline HIC_Select_Geometry (nr, polyline ) select polygon HIC_Select_Geometry (nr, polygon) select text HIC_Select_Geometry (nr, text) select geometry HIC_Select_Geometry (nr, geometry) select window HIC_Select_Window (nr, wind_info) select segment HIC_Select_Segment (nr, seg_info) ------------------------------------------------------------------------------
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 r, g, b, a; } rgb; } 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.
The remainder of this section contains the reference entries on the HOOPS I.M. functions, plus one classic HOOPS function, Define_System_Options ., which is needed to activate HOOPS I.M. functionality. The HOOPS I.M. functions are available only from C or C++ programs, and their names all begin with begin with HIC_. Following the convention of the rest of this manual, when classic HOOPS functions are mentioned, their names are given without prefix, but you should remember that they take the prefix HC_ when called from C and HF_ when called from Fortran.