Open topic with navigation

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

enum ZSFrustumAttribute

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)

enum ZSPortalMode

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.

Open topic with navigation