C++ Java Unity
Java Reference
RenderingPrimitives Class Reference

Detailed Description

Provides low-level information and tools for rendering AR and VR content.

RenderingPrimitives provides a set of unified function calls that are designed to work across all AR/VR display devices, including hand-held, head-mounted (monocular/stereo) and wearable mobile devices.

This means that you can write a single common rendering loop and have it work across multiple output platforms, AR or VR, mono and stereo, with a minimum of device-specific or context-specific code required.

A valid RenderingPrimitives instance can only be obtained from the Device singleton instance after:

The transformation measurement unit used is the same as the one used to define the target size (usually meters).

Public Member Functions

boolean equals (Object obj)
 
 RenderingPrimitives (RenderingPrimitives other)
 Copy constructor. More...
 
ViewList getRenderingViews ()
 Get the set of VIEWs available for rendering from these primitives. More...
 
Vec4I getViewport (int viewID)
 Get the viewport for a particular VIEW. More...
 
Vec4F getNormalizedViewport (int viewID)
 Get the normalized viewport for a particular VIEW. More...
 
Matrix34F getProjectionMatrix (int viewID, CameraCalibration cameraCalibration, boolean adjustForViewportCentreToEyeAxis)
 Get a projection matrix for rendering content for the specified VIEW. More...
 
Matrix34F getProjectionMatrix (int viewID, CameraCalibration cameraCalibration)
 Get a projection matrix for rendering content for the specified VIEW. More...
 
Vec4F getEffectiveFov (int viewID)
 Get the effective field of view for the specified VIEW. More...
 
Vec2F getViewportCentreToEyeAxis (int viewID)
 Get any skew adjustments that need to be applied to the projection matrix before rendering. More...
 
Matrix34F getEyeDisplayAdjustmentMatrix (int viewID)
 Get a matrix that can correct rendering to account for the offset of the eye from the central rendering position. More...
 
Vec2I getVideoBackgroundTextureSize ()
 Get the size of a texture that can be used to render the video background. More...
 
Matrix34F getVideoBackgroundProjectionMatrix (int viewID, boolean adjustForViewportCentreToEyeAxis)
 Get a projection matrix to use when rendering the video frame as a background image for the augmentation. More...
 
Matrix34F getVideoBackgroundProjectionMatrix (int viewID)
 Get a projection matrix to use when rendering the video frame as a background image for the augmentation. More...
 
Mesh getVideoBackgroundMesh (int viewID)
 Get a simple mesh suitable for use when rendering the video frame as a background image. More...
 
Vec2I getDistortionTextureSize (int viewID)
 Get the size of a texture that can be used to render undistorted content for stereo applications. More...
 
Vec4I getDistortionTextureViewport (int viewID)
 Get the viewport for the given VIEW to use when rendering the distortion mesh. More...
 
Mesh getDistortionTextureMesh (int viewID)
 Get a distortion mesh for the given view. More...
 

Constructor & Destructor Documentation

Copy constructor.

Member Function Documentation

boolean equals ( Object  obj)
ViewList getRenderingViews ( )

Get the set of VIEWs available for rendering from these primitives.

In the most common use case (handheld AR on a mobile device), the returned ViewList will contain just a single entry, VIEW::VIEW_SINGULAR.

In other use cases (such as stereo head-mounted AR or VR) the returned ViewList may contain multiple entries: typically VIEW::VIEW_LEFTEYE, VIEW::VIEW_RIGHTEYE and VIEW::VIEW_POSTPROCESS.

For see-through AR, the list will typically contain VIEW::VIEW_LEFTEYE and VIEW::VIEW_RIGHTEYE.

Vec4I getViewport ( int  viewID)

Get the viewport for a particular VIEW.

The returned vector describes the starting position, width, and height of the area where content for the given viewID should be rendered, in screen coordinates (i.e. pixels).

Parameters
viewIDThe VIEW you want a viewport for
Returns
The viewport for the given View in the format (x, y, width, height) in screen coordinates (i.e. pixels).
Vec4F getNormalizedViewport ( int  viewID)

Get the normalized viewport for a particular VIEW.

