Show_Existence

Functions

int QShow_Existence (const char *segment, const char *filter)
 Similar to Show_Existence(), but operates on a given segment rather than the currently open one. More...
 
int QShow_Existence_Unicode (const char *segment, unsigned short const *filter)
 Similar to Show_Existence_Unicode(), but operates on a given segment rather than the currently open one. More...
 
int Show_Existence (const char *filter)
 A utility routine to determine how much of something exists within a segment, or if it exists at all. More...
 
int Show_Existence_By_Key (HC_KEY key, const char *filter)
 Similar to Show_Existence(), but operates on an object referenced by an HC_KEY. More...
 
int Show_Existence_Unicode (unsigned short const *filter)
 A utility routine used to determine whether one or more unicode user options exist within a segment. More...
 
int Show_Existence_Unicode_By_Key (HC_KEY key, unsigned short const *filter)
 Similar to Show_Existence_Unicode(), but operates on an object referenced by an HC_KEY. More...
 

Detailed Description

Function Documentation

◆ QShow_Existence()

int QShow_Existence ( const char *  segment,
const char *  filter 
)

Similar to Show_Existence(), but operates on a given segment rather than the currently open one.

Parameters
segment- Name of the segment(s) in which to search. Can include wildcards, multiple segments, etc.
filter- List of the types of objects to be queried.
Returns
count - Number of objects found that match the requested type.

DETAILS

The segment parameter can take a number of valid segment name 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:

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

◆ QShow_Existence_Unicode()

int QShow_Existence_Unicode ( const char *  segment,
unsigned short const *  filter 
)

Similar to Show_Existence_Unicode(), but operates on a given segment rather than the currently open one.

Parameters
segment- Name of the segment(s) in which to search. Can include wildcards, multiple segments, etc.
filter- List of the types of objects to query.
Returns
count - Number of objects found that match the requested type.

DETAILS

No additional details. See Show_Existence_Unicode()

◆ Show_Existence()

int Show_Existence ( const char *  filter)

A utility routine to determine how much of something exists within a segment, or if it exists at all.

Parameters
filter- List of the types of objects to query.
Returns
count - Number of objects found that match the requested type.

DETAILS

Show_Existence() takes a look at the types of entities named by filter that exist immediately within the segment(s) named, and returns a count of the total.

The Show_(Attribute) routines may complain if they are called on a segment that doesn't have the attribute set. Instead, Show_Existence can be quickly used to test for the attribute's existence. If a "1" is returned, the attribute is set on the segment, and the Show_(Attribute) call is safe.
If filter is equal to the special value "self", Show_Existence() tells whether there is any open segment, and is equivalent to the following:

    Begin_Segment_Search (segment)
    Show_Segment_Count (&count)
    End_Segment_Search () 

That is, it counts the number of segments, matching the specification string segment (which can contain wildcards) if any such segment exists.

If filter is anything else, Show_Existence() and QShow_Existence() are equivalent to the following:

    Begin_Contents_Search (segment, filter)
    Show_Contents_Count (&count)
    End_Contents_Search () 

That is, they count the number of such items within segment or within the currently-open segment. Count is then returned as the function value.

As in Begin_Contents_Search(), filter is of the form "type, type", where each type is one of the following:

  • Geometry that can be inserted, such as "cutting planes, images, lights, lines, markers, meshes, polygons, polylines, shells, string cursors, text, cylinders, nurbs curves, nurbs surfaces".
  • One of the attributes that can be set, such as "color", "marker size", "color map", "streaming mode", etc.
  • The word "attributes" matches all the attributes.
  • The word "everything" matches all the above.
  • The word "first match" returns with a count of "1" if any of the requested types are found.
  • The word "geometry" matches all the kinds of geometry.
  • The word "hardware resources" matches display lists, vertex arrays, and textures that exist in the video card's cache.
  • The word "inked line" selects the "currently being inked in" polyline (if any).
  • The word "interesting" matches those items where the interesting bit has been set via Control_Update().
  • The word "ordered" returns only geometry that has been brought to the front by Bring_To_Front() . The items are returned in drawing order, with successively returned items being the ones drawn on top of previously returned items when the scene is updated.
  • The word "style" matches style references.
  • The types "segment" and "include" match, respectively, child segments and segments that have been included.
  • The word "subsegment" matches "segment" and "include".
  • The word "user options" matches any user options or user indices that have been set (alternatively, "user indices" can be used as an alias here).

Note that a filter equal to "segment" returns the number of segments within the segment, as opposed to a "self" search, which returns the number of segments similar to segment.

Show_Existence_By_Key() is almost identical to Show_Existence(), except that the "self" operator is slightly different. If the key is non-negative (i.e., the key value was set with Renumber_Key() ), the "self" operator signifies whether or not the key refers to a valid HOOPS object. This works even if the key refers to something besides a segment. However, if the key is negative, then it is a direct memory reference and it becomes too dangerous to test to see whether it still exists. In this case, Show_Existence_By_Key() will just complain and return.
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" and "reference geometry".

NOTES

Users can query the suboption settings for specific geometries by using an "=" sign. For example, to query the existence of a transparency color setting on faces, use Show_Existence("color=(faces=transmission)").

RESTRICTIONS

See also
Begin_Segment_Search, Begin_Contents_Search, Show_Key_Type, Show_Polyline, Show_Shell, Show_Marker.

◆ Show_Existence_By_Key()

int Show_Existence_By_Key ( HC_KEY  key,
const char *  filter 
)

Similar to Show_Existence(), but operates on an object referenced by an HC_KEY.

Parameters
key- A key previously returned from a "K" routine, or a renumbered key.
filter- List of the types of objects to query.
Returns
count - Number of objects found that match the requested type.

DETAILS

No additional details. See Show_Existence()

◆ Show_Existence_Unicode()

int Show_Existence_Unicode ( unsigned short const *  filter)

A utility routine used to determine whether one or more unicode user options exist within a segment.

Parameters
filter- List of the types of objects to query.
Returns
count - Number of objects found that match the requested type.

DETAILS

This function allows the user to query the existence of unicode user options in a particular segment. It is similar to Show_Existence(), except that filter accepts a unicode value in the fashion "user option = unicode name".

NOTES

This function can be used only to query the existence of user options set with unicode values. If used to query options with any other encoding, HOOPS will return an error.

RESTRICTIONS

See also
Begin_Segment_Search, Begin_Contents_Search, Insert_Unicode_Text, Show_Net_Unicode_Opt_Length, Show_Unicode_Options_Length, Set_Unicode_Options, Show_Unicode_Options, Show_Unicode_Text

◆ Show_Existence_Unicode_By_Key()

int Show_Existence_Unicode_By_Key ( HC_KEY  key,
unsigned short const *  filter 
)

Similar to Show_Existence_Unicode(), but operates on an object referenced by an HC_KEY.

Parameters
key- A key previously returned from a "K" routine, or a renumbered key.
filter- List of the types of objects to query.
Returns
count - Number of objects found that match the requested type.

DETAILS

No additional details. See Show_Existence_Unicode()