729380ddfb00fa4478129cd2437ccdec499940bd
[blender.git] / source / gameengine / PyDoc / KX_Camera.py
1 # $Id$
2 # Documentation for Camera game objects.
3 from KX_GameObject import *
4
5 class KX_Camera(KX_GameObject):
6         """
7         A Camera object.
8         
9         @cvar INSIDE: see sphereInsideFrustum and boxInsideFrustum
10         @cvar INTERSECT: see sphereInsideFrustum and boxInsideFrustum
11         @cvar OUTSIDE: see sphereInsideFrustum and boxInsideFrustum
12         Attributes:
13         @cvar lens: The camera's lens value. float
14         @cvar near: The camera's near clip distance. float
15         @cvar far: The camera's far clip distance. float
16         @cvar frustum_culling: True if this camera is frustum culling. boolean
17         @cvar projection_matrix: This camera's 4x4 projection matrix. [[float]]
18         @cvar modelview_matrix: This camera's 4x4 model view matrix. [[float]] (read only)
19         Regenerated every frame from the camera's position and orientation.
20         @cvar camera_to_world: This camera's camera to world transform. [[float]] (read only)
21         Regenerated every frame from the camera's position and orientation.
22         @cvar world_to_camera: This camera's world to camera transform. [[float]] (read only)
23         Regenerated every frame from the camera's position and orientation.
24         This is camera_to_world inverted.
25         """
26         
27         def sphereInsideFrustum(centre, radius):
28                 """
29                 Tests the given sphere against the view frustum.
30                 
31                 @return: INSIDE, OUTSIDE or INTERSECT
32                 @type centre: list
33                 @param centre: The centre of the sphere (in world coordinates.)
34                 @type radius: float
35                 @param radius: the radius of the sphere
36                 
37                 Example:
38                 import GameLogic
39                 co = GameLogic.getCurrentController()
40                 cam = co.GetOwner()
41                 
42                 # A sphere of radius 4.0 located at [x, y, z] = [1.0, 1.0, 1.0]
43                 if (cam.sphereInsideFrustum([1.0, 1.0, 1.0], 4) != cam.OUTSIDE):
44                         # Sphere is inside frustum !
45                         # Do something useful !
46                 else:
47                         # Sphere is outside frustum
48                 """
49         def boxInsideFrustum(box):
50                 """
51                 Tests the given box against the view frustum.
52                 
53                 @return: INSIDE, OUTSIDE or INTERSECT
54                 @type box: list
55                 @param box: Eight (8) corner points of the box (in world coordinates.)
56                 
57                 Example:
58                 @verbatim{
59                 import GameLogic
60                 co = GameLogic.getCurrentController()
61                 cam = co.GetOwner()
62                 
63                 # Box to test...
64                 box = []
65                 box.append([-1.0, -1.0, -1.0])
66                 box.append([-1.0, -1.0,  1.0])
67                 box.append([-1.0,  1.0, -1.0])
68                 box.append([-1.0,  1.0,  1.0])
69                 box.append([ 1.0, -1.0, -1.0])
70                 box.append([ 1.0, -1.0,  1.0])
71                 box.append([ 1.0,  1.0, -1.0])
72                 box.append([ 1.0,  1.0,  1.0])
73                 
74                 if (cam.boxInsideFrustum(box) != cam.OUTSIDE):
75                         # Box is inside/intersects frustum !
76                         # Do something useful !
77                 else:
78                         # Box is outside the frustum !
79                 }
80                 """
81         def pointInsideFrustum(point):
82                 """
83                 Tests the given point against the view frustum.
84                 
85                 @rtype: boolean
86                 @return: True if the given point is inside this camera's viewing frustum.
87                 @type point: [x, y, z]
88                 @param point: The point to test (in world coordinates.)
89                 
90                 Example:
91                 @verbatim{
92                 import GameLogic
93                 co = GameLogic.getCurrentController()
94                 cam = co.GetOwner()
95                 
96                 # Test point [0.0, 0.0, 0.0]"
97                 if (cam.pointInsideFrustum([0.0, 0.0, 0.0])):
98                 # Point is inside frustum !
99                 # Do something useful !
100                 else:
101                 # Box is outside the frustum !
102                 }
103                 """
104         def getCameraToWorld():
105                 """
106                 Returns the camera-to-world transform.
107                 
108                 @rtype: matrix (4x4 list)
109                 @return: the camera-to-world transform matrix.
110                 """
111         def getWorldToCamera():
112                 """
113                 Returns the world-to-camera transform.
114                 
115                 This returns the inverse matrix of getCameraToWorld().
116                 
117                 @rtype: matrix (4x4 list)
118                 @return: the world-to-camera transform matrix.
119                 """
120         def getProjectionMatrix():
121                 """
122                 Returns the camera's projection matrix.
123                 
124                 @rtype: matrix (4x4 list)
125                 @return: the camera's projection matrix.
126                 """
127         def setProjectionMatrix(matrix):
128                 """
129                 Sets the camera's projection matrix.
130                 
131                 You should use normalised device coordinates for the clipping planes:
132                 left = -1.0, right = 1.0, top = 1.0, bottom = -1.0, near = cam.near, far = cam.far
133                 
134                 @type matrix: 4x4 matrix.
135                 @param matrix: The new projection matrix for this camera.
136                 
137                 Example:
138                 @verbatim{
139                 import GameLogic
140                 
141                 # Generate an identiy matrix.
142                 def Identity():
143                         return [[1.0, 0.0, 0.0, 0.0], [0.0, 1.0, 0.0, 0.0], [0.0, 0.0, 1.0, 0.0], [0.0, 0.0, 0.0, 1.0]]
144                 
145                 # Generate a perspective projection matrix
146                 def Perspective(cam):
147                         return [[cam.near, 0.0     ,  0.0                                  ,  0.0                                      ],
148                                 [0.0     , cam.near,  0.0                                  ,  0.0                                      ],
149                                 [0.0     , 0.0     , -(cam.far+cam.near)/(cam.far-cam.near), -2.0*cam.far*cam.near/(cam.far - cam.near)],
150                                 [0.0     , 0.0     , -1.0                                  ,  0.0                                      ]]
151                 
152                 # Generate an orthographic projection matrix
153                 # You will need to scale the camera
154                 def Orthographic(cam):
155                         return [[1.0/cam.scaling[0], 0.0               ,  0.0                   ,  0.0                                  ],
156                                 [0.0               , 1.0/cam.scaling[1],  0.0                   ,  0.0                                  ],
157                                 [0.0               , 0.0               , -2.0/(cam.far-cam.near), -(cam.far+cam.near)/(cam.far-cam.near)],
158                                 [0.0               , 0.0               ,  0.0                   ,  1.0                                  ]]
159                 
160                 # Generate an isometric projection matrix
161                 def Isometric():
162                         return [[0.866, 0.0  , 0.866, 0.0],
163                                 [0.25 , 0.866,-0.25 , 0.0],
164                                 [0.0  , 0.0  ,-1.0  , 0.0],
165                                 [0.0  , 0.0  , 0.0  , 1.0]]
166                         m = Identity()
167                         m[0][0] = m[0][2] = m[1][1] = 0.8660254037844386
168                         m[1][0] = 0.25
169                         m[1][2] = -0.25
170                         m[3][3] = 1.0
171                         return m
172                 
173                 co = GameLogic.getCurrentController()
174                 cam = co.getOwner()
175                 cam.setProjectionMatrix(Perspective()))
176                 """
177