void Set_Rendering_Options (const char *list)
 Allows you to control how carefully and accurately your scene is drawn, and to enable several special drawing effects. More...
void UnSet_One_Rendering_Option (const char *which)
 Removes a given setting established by a previous call to Set_Rendering_Options(), rather than all settings. More...
void UnSet_Rendering_Options (void)
 Removes all settings established by a previous call to Set_Rendering_Options(). More...

Detailed Description

Function Documentation

◆ Set_Rendering_Options()

void Set_Rendering_Options ( const char *  list)

Allows you to control how carefully and accurately your scene is drawn, and to enable several special drawing effects.

list- A quoted string or a string variable containing a list of the desired settings.
Supported Options:
ambient up vector, anti alias, atmospheric attenuation, attribute lock, color interpolation, color index interpolation, color index interpolation options, cut geometry options, debug, clear debug, depth range, diffuse color tint, diffuse texture tint, display lists, eye dome lighting back color face displacement, fea nodes, force grayscale, frame buffer effects, general curve, general displacement, geometry options, gooch options, hidden line removal options, hidden surface removal algorithm, ignore subsegment locks, image scale, image tint, isoline options, join cutoff angle, lighting interpolation, lighting, level of detail, level of detail options, local cutting planes, local viewer, mask transform, nurbs curve, nurbs surface, perspective correction, quantization, randomize vertices, screen range, set debug, shadow map, simple reflection, simple shadow, stereo, stereo distance, stereo separation, software frame buffer options, tessellation, texture interpolation, transparency, vertex decimation, vertex displacement


"Rendering," in computer graphics, is the process of converting a scene description into actual specific pixels on a screen or lines on a page. The "Rendering Options" attribute, in HOOPS, lets you make some choices about the basic algorithms the system should use to do the rendering. You make these choices by specifying the minimum properties you want the final image to have. Then HOOPS selects and calls upon the available algorithms and hardware to achieve the requested quality.

The list of "qualities" is passed to the system as an arbitrarily long formatted string containing one or more specifications, separated from each other by commas. Saying "option" or "no option" is the same as saying "option = on" or "option = off". You can use whichever style you please. 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 Rendering Option inherits up and down the segment tree and is Set independently of all the other choices—you might find yourself calling Set_Rendering_Options() 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 one long specification string. (Note that UnSet_Rendering_Options() removes all the information for the attribute for that segment—use UnSet_One_Rendering_Option() to discard just one of the options described below.)

The following choices for list are recognized:
[no] ambient up vector [= (xxx, yyy, zzz)] If not set, or set to "no ambient up vector", HOOPS Visualize will use the camera's up vector for ambient light interpolation, and therefore the effects will be camera-relative. If lights are visible, ambient light is always interpolated between the up color and down color, where "up" is determined by the ambient up vector setting. To replicate the effect of ambient light in the usual sense, call Set_Color() and set the ambient up and down colors equal to one another. The ambient up vector setting is honored in all drivers except the opengl driver. The default is "no ambient up vector".

anti-alias [= (option, option, ...)]

Enables anti-aliasing for a given segment. Default is off. For instructions on how to control the number of samples, see the "anti-alias" option for Set_Driver_Options(). Legal choices for option are:

  • lines [= on|off]

    All lines and edge geometry is anti-aliased.

  • text [= on|off]

    All text geometry is anti-aliased.

  • screen [= on|off]

    The full scene is anti-aliased. This option is only allowed on drivers that were initialized with the anti-alias Driver_Option set.

  • on|off

    Toggles anti-aliasing for all of the options above.

[no] atmospheric attenuation [= (hither = x.x, yon = x.x)]

Also referred to as fog or depth cueing, atmospheric attenuation is implemented via a linear interpolation model. In the linear model, the color at each vertex of a primitive is dependent on it's position relative to two reference planes perpendicular to the viewing axis. Given hither and yon plane values, the color is calculated as

atmospheric attenuation = (z - yon) / (hither - yon) 

final color = atmospheric attenuation * input color +
              (1 - atmospheric attenuation) * background color 

In general, the hither and yon planes should reflect the extent of the objects in camera - eye space (see Compute_Coordinates() and Compute_Circumsphere() for conversions to this coordinate system).

The default is "no atmospheric attenuation".

Note: The hither and yon planes of atmospheric attenuation have no effect on z-buffering. HOOPS Visualize does not currently provide user control of hither and yon planes for use by the z-buffer.

[no] attribute lock[= (type, type)]

Temporarily overrides attribute settings within a segment tree, where "type" is any one of the settable HOOPS Visualize attributes such as "color", "marker size", "color map", etc. The word can also be "style", to prevent style-segments from being observed, or "everything", to lock all attributes.

Note that we do not recommend that you use attribute locks regularly. When this feature is enabled, rendering performance can be severely impacted.

For example, the user might want to temporarily turn all lines red to highlight them, even though some inner segments have other line colors set. To do this, the user can set the line color to "red" in the owner segment and then lock that color setting:

     "attribute lock = color"

This would cause the inner segments' color settings not to have any effect on the rendering of the tree - to become "invisible" - unless or until an inner segment explicitly turns the lock back off within its scope.

Locking mechanisms may be further refined by specifying discrete geometry types and multiple attributes, such as color and visibility. For example:

"attribute lock = (face pattern, color = (face, markers), visibility=(edge))"

Attribute locks may also be placed on any of the color suboptions. For example, if the user wanted to lock the diffuse color settings, an attribute lock could be placed on the diffuse channel:

"attribute lock = (color = (faces = diffuse))"

This would ensure that transparency or specular settings would not be overwritten on objects affected by the attribute lock.

Attributes that are not inherited cannot be locked. These include "streaming mode", "metafile", "normal" and "window". Furthermore, the "attribute lock" property itself can't be locked. The default is "no attribute lock". See the Restrictions section for more information regarding attribute lock.

NOTE: "no attribute lock" explicitly turns off locks, both on the specified segment, and any children. However, setting "no attribute lock" absolutely does not unset a previously established lock (although the visual effect will often be the same, depending on the data). To ensure that attribute locks are properly disabled, use UnSet_One_Rendering_Option("attribute lock").

[no] color interpolation[ = faces/edges]

HOOPS Visualize allows you to "false-color" polygons, shells, or meshes by setting nominal edge and face colors at each vertex via Open_Vertex() and then one of the Set_Color() routines. Specifying "color interpolation" tells the system that such vertex face colors should be smoothly interpolated along the edge and across the interior of the face.

If you say "no color interpolation," the system draws the edge or face using the explicit local face color ( Open_Face() and Set_Color() ) if any, otherwise the segment-level edge or face color.

The default is "color interpolation". Note that color interpolation is only meaningful for edge and faces with vertex face colors.

Refer to the entry on Set_Color_By_FIndex() for an additional discussion of color interpolating.

[no] color index interpolation[ = faces/edges/isolines]

This is related to "color interpolation". If the "vertex edge colors" or "vertex face colors" are set "by index," the system can either interpolate the indices and then convert them to a color at each pixel ("color index interpolation" specified), or convert the indices into colors at each vertex. Then (optionally) interpolate the colors ("no color index interpolation").

All combinations of "color interpolation" and "color index interpolation" are legal except isolines. Both "on" gives you colors that vary smoothly between the colors in your color map. The first "on" and the second "off" gives you colors that start rounded off to the nearest color map entry and vary smoothly in RGB space (which might or might not have anything to do with your chosen color map rainbow). The first "off" and the second "on" gives you discretely changing colors, such as a contour map. Both "off" gives each face a separate flat color (local or segment-level). These four combinations can be applied to edges and faces separately.

