Insert_Shell

Functions

HC_KEY DInsert_Shell (int pcount, const HCD_POINT *points, int flist_length, const int *face_list)
 Similar to Insert_Shell() but accepts double-precision values for points. More...
 
HC_KEY DInsert_Shell_By_Ref (int pcount, const HC_DPOINT *points, int flist_length, const int *face_list)
 Similar to Insert_Shell_By_Ref(), but operates on double-precision data. More...
 
HC_KEY Insert_Shell (int pcount, const HC_POINT *points, int flist_length, const int *face_list)
 Generates an object that is an arbitrarily-connected collection of arbitrary polygonal facets. More...
 

Detailed Description

Function Documentation

◆ DInsert_Shell()

HC_KEY DInsert_Shell ( int  pcount,
const HCD_POINT *  points,
int  flist_length,
const int *  face_list 
)

Similar to Insert_Shell() but accepts double-precision values for points.

Parameters
pcount- Number of valid points in points.
points- Vector of x-y-z triplets for the coordinates of the vertices to be used to build the shell. (A simple N x 3 array may also be used.) Passed by reference always.
flist_length- Total number of integers in face_list.
face_list- Encoded description of how to connect the points to build the faces of the shell (see below).
Returns
The key to the inserted geometry.

DETAILS

No additional details. See Insert_Shell().

◆ DInsert_Shell_By_Ref()

HC_KEY DInsert_Shell_By_Ref ( int  pcount,
const HC_DPOINT *  points,
int  flist_length,
const int *  face_list 
)

Similar to Insert_Shell_By_Ref(), but operates on double-precision data.

Parameters
pcount- Number of valid points in points.
points- Vector of x-y-z triplets for the coordinates of the vertices to be used to build the shell. (A simple N x 3 array may also be used.) Passed by reference always.
flist_length- Total number of integers in face_list.
face_list- Encoded description of how to connect the points to build the faces of the shell (see below).
Returns
The key to the inserted geometry.

◆ Insert_Shell()

HC_KEY Insert_Shell ( int  pcount,
const HC_POINT *  points,
int  flist_length,
const int *  face_list 
)

Generates an object that is an arbitrarily-connected collection of arbitrary polygonal facets.

Parameters
pcount- Number of valid points in points.
points- Vector of x-y-z triplets for the coordinates of the vertices to be used to build the shell. (A simple N x 3 array may also be used.) Passed by reference always.
flist_length- Total number of integers in face_list.
face_list- Encoded description of how to connect the points to build the faces of the shell (see below).
Returns
The key to the inserted geometry, or -1 if an error occurred.

DETAILS

A shell is an collection of triangles. Shells have the following interesting abilities in comparison with polygon primitives:


  • The shell will require less database memory—the x-y-z data for the vertices that are shared by more than one face do not have to be repeated.
  • The shell will probably be drawn more quickly—there is less x-y-z data that has to be transformed to screen coordinates. If the shell is a closed polyhedron, backplane culling (see Set_Heuristics() ) becomes easy to perform and will also speed up drawing.
  • The shell can be smooth-shaded—the shell gives the system enough information to automatically compute the necessary vertex normals.


The face_list is an array of integers. The first integer is the number of vertices that should be connected to form the first face. For example, '3' for a triangle. The next three integers (in this example) are the offsets into the points array at which the three x-y-z's can be found. The first point in the points array is considered to be at offset zero, so (0, 1, 2) in the face_list array would form the triangle from the first three entries in points.

Continuing with the example, a second triangle might be specified as (3, 0, 1, 3), meaning 'form a face using three vertices. The vertices are at offsets zero, one, and three in the points array'. So this second face happens to share an edge—the (0, 1) edge—with the first face. A third face might be (4, 1, 2, 11, 12), forming a quadrilateral. Faces continue being formed until an flist_length number of integers in face_list have been processed.

