Class SoOffscreenRenderArea
- java.lang.Object
-
- com.openinventor.inventor.Inventor
-
- com.openinventor.inventor.SoOffscreenRenderArea
-
- All Implemented Interfaces:
SafeDisposable
,SiRenderArea
,SiRenderAreaAntialiasing
,SiRenderAreaTransparency
public class SoOffscreenRenderArea extends Inventor implements SiRenderArea, SiRenderAreaAntialiasing, SiRenderAreaTransparency, SafeDisposable
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 theSoSceneManager
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
andSoModifyViewVolumeElement
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 = 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); - Since:
- Open Inventor 10.0
-
-
Nested Class Summary
Nested Classes Modifier and Type Class 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.-
Nested classes/interfaces inherited from class com.openinventor.inventor.Inventor
Inventor.ConstructorCommand
-
Nested classes/interfaces inherited from interface com.openinventor.inventor.viewercomponents.SiRenderArea
SiRenderArea.ClearPolicies, SiRenderArea.RenderEventArg, SiRenderArea.RenderStatus
-
-
Field Summary
Fields Modifier and Type Field Description SbEventHandler<SoOffscreenRenderArea.EventArg>
onTileRendered
Event raised when a tile has been rendered.-
Fields inherited from class com.openinventor.inventor.Inventor
VERBOSE_LEVEL, ZeroHandle
-
-
Constructor Summary
Constructors Constructor 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.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method 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 callSafeDisposable.dispose()
on the object.SbEventHandler<SiRenderArea.RenderEventArg>
onStartRender()
Returns the event handler that raises when a new render starts.SiRenderArea.RenderStatus
render()
Calling therender()
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.-
Methods inherited from class com.openinventor.inventor.Inventor
getNativeResourceHandle
-
-
-
-
Field Detail
-
onTileRendered
public final SbEventHandler<SoOffscreenRenderArea.EventArg> onTileRendered
Event raised when a tile has been rendered.
-
-
Constructor Detail
-
SoOffscreenRenderArea
public SoOffscreenRenderArea(SoGLContext glContex)
Builds a new offscreen render area by sharing the given SoGlContext.
-
SoOffscreenRenderArea
public SoOffscreenRenderArea()
Default constructor. NOTE: An internally createdSoGLContext
will be shared with the current context or an existing one if possible. In order to have control over theSoGLContext
sharing, use the alternate constructor.
-
SoOffscreenRenderArea
public 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.
-
-
Method Detail
-
onStartRender
public SbEventHandler<SiRenderArea.RenderEventArg> onStartRender()
Returns the event handler that raises when a new render starts.- Specified by:
onStartRender
in interfaceSiRenderArea
-
isDisposable
public boolean isDisposable()
Description copied from interface:SafeDisposable
Returns a boolean flag which indicates if it is safe to callSafeDisposable.dispose()
on the object.- Specified by:
isDisposable
in interfaceSafeDisposable
- Returns:
true
if the object can be disposed in a safe manner
-
renderToBuffer
public boolean renderToBuffer(SoBufferObject buffer)
Calls renderToBuffer(buffer, SoOffscreenRenderArea.OutputFormats.valueOf( SoOffscreenRenderArea.OutputFormats.RGB.getValue() )).
-
renderToFile
public boolean renderToFile(java.lang.String filename)
Calls renderToFile(filename, SoOffscreenRenderArea.OutputFormats.valueOf( SoOffscreenRenderArea.OutputFormats.RGB.getValue() )).
-
dispose
public boolean dispose()
Description copied from class:Inventor
Explicitly call this method to force object to dispose its unmanaged resources. The object may not be reused in the application code after this call.- Specified by:
dispose
in interfaceSafeDisposable
- Overrides:
dispose
in classInventor
- Returns:
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.
-
setTransparencyType
public void setTransparencyType(SoGLRenderAction.TransparencyTypes type)
Defines the algorithm for rendering transparent objects. Default is NO_SORT. SeeSoGLRenderAction
for possible transparency types. See alsoSoGLRenderAction.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.
- Specified by:
setTransparencyType
in interfaceSiRenderAreaTransparency
-
getViewportRegion
public SbViewportRegion getViewportRegion()
- See Also:
setViewportRegion()
-
render
public SiRenderArea.RenderStatus render()
Calling therender()
method is useless and does nothing. This function returns always ABORTED.- Specified by:
render
in interfaceSiRenderArea
-
getTransparencyType
public SoGLRenderAction.TransparencyTypes getTransparencyType()
- Specified by:
getTransparencyType
in interfaceSiRenderAreaTransparency
- See Also:
setTransparencyType()
-
setAntialiasingQuality
public void setAntialiasingQuality(float quality)
Define the antialiasing quality value.- Specified by:
setAntialiasingQuality
in interfaceSiRenderAreaAntialiasing
- 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.
-
getSceneManager
public SoSceneManager getSceneManager()
Returns the encapsulated scene manager.
-
getAntialiasingQuality
public float getAntialiasingQuality()
- Specified by:
getAntialiasingQuality
in interfaceSiRenderAreaAntialiasing
- See Also:
setAntialiasingQuality()
-
getMaxTileSize
public static SbVec2i32 getMaxTileSize()
Gets the maximum subimage (tile) size for rendering.
-
setClearPolicy
public void setClearPolicy(SiRenderArea.ClearPolicies policy)
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. . See also setClearColor and setClearDepth.- Specified by:
setClearPolicy
in interfaceSiRenderArea
- Parameters:
policy
- color buffer and depth buffer clear policy.
-
setViewportRegion
public void setViewportRegion(SbViewportRegion newRegion)
Defines viewport region (within the image) to use for rendering.
-
getSceneGraph
public SoNode getSceneGraph()
- Specified by:
getSceneGraph
in interfaceSiRenderArea
- See Also:
setSceneGraph()
-
setSceneGraph
public void setSceneGraph(SoNode newScene)
Defines the scene graph which will be traversed for rendering.- Specified by:
setSceneGraph
in interfaceSiRenderArea
- Parameters:
newScene
- scene graph.
-
getSize
public SbVec2i32 getSize()
- Specified by:
getSize
in interfaceSiRenderArea
- See Also:
setSize()
-
setClearColor
public void setClearColor(SbColorRGBA color)
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 whenrenderToFile()
orrenderToBuffer()
are called withsetClearPolicy()
method set to COLORBUFFER or COLORBUFFER_AND_DEPTHBUFFER . See also setClearPolicy.- Specified by:
setClearColor
in interfaceSiRenderArea
- Parameters:
color
- RGBA value used to clear the color buffer.
-
getClearPolicy
public SiRenderArea.ClearPolicies getClearPolicy()
- Specified by:
getClearPolicy
in interfaceSiRenderArea
- See Also:
setClearPolicy()
-
setGLRenderAction
public void setGLRenderAction(SoGLRenderAction glAction)
Defines the render action used for rendering.
-
getClearDepth
public float getClearDepth()
- Specified by:
getClearDepth
in interfaceSiRenderArea
- See Also:
setClearDepth()
-
setClearDepth
public void setClearDepth(float depth)
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 whenrenderToFile()
orrenderToBuffer()
are called withsetClearPolicy()
method set to DEPTHBUFFER or COLORBUFFER_AND_DEPTHBUFFER . See also setClearPolicy.- Specified by:
setClearDepth
in interfaceSiRenderArea
- Parameters:
depth
- value used to clear the depth buffer. Value is clamped to the range [0,1].
-
setSize
public void setSize(SbVec2i32 size)
Defines the image size to use for rendering.- Specified by:
setSize
in interfaceSiRenderArea
-
getClearColor
public SbColorRGBA getClearColor()
- Specified by:
getClearColor
in interfaceSiRenderArea
- See Also:
setClearColor()
-
setAntialiasingMode
public void setAntialiasingMode(SoSceneManager.AntialiasingModes mode)
Define the antialiasing mode.- Specified by:
setAntialiasingMode
in interfaceSiRenderAreaAntialiasing
- Parameters:
mode
- The antialiasing algorithm. Default is NO_ANTIALIASING which turns off antialiasing.
-
renderToBuffer
public boolean renderToBuffer(SoBufferObject buffer, SoOffscreenRenderArea.OutputFormats outputFormat)
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 anSbRasterImage
using the appropriate constructor. Once instantiated, theSbRasterImage
can be passed as a parameter to the write function of any class inheriting fromSoRasterImageRW
(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 toRGBA
, the alpha component of the rendering is also written to the buffer.
-
getAntialiasingMode
public SoSceneManager.AntialiasingModes getAntialiasingMode()
- Specified by:
getAntialiasingMode
in interfaceSiRenderAreaAntialiasing
- See Also:
setAntialiasingMode()
-
renderToFile
public boolean renderToFile(java.lang.String filename, SoOffscreenRenderArea.OutputFormats outputFormat)
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 toRGBA
, 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 withRGB
components only. See the 3rd column of the above table.
-
getNumEdgePixels
public int getNumEdgePixels()
- See Also:
setTile()
-
getGLRenderAction
public SoGLRenderAction getGLRenderAction()
Returns the render action used for rendering.
-
setTile
public 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. The default tile size is set to the maximum viewport size supported by the hardware (GL_MAX_VIEWPORT_DIMS) and can be queried using thegetMaxTileSize()
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.
-
-