Main Page   Modules   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members  

SoGLRenderAction Class Reference

The SoGLRenderAction class renders the scene graph with OpenGL calls. More...

#include <Inventor/actions/SoGLRenderAction.h>

Inheritance diagram for SoGLRenderAction::

SoAction SoBoxHighlightRenderAction SoLineHighlightRenderAction List of all members.

Public Types

enum  TransparencyType {
  SCREEN_DOOR, ADD, DELAYED_ADD, SORTED_OBJECT_ADD,
  BLEND, DELAYED_BLEND, SORTED_OBJECT_BLEND, SORTED_OBJECT_SORTED_TRIANGLE_ADD,
  SORTED_OBJECT_SORTED_TRIANGLE_BLEND
}
enum  AbortCode { CONTINUE, ABORT, PRUNE, DELAY }

Public Methods

 SoGLRenderAction (const SbViewportRegion &viewportregion)
virtual ~SoGLRenderAction ()
typedef AbortCode SoGLRenderAbortCB (void *userdata)
void setViewportRegion (const SbViewportRegion &newregion)
const SbViewportRegion & getViewportRegion (void) const
void setUpdateArea (const SbVec2f &origin, const SbVec2f &size)
void getUpdateArea (SbVec2f &origin, SbVec2f &size) const
void setAbortCallback (SoGLRenderAbortCB *const func, void *const userdata)
void setTransparencyType (const TransparencyType type)
TransparencyType getTransparencyType (void) const
void setSmoothing (const SbBool smooth)
SbBool isSmoothing (void) const
void setNumPasses (const int num)
int getNumPasses (void) const
void setPassUpdate (const SbBool flag)
SbBool isPassUpdate (void) const
void setPassCallback (SoGLRenderPassCB *const func, void *const userdata)
void setCacheContext (const uint32_t context)
uint32_t getCacheContext (void) const
void addDelayedPath (SoPath *path)
SbBool isRenderingDelayedPaths (void) const
SbBool handleTransparency (SbBool istransparent=FALSE)
int getCurPass (void) const
SbBool abortNow (void)
void setRenderingIsRemote (SbBool isremote)
SbBool getRenderingIsRemote (void) const
virtual void invalidateState (void)
void addPreRenderCallback (SoGLPreRenderCB *func, void *userdata)
void removePreRenderCallback (SoGLPreRenderCB *func, void *userdata)

Static Public Methods

void initClass (void)

Protected Methods

virtual void beginTraversal (SoNode *node)
virtual void endTraversal (SoNode *node)

Detailed Description

The SoGLRenderAction class renders the scene graph with OpenGL calls.

Applying this method at a root node for a scene graph, path or pathlist will render all geometry contained within that instance to the current OpenGL context.

Member Enumeration Documentation

enum SoGLRenderAction::TransparencyType
 

Various settings for how to do rendering of transparent objects in the scene. Some of the settings will provide faster rendering, while others gives you better quality rendering.

Enumeration values:
SCREEN_DOOR   Transparent triangles are rendered with a dither pattern. This is a fast (on most GFX cards) but not-so-high-quality transparency mode.
ADD   Transparent objects are rendered using additive alpha blending. Additive blending is probably mostly used to create special transparency effects. The new pixel color is calculated as the current pixel color plus the source pixel color multiplied with the source pixel alpha value.
DELAYED_ADD   SoGLRenderAction::DELAYED_ADD Transparent objects are rendered using additive alpha blending, in a second rendering pass with depth buffer updates disabled.
SORTED_OBJECT_ADD   SoGLRenderAction::SORTED_OBJECT_ADD Transparent objects are rendered using additive alpha blending. Opaque objects are rendered first, and transparent objects are rendered back to front with z-buffer updates disabled.
BLEND   Transparent objects are rendered using multiplicative alpha blending.

Multiplicative alpha blending is the blending type that is most often used to render transparent objects. The new pixel value is calculated as the old pixel color multiplied with one minus the source alpha value, plus the source pixel color multiplied with the source alpha value.

We recommend that you use this transparency mode if you have only one transparent object in your scene, and you know that it will be rendered after the opaque objects.

DELAYED_BLEND   Transparent objects are rendered using multiplicative alpha blending, in a second rendering pass with depth buffer updates disabled.

Use this transparency type when you have one transparent object, or several transparent object that you know will never overlap (when projected to screen). Since the transparent objects are rendered after opaque ones, you'll not have to worry about putting the transparent objects at the end of your scene graph. It will not be as fast as the BLEND transparency type, of course, since the scene graph is traversed twice.

SORTED_OBJECT_BLEND   Transparent objects are rendered using multiplicative alpha blending, Opaque objects are rendered first, and transparent objects are rendered back to front with z-buffer updates disabled.

