SoOffscreenRenderer class Reference

If you want to render to a memory buffer instead of an on-screen OpenGL context, use this class. Rendering to a memory buffer can be used to generate texture maps on-the-fly, or for saving snapshots of the scene to disk files (as pixel bitmaps or as Postscript files for sending to a Postscript-capable printer).

Currently offscreen rendering can be done with GLX (i.e. OpenGL on X11), WGL (i.e. OpenGL on Win32) and AGL (i.e. OpenGL on Mac OS X).

  SoOffscreenRenderer * myRenderer = new SoOffscreenRenderer(vpregion);
  SoNode * root = myViewer->getSceneManager()->getSceneGraph();
  SbBool ok = myRenderer->render(root);
  // [then use image buffer in a texture, or write it to file, or whatever]

Member Enumeration Documentation

enum SoOffscreenRenderer::Components

Enumerated values for the available image formats.

See also:: setComponents()

Constructor & Destructor Documentation

SoOffscreenRenderer::SoOffscreenRenderer

(

const SbViewportRegion &

viewportregion

)

Constructor. Argument is the viewportregion we should use when rendering. An internal SoGLRenderAction will be constructed.

SoOffscreenRenderer::SoOffscreenRenderer

(

SoGLRenderAction *

action

)

Constructor. Argument is the action we should apply to the scene graph when rendering the scene. Information about the viewport is extracted from the action.

Member Function Documentation

float SoOffscreenRenderer::getScreenPixelsPerInch ( void ) [static]

Returns the screen pixels per inch resolution of your monitor.

SbVec2s SoOffscreenRenderer::getMaximumResolution ( void ) [static]

Get maximum dimensions (width, height) of the offscreen buffer.

void SoOffscreenRenderer::setComponents

(

const Components

components

)

Sets the component format of the offscreen buffer.

If set to LUMINANCE, a grayscale image is rendered, LUMINANCE_TRANSPARENCY gives us a grayscale image with transparency, RGB will give us a 24-bit image with 8 bits each for the red, green and blue component, and RGB_TRANSPARENCY yields a 32-bit image (RGB plus transparency).

The default format to render to is RGB.

void SoOffscreenRenderer::setViewportRegion

(

const SbViewportRegion &

region

)

Sets the viewport region.

const SbViewportRegion & SoOffscreenRenderer::getViewportRegion

(

void

)

const

Returns the viewerport region.

void SoOffscreenRenderer::setBackgroundColor

(

const SbColor &

color

)

Sets the background color. The buffer is cleared to this color before rendering.

const SbColor & SoOffscreenRenderer::getBackgroundColor

(

void

)

const

Returns the background color.

void SoOffscreenRenderer::setGLRenderAction

(

SoGLRenderAction *

action

)

Sets the render action. Use this if you have special rendering needs.

SoGLRenderAction * SoOffscreenRenderer::getGLRenderAction

(

void

)

const

Returns the rendering action currently used.

SbBool SoOffscreenRenderer::render

(

SoNode *

scene

)

Render the scenegraph rooted at scene into our internal pixel buffer.

Important note: make sure you pass in a scene node pointer which has both a camera and at least one lightsource below it -- otherwise you are likely to end up with just a blank or black image buffer.

This mistake is easily made if you use an SoOffscreenRenderer on a scenegraph from one of the standard viewer components, as you will often just leave the addition of a camera and a headlight lightsource to the viewer to set up. This camera and lightsource are then part of the viewer's private "super-graph" outside of the scope of the scenegraph passed in by the application programmer. To make sure the complete scenegraph (including the viewer's "private parts" (*snicker*)) are passed to this method, you can get the scenegraph root from the viewer's internal SoSceneManager instance instead of from the viewer's own getSceneGraph() method, like this:

  SoOffscreenRenderer * myRenderer = new SoOffscreenRenderer(vpregion);
  SoNode * root = myViewer->getSceneManager()->getSceneGraph();
  SbBool ok = myRenderer->render(root);
  // [then use image buffer in a texture, or write it to file, or whatever]

If you do this and still get a blank buffer, another common problem is to have a camera which is not actually pointing at the scene geometry you want a snapshot of. If you suspect that could be the cause of problems on your end, take a look at SoCamera::pointAt() and SoCamera::viewAll() to see how you can make a camera node guaranteed to be directed at the scene geometry.

See also:: writeToRGB()

SbBool SoOffscreenRenderer::render

(

SoPath *

scene

)

Render the scene path into our internal memory buffer.

unsigned char * SoOffscreenRenderer::getBuffer

(

void

)

const

Returns the offscreen memory buffer.

SbBool SoOffscreenRenderer::writeToRGB

(

FILE *

)

const

Writes the buffer in SGI RGB format by appending it to the already open file. Returns FALSE if writing fails.

Important note: do not use this method when the Coin library has been compiled as an MSWindows DLL, as passing FILE* instances back or forth to DLLs is dangerous and will most likely cause a crash. This is an intrinsic limitation for MSWindows DLLs.

SbBool SoOffscreenRenderer::writeToPostScript

(

FILE *

)

const

Writes the buffer in Postscript format by appending it to the already open file. Returns FALSE if writing fails.

SbBool SoOffscreenRenderer::writeToPostScript	(	FILE *	fp,

		const SbVec2f &	printsize
	)	const

Writes the buffer to a file in Postscript format, with printsize dimensions.

SbBool SoOffscreenRenderer::writeToRGB

(

const char *

filename

)

const

