SoOffscreenRenderArea Class Reference

Render to an off-screen buffer for printing or generating textures. More...

#include <Inventor/SoOffscreenRenderArea.h>

Inheritance diagram for SoOffscreenRenderArea:

Classes
struct	EventArg
	Event that can be sent to the application for each tile rendered. More...

Public Types
enum	OutputFormat {   RGB ,   RGBA }
	Describes the format of the rendering output. More...
Public Types inherited from SiRenderArea
enum	ClearPolicy {   NONE ,   COLORBUFFER ,   DEPTHBUFFER ,   COLORBUFFER_AND_DEPTHBUFFER }
	Policy values to clear color and depth buffers beforing rendering. More...
enum	RenderStatus {   ABORTED ,   INTERACTIVE ,   STILL }
	Returned by the render method. More...

Public Member Functions
	SoOffscreenRenderArea ()
	Default constructor.
	SoOffscreenRenderArea (SoGLContext *glContex)
	Builds a new offscreen render area by sharing the given SoGlContext.
	SoOffscreenRenderArea (SoRenderAreaCore *renderAreaCore)
	Builds a new offscreen render area by using the given renderAreaCore.
	~SoOffscreenRenderArea ()
	Destructor.
virtual void	setSceneGraph (SoNode *newScene)
	Defines the scene graph which will be traversed for rendering.
virtual SoNode *	getSceneGraph () const
void	setViewportRegion (const SbViewportRegion &newRegion)
	Defines viewport region (within the image) to use for rendering.
SbViewportRegion	getViewportRegion () const
virtual void	setTransparencyType (SoGLRenderAction::TransparencyType type)
	Defines the algorithm for rendering transparent objects.
virtual SoGLRenderAction::TransparencyType	getTransparencyType () const
SoSceneManager *	getSceneManager () const
	Returns the encapsulated scene manager.
bool	renderToFile (const SbString &filename, OutputFormat outputFormat=RGB) const
	Render the given scene graph and save the result in the given file.
bool	renderToBuffer (SoBufferObject *buffer, OutputFormat outputFormat=RGB) const
	Render the given scene graph and save the result in the given buffer.
void	setTile (SbVec2i32 size, int numEdgePixels)
	Defines the maximum sub-image (tile) size for rendering and the number of pixels on the border of each sub-image that are not written on the final image.
SbVec2i32	getTileSize () const
int	getNumEdgePixels () const
virtual ClearPolicy	getClearPolicy () const
virtual void	setClearPolicy (ClearPolicy policy)
	Defines the color buffer and depth buffer clear policy.
virtual void	setClearColor (const SbColorRGBA &color)
	Defines the RGBA value used when the color buffer is cleared.
virtual SbColorRGBA	getClearColor () const
virtual void	setClearDepth (float depth)
	Defines the depth value used when the depth buffer is cleared.
virtual float	getClearDepth () const
virtual void	setSize (const SbVec2i32 &size)
	Defines the image size to use for rendering.
virtual SbVec2i32	getSize () const
virtual void	setGLRenderAction (SoGLRenderAction *glAction)
	Defines the render action used for rendering.
virtual SoGLRenderAction *	getGLRenderAction () const
	Returns the render action used for rendering.
virtual SbEventHandler< RenderEventArg & > &	onStartRender ()
	Returns the event handler that raises when a new render starts.
virtual void	setAntialiasingMode (SoSceneManager::AntialiasingMode mode)
	Define the antialiasing mode.
virtual SoSceneManager::AntialiasingMode	getAntialiasingMode () const
virtual void	setAntialiasingQuality (float quality)
	Define the antialiasing quality value.
virtual float	getAntialiasingQuality () const
virtual RenderStatus	render ()
	Calling the render() method is useless and does nothing.
Public Member Functions inherited from SoRefCounter
void	ref () const
	Adds a reference to an instance.
void	unref () const
	Removes a reference from an instance.
void	unrefNoDelete () const
	unrefNoDelete() should be called when it is desired to decrement the reference count, but not delete the instance if this brings the reference count to zero.
int	getRefCount () const
	Returns current reference count.
void	lock () const
	lock this instance.
void	unlock () const
	unlock this instance.

Static Public Member Functions
static SbVec2i32	getMaxTileSize ()
	Gets the maximum subimage (tile) size for rendering.

Public Attributes
SbEventHandler< EventArg & >	onTileRendered
	Event raised when a tile has been rendered.

Detailed Description

