Begin_Contents_Search

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 End_Contents_Search (void)
 Terminates the object search sequence and frees any involved memory. 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...
 
HC_BOOLEAN Find_Contents_Original_Key (char *type, HC_KEY *key)
 Retrieves the original object keys, one at a time. The function returns false when all objects have been returned. 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...
 

Detailed Description

Function Documentation

◆ Begin_Contents_Search()

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.

Parameters
segment- A string specifying the location(s) of the search.
filter- List of the types of objects you 're interested in.

DETAILS

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:

  • "." Searches the currently open segment.
  • ".." Searches the parent of the currently open segment.
  • "..." Searches the currently open segment and its child segments.
  • "...." Searches the currently open segment, its children, and any include segments below the current segment.
  • "?picture/model" Searches the segment "model".
  • "?picture/model/..." searches the segment named 'model' and all of its subsegments.
  • "?picture/model/...." Searches the segment named 'model', all of its children, and any include segments below 'model'.
  • "/.../model*" Searches all segments in the entire tree starting with 'model', but not their subsegments.

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:

  • Geometry that can be inserted such as "images, lights, lines, markers, meshes, polygons, polylines, shells, string cursors, text".
  • One of the attributes that can be set such as "color", "marker size", "color map", "streaming mode", etc. Attribute filters may be refined by adding sub-options to the string, such as "color=(lines)", "user options = cost" or "visibility=faces".
  • The word "geometry" matches all types of geometry.
  • The word "attributes" matches all attributes.
  • The word "style" matches style references.
  • The types "segment" and "include" match, respectively, child segments and "include references" to segments.
  • The word "subsegment" matches "segment" and "include".
  • The word "inked line" selects the "currently being inked in" polyline (if any).
  • The word "ordered" returns only geometry brought to the front by Bring_To_Front() . The items are returned in drawing order. Successively returned items are drawn on top of previously returned items when the scene is updated.
  • The word "everything", matches all types.
  • The word "self", matches the subsegments themselves in a recursive search. This differs from the "subsegment" keyword in that it returns the parent instead of the children.
  • Any of the above types with "no" in front of them. For example: "everything, no geometry, no windows, no color maps" selects all types except windows, color maps, and all types of geometry. If specifications overlap (as in "geometry, no lines"), the last specification wins.
  • The word "hardware resources" matches display lists, textures, and vertex arrays that exist on the video card's cache.
  • The word "follow references" means the search will dig through references as part of the search. Without it, you'd have to search for references explicitly, find what they're pointing at and do a new search there.

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 leader",
"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.

NOTES

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.

RESTRICTIONS

See also
Begin_Segment_Search, Show_Existence, Show_Key_Type, Show_Segment, Show_Owner, Show_Polyline, Show_Shell, Show_Marker.

◆ End_Contents_Search()

void End_Contents_Search ( void  )

Terminates the object search sequence and frees any involved memory.

DETAILS

No additional details. See Begin_Contents_Search()

◆ Find_Contents()

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.

Parameters
type- The type of object found by this call. Returned to user. Passed by reference always.
key- Unique numeric identifier for this object. For attribute types it will be the key of the segment owning the attribute. Returned to user. Passed by reference always.
Returns
The function returns false when all objects have been returned.

DETAILS

No additional details. See Begin_Contents_Search()

◆ Find_Contents_Original_Key()

HC_BOOLEAN Find_Contents_Original_Key ( char *  type,
HC_KEY *  key 
)

Retrieves the original object keys, one at a time. The function returns false when all objects have been returned.

Parameters
type- The type of object found by this call. Returned to user. Passed by reference always.
key- Unique numeric identifier for this object. For attribute types it will be the key of the segment owning the attribute. Returned to user. Passed by reference always.
Returns
The function returns false when all objects have been returned.

DETAILS

This function returns the original key value for the item, which is safe to use regardless of which segment is open because, unlike locally renumbered keys, it is unambiguous and not dependent on context.

For additional details, see Begin_Contents_Search()

◆ Show_Contents_Count()

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.

Parameters
count- The total number of objects returned by Find_Contents() . Returned to user. Passed by reference always.

DETAILS

No additional details. See Begin_Contents_Search()