Stereo Frustum API module

Contents

After you create a stereo viewport, you will need to get a handle for that viewport's stereo frustum. Although your application can have multiple viewports, each one has a single stereo frustum.

Classes

union ZCFrustumBounds
Union representing frustum bounds.

Enums

enum ZCEye { ZC_EYE_LEFT = 0, ZC_EYE_RIGHT = 1, ZC_EYE_CENTER = 2 }
enum ZCFrustumAttribute { ZC_FRUSTUM_ATTRIBUTE_IPD = 0x00000000, ZC_FRUSTUM_ATTRIBUTE_VIEWER_SCALE = 0x00000001, ZC_FRUSTUM_ATTRIBUTE_HEAD_SCALE = 0x00000003, ZC_FRUSTUM_ATTRIBUTE_NEAR_CLIP = 0x00000004, ZC_FRUSTUM_ATTRIBUTE_FAR_CLIP = 0x00000005, ZC_FRUSTUM_ATTRIBUTE_GLASSES_OFFSET = 0x00000006, ZC_FRUSTUM_ATTRIBUTE_CC_LIMIT = 0x00000007, ZC_FRUSTUM_ATTRIBUTE_UC_LIMIT = 0x00000008, ZC_FRUSTUM_ATTRIBUTE_CU_LIMIT = 0x00000009, ZC_FRUSTUM_ATTRIBUTE_UU_LIMIT = 0x0000000A, ZC_FRUSTUM_ATTRIBUTE_CC_DEPTH = 0x0000000B, ZC_FRUSTUM_ATTRIBUTE_UC_DEPTH = 0x0000000C, ZC_FRUSTUM_ATTRIBUTE_DISPLAY_ANGLE_X = 0x0000000D, ZC_FRUSTUM_ATTRIBUTE_DISPLAY_ANGLE_Y = 0x0000000E, ZC_FRUSTUM_ATTRIBUTE_DISPLAY_ANGLE_Z = 0x0000000F, ZC_FRUSTUM_ATTRIBUTE_AUTO_STEREO_DELAY = 0x00000010, ZC_FRUSTUM_ATTRIBUTE_AUTO_STEREO_DURATION = 0x00000011, ZC_FRUSTUM_ATTRIBUTE_AUTO_STEREO_ENABLED = 0x00010000 }
enum ZCPortalMode { ZC_PORTAL_MODE_NONE = 0x00000000, ZC_PORTAL_MODE_ANGLE = 0x00000001, ZC_PORTAL_MODE_POSITION = 0x00000002, ZC_PORTAL_MODE_ALL = 0xFFFFFFFF }

Typedefs

using ZCEye = enum ZCEye
using ZCFrustumAttribute = enum ZCFrustumAttribute
using ZCPortalMode = enum ZCPortalMode
using ZCFrustumBounds = union ZCFrustumBounds
Union representing frustum bounds.

Functions

auto zcGetFrustum(ZCHandle viewportHandle, ZCHandle* frustumHandle) -> ZCError
auto zcSetFrustumAttributeF32(ZCHandle frustumHandle, ZCFrustumAttribute attribute, ZSFloat value) -> ZCError
auto zcGetFrustumAttributeF32(ZCHandle frustumHandle, ZCFrustumAttribute attribute, ZSFloat* value) -> ZCError
auto zcSetFrustumAttributeB(ZCHandle frustumHandle, ZCFrustumAttribute attribute, ZSBool value) -> ZCError
auto zcGetFrustumAttributeB(ZCHandle frustumHandle, ZCFrustumAttribute attribute, ZSBool* value) -> ZCError
auto zcSetFrustumPortalMode(ZCHandle frustumHandle, ZSInt32 portalModeFlags) -> ZCError
auto zcGetFrustumPortalMode(ZCHandle frustumHandle, ZSInt32* portalModeFlags) -> ZCError
auto zcSetFrustumCameraOffset(ZCHandle frustumHandle, const ZSVector3* cameraOffset) -> ZCError
auto zcGetFrustumCameraOffset(ZCHandle frustumHandle, ZSVector3* cameraOffset) -> ZCError
auto zcSetFrustumHeadPose(ZCHandle frustumHandle, const ZCTrackerPose* headPose) -> ZCError
auto zcGetFrustumHeadPose(ZCHandle frustumHandle, ZCTrackerPose* headPose) -> ZCError
auto zcGetFrustumViewMatrix(ZCHandle frustumHandle, ZCEye eye, ZSMatrix4* viewMatrix) -> ZCError
auto zcGetFrustumProjectionMatrix(ZCHandle frustumHandle, ZCEye eye, ZSMatrix4* projectionMatrix) -> ZCError
auto zcGetFrustumBounds(ZCHandle frustumHandle, ZCEye eye, ZCFrustumBounds* bounds) -> ZCError
auto zcGetFrustumEyePosition(ZCHandle frustumHandle, ZCEye eye, ZCCoordinateSpace coordinateSpace, ZSVector3* eyePosition) -> ZCError
auto zcGetFrustumCoupledBoundingBox(ZCHandle frustumHandle, ZCBoundingBox* boundingBox) -> ZCError
auto zcCalculateFrustumFit(ZCHandle frustumHandle, const ZCBoundingBox* boundingBox, ZSFloat* viewerScale, ZSMatrix4* lookAtMatrix) -> ZCError
auto zcCalculateFrustumDisparity(ZCHandle frustumHandle, const ZSVector3* point, ZSFloat* disparity) -> ZCError