Render to an off-screen buffer for printing or generating textures.

This class is used to render a scene graph and to write the the result into a file or a buffer.

This is not a screen capture class. The specified scene graph is rendered to generate an image. This allows generation of images larger (higher resolution) than the user's screen and/or using different (e.g. higher quality) rendering parameters. The offscreen rendering may take more or less time than the same rendering on screen.

The renderer can render very large images because it is able to render the scene as multiple "tiles" and assemble the tiles into a complete image. Of course this requires multiple render traversals of the specified scene graph (one for each tile).

Rendering a "snapshot":

Your application may want to render the same image that the user sees on the screen. There are several things to consider. First, the scene graph given to the renderer must include the camera node that the viewer is using. If the application allows the viewer to create a camera automatically, the scene graph returned by the viewer's getSceneGraph() method does not include the camera. It's always safer to get the SoSceneManager object then get the scene graph. Second, some rendering options are set on the viewer object, not in the scene graph. These options, which include background color and transparency mode, must be explicitly queried from the viewer and set on the renderer object.

Notes & Limitations:

• The default tile size is set to the maximum viewport size supported by the hardware (GL_MAX_VIEWPORT_DIMS), which means that tiling will be enabled only when large viewport sizes are requested.
• When tiling is enabled, the elements SoViewportRegionElement, SoLogicalViewportElement and SoModifyViewVolumeElement are set with different values for each tile, which means that scenegraphs that manage sub-viewports will need to take these elements into account in order for the final rendering to be correct.
• Maximum output image size is 25000 x 25000 pixels.

EXAMPLE

SoOffscreenRenderArea myOffscreen;
// Set the size of the output
myOffscreen.setSize( SbVec2i32( 15360, 8640 ) );
// Set the sceneGraph to render
myOffscreen.setSceneGraph(mySceneGraph);
// If you want to render by tile
if ( tileRendering )
  myOffscreen.setTile(SbVec2i32(3840, 2160), 2);
 
// Specify the color of the clear performed before rendering, here clear with white color
myOffscreen.setClearColor( SbColorRGBA(1.f, 1.f, 1.f, 1.f) );
 
// Save the render as a PNG file
// Specify that we also want to write the alpha component
myOffscreen.renderToFile("result.png", SoOffscreenRenderArea::RGBA);
 
// Or... Save the render in a buffer
myOffscreen.renderToBuffer(myBuffer);

Since Open Inventor 10.0

Definition at line 160 of file SoOffscreenRenderArea.h.

Member Enumeration Documentation

OutputFormat

enum SoOffscreenRenderArea::OutputFormat

Describes the format of the rendering output.

Enumerator
RGB	3 components: red, green and blue
RGBA	4 components: red, green, blue and alpha

Definition at line 230 of file SoOffscreenRenderArea.h.

Constructor & Destructor Documentation

SoOffscreenRenderArea() [1/3]

SoOffscreenRenderArea::SoOffscreenRenderArea

(

)

Default constructor.

NOTE: An internally created SoGLContext will be shared with the current context or an existing one if possible. In order to have control over the SoGLContext sharing, use the alternate constructor.

SoOffscreenRenderArea() [2/3]

SoOffscreenRenderArea::SoOffscreenRenderArea

(

SoGLContext *

glContex

)

Builds a new offscreen render area by sharing the given SoGlContext.

SoOffscreenRenderArea() [3/3]

SoOffscreenRenderArea::SoOffscreenRenderArea

(

SoRenderAreaCore *

renderAreaCore

)

Builds a new offscreen render area by using the given renderAreaCore.

Any following call to setSceneGraph will change the scene graph used by this instance.

~SoOffscreenRenderArea()

SoOffscreenRenderArea::~SoOffscreenRenderArea

(

)

Destructor.

Member Function Documentation

getAntialiasingMode()

virtual SoSceneManager::AntialiasingMode SoOffscreenRenderArea::getAntialiasingMode ( ) const

virtual

See also

setAntialiasingMode().

Implements SiRenderAreaAntialiasing.

getAntialiasingQuality()

virtual float SoOffscreenRenderArea::getAntialiasingQuality ( ) const

virtual

See also

setAntialiasingQuality().

Implements SiRenderAreaAntialiasing.

getClearColor()

virtual SbColorRGBA SoOffscreenRenderArea::getClearColor ( ) const

virtual

See also

setClearColor().

Implements SiRenderArea.

getClearDepth()

