Brief Index      Full Index      Events Index      I.M. Reference

Show_Geometry_Pointer


Functions

void Show_Geometry_Pointer (HC_KEY key, const char *data_type, void *value)

Function Documentation

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.

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

DETAILS

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.

  • mapped 16 rasters
    The returned pointer is to the raster array of an image. It is an array of shorts which index into a color map. Please note that the format of the referenced image must be be "mapped 16" otherwise the function will return NULL.

NOTES

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.

RESTRICTIONS

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.

See also:
Insert_Shell_By_Ref, Insert_Mesh_By_Ref, Insert_Image

Brief Index      Full Index      Events Index      I.M. Reference