Define_Highlight

Functions

void Define_Highlight (int count, const HC_KEY *keys, const char *style, const char *options)
 Specifies a method of highlighting an item. More...
 
int UnDefine_Highlight (int count, const HC_KEY *keys, const char *style, const char *options)
 UnDefines an existing highlight. More...
 

Detailed Description

Function Documentation

◆ Define_Highlight()

void Define_Highlight ( int  count,
const HC_KEY *  keys,
const char *  style,
const char *  options 
)

Specifies a method of highlighting an item.

Parameters
count- Length of 'keys' array in parameter 2
keys- An array of HC_KEYs defining an unambiguous path to the highlighted object. See DETAILS for more.
style- The named style to apply to the specified item, set by Define_Named_Style
options- Options to control the behavior of the function

DETAILS

Highlighting an item in the HOOPS scene-graph involves having an entity/segment redrawn with a particular set of attributes. Define_Highlight allows you to apply a named style to an entity or segment, thus causing it to be drawn with that style during the next update.

When a segment-tree is highlighted, it will highlight both subsegments and included segments.

HOOPS Visualize expects the keys parameter to be an array of segment keys from leaf to root which define an unambiguous path to the geometry you wish to highlight. Using a special key value of -1 indicates an include key wildcard.

This wildcard enables you to specify only a partial path. For example, imagine you have instanced geometry [G1, G2, G3, G4] in four places using an include segment [G]. To highlight G3, you would normally need to provide a keys array of [G3, G, model_key, scene_key, etc...] all the way to the root. Using the wildcard, you are able to achieve the same effect by passing [G3, G, -1]. The value -1 "fills in the blanks" so you don't have to.

Note that other than the target key, you are only required to specify the include keys in the keys array - other normal segment keys along the path are legal but will be ignored.

The following choices for the options parameter are recognized:

[no] segment only Indicates that the highlight only applies to the geometry in the specified segment, and will not apply to any subsegments. The default is "no segment only" This option only applies if the key path ends with a segment.

quick moves = [inplace | overlay | spriting | off]

  • InPlace The InPlace option is useful when you are applying a highlight style that contains transparency. In this situation, the overlay geometry is not drawn - the highlight itself is drawn in its place. Using this method incurs a small performance penalty relative to the other options. If you are not using a transparent highlight style, this option will have no visible effect.

  • Overlay The highlighted items will be rendered on top of the scene and ignore the scene’s z-values. Refer to the full details in the ‘quick moves’ section.

  • Spriting The highlighted items will be rendered into the scene with z-values. Refer to the full details in the ‘quick moves’ section.

  • Off The highlighted item will be rendered in the scene with its style as if the attribute had been changed directly in the tree. The general redraw rules for attributes will apply to any items modified by the style.

passive

With the "passive" option enabled, Define_Highlight will not override attribute locks set on highlighted segments.

The following is a usage example for the "passive" option. By default, Define_Highlight will override locked attributes. However, passing passive as a parameter means that locked attributes will NOT be overriden by Define_Highlight:

HC_Define_Highlight(myKeyCount,myKeysToHighlight,"show","passive");

append

With the "append" option enabled, Define_Highlight will append the named style to the named style currently active for the highlighted segment.

The following is a usage example for the "append" option. The first call to Define_Highlight sets the specified keys to the attributes defined in the named style "show" (which might, for example, set opacity). In the second call, with the append option enabled, the options defined in the "pink" named style are appended to the options defined in the "show" named style:

HC_Define_Highlight(myKeyCount,myKeysToHighlight,"show","");
HC_Define_Highlight(myKeyCount,myKeysToHighlight,"pink","append");

Calls to Define_Highlight using the append option will override any conflicting styles defined in previous calls Define_Highlight.

RESTRICTIONS

Highlighted items will be drawn using geometry display lists (segment-level display lists are not currently used). Line-type geometry such as lines, polylines and fixed-tessellation NURBS curves will be drawn in immediate mode. Non-highlighted items in segments with items highlighted with ‘quick moves = off’, are subject to the same limitations.

See also
UnDefine_Highlight, Define_Geometry_Highlight

◆ UnDefine_Highlight()

int UnDefine_Highlight ( int  count,
const HC_KEY *  keys,
const char *  style,
const char *  options 
)

UnDefines an existing highlight.

Parameters
count- Length of 'keys' array in parameter 2
keys- An array of HC_KEYs defining an unambiguous path to the highlighted object
style- The named style to undefine on the specified item, set by Define_Named_Style
options- Options to control the behavior of the function

DETAILS

If a style is specified, then only that style will be removed, based on the options. If a style is not specified, then all styles that apply to the matched key-path and options will be removed.

The following choices for options are recognized:

  • Exact - Only removes the highlights along the specified path.

  • Segment - Only removes segment and segment-tree highlights.

  • Geometry - Only removes geometry highlights.

  • Everything - Removes segment and geometry highlights.

The default is ‘exact’.

See Define_Highlight()