virtual float SoOffscreenRenderArea::getClearDepth ( ) const

virtual

See also

setClearDepth().

Implements SiRenderArea.

getClearPolicy()

virtual ClearPolicy SoOffscreenRenderArea::getClearPolicy ( ) const

virtual

See also

setClearPolicy().

Implements SiRenderArea.

getGLRenderAction()

virtual SoGLRenderAction * SoOffscreenRenderArea::getGLRenderAction ( ) const

virtual

Returns the render action used for rendering.

getMaxTileSize()

static SbVec2i32 SoOffscreenRenderArea::getMaxTileSize ( )

static

Gets the maximum subimage (tile) size for rendering.

getNumEdgePixels()

int SoOffscreenRenderArea::getNumEdgePixels

(

)

const

See also

setTile().

getSceneGraph()

virtual SoNode * SoOffscreenRenderArea::getSceneGraph ( ) const

virtual

See also

setSceneGraph().

Implements SiRenderArea.

getSceneManager()

SoSceneManager * SoOffscreenRenderArea::getSceneManager

(

)

const

Returns the encapsulated scene manager.

getSize()

virtual SbVec2i32 SoOffscreenRenderArea::getSize ( ) const

virtual

See also

setSize().

Implements SiRenderArea.

getTileSize()

SbVec2i32 SoOffscreenRenderArea::getTileSize

(

)

const

See also

setTile().

getTransparencyType()

virtual SoGLRenderAction::TransparencyType SoOffscreenRenderArea::getTransparencyType ( ) const

virtual

See also

setTransparencyType().

Implements SiRenderAreaTransparency.

getViewportRegion()

SbViewportRegion SoOffscreenRenderArea::getViewportRegion

(

)

const

See also

setViewportRegion().

onStartRender()

virtual SbEventHandler< RenderEventArg & > & SoOffscreenRenderArea::onStartRender ( )

virtual

Returns the event handler that raises when a new render starts.

Implements SiRenderArea.

render()

virtual RenderStatus SoOffscreenRenderArea::render ( )

virtual

Calling the render() method is useless and does nothing.

This function returns always ABORTED.

Implements SiRenderArea.

renderToBuffer()

bool SoOffscreenRenderArea::renderToBuffer	(	SoBufferObject *	buffer,
		OutputFormat	outputFormat = RGB
	)		const

Render the given scene graph and save the result in the given buffer.

The buffer is resized if its current size is not equal to the the necessary size to store the rendering result.

If your application needs more control over creation of an output file, the SoBufferObject can be converted into an SbRasterImage using the appropriate constructor. Once instantiated, the SbRasterImage can be passed as a parameter to the write function of any class inheriting from SoRasterImageRW (SoJPEGImageRW for example to generate a JPEG file).

Parameters

buffer	stores the result of the rendering.
outputFormat	defines which components to write to the output. If set to RGBA, the alpha component of the rendering is also written to the buffer.

renderToFile()

bool SoOffscreenRenderArea::renderToFile	(	const SbString &	filename,
		OutputFormat	outputFormat = RGB
	)		const

Render the given scene graph and save the result in the given file.

The format of the generated image is chosen automatically according to the file extension. Returns true if successful.

If your application needs more control over creation of the file, please see the renderToBuffer() method.

Supported file types are:

extension file (case insensitive)	raster image type	Alpha Component Support
.bmp	Windows bitmap	YES
.dds	DirectDraw surface	YES
.gif	Graphics Interchange Format	YES
.hdr	hdr	NO
.jp2, .j2c, .j2k, .jpc, .jpx, .ecw, .ecwp	jpeg 2000	YES
.jpg, .jpeg, .jif, .jfif	Joint Photographic Experts Group	NO
.png	Portable Network Graphics	YES
.ps	PostScript	NO
.rgb .sgi	sgi	YES
.tif .tiff	Tagged Image File Format	YES

Parameters

filename	path and name of the image file to be generated. If the file extension is not one of the above type, no file is generated.
outputFormat	defines which components to write to the output. If set to RGBA, the alpha component of the rendering is also written to the file. However if the targeted file type does not support alpha component, the file will be generated with RGB components only. See the 3rd column of the above table.

setAntialiasingMode()

virtual void SoOffscreenRenderArea::setAntialiasingMode ( SoSceneManager::AntialiasingMode  mode )

virtual

Define the antialiasing mode.

Parameters

mode	The antialiasing algorithm. Default is NO_ANTIALIASING which turns off antialiasing.

