Creating and Rendering Parasolid Entities

Rendering Parasolid entities requires a sequence of steps, most of which are encapsulated by the HOOPS/Parasolid Integration functions.

  1. First, a ‘Frustum’, which includes a set of Graphical Output (GO) routines, must be implemented and registered with Parasolid.

  2. Second, the tessellated geometric data intercepted by the GO routines must be stored and displayed to various devices (rendered).

  3. Once these are accomplished, the Parasolid render routines (PK_TOPOL_render_xxx) must be called in order that the geometry associated with each Parasolid object can be rendered via the frustum.

The HOOPS/Parasolid Integration fully encapsulates the first two items. Additionally, when a Parasolid file is read via the HP_Read_Xmt_File() function, all the necessary PK_TOPOL_render_xxx calls are made automatically as each Parasolid part/entity is parsed. However, the HP_Render_Entity routine needs to be manually called when Parasolid entities are being dynamically created and edited via the application’s user-interface and underlying logic.

As an example, we will go through the process for inserting a cylinder object into Parasolid, and passing the tessellated information to HOOPS for subsequent rendering and interaction. This and future sections assume familiarity with the types of Parasolid entities, denoted by the Parasolid type PK_CLASS_t.

Defining Parasolid Geometry

A cylinder, along with many other predefined Parasolid objects, is represented by a PK_BODY entity, and is created via the routine:

<error_code> = PK_BODY_create_solid_cyl(<radius>, <height>, <cyl_basis_set>, <cyl_body>);

Parasolid entities are referred to by a ‘TagID’, so this function populates the Parasolid kernel with a cylinder of the specified radius and basis_set, and returns the TagID of the associated Parasolid body. However, the cylinder will not actually be rendered (mapped to corresponding HOOPS segments and geometry) until a call is made to the HP_Rendering_Entity() routine, discussed in the next section.

The following code demonstrates how to create a Parasolid cylinder. Note that it calls HP_Render_Entity():

// create a parasolid cylinder and return the cylinder's body id

PK_BODY_t HOpCreateSolidCylinder::CreateSolidCylinder(HPoint &center, HVector radius_vector, HVector height_vector)
{

        PK_ERROR_code_t error_code;
        PK_AXIS2_sf_t cyl_basis_set;
        PK_BODY_t cyl_body;
        float radius, height;
        double view[3], up[3];
        HPoint add, subtract;

        HUtility::GetViewplaneVectors(m_pView->GetSceneKey(), view, up);
        radius = (float) HC_Compute_Vector_Length(&radius_vector);
        height = (float) HC_Compute_Vector_Length(&height_vector);

        // to determine orientation add and subtract the view plane up
        // vector and the cylinder up vector. By measuring the size of
        // each vector we can determine the direction of the cylinder

        add.Set(height_vector.x + (float) up[0],
                                height_vector.y + (float) up[1],
                                height_vector.z + (float) up[2]);

        subtract.Set(height_vector.x - (float) up[0],
                                        height_vector.y - (float) up[1],
                                        height_vector.z - (float) up[2]);

        cyl_basis_set.location.coord[0] = (double) center.x;
        cyl_basis_set.location.coord[1] = (double) center.y;
        cyl_basis_set.location.coord[2] = (double) center.z;

        if (HC_Compute_Vector_Length(&add) > HC_Compute_Vector_Length(&subtract))
        {
                cyl_basis_set.axis.coord[0] = up[0];
                cyl_basis_set.axis.coord[1] = up[1];
                cyl_basis_set.axis.coord[2] = up[2];
        }
        else
        {
                cyl_basis_set.axis.coord[0] = -up[0];
                cyl_basis_set.axis.coord[1] = -up[1];
                cyl_basis_set.axis.coord[2] = -up[2];
        }

        cyl_basis_set.ref_direction.coord[0] = view[0];
        cyl_basis_set.ref_direction.coord[1] = view[1];
        cyl_basis_set.ref_direction.coord[2] = view[2];

        HSolidModel * model = (HSolidModel*)(m_pView->GetModel());
        PK_PARTITION_set_current(model->GetPartition());

        error_code = PK_BODY_create_solid_cyl(radius, height, &cyl_basis_set,&cyl_body);

        if ( report_ifail(error_code,0) != 0)
        {
                char error_message[256];
                sprintf(error_message, "failed rendering cylinder\n Error Code %d", error_code);
                MessageBox(NULL, error_message, 0, MB_OK);
                return 0;
        }

        // now put it in the HOOPS database
        HP_Render_Entity(cyl_body)
        return cyl_body;
}

Rendering Parasolid Geometry

