HC_Set_Rendering_Options
-
void HC_Set_Rendering_Options(char const *list)
- “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.
\brief Allows you to control how carefully and accurately your scene is drawn, and to enable several special drawing effects.
- 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
- DETAILS
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
hitherandyonplane values, the color is calculated asatmospheric 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.
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.[no] value adjustment [= none | normalized | explicit = (scale [= fff], translate [= fff])]
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:
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”.level = [ entity | segment | segment tree ]
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%”.tolerance = xxx[%]
[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 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.
xxxandyyyshould be floating point values such that0 <= 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).
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]
[no] continued budget [= xxx]
[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]
invert polycylinders = [on | [no] radii, [no] colors]
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
dim factor = [fff]
face displacement = [fff]
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]
pattern = [ddd]
LP_DOTTEDin patterns.h.)remove duplicate lines = [on/off]
render faces = [on/off]
render text = [on|off]
rendered face sorting algorithm = [none/painters/z-sort/szb/hzb]
silhouette cleanup = [on/off]
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 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.
Limitations:
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 use ‘*’ 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, but 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 in 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.
Limitations
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
[no] bounding = current | (minx, miny, minz, maxx, maxy, maxz)
[no] calculation usefulness cutoff = (xxx,xxx,xxx,xxx…)
[no] clamp = [xxx]
[no] collapse duplicate vertices
fallback = none | bounding | coarsest bounding | coarsest none
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 ]
[no] max degree [=xxx]
[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]
ratio = xxx[, xxx, xxx, xxx, …]
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]
usefulness heuristic = [type]
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]
maximum facet deviation = xxx [1]
maximum facet angle = xxx [20]
maximum facet width = xxx [1.42]
trim budget = xxx [500]
maximum trim curve deviation = xxx [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
[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
samples = xxx
[no] view dependent [ = on | off]
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 additional information.
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
[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]
fading = (on/off)
opacity = fff
plane = (a, b, c, d)
visibility = visibility_spec
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
opacity = fff
plane=(a, b, c, d)
light=(i,j,k)
resolution = x
blurring = y
color = color_spec
[no] ignore transparencies = on/off
Ignores any segment level transparency setting when rendering the simple shadow. The default is “ignore
transparencies=off”.
fast 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]
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
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:
The “texture interpolation” rendering option is enabled.
The shell or mesh to be textured has vertex parameters specified (with MSet_Vertex_Parameters() ).
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 ]
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:
“style=screen door” - screen door transparency does not require sorting, so “screen door” automatically implies that sorting will be disabled;
extra information is known about the data to indicate that no two transparent objects overlap (e.g. they are coplanar);
severe visual artifacts can be tolerated (e.g. as an aggressive constant frame rate strategy);
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.
There is a constant overhead performance cost regardless of the number of objects rendered. This is the default.<li>algorithm = [pixel|buffer] <p>"buffer" refers to the legacy depth peeling algorithm. Using this algorithm, you may choose up to 4 depth peeling layers.
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.<p>"pixel" applies to shader-based drivers only. With this algorithm, transparency is calculated on a per-pixel basis and the
needed to handle minimum area.<p>Visual results will vary slightly between each algorithm.</p> <li>minimum area = ddd % | ddd pixels <p>The amount of the screen a layer needs to occupy in order to process another layer. Hardware occlusion testing support is
[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.
- NOTES
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.
- RESTRICTIONS
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:
camera
See also
HC_Set_Driver_Options, HC_Set_Heuristics, HC_Set_Color, HC_Set_Color_By_Value, HC_Set_Color_By_Index, HC_Set_Visibility, HC_Show_Device_Info, HC_Insert_Shell, HC_Insert_Mesh.
- Parameters
list – - A quoted string or a string variable containing a list of the desired settings.
