com.openinventor.inventor.mpeg

Class SoMPEGRenderer

java.lang.Object

com.openinventor.inventor.Inventor

com.openinventor.inventor.mpeg.SoMPEGRenderer

Direct Known Subclasses:

SoMPEGFrameRenderer, SoMPEGNavRenderer

public class SoMPEGRenderer
extends Inventor

Base class for generating MPEG output from a scene graph. This class is the base class for creating MPEG video output from a scene graph. Two specialized classes SoMPEGFrameRenderer and SoMPEGNavRenderer are provided to give applications more control over video generation.

Warning : Writing in multiple streams at the same time is not possible.

This class is used by the viewer classes to record MPEG video (see for example the SoWinRenderArea method setMPEGRecorder ). The default right-mouse popup menu in the viewer classes provides an option to display a video recording dialog box. This dialog allows the user to conveniently start and stop recording the scene in the viewer window.

The setShareContext method allows you to share an existing OpenGL context with the MPEG 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.

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

 SoMPEGRenderer renderer = new SoMPEGRenderer();
 renderer.setShareContext( viewer.getArea().getGLSharedContext() );

The MPEGRender uses two separate tasks. One to record rendered frames and one to encode the frames in MPEG format (this is a much slower task). If the recording task is stopped, the encoding one can continue. If openFile is called before the end of this task, two scenarios can occur. If the filename is the same file as the one currently in use by the encoding task, this task is stopped. The behavior is the same if record is called after stop . If the filename is different, the file is not opened and encoding continues.

It is important to note that the MPEGRenderer can only generate raw MPEG-1 video streams. In order for the generated video to be played correctly by any video player, it needs to be embedded into a container. This operation can be easily performed by the multimedia tool FFmpeg. For example, the following command allows you to embed the generated raw video stream into an MP4 container format:

 ffmpeg -i input_raw_stream.mpg -codec copy output_video.mp4

The -codec copy argument is important because it allows ffmpeg to only copy the input stream inside the container instead of doing a real re-encoding.

Different container formats can also be used, like AVI or MKV.

See also:

SoMPEGNavRenderer, SoMPEGFrameRenderer

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SoMPEGRenderer.Components Components.

Nested classes/interfaces inherited from class com.openinventor.inventor.Inventor

Inventor.ConstructorCommand

Field Summary

Fields

Modifier and Type	Field and Description
static int	LUMINANCE Deprecated. Use SoMPEGRenderer.Components.LUMINANCE instead.
static int	LUMINANCE_TRANSPARENCY Deprecated. Use SoMPEGRenderer.Components.LUMINANCE_TRANSPARENCY instead.
static int	RGB Deprecated. Use SoMPEGRenderer.Components.RGB instead.
static int	RGB_TRANSPARENCY Deprecated. Use SoMPEGRenderer.Components.RGB_TRANSPARENCY instead.

Fields inherited from class com.openinventor.inventor.Inventor

VERBOSE_LEVEL, ZeroHandle

Constructor Summary

Constructors

Constructor and Description
SoMPEGRenderer() Constructor.

Method Summary

Modifier and Type	Method and Description
void	addFrame(byte[] frame) Low level method to add a new frame to the MPEG output from a buffer of unsigned characters.
void	closeFile() Closes the MPEG file previously opened with the openFile() method.
SbColor	getBackgroundColor() Gets the background color for rendering each frame.
SoMPEGRenderer.Components	getComponents() Returns the number of color components of the frames recorded.
float	getCompressionRate() Returns the compression rate.
SoGLRenderAction	getGLRenderAction() Gets the GL Render action used to generate each frame.
int	getNumFramesPerSecond() Gets the number of frames per second to be encoded in the MPEG output.
SoNode	getSceneGraph() Gets the scene graph used for generating frames in the MPEG output.
SbGLShareContext	getShareContext() Gets the OpenGL context shared by the SoOffscreenRenderer.
SbVec2s	getSize() Gets the frame pixel size.
boolean	isRecording() Returns true if this renderer is recording.
boolean	isViewerIdle()
boolean	openFile(java.lang.String filename) Calls openFile(filename, (int)10000).
boolean	openFile(java.lang.String filename, int numFrames) Specifies the MPEG output file name.
void	pause() Pauses the recording.
void	record() Starts the recording.
void	setBackgroundColor(SbColor c) Sets the background color for rendering each frame.
void	setBitPerSec(float mbps) This method allows the user to specify a fixed bit rate.
void	setComponents(SoMPEGRenderer.Components components) Set the number of color components of the frames recorded.
void	setCompressionRate(float value) Compression rate of the MPEG output.
void	setGLRenderAction(SoGLRenderAction ra) Sets the GL Render action used to generate each frame.
void	setNumFramesPerSecond(float num) Sets the number of frames per second encoded in the MPEG output.
void	setSceneGraph(SoNode node) Sets the scene graph used for generating frames in the MPEG output.
void	setShareContext(SbGLShareContext shareCxt) Sets the OpenGL context to be shared by the SoMPEGRenderer.
void	setSize(SbVec2s size) Sets the frame pixel size.
void	setViewerIsIdle(boolean isIdle) Tells the recorder that the viewer is idle.
void	stop() Stops the recording and closes the opened file.

Methods inherited from class com.openinventor.inventor.Inventor

dispose, getAddress, getNativeResourceHandle, startInternalThreads, stopInternalThreads

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LUMINANCE

@Deprecated
public static final int LUMINANCE

Deprecated. Use SoMPEGRenderer.Components.LUMINANCE instead.

LUMINANCE_TRANSPARENCY

@Deprecated
public static final int LUMINANCE_TRANSPARENCY

