CameraUtilFraming Class Referencefinal

Framing information. More...

Public Member Functions

CAMERAUTIL_API CameraUtilFraming ()
 Creates an invalid framing, i.e., with empty display and data window. More...
 
CAMERAUTIL_API CameraUtilFraming (const GfRange2f &displayWindow, const GfRect2i &dataWindow, float pixelAspectRatio=1.0)
 Creates a framing with given display and data window and pixel aspect ratio. More...
 
CAMERAUTIL_API CameraUtilFraming (const GfRect2i &dataWindow)
 Creates a framing with equal display and data window (and assuming square pixels). More...
 
CAMERAUTIL_API bool IsValid () const
 Is display and data window non-empty. More...
 
CAMERAUTIL_API bool operator== (const CameraUtilFraming &other) const
 
CAMERAUTIL_API bool operator!= (const CameraUtilFraming &other) const
 
CAMERAUTIL_API GfMatrix4d ApplyToProjectionMatrix (const GfMatrix4d &projectionMatrix, CameraUtilConformWindowPolicy windowPolicy) const
 Given the projectionMatrix computed from a camera, applies the framing. More...
 

Public Attributes

GfRange2f displayWindow
 The display window. More...
 
GfRect2i dataWindow
 The data window. More...
 
float pixelAspectRatio
 The ratio of the width to the height of a pixel - same as OpenEXR. More...
 

Detailed Description

Framing information.

That is information determining how the filmback plane of a camera maps to the pixels of the rendered image (displayWindow together with pixelAspectRatio and window policy) and what pixels of the image will be filled by the renderer (dataWindow).

The concepts of displayWindow and dataWindow are similar to the ones in OpenEXR, including that the x- and y-axis of the coordinate system point left and down, respectively.

In fact, these windows mean the same here and in OpenEXR if the displayWindow has the same aspect ratio (when accounting for the pixelAspectRatio) as the filmback plane of the camera has (that is the ratio of the horizontalAperture to verticalAperture of, e.g., Usd's Camera or GfCamera).

In particular, overscan can be achieved by making the dataWindow larger than the displayWindow.

If the aspect ratios differ, a window policy is applied to the displayWindow to determine how the pixels correspond to the filmback plane. One such window policy is to take the largest rect that fits (centered) into the displayWindow and has the camera's aspect ratio. For example, if the displayWindow and dataWindow are the same and both have an aspect ratio smaller than the camera, the image is created by enlarging the camera frustum slightly in the bottom and top direction.

When using the AOVs, the render buffer size is determined independently from the framing info. However, the dataWindow is supposed to be contained in the render buffer rect (in particular, the dataWindow cannot contain pixels withs negative coordinates - this restriction does not apply if, e.g., hdPrman circumvents AOVs and writes directly to EXR). In other words, unlike in OpenEXR, the rect of pixels for which we allocate storage can differ from the rect the renderer fills with data (dataWindow).

For example, an application can set the render buffer size to match the widget size but use a dataWindow and displayWindow that only fills the render buffer horizontally to have slates at the top and bottom.

Definition at line 79 of file framing.h.

Constructor & Destructor Documentation

◆ CameraUtilFraming() [1/3]

CAMERAUTIL_API CameraUtilFraming ( )

Creates an invalid framing, i.e., with empty display and data window.

◆ CameraUtilFraming() [2/3]

CAMERAUTIL_API CameraUtilFraming ( const GfRange2f displayWindow,
const GfRect2i dataWindow,
float  pixelAspectRatio = 1.0 
)

Creates a framing with given display and data window and pixel aspect ratio.

◆ CameraUtilFraming() [3/3]

CAMERAUTIL_API CameraUtilFraming ( const GfRect2i dataWindow)
explicit

Creates a framing with equal display and data window (and assuming square pixels).

Member Function Documentation

◆ ApplyToProjectionMatrix()

CAMERAUTIL_API GfMatrix4d ApplyToProjectionMatrix ( const GfMatrix4d projectionMatrix,
CameraUtilConformWindowPolicy  windowPolicy 
) const

Given the projectionMatrix computed from a camera, applies the framing.

To obtain a correct result, a rasterizer needs to use the resulting projection matrix and set the viewport to the data window.

◆ IsValid()

CAMERAUTIL_API bool IsValid ( ) const

Is display and data window non-empty.

Member Data Documentation

◆ dataWindow

GfRect2i dataWindow

The data window.

That is the rect of pixels that the renderer will fill.

Definition at line 129 of file framing.h.

◆ displayWindow

GfRange2f displayWindow

The display window.

It will be conformed to the camera's aspect ratio and then mapped to the filmback plane.

Definition at line 125 of file framing.h.

◆ pixelAspectRatio

float pixelAspectRatio

The ratio of the width to the height of a pixel - same as OpenEXR.

Definition at line 133 of file framing.h.


The documentation for this class was generated from the following file: