1/*
2---------------------------------------------------------------------------
3Open Asset Import Library (assimp)
4---------------------------------------------------------------------------
5
6Copyright (c) 2006-2017, assimp team
7
8
9All rights reserved.
10
11Redistribution and use of this software in source and binary forms,
12with or without modification, are permitted provided that the following
13conditions are met:
14
15* Redistributions of source code must retain the above
16 copyright notice, this list of conditions and the
17 following disclaimer.
18
19* Redistributions in binary form must reproduce the above
20 copyright notice, this list of conditions and the
21 following disclaimer in the documentation and/or other
22 materials provided with the distribution.
23
24* Neither the name of the assimp team, nor the names of its
25 contributors may be used to endorse or promote products
26 derived from this software without specific prior
27 written permission of the assimp team.
28
29THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
30"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
31LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
32A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
33OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
34SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
35LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
36DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
37THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
38(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
39OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
40---------------------------------------------------------------------------
41*/
42
43/** @file camera.h
44 * @brief Defines the aiCamera data structure
45 */
46
47#pragma once
48#ifndef AI_CAMERA_H_INC
49#define AI_CAMERA_H_INC
50
51#include "types.h"
52
53#ifdef __cplusplus
54extern "C" {
55#endif
56
57// ---------------------------------------------------------------------------
58/** Helper structure to describe a virtual camera.
59 *
60 * Cameras have a representation in the node graph and can be animated.
61 * An important aspect is that the camera itself is also part of the
62 * scenegraph. This means, any values such as the look-at vector are not
63 * *absolute*, they're <b>relative</b> to the coordinate system defined
64 * by the node which corresponds to the camera. This allows for camera
65 * animations. For static cameras parameters like the 'look-at' or 'up' vectors
66 * are usually specified directly in aiCamera, but beware, they could also
67 * be encoded in the node transformation. The following (pseudo)code sample
68 * shows how to do it: <br><br>
69 * @code
70 * // Get the camera matrix for a camera at a specific time
71 * // if the node hierarchy for the camera does not contain
72 * // at least one animated node this is a static computation
73 * get-camera-matrix (node sceneRoot, camera cam) : matrix
74 * {
75 * node cnd = find-node-for-camera(cam)
76 * matrix cmt = identity()
77 *
78 * // as usual - get the absolute camera transformation for this frame
79 * for each node nd in hierarchy from sceneRoot to cnd
80 * matrix cur
81 * if (is-animated(nd))
82 * cur = eval-animation(nd)
83 * else cur = nd->mTransformation;
84 * cmt = mult-matrices( cmt, cur )
85 * end for
86 *
87 * // now multiply with the camera's own local transform
88 * cam = mult-matrices (cam, get-camera-matrix(cmt) )
89 * }
90 * @endcode
91 *
92 * @note some file formats (such as 3DS, ASE) export a "target point" -
93 * the point the camera is looking at (it can even be animated). Assimp
94 * writes the target point as a subnode of the camera's main node,
95 * called "<camName>.Target". However this is just additional information
96 * then the transformation tracks of the camera main node make the
97 * camera already look in the right direction.
98 *
99*/
100struct aiCamera
101{
102 /** The name of the camera.
103 *
104 * There must be a node in the scenegraph with the same name.
105 * This node specifies the position of the camera in the scene
106 * hierarchy and can be animated.
107 */
108 C_STRUCT aiString mName;
109
110 /** Position of the camera relative to the coordinate space
111 * defined by the corresponding node.
112 *
113 * The default value is 0|0|0.
114 */
115 C_STRUCT aiVector3D mPosition;
116
117
118 /** 'Up' - vector of the camera coordinate system relative to
119 * the coordinate space defined by the corresponding node.
120 *
121 * The 'right' vector of the camera coordinate system is
122 * the cross product of the up and lookAt vectors.
123 * The default value is 0|1|0. The vector
124 * may be normalized, but it needn't.
125 */
126 C_STRUCT aiVector3D mUp;
127
128
129 /** 'LookAt' - vector of the camera coordinate system relative to
130 * the coordinate space defined by the corresponding node.
131 *
132 * This is the viewing direction of the user.
133 * The default value is 0|0|1. The vector
134 * may be normalized, but it needn't.
135 */
136 C_STRUCT aiVector3D mLookAt;
137
138
139 /** Half horizontal field of view angle, in radians.
140 *
141 * The field of view angle is the angle between the center
142 * line of the screen and the left or right border.
143 * The default value is 1/4PI.
144 */
145 float mHorizontalFOV;
146
147 /** Distance of the near clipping plane from the camera.
148 *
149 * The value may not be 0.f (for arithmetic reasons to prevent
150 * a division through zero). The default value is 0.1f.
151 */
152 float mClipPlaneNear;
153
154 /** Distance of the far clipping plane from the camera.
155 *
156 * The far clipping plane must, of course, be further away than the
157 * near clipping plane. The default value is 1000.f. The ratio
158 * between the near and the far plane should not be too
159 * large (between 1000-10000 should be ok) to avoid floating-point
160 * inaccuracies which could lead to z-fighting.
161 */
162 float mClipPlaneFar;
163
164
165 /** Screen aspect ratio.
166 *
167 * This is the ration between the width and the height of the
168 * screen. Typical values are 4/3, 1/2 or 1/1. This value is
169 * 0 if the aspect ratio is not defined in the source file.
170 * 0 is also the default value.
171 */
172 float mAspect;
173
174#ifdef __cplusplus
175
176 aiCamera()
177 : mUp (0.f,1.f,0.f)
178 , mLookAt (0.f,0.f,1.f)
179 , mHorizontalFOV (0.25f * (float)AI_MATH_PI)
180 , mClipPlaneNear (0.1f)
181 , mClipPlaneFar (1000.f)
182 , mAspect (0.f)
183 {}
184
185 /** @brief Get a *right-handed* camera matrix from me
186 * @param out Camera matrix to be filled
187 */
188 void GetCameraMatrix (aiMatrix4x4& out) const
189 {
190 /** todo: test ... should work, but i'm not absolutely sure */
191
192 /** We don't know whether these vectors are already normalized ...*/
193 aiVector3D zaxis = mLookAt; zaxis.Normalize();
194 aiVector3D yaxis = mUp; yaxis.Normalize();
195 aiVector3D xaxis = mUp^mLookAt; xaxis.Normalize();
196
197 out.a4 = -(xaxis * mPosition);
198 out.b4 = -(yaxis * mPosition);
199 out.c4 = -(zaxis * mPosition);
200
201 out.a1 = xaxis.x;
202 out.a2 = xaxis.y;
203 out.a3 = xaxis.z;
204
205 out.b1 = yaxis.x;
206 out.b2 = yaxis.y;
207 out.b3 = yaxis.z;
208
209 out.c1 = zaxis.x;
210 out.c2 = zaxis.y;
211 out.c3 = zaxis.z;
212
213 out.d1 = out.d2 = out.d3 = 0.f;
214 out.d4 = 1.f;
215 }
216
217#endif
218};
219
220
221#ifdef __cplusplus
222}
223#endif
224
225#endif // AI_CAMERA_H_INC
226