HC_Set_Heuristics

void HC_Set_Heuristics(char const *list)

Gives hints to the system about good short cuts to take during program execution.

In HOOPS Visualize, heuristics are assumptions that you’re telling the system to make about your picture. The purpose of making these assumptions is to reduce the time it takes to update the screen, the time it takes to insert new information into the database, or the amount of memory required by the database. In general, if you want your program to run as efficiently as possible, tell the system about all the optimization assumptions you can. (As a rule, though, it’s not generally profitable to go out of your way to make an assumption “come true”.) Note that the “Heuristics” attribute inherits and is scoped just like any other attribute, and it’s perfectly reasonable for different portions of your picture to have different heuristics in effect.

The list of heuristics is passed to the system as an arbitrarily long formatted string containing one or more specifications, separated from each other by commas. Each specification can be preceded by the word “no”. Uppercase versus lowercase is not significant, nor are any leading or trailing blanks on any specification. Embedded blanks within the option name itself are significant.

Each individual heuristic inherits up and down the segment tree and is Set independently of all the other choices; you might find yourself calling Set_Heuristics() several times in a row, feeding in more choices each time. The new choices are merged with the old as they arrive. This avoids having to make the call just once with a long specification string. (Note that UnSet_Heuristics() removes all the information for the attribute for that segment. Use UnSet_One_Heuristic() to remove the setting for just one heuristic.)

The following choices are recognized:

[no] backplane cull [= on | off]

Deprecated. See “face culling”.

[no] clipping [= on | off]

If you choose “no clipping” you are guaranteeing that nothing you draw will fall outside its screen window and need to be trimmed off, nor will anything fall behind a perspective viewing camera. The default is “clipping”.

[no] concave polygons [= on | off]

“No concave polygons” guarantees that all polygons are convex (though concave shell and mesh faces are still ok), and significantly improves the performance of polygon drawing. The default is “no concave polygons”.

[no] culling = [(option, option, option…)]

Tells Visualize not to draw certain objects, depending on settings. Valid choices for option are as follows:

on/off

”On” is a synonym for “culling = (view frustum=on, obscuration=on)”.
hard extent = [x]

Does not draw shells, meshes or segments (including the subtree) whose screen bounding box dimensions are less than this value in pixels. This is independent of the maximum extent mode. The default setting is “hard extent = 0”.
```
 <li> [no] max distance = [x] 
 This will cull anything that lies beyond the specified distance. Units are in world-space. Default is "no max distance".

 <li> maximum extent = [x] 
 Skips the drawing of shells, meshes or segments (including the subtree) whose screen bounding box dimensions are less than
```
this value in pixels. Note: when maximum extent = [x] and the maximum extent mode = none, then the behavior is equivalent to the hard extent = [x]. The default value is 1.
```
 <li> maximum extent level = [ segment | geometry | primitive | default ] 
 Culling is normally done at the segment level, and for potentially large or complex objects like shells and meshes, will be
```
done at the geometry level and even on individual primitives (tristrips, etc) within. This option allows you to specify which type of extent culling is used. The choices are “segment”, “geometry”, and “primitive”. One or more options are valid. The default setting “all” means this is active at all levels.
```
 <li> maximum extent mode = [ none | dot | bounding | defer ] 
```
Defines the drawing behavior when a segment’s bounding box goes below the maximum extent value. Values are as follows:
- ”None” will cause nothing to be drawn.
- “Dot” will cause a single pixel to be drawn at the center of the bouding box.
- “Bounding” will cause the bounding area to be filled with pixels. The color of the pixels equals the net color of faces in the segment on which the culling occured.
- “Defer” results in all geometry below the “extent threshold” being deferred until the end of the update, at which point it will be drawn in a fixed number of equal buckets from large to small. Note that this option is only applicable when you are using Update_Display_Timed().
The default setting is “maximum extent mode = none”.
[no] extent detail = [ on | off]

