Package com.jogamp.opengl.util.stereo

Interface StereoDeviceRenderer

public interface StereoDeviceRenderer

Stereoscopic device rendering interface.

The following pseudo-code describes how to implement a renderer using a StereoDeviceRenderer. See StereoClientRenderer which implements the following:

• device.beginFrame(GL)
• For both eyes:
  • device.#updateViewerPose(int)
  • if device.ppAvailable(): Set the render target, e.g. FBO
  • Set the viewport using StereoDeviceRenderer.Eye.getViewport()
  • upstream.reshapeEye(..)
  • upstream.display(..).
• Reset the viewport
• If device.ppAvailable():
  • device.ppBegin(GL)
  • Use render target, e.g. FBO's texture
  • device.#ppBothEyes(GL) or device.ppOneEye(GL, int) for both eyes
  • device.ppEnd(GL)
• device.endFrame(GL)

Correct Asymmetric FOV Rendering

The StereoClientRenderer shall render both images for each eye correctly Off-axis utilizing an asymmetric camera frustum, i.e. by using StereoDevice's default FovHVHalves.
Some references:

• Wiki: Binocular Vision
• Paul Burke: Stereo Graphics - Stereo Renderer
• Wiki: Distortion (Optics)

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	StereoDeviceRenderer.Eye	Interface describing one eye of the stereoscopic device, see getEye(int).

Field Summary

Fields

Modifier and Type	Field	Description
static int	DISTORTION_BARREL	Distortion Bit: Barrel distortion compensating lens pincushion distortion
static int	DISTORTION_CHROMATIC	Distortion Bit: Chromatic distortion compensating lens chromatic aberration.
static int	DISTORTION_TIMEWARP	Distortion Bit: Timewarp distortion technique to predict ViewerPose movement to reduce latency.
static int	DISTORTION_VIGNETTE	Distortion Bit: Vignette distortion compensating lens chromatic aberration.

Method Summary

Modifier and Type	Method	Description
void	beginFrame(GL gl)	Notifying that a new frame is about to start.
void	dispose(GL gl)	Release all OpenGL related resources
void	endFrame(GL gl)	Notifying that the frame has been rendered completely.
StereoDevice	getDevice()	Returns the StereoDevice of this StereoDeviceRenderer instance.
int	getDistortionBits()	Returns used distortion compensation bits, e.g.
StereoDeviceRenderer.Eye	getEye(int eyeNum)	Returns the StereoDeviceRenderer.Eye instance for the denoted eyeNum.
DimensionImmutable[]	getEyeSurfaceSize()	Returns the surface size for each eye's a single image in pixel units.
ViewerPose	getLastViewerPose()	Returns the last ViewerPose.
int	getTextureCount()	Returns the used texture-image count for post-processing, see ppAvailable().
int	getTextureUnit()	Returns the desired texture-image unit for post-processing, see ppAvailable().
DimensionImmutable	getTotalSurfaceSize()	Returns the total surface size required for the complete images in pixel units.
void	init(GL gl)	Initialize OpenGL related resources
boolean	ppAvailable()	Returns true if stereoscopic post-processing is required and available, otherwise false.
void	ppBegin(GL gl)	Begin stereoscopic post-processing, see ppAvailable().
void	ppEnd(GL gl)	End stereoscopic post-processing, see ppAvailable().
void	ppOneEye(GL gl, int eyeNum)	Performs stereoscopic post-processing for one eye, see ppAvailable().
ViewerPose	updateViewerPose()	Updates the ViewerPose and returns it.
boolean	usesSideBySideStereo()	Method returns true if using side-by-side (SBS) stereoscopic images, otherwise false.

Field Detail

DISTORTION_BARREL

static final int DISTORTION_BARREL

Distortion Bit: Barrel distortion compensating lens pincushion distortion

See Also:

Constant Field Values

DISTORTION_CHROMATIC

static final int DISTORTION_CHROMATIC

Distortion Bit: Chromatic distortion compensating lens chromatic aberration.

See Also:

Constant Field Values

DISTORTION_VIGNETTE

static final int DISTORTION_VIGNETTE

Distortion Bit: Vignette distortion compensating lens chromatic aberration.

See Also:

Constant Field Values

DISTORTION_TIMEWARP

static final int DISTORTION_TIMEWARP

Distortion Bit: Timewarp distortion technique to predict ViewerPose movement to reduce latency.

FIXME: Explanation needs refinement!

See Also:

Constant Field Values

Method Detail

getDevice

StereoDevice getDevice()

Returns the StereoDevice of this StereoDeviceRenderer instance.

getEye

StereoDeviceRenderer.Eye getEye(int eyeNum)

Returns the StereoDeviceRenderer.Eye instance for the denoted eyeNum.

updateViewerPose

ViewerPose updateViewerPose()

Updates the ViewerPose and returns it.

getLastViewerPose

ViewerPose getLastViewerPose()

Returns the last ViewerPose.

getDistortionBits

int getDistortionBits()

Returns used distortion compensation bits, e.g. DISTORTION_BARREL, in case the stereoscopic display requires such, i.e. in case lenses are utilized.

Distortion requires post-processing.

usesSideBySideStereo

boolean usesSideBySideStereo()

Method returns true if using side-by-side (SBS) stereoscopic images, otherwise false.

SBS requires that both eye's images are presented side-by-side in the final framebuffer.

Either the renderer presents the images side-by-side according to the eye's viewport, or post-processing is utilized to merge textures to a side-by-side configuration.

getEyeSurfaceSize

DimensionImmutable[] getEyeSurfaceSize()

Returns the surface size for each eye's a single image in pixel units.

getTotalSurfaceSize

DimensionImmutable getTotalSurfaceSize()

Returns the total surface size required for the complete images in pixel units.

If usesSideBySideStereo() the total size spans over both getEyeSurfaceSize(), side-by-side.

Otherwise the size is equal to getEyeSurfaceSize().

getTextureCount

int getTextureCount()

Returns the used texture-image count for post-processing, see ppAvailable().

In case the renderer does not support multiple textures for post-processing, or no post-processing at all, method returns zero despite the request from StereoDevice#createRenderer(int, int, float[], com.jogamp.opengl.math.FovHVHalves[], float).

getTextureUnit

int getTextureUnit()

Returns the desired texture-image unit for post-processing, see ppAvailable().

init

void init(GL gl)

Initialize OpenGL related resources

dispose

void dispose(GL gl)

Release all OpenGL related resources

beginFrame

void beginFrame(GL gl)

Notifying that a new frame is about to start.

endFrame

void endFrame(GL gl)

Notifying that the frame has been rendered completely.

ppAvailable

boolean ppAvailable()

Returns true if stereoscopic post-processing is required and available, otherwise false.

Stereoscopic post-processing is available if:

• one of the distortion bits are set, see getDistortionBits()

If stereoscopic post-processing is used the following post-processing methods must be called to before #endFrame():

• ppBegin(GL)
• ppOneEye(GL, int) for both eyes
• ppEnd(GL)

ppBegin

void ppBegin(GL gl)

Begin stereoscopic post-processing, see ppAvailable().

#updateViewerPose(int) for both eyes must be called upfront when rendering upstream StereoGLEventListener.

Parameters:

gl -

ppOneEye

void ppOneEye(GL gl,
              int eyeNum)

Performs stereoscopic post-processing for one eye, see ppAvailable().

Parameters:

gl -

eyeNum -

ppEnd

void ppEnd(GL gl)

End stereoscopic post-processing, see ppAvailable().

Parameters:

gl -