1 /*=========================================================================
3 Program: Visualization Toolkit
4 Module: $RCSfile: vtkPerspectiveTransform.h,v $
6 Date: $Date: 2002/12/26 18:24:21 $
7 Version: $Revision: 1.30 $
9 Copyright (c) 1993-2002 Ken Martin, Will Schroeder, Bill Lorensen
11 See Copyright.txt or http://www.kitware.com/Copyright.htm for details.
13 This software is distributed WITHOUT ANY WARRANTY; without even
14 the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
15 PURPOSE. See the above copyright notice for more information.
17 =========================================================================*/
19 // .NAME vtkPerspectiveTransform - describes a 4x4 matrix transformation
20 // .SECTION Description
21 // A vtkPerspectiveTransform can be used to describe the full range of
22 // homogeneous transformations. It was designed in particular
23 // to describe a camera-view of a scene.
24 // <P>The order in which you set up the display coordinates (via
25 // AdjustZBuffer() and AdjustViewport()), the projection (via Perspective(),
26 // Frustum(), or Ortho()) and the camera view (via SetupCamera()) are
27 // important. If the transform is in PreMultiply mode, which is the
28 // default, set the Viewport and ZBuffer first, then the projection, and
29 // finally the camera view. Once the view is set up, the Translate
30 // and Rotate methods can be used to move the camera around in world
31 // coordinates. If the Oblique() or Stereo() methods are used, they
32 // should be called just before SetupCamera().
33 // <P>In PostMultiply mode, you must perform all transformations
34 // in the opposite order. This is necessary, for example, if you
35 // already have a perspective transformation set up but must adjust
36 // the viewport. Another example is if you have a view transformation,
37 // and wish to perform translations and rotations in the camera's
38 // coordinate system rather than in world coordinates.
39 // <P>The SetInput and Concatenate methods can be used to create
40 // a transformation pipeline with vtkPerspectiveTransform. See vtkTransform
41 // for more information on the transformation pipeline.
43 // vtkGeneralTransform vtkTransform vtkMatrix4x4 vtkCamera
45 #ifndef __vtkPerspectiveTransform_h
46 #define __vtkPerspectiveTransform_h
48 #include "vtkHomogeneousTransform.h"
50 #include "vtkMatrix4x4.h" // Needed for inline methods
52 class VTK_COMMON_EXPORT vtkPerspectiveTransform : public vtkHomogeneousTransform
55 static vtkPerspectiveTransform *New();
56 vtkTypeRevisionMacro(vtkPerspectiveTransform,vtkHomogeneousTransform);
57 void PrintSelf(ostream& os, vtkIndent indent);
60 // Set this transformation to the identity transformation. If
61 // the transform has an Input, then the transformation will be
62 // reset so that it is the same as the Input.
63 void Identity() { this->Concatenation->Identity(); this->Modified(); };
66 // Invert the transformation. This will also set a flag so that
67 // the transformation will use the inverse of its Input, if an Input
69 void Inverse() { this->Concatenation->Inverse(); this->Modified(); };
72 // Perform an adjustment to the viewport coordinates. By default Ortho,
73 // Frustum, and Perspective provide a window of ([-1,+1],[-1,+1]).
74 // In PreMultiply mode, you call this method before calling Ortho, Frustum,
75 // or Perspective. In PostMultiply mode you can call it after. Note
76 // that if you must apply both AdjustZBuffer and AdjustViewport, it
77 // makes no difference which order you apply them in.
78 void AdjustViewport(double oldXMin, double oldXMax,
79 double oldYMin, double oldYMax,
80 double newXMin, double newXMax,
81 double newYMin, double newYMax);
84 // Perform an adjustment to the Z-Buffer range that the near and far
85 // clipping planes map to. By default Ortho, Frustum, and Perspective
86 // map the near clipping plane to -1 and the far clipping plane to +1.
87 // In PreMultiply mode, you call this method before calling Ortho, Frustum,
88 // or Perspective. In PostMultiply mode you can call it after.
89 void AdjustZBuffer(double oldNearZ, double oldFarZ,
90 double newNearZ, double newFarZ);
93 // Create an orthogonal projection matrix and concatenate it by the
94 // current transformation. The matrix maps [xmin,xmax], [ymin,ymax],
95 // [-znear,-zfar] to [-1,+1], [-1,+1], [+1,-1].
96 void Ortho(double xmin, double xmax, double ymin, double ymax,
97 double znear, double zfar);
100 // Create an perspective projection matrix and concatenate it by the
101 // current transformation. The matrix maps a frustum with a back
102 // plane at -zfar and a front plane at -znear with extent
103 // [xmin,xmax],[ymin,ymax] to [-1,+1], [-1,+1], [+1,-1].
104 void Frustum(double xmin, double xmax, double ymin, double ymax,
105 double znear, double zfar);
108 // Create a perspective projection matrix by specifying the view angle
109 // (this angle is in the y direction), the aspect ratio, and the near
110 // and far clipping range. The projection matrix is concatenated
111 // with the current transformation. This method works via Frustum.
112 void Perspective(double angle, double aspect, double znear, double zfar);
115 // Create a shear transformation about a plane at distance z from
116 // the camera. The values dxdz (i.e. dx/dz) and dydz specify the
117 // amount of shear in the x and y directions. The 'zplane' specifies
118 // the distance from the camera to the plane at which the shear
119 // causes zero displacement. Generally you want this plane to be the
121 // This transformation can be used in combination with Ortho to create
122 // an oblique projection. It can also be used in combination with
123 // Perspective to provide correct stereo views when the eye is at
124 // arbitrary but known positions relative to the center of a flat
126 void Shear(double dxdz, double dydz, double zplane);
129 // Create a stereo shear matrix and concatenate it with the
130 // current transformation. This can be applied in conjunction with either a
131 // perspective transformation (via Frustum or Projection) or an
132 // orthographic projection. You must specify the distance from
133 // the camera plane to the focal plane, and the angle between
134 // the distance vector and the eye. The angle should be negative
135 // for the left eye, and positive for the right. This method
136 // works via Oblique.
137 void Stereo(double angle, double focaldistance);
140 // Set a view transformation matrix for the camera (this matrix does
141 // not contain any perspective) and concatenate it with the current
143 void SetupCamera(const double position[3], const double focalpoint[3],
144 const double viewup[3]);
146 void SetupCamera(double p0, double p1, double p2,
147 double fp0, double fp1, double fp2,
148 double vup0, double vup1, double vup2);
151 // Create a translation matrix and concatenate it with the current
152 // transformation according to PreMultiply or PostMultiply semantics.
153 void Translate(double x, double y, double z) {
154 this->Concatenation->Translate(x,y,z); };
155 void Translate(const double x[3]) { this->Translate(x[0], x[1], x[2]); };
156 void Translate(const float x[3]) { this->Translate(x[0], x[1], x[2]); };
159 // Create a rotation matrix and concatenate it with the current
160 // transformation according to PreMultiply or PostMultiply semantics.
161 // The angle is in degrees, and (x,y,z) specifies the axis that the
162 // rotation will be performed around.
163 void RotateWXYZ(double angle, double x, double y, double z) {
164 this->Concatenation->Rotate(angle,x,y,z); };
165 void RotateWXYZ(double angle, const double axis[3]) {
166 this->RotateWXYZ(angle, axis[0], axis[1], axis[2]); };
167 void RotateWXYZ(double angle, const float axis[3]) {
168 this->RotateWXYZ(angle, axis[0], axis[1], axis[2]); };
171 // Create a rotation matrix about the X, Y, or Z axis and concatenate
172 // it with the current transformation according to PreMultiply or
173 // PostMultiply semantics. The angle is expressed in degrees.
174 void RotateX(double angle) { this->RotateWXYZ(angle, 1, 0, 0); };
175 void RotateY(double angle) { this->RotateWXYZ(angle, 0, 1, 0); };
176 void RotateZ(double angle) { this->RotateWXYZ(angle, 0, 0, 1); };
179 // Create a scale matrix (i.e. set the diagonal elements to x, y, z)
180 // and concatenate it with the current transformation according to
181 // PreMultiply or PostMultiply semantics.
182 void Scale(double x, double y, double z) {
183 this->Concatenation->Scale(x,y,z); };
184 void Scale(const double s[3]) { this->Scale(s[0], s[1], s[2]); };
185 void Scale(const float s[3]) { this->Scale(s[0], s[1], s[2]); };
188 // Set the current matrix directly. This actually calls Identity(),
189 // followed by Concatenate(matrix).
190 void SetMatrix(vtkMatrix4x4 *matrix) {
191 this->SetMatrix(*matrix->Element); };
192 void SetMatrix(const double elements[16]) {
193 this->Identity(); this->Concatenate(elements); };
196 // Concatenates the matrix with the current transformation according
197 // to PreMultiply or PostMultiply semantics.
198 void Concatenate(vtkMatrix4x4 *matrix) {
199 this->Concatenate(*matrix->Element); };
200 void Concatenate(const double elements[16]) {
201 this->Concatenation->Concatenate(elements); };
204 // Concatenate the specified transform with the current transformation
205 // according to PreMultiply or PostMultiply semantics.
206 // The concatenation is pipelined, meaning that if any of the
207 // transformations are changed, even after Concatenate() is called,
208 // those changes will be reflected when you call TransformPoint().
209 void Concatenate(vtkHomogeneousTransform *transform);
212 // Sets the internal state of the transform to PreMultiply. All subsequent
213 // operations will occur before those already represented in the
214 // current transformation. In homogeneous matrix notation, M = M*A where
215 // M is the current transformation matrix and A is the applied matrix.
216 // The default is PreMultiply.
218 if (this->Concatenation->GetPreMultiplyFlag()) { return; }
219 this->Concatenation->SetPreMultiplyFlag(1); this->Modified(); };
222 // Sets the internal state of the transform to PostMultiply. All subsequent
223 // operations will occur after those already represented in the
224 // current transformation. In homogeneous matrix notation, M = A*M where
225 // M is the current transformation matrix and A is the applied matrix.
226 // The default is PreMultiply.
227 void PostMultiply() {
228 if (!this->Concatenation->GetPreMultiplyFlag()) { return; }
229 this->Concatenation->SetPreMultiplyFlag(0); this->Modified(); };
232 // Get the total number of transformations that are linked into this
233 // one via Concatenate() operations or via SetInput().
234 int GetNumberOfConcatenatedTransforms() {
235 return this->Concatenation->GetNumberOfTransforms() +
236 (this->Input == NULL ? 0 : 1); };
239 // Get one of the concatenated transformations as a vtkAbstractTransform.
240 // These transformations are applied, in series, every time the
241 // transformation of a coordinate occurs. This method is provided
242 // to make it possible to decompose a transformation into its
243 // constituents, for example to save a transformation to a file.
244 vtkHomogeneousTransform *GetConcatenatedTransform(int i) {
245 if (this->Input == NULL) {
246 return (vtkHomogeneousTransform *)this->Concatenation->GetTransform(i); }
247 else if (i < this->Concatenation->GetNumberOfPreTransforms()) {
248 return (vtkHomogeneousTransform *)this->Concatenation->GetTransform(i); }
249 else if (i > this->Concatenation->GetNumberOfPreTransforms()) {
250 return (vtkHomogeneousTransform*)this->Concatenation->GetTransform(i-1);}
251 else if (this->GetInverseFlag()) {
252 return (vtkHomogeneousTransform *)this->Input->GetInverse(); }
254 return (vtkHomogeneousTransform *)this->Input; } };
257 // Set the input for this transformation. This will be used as the
258 // base transformation if it is set. This method allows you to build
259 // a transform pipeline: if the input is modified, then this transformation
260 // will automatically update accordingly. Note that the InverseFlag,
261 // controlled via Inverse(), determines whether this transformation
262 // will use the Input or the inverse of the Input.
263 void SetInput(vtkHomogeneousTransform *input);
264 vtkHomogeneousTransform *GetInput() { return this->Input; };
267 // Get the inverse flag of the transformation. This controls
268 // whether it is the Input or the inverse of the Input that
269 // is used as the base transformation. The InverseFlag is
270 // flipped every time Inverse() is called. The InverseFlag
271 // is off when a transform is first created.
272 int GetInverseFlag() {
273 return this->Concatenation->GetInverseFlag(); };
276 // Pushes the current transformation onto the transformation stack.
277 void Push() { if (this->Stack == NULL) {
278 this->Stack = vtkTransformConcatenationStack::New(); }
279 this->Stack->Push(&this->Concatenation);
283 // Deletes the transformation on the top of the stack and sets the top
284 // to the next transformation on the stack.
285 void Pop() { if (this->Stack == NULL) { return; }
286 this->Stack->Pop(&this->Concatenation);
290 // Make a new transform of the same type -- you are responsible for
291 // deleting the transform when you are done with it.
292 vtkAbstractTransform *MakeTransform();
295 // Check for self-reference. Will return true if concatenating
296 // with the specified transform, setting it to be our inverse,
297 // or setting it to be our input will create a circular reference.
298 // CircuitCheck is automatically called by SetInput(), SetInverse(),
299 // and Concatenate(vtkXTransform *). Avoid using this function,
300 // it is experimental.
301 int CircuitCheck(vtkAbstractTransform *transform);
304 // Override GetMTime to account for input and concatenation.
305 unsigned long GetMTime();
308 vtkPerspectiveTransform();
309 ~vtkPerspectiveTransform();
311 void InternalDeepCopy(vtkAbstractTransform *t);
312 void InternalUpdate();
314 vtkHomogeneousTransform *Input;
315 vtkTransformConcatenation *Concatenation;
316 vtkTransformConcatenationStack *Stack;
319 vtkPerspectiveTransform(const vtkPerspectiveTransform&); // Not implemented
320 void operator=(const vtkPerspectiveTransform&); // Not implemented