The default is "color index interpolation". This default is only meaningful when there are edge or faces present that have colors set "by index" at the vertices.

Fractional color index values at the vertices are useful when doing color index interpolation, in order to get the phasing right.
Set_Color_By_FIndex() lets you set such values. See Set_Color_By_FIndex() for an additional discussion of color interpolating.
The 'isolines' option has been deprecated. To enable, set and modify isolines, please use the isoline options.

color index interpolation options | cii options [= (option, option, ...)]

These settings are used when handling color-by-findex at vertices of tristrips. It let's you control how color map values are applied.
To set the visibility, positioning, color, pattern and weight of isolines, use the isoline options.

  • [no] value adjustment [= none | normalized | explicit = (scale [= fff], translate [= fff])]

    This option allows you to determines how color map values are applied. If normalized is specified, the color map values are assumed to range from 0 to 1 and are scaled to fit the current color map. If none, which is the default, is set then the index values are used as they are. If you want to explicitly specify a value adjustment, use the scale and translate option. These two transform options help determine the position of the contour in relation to the color map. If only one is specified, the other defaults to the natural value: scale=1 or translate=0.

cut geometry options = (option, option, ...)

Controls the rendering of cutting planes and lines. See also the cut geometry options in Set_Visibility() and Set_Color(). Legal choices for option include the following:

  • level = [ entity | segment | segment tree ]

    Describes the hierarchical scope of the option's effectiveness. Ideally, this should be set to the lowest level below which geometry generally encloses complete volumes. The default value is "entity".

  • tolerance = xxx[%]

    The distance below which line segments can be joined to form closed loops. If the distance is less than the tolerance value, the loop is closed. Cutting lines that cannot be merged into closed loops do not generate cut faces. The value is specified either as a world space distance (without a '%') or a percentage of camera field (with a '%'). The default is "10%".

  • [no] match color[s] = [on | off]

    When this is set, it causes the capping geometry to assume the color of the geometry that's being cut rather then what's set with \ref Set_Color_cut_geometry "cut geometry option" provided in Set_Color(). This is off by default.

[no] debug [= ddd]

Enables special (not yet fully supported) capabilities. The definitions of the debug bits change from release to release and so please contact support for a list of specific options. Keep in mind that debug bits set through this API are not cumulative, so subsequent debug bit settings will replace everything. If you wish to have a cumulatve effect you should look at either the 'clear debug' or 'set debug' options. The default is "no debug".

clear debug = [ddd]

Removes the specified debug bit from the current debug value.

set debug = [ddd]

Adds the specified debug value to the existing debug value.

depth range = ( xxx, yyy )

Compresses effective z values into a subset of what they would otherwise have been. This allows certain pieces of the scene to be drawn on top at all times without additional sub-windows and without the limitations of Bring_To_Front. xxx and yyy should be floating point values such that 0 <= xxx <= yyy <= 1. "depth range = (0,0)" will force all geometry into the frontmost bucket, but will suffer the drawback that it will cause z-fighting amongst the geometry that shares that setting. To get such pieces of geometry to resolve reasonably well against each other, "depth range = (0,0.1)" should perform reasonably well. Depth range settings are not cumulative, and have no effect when the hsr algorithm is set to "none". Default is "depth range = (0,1)"

diffuse color tint = [(option, option, ...)]

Modifies (tints) the diffuse color channel. Legal choices for option include the following:

  • on/off

    Enables or disables the option.

  • [no] color [= color_spec]

    Indicates tint color. Examples include "color = red" or "color = (R=1 G=0 B=0)".

  • effect [= option]

    Means of applying tint. Choices are:

    • grayscale

      Replace the diffuse color with a grayscale equivalent.

    • modulate

      Modulate (filter) the object color by the tint color.

    • modulate grayscale

      Compute grayscale then modulates the object color by the tint color.

    • tone

      Apply a toning function; the grayscale is remapped so instead of going black - gray - white, it's black - tint color - white.

  • range = (float, float)

    Defines a scale and translate applied to the color components before other tinting (results exceeding 0-1 range are clamped).

Defaults are "off, color = white, effect = modulate grayscale, range=(0,1)"

diffuse texture tint [= color_spec]

This option is just like the image tint rendering option but effects diffuse textures instead.

[no] display lists [= on | off | geometry | segment]

Display lists enables the HOOPS Visualize Direct3D and OpenGL drivers to cache data in video card memory. This ensures optimal rendering performance. Legal values have the following meaning:

  • on

    A synonym for "display lists = geometry".

  • geometry

    Places each individual shell or mesh into a single display list. All other possible geometry within a segment will be put into a geometry-specific, segment-level display list.

  • segment

    Places all geometry within a single segment into a single, geometry-specific display list. This means that the number of display lists within a single segment will be equal to the number of different types of geometry contained within that segment. Note that as far as display lists are concerned, shells, meshes and NURBS surfaces are considered a single type of geometry. Using this approach can result in better performance, due to better batching.

See the Restrictions section for more information regarding display lists. The default is "display lists = off".

[no] eye dome lighting back color = color_spec

Sets the back facing color for point clouds. color_spec is the color to be applied. Examples include "color = red" and "color = 'R=1 G=0 B=0' ".

[no] face displacement [= nnn]

This rendering option specifies the number of Z-buffer units that rendered faces should be pushed away from the camera. This can be used to reduce edge stitching by ensuring that coincident edges lay on top of the faces. The units are 1/2^24 in the normalized depth range [0,1]. Negative values will move faces toward the camera, positive values away from the camera. The default value is 8.

Note that the Show_Device_Info() routine can report the size of the Z-buffer being used.

See the Restrictions section regarding edge stitching.

fea nodes This option is intended for FEA-type shell data that may have non co-planar faces which contain 6 or 8 sides. (Note that by default, HOOPS shell faces must be planar.) If this option is set, HOOPS will triangulate 6 or 8 sided faces as if they had an internal triangle or rectangle, respectively. This will result in vertex-color-interpolation that may be more desirable, and ensures that adjacent 6/8-sided faces which share vertices will render without visual artifacts.

[no] force grayscale [= on/off]

Forces grayscale for a segment and its descendants (unless one of its descendants turns it back off). Gray levels are calculated with HOOPS Visualize's standard conversion system: 0.3*red + 0.5*green + 0.2*blue. Grayscale can also be forced for the entire scene (preventing any local settings from turning it back off) with the "force grayscale" option in Set_Driver_Options. For the purposes of color locks, this setting acts as if it were a color setting. In other words, if color is locked (see the "attribute lock=color" rendering option) above the point at which force grayscale is set, it will have no effect. Similarly, if color is locked above where it is unset with a "no force grayscale", it stays gray. Default is "no force grayscale".

[no] frame buffer effects [= on/off]

Frame buffer effects (ambient occlusion, silhouettes, bloom and depth of field) can only be toggled on/off on a per segment basis en masse. They can, however, be individually toggled on a per driver basis with their respective driver options. The default is "frame buffer effects = on".

general curve = [ (option, option, ...)]

