Updates to GamePython Reference.
[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. (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                         def Scale(matrix, size):
143                                 for y in range(4):
144                                         for x in range(4):
145                                                 matrix[y][x] = matrix[y][x] * size[y]
146                                 return matrix
147                         
148                         # Generate a perspective projection matrix
149                         def Perspective(cam):
150                                 return [[cam.near, 0.0     ,  0.0                                  ,  0.0                                      ],
151                                         [0.0     , cam.near,  0.0                                  ,  0.0                                      ],
152                                         [0.0     , 0.0     , -(cam.far+cam.near)/(cam.far-cam.near), -2.0*cam.far*cam.near/(cam.far - cam.near)],
153                                         [0.0     , 0.0     , -1.0                                  ,  0.0                                      ]]
154                         
155                         # Generate an orthographic projection matrix
156                         # You will need to scale the camera
157                         def Orthographic(cam):
158                                 return [[1.0/cam.scaling[0], 0.0               ,  0.0                   ,  0.0                                  ],
159                                         [0.0               , 1.0/cam.scaling[1],  0.0                   ,  0.0                                  ],
160                                         [0.0               , 0.0               , -2.0/(cam.far-cam.near), -(cam.far+cam.near)/(cam.far-cam.near)],
161                                         [0.0               , 0.0               ,  0.0                   ,  1.0                                  ]]
162                         
163                         # Generate an isometric projection matrix
164                         def Isometric(cam):
165                                 return Scale([[0.707, 0.0  , 0.707, 0.0],
166                                               [0.408, 0.816,-0.408, 0.0],
167                                               [0.0  , 0.0  , 0.0  , 0.0],
168                                               [0.0  , 0.0  , 0.0  , 1.0]],
169                                               [1.0/cam.scaling[0], 1.0/cam.scaling[1], 1.0/cam.scaling[2], 1.0])
170                         
171                         co = GameLogic.getCurrentController()
172                         cam = co.getOwner()
173                         cam.setProjectionMatrix(Perspective(cam)))
174                 
175                 @type matrix: 4x4 matrix.
176                 @param matrix: The new projection matrix for this camera.
177                 """
178