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