This class is used to render into an off-screen buffer to create a printable image or to generate a texture image. It uses a Pbuffer (if possible) or an off-screen bitmap for rendering. Methods are provided to write the buffer to a file, as an RGB image, an encapsulated PostScript description, or in one of several other image formats.

<font color="#0000FF">NOTE:</font> This class does not exist in Open Inventor 10.0 and later. Replace with SoOffscreenRenderArea.

The renderer can generate images of any size. If the requested image size exceeds OpenGL rendering capabilities, the image will be created by automatically rendering some number of "tiles" and "stitching" them together. See setMaxTileSize for details. Using tiles allows you to create very large, very high resolution images. For example, a poster size image to be printed at 300 dpi would need to be (approximately) 10,000 pixels wide.

The renderer can generate images with a transparent background (as long as there is an OpenGL render format available that supports an alpha buffer). See setBackgroundColorRGBA(). Note that you must also call setComponents() with the parameter set to RGBA (setBackgroundColorRGBA does not do this automatically).

Some output file formats are much more efficient than others at dealing with tiled output. If you anticipate generating very large images, it may be helpful to chose an output format that can generate tiled output efficiently. The formats in the "WRITE_SCANLINES" column in the following table are more efficient at generating tiled output.

Write Capability WRITE_FULL_IMAGE	Write Capability WRITE SCANLINES
BMP JP2 (JPEG2000) PGX PNM SUN	JPEG PNG PS (PostScript) SGIRGB TIFF

For the WRITE_FULL_IMAGE formats, the entire image must be written at once, so a buffer large enough for the whole image is allocated, and tiles are copied into it. Therefore it must be possible to allocate enough memory for a single tile (num_components * tile_width * tile_height) plus enough memory to assemble the complete image (num_components * width * height).

For the WRITE_SCANLINES formats, the image can be written incrementally, some number of scanlines at a time. Therefore it is only necessary to allocate enough memory for a single tile, which at most will be the size of the maximum OpenGL viewport (typically 2048x2048).

See the documentation for SoRasterImageRW and the individual image classes (SoBMPImageRW, SoGIFImageRW, etc.) for further information.

PBuffers Beginning with Open Inventor 3.1, this class will automatically try to use an OpenGL Pbuffer for rendering. If a Pbuffer is available, rendering will be accelerated by the 3D graphics hardware. If no Pbuffer is available, rendering will use a software rendered off-screen buffer as before. Pbuffers are a standard feature of OpenGL 1.2 and are often available as an extension on older versions of OpenGL. However it is not guaranteed that Pbuffers will be available or that a Pbuffer of the desired size can be created.

Rendering with a Pbuffer will generally produce the same image as would be rendered on the screen, but this is not guaranteed. In general, software rendering will produce the same image as on-screen if only OpenGL 1.1 features are used. Newer OpenGL features and extensions will generally not be available using software rendering.

Note that Pbuffers are a limited resource. If the application creates multiple instances of SoOffscreenRenderer, it may be desirable to prevent some of them (that are lower priority or render small scene graphs) from using a Pbuffer. See the method setPbufferEnable().

Rendering contexts The setShareContext method allows you to share an already existing OpenGL context with the offscreen renderer. This avoids the necessity to re-generate textures and display lists if they are already available in another OpenGL context (the viewer context, for instance). This can dramatically reduce offscreen rendering time, depending on your scene graph.

A corresponding query method (#GetShareContext) is also available.

Here's how you might use these methods to share OpenGL contexts:

renderer.SetShareContext( viewer.GetShareContext() );

Rendering a "snapshot" SoOffscreenRenderer is often used to save a snapshot of the image in the viewer window. There are several common pitfalls. 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.

Sample code to make a snapshot, given a viewer object, might look like this:

SoOffscreenRenderer renderer =
 new SoOffscreenRenderer( viewer.GetViewportRegion() );

renderer.SetShareContext( viewer.GetShareContext() );
renderer.SetBackgroundColor( viewer.GetBackgroundColor() );
renderer.GetGLRenderAction().SetTransparencyType( viewer.GetTransparencyType() );

renderer.Render( viewer.GetSceneManager().GetSceneGraph() );

renderer.WriteToPNG( "output.png" );

NOTE: Tiled rendering does not currently work correctly when a camera node's viewportMapping field is set to one of the CROP_ options. It does work correctly with the LEAVE_ALONE and ADJUST_CAMERA (default) settings.

SoOffscreenRenderer is useful because it allows the image size to be specified (e.g. different than the on-screen window) and because it can render images of almost any size (much larger than the physical screen). However it does require an additional render traversal to create the image. For a simple snapshot of an on-screen window it may be more efficient to use the saveSnapshot() method in the So___GLWidget class (e.g. SoWinGLWidget).

Reference