Deprecated. Use SoMPEGRenderer.Components.LUMINANCE_TRANSPARENCY instead.

RGB

@Deprecated
public static final int RGB

Deprecated. Use SoMPEGRenderer.Components.RGB instead.

RGB_TRANSPARENCY

@Deprecated
public static final int RGB_TRANSPARENCY

Deprecated. Use SoMPEGRenderer.Components.RGB_TRANSPARENCY instead.

Constructor Detail

SoMPEGRenderer

public SoMPEGRenderer()

Constructor.

Method Detail

openFile

public boolean openFile(java.lang.String filename)

Calls openFile(filename, (int)10000).

getSize

public SbVec2s getSize()

Gets the frame pixel size. These values may be different from those given by the setSize() method.

setSize

public void setSize(SbVec2s size)

Sets the frame pixel size. The width and height of the frame must be a multiple of 16. If they are not, they are reduced to the next lower multiple of 16.

By default, width and height values are 96.

NOTE: This method must be called before openFile or setFilePointer in order to have an effect. Calling it after calling openFile or setFilePointer may cause undesirable results.

stop

public void stop()

Stops the recording and closes the opened file.

isRecording

public boolean isRecording()

Returns true if this renderer is recording.

setViewerIsIdle

public void setViewerIsIdle(boolean isIdle)

Tells the recorder that the viewer is idle.

closeFile

public void closeFile()

Closes the MPEG file previously opened with the openFile() method.

openFile

public boolean openFile(java.lang.String filename,
                        int numFrames)

Specifies the MPEG output file name. numFrames gives an estimate of the number of frames that the MPEG output will contain.

If filename is the same as the one currently in use by the encoding task (if there is one), the encoding task is stopped. If the filename is different, the file is not opened and the current encoding task continues.

Returns false if the file cannot be opened, true otherwise.

isViewerIdle

public boolean isViewerIdle()

setComponents

public void setComponents(SoMPEGRenderer.Components components)

Set the number of color components of the frames recorded.

setGLRenderAction

public void setGLRenderAction(SoGLRenderAction ra)

Sets the GL Render action used to generate each frame. If no render action is specified, an internal instance of an SoGLRenderAction will be maintained with a viewport region set to the size given with the method setSize().

setNumFramesPerSecond

public void setNumFramesPerSecond(float num)

Sets the number of frames per second encoded in the MPEG output. It has nothing to do with the speed of playback. The default value is 30.

NOTE: This method must be called before openFile or setFilePointer in order to have an effect. Calling it after calling openFile or setFilePointer may cause undesirable results.

getBackgroundColor

public SbColor getBackgroundColor()

Gets the background color for rendering each frame.

getNumFramesPerSecond

public int getNumFramesPerSecond()

Gets the number of frames per second to be encoded in the MPEG output.

setCompressionRate

public void setCompressionRate(float value)

Compression rate of the MPEG output. Values are between 0 and 1. 0=no compression, 1=maximum compression.

The default value is 0.3.

NOTE: This method must be called before openFile or setFilePointer in order to have an effect. Calling it after calling openFile or setFilePointer may cause undesirable results.

getCompressionRate

public float getCompressionRate()

Returns the compression rate.

getGLRenderAction

public SoGLRenderAction getGLRenderAction()

Gets the GL Render action used to generate each frame.

setBitPerSec

public void setBitPerSec(float mbps)

This method allows the user to specify a fixed bit rate. This is useful when the MPEG output is to be put on a video CD, for example. If you do not know what this rate means, you can use the default value (-1) which indicates that the bit rate is variable. The standards bit rates for VCD are 1205862 bps and 2726300 bps. (It is the speed the MPEG stream is read by VCD players)

The default value is 1205862. The maximum value is 104857600. NOTE: This method must be called before openFile or setFilePointer in order to have an effect. Calling it after calling openFile or setFilePointer may cause undesirable results.

addFrame

public void addFrame(byte[] frame)

Low level method to add a new frame to the MPEG output from a buffer of unsigned characters. Each pixel is stored sequentially by scanline, starting with the lower left corner. The data stored for each pixel is determined by the components set before rendering (3 by default). Pixels are stored in RGBA order and are packed without any padding between pixels or scanlines.

record

public void record()

Starts the recording. If called directly after stop method, the current encoding task (if one) is stopped.

Note: A file must have been opened or a file pointer set.

setSceneGraph

public void setSceneGraph(SoNode node)

Sets the scene graph used for generating frames in the MPEG output.

pause

public void pause()

Pauses the recording.

getComponents

public SoMPEGRenderer.Components getComponents()

Returns the number of color components of the frames recorded.

setShareContext

public void setShareContext(SbGLShareContext shareCxt)

Sets the OpenGL context to be shared by the SoMPEGRenderer. Its use is strongly recommended, because it can improve performance when switching between on-screen and off-screen rendering. This is because it allows the display lists and texture objects to be shared between the on-screen and off-screen render context. The shared context info is normally obtained by calling the viewer's getShareContext method.

NOTE: It has no effect when the hardware (or driver) does not allow sharing with the off-screen context, for example if Pbuffers are not supported.

setBackgroundColor

public void setBackgroundColor(SbColor c)

Sets the background color for rendering each frame. The default background color is 0 0 0 (black).

The default value can be set using the environment variable OIV_BACKGROUND_COLOR. Specify three floats (R, G, B) in the range 0. to 1., separated by spaces.

getShareContext

public SbGLShareContext getShareContext()

Gets the OpenGL context shared by the SoOffscreenRenderer.

getSceneGraph

public SoNode getSceneGraph()

Gets the scene graph used for generating frames in the MPEG output.