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