Enum documentation

enum ZCEye

Defines the eyes for the Stereo Frustum API. This enum is also used by the Stereo Buffer API.

Enumerators
ZC_EYE_LEFT
ZC_EYE_RIGHT
ZC_EYE_CENTER

enum ZCFrustumAttribute

Defines the attributes that you can set and query for the StereoFrustum. These attributes are important for comfortable viewing of stereoscopic 3D.

Enumerators
ZC_FRUSTUM_ATTRIBUTE_IPD

The physical separation, or inter-pupillary distance, between the eyes in meters. An IPD of 0 will effectively disable stereo since the eyes are assumed to be at the same location. (Default: 0.060)
ZC_FRUSTUM_ATTRIBUTE_VIEWER_SCALE

Viewer scale adjusts the display and head tracking for larger and smaller scenes. (Default: 1) Use larger values for scenes with large models and smaller values for smaller models.
ZC_FRUSTUM_ATTRIBUTE_HEAD_SCALE

Uniform scale factor applied to the frustum's incoming head pose. (Default: 1)
ZC_FRUSTUM_ATTRIBUTE_NEAR_CLIP

Near clipping plane for the frustum in meters. (Default: 0.1)
ZC_FRUSTUM_ATTRIBUTE_FAR_CLIP

Far clipping plane for the frustum in meters. (Default: 1000)
ZC_FRUSTUM_ATTRIBUTE_GLASSES_OFFSET

Distance between the bridge of the glasses and the bridge of the nose in meters. (Default: 0.01)
ZC_FRUSTUM_ATTRIBUTE_CC_LIMIT

Maximum pixel disparity for crossed images (negative parallax) in the coupled zone. (Default: -100) The coupled zone refers to the area where our eyes can both comfortably converge and focus on an object.
ZC_FRUSTUM_ATTRIBUTE_UC_LIMIT

Maximum pixel disparity for uncrossed images (positive parallax) in the coupled zone. (Default: 100)
ZC_FRUSTUM_ATTRIBUTE_CU_LIMIT

Maximum pixel disparity for crossed images (negative parallax) in the uncoupled zone. (Default: -200)
ZC_FRUSTUM_ATTRIBUTE_UU_LIMIT

Maximum pixel disparity for uncrossed images (positive parallax) in the uncoupled zone. (Default: 250)
ZC_FRUSTUM_ATTRIBUTE_CC_DEPTH

Maximum depth in meters for negative parallax in the coupled zone. (Default: 0.13)
ZC_FRUSTUM_ATTRIBUTE_UC_DEPTH

Maximum depth in meters for positive parallax in the coupled zone. (Default: -0.30)
ZC_FRUSTUM_ATTRIBUTE_DISPLAY_ANGLE_X

Display angle in degrees about the X axis. (Default: 30.0) Is only used when ZC_PORTAL_MODE_ANGLE is not enabled on the frustum.
ZC_FRUSTUM_ATTRIBUTE_DISPLAY_ANGLE_Y