After a Parasolid entity is defined and inserted into the Parasolid database, the tessellated geometric information that represents the entity must be generated. PK_BODY entities (along with many others) are composed of PK_FACE and PK_EDGE entities. These entities denote the logical surface and edge/boundary information associated with the body. Specifically, a cylinder body object is composed of three PK_FACE entities, one for the top, one for the bottom, and one for the ‘tubular’ part of the cylinder. It is composed of two PK_EDGE entities, one for a circle denoting the top edge, and one for a circle denoting the bottom edge. The tessellated geometric information associated with the PK_FACE and PK_EDGE entities would typically need to be generated by manually calling the following Parasolid routines:

<error_code> = PK_TOPOL_render_facet(<number_of_bodies>, <bodies>, <topol_transfs>, <view_transf>, <rendering_options>);

<error_code> = PK_TOPOL_render_line(<number_of_bodies>, <bodies>, <topol_transfs>, <view_transf>, <line_options>);

In addition to tessellating the body into facets and lines, these functions will send the tessellated information to the graphical output routines.

The HOOPS/Parasolid Integration includes a function which automatically makes the above PK_TOPOL_render_facet calls, and because the HOOPS/Parasolid Integration implements the underlying GO routines, the geometric data that represents the cylinder is automatically mapped to a group of geometric primitives in the HOOPS database. By default, these primitives are inserted in the currently open HOOPS segmen. The HP_Set_Rendering_Options function discussed later in this document, provides for control of this behavior, including creation of subsegments and optimization of the geometry.

To render Parasolid entities and have their tessellated representation automatically mapped to HOOPS graphical primitives, you may simply call:

HP_Render_Entities (count, entities);

where ‘count’ is the number of entities, and ‘entities’ is the array of Parasolid entities (of type PK_Entity_t). This function also updates the bi-directional mapping (which uses a hash table) maintained by the HOOPS/Parasolid integration.<br>

Inserting Parasolid Geometry Into the HOOPS Database

Recall that the HOOPS geometry and any additional segments generated as a result of the HP_Render_Entity and HP_Render_Entities routines will be placed in the currently open HOOPS segment. The following code ties together the code necessary to insert a cylinder object into both Parasolid and HOOPS. It assumes that we have obtained the creation parameters for a cylinder from the UI, opens a segment and then calls the CreateSolidCylinder function discussed previously. After CreateSolidCylinder is called (which calls HP_Render_Entity, discussed above), the Parasolid database will contain a parametric representation of the cylinder (a Parasolid ‘body’), and the HOOPS database will contain the corresponding geometric representation (a HOOPS ‘shell’):

// open up a HOOPS segment which will contain the cylinder geometry
HC_Open_Segment_By_Key(GetView()->GetModel()->GetModelKey());

        // put each entity in a separate segment so that we can easily apply
        // transformations to separately created entities
        HC_Open_Segment("");
        PK_BODY_t cyl_tag;
        cyl_tag = CreateSolidCylinder(m_ptFirst, m_world_radius_vector,height_vector);
        HC_Close_Segment();

HC_Close_Segment();

The Parasolid ‘body’ entity that represents the cylinder is accessible via the cyl_tag TagID. Details on how to identify the HOOPS geometric primitives associated with the Parasolid entity are covered later in this document, in the section entitled ‘Operating on Parasolid Entities’.

Deleting Parasolid and HOOPS Geometry

We will recall that the HOOPS/Parasolid Integration maintains a mapping between Parasolid entities and HOOPS Geometry, which enables the developer to determine the Parasolid entities associated with a given HOOPS geometric primitive or segment, and vice versa. The HP_Render_Entities function causes this mapping to be created/updated each time it is called to populate the HOOPS database with the tessellated representation of Parasolid entities.

As a result, another HOOPS/Parasolid function must be called when deleting HOOPS geometry associated with Parasolid entities to ensure that the internal mapping is kept up to date. The function is called HP_Delete_Entity_Geometry, and would be used to delete the HOOPS geometry associated with a Parasolid entity after the latter is deleted. For example, the following function is a wrapper function which deletes a Parasolid entity along with its associated HOOPS geometry:

void HSolidModel::DeleteParasolidEntity( PK_ENTITY_t entity)
{
        HP_Delete_Entity_Geometry(1, &entity);

        PK_ENTITY_delete(1, &entity);
}

It is important to use the HP_Delete_Entity_Geometry function whenever deleting HOOPS geometric primitives associated with deleted Parasolid entities. If only the normal HOOPS/3DGS deletion functions were called (HC_Delete_By_Key, etc…), then the HOOPS/Parasolid mapping would not be correct, and problems would occur during subsequent operations.

Retesselation of Geometry Into the Same Segment Structure

