BGE PyAPI
[blender.git] / source / gameengine / Ketsji / KX_Camera.h
1 /*
2  * $Id$
3  *
4  * ***** BEGIN GPL LICENSE BLOCK *****
5  *
6  * This program is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU General Public License
8  * as published by the Free Software Foundation; either version 2
9  * of the License, or (at your option) any later version.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program; if not, write to the Free Software Foundation,
18  * Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
19  *
20  * The Original Code is Copyright (C) 2001-2002 by NaN Holding BV.
21  * All rights reserved.
22  *
23  * The Original Code is: all of this file.
24  *
25  * Contributor(s): none yet.
26  *
27  * ***** END GPL LICENSE BLOCK *****
28  * Camera in the gameengine. Cameras are also used for views.
29  */
30
31 #ifndef __KX_CAMERA
32 #define __KX_CAMERA
33
34
35 #include "MT_Transform.h"
36 #include "MT_Matrix3x3.h"
37 #include "MT_Matrix4x4.h"
38 #include "MT_Vector3.h"
39 #include "MT_Point3.h"
40 #include "KX_GameObject.h"
41 #include "IntValue.h"
42 #include "RAS_CameraData.h"
43
44 class KX_Camera : public KX_GameObject
45 {
46         Py_Header;
47 protected:
48         friend class KX_Scene;
49         /** Camera parameters (clips distances, focal lenght). These
50          * params are closely tied to Blender. In the gameengine, only the
51          * projection and modelview matrices are relevant. There's a
52          * conversion being done in the engine class. Why is it stored
53          * here? It doesn't really have a function here. */
54         RAS_CameraData  m_camdata;
55
56         // Never used, I think...
57 //      void MoveTo(const MT_Point3& movevec)
58 //      {
59                 /*MT_Transform camtrans;
60                 camtrans.invert(m_trans1);
61                 MT_Matrix3x3 camorient = camtrans.getBasis();
62                 camtrans.translate(camorient.inverse()*movevec);
63                 m_trans1.invert(camtrans);
64                 */
65 //      }
66
67         /**
68          * Storage for the projection matrix that is passed to the
69          * rasterizer. */
70         MT_Matrix4x4 m_projection_matrix;
71         //MT_Matrix4x4 m_projection_matrix1;
72
73         /**
74          * Storage for the modelview matrix that is passed to the
75          * rasterizer. */
76         MT_Matrix4x4 m_modelview_matrix;
77         
78         /**
79          * true if the view frustum (modelview/projection matrix)
80          * has changed - the clip planes (m_planes) will have to be
81          * regenerated.
82          */
83         bool         m_dirty;
84         /**
85          * true if the frustum planes have been normalized.
86          */
87         bool         m_normalized;
88         
89         /**
90          * View Frustum clip planes.
91          */
92         MT_Vector4   m_planes[6];
93         
94         /**
95          * This camera is frustum culling.
96          * Some cameras (ie if the game was started from a non camera view should not cull.)
97          */
98         bool         m_frustum_culling;
99         
100         /**
101          * true if this camera has a valid projection matrix.
102          */
103         bool         m_set_projection_matrix;
104         
105         /**
106          * The center point of the frustum.
107          */
108         MT_Point3    m_frustum_center;
109         MT_Scalar    m_frustum_radius;
110         bool         m_set_frustum_center;
111
112         /**
113          * Extracts the camera clip frames from the projection and world-to-camera matrices.
114          */
115         void ExtractClipPlanes();
116         /**
117          * Normalize the camera clip frames.
118          */
119         void NormalizeClipPlanes();
120         /**
121          * Extracts the bound sphere of the view frustum.
122          */
123         void ExtractFrustumSphere();
124         /**
125          * return the clip plane
126          */
127         MT_Vector4 *GetNormalizedClipPlanes()
128         {
129                 ExtractClipPlanes();
130                 NormalizeClipPlanes();
131                 return m_planes;
132         }
133
134 public:
135
136         enum { INSIDE, INTERSECT, OUTSIDE } ;
137
138         KX_Camera(void* sgReplicationInfo,SG_Callbacks callbacks,const RAS_CameraData& camdata, bool frustum_culling = true, PyTypeObject *T = &Type);
139         virtual ~KX_Camera();
140         
141         /** 
142          * Inherited from CValue -- return a new copy of this
143          * instance allocated on the heap. Ownership of the new 
144          * object belongs with the caller.
145          */
146         virtual CValue*                         
147         GetReplica(
148         );
149
150         MT_Transform            GetWorldToCamera() const;
151         MT_Transform            GetCameraToWorld() const;
152
153         /**
154          * Not implemented.
155          */
156         void                            CorrectLookUp(MT_Scalar speed);
157         const MT_Point3         GetCameraLocation() const;
158
159         /* I want the camera orientation as well. */
160         const MT_Quaternion GetCameraOrientation() const;
161                 
162         /** Sets the projection matrix that is used by the rasterizer. */
163         void                            SetProjectionMatrix(const MT_Matrix4x4 & mat);
164
165         /** Sets the modelview matrix that is used by the rasterizer. */
166         void                            SetModelviewMatrix(const MT_Matrix4x4 & mat);
167                 
168         /** Gets the projection matrix that is used by the rasterizer. */
169         const MT_Matrix4x4&             GetProjectionMatrix() const;
170         
171         /** returns true if this camera has been set a projection matrix. */
172         bool                            hasValidProjectionMatrix() const;
173         
174         /** Sets the validity of the projection matrix.  Call this if you change camera
175             data (eg lens, near plane, far plane) and require the projection matrix to be
176             recalculated.
177          */
178         void                            InvalidateProjectionMatrix(bool valid = false);
179         
180         /** Gets the modelview matrix that is used by the rasterizer. 
181          *  @warning If the Camera is a dynamic object then this method may return garbage.  Use GetCameraToWorld() instead.
182          */
183         const MT_Matrix4x4&             GetModelviewMatrix() const;
184
185         /** Gets the aperture. */
186         float                           GetLens() const;
187         /** Gets the ortho scale. */
188         float                           GetScale() const;
189         /** Gets the near clip distance. */
190         float                           GetCameraNear() const;
191         /** Gets the far clip distance. */
192         float                           GetCameraFar() const;
193         /** Gets the focal length (only used for stereo rendering) */
194         float                           GetFocalLength() const;
195         /** Gets all camera data. */
196         RAS_CameraData*         GetCameraData();
197         
198         /**
199          * Tests if the given sphere is inside this camera's view frustum.
200          *
201          * @param center The center of the sphere, in world coordinates.
202          * @param radius The radius of the sphere.
203          * @return INSIDE, INTERSECT, or OUTSIDE depending on the sphere's relation to the frustum.
204          */
205         int SphereInsideFrustum(const MT_Point3& center, const MT_Scalar &radius);
206         /**
207          * Tests the given eight corners of a box with the view frustum.
208          *
209          * @param box a pointer to eight MT_Point3 representing the world coordinates of the corners of the box.
210          * @return INSIDE, INTERSECT, or OUTSIDE depending on the box's relation to the frustum.
211          */
212         int BoxInsideFrustum(const MT_Point3 *box);
213         /**
214          * Tests the given point against the view frustum.
215          * @return true if the given point is inside or on the view frustum; false if it is outside.
216          */
217         bool PointInsideFrustum(const MT_Point3& x);
218         
219         /**
220          * Gets this camera's culling status.
221          */
222         bool GetFrustumCulling() const;
223         
224         /**
225          * Sets this camera's viewport status.
226          */
227         void EnableViewport(bool viewport);
228         
229         /**
230          * Sets this camera's viewport.
231          */
232         void SetViewport(int left, int bottom, int right, int top);
233         
234         /**
235          * Gets this camera's viewport status.
236          */
237         bool GetViewport() const;
238         
239         /**
240          * Gets this camera's viewport left.
241          */
242         int GetViewportLeft() const;
243         
244         /**
245          * Gets this camera's viewport bottom.
246          */
247         int GetViewportBottom() const;
248         
249         /**
250          * Gets this camera's viewport right.
251          */
252         int GetViewportRight() const;
253         
254         /**
255          * Gets this camera's viewport top.
256          */
257         int GetViewportTop() const;
258
259
260         KX_PYMETHOD_DOC_VARARGS(KX_Camera, sphereInsideFrustum);
261         KX_PYMETHOD_DOC_O(KX_Camera, boxInsideFrustum);
262         KX_PYMETHOD_DOC_O(KX_Camera, pointInsideFrustum);
263         
264         KX_PYMETHOD_DOC_NOARGS(KX_Camera, getCameraToWorld);
265         KX_PYMETHOD_DOC_NOARGS(KX_Camera, getWorldToCamera);
266         KX_PYMETHOD_DOC_NOARGS(KX_Camera, getProjectionMatrix);
267         KX_PYMETHOD_DOC_O(KX_Camera, setProjectionMatrix);
268         
269         KX_PYMETHOD_DOC_O(KX_Camera, enableViewport);
270         KX_PYMETHOD_DOC_VARARGS(KX_Camera, setViewport);        
271         KX_PYMETHOD_DOC_NOARGS(KX_Camera, setOnTop);    
272
273         virtual PyObject* py_getattro(PyObject *attr); /* lens, near, far, projection_matrix */
274         virtual PyObject* py_getattro_dict();
275         virtual int       py_setattro(PyObject *attr, PyObject *pyvalue);
276         
277         static PyObject*        pyattr_get_perspective(void *self_v, const KX_PYATTRIBUTE_DEF *attrdef);
278         static int                      pyattr_set_perspective(void *self_v, const KX_PYATTRIBUTE_DEF *attrdef, PyObject *value);
279
280         static PyObject*        pyattr_get_lens(void *self_v, const KX_PYATTRIBUTE_DEF *attrdef);
281         static int                      pyattr_set_lens(void *self_v, const KX_PYATTRIBUTE_DEF *attrdef, PyObject *value);
282         static PyObject*        pyattr_get_near(void *self_v, const KX_PYATTRIBUTE_DEF *attrdef);
283         static int                      pyattr_set_near(void *self_v, const KX_PYATTRIBUTE_DEF *attrdef, PyObject *value);
284         static PyObject*        pyattr_get_far(void *self_v, const KX_PYATTRIBUTE_DEF *attrdef);
285         static int                      pyattr_set_far(void *self_v, const KX_PYATTRIBUTE_DEF *attrdef, PyObject *value);
286         
287         static PyObject*        pyattr_get_is_viewport(void *self_v, const KX_PYATTRIBUTE_DEF *attrdef);
288         static int                      pyattr_set_is_viewport(void *self_v, const KX_PYATTRIBUTE_DEF *attrdef, PyObject *value);
289         
290         static PyObject*        pyattr_get_projection_matrix(void *self_v, const KX_PYATTRIBUTE_DEF *attrdef);
291         static int                      pyattr_set_projection_matrix(void *self_v, const KX_PYATTRIBUTE_DEF *attrdef, PyObject *value);
292         
293         static PyObject*        pyattr_get_modelview_matrix(void *self_v, const KX_PYATTRIBUTE_DEF *attrdef);
294         static PyObject*        pyattr_get_camera_to_world(void *self_v, const KX_PYATTRIBUTE_DEF *attrdef);
295         static PyObject*        pyattr_get_world_to_camera(void *self_v, const KX_PYATTRIBUTE_DEF *attrdef);
296         
297         static PyObject*        pyattr_get_INSIDE(void *self_v, const KX_PYATTRIBUTE_DEF *attrdef);
298         static PyObject*        pyattr_get_OUTSIDE(void *self_v, const KX_PYATTRIBUTE_DEF *attrdef);
299         static PyObject*        pyattr_get_INTERSECT(void *self_v, const KX_PYATTRIBUTE_DEF *attrdef);
300 };
301
302 #endif //__KX_CAMERA
303