Implements SiRenderAreaAntialiasing.

setAntialiasingQuality()

virtual void SoOffscreenRenderArea::setAntialiasingQuality ( float  quality )

virtual

Define the antialiasing quality value.

Parameters

quality

The quality is a factor in the range [0.0,1.0]. Default is 0.0. The value 0.0 turns off antialiasing.

Implements SiRenderAreaAntialiasing.

setClearColor()

virtual void SoOffscreenRenderArea::setClearColor ( const SbColorRGBA &  color )

virtual

Defines the RGBA value used when the color buffer is cleared.

Default is transparent black (0,0,0,0). This is the value used to clear the color buffer when renderToFile() or renderToBuffer() are called with setClearPolicy() method set to COLORBUFFER or COLORBUFFER_AND_DEPTHBUFFER . See also setClearPolicy.

Parameters

color

RGBA value used to clear the color buffer.

Implements SiRenderArea.

setClearDepth()

virtual void SoOffscreenRenderArea::setClearDepth ( float  depth )

virtual

Defines the depth value used when the depth buffer is cleared.

The default value is 1. This is the value used to clear the depth buffer when renderToFile() or renderToBuffer() are called with setClearPolicy() method set to DEPTHBUFFER or COLORBUFFER_AND_DEPTHBUFFER . See also setClearPolicy.

Parameters

depth

value used to clear the depth buffer. Value is clamped to the range [0,1].

Implements SiRenderArea.

setClearPolicy()

virtual void SoOffscreenRenderArea::setClearPolicy ( ClearPolicy  policy )

virtual

Defines the color buffer and depth buffer clear policy.

Default value is ClearPolicy::COLORBUFFER_AND_DEPTHBUFFER. Effects such as motion blur can be created by disabling clear color buffer or depth buffer. Use enum ClearPolicy. See also setClearColor and setClearDepth.

Parameters

policy

color buffer and depth buffer clear policy.

Implements SiRenderArea.

setGLRenderAction()

virtual void SoOffscreenRenderArea::setGLRenderAction ( SoGLRenderAction *  glAction )

virtual

Defines the render action used for rendering.

setSceneGraph()

virtual void SoOffscreenRenderArea::setSceneGraph ( SoNode *  newScene )

virtual

Defines the scene graph which will be traversed for rendering.

Implements SiRenderArea.

setSize()

virtual void SoOffscreenRenderArea::setSize ( const SbVec2i32 &  size )

virtual

Defines the image size to use for rendering.

Implements SiRenderArea.

setTile()

void SoOffscreenRenderArea::setTile	(	SbVec2i32	size,
		int	numEdgePixels
	)

Defines the maximum sub-image (tile) size for rendering and the number of pixels on the border of each sub-image that are not written on the final image.

The default tile size is set to the maximum viewport size supported by the hardware (GL_MAX_VIEWPORT_DIMS) and can be queried using the getMaxTileSize() method.

The default value for the number of edge pixels is 2 pixels.

Edge pixels are usually required to avoid visual "artifacts" at the subimage boundaries. One source of artifacts is that when OpenGL clips lines, it draws a line between the points where the line exits and re-enters the visible region. This additional segment is not part of the actual geometry. A two pixel border will hide this undesired segment unless the line width is greater than two, in which case you may need to specify a larger number of edge pixels.

Parameters

size	is dimension of the tile.
numEdgePixels	is the number of pixels on the edge of the tile which will not be included in the final image.

setTransparencyType()

virtual void SoOffscreenRenderArea::setTransparencyType ( SoGLRenderAction::TransparencyType  type )

virtual

Defines the algorithm for rendering transparent objects.

Default is NO_SORT. See SoGLRenderAction for possible transparency types. See also SoGLRenderAction::TransparencyType.

Note: When using OPAQUE_FIRST, SORTED_OBJECT or SORTED_PIXEL transparency, 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.

Implements SiRenderAreaTransparency.

setViewportRegion()

void SoOffscreenRenderArea::setViewportRegion

(

const SbViewportRegion &

newRegion

)

Defines viewport region (within the image) to use for rendering.

Member Data Documentation

onTileRendered

SbEventHandler<EventArg&> SoOffscreenRenderArea::onTileRendered

Event raised when a tile has been rendered.

Definition at line 476 of file SoOffscreenRenderArea.h.

---

The documentation for this class was generated from the following file:

• Inventor/SoOffscreenRenderArea.h