Allows the user to define the tessellation for all curve geometries. Such geometries include circles, ellipses, circular arcs/chords/wedges, elliptical arcs and NURBS curves (for NURBS Surfaces, refer to the nurbs surface Rendering_Option). Legal choices for option include the following:

  • budget [= xxx] [512]

    The upper boundary of the number of vertices that will be allowed in the tessellation of the curve, regardless of view settings. Default is 512, which is a large enough number that most curves will be limited by the other constraints.

  • [no] continued budget [= xxx]

    The number of additional vertices will be allocated to the overall curve. A curve with exactly degree+1 control points will have "budget" number of vertices, whereas curves with more control points than that number will have "continued budget" additional vertices for every extra control point. For example, a cubic curve with 6 control points will have [budget] + 2*[continued budget] number of vertices. This option applies to NURBS curves only.

  • [no] maximum deviation [= xxx] Distance, in object space, from the parametric definition of the curve to its tessellated counterpart. Note that since this setting is in object space, it should be set differently depending on the scale of the NURBS control points. Applies to view-independent curves only. Default is "no maximum deviation".

  • maximum angle = xxx The largest angle allowed between adjacent line segments in the tessellated representation. Expressed in degrees. Applies to view-independent curves only. Default is 20.

  • maximum length = xxx The largest allowable length, in the NURBS Curve's normalized [0..1] parametric space, of any line segment. Applies to view-independent curves only. Default is "0.1".

  • view independent | no view dependent

    "view independent" means that HOOPS Visualize tesselates each curve with the number of vertices specified in "budget", in such a fashion that it honors the other "general curve" settings. "view dependent" allows tessalation of a NURBS curve as far as necessary, depending on the camera setting, in order to maintain a smooth curve. "view dependent" is more accurate, but "view independent" is computationally cheaper. Default is "view independent".

general displacement = [nnn]

This rendering option specifies the number of Z-buffer units that rendered geometry should be pushed away from the camera. This can be used to ensure that certain geometry is drawn on top of or behind the rest of the scene. The units are 1/2^24 in the normalized depth range [0,1]. Negative values will move geometry toward the camera, positive values away from the camera. The default setting is "no general displacement".

geometry options = (option, option, option,....)

Sets miscellaneous options on the various 3dGS primitives. Valid choices for option include:

  • hard edge angle = [fff]

    If the angle in degrees between adjacent faces of a Shell/Mesh is less than this value, then the corresponding edge is marked as a "hard" edge. The visibility of these edges can then be controlled by using Set_Visibility("edges=(hard=on/off)"). The default is "hard edge angle = 135".

  • invert polycylinders = [on | [no] radii, [no] colors]

    Changes the order upon which the radii and colors are applied to points in a polycylinder. "invert polycylinders = on" is equivalent to "invert polycylinders = (radii = on, colors = on)" . The default is "no invert polycylinders".

gooch options = (list) Controls the parameters of the Gooch lighting interpolation option. Valid choices for list include the following:

  • [no] color range [= xxx, xxx]

    The color range is in the order of cool (normal pointing away from the light) to warm (normal pointing straight at the light). It would always have to come from a color map as a color by index (or findex). Color ranges that include many intermediate colors are legal (and encouraged). If disabled, the effective color range is assumed to span the entire color map. The default is "no color range".

  • diffuse weight = xxx

    The diffuse weight ranges from 0 to 1. Regular diffuse lighting contributes weight, and the non-photorealistic lighting from Gooch contributes (1-weight). The default is "diffuse weight = 0.5".

  • [no] color map segment = xxx

    A segment from which to take the color map used for the Gooch lighting model. If disabled, gooch lighting draws from the same color map as is used for Set_Color_By_Index and Set_Color_By_FIndex.

hidden line removal options [= (option, option,...)]

This rendering option is applicable when the "hsr algorithm" is set to "hidden line". Legal choices for option include the following:

  • color = color_spec

    color to be applied to the hidden lines and markers. Examples include "color = red" and "color = (R=1 G=0 B=0)".

  • dim factor = [fff]

    "Dim factor" specifies the fraction of the current line color's R, G, and B channels to use for the color of hidden lines and markers. By default, HOOPS Visualize will automatically take a fraction of the RGB values to darken the hidden lines and markers. However, if the window color is white (or near white), Visualize will then effectively use an inverse of the dim factor to actually brighten the hidden lines, thereby providing a consistent means of distinguishing hidden lines from visible lines. Future releases may support specific control of hidden line color and weight. The default value is "dim factor = 0.5"

  • face displacement = [fff]

    "face displacement" specifies how many units to push faces into dc z-space. This can help improve hidden line scene quality if distinct polylines/lines are being used to denote user-defined edges on shell/mesh regions, but are not exactly coincident with the actual shell/mesh edges/vertices. The factor sets a tolerance value which allows lines that might not be fully above the shell/mesh surface to still be rendered. (The display of shell/mesh edges themselves does not pose a problem.)

    Note: hidden line face displacement is separate from the general face displacement value set via Set_Rendering_Options("face displacement = ddd"). Recall that the latter is used to reduce edge-stitching with the z-buffer hidden surface removal algorithm. The default value is "face displacement = 0.5"

  • image outlines = [on/off]

    Turning this on causes HOOPS Visualize to draw a polyline around the edge of where the image previously resided.

  • pattern = [ddd]

    "pattern" specifies line pattern of the hidden lines. See 'patterns.h' for an enumerated list of line patterns. The default value is "line pattern = 3", or a 'dotted' line pattern. (LP_DOTTED in patterns.h.)

  • remove duplicate lines = [on/off]

    Use in presence of pattern option only. Causes duplicate lines to be rendered once resulting in a better picture when using patterned lines. When 1 shell per topological face is being used, an HLR rendering will result in the dashed/hidden lines showing up with inconsistent patterning, due to their being overlapped and out of sync.

  • render faces = [on/off]

    Causes triangles to be flagged for display during a hidden-line rendering. HLR visibility & dim factor are applied appropriately. Faces are either visible or hidden based on a centroid test. Transformed text characters are drawn as triangles with the "render faces" flag forced on. The default value is "render faces = off".

  • render text = [on|off]

    When enabled, this option causes text to be flagged for display during a hidden-line rendering regardless of its location in the scene. The default value is "render text = off".

  • rendered face sorting algorithm = [none/painters/z-sort/szb/hzb]

    Specifies the sorting algorithm that should be used to sort the geometry which has the render faces option turned on. This option does not take a hidden line algorithm as a value. Default is "hzb" unless hardware is not available, in which case it falls back to "painters".

  • silhouette cleanup = [on/off]

    A silhouette edge is defined as any edge for which one adjacent face points towards and the other away from the camera. Silhouette edges can show unpleasant "fishtail" patterns at points on smooth surfaces where curvature in one orientation is very different from the curvature in another (e.g. the inside of a torus). Silhouette cleanup forces a postprocesses to remove most of these patterns. The default setting is "on'.

  • visibility = [on/off]

    "Visibility" controls the display of hidden lines and markers. This is NOT to be confused with the choice of the hidden line algorithm itself. The default value is "visibility = on".

  • weight = [ddd]

    Weight applied to the hidden lines. Refer to Set_Line_Weight() for appropriate values.

  • transparency cutoff = [fff]

    This option specifies the threshold for when transparent objects are considered opaque. Objects with transparency greater than the cutoff will be considered opaque while objects with transparency less than the cutoff will treated as transparent. The cutoff value ranges from 0 to 1. The default is 0.8.

hsra | hsr algorithm | hidden surface removal algorithm | visible surface algorithm = [type]

