Porting Your Legacy HOOPS I.M. Code

In Release 17, HOOPS I.M. underwent a redesign. The new interface is type safe with opaque data structures. These new features have given the HOOPS development team more flexibility to increase the stability and performance of the intermediate mode environment.

The I.M. functions and their names have remained the same. However, the I.M. data structures have changed. As a consequence, many function signatures have changed as well. For example, prior to Release 17, it was legal to pass an array with three floats in place of passing the I.M. data structure HT_RGB when calling HIC_Set_Face_Color. Now, if you call HIC_Set_Face_Color, it accepts neither an array of three floats or HT_RGB. Instead, it expects a new data structure, HIC_RGB. HIC_RGB and HT_RGB are primarily the same. They both encapsulate color information. So, you can still pass an array of three floats but you must first explicitly cast the array to const HIC_RGB*. When porting your code, the new parameters for the I.M functions are primarily the same as their original counterparts in functionality with the main difference being that the name now has a HIC prefix instead of an HT prefix. For instance, HIC_RGB’s counterpart in Release 16 is HT_RGB. In most cases, to port your code, you simply need to explicitly cast your data into the new data type and use the keyword const.

Another important difference between the new data structures and their original counterparts is that Release 17 data structures are opaque. In prior releases, it was legal to directly access any members in an I.M. data structure. As of Release 17, to retrieve member information from a given I.M. data structure, you should use the provided Show function. For instance, to find the value of the blue component for the current face color, you can call HIC_Show_Face_Color_Blue and pass in a pointer to an instance of HIC_Rendition.

Let’s look at an example as how one of our sample programs is ported to the new I.M. interface. In lines.c, we set up a callback point at “draw dc polylines” with the function user_defined_lines. Below, we see the original function signature for user_defined_lines:

void user_defined_lines (
        HT_Rendition    *rendition,
        int                     count,
        HT_DC_Point             *points)
{...

In the sample snippet below is the ported function signature for user_defined_lines. As you can see, HT_Rendition is replaced with HIC_Rendition while HT_DC_Point is now HIC_DC_Point:

void user_defined_lines (
        HIC_Rendition   const *rendition,
        int                             count,
        HIC_DC_Point            const *points)
{...

In the user_defined_lines function, we determine how to render a line by looking at the user option set on the segment. When the user option is set to MEASURED_DASHES, the function sets the line color to the variable purple which is defined as an array of three floats. In the original function below, we call HIC_Set_Line_Color passing purple as an array of three floats even when the function is asking for an HT_RGB structure:

...
float purple[] = {1.0f, 0.0f, 1.0f};
...
void user_defined_lines (
        HT_Rendition    *rendition,
        int                     count,
        HT_DC_Point             *points)
{...
        case MEASURED_DASHES: {
                long            length;
                HT_Rendition    *new_rendition;

                length = (long)HIC_Show_User_Option_By_Index (rendition,
                                                          MY_DASH_SIZE_IN_PTS);

                new_rendition = HIC_New_Rendition (rendition);
                HIC_Set_Line_Weight (new_rendition, 5);

                /************************************
                Setting the line color to purple by
                passing an array of floats.
                *************************************/
                HIC_Set_Line_Color (new_rendition, purple);

                HIC_Draw_DC_Polyline (new_rendition, count, points);
                HIC_Free_Rendition (new_rendition);

....

In the ported code below, when HIC_Set_Line_Color is called, purple is still passed as the color parameter but it is cast explicitly to the HIC_RGB data structure and with the const keyword:

...
float purple[] = {1.0f, 0.0f, 1.0f};
...

void user_defined_lines (
        HIC_Rendition   const *rendition,
        int                             count,
        HIC_DC_Point            const *points)
{...

        case MEASURED_DASHES: {
                long            length;
                HIC_Rendition   const *new_rendition;

                length = (long)HIC_Show_User_Option_By_Index (rendition,
                                                          MY_DASH_SIZE_IN_PTS);

                new_rendition = HIC_New_Rendition (rendition);
                HIC_Set_Line_Weight (new_rendition, 5);

                /************************************
                Setting the line color to purple by
                passing an array of floats that has
                been cast to the correct data type.
                *************************************/
                HIC_Set_Line_Color (new_rendition, (const HIC_RGB*)purple);

                HIC_Draw_DC_Polyline (new_rendition, count, points);
                HIC_Free_Rendition (new_rendition);
        }   break;

...

Another important point to note is how user option information is obtained from an HIC_Rendition data structure. In prior releases, you could access data directly from the rendition structure or use the show function as seen in the code sample below:

// obtaining user option information from a show function
length = (long)HIC_Show_User_Option_By_Index (rendition, MY_LINE_PATTERN);

// obtaining user option information by accessing the internal data directly
length = (long)rendition->user_rendition->values[MY_LINE_PATTERN].value;

As of Release 17, data structures like HIC_Rendition are opaque. Thus, it is not possible to access any internal data directly. Instead, you must use a Show function like HIC_Show_User_Option_By_Index.