Use this transparency mode when you have several transparent object that you know might overlap (when projected to screen). This method will require 1 + num_transparent_objects rendering passes. Path traversal is used when rendering transparent objects, of course, but it might still be slow if you have lots of state changes before your transparent object. When using this mode, we recommend placing the transparent objects as early as possible in the scene graph to minimize traversal overhead.

SORTED_OBJECT_SORTED_TRIANGLE_ADD   This transparency type is a Coin extension versus the Open Inventor API.

Transparent objects are rendered using additive alpha blending, Transparent objects are rendered back to front, and triangles in each object are sorted back to front before rendering.

See description for SORTED_OBJECT_SORTED_TRIANGLE_BLEND for more information about this transparency type.

SORTED_OBJECT_SORTED_TRIANGLE_BLEND   This transparency type is a Coin extension versus the Open Inventor API.

Transparent objects are rendered using multiplicative alpha blending, Transparent objects are rendered back to front, and triangles in each object are sorted back to front before rendering.

Use this transparency type when you have one (or more) transparent object(s) where you know triangles might overlap inside the object. This transparency type might be very slow if you have an object with lots of triangles, since all triangles have to be sorted before rendering, and an unoptimized rendering loop is used when rendering. Lines and points are not sorted before rendering. They are rendered as in the normal SORTED_OBJECT_BLEND transparency type.

Please note that this transparency mode does not guarantee "correct" transparency rendering. It is almost impossible to find an algorithm that will sort triangles correctly in all cases, and intersecting triangles are not handled. Also, since each object is handled separately, two intersecting object will lead to incorrect transparency.

enum SoGLRenderAction::AbortCode
 

The return codes which an SoGLRenderAbortCB callback function should use.

Enumeration values:
CONTINUE   Continue rendering as usual.
ABORT   Abort the rendering action immediately.
PRUNE   Do not render the current node or any of its children, but continue the rendering traversal.
DELAY   Delay rendering of the current node (and its children) until the next rendering pass.

Constructor & Destructor Documentation

SoGLRenderAction::SoGLRenderAction (  const SbViewportRegion & viewportregion ) 
 

Constructor. Sets up the render action for rendering within the given viewportregion.

SoGLRenderAction::~SoGLRenderAction (  )  [virtual]
 

Destructor, frees up all internal resources for action instance.

Member Function Documentation

void SoGLRenderAction::initClass (  void )  [static]
 

Initializes the run-time type system for this class, and sets up the enabled elements and action method list.

Reimplemented from SoAction.

Reimplemented in SoBoxHighlightRenderAction, and SoLineHighlightRenderAction.

typedef SoGLRenderAction::SoGLRenderAbortCB (  void * userdata ) 
 

Abort callbacks should be of this type.

See also:
setAbortCallback()

void SoGLRenderAction::setViewportRegion (  const SbViewportRegion & newregion ) 
 

Sets the viewport region for rendering. This will then override the region passed in with the constructor.

const SbViewportRegion & SoGLRenderAction::getViewportRegion (  void )  const
 

Returns the viewport region for the rendering action.

void SoGLRenderAction::setUpdateArea (  const SbVec2f & origin,
const SbVec2f & size
) 
 

Sets the area of the OpenGL context canvas we should render into.

The coordinates for origin and size should be normalized to be within [0.0, 1.0]. The default settings are <0.0, 0.0> for the origin and <1.0, 1.0> for the size, using the full size of the rendering canvas.

void SoGLRenderAction::getUpdateArea (  SbVec2f & origin,
SbVec2f & size
)  const
 

Returns information about the area of the rendering context window to be updated.

void SoGLRenderAction::setAbortCallback (  SoGLRenderAbortCB *const func,
void *const userdata
) 
 

Sets the abort callback. The abort callback is called by the action for each node during traversal to check for abort conditions.

See also:
SoGLRenderAction::AbortCode

void SoGLRenderAction::setTransparencyType (  const TransparencyType type ) 
 

Sets the transparency rendering method for transparent objects in the scene graph.

See also:
SoGLRenderAction::TransparencyType

SoGLRenderAction::TransparencyType SoGLRenderAction::getTransparencyType (  void )  const
 

Returns the transparency rendering type.

void SoGLRenderAction::setSmoothing (  const SbBool smooth ) 
 

Sets (or unsets) smoothing. If the smoothing flag is on, Coin will try to use built-in features from the OpenGL implementation to smooth the appearance of otherwise jagged borders.

This is a simple (and computationally non-intensive) way of doing anti-aliasing.

Default value for this flag is to be off.

SbBool SoGLRenderAction::isSmoothing (  void )  const
 

