Functions | |
void | Begin_Contents_Search (const char *segment, const char *filter) |
void | Show_Contents_Count (int *count) |
HC_BOOLEAN | Find_Contents (char *type, HC_KEY *key) |
void | End_Contents_Search (void) |
void Begin_Contents_Search | ( | const char * | segment, | |
const char * | filter | |||
) |
These routines are used to "dump" the contents of a segment or certain types of geometry.
segment | - A string specifying the location(s) of the search. | |
filter | - List of the types of objects you 're interested in. |
In a contents search, Begin_Contents_Search() initiates and defines the search. Only the types specified in filter are used in the search (see below), and only the segment or geometry specified in segment are checked.
Show_Contents_Count() determines the number of entities returned. This is useful for determining the size of a data structure needed to store the incoming items.
Find_Contents() returns entities, one at a time, from the selected segment/geometry. Find_Contents returns a type (i.e. "window frame") and, if appropriate, a key. (Geometry, segments, includes, and styles have keys. Attributes do not have keys.) The return value is false when all items have been returned.
End_Contents_Search() terminates the search sequence.
As with the other search routines, Begin_Contents_Search() operations can be nested. This feature can be used, for example, to "walk the tree" as sub-segments are encountered. A call to End_Contents_Search() terminates the current search context (segment specification and filter) and reactivates the previously active context (if any).
The segment parameter can take a number of valid location specifications including aliases, wildcards, and paths, as explained in the HOOPS/3dGS programming guide section 1.2.6 "Segment-Name Syntax". The following examples are valid usages:
Additional types (meanings should be self-explanatory) accepted by this function are: "distant light", "local light", "spot light", "area light", "includer", "styler", "style", "color", "callback", "camera", "clip region", "handedness", "selectability", "visibility", "window", "window frame", "color map", "driver", "driver options", "edge pattern", "edge weight", "face pattern", "heuristics", "line pattern", "line weight", "marker size", "marker symbol", "metafile", "modelling matrix", "rendering options", "text alignment", "text font", "text path", "text spacing", "texture matrix", "user value", "window pattern", "texture definition", "local texture", "glyph definition", "line pattern definition", "line style definition", "condition", "streaming mode", "circle", "circular arc", "circular chord", "circular wedge", "cutting plane", "cutting section", "light", "ellipse", "elliptical arc", "grid", "line", "marker", "mesh", "image", "pixel array", "polyline", "polygon", "shell", "string cursor", "text", "nurbs curve", "nurbs surface", "cylinder", "polycylinder", "sphere", "include", "reference geometry",
The following code example sums the areas of all polygons in all segments that contain the word "plate". It assumes the existence of a user written function that returns the area of a polygon given its key.
sum = 0.0 Begin_Contents_Search ("/...*plate*", "polygons") while (Find_Contents (type, poly)) sum = sum + polygon_area(poly) End_Contents_Search ()
(The "type" variable in this example will always be given the value "polygon".)
The segment name passed to Begin_Contents_Search() can contain wildcards, a list of segments or both. In this case, subsequent calls to Find_Contents() do not distinguish which segment contains each object. Use Show_Owner_By_Key() to determine this. Also, when multiple segments are specified, the type "ordered" does not distinguish which objects in the segments will be drawn first.
The returned types are entirely lowercase and singular, for example: "line", "selectability", "polygon". Normally, you would look at the type and make other calls ( Show_Visibility() , Show_Polyline() , etc.) to get more details about the object whose key was returned.
Show_Contents_Count() is only valid between Begin_Contents_Search() and End_Contents_Search() . It will always return the total number of items not the remaining number of items.
The inked line returned from a streaming segment will contain only the portion added since the last "Set" command changed any attribute in that segment.
"When "hardware resources" are found by Begin_Contents_Search, Find_Contents always return -1. In other words, hardware resources have no keys associated with them. Shells and Meshes can be opened and have their "hardware resources" flushed, but all other types of geometry (e.g. lines, polylines polycylinders and images) must have their "hardware resources" flushed from either their owning segment or some segment above.
void Show_Contents_Count | ( | int * | count | ) |
Finds out how many objects will be returned. This is useful for determining the size of a data structure needed to store incoming items.
count | - The total number of objects returned by Find_Contents() . Returned to user. Passed by reference always. |
HC_BOOLEAN Find_Contents | ( | char * | type, | |
HC_KEY * | key | |||
) |
Retrieves the object keys, one at a time. The function returns false when all objects have been returned.
type | - The type of object found by this call. Returned to user. Passed by reference always. | |
key | - Unique numeric identifier for this object. Negative one for attribute types. Returned to user. Passed by reference always. |
void End_Contents_Search | ( | void | ) |
Terminates the object search sequence and frees any involved memory.