Perhaps the most common use-case for Umbra is to determine what is visible from the point of view of a camera. This is done by calling Umbra::Query::queryPortalVisibility(). In order for Umbra to find out what is visible to the camera, a representation of it is naturally required. This representation is encapsulated in the CameraTransform class, which is passed as an argument for queryPortalVisibility().
Typically, the CameraTransform object contains the same information that is also used in rendering the camera view. As such, the camera transformation contains information about the camera’s location and orientation, the perspective transformation and clipping frustum.
The CameraTransform object is initialized using either it’s constructor or the Umbra::CameraTransform::set() method. The arguments for both are identical: the transformation matrix from world space to clip space, the position of the camera, the depth range (optional) and the matrix format (optional). See also for the full Umbra::CameraTransform API documentation and below for more details.
Umbra also supports specifying the camera transformation using the camera space to world space transformation matrix accompanied by explicitly specifying the viewing frustum. The Frustum struct describes the information about the perspective projection and corresponding clipping planes. See Umbra::CameraTransform() and below for more information.
The definition of the view frustum in clip space varies between rendering APIs. For instance, in OpenGL the frustum is defined by the clip space unit cube, ranging from [-1, -1, -1] to [1, 1, 1], whereas in Direct3D the viewing frustum is defined as the range from [-1, -1, 0] to [1, 1, 1] in clip space. Thus, the user may specify which format their camera transformation uses, by specifying either Umbra::CameraTransform::DEPTHRANGE_MINUS_ONE_TO_ONE (the former) or Umbra::CameraTransform::DEPTHRANGE_ZERO_TO_ONE (the latter and the default).
All Umbra API functions that accept 4x4 transformation matrices as input also allow the user to specify how the matrices are laid out in memory. More specifically, the user may specify either Umbra::MF_COLUMN_MAJOR for the so-called “column major” matrix format or Umbra::MF_ROW_MAJOR for “row major” matrices. In this context, “column major” refers to storing the translation component of the matrix in memory locations 12, 13 and 14 when considering a flat 16-element array representation of the matrix. In contrast, the translation component of “row major” matrices is stored in memory locations 3, 7 and 11, respectively. Umbra::MF_COLUMN_MAJOR is the format used in both Direct3D and OpenGL, and is also the default value in all Umbra API entries.
Constructing a frustum
There are two ways to specify the camera transformation. Using the first method, the user specifies the combined transformation matrix from world space to clip space. This can typically be obtained by multiplying the view transformation (modelview) matrix by the projection matrix. In addition, the user needs to specify the location of the camera. Additionally, the user may specify the clip space depth range and the matrix layout format.
An alternative method of constructing the camera transformation is to specify the camera’s “inverse view” matrix, i.e. the matrix transforming from the camera space to world space. In addition, the user needs to manually construct the frustum. This is done by initializing a Frustum object, which defines the details of the projection. The Frustum merely contains the coordinates of each frustum plane, which can either be initialized manually or computed using the helper constructor of the Frustum class. The helper constructor calculates the values using the given field-of-view angle, aspect ratio and the distances to the near and far planes. In addition, the user may specify whether the projection is a perspective projection or an orthographic projection, by defining either Umbra::Frustum::PERSPECTIVE or Umbra::Frustum::ORTHOGRAPHIC, respectively. See the full API documentation of Umbra::Frustum for more details.
User clip planes
By default, Umbra’s view is bounded by six clipping planes. The user may specify additional clip planes by calling Umbra::CameraTransform::setUserClipPlanes(). The method accepts the clip plane equations (in general form, in world space) and the number of user clip planes as arguments.