1
# $Id: KX_Camera.py,v 1.6 2004/07/20 12:07:06 kester Exp $
2
# Documentation for Camera game objects.
3
from KX_GameObject import *
5
class KX_Camera(KX_GameObject):
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()
14
@ivar lens: The camera's lens value.
16
@ivar near: The camera's near clip distance.
18
@ivar far: The camera's far clip distance.
20
@ivar perspective: True if this camera has a perspective transform.
22
If perspective is False, this camera has an orthographic transform.
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.
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]]
45
def sphereInsideFrustum(centre, radius):
47
Tests the given sphere against the view frustum.
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
53
@return: INSIDE, OUTSIDE or INTERSECT
57
co = GameLogic.getCurrentController()
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 !
65
# Sphere is outside frustum
67
def boxInsideFrustum(box):
69
Tests the given box against the view frustum.
73
co = GameLogic.getCurrentController()
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])
87
if (cam.boxInsideFrustum(box) != cam.OUTSIDE):
88
# Box is inside/intersects frustum !
89
# Do something useful !
91
# Box is outside the frustum !
93
@return: INSIDE, OUTSIDE or INTERSECT
95
@param box: Eight (8) corner points of the box (in world coordinates.)
97
def pointInsideFrustum(point):
99
Tests the given point against the view frustum.
103
co = GameLogic.getCurrentController()
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 !
111
# Box is outside the frustum !
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.)
118
def getCameraToWorld():
120
Returns the camera-to-world transform.
122
@rtype: matrix (4x4 list)
123
@return: the camera-to-world transform matrix.
125
def getWorldToCamera():
127
Returns the world-to-camera transform.
129
This returns the inverse matrix of getCameraToWorld().
131
@rtype: matrix (4x4 list)
132
@return: the world-to-camera transform matrix.
134
def getProjectionMatrix():
136
Returns the camera's projection matrix.
138
@rtype: matrix (4x4 list)
139
@return: the camera's projection matrix.
141
def setProjectionMatrix(matrix):
143
Sets the camera's projection matrix.
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
151
def Scale(matrix, size):
154
matrix[y][x] = matrix[y][x] * size[y]
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 ]]
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 ]]
172
# Generate an isometric projection matrix
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])
180
co = GameLogic.getCurrentController()
182
cam.setProjectionMatrix(Perspective(cam)))
184
@type matrix: 4x4 matrix.
185
@param matrix: The new projection matrix for this camera.