Functions | |
void | Show_Geometry_Pointer (HC_KEY key, const char *data_type, void *value) |
void Show_Geometry_Pointer | ( | HC_KEY | key, |
const char * | data_type, | ||
void * | value | ||
) |
Retrieves a pointer to the internal data structure of the object identified by key.
key | - Unique numeric identifier for an object in the database. |
data_type | - See below. |
value | - The pointer to the requested internal data structure. Returned to caller. Passed by reference always. |
Legal choices for data_type include the following:
face list
The returned pointer is an array of integers that describe the connectivity of a shell (applies to shells only). Format is as described in Insert_Shell). length is as returned by Show_Shell_Size. Shells that were inserted by tristrips require.
face planes
The returned pointer is an array of structures, a-b-c-d, in floating-point format. These are the plane equations for each of the planes in the shell or mesh. length is 4 * face count.
points
The returned pointer is an array of x-y-z triplets of floating-point values representing the vertices. length is as returned by Show_Shell_Size.
rgba rasters
The returned pointer is to the raster array of an image. It is an array of four floats representing an RGB value. Please note that the format of the referenced image must be be "RGB", "RGBA" or "ARGB" otherwise the function will return NULL.
mapped 8 rasters
The returned pointer is to the raster array of an image. It is an array of bytes which index into a color map. Please note that the format of the referenced image must be be "mapped 8" otherwise the function will return NULL.
Show_Geometry_Pointer references point data that is stored within the HOOPS database. This function is useful because it allows for access (read-only) without incurring the performance and memory resource costs of creating a new copy.
This function can be particularly useful in conjunction with Insert_Shell_By_Ref() or Insert_Mesh_By_Ref(), for it does not require the programmer to store and maintain surface data in non-HOOPS structures. Instead, the pointer returned by this function can be passed directly to Insert_Shell_By_Ref() to create a new shell that shares data.
If key is an image key, the raster data_type must be of the same type as that used initially to insert the image ( see Insert_Image() ). To determine the image type, simply make a call to Show_Image_Size().
If the object identified by key is ever deleted, the pointer returned in a previous call to Show_Geometry_Pointer() will point to garbage memory.
The data structures to which this function grants access are internal to HOOPS. As such, they are subject to change without notice.
If the object identified by key is a shell inserted by tristrips, the "face list" request will generally return null. Currently the only recourse for this is to use Show_Shell_By_Tristrips() to read the tristrip data into a separately allocated array. No "tristrips" request is currently implemented because the internal tristrips format is one of the data structures most frequently changed for performance tuning.