HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
framing.h
Go to the documentation of this file.
1 //
2 // Copyright 2020 Pixar
3 //
4 // Licensed under the Apache License, Version 2.0 (the "Apache License")
5 // with the following modification; you may not use this file except in
6 // compliance with the Apache License and the following modification to it:
7 // Section 6. Trademarks. is deleted and replaced with:
8 //
9 // 6. Trademarks. This License does not grant permission to use the trade
10 // names, trademarks, service marks, or product names of the Licensor
11 // and its affiliates, except as required to comply with Section 4(c) of
12 // the License and to reproduce the content of the NOTICE file.
13 //
14 // You may obtain a copy of the Apache License at
15 //
16 // http://www.apache.org/licenses/LICENSE-2.0
17 //
18 // Unless required by applicable law or agreed to in writing, software
19 // distributed under the Apache License with the above modification is
20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21 // KIND, either express or implied. See the Apache License for the specific
22 // language governing permissions and limitations under the Apache License.
23 //
24 #ifndef PXR_IMAGING_CAMERA_UTIL_FRAMING_H
25 #define PXR_IMAGING_CAMERA_UTIL_FRAMING_H
26 
27 #include "pxr/pxr.h"
29 
31 
32 #include "pxr/base/gf/rect2i.h"
33 #include "pxr/base/gf/range2f.h"
34 
36 
37 /// \class CameraUtilFraming
38 ///
39 /// Framing information. That is information determining how the filmback
40 /// plane of a camera maps to the pixels of the rendered image (displayWindow
41 /// together with pixelAspectRatio and window policy) and what pixels of the
42 /// image will be filled by the renderer (dataWindow).
43 ///
44 /// The concepts of displayWindow and dataWindow are similar to the ones in
45 /// OpenEXR, including that the x- and y-axis of the coordinate system point
46 /// left and down, respectively.
47 ///
48 /// In fact, these windows mean the same here and in OpenEXR if the
49 /// displayWindow has the same aspect ratio (when accounting for the
50 /// pixelAspectRatio) as the filmback plane of the camera has (that is the
51 /// ratio of the horizontalAperture to verticalAperture of, e.g., Usd's Camera
52 /// or GfCamera).
53 ///
54 /// In particular, overscan can be achieved by making the dataWindow larger
55 /// than the displayWindow.
56 ///
57 /// If the aspect ratios differ, a window policy is applied to the
58 /// displayWindow to determine how the pixels correspond to the
59 /// filmback plane. One such window policy is to take the largest
60 /// rect that fits (centered) into the displayWindow and has the
61 /// camera's aspect ratio. For example, if the displayWindow and dataWindow
62 /// are the same and both have an aspect ratio smaller than the camera, the
63 /// image is created by enlarging the camera frustum slightly in the bottom
64 /// and top direction.
65 ///
66 /// When using the AOVs, the render buffer size is determined
67 /// independently from the framing info. However, the dataWindow is
68 /// supposed to be contained in the render buffer rect (in particular,
69 /// the dataWindow cannot contain pixels withs negative coordinates -
70 /// this restriction does not apply if, e.g., hdPrman circumvents AOVs
71 /// and writes directly to EXR). In other words, unlike in OpenEXR,
72 /// the rect of pixels for which we allocate storage can differ from
73 /// the rect the renderer fills with data (dataWindow).
74 ///
75 /// For example, an application can set the render buffer size to match
76 /// the widget size but use a dataWindow and displayWindow that only fills
77 /// the render buffer horizontally to have slates at the top and bottom.
78 ///
79 class CameraUtilFraming final
80 {
81 public:
82  /// Creates an invalid framing, i.e., with empty display and data
83  /// window.
86 
87  /// Creates a framing with given display and data window and pixel
88  /// aspect ratio.
89  ///
92  const GfRange2f &displayWindow,
93  const GfRect2i &dataWindow,
94  float pixelAspectRatio = 1.0);
95 
96  /// Creates a framing with equal display and data window (and
97  /// assuming square pixels).
98  ///
100  explicit CameraUtilFraming(
101  const GfRect2i &dataWindow);
102 
103  /// Is display and data window non-empty.
105  bool IsValid() const;
106 
108  bool operator==(const CameraUtilFraming& other) const;
109 
111  bool operator!=(const CameraUtilFraming& other) const;
112 
113  /// Given the projectionMatrix computed from a camera, applies
114  /// the framing. To obtain a correct result, a rasterizer needs
115  /// to use the resulting projection matrix and set the viewport
116  /// to the data window.
117  ///
120  const GfMatrix4d &projectionMatrix,
121  CameraUtilConformWindowPolicy windowPolicy) const;
122 
123  /// The display window. It will be conformed to the camera's
124  /// aspect ratio and then mapped to the filmback plane.
126 
127  /// The data window. That is the rect of pixels that the renderer
128  /// will fill.
130 
131  /// The ratio of the width to the height of a pixel - same as
132  /// OpenEXR.
134 };
135 
137 
138 #endif
GfRange2f displayWindow
Definition: framing.h:125
GfRect2i dataWindow
Definition: framing.h:129
CAMERAUTIL_API GfMatrix4d ApplyToProjectionMatrix(const GfMatrix4d &projectionMatrix, CameraUtilConformWindowPolicy windowPolicy) const
CameraUtilConformWindowPolicy
Definition: conformWindow.h:44
CAMERAUTIL_API bool operator==(const CameraUtilFraming &other) const
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1375
float pixelAspectRatio
Definition: framing.h:133
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
#define CAMERAUTIL_API
Definition: api.h:40
CAMERAUTIL_API bool operator!=(const CameraUtilFraming &other) const
CAMERAUTIL_API bool IsValid() const
Is display and data window non-empty.
CAMERAUTIL_API CameraUtilFraming()