Package com.openinventor.inventor.actions

Class SoGLRenderAction

java.lang.Object
com.openinventor.inventor.Inventor
com.openinventor.inventor.actions.SoAction
com.openinventor.inventor.actions.SoGLRenderAction
Direct Known Subclasses:
SoHighlightRenderAction
public class SoGLRenderAction extends SoAction
Renders a scene graph using Open Inventor's Render Engine. This class renders a scene graph using Open Inventor's render engine. This action traverses a scene graph and queues commands that allow the render engine to render the scene asynchronously. Note that (despite the "historical" name) this class is not dependent on any graphics library and does not directly provide rendering to a window.

The viewer classes, SoWin/SoXt/SoQtExaminerViewer etc, automatically create a render action for you and also expose most of the rendering options for convenience. See also the viewer component classes (SceneExaminer etc).

Traversal order
Nodes from the scene graph are traversed using depth-first traversal. However, traversal of some objects may be delayed, depending on transparency options.

A transparent object is an object:

  • With a material that has a transparency value set either by a material node or a vertex property node.
    or
  • With a texture that has an alpha value < 1.

Open Inventor automatically detects these cases.

The rendering order for transparent objects depends on the transparency "type" (transparency rendering method) assigned to each object. A transparency type may be set for the entire scene graph using the SoGLRenderAction or

invalid reference 
SoWinRenderArea
method.

There are several special cases including:

  • Transparency type SORTED_PIXEL.
    The environment variable OIV_NO_SHADER_LAYERS_BLEND allows you to disable the use of a fragment shader for this technique.
  • SoRenderList nodes, e.g. SoOctreeOrdering.
    Objects that are delayed are generally rendered in the sequence below, but other objects are rendered in various specific orders, not in scene graph order. See the specific node for details.

The general rendering order is:

  1. Scene graph traversal
    All objects not in one of the following categories, specifically including transparent objects using the NO_SORT transparency type.

  2. FastEdit KEEP_ZBUFFER objects
    Objects under an SoSeparator node with fastEditing field set to KEEP_ZBUFFER.

  3. Opaque delayed objects

  4. Transparent delayed objects
    Objects using transparency types OPAQUE_FIRST or SORTED_PIXEL. Note that by default the OpenGL depth buffer is not updated while rendering these objects.

  5. Transparent sorted objects
    Objects using transparency types SORTED_OBJECT These objects are sorted by the distance of their bounding box from the camera, then rendered in back-to-front order. Note that by default the OpenGL depth buffer is not updated while rendering these objects.

  6. Annotation delayed objects
    Objects under an SoAnnotation node.

  7. FastEdit CLEAR_ZBUFFER objects
    Objects under an SoSeparator node with fastEditing field set to CLEAR_ZBUFFER.

Elements
Sets: SoDecimationTypeElement, SoDecimationPercentageElement, SoUpdateAreaElement, SoRenderPassElement, SoViewportRegionElement, SoLogicalViewportElement

Notes & Limitations:

  • Since OpenInventor 10.0, most rendering and caching mechanisms are managed by SoSceneManager, which means that a SoGLRenderAction cannot be used outside of the render() call of SoSceneManager. Hence, manually calling apply() on an SoGLRenderAction can only be done during the traversal of the scene graph, for example inside an SoCallback. Calling apply() outside of this case leads to undefined behavior and will potentially result in incorrect rendering, performance issues, memory leaks and crashes.

