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.updateEyePose(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 and Description
static interface	StereoDeviceRenderer.Eye Interface describing one eye of the stereoscopic device, see getEye(int).

Field Summary

Fields

Modifier and Type	Field and 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 EyePose movement to reduce latency.
static int	DISTORTION_VIGNETTE Distortion Bit: Vignette distortion compensating lens chromatic aberration.

Method Summary

Methods

Modifier and Type	Method and 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	getSingleSurfaceSize() Returns the unified surface size of one eye's a single image in pixel units.
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().
EyePose	updateEyePose(int eyeNum) Updates the StereoDeviceRenderer.Eye.getLastEyePose() for the denoted eyeNum.
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 EyePose 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.

updateEyePose

EyePose updateEyePose(int eyeNum)

Updates the StereoDeviceRenderer.Eye.getLastEyePose() for the denoted eyeNum.

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.

getSingleSurfaceSize

DimensionImmutable getSingleSurfaceSize()

Returns the unified surface size of one 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 getSingleSurfaceSize(), side-by-side.

Otherwise the size is equal to getSingleSurfaceSize().

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().

updateEyePose(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 -