The returned vector describes the starting position, width, and height of the area where content for the given viewID should be rendered, in normalized coordinates (i.e. all values are in the range 0..1).

Parameters
viewIDThe VIEW you want a viewport for.
Returns
The normalized viewport for the given View in the format (x, y, width, height) where all values are in the range 0..1.
Matrix34F getProjectionMatrix ( int  viewID,
CameraCalibration  cameraCalibration,
boolean  adjustForViewportCentreToEyeAxis 
)

Get a projection matrix for rendering content for the specified VIEW.

Note: The returned matrix is row-major. For OpenGL, you will need to convert the matrix to column-major using one of the functions in Tool (typically Tool::convertPerspectiveProjection2GLMatrix).

Note: In AR mode, the returned projection matrix will also include a user interface orientation transform.

Parameters
viewIDThe VIEW you want a projection matrix for.
cameraCalibrationCamera calibration details, or NULL. Typically, you should pass in camera calibration returned from State::getCameraCalibration(). If NULL, the camera calibration calculated when this RenderingPrimitives instance was constructed will be used.
adjustForViewportCentreToEyeAxisIf true, apply skew offsets (see getViewportCentreToEyeAxis) for VIEW::VIEW_LEFTEYE and VIEW::VIEW_RIGHTEYE.
Returns
A 3x4 row-major projection matrix (use conversion functions in the Tool class, if necessary, to convert the matrix for use with OpenGL).
Matrix34F getProjectionMatrix ( int  viewID,
CameraCalibration  cameraCalibration 
)

Get a projection matrix for rendering content for the specified VIEW.

Note: The returned matrix is row-major. For OpenGL, you will need to convert the matrix to column-major using one of the functions in Tool (typically Tool::convertPerspectiveProjection2GLMatrix).

Note: In AR mode, the returned projection matrix will also include a user interface orientation transform.

Parameters
viewIDThe VIEW you want a projection matrix for.
cameraCalibrationCamera calibration details, or NULL. Typically, you should pass in camera calibration returned from State::getCameraCalibration(). If NULL, the camera calibration calculated when this RenderingPrimitives instance was constructed will be used.
Returns
A 3x4 row-major projection matrix (use conversion functions in the Tool class, if necessary, to convert the matrix for use with OpenGL).
Vec4F getEffectiveFov ( int  viewID)

Get the effective field of view for the specified VIEW.

The effective FOV is calculated based on the screen size and the viewer hardware's maximum FOV, as configured via Device::selectViewer(). Note that this will vary according to the host device and viewer.

This function will only return meaningful data for VIEW::VIEW_LEFTEYE and VIEW::VIEW_RIGHTEYE, and only when a viewer profile has been configured via Device::selectViewer().

Parameters
viewIDThe VIEW you want the Field-of-View for. Only VIEW::VIEW_LEFTEYE or VIEW::VIEW_RIGHTEYE will return meaningful results.
Returns
Field-of-View half-angles {left, right, bottom, top}, in radians, as measured from the eye axis.
Vec2F getViewportCentreToEyeAxis ( int  viewID)

Get any skew adjustments that need to be applied to the projection matrix before rendering.

The skew adjustment values should be used to modify the left/right eye projection matrices to ensure that the eye axis is aligned with the centre of the viewport.

Note: In AR mode, the returned projection matrix will also include a user interface orientation transform.

Note: If you call getProjectionMatrix() or getVideoBackgroundProjectionMatrix() with the adjustForViewportCentreToEyeAxis parameter set to true, it is not necessary to call this function as the skew adjustments have already been applied to the matrix.

Parameters
viewIDThe VIEW you want skew adjustments for (typically VIEW::VIEW_LEFTEYE or VIEW::VIEW_RIGHTEYE).
Returns
Skew adjustments (ie the offset of the eye axis relative to the centre of the viewport), normalised to the extents of the viewport (i.e. in the range -1..1).
Matrix34F getEyeDisplayAdjustmentMatrix ( int  viewID)

Get a matrix that can correct rendering to account for the offset of the eye from the central rendering position.

The returned matrix should be applied to the pose matrix of any tracked object during rendering.

