public class SoOffscreenRenderArea extends Inventor implements SiRenderArea, SiRenderAreaAntialiasing, SiRenderAreaTransparency, SafeDisposable
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:
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.
SoOffscreenRenderArea myOffscreen = new SoOffscreenRenderArea(); // Set the size of the output myOffscreen.setSize( new SbVec2i32( 15360, 8640 ) ); // Set the sceneGraph to render myOffscreen.setSceneGraph(mySceneGraph); // If you want to render by tile if ( tileRendering ) myOffscreen.setTile(new SbVec2i32(3840, 2160), 2); // Specify the color of the clear performed before rendering, here clear with white color myOffscreen.setClearColor( new 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.OutputFormats.RGBA); // Save the render in a buffer myOffscreen.renderToBuffer(myBuffer);
Modifier and Type | Class and Description |
---|---|
static class |
SoOffscreenRenderArea.EventArg
Event that can be sent to the application for each tile rendered.
|
static class |
SoOffscreenRenderArea.OutputFormats
Describes the format of the rendering output.
|
Inventor.ConstructorCommand
SiRenderArea.ClearPolicies, SiRenderArea.RenderEventArg, SiRenderArea.RenderStatus
Modifier and Type | Field and Description |
---|---|
SbEventHandler<SoOffscreenRenderArea.EventArg> |
onTileRendered
Event raised when a tile has been rendered.
|
VERBOSE_LEVEL, ZeroHandle
Constructor and Description |
---|
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.
|
Modifier and Type | Method and Description |
---|---|
boolean |
dispose()
Explicitly call this method to force object to dispose its unmanaged
resources.
|
SoSceneManager.AntialiasingModes |
getAntialiasingMode() |
float |
getAntialiasingQuality() |
SbColorRGBA |
getClearColor() |
float |
getClearDepth() |
SiRenderArea.ClearPolicies |
getClearPolicy() |
SoGLRenderAction |
getGLRenderAction()
Returns the render action used for rendering.
|
static SbVec2i32 |
getMaxTileSize()
Gets the maximum subimage (tile) size for rendering.
|
int |
getNumEdgePixels() |
SoNode |
getSceneGraph() |
SoSceneManager |
getSceneManager()
Returns the encapsulated scene manager.
|
SbVec2i32 |
getSize() |
SbVec2i32 |
getTileSize() |
SoGLRenderAction.TransparencyTypes |
getTransparencyType() |
SbViewportRegion |
getViewportRegion() |
boolean |
isDisposable()
Returns a boolean flag which indicates if it is safe to call
SafeDisposable.dispose() on the object. |
SbEventHandler<SiRenderArea.RenderEventArg> |
onStartRender()
Returns the event handler that raises when a new render starts.
|
SiRenderArea.RenderStatus |
render()
Calling the
render() method is useless and does nothing. |
boolean |
renderToBuffer(SoBufferObject buffer)
Calls renderToBuffer(buffer, SoOffscreenRenderArea.OutputFormats.valueOf( SoOffscreenRenderArea.OutputFormats.RGB.getValue() )).
|
boolean |
renderToBuffer(SoBufferObject buffer,
SoOffscreenRenderArea.OutputFormats outputFormat)
Render the given scene graph and save the result in the given buffer.
|
boolean |
renderToFile(java.lang.String filename)
Calls renderToFile(filename, SoOffscreenRenderArea.OutputFormats.valueOf( SoOffscreenRenderArea.OutputFormats.RGB.getValue() )).
|
boolean |
renderToFile(java.lang.String filename,
SoOffscreenRenderArea.OutputFormats outputFormat)
Render the given scene graph and save the result in the given file.
|
void |
setAntialiasingMode(SoSceneManager.AntialiasingModes mode)
Define the antialiasing mode.
|
void |
setAntialiasingQuality(float quality)
Define the antialiasing quality value.
|
void |
setClearColor(SbColorRGBA color)
Defines the RGBA value used when the color buffer is cleared.
|
void |
setClearDepth(float depth)
Defines the depth value used when the depth buffer is cleared.
|
void |
setClearPolicy(SiRenderArea.ClearPolicies policy)
Defines the color buffer and depth buffer clear policy.
|
void |
setGLRenderAction(SoGLRenderAction glAction)
Defines the render action used for rendering.
|
void |
setSceneGraph(SoNode newScene)
Defines the scene graph which will be traversed for rendering.
|
void |
setSize(SbVec2i32 size)
Defines the image size to use for rendering.
|
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.
|
void |
setTransparencyType(SoGLRenderAction.TransparencyTypes type)
Defines the algorithm for rendering transparent objects.
|
void |
setViewportRegion(SbViewportRegion newRegion)
Defines viewport region (within the image) to use for rendering.
|
getNativeResourceHandle
public final SbEventHandler<SoOffscreenRenderArea.EventArg> onTileRendered
public SoOffscreenRenderArea(SoGLContext glContex)
public SoOffscreenRenderArea()
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.public SoOffscreenRenderArea(SoRenderAreaCore renderAreaCore)
public SbEventHandler<SiRenderArea.RenderEventArg> onStartRender()
onStartRender
in interface SiRenderArea
public boolean isDisposable()
SafeDisposable
SafeDisposable.dispose()
on the object.isDisposable
in interface SafeDisposable
true
if the object can be disposed in a safe mannerpublic boolean renderToBuffer(SoBufferObject buffer)
public boolean renderToFile(java.lang.String filename)
public boolean dispose()
Inventor
dispose
in interface SafeDisposable
dispose
in class Inventor
true
if this object native resources were successfully
disposed; false
if it was already disposed or no
native resources has been registered for this object.public void setTransparencyType(SoGLRenderAction.TransparencyTypes type)
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.
setTransparencyType
in interface SiRenderAreaTransparency
public SbViewportRegion getViewportRegion()
setViewportRegion()
public SiRenderArea.RenderStatus render()
render()
method is useless and does nothing.
This function returns always ABORTED.render
in interface SiRenderArea
public SoGLRenderAction.TransparencyTypes getTransparencyType()
getTransparencyType
in interface SiRenderAreaTransparency
setTransparencyType()
public void setAntialiasingQuality(float quality)
setAntialiasingQuality
in interface SiRenderAreaAntialiasing
quality
- The quality is a factor in the range [0.0,1.0]. public SoSceneManager getSceneManager()
public float getAntialiasingQuality()
getAntialiasingQuality
in interface SiRenderAreaAntialiasing
setAntialiasingQuality()
public static SbVec2i32 getMaxTileSize()
public void setClearPolicy(SiRenderArea.ClearPolicies policy)
setClearPolicy
in interface SiRenderArea
policy
- color buffer and depth buffer clear policy.public void setViewportRegion(SbViewportRegion newRegion)
public SoNode getSceneGraph()
getSceneGraph
in interface SiRenderArea
setSceneGraph()
public void setSceneGraph(SoNode newScene)
setSceneGraph
in interface SiRenderArea
newScene
- scene graph.public SbVec2i32 getSize()
getSize
in interface SiRenderArea
setSize()
public void setClearColor(SbColorRGBA color)
renderToFile()
or renderToBuffer()
are called with setClearPolicy()
method set to COLORBUFFER or COLORBUFFER_AND_DEPTHBUFFER . See also setClearPolicy.
setClearColor
in interface SiRenderArea
color
- RGBA value used to clear the color buffer.public SiRenderArea.ClearPolicies getClearPolicy()
getClearPolicy
in interface SiRenderArea
setClearPolicy()
public void setGLRenderAction(SoGLRenderAction glAction)
public float getClearDepth()
getClearDepth
in interface SiRenderArea
setClearDepth()
public void setClearDepth(float depth)
renderToFile()
or renderToBuffer()
are called with setClearPolicy()
method set to DEPTHBUFFER or COLORBUFFER_AND_DEPTHBUFFER . See also setClearPolicy.
setClearDepth
in interface SiRenderArea
depth
- value used to clear the depth buffer. Value is clamped to the range [0,1].public void setSize(SbVec2i32 size)
setSize
in interface SiRenderArea
public SbColorRGBA getClearColor()
getClearColor
in interface SiRenderArea
setClearColor()
public void setAntialiasingMode(SoSceneManager.AntialiasingModes mode)
setAntialiasingMode
in interface SiRenderAreaAntialiasing
mode
- The antialiasing algorithm. Default is NO_ANTIALIASING which turns off antialiasing.public boolean renderToBuffer(SoBufferObject buffer, SoOffscreenRenderArea.OutputFormats outputFormat)
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).
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.public SoSceneManager.AntialiasingModes getAntialiasingMode()
getAntialiasingMode
in interface SiRenderAreaAntialiasing
setAntialiasingMode()
public boolean renderToFile(java.lang.String filename, SoOffscreenRenderArea.OutputFormats outputFormat)
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 |
.pgx | pgx | NO |
.png | Portable Network Graphics | YES |
.pnm .pgm .ppm | pnm | YES |
.ps | PostScript | NO |
.rgb .sgi | sgi | YES |
.ras | sun | YES |
.tif .tiff | Tagged Image File Format | YES |
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.public int getNumEdgePixels()
setTile()
public SoGLRenderAction getGLRenderAction()
public void setTile(SbVec2i32 size, int numEdgePixels)
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.
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.Generated on December 23, 2020, Copyright © Thermo Fisher Scientific. All rights reserved. http://www.openinventor.com