Setting this option instructs the system to take into account the size of shell-vertices when performing extent culling. The default is “no extent detail”.
obscuration [= on | (pixel threshold = x) | off] (deprecated)
An “obscuration” setting tells 3dGS to do a z-buffer test on each segment to determine whether drawing the contents will result in pixels being modified on the screen. If set, a segment’s contents will only be drawn if the operation modifies any pixels on the screen. Setting “obscuration = (pixel

threshold = x)” ensures that a segment is drawn only if it modifies more than the specified number (x) of pixels. A setting of “obscuration = on” is equivalent to “obscuration = (on, pixel threshold = 50)”. The default setting is “obscuration = off”. This setting has been deprecated and using it may result in undefined behavior.
[no] vector [= (x, y, z)]

Specifies the vector that is used to determine whether or not the owning segment is culled. In particular, if the angle between this vector and the current view vector (the direction from the camera position to the target) is less than the angle defined in the vector tolerance suboption, then the segment will not be drawn. Default is “no vector”.
vector tolerance = fff

Specifies the angle between the view vector and the culling vector which the owning segment is culled. This value is a floating point value in degrees. Default is “vector tolerance = 0.0”.
view frustum [=on/off]

A “view frustum” setting tells 3dGS to not draw any objects (shells, meshes or segments) that are located outside of the current viewport.
view volume = (xmin, ymin, zmin, xmax, ymax, zmax)

Any geometry lying outside of the specified world-space volume will be culled. The volume is the rectangular cuboid defined by a minimum and maximum point. The default is “no view volume”.

The default is “view frustum, maximum extent = 1”. See also the backplane cull option.

[no] detail selection [= on | off]

Instructs selection events to honor the exact shape of the glyphs of a curve, edge or polyline. This means that both the pattern and the weight of a line/edge will affect its selectability. The default setting is “no detail selection”.

[no] exclude bounding [= on | off]

Removes the current segment and its children from bounding box calculations.

Exclude bounding is mainly intended for use by non-visible geometries. There are some exceptions to this rule. An example is HBaseView’s windowspace key and other “screen projected” (which are more of an emulation of screen projection) geometries. Here, care should be taken to ensure none of the geometries get culled. MVO uses quick moves and/or depth range to help deal with this.

Exclude boundings will not force its geometries to participate in automatic near limit calculations. This can cause these geometries to not be drawn.

Exclude bounding is not inherited by parent segments. This means that if a parent is determined to be frustrum culled (for instance), then its subsegment with exclude bounding will be culled as well, regardless of its contents.

Default is “no exclude bounding”.

[no] face culling [ front | back ]

Culling is a 3D update optimization that tells the system it’s OK to remove any polygons, circles, or ellipses, shell, or mesh faces that are facing away (“back”) from the camera, or facing toward (“front”) during drawing. This removes the need to fill the pixels representing the farther face of a closed polyhedron, for example. This culling will not work properly on self-intersecting polygons. With the exception of a closed shell - for which the handedness is automatically defined - you will need to also specify polygon handedness to make “face culling” meaningful. The default value is “back”.

Warning: Culling is performed relative to the camera, so mixing culling with shadow maps may produce unexpected results, such as shadows being cast by parts of the model that are invisible to the camera.

force defer batch [= n]

If the value is greater than zero, then this segment will be placed on a defer list and be drawn after all other segments with “force defer batch = 0” have been drawn. Segments will be drawn from the defer list in order with the segments with a lower “force

defer batch” value being drawn first. This attribute does not inherit and the default value for each segment is “force defer batch

= 0”.

[no] hidden surfaces [= on | off]

“No hidden surfaces” tells the system that it’s not necessary to figure out which parts of your 3-D scene are in front of and should hide other parts of the scene - either nothing overlaps (you don’t especially care what happens when geometries overlap, you’re really only working 2-D), or the ordering will be done manually by calls to Set_Priority() .

“Hidden surfaces”, on the other hand, tells the system that it is necessary to determine what lies in front of what according to their Z -values, and to render the scene in the proper order.

