1 //
2 // Copyright 2016 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_CONFORM_WINDOW_H
25 #define PXR_IMAGING_CAMERA_UTIL_CONFORM_WINDOW_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/imaging/cameraUtil/api.h"
29 
30 PXR_NAMESPACE_OPEN_SCOPE
31 
32 class GfVec2d;
33 class GfVec4d;
34 class GfMatrix4d;
35 class GfRange2d;
36 class GfCamera;
37 class GfFrustum;
38 
39 /// \enum CameraUtilConformWindowPolicy
40 ///
41 /// Policy of how to conform a window to the given aspect ratio.
42 /// An ASCII-art explanation is given in the corresponding .cpp file.
43 ///
44 enum CameraUtilConformWindowPolicy {
45     /// Modify width
46     CameraUtilMatchVertically,
47     /// Modify height
48     CameraUtilMatchHorizontally,
49     /// Increase width or height
50     CameraUtilFit,
51     /// Decrease width or height
52     CameraUtilCrop,
53     /// Leave unchanged (This can result in stretching/shrinking if not pre-fit)
54     CameraUtilDontConform
55 };
56 
57 /// Returns a window with aspect ratio \p targetAspect by applying
58 /// \p policy to \p window where \p window is encoded as GfRange2d.
59 CAMERAUTIL_API
60 GfRange2d
61 CameraUtilConformedWindow(
62     const GfRange2d &window,
63     CameraUtilConformWindowPolicy policy, double targetAspect);
64 
65 /// Returns a window with aspect ratio \p targetAspect by applying
66 /// \p policy to \p window where \p window is encoded as vector
67 /// (left, right, bottom, top) similarly to RenderMan's RiScreenWindow.
68 CAMERAUTIL_API
69 GfVec4d
70 CameraUtilConformedWindow(
71     const GfVec4d &window,
72     CameraUtilConformWindowPolicy policy, double targetAspect);
73 
74 /// Returns a window with aspect ratio \p targetAspect by applying
75 /// \p policy to \p window where \p window is encoded as vector
76 /// (width, height).
77 CAMERAUTIL_API
78 GfVec2d
79 CameraUtilConformedWindow(
80     const GfVec2d &window,
81     CameraUtilConformWindowPolicy policy, double targetAspect);
82 
83 /// Conforms the given \p projectionMatrix to have aspect ratio \p targetAspect
84 /// by applying \p policy.
85 ///
86 /// Note that this function also supports mirroring about the x- or y-axis of
87 /// the image corresponding to flipping all signs in the second, respectively,
88 /// third column of the projection matrix. In other words, we get the same
89 /// result whether we flip the signs in the matrix and then give it to this
90 /// function or call this function first and flip the signs of the resulting
91 /// matrix.
92 CAMERAUTIL_API
93 GfMatrix4d
94 CameraUtilConformedWindow(
95     const GfMatrix4d &projectionMatrix,
96     CameraUtilConformWindowPolicy policy, double targetAspect);
97 
98 /// Conforms the given \p camera to have aspect ratio \p targetAspect
99 /// by applying \p policy.
100 CAMERAUTIL_API
101 void
102 CameraUtilConformWindow(
103     GfCamera *camera,
104     CameraUtilConformWindowPolicy policy, double targetAspect);
105 
106 /// Conforms the given \p frustum to have aspect ratio \p targetAspect
107 /// by applying \p policy.
108 CAMERAUTIL_API
109 void
110 CameraUtilConformWindow(
111     GfFrustum *frustum,
112     CameraUtilConformWindowPolicy policy, double targetAspect);
113 
114 
115 PXR_NAMESPACE_CLOSE_SCOPE
116 
117 #endif
118