BGE Epydocs were missing some functions
[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 perspective: True if this camera has a perspective transform. 
21         
22                 If perspective is False, this camera has an orthographic transform.
23                 
24                 Note that the orthographic transform is faked by multiplying the lens attribute
25                 by 100.0 and translating the camera 100.0 along the z axis.
26                 
27                 This is the same as Blender.  If you want a true orthographic transform, see L{setProjectionMatrix}.
28         @type perspective: boolean
29         @ivar frustum_culling: True if this camera is frustum culling. 
30         @type frustum_culling: boolean
31         @ivar projection_matrix: This camera's 4x4 projection matrix.
32         @type projection_matrix: 4x4 Matrix [[float]]
33         @ivar modelview_matrix: This camera's 4x4 model view matrix. (read only)
34                                 Regenerated every frame from the camera's position and orientation.
35         @type modelview_matrix: 4x4 Matrix [[float]] 
36         @ivar camera_to_world: This camera's camera to world transform. (read only)
37                                Regenerated every frame from the camera's position and orientation.
38         @type camera_to_world: 4x4 Matrix [[float]]
39         @ivar world_to_camera: This camera's world to camera transform. (read only)
40                                Regenerated every frame from the camera's position and orientation.
41                                This is camera_to_world inverted.
42         @type world_to_camera: 4x4 Matrix [[float]]
43         """
44         
45         def sphereInsideFrustum(centre, radius):
46                 """
47                 Tests the given sphere against the view frustum.
48                 
49                 @param centre: The centre of the sphere (in world coordinates.)
50                 @type centre: list [x, y, z]
51                 @param radius: the radius of the sphere
52                 @type radius: float
53                 @return: INSIDE, OUTSIDE or INTERSECT
54                 
55                 Example::
56                         import GameLogic
57                         co = GameLogic.getCurrentController()
58                         cam = co.GetOwner()
59                         
60                         # A sphere of radius 4.0 located at [x, y, z] = [1.0, 1.0, 1.0]
61                         if (cam.sphereInsideFrustum([1.0, 1.0, 1.0], 4) != cam.OUTSIDE):
62                                 # Sphere is inside frustum !
63                                 # Do something useful !
64                         else:
65                                 # Sphere is outside frustum
66                 """
67         def boxInsideFrustum(box):
68                 """
69                 Tests the given box against the view frustum.
70                 
71                 Example::
72                         import GameLogic
73                         co = GameLogic.getCurrentController()
74                         cam = co.GetOwner()
75                         
76                         # Box to test...
77                         box = []
78                         box.append([-1.0, -1.0, -1.0])
79                         box.append([-1.0, -1.0,  1.0])
80                         box.append([-1.0,  1.0, -1.0])
81                         box.append([-1.0,  1.0,  1.0])
82                         box.append([ 1.0, -1.0, -1.0])
83                         box.append([ 1.0, -1.0,  1.0])
84                         box.append([ 1.0,  1.0, -1.0])
85                         box.append([ 1.0,  1.0,  1.0])
86                         
87                         if (cam.boxInsideFrustum(box) != cam.OUTSIDE):
88                                 # Box is inside/intersects frustum !
89                                 # Do something useful !
90                         else:
91                                 # Box is outside the frustum !
92                 
93                 @return: INSIDE, OUTSIDE or INTERSECT
94                 @type box: list
95                 @param box: Eight (8) corner points of the box (in world coordinates.)
96                 """
97         def pointInsideFrustum(point):
98                 """
99                 Tests the given point against the view frustum.
100                 
101                 Example::
102                         import GameLogic
103                         co = GameLogic.getCurrentController()
104                         cam = co.GetOwner()
105         
106                         # Test point [0.0, 0.0, 0.0]
107                         if (cam.pointInsideFrustum([0.0, 0.0, 0.0])):
108                                 # Point is inside frustum !
109                                 # Do something useful !
110                         else:
111                                 # Box is outside the frustum !
112                 
113                 @rtype: boolean
114                 @return: True if the given point is inside this camera's viewing frustum.
115                 @type point: [x, y, z]
116                 @param point: The point to test (in world coordinates.)
117                 """
118         def getCameraToWorld():
119                 """
120                 Returns the camera-to-world transform.
121                 
122                 @rtype: matrix (4x4 list)
123                 @return: the camera-to-world transform matrix.
124                 """
125         def getWorldToCamera():
126                 """
127                 Returns the world-to-camera transform.
128                 
129                 This returns the inverse matrix of getCameraToWorld().
130                 
131                 @rtype: matrix (4x4 list)
132                 @return: the world-to-camera transform matrix.
133                 """
134         def getProjectionMatrix():
135                 """
136                 Returns the camera's projection matrix.
137                 
138                 @rtype: matrix (4x4 list)
139                 @return: the camera's projection matrix.
140                 """
141         def setProjectionMatrix(matrix):
142                 """
143                 Sets the camera's projection matrix.
144                 
145                 You should use normalised device coordinates for the clipping planes:
146                 left = -1.0, right = 1.0, top = 1.0, bottom = -1.0, near = cam.near, far = cam.far
147                 
148                 Example::
149                         import GameLogic
150
151                         def Scale(matrix, size):
152                                 for y in range(4):
153                                         for x in range(4):
154                                                 matrix[y][x] = matrix[y][x] * size[y]
155                                 return matrix
156                         
157                         # Generate a perspective projection matrix
158                         def Perspective(cam):
159                                 return [[cam.near, 0.0     ,  0.0                                  ,  0.0                                      ],
160                                         [0.0     , cam.near,  0.0                                  ,  0.0                                      ],
161                                         [0.0     , 0.0     , -(cam.far+cam.near)/(cam.far-cam.near), -2.0*cam.far*cam.near/(cam.far - cam.near)],
162                                         [0.0     , 0.0     , -1.0                                  ,  0.0                                      ]]
163                         
164                         # Generate an orthographic projection matrix
165                         # You will need to scale the camera
166                         def Orthographic(cam):
167                                 return [[1.0/cam.scaling[0], 0.0               ,  0.0                   ,  0.0                                  ],
168                                         [0.0               , 1.0/cam.scaling[1],  0.0                   ,  0.0                                  ],
169                                         [0.0               , 0.0               , -2.0/(cam.far-cam.near), -(cam.far+cam.near)/(cam.far-cam.near)],
170                                         [0.0               , 0.0               ,  0.0                   ,  1.0                                  ]]
171                         
172                         # Generate an isometric projection matrix
173                         def Isometric(cam):
174                                 return Scale([[0.707, 0.0  , 0.707, 0.0],
175                                               [0.408, 0.816,-0.408, 0.0],
176                                               [0.0  , 0.0  , 0.0  , 0.0],
177                                               [0.0  , 0.0  , 0.0  , 1.0]],
178                                               [1.0/cam.scaling[0], 1.0/cam.scaling[1], 1.0/cam.scaling[2], 1.0])
179                         
180                         co = GameLogic.getCurrentController()
181                         cam = co.getOwner()
182                         cam.setProjectionMatrix(Perspective(cam)))
183                 
184                 @type matrix: 4x4 matrix.
185                 @param matrix: The new projection matrix for this camera.
186                 """
187
188         def enableViewport(viewport):
189                 """
190                 Use this camera to draw a viewport on the screen (for split screen games or overlay scenes). The viewport region is defined with L{setViewport}.
191                 
192                 @type viewport: bool
193                 @param viewport: the new viewport status
194                 """
195         def setOnTop():
196                 """
197                 Set this cameras viewport ontop of all other viewport.
198                 """
199         def setViewport(left, bottom, right, top):
200                 """
201                 Sets the region of this viewport on the screen in pixels.
202                 
203                 Use L{Rasterizer.getWindowHeight} L{Rasterizer.getWindowWidth} to calculate values relative to the entire display.
204                 
205                 @type left: int
206                 @type bottom: int
207                 @type right: int
208                 @type top: int
209                 """