The matrix is specified in meters. If your scene is defined in another unit you will need to adjust the matrix (by scaling the offset parameters) before applying it to your scene.

Note that when working with OpenGL, this matrix will need be converted to column-major format using Tool::convert2GLMatrix().

Parameters
viewIDThe VIEW you want an adjustment matrix for (typically VIEW::VIEW_LEFTEYE or VIEW::VIEW_RIGHTEYE).
Returns
The row-major eye/display adjustment matrix to use for the given VIEW (use the conversion functions in the Tool class if required convert to an OpenGL-compatible matrix).
Vec2I getVideoBackgroundTextureSize ( )

Get the size of a texture that can be used to render the video background.

Note that the returned size may be larger than the video background itself (for example when a power-of-two texture size is required for performance).

Returns
The size that the video background texture needs to be.
Matrix34F getVideoBackgroundProjectionMatrix ( int  viewID,
boolean  adjustForViewportCentreToEyeAxis 
)

Get a projection matrix to use when rendering the video frame as a background image for the augmentation.

Note that when working with OpenGL, this matrix will need be converted to column-major format using Tool::convert2GLMatrix().

Parameters
viewIDThe VIEW you want a video background projection matrix for.
adjustForViewportCentreToEyeAxisIf true, apply skew offsets (
See also
getViewportCentreToEyeAxis).
Returns
A 3x4 row-major projection matrix (use Tool::convert2GLMatrix() to convert to column-major format for OpenGL).
Matrix34F getVideoBackgroundProjectionMatrix ( int  viewID)

Get a projection matrix to use when rendering the video frame as a background image for the augmentation.

Note that when working with OpenGL, this matrix will need be converted to column-major format using Tool::convert2GLMatrix().

Parameters
viewIDThe VIEW you want a video background projection matrix for.
See also
getViewportCentreToEyeAxis).
Returns
A 3x4 row-major projection matrix (use Tool::convert2GLMatrix() to convert to column-major format for OpenGL).
Mesh getVideoBackgroundMesh ( int  viewID)

Get a simple mesh suitable for use when rendering the video frame as a background image.

The returned mesh has dimensions and texture coordinates that are suitable for rendering a distortion-free camera frame in the requested VIEW, compensating for any discrepancies between the camera and viewport size and aspect ratio.

The mesh should be rendered as a textured mesh, in combination with the projection matrix returned by getVideoBackgroundProjectionMatrix(), using the video frame image as a texture.

Note: If you intend to apply your own distortion to the video background, you may need to construct a finer triangle mesh (based on this mesh), in order to avoid rendering artefacts.

Parameters
viewIDThe VIEW you want the mesh for.
Returns
A mesh to use when rendering the video frame as a background image.
Vec2I getDistortionTextureSize ( int  viewID)

Get the size of a texture that can be used to render undistorted content for stereo applications.

This function returns the recommended size for the texture that should be applied to the distortion mesh, in order to minimise visual artefacts resulting from the barrel distortion process.

Parameters
viewIDThe VIEW to return the recommended texture size for (typically VIEW::VIEW_POSTPROCESS).
Returns
The recommended texture size for the distortion texture.
Vec4I getDistortionTextureViewport ( int  viewID)

Get the viewport for the given VIEW to use when rendering the distortion mesh.

The returned vector describes the starting position, width, and height of the area where content for the given viewID should be rendered, in coordinates referencing into the distortion texture.

Parameters
viewIDThe VIEW you want a viewport for (typically VIEW::VIEW_POSTPROCESS).
Returns
The viewport for the given VIEW in the format (x, y, width, height) in distortion texture coordinates.
Mesh getDistortionTextureMesh ( int  viewID)

Get a distortion mesh for the given view.

When working with certain types of head-mounted display, visual content will need to be distorted to account for the optics of the display.

This function returns a barrel distortion mesh to perform this distortion. It should be rendered as a textured mesh using the distortion texture.

Parameters
viewIDThe VIEW you want a distortion mesh for (typically VIEW::VIEW_POSTPROCESS).
Returns
A barrel distortion mesh that should be rendered as a textured mesh using the distortion texture.