By default, hardware hidden surface removal will be used when available. A different algorithm can be chosen from a selection with Set_Rendering_Options().

Notes:

When “hidden surfaces” is in effect the system will be less able to add geometry incrementally to a scene, and will generally redraw everything from scratch upon any change.
```
<li>It is legal to mix "hidden surfaces" and "no hidden surfaces" in the scene. However, the result may be non-deterministic
```
or unexpected unless special attention is paid to the ordering of sibling segments. For example, if you have 5 siblings segments with 4 of them having “hidden surfaces” (let’s assume hardware z-buffer), and 1 has “no hidden surfaces”, it is possible to have the “no hidden surfaces” segment get drawn first (background) or last (on top of the z-buffered scene) by using Set_Priority(). However, if you are concerned with ensuring that various segments/geometries always draw on top of the regular z-buffered (3d) scene, it would be more appropriate to use the depth range Rendering Option.

The default is “hidden surfaces”.

[no] incremental updates [= on | off]

“Incremental updates” tells the system to try to perform an update by adjusting the existing screen image, rather than just erasing and starting over. This should always be enabled, but you might want to turn it off for debugging. The default is “incremental updates”.

[no] intersecting polygons [= on | off]

“No intersecting polygons” is a hidden-surfaces optimization, and tells the system not to make extra checks for polygons, lines, meshes, etc. that are projecting through each other. The default is “no intersecting polygons”.

[no] internal selection limit = (ddd|(shells=ddd, polyline=ddd))

Certain types of geometry (shells, meshes, and polylines) can have multiple sub-entities selected (faces, edges and/or vertices). However, building up the lists of these sub-entities is a computationally intensive task and is best skipped, unless the user actively requests the information by setting the ‘internal selection limit’. Setting this heuristic causes Show_Selection_Elements() to calculate/retrieve a specified number of faces, edges and vertices during a selection. For example, settting ‘no internal selection limit’ would result in all internal items getting selected.

A single input value applies the selection limit to shell, mesh, and polyline geometries. Otherwise, specific values can be set for shells and meshes, and polylines separately, for example “(shells=50, polyline=10)”. Note: setting “internal selection limit

= -1” tells 3dGS not to perform any detailed internal selection, and this can improve selection performance. However, this special setting will also cause Show_Selection_Element not to return subgeometry entities that are normally guaranteed to be the closest match to a selection ray. The default setting is “internal selection limit = 1”.

model type [= lmv | default]

By setting lmv, developers are informing HOOPS that this model contains a large number of segments and/or geometry. Setting this heuristic allows HOOPS to use algorithms more appropriate for large models. The default setting is “model type = default”.

[no] partial erase [= on | off]

Partial erase assists in minimizing screen updates under special circumstances. When this heuristic is set, and a piece of geometry is removed from a scene, HOOPS redraws the geometry in the containing window color to erase it rather than redrawing the entire scene.

The default is “no partial erase”.

See the Restrictions section regarding partial erase. In addition, there is an alternative method for accomplishing partial erase. The combination of partial erase and incremental updates is expensive in terms of memory consumption, since HOOPS has to remember the drawing context for geometry that might be partially erased. An alternative method for partial erase is to use Control_Update() in conjunction with setting geometry to the color of the window. This alternative uses less memory but requires more programming effort.

[no] polygon crossings [= on | off]

“No polygon crossings” guarantees that for any single polygon, no two edges actually cross each other. This may speed up Insert_Polygon() and polygon filling. The default is no polygon crossing.

[no] polygon handedness [= left | right]

In order to do a backplane cull, there must be some definition of a polygon’s “front” and “back” (or equivalently “inside face” and “outside face”). This orientation is determined by the order in which the polygon’s vertices were originally defined, and the polygon handedness setting (and not the coordinate system handedness). If you wrap the fingers of the chosen hand along the vertices of the polygon, with your wrist at the first vertex specified and your fingertips at the last, then extend your thumb perpendicular to your fingers, by definition, your thumb is extending out of the front face of the polygon. The default is “no polygon handedness”, i.e., no opinion.