Returns whether smoothing is set or not.

void SoGLRenderAction::setNumPasses (  const int num ) 
 

Sets the number of rendering passes. Default is 1, anything greater will enable antialiasing.

int SoGLRenderAction::getNumPasses (  void )  const
 

Returns the number of rendering passes done on updates.

void SoGLRenderAction::setPassUpdate (  const SbBool flag ) 
 

Sets whether each pass should render to screen or not.

SbBool SoGLRenderAction::isPassUpdate (  void )  const
 

Returns the value of the "show intermediate updates" flag.

See also:
setPassUpdate()

void SoGLRenderAction::setPassCallback (  SoGLRenderPassCB *const func,
void *const userdata
) 
 

Sets the pass callback. The callback is called between each rendering pass.

void SoGLRenderAction::setCacheContext (  const uint32_t context ) 
 

Sets the OpenGL cache context key, which is used for deciding when to share OpenGL display lists.

See also:
SoGLCacheContextElement::getUniqueCacheContext()

uint32_t SoGLRenderAction::getCacheContext (  void )  const
 

Returns the cache context key for this rendering action instance.

void SoGLRenderAction::addDelayedPath (  SoPath * path ) 
 

Adds a path to the list of paths to render after the current pass.

SbBool SoGLRenderAction::isRenderingDelayedPaths (  void )  const
 

Returns a flag indicating whether or not we are currently rendering from the list of delayed paths of the scene graph.

SbBool SoGLRenderAction::handleTransparency (  SbBool istransparent = FALSE ) 
 

Used by shape nodes or others which need to know whether or not they should immediately render themselves or if they should wait until the next pass.

int SoGLRenderAction::getCurPass (  void )  const
 

Returns the number of the current rendering pass.

SbBool SoGLRenderAction::abortNow (  void ) 
 

Returns TRUE if the render action should abort now based on user callback.

See also:
setAbortCallback()

void SoGLRenderAction::setRenderingIsRemote (  SbBool isremote ) 
 

Let SoGLRenderAction instance know if application is running on the local machine or if the rendering instructions are sent over the network.

This call has no effect in Coin for now, but eventually it will be used to optimize rendering (the displaylist caching strategy should be influenced by this flag to be more aggressive with the caching when rendering instructions are passed over the network).

See also:
getRenderingIsRemote()

SbBool SoGLRenderAction::getRenderingIsRemote (  void )  const
 

Returns whether or not the application is running remotely.

See also:
setRenderingIsRemote()

void SoGLRenderAction::invalidateState (  void )  [virtual]
 

Overloaded to reinitialize GL state on next apply.

Reimplemented from SoAction.

void SoGLRenderAction::addPreRenderCallback (  SoGLPreRenderCB * func,
void * userdata
) 
 

Adds a callback which is invoked right before the scene graph traversal starts. All necessary GL initialization is then done (e.g. the viewport is correctly set), and this callback can be useful to, for instance, clear the viewport before rendering, or draw a bitmap in the background before rendering etc.

The callback is only invoked once (before the first rendering pass) when multi pass rendering is enabled.

Please note that SoSceneManager usually adds a callback to clear the GL buffers in SoSceneManager::render(). So, if you plan to for instance draw an image in the color buffer using this callback, you should make sure that the scene manager doesn't clear the buffer. This can be done either by calling SoSceneManager::render() with both arguments FALSE, or, if you're using one of our GUI toolkits (SoXt/SoQt/SoGtk/SoWin), call setClearBeforeRender() on the viewer.

This method is an extension versus the Open Inventor API.

See also:
removePreRenderCallback().

void SoGLRenderAction::removePreRenderCallback (  SoGLPreRenderCB * func,
void * userdata
) 
 

Removed a callback added with the addPreRenderCallback() method.

This method is an extension versus the Open Inventor API.

See also:
addPreRenderCallback()

void SoGLRenderAction::beginTraversal (  SoNode * node )  [protected, virtual]
 

This virtual method is called from SoAction::apply(), and is the entry point for the actual scenegraph traversal.

It can be overridden to initialize the action at traversal start, for specific initializations in the action subclasses inheriting SoAction.

Default method just calls traverse(), which any overridden implementation of the method must do too (or call SoAction::beginTraversal()) to trigger the scenegraph traversal.

Reimplemented from SoAction.

void SoGLRenderAction::endTraversal (  SoNode * node )  [protected, virtual]
 

Overloaded from parent class to clean up the lists of objects which were included in the delayed rendering.

Reimplemented from SoAction.

The documentation for this class was generated from the following files:
Generated at Tue Mar 5 03:31:25 2002 for Coin by doxygen1.2.9 written by Dimitri van Heesch, © 1997-2001