Display angle in degrees about the Y axis. (Default: 0.0) Is only used when ZC_PORTAL_MODE_ANGLE is not enabled on the frustum.
ZC_FRUSTUM_ATTRIBUTE_DISPLAY_ANGLE_Z

Display angle in degrees about the Z axis. (Default: 0.0) Is only used when ZC_PORTAL_MODE_ANGLE is not enabled on the frustum.
ZC_FRUSTUM_ATTRIBUTE_AUTO_STEREO_DELAY

The delay in seconds before the automatic transition from stereo to mono begins. (Default: 5.0)
ZC_FRUSTUM_ATTRIBUTE_AUTO_STEREO_DURATION

The duration in seconds of the automatic transition from stereo to mono. (Default: 1.0)
ZC_FRUSTUM_ATTRIBUTE_AUTO_STEREO_ENABLED

Flag controlling whether the automatic transition from stereo to mono is enabled. (Default: true)

enum ZCPortalMode

Defines options for positioning the scene relative to the physical display or relative to the viewport.

Enumerators
ZC_PORTAL_MODE_NONE

The scene is positioned relative to the viewport.
ZC_PORTAL_MODE_ANGLE

The scene's orientation is fixed relative to the physical desktop.
ZC_PORTAL_MODE_POSITION

The scene's position is fixed relative to the center of the display.
ZC_PORTAL_MODE_ALL

All portal modes except "none" are enabled.

Typedef documentation

typedef enum ZCEye ZCEye

Defines the eyes for the Stereo Frustum API. This enum is also used by the Stereo Buffer API.

typedef enum ZCFrustumAttribute ZCFrustumAttribute

Defines the attributes that you can set and query for the StereoFrustum. These attributes are important for comfortable viewing of stereoscopic 3D.

typedef enum ZCPortalMode ZCPortalMode

Defines options for positioning the scene relative to the physical display or relative to the viewport.

Function documentation

ZCError zcGetFrustum(ZCHandle viewportHandle, ZCHandle* frustumHandle)

Parameters
viewportHandle in A handle to the viewport.
frustumHandle out A handle to the frustum.

Gets the frustum owned by a specified viewport.

ZCError zcSetFrustumAttributeF32(ZCHandle frustumHandle, ZCFrustumAttribute attribute, ZSFloat value)

Parameters
frustumHandle in A handle to the frustum.
attribute in The attribute to be modified.
value in The desired floating point value to be applied to the attribute.

Sets the specified frustum attribute's value. See ZCFrustumAttribute for a list of attributes and valid values.

ZCError zcGetFrustumAttributeF32(ZCHandle frustumHandle, ZCFrustumAttribute attribute, ZSFloat* value)

Parameters
frustumHandle in A handle to the frustum.
attribute in The attribute to be queried.
value out The specified attribute's current floating point value.

Gets the specified frustum attribute's value. See ZCFrustumAttribute for a list of attributes that can be queried.

ZCError zcSetFrustumAttributeB(ZCHandle frustumHandle, ZCFrustumAttribute attribute, ZSBool value)

Parameters
frustumHandle in A handle to the frustum.
attribute in The attribute to be modified.
value in The desired boolean value to be applied to the attribute.

Sets the specified frustum attribute's value. See ZCFrustumAttribute for a list of attributes and valid values.

ZCError zcGetFrustumAttributeB(ZCHandle frustumHandle, ZCFrustumAttribute attribute, ZSBool* value)

Parameters
frustumHandle in A handle to the frustum.
attribute in The attribute to be queried.
value out The specified attribute's current boolean value.

Gets the specified frustum attribute's value. See ZCFrustumAttribute for a list of attributes that can be queried.

ZCError zcSetFrustumPortalMode(ZCHandle frustumHandle, ZSInt32 portalModeFlags)

Parameters
frustumHandle in A handle to the frustum.
portalModeFlags in A bitmask for the portal mode flags.

Sets the frustum's portal mode. In portal mode, the scene is fixed relative to the physical world, not the viewport. Refer to ZCPortalMode for details on portal modes.

ZCError zcGetFrustumPortalMode(ZCHandle frustumHandle, ZSInt32* portalModeFlags)

Parameters
frustumHandle in A handle to the frustum.
portalModeFlags out A bitmask representing the current portal mode settings.

Gets the frustum's setting for portal mode. In portal mode, the scene is fixed relative to the physical world, not the viewport.

ZCError zcSetFrustumCameraOffset(ZCHandle frustumHandle, const ZSVector3* cameraOffset)

Parameters
frustumHandle in A handle to the frustum.
cameraOffset in The desired camera offset in meters.

Sets the frustum's camera offset.

ZCError zcGetFrustumCameraOffset(ZCHandle frustumHandle, ZSVector3* cameraOffset)

Parameters
frustumHandle in A handle to the frustum.
cameraOffset out The current camera offset in meters.

Gets the frustum's camera offset.

ZCError zcSetFrustumHeadPose(ZCHandle frustumHandle, const ZCTrackerPose* headPose)

Parameters
frustumHandle in A handle to the frustum.
headPose in The desired head pose.

Sets the frustum's head pose in tracker space.

ZCError zcGetFrustumHeadPose(ZCHandle frustumHandle, ZCTrackerPose* headPose)

Parameters
frustumHandle in A handle to the frustum
headPose out The current head pose

Gets the frustum's current head pose in tracker space.

ZCError zcGetFrustumViewMatrix(ZCHandle frustumHandle, ZCEye eye, ZSMatrix4* viewMatrix)

Parameters
frustumHandle in A handle to the frustum.
eye in The eye to query.
viewMatrix out The view matrix for the specified eye.

Gets the frustum's view matrix for a specified eye. The view matrix is calculated from the head pose + eye offset.

ZCError zcGetFrustumProjectionMatrix(ZCHandle frustumHandle, ZCEye eye, ZSMatrix4* projectionMatrix)

Parameters
frustumHandle in A handle to the frustum.
eye in The eye to query.
projectionMatrix out The projection matrix for the specified eye.

Gets the frustum's projection matrix for a specified eye.

ZCError zcGetFrustumBounds(ZCHandle frustumHandle, ZCEye eye, ZCFrustumBounds* bounds)

Parameters
frustumHandle in A handle to the frustum.
eye in The eye to query.
bounds out The boundaries for the specified eye.

Gets the frustum's boundaries for the specified eye.

ZCError zcGetFrustumEyePosition(ZCHandle frustumHandle, ZCEye eye, ZCCoordinateSpace coordinateSpace, ZSVector3* eyePosition)

Parameters
frustumHandle in A handle to the frustum.
eye in The eye to query.
coordinateSpace in The coordinate space in which to return the eye position.
eyePosition out The eye's position.

Gets the specified eye's position in the specified coordinate space.

ZCError zcGetFrustumCoupledBoundingBox(ZCHandle frustumHandle, ZCBoundingBox* boundingBox)

Parameters
frustumHandle in A handle to the frustum.
boundingBox out The bounding box containing the coupled comfort zone's minimum and maximum extents.

Gets the axis-aligned bounding box of the coupled comfort zone in camera space.

ZCError zcCalculateFrustumFit(ZCHandle frustumHandle, const ZCBoundingBox* boundingBox, ZSFloat* viewerScale, ZSMatrix4* lookAtMatrix)

Parameters
frustumHandle in A handle to the frustum.
boundingBox in The bounding box in world space.
viewerScale out The viewer scale.
lookAtMatrix out The 4x4 lookat matrix corresponding to the application's monoscopic camera. This is also known as the inverse of the monoscopic camera's world matrix.

Calculates the camera's lookat matrix and viewer scale for the specified world-space bounds.

Use this function to fit a 3D volume (ZCBoundingBox) so that it takes up the entire viewport without being clipped. The resulting viewer scale can be used as input to the zcSetFrustumAttributeF32() function.

ZCError zcCalculateFrustumDisparity(ZCHandle frustumHandle, const ZSVector3* point, ZSFloat* disparity)

Parameters
frustumHandle in A handle to the frustum.
point in The point for which pixel disparity is calculated.
disparity out The number of pixels between the left and right stereo images at the specified point.

Calculates the pixel disparity for a specified point in camera space. Pixel disparity can be used to determine whether a specified point is in the coupled or decoupled comfort zones. Viewing objects outside of the coupled comfort zone can potentially lead to visual discomfort.