For best performance on 3D drivers, display lists should be enabled.

Note: Polygon handedness does not take into account the coordinate system handedness and instead assumes that the coordinate system is left-handed. This means that for users of right-handed coordinate systems, the front and back faces of your polygons may appear to be reversed. The problem is solved by setting the polygon handedness to opposite of what it actually is. The reason Visualize assumes a left-handed coordinate system is so that developers can change the coordinate system handedness without having to also change the polygon handedness.

[no] quick moves [= on | spriting | inplace | off]

The quick moves heuristic tells the system that changes and screen updates are going to come quickly for a particular segment. Specifically, the heuristic says that it’s going to be worthwhile to do extra labor to allow moves or deletions to be updated to the screen without the usual repaint on the segment’s containing window.

on

This option causes geometry in the current segment to be drawn on top of all the other geometry within the scene. For this, HOOPS can use either an exclusive-or (xor) or overlay algorithm. The algorithm may be set using the quick moves preference option for Set_Driver_Options().
```
<li>spriting
 This option allows 3D objects embedded in the scene to be drawn and redrawn quickly, and employs the HOOPS spriting
```
algorithm instead of “exclusive-or” or “overlay” methods. Instead of continuously redrawing the entire scene, a transform with “quick moves = spriting” requires only 2 complete redraws: one at the beginning to update the scene minus the selected geometry, and one at the end after the selected geometry has been transformed. During the transform, only the geometry affected by the transformation is redrawn. Spriting should be used for all operations on geometry such as translation, rotation, scaling, and editing…especially in complex scenes. NOTE: the quickmove preference driver option has no effect on rendering when “quick moves =

spriting”. If spriting cannot be achieved, full updates will be performed instead.
```
<li>inplace</li>
 This setting is useful when you are applying a transparent highlight style to quick move geometry. This setting is
```
designed to suppress the drawing of the geometry (you can get around this by using spriting in your highlight style, if necessary), instead drawing the highlight itself in its place. If you are not using a transparent highlight style, this setting has no visible effect. This setting is slightly more computationally expensive than the other overlay settings.

Quick moves are only of use for display drivers such as OpenGL, Direct3D, X11 or MSW.

Quick-move mode should be used judiciously. If used too much, it might become “slow move” mode, since all quick-move geometry is redrawn on every update.

Quick moves OVERRIDES the effect of Bring_To_Front() and the priority on a segment using Set_Priority().

The default is “no quick moves”.

[no] related selection limit = (ddd)

Given a single mouse click, it takes significant work for the system to sort through and store all the geometry in a scene in its proximity order to the mouse. This happens even if Find_Related_Selection() is never called to look at the results. “Related

selection limit” tells the system that no more than the number of items of geometry past the first will be needed.

To eliminate related selections, use “related selection limit = 0”. “No related selection limit” is equivalent to “no limit”. The limit should be consistent throughout each screen window.

The special value of “related selection limit = -1” will cause the selection algorithm to return the first match it finds, even if there is a possible better match that could be found if it searched more extensively.

The default is “related selection limit = 5”.

[no] selection bias = (lines | markers)

With selection bias enabled, elements in the scene become easier to select. This is achieved by magnifying the selectable area of lines and markers beyond their intrinsic dimensions. Selection bias for both lines and markers can be enabled simultaneously.

“selection bias = [no] lines” results in lines becoming easier to select.

”selection bias = [no] markers” results in markers becoming easier to select.

The default is “no selection bias”.

If enabled, allows the developer to control whether culled entities are selectable. The choices are based on the type of culling. For example, if you do not want vector-culled entities to be selectable, you would choose the heuristic “selection

culling = vector”. To disable selection culling, you would choose the heuristic “no selection culling”. If you set “no selection

culling”, all items will be selectable even if they were culled.

This setting has no effect on backplane-culled geometry.