This attribute is used only if "hidden surfaces" is set under Set_Heuristics() . By default, the value is "hsr algorithm=hardware z-buffer" which means that hardware will be used if available, otherwise "painters" algorithm is used instead. NOTE: Transparent and non-transparent geometry have separate hidden surface removal algorithms. See transparency options for details. Legal choices for type include:

  • hardware z-buffer | hzb

    Uses any available hardware acceleration.

  • painters

    Skips over the hardware even if it is available. This option uses the painters algorithm, which may show fewer edge aliasing effects than a hardware Z buffer. It is often used instead of the software z-buffer when memory is limited.

  • software z-buffer | szb

    Skips over the hardware even if it is available. Software Z buffer may display fewer edge aliasing effects than a hardware Z buffer depending on the hardware used. The software Z buffer will allocate a frame buffer and a depth buffer in main memory. For complex scenes, the software Z buffer is the fastest, although it can be the most memory intensive algorithm.

  • Z-sort only

    Tells the system that the scene does have some hidden surfaces in it, but the full-scale software hidden surface computation won't be necessary. Specifically, "Z-sort only" says a simple sort of the geometry by approximate screen depth will be sufficient to generate an accurate picture. This can significantly decrease the update time for some pictures. You can also think of "Z-sort only" as a "rough draft" hidden-surface.

  • hidden line

    This is the analytic hidden line option. Instructs the system to display visible (i.e. unobscured) lines, parts of lines, markers and text. Faces of geometry which have a visibility setting of ("faces=on") will be used to obscure the lines, markers and text. Like all true hidden line hsr algorithms this is a fairly computationally intensive algorithm O(nlogn). This is because it needs to clip all visible lines, text and strings against all visible triangles. Triangles are placed into a quad-tree to speed up the clipping process. The insertion points of text and markers are used during the clipping process.

  • fast hidden line

    Like hidden line but uses a multi-pass rendering approach that takes advantage of graphics hardware. "zhlr" is a synonym for "fast hidden line". This algorithm falls back to analytic hidden line if the current driver is not OpenGL, or if HOOPS Visualize finds an OpenGL implementation that doesn't support the required features.

  • priority

    This instructs HOOPS Visualize to use the priority assigned with Set_Priority() to decide the drawing order of objects. Objects with the highest priority are drawn on top. By default all geometry (and includes) have a drawing priority assigned according to their order of insertion.

    Priorities can be set on segments, geometries and include links.

    Segment-level priority:

    • Priority values only control the traversal order of sibling segments.
    • For the OpenGL2 and Direct3D drivers, the only effect that segment-level priorities have is to disambiguate the drawing order of geometries that have the same priority.
    • For all other drivers, segment level priority has no useful effect.

    Geometry-level priority:

    • Priority values applied to primitives are global and are honored irrespective of the priority values of their parent segments.

    Include links:

    • All primitives behind an include link are put into the global list according to the priority set on the include link, and then sorted relative to each other using their respective priorities.

    Performance Notes:

    • HOOPS Visualize's shader-based drivers have the ability to convert priority values into final z positions, thereby enable hardware-accelerated z-buffer rendering, and thus fast performance. Other drivers will produce the correct result but rendering will be much slower since all geometry will be sorted during scene-graph traversal.


    The "priority" hidden surface removal algorithm is primarily used for creating layers within 2D scenes and can cause undesired results when rendering non-planar objects, such as shells or meshes, that can have some parts overlapping others within the same primitive.

See the Restrictions section regarding hidden surface removal.

[no] ignore subsegment locks[ = (type, type)]

Allows a user to force HOOPS Visualize to ignore attribute locks within the segment tree. The subsegments can not override a parent segment's "ignore". The syntax does allow specifying "no" or "=off", but that's for convenience of certain settings, such as: "ignore subsegment locks=(color=(geometry, no text))" to set "ignore" for all color locks except text. Note the use of attribute locks and the overriding of attribute locks results in a severe impact of rendering performance. This is option is not set by default.

image scale = ((float) width, (float) height)

Applies a linear image scaling factor to a segment and its children.

image tint [= color_spec]

When set, all pixels within images will be modulated with the specified color (blue, green, etc).

isoline options [ = (option, option, ...) ]

The isoline options let you set the visibilty, positioning, color, pattern, weight and lighting of isolines. Note, that the final position value of isolines is a result of the Set_Color_By_FIndex() setting as well as the value adjustment setting in color index interpolation options.

  • visibility [= on|off]

    Determines whether isolines are rendered. The default is 'visibility = off'.

  • positions [ = repeat[ing] = (offset = fff, interval = fff) | explicit = (fff, ...)]

    By default, isolines are draw at regular intervals which is equivalent to the setting: "positions = repeat=(offset=0, interval =1)". If you want to draw isolines at specific values, then use the explicit key word and then list the values. Note that explicit values should be specified strictly in increasing order (ie, no duplicate or decreasing values). If the value adjustment, in color index interpolation options, is normalized, explict values are assumed to be as well.

  • color[s] = (color_spec | '*' | '-', ...)

    This option allows you to pass a comma delimited list of colors for the isolines. Possible values include an explicit specification of the color, '*' for an inherited edge color, or '-' if you want the interpolated value. The default value is '-'.

  • pattern[s] = (pattern | *, ...)

    Set a pattern for isolines as specified in Set_Edge_Pattern() or you can '*' which indicates that the values should be inherited from the edge pattern. The default value is '*'.

  • weight[s] = (fff | *, ...)

    Sets the weights for isolines as specified in Set_Line_Weight() or you can pass '*' which indicates that the value should be inherited from the edge weight. The default value is '*'.

  • [no] lighting

    Controls whether isolines are lit. The default is 'no lighting'.

join cutoff angle [= nnn | (edges/lines) = nnn]

The maximum angle between two segments in a line or edge for which a mitered join will be drawn. The join style is set through Set_Line_Pattern() or Set_Edge_Pattern(). The default setting is "join cutoff angle = 150".

[no] lighting interpolation [= phong | gouraud | gooch | (faces/edges[= phong | gouraud | gooch])]

"Lighting interpolation" lets you treat the edges and faces of a shell or a mesh as if—for the purposes of lighting—they were really curved surfaces. "Phong" interpolation does this by figuring a nominal "vertex normal" for each vertex as the average of the surrounding normals. The vertex normals are then interpolated at each pixel of the edge or face to give a nominal local normal vector. The lighting is then figured at each pixel using the local normal.

"Gouraud" interpolation figures the lighting only at each vertex of the face. The resulting colors are then interpolated to obtain the pixels along the edge or within the face. Gouraud lighting is significantly faster than Phong in software; Gouraud also is often available directly in the hardware (see Show_Device_Info() ) while Phong never is. On the other hand, Phong lighting is more accurate and has fewer artifacts, especially in rapidly-changing areas such as the shiny spots (specular highlights) of the object.

"Gooch" interpolation, in addition to taken colors calculated by physics-based lighting equations, also blends them with a color that is taken more from artist's techniques. Highly lit surfaces are assigned a "warm" color, whereas areas pointing away from the light are given a "cool" color. The net effect is that lighting becomes a color shift in addition to the usual light to dark transition. Gooch lighting can be controlled by 'gooch options'.

"No lighting interpolation" means the edge or faces are to be drawn as flat objects. If your hardware doesn't directly support Gouraud lighting then "no lighting interpolation" will tend to be much speedier to render than Gouraud (or Phong) interpolation.

The default value is "lighting interpolation" of edges and faces.

