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

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