The default is “selection culling = view frustum”.

selection level = (entity | geometry | segment | segment tree)

Allows the user to designate, on a per-segment basis, what will be returned when a particular item in or below that segment is hit by a selection event. This can simplify the amount of work a developer needs to do in processing selections, while also resulting in a possibly significant improvement in the selection performance. Each option has the following meaning:

 \li "selection level = entity" directs selection events to return the item that was selected.
 \li "selection level = geometry" is a synonym for "selection level = entity".
 \li "selection level = segment" directs selection events to return the identifier of the containing segment of the item

selected.

“selection level = segment tree” is similar to segment
, except that selection events will return the identifier of the segment at the top of the subtree that owns a particular selection item. In other words: if “selection level = segment

tree” is set on segment-A, with two subsegments segment-B and segment-C, any selection event that hits an item in segment-B or segment-C will return the identifier for segment-A.

The default is “selection level = entity”.

Controls how selection events are sorted. Please see the table below:

Option	Description
on	Uses the appropriate sorting based on the selection type: Proximity for point selections and z-sorting for

[no] static model [= on (condition analysis=(view independent | single)) | off]

When the static model attribute is set to “on”, Visualize will combine the geometry and attributes from multiple segments into a more optimized, internal segment tree. At render time, Visualize renders from this internal segment tree instead of the external scene graph that you have defined. When used in conjunction with segment-level display lists, it can significantly improve rendering performance, because graphical objects will be grouped into larger segment-level display lists and result in better GPU throughput.

If you have also set the model type option set to ‘lmv’, then the optimized segment tree will be first organized spatially and then by attributes.

Static model, as its name implies, should be used when you expect your model not to change between updates. For example, you may have view/query logic that is changing a camera in a ‘view’ segment (where that view segment includes the model tree), or is selecting/querying the model. In this case, there are no changes being made to the actual model subtree.

Using one of the “condition analysis” options will cause Visualize to take logical conditions into account when computing the static tree. If it finds branches of the tree that won’t be rendered as a result of the conditions, it will exclude them from the static tree. This can have a significant positive impact on performance for models with a large number of conditions. When using condition analysis, the “view independent” option will work for most cases; “single” offers a further improvement for cases where the view does not frequently change.

If something that depends on conditions is included in multiple places (such as more than one view) with different condition set in them, the tree would thrash (regenerate each time it’s drawn). A case like that should stick with the default static tree and not use static conditions.

Making changes when the static model is active is permissible, but has potential performance implications. See the Static Model Programming guide for more information.

The default setting is “no static model”.

[no] target only [= on | off]

Limits the scope of a selection. Without it, the selection path will be walked up to the a scoping window. When enabled, the selection will be from the terminal segment of the path only.

[no] visual selection [= on | off]

If you turn on visble selection all selections will be post-processed and removed from the selection list if they are obscured in the current view by another object in the scene. This setting has no effect on object-space selections, such as Compute_Selection_By_Shell(), Compute_Selection_By_Ray(), or the “empty driver” cases of Compute_Selection() and Compute_Selection_By_Volume(). The default is ‘no visual selection’.

Any geometry lying outside of the specified world-space volume will be culled. The volume is the rectangular cuboid defined by a minimum and maximum point. This works independently of how the scene-graph was created.

The system is not obliged to make use of any of the Heuristics information. Your program should be prepared for either the “used” or “not used” situation to occur. In the case of “no transformations”, for example, you should set up a Camera Volume that maps to pixel coordinates just in case the system elects to transform your points despite being told not to - this can happen if the hardware, for example, always runs in “transforming” mode.

NOTES

The default setting of the Heuristics attribute - the setting on the root (“/”) segment - can be given a new initial value on most systems by means of the environment variable “HOOPS_HEURISTICS”.

The partial erase heuristic is not obeyed if active style segments are deleted. A full redraw is generated. Partial erase does not generally work when hidden surface removal is active.

RESTRICTIONS