Functions
Optimize_Segment_Tree

Functions

void Optimize_Segment_Tree (const char *segname, const char *option_string)
 Traverses the specified segment tree and makes modifications within it to try to improve rendering performance. More...
 
void Optimize_Segment_Tree_By_Key (HC_KEY segkey, const char *option_string)
 Similar to Optimize_Segment_Tree(), but operates on a segme. More...
 

Detailed Description

Function Documentation

void Optimize_Segment_Tree ( const char *  segname,
const char *  option_string 
)

Traverses the specified segment tree and makes modifications within it to try to improve rendering performance.

Parameters
segname- String containing the name of the segment from which to start the optimizations.
option_string- A comma separated list of the desired settings.

DETAILS

This function helps users improve rendering performance through a number of pre-formulated techniques specified in option_string. The ordering of the options within the list is important, as it dictates the order in which the optimizations are applied, and many of the options have a multiplicative effect on each other. The list of valid choices for option_string below is ordered into a generally applicable scheme:

collapse matrices [= on|off]

This option causes modelling matrices to be removed from the segment tree. Primitives that have a modelling matrix applied will be transformed into world space when the matrix is removed. Matrix calculations are relatively expensive during rendering, so scenes that use them extensively can gain a significant performance boost when this option is set. Default is "collapse matrices = off".

discard user data [= on|off]

This option causes all User_Option and User_Values to be removed from within the specified segment tree. Removing these will allow the function to collapse segments that previously only differed by a user attribute. The default is "off" which means that HOOPS will try merge segments that have the same attributes including user options. If you would like to keep segments with user options completely intact, please see the preserve user options below.

expand includes [= on|off]

When set, included segments will be replaced by a physical copy of the segments referenced by the include. This will, of course, result in an increase in the memory footprint of the HOOPS database. Though this option will not have a significant increase in performance on its own, it can have a significant impact on performance if used in conjunction with 'collapse matrices'. The default is "expand includes = off".

extract geometry attributes [= on|off]

When set, HOOPS will look to see if shells have sub-geometry face colors; if they do, they will be broken out into separate shells and placed into subsegments which have that color set at a segment level. The default setting is "extract geometry attributes = off".

generate mapping [= on|off]

When set, a mapping table is created between the objects in the pre-optimized segment tree and the new tree. This table can then be queried via Show_Optimized_Mapping(). Default is "generate mapping = off".

instance shells [= on|off]

When set, HOOPS will delete any shells in the segment tree that are identical, and replace those deleted shells with a geometry reference and a modelling matrix. For segment trees that contain many duplicates of the same object, this can result in a significant reduction in HOOPS' memory footprint. Duplicates that have rotation or scale matrices applied to to their vertices will not be replaced. The default setting is "instance shells = off".

localize matrices [= off|on]

Certain geometries can have a local matrix. When specified, matrices will be moved onto the geometry if possible and it appears heuristically desirable.

merge shells [= on|off]

When set, all shells in a single segment will be merged into a single shell. If there are many shells within a single segment (this may be the result of the re-organization that occured because of a 'reorganize' setting) then this can result in a significant performance increase. Note: when a number of shells are merged into a single shell, each shell is distributed as distinct region within that new shell. The mapping between these can be determined via a call to Show_Optimized_Mapping().

preserve user options [= on|merge|localize|off]

Allows segments on which user options are set to remain as segments, and not be collapsed in any way. This setting can significantly lessen the effectiveness of this API for models with large numbers of User_Options. The default setting is "preserve user options = off" which allows HOOPS to merge segments that have the same attributes including user options. If you want to merge segments with regard to user options, please see the discard user data option mentioned above. The "merge" setting allows the segments with identical user data to merge, but otherwise behaves just as "preserve user options = on" (such as keeping an otherwise empty segment). The "localize" option allows user options to be moved onto geometry. This can be used with the "merge" option and can counteract some of the negative effects of this option. If preserve user options is on and discard user data is also on, preserve user options will take precedence.

process includes [= on|off]

When this is set includes will be followed and whatever other actions are specified will be applied to them. This does nothing if "expand includes" was also specified.

reorganize [= (option, option, ...)]

Reorganizes the segment structure. Legal choices for option include:

  • attributes [= on|off]

    When set, optimize will analyze all attributes in the data and reorganize based on that. This is almost always preferable to color and is the recommended setting.

  • color [= on|off]

    When set, segments that have identical color settings will be merged into a single segment.

  • spatial [= on|off]

    When set, any segment that contains more than 8 subsegments or 32 pieces of geometry will be subdivided into 8 separate segments. The primitives contained in the old segments will be distributed within the new segments based on their spatial location.

The default setting is "no reorganize".

segment names [= discard|record|sequence]

The "discard" option will remove all segment names from the data. The "record" option will add a user option "ssn=" to each segment. When used with localized user data, this can reduce model complexity while preserving information encoded into the segment names. The "sequence" option renames all segments with a sequential number. This can aid debugging or remove model context that is undesirable to expose.

NOTES

After calling this function, the segment tree may have been modified. Use 'generate mapping = on' and Show_Optimized_Mapping() to associate primitives in the new and old segment trees.

The Optimize_Segment_Tree() API removes any streaming mode settings that may have been defined within the specified segment tree.

See also
Optimize_Segment_Tree_By_Key, Show_Optimized_Mapping, Insert_Shell_From_Region, Open_Region
void Optimize_Segment_Tree_By_Key ( HC_KEY  segkey,
const char *  option_string 
)

Similar to Optimize_Segment_Tree(), but operates on a segme.

Parameters
segkey- Key to the segment from which to start the optimizations.
option_string- A comma separated list of the desired settings.

DETAILS

No additional details. See Optimize_Segment_Tree().

See also
Show_Optimized_Mapping, Insert_Shell_From_Region, Open_Region