Intermediate Mode Routines


What is HOOPS I.M.?

Why use HOOPS I.M.?

Overview of Update Cycle

Callback Points

Setting Callbacks

HOOPS I.M. Functions

Datatypes in HOOPS I.M.

Outline of what this section contains


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.

Back


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:

  • You may want the graphical representation of your data, i.e. the actual primitives and attribute values used, to depend on the viewing parameters or the screen transformation. In particular, if your model has a hierarchy of scale and the view is zoomed out sufficiently far, then you may want to skip the rendering of entire subtrees that would appear very small on the display.

  • You may want to define your own version of a HOOPS primitive. For example, you could implement a spline drawing algorithm through the HOOPS polyline primitive, using the polyline vertices as spline control points. In this case, you would intercept at one of the callback points in the polyline drawing pipeline, and substitute your own spline drawing routine for the HOOPS polyline drawing routine.

  • You may want to devise your own marker symbols or line styles, and stroke them out yourself at traversal-time. Further, you may want to make the rendering style dependent on actual screen size. For example, in a cartographic application you could store railway tracks as polylines in the database, but draw them, for certain map scales, as parallel lines with cross ties.

  • If your graphics database is voluminous, you may want to avoid spending the memory needed for HOOPS to duplicate in its database some of the same information already contained in your application's private data structures. Using HOOPS I.M. in an "immediate mode" style allows you to pass some of your primitives to HOOPS one at a time in I.M. callbacks, rather than storing them in HOOPS segments.

  • In a real-time application, you may want to be able to modify the picture being displayed according to input received during traversal.

    Back


    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.

    Back


    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. 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.

    Back

    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.

    Back


    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)      
                                                                                     
    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)                   
    ------------------------------------------------------------------------------
    
    Back

    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 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.

    Back


    In This Section

    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.

    Back