Functions | |
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. More... | |
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. More... | |
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. More... | |
void | End_Contents_Search (void) |
Terminates the object search sequence and frees any involved memory. More... | |
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. |
Many user applications must manipulate the geometry in the database to perform some type of analysis. For example, if a program needs to calculate the areas of all polygons in a segment, it would need to know the coordinates of the points in each polygon. A contents search (specifically, Find_Contents()) can be used to retrieve the keys of all of the polygons, and then Show_Polygon() can be used to extract the points.
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:
The filter parameter specifies the types of objects that will be returned by later calls to Find_Contents() . The types are passed in a list of the form "type, type...", where each type is one of the following:
The plural "s" after each type is optional. The types can be in any combination of upper and lowercase. Leading and trailing blanks are not significant. A blank string is equivalent to "everything".
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", "user options"
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.
If an object satisfying the target specification is deleted while a segment search is in progress, it will not be returned by Find_Contents() . If a segment is renamed, the new name will be returned. If geometry is moved to a new segment, its key will be returned even if the new segment name no longer matches the original search specification. If an object is created after a call to Begin_Contents_Search() , it will not be returned in the current sequence of Find_Contents() calls.
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 End_Contents_Search | ( | void | ) |
Terminates the object search sequence and frees any involved memory.
No additional details. See Begin_Contents_Search()
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. |
No additional details. See Begin_Contents_Search()
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. |
No additional details. See Begin_Contents_Search()