One special case: if a vertex count in the list is negative, that means 'continue with the previous face and subtract a polygon formed from the following vertices'. This allows you to build faces with true holes in them. You may make any number of holes in a face. You may also nest holes in one another. Nested holes get an 'even-odd' rule applied. A region is part of the face (drawn) if there are an odd number of edges between it and infinity in the plane of the face. Otherwise a region is considered exterior and is not drawn. For example, a line drawn from the interior of a single hole in a shell face outward toward infinity in the plane of the face will cross two edges (the edge of the hole, then the edge of the containing face.) Two is even, thus the region is considered exterior and will not be drawn. A hole nested inside such a hole will be drawn because a line would cross three edges. The edges of the hole receive the usual edge attributes. For face-numbering purposes (for example, Edit_Shell_Faces() ) the hole is not counted separately—it's a part of the face it's in. Holes in shell faces should have their winding reversed (normals pointing in) and as holes nest deeper the winding must alternate.

The attributes that apply to polygons, polygon edges, and polygon faces also apply to the faces and edges of a shell. Specifically, the depiction of the interior of each face can be adjusted with face color and face pattern. The edges of each can be made distinct from the interiors through the use of edge color and edge pattern. The general drawing style is controlled with the rendering options. Visibility and selectability control whether the edges and faces or both, are included during drawing or mouse selection.

Individual faces and edges can have their attributes locally overridden by doing an Open_Face() or an Open_Edge() (or an Open_Vertex() for face color in the area of the vertex) and then setting the attribute.

The _By_Ref() (by reference) routines differ from the regular routines only in that HOOPS Visualize can choose not to make a copy of your data (at the system's option). Instead HOOPS remembers where your shell data was located. Then whenever the shell needs to be re-computed the data originally passed in points and face_list is used, not an internal copy. This can speed up the call to Insert_Shell() and save significant memory. But be careful—when you insert by reference you are guaranteeing that the data is going to remain valid. Also, you're guaranteeing you're not going to touch the data (except via Edit_Shell_Faces() and Edit_Shell_Points() ) until such time as the whole shell database entry gets deleted. Also, the system makes a copy of the data anyhow if it needs to, so you shouldn't assume that Edits will be observable back in the original arrays.

NOTES

It is not necessary to close each face explicitly by going back to the start point. If you do close a face, the close point will be discarded as the shell is stored in the database.

It is not necessary for the polygons to be connected to each other. It is not necessary for all the input points to be referenced in face_list.

It is permissible for shells to be degenerate—the number of points in a shell can be zero. The number of faces in a shell can be zero. The number of vertices in a face can be as few as two, one, or even zero. Points can be redundant. More than two faces can share the same edge. Edges can be of zero length.

In the present implementation there are no 'sharp' edges or vertices. In other words, smooth-shading, if turned on, always proceeds across shared edges and vertices, thus rounding off the edge or vertex. The only way to prevent this is by duplicating the edge or vertex so it is no longer actually shared between the faces.

The boundary of a face should not intersect itself.

If you work in 3-D, make sure the points in each face lie in the same plane. The system does not check for this—but displayed pictures might look strange.

If you work with a C compiler (and matching HOOPS library) with an int defined as only 16 bits, you may experience problems. Pcount and flist_length are defined as integers, so in this rare case would not be able to exceed 32767. One work-around is to use Edit_Shell_Faces() and Edit_Shell_Points() to grow an initially-small shell to a large size. But be warned that Open_Face() , Open_Edge() , Open_Vertex() , and Show_Selection_Element() also deal in integers and therefore won't work with an overgrown shell.

If the shell is closed (the viewing camera is not within the object), and if the transform-and-clip operation is done is software, HOOPS always performs a backplane cull (see Set_Heuristics() ) before drawing the shell.

RESTRICTIONS

HOOPS Visualize cannot handle self-intersecting polygons in shells and meshes. In addition, shells with holes are not handled correctly if a polygon edge and a hole are share the same vertex.

See also
Insert_Shell_By_Tristrips, Edit_Shell_Faces, Edit_Shell_Points, Insert_Mesh, Insert_Grid, Insert_Polygon, Insert_Polyline, Set_Rendering_Options, Set_Visibility, Set_Face_Pattern, Set_Edge_Pattern, Set_Edge_Weight, Set_Color, Open_Geometry, Open_Face, Open_Edge, Open_Vertex, Renumber_Key.