Since vertex normals are required for both Phong and Gouraud, "lighting interpolation" has no effect on simple polygon faces nor edges. Also, this option only affects the lighting calculation: the silhouette of the object will still clearly show that the object is built of flat faces.

[no] lighting [= phong | gouraud / (faces/edges[= phong | gouraud])]

A convenience synonym for "lighting interpolation".

level of detail | lod [= off | on ]

This option implements or disables the LOD module in all rendering operations. Also see our separate documentation on LOD and the Programming Guide.

level of detail options | lodo [= (option, option, ...)]

This rendering option is applicable only if the level of detail option is set to on.


  • Not all options are applicable to point clouds (a shell with a face list count of zero).
  • If the mode is set to "segment", only the "clamp", "threshold = (xxx% area)" and "fallback" options are supported.

Legal choices for option include the following:

  • algorithm = fast | nice

    Use the fast-LOD algorithm, with some visual quality degradation, or the "nice" LOD algorithm, with extra generation time but a better representation. Default is "fast". This option only applies to facetted shells.

  • [no] bounding = current | (minx, miny, minz, maxx, maxy, maxz)

    Setting the bounding option for LODs affects the calculation usefulness heuristic (see below). In the 'current' case, HOOPS Visualize will adapt to whatever changes are made to the current segment's bounding volume while when you provide an explicit bounding box, HOOPS Visualize will be ignore any changes to bounding volumes in the database. Default is "no bounding".

  • [no] calculation usefulness cutoff = (xxx,xxx,xxx,xxx...)

    This option sets the thresholds below which LOD's will not be calculated. This can be specified as one global value to apply to all levels, or as a list of numbers, a different one for each level. Default is "no calculation usefulness cutoff". (Note: this option, in practice, turned out to be less useful than expected and so may be phased out at some point in the future)

  • [no] clamp = [xxx]

    This will cause the LOD module to unconditionally display a certain level of detail. "clamp=0" will have the effect of forcing the original data to be displayed. This will have the same visual effect as turning LOD off. "clamp=-1" is equivalent to "no clamp". With clamping, no new levels of detail will be created unless the preprocess option is used (as opposed to when clamping is disabled, in which case levels of detail will be created as needed). If a requested level is not present, HOOPS Visualize will display the next lower resolution. If there is no lower resolution available, it will display the next higher resolution. The default is no clamp.

  • [no] collapse duplicate vertices

    The collapse duplicate vertices option prevents cracks from forming where there are multiple vertices coincident in space (that were, for example, put there to create a hard edge). Default is "collapse duplicate vertices".

  • fallback = none | bounding | coarsest bounding | coarsest none

    The fallback option dictates switching behavior if and when LOD is clamped to a level that doesn't exist for a particular shell. The default is "coarsest none", where:

    • none == draw nothing
    • coarsest == draw the coarsest representation available
    • bounding == draw the bounding box of the object
    • bounding none == draw the bounding box if LOD at draw time arrives at one level coarser than the coarsest currently defined. If it arrives at a level two or more levels coarser than the coarseset defined, draw nothing at all.
    • coarsest bounding == draw coarsest representation if and only if it is determined that calculation halted as a result of "min triangle count". Otherwise, draw the bounding box
    • coarsest none == draw coarsest representation if and only if it is determined that calculation halted as a result of "min triangle count". Otherwise, draw nothing.

  • levels [ = xxx ]

    Specifies how many levels should be calculated. The lowest level number is the most detailed, and the highest is the most compressed. The default number of levels is 2.

  • [no] max degree [=xxx]

    Places a limit on the number of edges that can be connected to a vertex. Default is "max degree=15". This option does not apply to point clouds.

  • [no] preprocess

    Relevant only if clamp (see above) is set and greater than zero. Causes geometry to generate LOD versions during an update if not already present. Geometry that is not clamped (a.k.a. dynamically switched) will automatically generate LOD representations even without this option. Additionally, one other way that LOD representations can be generated is with an explicit call to Regenerate_LOD(). The default is "no preprocess".

  • mode = segment | geometry

    Sets whether the LOD should be attached to the geometry or the segment. In the case where we set 'segment' then all LODs under that segment will be ignored during LOD switches. Furthermore, when you call Regenerate_LOD(), 3dGS will try and collapse all shells contain in this portion of the segment tree into a single monolithic shell and generate LODs from it. If the mode is set to "segment", only the "clamp", "threshold = (xxx% area)" and "fallback" options are supported. Default mode is "mode = geometry".

  • [no] min triangle count [= xxx]

    Sets a lower bound on the number of triangles that a LOD representation can have. Simplification will halt at the final level above the given threshold. Quality of simplified representations degrades quickly as the number of triangles gets to be too low. Changes to this variable will not trigger recalculation of representations. The default is "min triangle count = 50". This option only applies to facetted shells.

  • ratio = xxx[, xxx, xxx, xxx, ...]

    Specifies how many triangles for facetted shells or points for point clouds each LOD level should have in relation to the previous, expressed as a floating point value between 0 and 1. For example, ratio = 0.25 would mean that level 1 would have 1 triangle for every 4 triangles in level 0 for a shell with a face list. The default is "ratio = 0.50".

  • threshold = (xxx triangles per cm squared | xxx triangles per pixel squared | xxx % area, [xxx, xxx, xxx...]

    An array of floating point values, along with units to determine how they should be interpreted.These values dictate the point at which switching should occur from one LOD level to the next. If specified without units, the values are assumed to be distances in world space from the camera position. The values can be density of triangles in physical square centimeters (resolution independent), density of triangles in terms of square pixels (resolution dependent) or the screen space size of an object (resolution and model complexity independent). The units can be specified by their abbreviations of "tpcm2", "tppix2", or "%", respectively. It is not legal to specify different units for individual levels. The last specified value is copied to all subsequent LOD levels. Note that only the percentage of area option will apply to point clouds. Default is "threshold = 30 tpcm2" (for every LOD level).

    Note: for threshold, neither distance nor "% area" factor in the number of triangles at each LOD level. Therefore the only useful way to use it is to specify more than a single value.

  • [no] tolerance [= xxx oru / xxx % fru]

    This option is only relevant if the "collapse duplicate vertices" option (see above) is also set, in which case it behaves exactly as described in ::Compute_Optimized_Shell(). The default is "no tolerance".

  • usefulness heuristic = [type]

    Avoids LOD calculations for objects which do not pass the tests. Legal values for type include:

    • bounding volume ratio per triangle
    • bounding volume ratio
    • bounding volume per triangle
    • bounding diagonal ratio per triangle
    • bounding diagonal ratio
    • bounding diagonal per triangle

    The per triangle options will only be applicable for facetted shells.

local cutting planes = on/off [off]

Controls whether cutting planes are treated as global (affect the scene in the curent window) or local (affect geometry in the current segment and subsegments). Whatever setting is active at the segment containing the cutting plane takes effect. Thus, geometry can be affected by both local and global cutting planes at the same time. By default, cutting planes are global.

local viewer = on/off [off]

Controls whether, for the purpose of lighting calculations, the position of the camera should be considered important. Lighting calculations are normally done only considering the direction of normals relative to lights and the view vector. The default is "no local viewer".

mask transform = ( camera=(option1, option2, ...), modelling matrix = (option1, option2, ..) )

The mask transform allows you to force 3dGS to ignore any rotations, scales or translations that are due to either a modelling matrix or a camera. The option string can be either 'scale', 'rotation' or 'translation' with each resulting in the respective elements being removed from the final matrix used to draw the geometry in the specified segment tree.

nurbs curve = [(option, option, ...)]

nurbs surface = [(option, option, ...)]

Controls the rendering of NURBS surfaces. Option can include the following:

  • budget = xxx [10000]

    An upper bound on the number of vertices that will be allowed in the tessellation of the NURBS surface. Default is 10000, which is a large enough number that we expect most surfaces to be limited by the other constraints.

  • maximum facet deviation = xxx [1]

    Distance, in object space, of the tessellation to the parametric definition of the surface. Note that since this setting is in object space, it should be set differently depending on the scale of the NURBS control points. Default is 1.

  • maximum facet angle = xxx [20]

    The largest angle allowed between the surface tangents evaluated at any two corners of a given facet. Expressed in degrees. Default is 20.

  • maximum facet width = xxx [1.42]

    The largest allowable length, in the NURBS Surface's normalized [0..1] parametric space, of any facet's edge. Default is 1.42, which is larger than the longest possible edge that can be created, sqrt(2).

  • trim budget = xxx [500]

    An upper bound on the number of vertices that will be allowed in the tessellation of a trim curve. Default is 500.

  • maximum trim curve deviation = xxx [0.005]

    Distance, in the NURBS Surface's normalized [0..1] parametric space, of trim curve vertices from the parametric definition of the trimming curve. Default is 0.005.

[no] perspective correction

Normally, when performing Phong shading or texture mapping, various values (vertex parameters, geometric location, etc.) are interpolated across each surface. Without perspective correction, these values are linearly interpolated in screen-space. This linear interpolation will produce undesired artifacts. Requesting "perspective correction" will use a slower, but more accurate nonlinear interpolation method.

Note that some systems with accelerated hardware always perform perspective correction. Default is "perspective correction".

quantization = type

On devices that limit the number of colors that can be simultaneously displayed (such as 8-bit-plane mapped devices), HOOPS Visualize may need to dither colors when drawing. The quantization option selects the dithering algorithm to be used when a true-color object needs to be drawn on a mapped (color-limited) device. Legal choices for type include:

  • threshold

    Objects will be drawn in the color found in the fixed color table that is closest to the desired true-color value. Although thresholding is the fastest method for converting from true-color to a mapped device, it can produce "banding" artifacts on smoothly shaded surfaces.

  • ordered dither

    The desired true-color object will be drawn in a series of screen-aligned fixed color table colors. When viewed from a distance, this series of fixed table colors has the appearance of the desired true-color. Though marginally slower than thresholding, an ordered dither does not produce "banding" artifacts.

  • dither

    A synonym for "ordered dither".

  • error diffusion

    Similar to the "ordered dither," this method produces a more pleasing image, but at greater computational cost.

In each case, using a larger fixed color table will improve the dither quality. See the "fixed colors" option of Set_Driver_Options() for more information.

The default method of quantization is "ordered dither". Note: Some devices may ignore the quantization option except when drawing into the software Z-buffer.

[no] randomize vertices = [on/off]

When "randomize vertices" is enabled, vertices that are compiled into display lists will be inserted in random order. This option is intended for a more uniform point distribution when applying vertex decimation to non-randomized data.

screen range = (left, right, bottom, top)

Limits the amount of the screen (or the containing window) to be used by the referenced segment upon display. Units are in window coordinates. Default value is no screen range. This functions just like Set_Window() except it does not nest.

shadow map [ = (option, option, ...)]

Instructs Visualize to generate shadow maps for the scene. Legal choices for option include:

  • on | off

    High-level control of whether shadow maps are generated

  • [no] jitter [= on | off]

    Turning this on causes stochastic sampling of shadow maps. This should reduce aliasing in the shadow map. Default is "jitter = on".

  • resolution = xxx

    The width and height of the shadow map. This value will be clamped up/down to 512, 1024 or 2048.

  • samples = xxx

    The number of locations in the shadow map used to determine the percentage value of light received by a pixel in the rendered scene.

  • [no] view dependent [ = on | off]

    When enabled, the view frustum is taken into account when generating shadow maps. This results in significantly better visual quality, but at the cost of not being able to reuse shadow maps from previous frames, even if the lighting is constant with respect to the scene. The default is "view dependent".

The shadows visibility option must also be on for shadows to be rendered in the scene. The default setting is "shadow map = (off, jitter=on, resolution=512, samples = 4)". A more detailed discussion on shadow maps can be found in the programming guide. Please see restrictions for a list of what primitives can or cannot cast shadows.

NOTE: This feature is currently supported in the HOOPS Visualize DX11 and OpenGL2 drivers. Also, shadow maps are calculated by double-drawing of the scene, and so turning on shadow maps will result in approximately a 50-percent slowdown in rendering performance.

[no] simple reflection [ = (option, option, ...)]

This option tells HOOPS Visualize to draw a reflection of the model on a plane defined within the scene. Legal choices for option include one or more of the following:

  • on | off

    Controls the visibility the reflection plane. Default is "off".

  • [no] attenuation [= ( hither = fff, yon = fff ) ]

    Fades the reflection as the model moves away from the reflection plane. The hither and yon settings define the orthogonal distances (in world space) from the reflection plane to the parallel hither and yon planes. Attenuation begins at the hither plane and increases linearly such that the model is not visible in the reflection beyond the yon plane. Default is "no attenuation". This option is only available under the DirectX driver.

  • [no] blurring [= ddd]

    An integer between 1 and 31 indicating the level of blurring (softening) that is applied to the reflection. This option is only available under the DirectX driver.

  • fading = (on/off)

    When set, the reflection plane will fade as it moves away from the camera. Default is "fading = on".

  • opacity = fff

    A value between 0 and 1 that sets the transparency of the reflection plane. A value of zero will make the plane completely transparent. Default is "opacity = 0.5".

  • plane = (a, b, c, d)

    Sets the plane on which the reflection should be projected. Default is "plane=(0,1,0,1)".

  • visibility = visibility_spec

    Defines the visibility settings for the model when rendered in the reflection plane. You can only control the visibility of "edges", "faces", "lines", "text", "polygons", "images", "vertices", "markers" and "lights" . Sub-geometry settings are not allowed. The default setting is "visibility= (everything=off, faces=on, lights=on)".

Please note that using simple reflections requires HOOPS Visualize to draw the scene twice which will result in approximately a 50-percent reduction in rendering speed. The default setting is "simple reflection = (off, plane = (0,1,0,1), opacity=0.5, fading, no attenuation, no blur, visibility=(everything=off, faces=on, lights=on))".

[no] simple shadow [ = on | off | auto | (option, option,...)]

This setting is used to turn shadows on and additionally to set the location within the segment tree from which shadows should be generated. Typically "on/off" is used at the root of the segment tree where other shadow properties are set. The "auto" setting helps to optimize shadow regeneration, and should be set at locations within the segment tree that require frequent regeneration due to changing modelling matrices or visibility changes. The "auto" setting ensures that the shadow geometry will only be re-generated for the local portion of the segment tree. Default is "off".

Legal choices for option include one or more of the following:

  • on/off

    Controls the visibility of the shadow. Turning 'on' always causes 3dGS to regenerate the shadow. Default is 'off'

  • opacity = fff

    A floating point value between 0 and 1 that sets the transparency of the shadow. The default value is "opacity=1".

  • plane=(a, b, c, d)

    Sets the plane that the shadow should be projected onto. The four parameters represent the plane equation ax + by + cz + d = 0. Default is (0, 1, 0, -1).

  • light=(i,j,k)

    Sets the direction that the light is coming from. Default is (0, 1, 0).

  • resolution = x

    A number from 32 to 1024 which sets the resolution of the shadow. The current default is 256.

  • blurring = y

    A number between 1 to 31 indicating the level of blurring (softening) that is applied to the shadow. The effect is more noticeable at lower resolutions as the number controls the size of the blur region, which is effectively a smaller part of high-resolution images.

  • color = color_spec

    The desired color of the Shadow. Default is 'black'.

  • [no] ignore transparencies = on/off

    Ignores any segment level transparency setting when rendering the simple shadow. The default is "ignore transparencies=off".

  • fast bounding

    If set, this will use an available segment bounding rather than calculating a more accurate but time-consuming bounding.

[no] stereo

Toggles stereo viewing. Valid only when the "stereo" driver option has been set.

stereo distance = (xxx)

Adjusts the distance between camera position and the stereo focal plane, and is given in terms of the camera eye distance. A stereo distance of zero corresponds to the stereo focal plane being set at the camera target. Default is "stereo distance = 0".

stereo separation = [xxx]

Adjusts the angle of separation between right and left stereo views. Default is 3.0 degrees

software frame buffer options [= (option, option, ...)]

This rendering option is applicable when the "hsr algorithm" is set to "software Z buffer". Legal choices for option include the following:

  • [no] size limit [= nnn rasters | nnn bytes]

    Can be used to limit the amount of memory used by the software frame buffer (at the expense of speed). When limited, the software Z buffer is rendered to the screen using horizontal bands.

  • color depth = [match device | full color]

    Specifies the depth of the software frame buffer. On 24-bit-plane display devices, there is no difference between "match device" and "full color".

    For 8-bit-plane display devices, "match device" will require less memory for the buffer, and will allow the finished buffer to be transferred to the screen quickly. However, "match device" may be slower overall since dithering might be applied multiple times per pixel when rendering to the buffer (this depends on scene content).

    When "full color" is specified, rendering to the buffer does not require dithering and will be faster. However, "full color" will require more memory (up to a factor of four) and will be slower when transferring the finished buffer to the screen (due to dithering).

    Use "match device" for simple scenes, and "full color" for complex scenes (if you have sufficient memory). The default is "match device".

  • [no] retention

    Retention determines whether or not the memory for the software frame buffer is retained from update to update. For most circumstances, "retention" (the default) will allow faster incremental drawing of subsequent updates.

    You would normally select "no retention" for applications that have many overlapping Z-buffered windows, due to the extreme memory required to retain multiple buffers.

    This aspect of software frame buffer options is only applicable when "no size limit" is also set. The default is "no size limit, color depth = match device, retention".

  • [no] technology [= software frame buffer]

    The software frame buffer (not to be confused with the software z buffer) writes all graphics to an offscreen buffer first, then writes that result to the screen when done. The benefit is that only one bus transfer is involved. The "software frame buffer" rendering option is fully compatible with all the hidden surface algorithms with the obvious exception of "hardware." Additionally, it is very useful in trapping graphics in "no hidden surfaces" mode.

tessellation = (cylinder = (xxx [, xxx, xxx, xxx...]), sphere=(xxx [, xxx, xxx, xxx, xxx...) )"

This option controls the tessellation of cylinders and spheres during insertion and LOD calculations.

For cylinders, tessellation sets the number of faces that should be used during the rendering of a cylinder at each LOD level, where the first integer corresponds LOD level 0 (no simplification): the standard cylinder that is generated during insertion. The second (optional) integer corresponds to LOD level 1, etc. Special values are 0 to trigger drawing a line (using edge visibility), or -1 to trigger drawing nothing at all. Default resolutions are (cylinder = (24,12,6,0,-1)) For spheres, the first integer tessellation sets the number of faces that are generated around the sphere's equator during a call to Insert_Sphere(). Subsequent integers correspond to LOD levels 1, 2, 3 etc. As with cylinders, 0 and -1 have special meaning: 0 means draw a point at the center. -1 means draw nothing at all. An example of the tessellation setting for a sphere is as follows:

  HC_Set_Rendering_Options("tessellation=(sphere=(20, 5, 1, 0, -1 ))").

[no] texture interpolation [= on/off / (faces/edges[= on/off])]

"Texture interpolation" is an option that allows you to control the application of texture mapping to shell or mesh faces and edges without changing other attributes. For texture maps to be applied to a surface, the following must all be true:

  1. The "texture interpolation" rendering option is enabled.
  2. The shell or mesh to be textured has vertex parameters specified (with MSet_Vertex_Parameters() ).
  3. The face color attribute has been set (with Set_Color() ) to a named texture (defined by Define_Texture() or Insert_Image() ).

Setting "texture interpolation" (the default) is equivalent to "texture interpolation= (faces=on, edges=on)".

Note: Texture mapping both edges and faces simultaneously (with both visible) does not make sense (since texture mapping just faces will render the same image) and will perform slowly. Turn off edge visibility (with Set_Visibility() ) when texture mapping faces.

transparency = (option, option, ...)

Controls transparency. Legal options are as follows:

  • style = [ blended | screen door | off ]

    Style affects 'how' to perform blending. "blended" is the default behavior.

    blending: The transparent object will be blended with the color of the underlying object. This is the standard alpha-blending approach and the default behavior for this option.

    off : This will disable transparency overriding all other transparency settings and forcing the geometry to be opaque. It can be used to temporarily disable transparency for the object or scene. (Another way to do this is to reset the tranmission component of color to 'black' for transparent objects, but this is much more cumbersome of there are many segments that have a settting for transmission color.)

    screen door: This is a pseudo-transparency algorithm that optimizes performance and can be used as shortcut in the place of blending. A fraction of the pixels of the transparent object will be drawn, effectively allowing the user to see through the transparent object (hence the name screen door). This will only produce reasonable results if the tranmission value was close to 'gray' (meaning, the developer wanted 50% of all light to pass through). Additionally, no sorting of transparent objects will be performed when 'screen door' is set; therefore, it should also only be used when there is only 1 'layer' of transparent objects.

  • hsra = [ painters | z-sort only | depth peeling | none ]

    Hidden surface removal algorithm(hsra) controls which algorithm will be used to sort all the triangles that represent transparent objects. The default option is z-sort only.

    depth peeling : This in a non-sorting technique based on multi-pass drawing, and leverages hardware acceleration to quickly produce an accurate rendering. Depending on the amount of overlayed transparent objects, this approach will give varying accuracy and performance results based on the number of 'layers' that are specified by the user (and how many are currently supported by Visualize). Currently it is only recommended to specify 1 layer (the default) since each additional layer may incur a performance hit.

    painters: This sorting method will produce a completely accurate rendering of transparent scenes that have overlapping transparent objects, but at the cost of additional rendering speed.

    z-sort: This sorting method can result in rendering artifacts at locations where transparent objects intersect with one another, but is faster than doing a full-blown 'painter's sort'. It is the default algorithm.

    none: No sorting will be performed, but transparent objects will get draw deffered (drawn on top). However, if overlapping transparent objects are present (or if a single transparent object is present that contains overlapping faces, like a sphere), the rendering will not be accurate.

    Transparent and non-transparent geometry have separate hidden surface removal algorithms. Default is z-sort only.

    NOTE: The none (i.e. no sorting at all) setting should only be used if:

    1. "style=screen door" -- screen door transparency does not require sorting, so "screen door" automatically implies that sorting will be disabled;
    2. extra information is known about the data to indicate that no two transparent objects overlap (e.g. they are coplanar);
    3. severe visual artifacts can be tolerated (e.g. as an aggressive constant frame rate strategy);
    4. alternative mechanisms are available to control drawing order, e.g. alphabetical order in the case of named sibling segments or the use of Bring_To_Front() for anything else.
  • z-sort options = [fast|nice]

    A setting of "nice" sorts every transparent triangle in a shell by its mid-point. Alternatively, the "fast" setting sorts the rendering by the mid-point of each tristrip. Unless a shell has color settings on subgeometry (vertices, edges, etc.) a shell will typically have only one tristrip, and so using the "fast" setting usually affords significant (about 2 orders of magnitude) performance improvements over "nice". Because "fast" relies on drawing front and back faces in separate passes, it requires that a polygon handedness other than "none" is set in Set_Heuristics (otherwise, the concept of which faces are facing frontwards or backwards is undefined). The default is "z-sort options = nice".

  • depth peeling options = (option, option, ...)

    Legal options for depth peeling options include:

    • layers = ddd

      The number of transparent layers to process. Hardware support is needed to process more than 1 layer. If the hardware cannot handle multiple layers, only the first layer is rendered. Performance will be roughly linearly proportional to 1/(the number of layers requested). The maximum number of layers that can be set is 8.

    • algorithm = [pixel|buffer]

      "buffer" refers to the legacy depth peeling algorithm. Using this algorithm, you may choose up to 4 depth peeling layers. There is a constant overhead performance cost regardless of the number of objects rendered. This is the default.

      "pixel" applies to shader-based drivers only. With this algorithm, transparency is calculated on a per-pixel basis and the rendering speed depends on the number of transparent pixels in the destination image. If the "layers" option is set to 1, this algorithm will have the same effect as "buffer". Otherwise, the pixel algorithm will ignore the layer setting and use as many layers of depth peeling as is supported by the GPU. However, if the pixel algorithm is requested but is unavailable, Visualize will fall back to "buffer" and use the layers value accordingly.

      Visual results will vary slightly between each algorithm.

    • minimum area = ddd % | ddd pixels

      The amount of the screen a layer needs to occupy in order to process another layer. Hardware occlusion testing support is needed to handle minimum area.

  • [no] depth writing = [on|off]

    Controls whether transparent geometry writes into the z buffer. Applies only when transparency hsra is set to "z sort" or "none", and only when a z buffer is active. This does not eliminate undesirable artifacts that come as a result of the incorrect ordering of geometry that is unavoidable with transparency hsra = none (and in some situations with hsra = z sort). The default value is "no depth writing".

[no] vertex decimation = float

The float value ranges from 0.0 to 1.0 indicating the fraction of the vertices to be drawn. The fraction will be drawn from the front of the points array (assumed to be randomized). The default value is "no vertex decimation".

[no] vertex displacement = [nnn]

This rendering option specifies the number of Z-buffer units that vertices should be pushed away from the camera. This can be used to ensure that vertices are drawn on top of or behind other geometry. The units are 1/2^24 in the normalized depth range [0,1]. Negative values will move vertices toward the camera, positive values away from the camera. The default setting is "no vertex displacement".


You should specify your Rendering Options high enough in the segment tree so they apply to a whole scene at a time. Mixing effects within a single scene might give unpredictable results. The easiest way to do this is to specify Rendering Options on the window segment itself. An exception is "color interpolation" and "color index interpolation". Specify these options as near as you want to the affected geometry, the same applies to attribute locks.

Every possible combination of the options is legal and probably meaningful. For example, it is legal and reasonable to ask that Phong lighting interpolation be computed on a color-interpolated surface.

The default setting of the Rendering Options attribute—the setting on the root ("/") segment—can be given a new initial value on most systems by means of the environment variable "HOOPS_RENDERING_OPTIONS".


Attribute lock: Caution should be exercised when locking modelling matrices if bounding volumes are used. Locks on modelling matrices, but not modelling matrices themselves, are ignored by bounding volumes. This means that a bounding volume accumulates all transformations as it propagates through the segment tree. Due to this restriction, it is advisable to disable bounding volumes when using attribute lock on modelling matrices.

Display Lists: Although using display lists can significantly improve the the rendering performance of your scene, there are a number of limitations associated with enabling this rendering option. The following list describes the limitations and restrictions that exist when the display lists option is set to geometry or segment.

  • LODs are completely disabled whenever segment level display lists are active.
  • View-dependent tessellated curves, arcs, circles and ellipses are not supported. They are only added to display lists when they are configured to be view-independent. This can be set using Set_Rendering_Options as described in the general curve suboption.

    HC_Set_Rendering_Options("nurbs curve = (view-independent)");
  • Most markers are not supported. However, mesh and shell vertices with the ".", "(*)", or "[*]" symbol are supported when using Set_Driver_Options to set "marker drawing = fastest".
  • Grids, text, images, and string cursors are not supported.
  • View-dependent lighting when using the OpenGL driver is not supported unless polygon handedness is defined using Set_Heuristics.
  • Display lists are subject resource availability of the GPU. Display lists can be only be placed on a graphics card if there is enough room in the cache. However, HOOPS Visualize keeps track of the memory budget so that it can fall back to drawing in immediate mode for objects that could not be placed in the display list.
  • The use of display lists can significantly increase the overall memory footprint of an application.

In addition to the above limitiations, please note that Visualize must recompile display lists when geometry is added, removed, or modified. As this is an expensive operation, segment level display lists are not recommended for animated scenes.

Hidden surface removal: The hidden surface removal algorithms still make an occasional mistake. This can be improved by breaking unusually wide, deep, and tall objects into smaller pieces, so that items of geometry in the scene are of similar sizes. This especially improves results in the "z-sort only" rendering option. Furthermore, the face displacement rendering option can also be used to obviate most stitching problems; however, even with face displacement, the painters algorithm can have problems. The painter's algorithm splits triangles independently along their edges, even if those edges are shared. This can lead to phasing errors during scan conversion which manifest as pixel dropouts. We strong advise you to set the hidden surface removal algorithm only on segments with windows with the only exception being if you have subwindows. If you set HSRA on a segment without a window, you will experience unexpected behavior.
Screen Door Transparency: "transparency = screen door" is not valid for software rendering. Although using this option with a non-hardware-accelerated driver will not cause HOOPS Visualize to generate warnings or errors, the picture will most likely look strange.

Shadow Map: Only faces can cast shadows. Thus, primitives like text and lines are not rendered with shadows.
Additionally, objects will not cast shadows if they are at or below a segment that contains one or more of the following:

See also
Set_Driver_Options, Set_Heuristics, Set_Color, Set_Color_By_Value, Set_Color_By_Index, Set_Visibility, Show_Device_Info, Insert_Shell, Insert_Mesh.

◆ UnSet_One_Rendering_Option()

void UnSet_One_Rendering_Option ( const char *  which)

Removes a given setting established by a previous call to Set_Rendering_Options(), rather than all settings.

which- A quoted string or a string variable containing the desired setting to be changed.


No additional details. See Set_Rendering_Options()

◆ UnSet_Rendering_Options()

void UnSet_Rendering_Options ( void  )

Removes all settings established by a previous call to Set_Rendering_Options().


No additional details. See Set_Rendering_Options()