A call to HP_Delete_Entity_Geometry() normally deletes all associated entities from HOOPS including segments. Sometimes however it is desirable to preserve the segment structure if e.g. extra information with no connection to the solid modeller has been previously associated to a body. To allow that there is a third parameter in the call to HP_Delete_Entity_Geometry() called PreserveSegments. If this Boolean is set to true``(it defaults to ``false) then only true HOOPS geometry is deleted and keys that are associated with segments are disregarded. This means that if a body is deleted it will be retesselated into the same segment again on the next call to HP_Render_Entity().

However, let’s consider the following scenario. Say we have a simple cylinder body which contains (among other things) two edges. After normal tesselation we want to move one of the edges (consisting of two HOOPS ellipses) into a separate segment (let’s call it “special”) which contains e.g. some text annotation and a different line weight attribute. We can do this with HC_Move_By_Key(). Unfortunately, after a retesselation (even when using HP_Delete_Entity_Geometry with PreserveSegments = true) the two HOOPS ellipses are recreated in their default segment again and the newly created “special” segment is empty.<br>

To avoid this, HP_Associate_Entity_To_Key() can be used which associates a HOOPS keys to a Parasolid entity. In our example we use it to associate the key of the “special” segment to the Parasolid edge entity that we want to store underneath it. Whenever the Parasolid body needs to be rerendered we delete it’s associated geometry by using HP_Delete_Entity_Geometry with the PreserveSegment flag set to true. This way even though all the HOOPS geometry of the body is deleted there is still the connection to the “special” segment in the database.

Here is some example code:

// first we render the object let's assume it is a cylinder) normally
HC_Open_Segment_By_Key(((HBaseModel*)my_view->GetModel())->GetModelKey());
HP_Render_Entities(1, &body);


// this code simply queries all edges of the cylinder and moves the
// first edge into a segment called special which contains a new line
// weight attribute setting

long list[10000];
int count;
int num_edges;

PK_EDGE_t *edges;

PK_BODY_ask_edges(body,&num_edges, &edges);
count = HP_Compute_Geometry_Keys(edges[0], 10000, list, "edges");

long key = HC_KOpen_Segment("special");
for(int i = 0; i < count; i++)
{
        HC_Move_By_Key(list[i],".");
        HC_Set_Line_Weight(8.0);
}

HC_Close_Segment();

//we are associating the edge entity to the key of the segment where
//it's geometry now resides in
HP_Associate_Key_To_Entity(edges[0],key);

// ...

// assuming the body has changed (e.g. it was the target of a boolean
// operation) we are first deleting all the bodies that are completely
// gone normally
HP_Delete_Entity_Geometry(number_of_tools, tools);

// the target body (let's assume it's the one that we have created
// above) survives the operation so we delete it's geometry but
// preserve it's segment structure
HP_Delete_Entity_Geometry(1, &target,true);

// ... (some boolean operation applied)

// the body is now rerendered in the same segment as it was sitting in
// before and (important!) the edge that we have put into the "special"
// segment is again in the special segment in it's new form (it might
// be partly cut due to the boolean)
HP_Render_Entities(1, &target);

View-Dependent Tesselation

HP_Render_Entity() and HP_Render_Entities() have a third parameter which is a Parasolid transformation entity (0 by default) that represents the view matrix for view dependent tessellation. It is the responsibility of the caller to set the appropriate tessellation options for the frustum routines. This example demonstrates how to temporarily overwrite tesselation options to render the body in a view dependent way:

// create the PS transform from a supplied matrix
PK_TRANSF_t view_transf;
PK_TRANSF_create(&rot_m,&view_transf);

// temporarily set tesselation options
// for silhouette+hidden line output
PK_TOPOL_render_line_o_t g_lineOptions,g_lineOptionsSav;
HP_Show_Tessellation_Options(&g_lineOptions, NULL, NULL);
HP_Show_Tessellation_Options(&g_lineOptionsSav, NULL, NULL);

g_lineOptions.edge = PK_render_edge_yes_c;
g_lineOptions.silhouette = PK_render_silhouette_yes_c;
g_lineOptions.visibility = PK_render_vis_hid_c;

HP_Set_Tessellation_Options(&g_lineOptions, NULL,NULL);

// rerender the bodies with the supplied view transformation
HC_Open_Segment_By_Key(GetModel()->GetModelKey());
HSolidModel * model = (HSolidModel *)(GetModel());
PK_PARTITION_set_current(model->GetPartition());
HP_Render_Entities(numbodies, bodies, view_transf);

HC_Close_Segment();

// restore old tessellation settings
HP_Set_Tessellation_Options(&g_lineOptionsSav, NULL, NULL);