Opens a file with the given name and writes the offscreen buffer in SGI RGB format to the new file. If the file already exists, it will be overwritten (if permitted by the filesystem).

Returns TRUE if all went ok, otherwise FALSE.

SbBool SoOffscreenRenderer::writeToPostScript

(

const char *

filename

)

const

Opens a file with the given name and writes the offscreen buffer in Postscript format to the new file. If the file already exists, it will be overwritten (if permitted by the filesystem).

Returns TRUE if all went ok, otherwise FALSE.

SbBool SoOffscreenRenderer::writeToPostScript	(	const char *	filename,

		const SbVec2f &	printsize
	)	const

Opens a file with the given name and writes the offscreen buffer in Postscript format with printsize dimensions to the new file. If the file already exists, it will be overwritten (if permitted by the filesystem).

Returns TRUE if all went ok, otherwise FALSE.

SbBool SoOffscreenRenderer::isWriteSupported

(

const SbName &

filetypeextension

)

const

Returns TRUE if the buffer can be saved as a file of type filetypeextension, using SoOffscreenRenderer::writeToFile(). This function needs simage v1.1 or newer.

Examples of possibly supported extensions are: "jpg", "png", "tiff", "gif", "bmp", etc. The extension match is not case sensitive.

Which formats are actually supported depends on the capabilities of Coin's support library for handling import and export of pixel-data files: the simage library. If the simage library is not installed on your system, no extension output formats will be supported.

Also, note that it is possible to build and install a simage library that lacks support for most or all of the file formats it is capable of supporting. This is so because the simage library depends on other, external 3rd party libraries -- in the same manner as Coin depends on the simage library for added file format support.

The two built-in formats that are supported through the SoOffscreenRenderer::writeToRGB() and SoOffscreenRenderer::writeToPostScript() methods (for SGI RGB format and for Adobe Postscript files, respectively) are not considered by this method, as those two formats are guaranteed to always be supported through those functions.

So if you want to be guaranteed to be able to export a screenshot in your wanted format, you will have to use either one of the above mentioned method for writing SGI RGB or Adobe Postscript directly, or make sure the Coin library has been built and is running on top of a version of the simage library (that you have preferably built yourself) with the file format you want known to have been included.

This method is an extension versus the original SGI Open Inventor API.

See also:: getNumWriteFiletypes(), getWriteFiletypeInfo(), writeToFile()

int SoOffscreenRenderer::getNumWriteFiletypes

(

void

)

const

Returns the number of available exporters. Detailed information about the exporters can then be found using getWriteFiletypeInfo().

See SoOffscreenRenderer::isWriteSupported() for information about which file formats you can expect to be present.

Note that the two built-in export formats (SGI RGB and Adobe Postscript) are not counted.

This method is an extension versus the original SGI Open Inventor API.

See also:: getWriteFiletypeInfo()

void SoOffscreenRenderer::getWriteFiletypeInfo	(	const int	idx,

		SbList< SbName > &	extlist,

		SbString &	fullname,

		SbString &	description
	)

Returns information about an image exporter. extlist is a list of filenameextensions for a file format. E.g. for JPEG it is legal to use both jpg and jpeg. fullname is the full name of the image format. description is an optional string with more information about the file format.

See SoOffscreenRenderer::isWriteSupported() for information about which file formats you can expect to be present.

This method is an extension versus the original SGI Open Inventor API.

See also:: getNumWriteFiletypes(), writeToFile()

SbBool SoOffscreenRenderer::writeToFile	(	const SbString &	filename,

		const SbName &	filetypeextension
	)	const

Saves the buffer to filename, in the filetype specified by filetypeextensions.

This method is an extension versus the orignal SGI Open Inventor API.

See also:: isWriteSupported()

Public Types
enum	Components { LUMINANCE = 1, LUMINANCE_TRANSPARENCY = 2, RGB = 3, RGB_TRANSPARENCY = 4 }
Public Methods
	SoOffscreenRenderer (const SbViewportRegion &viewportregion)
	SoOffscreenRenderer (SoGLRenderAction *action)
	~SoOffscreenRenderer ()
void	setComponents (const Components components)
Components	getComponents (void) const
void	setViewportRegion (const SbViewportRegion &region)
const SbViewportRegion &	getViewportRegion (void) const
void	setBackgroundColor (const SbColor &color)
const SbColor &	getBackgroundColor (void) const
void	setGLRenderAction (SoGLRenderAction *action)
SoGLRenderAction *	getGLRenderAction (void) const
SbBool	render (SoNode *scene)
SbBool	render (SoPath *scene)
unsigned char *	getBuffer (void) const
SbBool	writeToRGB (FILE *fp) const
SbBool	writeToPostScript (FILE *fp) const
SbBool	writeToPostScript (FILE *fp, const SbVec2f &printsize) const
SbBool	writeToRGB (const char *filename) const
SbBool	writeToPostScript (const char *filename) const
SbBool	writeToPostScript (const char *filename, const SbVec2f &printsize) const
SbBool	isWriteSupported (const SbName &filetypeextension) const
int	getNumWriteFiletypes (void) const
void	getWriteFiletypeInfo (const int idx, SbList< SbName > &extlist, SbString &fullname, SbString &description)
SbBool	writeToFile (const SbString &filename, const SbName &filetypeextension) const
Static Public Methods
float	getScreenPixelsPerInch (void)
SbVec2s	getMaximumResolution (void)

SoOffscreenRenderer Class Reference

Public Types

Public Methods

Static Public Methods

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation