Stereo Frustum API

Detailed Description

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.

Note:
For brevity, most of the code examples in this section omit initializing the handle for the stereo frustum. For a complete example, refer to zsFindFrustum().

List of Functions

ZSError  zsFindFrustum (ZSHandle viewportHandle, ZSHandle* frustumHandle)
ZSError  zsSetFrustumAttribute (ZSHandle frustumHandle, ZSFrustumAttribute attribute, ZSFloat value)
ZSError  zsGetFrustumAttribute (ZSHandle frustumHandle, ZSFrustumAttribute attribute, ZSFloat* value)
ZSError  zsSetFrustumPortalMode (ZSHandle frustumHandle, ZSInt32 portalModeFlags)
ZSError  zsGetFrustumPortalMode (ZSHandle frustumHandle, ZSInt32* portalModeFlags)
ZSError  zsSetFrustumCameraOffset (ZSHandle frustumHandle, const ZSVector3* cameraOffset)
ZSError  zsGetFrustumCameraOffset (ZSHandle frustumHandle, ZSVector3* cameraOffset)
ZSError  zsSetFrustumHeadPose (ZSHandle frustumHandle, const ZSTrackerPose* headPose)
ZSError  zsGetFrustumHeadPose (ZSHandle frustumHandle, ZSTrackerPose* headPose)
ZSError  zsGetFrustumViewMatrix (ZSHandle frustumHandle, ZSEye eye, ZSMatrix4* viewMatrix)
ZSError  zsGetFrustumProjectionMatrix (ZSHandle frustumHandle, ZSEye eye, ZSMatrix4* projectionMatrix)
ZSError  zsGetFrustumBounds (ZSHandle frustumHandle, ZSEye eye, ZSFrustumBounds* bounds)
ZSError  zsGetFrustumEyePosition (ZSHandle frustumHandle, ZSEye eye, ZSCoordinateSpace coordinateSpace, ZSVector3* eyePosition)
ZSError  zsGetFrustumCoupledBoundingBox (ZSHandle frustumHandle, ZSBoundingBox* boundingBox)
ZSError  zsCalculateFrustumFit (ZSHandle frustumHandle, const ZSBoundingBox* boundingBox, ZSFloat* viewerScale, ZSMatrix4* lookAtMatrix)
ZSError  zsCalculateFrustumDisparity (ZSHandle frustumHandle, const ZSVector3* point, ZSFloat* disparity)
ZSError  zsCalculateFrustumFovScale (ZSHandle frustumHandle, ZSFloat fov, ZSFloat* fovScale)

List of Data Structures

union   ZSFrustumBounds
  Union representing frustum bounds. More...

List of Enumerations

enum   ZSEye {
  ZS_EYE_LEFT = 0,
  ZS_EYE_RIGHT = 1,
  ZS_EYE_CENTER = 2
}
enum   ZSFrustumAttribute {
  ZS_FRUSTUM_ATTRIBUTE_IPD = 0,
  ZS_FRUSTUM_ATTRIBUTE_VIEWER_SCALE = 1,
  ZS_FRUSTUM_ATTRIBUTE_FOV_SCALE = 2,
  ZS_FRUSTUM_ATTRIBUTE_HEAD_SCALE = 3,
  ZS_FRUSTUM_ATTRIBUTE_NEAR_CLIP = 4,
  ZS_FRUSTUM_ATTRIBUTE_FAR_CLIP = 5,
  ZS_FRUSTUM_ATTRIBUTE_GLASSES_OFFSET = 6,
  ZS_FRUSTUM_ATTRIBUTE_CC_LIMIT = 7,
  ZS_FRUSTUM_ATTRIBUTE_UC_LIMIT = 8,
  ZS_FRUSTUM_ATTRIBUTE_CU_LIMIT = 9,
  ZS_FRUSTUM_ATTRIBUTE_UU_LIMIT = 10,
  ZS_FRUSTUM_ATTRIBUTE_CC_DEPTH = 11,
  ZS_FRUSTUM_ATTRIBUTE_UC_DEPTH = 12
}
enum   ZSPortalMode {
  ZS_PORTAL_MODE_NONE = 0x00000000,
  ZS_PORTAL_MODE_ANGLE = 0x00000001,
  ZS_PORTAL_MODE_POSITION = 0x00000002,
  ZS_PORTAL_MODE_ALL = 0xFFFFFFFF
}

Function Descriptions

ZSError zsCalculateFrustumDisparity ( ZSHandle  frustumHandle,
const ZSVector3*   point,
ZSFloat*   disparity 
)

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.

Parameters:
[in] frustumHandle A handle to the frustum.
[in] point The point for which pixel disparity is calculated.
[out] disparity The number of pixels between the left and right stereo images at the specified point.
ZSError zsCalculateFrustumFit ( ZSHandle  frustumHandle,
const ZSBoundingBox*   boundingBox,
ZSFloat*   viewerScale,
ZSMatrix4*   lookAtMatrix 
)

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

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

Parameters:
[in] frustumHandle A handle to the frustum.
[in] boundingBox The bounding box in world space.
[out] viewerScale The viewer scale.
[out] lookAtMatrix 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..
Example:
 ZSHandle frustumHandle;

 // Set up a bounding box that is centered about the world's origin (0, 0, 0) 
 // and has a width, height, and depth of 0.10 meters. 
 float halfSize = 0.05f;
 ZSBoundingBox b;
 b.lower.x = -halfSize;
 b.lower.y = -halfSize;
 b.lower.z = -halfSize;
 
 b.upper.x =  halfSize;
 b.upper.y =  halfSize;
 b.upper.z =  halfSize;
 
 ZSMatrix4 lookAtMatrix;
 ZSFloat   viewerScale;

 // Calculate the appropriate viewer scale and camera lookat matrix 
 // such that content in the above bounding box will take up the entire  
 // viewport without being clipped. 
 zsCalculateFrustumFit(frustumHandle, &b, &viewerScale, &lookAtMatrix);

 // Set the frustum's viewer scale with the value that was calculated 
 // by zsCalculateFrustumFit(). 
 zsSetFrustumAttribute(frustumHandle, 
                       ZS_FRUSTUM_ATTRIBUTE_VIEWER_SCALE, 
                       viewerScale);
 
 // Although this is OpenGL specific, here is one way to apply the lookat 
 // matrix that was calculated by zsCalculateFrustumFit(). 
 glMatrixMode(GL_MODELVIEW);
 glLoadMatrixf(lookAtMatrix.f);
ZSError zsCalculateFrustumFovScale ( ZSHandle  frustumHandle,
ZSFloat  fov,
ZSFloat*   fovScale 
)

Calculates the field of view scale for the specified field of view. Use the resulting fovScale as an input parameter to zsSetFrustumAttribute() to update the frustum's field of view scale.

Parameters:
[in] frustumHandle A handle to the frustum.
[in] fov The field of view in degrees.
[out] fovScale The calculated scale for the field of view.
ZSError zsFindFrustum ( ZSHandle  viewportHandle,
ZSHandle*   frustumHandle 
)

Gets the frustum owned by a specified viewport.

Parameters:
[in] viewportHandle A handle to the viewport.
[out] frustumHandle A handle to the frustum.
Example:
 ZSContext context = ...;

 ZSHandle viewportHandle = NULL;
 ZSHandle frustumHandle = NULL;
 zsCreateViewport(context, &viewportHandle);
 zsFindFrustum(viewportHandle, &frustumHandle); 
ZSError zsGetFrustumAttribute ( ZSHandle  frustumHandle,
ZSFrustumAttribute  attribute,
ZSFloat*   value 
)

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

Parameters:
[in] frustumHandle A handle to the frustum.
[in] attribute The attribute to be queried.
[out] value The specified attribute's current floating point value.
ZSError zsGetFrustumBounds ( ZSHandle  frustumHandle,
ZSEye  eye,
ZSFrustumBounds*   bounds 
)

Gets the frustum's boundaries for the specified eye.

Parameters:
[in] frustumHandle A handle to the frustum.
[in] eye The eye to query.
[out] bounds The boundaries for the specified eye.
ZSError zsGetFrustumCameraOffset ( ZSHandle  frustumHandle,
ZSVector3*   cameraOffset 
)

Gets the frustum's camera offset.

Parameters:
[in] frustumHandle A handle to the frustum.
[out] cameraOffset The current camera offset in meters.
ZSError zsGetFrustumCoupledBoundingBox ( ZSHandle  frustumHandle,
ZSBoundingBox*   boundingBox 
)

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

Parameters:
[in] frustumHandle A handle to the frustum.
[out] boundingBox The bounding box containing the coupled comfort zone's minimum and maximum extents.
ZSError zsGetFrustumEyePosition ( ZSHandle  frustumHandle,
ZSEye  eye,
ZSCoordinateSpace  coordinateSpace,
ZSVector3*   eyePosition 
)

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

Parameters:
[in] frustumHandle A handle to the frustum.
[in] eye The eye to query.
[in] coordinateSpace The coordinate space in which to return the eye position.
[out] eyePosition The eye's position.
ZSError zsGetFrustumHeadPose ( ZSHandle  frustumHandle,
ZSTrackerPose*   headPose 
)

Gets the frustum's current head pose.

Parameters:
[in] frustumHandle A handle to the frustum
[out] headPose The current head pose
ZSError zsGetFrustumPortalMode ( ZSHandle  frustumHandle,
ZSInt32*   portalModeFlags 
)

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

Parameters:
[in] frustumHandle A handle to the frustum.
[out] portalModeFlags A bitmask representing the current portal mode settings.
ZSError zsGetFrustumProjectionMatrix ( ZSHandle  frustumHandle,
ZSEye  eye,
ZSMatrix4*   projectionMatrix 
)

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

Parameters:
[in] frustumHandle A handle to the frustum.
[in] eye The eye to query.
[out] projectionMatrix The projection matrix for the specified eye.
Example:
 ZSHandle frustumHandle;
 
 // Get the projection matrix for the left eye. 
 ZSMatrix4 projectionMatrix;
 zsGetFrustumProjectionMatrix(frustumHandle, ZS_EYE_LEFT, &projectionMatrix);
ZSError zsGetFrustumViewMatrix ( ZSHandle  frustumHandle,
ZSEye  eye,
ZSMatrix4*   viewMatrix 
)

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

Parameters:
[in] frustumHandle A handle to the frustum.
[in] eye The eye to query.
[out] viewMatrix The view matrix for the specified eye.
Example:
 ZSHandle frustumHandle;

 // Get the view matrix for the left eye. 
 ZSMatrix4 viewMatrix;
 zsGetFrustumViewMatrix(frustumHandle, ZS_EYE_LEFT, &viewMatrix);
ZSError zsSetFrustumAttribute ( ZSHandle  frustumHandle,
ZSFrustumAttribute  attribute,
ZSFloat  value 
)

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

Parameters:
[in] frustumHandle A handle to the frustum.
[in] attribute The attribute to be modified.
[in] value The desired floating point value to be applied to the attribute.
ZSError zsSetFrustumCameraOffset ( ZSHandle  frustumHandle,
const ZSVector3*   cameraOffset 
)

Sets the frustum's camera offset.

Parameters:
[in] frustumHandle A handle to the frustum.
[in] cameraOffset The desired camera offset in meters.
ZSError zsSetFrustumHeadPose ( ZSHandle  frustumHandle,
const ZSTrackerPose*   headPose 
)

Sets the frustum's head pose.

Parameters:
[in] frustumHandle A handle to the frustum.
[in] headPose The desired head pose.
ZSError zsSetFrustumPortalMode ( ZSHandle  frustumHandle,
ZSInt32  portalModeFlags 
)

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

Parameters:
[in] frustumHandle A handle to the frustum.
[in] portalModeFlags A bitmask for the portal mode flags.
Example:
 ZSHandle frustumHandle;

 // The following calls are a few examples of how to specify 
 // portal mode flags: 
 zsSetFrustumPortalMode(frustumHandle, ZS_PORTAL_MODE_NONE);  // Disables Portal Mode 
 zsSetFrustumPortalMode(frustumHandle, ZS_PORTAL_MODE_ANGLE); // Angle 
 zsSetFrustumPortalMode(frustumHandle, 
             ZS_PORTAL_MODE_ANGLE | ZS_PORTAL_MODE_POSITION); // Angle & Position

Enumeration Descriptions

enum ZSEye

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

Enumerator:
ZS_EYE_LEFT 
ZS_EYE_RIGHT 
ZS_EYE_CENTER 

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

Enumerator:
ZS_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.06)

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

ZS_FRUSTUM_ATTRIBUTE_FOV_SCALE 

Field of view scale for the frustum. (Default: 1) A value greater than 1 causes a wide angle effect, while a value less than 1 causes a zoom effect. However, large changes to the field of view scale will interfere with the mapping between the physical and virtual stylus.

ZS_FRUSTUM_ATTRIBUTE_HEAD_SCALE 

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

ZS_FRUSTUM_ATTRIBUTE_NEAR_CLIP 

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

ZS_FRUSTUM_ATTRIBUTE_FAR_CLIP 

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

ZS_FRUSTUM_ATTRIBUTE_GLASSES_OFFSET 

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

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

ZS_FRUSTUM_ATTRIBUTE_UC_LIMIT 

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

ZS_FRUSTUM_ATTRIBUTE_CU_LIMIT 

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

ZS_FRUSTUM_ATTRIBUTE_UU_LIMIT 

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

ZS_FRUSTUM_ATTRIBUTE_CC_DEPTH 

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

ZS_FRUSTUM_ATTRIBUTE_UC_DEPTH 

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

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

Enumerator:
ZS_PORTAL_MODE_NONE 

The scene is positioned relative to the viewport.

ZS_PORTAL_MODE_ANGLE 

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

ZS_PORTAL_MODE_POSITION 

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

ZS_PORTAL_MODE_ALL 

All portal modes except "none" are enabled.