See Also:

  • Constructor Details

    • SoGLRenderAction

      public SoGLRenderAction(SbViewportRegion viewportRegion)
      Constructor. The parameter defines the viewport region into which rendering will take place.

  • Method Details

    • setPassCallback

      public void setPassCallback(SoGLRenderPassCB func)

    • setPassCallback

      public void setPassCallback(SoGLRenderPassCB func, Object userData)

    • isSortedLayersSupported

      public static boolean isSortedLayersSupported()
      Calls isSortedLayersSupported((com.openinventor.inventor.misc.SoState)null).

    • setDecimationValue

      public void setDecimationValue(SoDecimationTypeElement.Types type)
      Calls setDecimationValue(type, (float)1.0).

    • handleTransparency

      public boolean handleTransparency()
      Calls handleTransparency(false, false).

    • setFastEditSavePolicy

      public void setFastEditSavePolicy(SoGLRenderAction.FastEditSavePolicies policy)
      Calls setFastEditSavePolicy(policy, false).

    • resetFrameCounter

      public void resetFrameCounter()
      Calls resetFrameCounter((int)0).

    • handleTransparency

      public boolean handleTransparency(boolean isTransparent)
      Calls handleTransparency(isTransparent, false).

    • getUpdateArea

      public SbVec2f[] getUpdateArea()
      Returns the current update area. See setUpdateArea() for details.

    • setTransparencyType

      public void setTransparencyType(SoGLRenderAction.TransparencyTypes type)
      Sets global transparency algorithm to use when rendering. . The default is NO_SORT, but SORTED_PIXEL is recommended for most cases. See also getTransparencyType(). Transparency handling can be completely disabled by setting NO_SORT.

      The global transparency algorithm can also be set using a method in the viewer class (e.g. SoWinRenderArea.setTransparencyType()).

      The default value for this field can be set using the environment variable OIV_TRANSPARENCY_TYPE.

      See SoGLRenderAction.TransparencyType for more discussion about transparency.

      Notes:

      • When using transparency types with DELAYED in the name, the depth buffer is not updated (depth buffer writes are disabled) while rendering transparent objects. As a result complex 3D shapes may not be rendered correctly.
      • When using a delayed transparency mode, paths to transparent objects are saved in a list. After all opaque objects have been rendered, this list is rendered. In order to avoid unnecessary rendering, the common part of each path is rendered only once. This can increase performance on very complex scene graphs. However, in some cases, it can lead to incorrect rendering. In the figure below, node B is a transparent object and node A has a side effect on node B (clipping, shader...). When the compact path optimization is on (the default), node A will not be traversed during the transparency pass, which will lead to incorrect rendering. When a case like this occurs in your scene graph, set the environment variable OIV_USE_COMPACT_PATHS to false to disable this optimization.

    • getTransparencyType

      public SoGLRenderAction.TransparencyTypes getTransparencyType()
      Returns transparency quality level to use when rendering. See setTransparencyType().

    • setFastEditSavePolicy

      public void setFastEditSavePolicy(SoGLRenderAction.FastEditSavePolicies policy, boolean fastEditDelayedObjects)
      Sets fast editing save policy to use when rendering. The default is WHEN_NEEDED. Valid values are DISABLE, EACH_FRAME, and WHEN_NEEDED. See SoSeparator.

      If fastEditDelayedObjects is set to true, delayed objects won't be redrawn when editing the scene graph. It means that the composition between delayed transparent objects and the fast edit scene graph won't be correct, but rendering will be much faster if there are a lot of transparent objects.

    • getRenderingIsRemote

      public boolean getRenderingIsRemote()
      Returns true if remote rendering is being done.

    • isUsedCacheContext

      public static boolean isUsedCacheContext(int context)
      Returns true if the specified cache context id is currently used by any SoGLRenderAction.

    • shouldAutoCache

      public void shouldAutoCache(SoGLRenderAction.AutoCacheModes mode)
      Called by nodes to say that they should/shouldn't be auto-cached (pass true if should, false if shouldn't, don't call this method at all if the node doesn't care):

    • generateCacheContext

      public static int generateCacheContext()
      Generates and returns a new cache context id. The returned cache context id can then be used to pass to the setCacheContext() method call.

    • getFrameCounter

      public int getFrameCounter()
      Returns the current frame counter. The frame counter starts at zero and is automatically incremented each time the action is applied. The frame counter will have the same value throughout a single apply, even if there are multiple render passes, delayed rendering, etc.

    • getDecimationType

      public SoDecimationTypeElement.Types getDecimationType()
      Gets decimation type.

    • resetFrameCounter

      public void resetFrameCounter(int count)
      Reset the frame counter. Do not call this method during a traversal.

    • setInvalidateCacheMode

      public void setInvalidateCacheMode(SoGLRenderAction.InvalidateCacheModes icm)
      Enables or disables the invalidation of render caches.
      • When set to ALWAYS, the caches are invalidated for each SoSeparator node before its children are traversed. No new caches will be built. This value forces all nodes to be visited during each render traversal.
      • When set to ONCE, the caches are invalidated for each SoSeparator node before its children are traversed. The invalidate cache mode is automatically changed to OFF at the end of the traversal.
      • When set to OFF (default), caches are managed by their respective render caching nodes in the usual way.

      This method is useful to force all nodes to be visited during render traversal.

    • getInvalidateCacheMode

      public SoGLRenderAction.InvalidateCacheModes getInvalidateCacheMode()
      Returns the current cache invalidation mode.

    • getDecimationPercentage

      public float getDecimationPercentage()
      Gets decimation percentage, the value should be a number between 0.0 and 1.0.

    • setDecimationValue

      public void setDecimationValue(SoDecimationTypeElement.Types type, float percentage)
      Sets decimation percentage, the value should be a number between 0.0 and 1.0 Useful for reducing the number of triangles rendered in the scene.

    • setLogicalViewportRegion

      public void setLogicalViewportRegion(SbViewportRegion newLogicalRegion)
      Sets current logical viewport region to use for rendering. Setting an empty viewport region (0,0) unsets the logical viewport.

    • getLogicalViewportRegion

      public SbViewportRegion getLogicalViewportRegion()
      Returns current logical viewport region.

    • setUpdateArea

      public void setUpdateArea(SbVec2f origin, SbVec2f size)
      Sets the current update area, which is the rectangular area of the viewport region that will actually be rendered into. This can be used for partial updates in applications that can manage them. The update area is specified in normalized viewport coordinates, where (0,0) is the lower left corner of the viewport and (1,1) is the upper right corner. The area is specified or returned as an origin and a size.

    • setViewportRegion

      public void setViewportRegion(SbViewportRegion newRegion)
      Changes viewport region to use for rendering.

    • getViewportRegion

      public SbViewportRegion getViewportRegion()
      Returns viewport region to use for rendering.

    • handleTransparency

      public boolean handleTransparency(boolean isTransparent, boolean isLinesOrPoints)

    • getNumPasses

      public int getNumPasses()
      Gets number of rendering passes for multipass rendering.

    • setDelayedObjDepthWrite

      public void setDelayedObjDepthWrite(boolean flag)
      Control whether delayed transparent objects update the depth buffer. By default they do not (historical behavior)

    • isPassUpdate

      public boolean isPassUpdate()
      Returns a flag indicating whether intermediate results are displayed after each antialiasing pass for progressive improvement. The default value can be set using the environment variable OIV_ANTIALIAS_PASS_UPDATE.

    • abortNow

      public boolean abortNow()

    • setPassUpdate

      public void setPassUpdate(boolean flag)
      Sets a flag indicating whether intermediate results are displayed after each antialiasing pass for progressive improvement (default is false).

    • setNumPasses

      public void setNumPasses(int num)
      Sets number of rendering passes for multipass antialiasing. The default is 1. Specifying more than one pass will result in antialiasing of the rendered scene, using OpenGL's accumulation buffer. (Camera nodes typically move their viewpoints a little bit for each pass to achieve the antialiasing.) Each additional pass provides better antialiasing, but requires more rendering time.

      The default value can be set using the environment variable OIV_NUM_RENDER_PASSES.

      NOTE: Multipass antialiasing can have very poor performance for large scenes. Full-scene antialiasing (multi-sample) is strongly recommended when the hardware supports it. See SoSceneManager and SoFullSceneAntialiasing.

    • setSmoothing

      @Deprecated(since="101.0.0.0") public void setSmoothing(boolean smooth)
      Deprecated.
      As of Open Inventor 101.0.0.0. No longer used.
      Sets smoothing flag. When on, smoothing uses OpenGL's line- and point-smoothing features to provide cheap antialiasing of lines and points. The default is false.

      The default value can be set using the environment variable OIV_GL_SMOOTHING (0 = false, 1 = true).

      Warning Deprecated since Open Inventor 101000. No longer used.

    • getCache

      public SoCache getCache()
      Returns the cache that has been set with setCache()

    • getFastEditSavePolicy

      public SoGLRenderAction.FastEditSavePolicies getFastEditSavePolicy()
      Returns fast editing save policy used when rendering.

    • getDelayedObjDepthWrite

      public boolean getDelayedObjDepthWrite()
      Returns whether delayed transparent objects update the depth buffer. By default they do not (historical behavior)

    • isSmoothing

      @Deprecated(since="101.0.0.0") public boolean isSmoothing()
      Deprecated.
      As of Open Inventor 101.0.0.0. No longer used.
      Returns smoothing flag.

      Warning Deprecated since Open Inventor 101000. No longer used.

    • setCache

      public void setCache(SoCache cache)
      Sets the main cache to use with this render action. When calling apply() on this action, the SoCacheElement will be set with this cache.

    • setAlphaTest

      public void setAlphaTest(boolean flag)
      Enable or disable the OpenGL alpha test for rendering. Default is false (alpha test disabled) and the default test is "not equal to zero". The alpha test operates on all pixel writes, including those resulting from the scan conversion of points, lines, polygons, and bitmaps, and from pixel draw and copy operations. It does not affect screen clear operations.

      For example, if rendering with textures containing "binary" alpha values (0 or 1), the alpha test may be faster than blended transparency and does not require the use of delayed rendering transparency types.

      The default value can be set using the environment variable OIV_ALPHA_TEST (0 = false, 1 = true).

    • enableElement

      public static void enableElement(Class<? extends Inventor> t, int stkIndex)

    • getSortedLayersNumPasses

      public int getSortedLayersNumPasses()
      Returns the number of rendering passes used when transparency type is SORTED_PIXEL.

    • setRenderingIsRemote

      public void setRenderingIsRemote(boolean flag)
      Sets whether or not "remote" rendering is done. Inventor's auto-render-caching algorithm will choose to cache more often when rendering is remote (the assumption being that performance will be better with display lists stored on the remote machine). By default, it is assumed rendering is NOT remote.

    • isSortedLayersSupported

      public static boolean isSortedLayersSupported(SoState state)
      Indicates if SORTED_PIXEL transparency is supported by your graphics board on the current context.

    • isAlphaTest

      public boolean isAlphaTest()
      Returns whether the OpenGL alpha test is enabled for rendering.

    • isDoingDepthPeeling

      public boolean isDoingDepthPeeling()
      Return true if depth peeling is active.

    • enableDepthPeeling3D

      public void enableDepthPeeling3D(boolean flag)
      Use 3D texturing instead of 2D for the fixed functionality emulation in depth peeling.

    • setCacheContext

      public void setCacheContext(int context)
      Sets the OpenGL cache context. A cache context is just an integer identifying when OpenGL display lists (which are used for render caching) can be shared between render actions; for example, see the documentation on GLX contexts for information on when OpenGL display lists can be shared between GLX windows. See generateCacheContext(). Note: The value 0xFFFFFFFF (~0) is reserved to represent an undefined id.

    • getCurPass

      public int getCurPass()

    • setSortedLayersNumPasses

      public void setSortedLayersNumPasses(int num)
      Sets the number of rendering passes used when transparency type is SORTED_PIXEL. Default is 4.

      Note: Since Open Inventor 9.4, if the hardware supports the necessary OpenGL features, these transparency modes are implemented using a single-pass, order-independent fragment sorting (A-buffer) algorithm. Therefore the value of this field is not used except in two special cases:

      • If hardware support for single pass transparency is not available, then the previous "depth peeling" algorithm is used (which normally requires multiple passes), or
      • If volume rendering (see SoVolumeRender) is combined with geometry rendering, then multiple layers of transparency information are required and this field specifies the number of layers.

      Use more passes for more correct transparency. Usually four passes (which is the default value) gives good results. For example, the number of passes needed for rendering an opaque sphere behind two cubes is the number of planes separating the sphere from the viewer. So, when backface culling is enabled, 2 faces separate the sphere from the viewer: the front face of the first cube and the front face of the second cube. The number of passes needed in this case is 2.

      The default value for this field can be set using the environment variable OIV_NUM_SORTED_LAYERS_PASSES.

    • getDepthPeelingPass

      public int getDepthPeelingPass()
      Get the current pass of depth peeling, -1 if not doing depth peeling.

    • getCacheContext

      public int getCacheContext()
      Returns the OpenGL cache context id for this action.