Module KX_Camera :: Class KX_Camera

Class KX_Camera

KX_GameObject.KX_GameObject --+
                              |
                             KX_Camera

A Camera object.

Instance Methods

sphereInsideFrustum(centre, radius)
Tests the given sphere against the view frustum.

source code

boxInsideFrustum(box)
Tests the given box against the view frustum.

source code

boolean

pointInsideFrustum(point)
Tests the given point against the view frustum.

source code

matrix (4x4 list)

getCameraToWorld()
Returns the camera-to-world transform.

source code

matrix (4x4 list)

getWorldToCamera()
Returns the world-to-camera transform.

source code

matrix (4x4 list)

getProjectionMatrix()
Returns the camera's projection matrix.

source code

setProjectionMatrix(matrix)
Sets the camera's projection matrix.

source code

Inherited from KX_GameObject.KX_GameObject: applyImpulse, disableRigidBody, enableRigidBody, getDistanceTo, getLinearVelocity, getMass, getMesh, getOrientation, getParent, getPhysicsId, getPosition, getReactionForce, getVelocity, rayCastTo, removeParent, restoreDynamics, setOrientation, setParent, setPosition, setVisible, suspendDynamics

Constants
Instance Variables
4x4 Matrix [[float]]	camera_to_world This camera's camera to world transform.
float	far The camera's far clip distance.
boolean	frustum_culling True if this camera is frustum culling.
float	lens The camera's lens value.
4x4 Matrix [[float]]	modelview_matrix This camera's 4x4 model view matrix.
float	near The camera's near clip distance.
boolean	perspective True if this camera has a perspective transform.
4x4 Matrix [[float]]	projection_matrix This camera's 4x4 projection matrix.
4x4 Matrix [[float]]	world_to_camera This camera's world to camera transform.
Inherited from `KX_GameObject.KX_GameObject`: `mass`, `name`, `orientation`, `parent`, `position`, `scaling`, `visible`
	INSIDE see sphereInsideFrustum() and boxInsideFrustum()
	INTERSECT see sphereInsideFrustum() and boxInsideFrustum()
	OUTSIDE see sphereInsideFrustum() and boxInsideFrustum()

Method Details

sphereInsideFrustum(centre, radius)

source code

Tests the given sphere against the view frustum.

Parameters:

centre (list [x, y, z]) - The centre of the sphere (in world coordinates.)
radius (float) - the radius of the sphere

Returns:

INSIDE, OUTSIDE or INTERSECT

Example:

       import GameLogic
       co = GameLogic.getCurrentController()
       cam = co.GetOwner()
       
       # A sphere of radius 4.0 located at [x, y, z] = [1.0, 1.0, 1.0]
       if (cam.sphereInsideFrustum([1.0, 1.0, 1.0], 4) != cam.OUTSIDE):
               # Sphere is inside frustum !
               # Do something useful !
       else:
               # Sphere is outside frustum

boxInsideFrustum(box)

source code

Tests the given box against the view frustum.

Example:

       import GameLogic
       co = GameLogic.getCurrentController()
       cam = co.GetOwner()
       
       # Box to test...
       box = []
       box.append([-1.0, -1.0, -1.0])
       box.append([-1.0, -1.0,  1.0])
       box.append([-1.0,  1.0, -1.0])
       box.append([-1.0,  1.0,  1.0])
       box.append([ 1.0, -1.0, -1.0])
       box.append([ 1.0, -1.0,  1.0])
       box.append([ 1.0,  1.0, -1.0])
       box.append([ 1.0,  1.0,  1.0])
       
       if (cam.boxInsideFrustum(box) != cam.OUTSIDE):
               # Box is inside/intersects frustum !
               # Do something useful !
       else:
               # Box is outside the frustum !

Parameters:

box (list) - Eight (8) corner points of the box (in world coordinates.)

Returns:

INSIDE, OUTSIDE or INTERSECT

pointInsideFrustum(point)

source code

Tests the given point against the view frustum.

Example:

       import GameLogic
       co = GameLogic.getCurrentController()
       cam = co.GetOwner()

       # Test point [0.0, 0.0, 0.0]
       if (cam.pointInsideFrustum([0.0, 0.0, 0.0])):
               # Point is inside frustum !
               # Do something useful !
       else:
               # Box is outside the frustum !

Parameters:

point ([x, y, z]) - The point to test (in world coordinates.)

Returns: boolean

True if the given point is inside this camera's viewing frustum.

getCameraToWorld()

source code

Returns the camera-to-world transform.

Returns: matrix (4x4 list): the camera-to-world transform matrix.

getWorldToCamera()

source code

Returns the world-to-camera transform.

This returns the inverse matrix of getCameraToWorld().

Returns: matrix (4x4 list): the world-to-camera transform matrix.

getProjectionMatrix()

source code

Returns the camera's projection matrix.

Returns: matrix (4x4 list): the camera's projection matrix.

setProjectionMatrix(matrix)

source code

Sets the camera's projection matrix.

You should use normalised device coordinates for the clipping planes: left = -1.0, right = 1.0, top = 1.0, bottom = -1.0, near = cam.near, far = cam.far

Example:

       import GameLogic

       def Scale(matrix, size):
               for y in range(4):
                       for x in range(4):
                               matrix[y][x] = matrix[y][x] * size[y]
               return matrix
       
       # Generate a perspective projection matrix
       def Perspective(cam):
               return [[cam.near, 0.0     ,  0.0                                  ,  0.0                                      ],
                       [0.0     , cam.near,  0.0                                  ,  0.0                                      ],
                       [0.0     , 0.0     , -(cam.far+cam.near)/(cam.far-cam.near), -2.0*cam.far*cam.near/(cam.far - cam.near)],
                       [0.0     , 0.0     , -1.0                                  ,  0.0                                      ]]
       
       # Generate an orthographic projection matrix
       # You will need to scale the camera
       def Orthographic(cam):
               return [[1.0/cam.scaling[0], 0.0               ,  0.0                   ,  0.0                                  ],
                       [0.0               , 1.0/cam.scaling[1],  0.0                   ,  0.0                                  ],
                       [0.0               , 0.0               , -2.0/(cam.far-cam.near), -(cam.far+cam.near)/(cam.far-cam.near)],
                       [0.0               , 0.0               ,  0.0                   ,  1.0                                  ]]
       
       # Generate an isometric projection matrix
       def Isometric(cam):
               return Scale([[0.707, 0.0  , 0.707, 0.0],
                             [0.408, 0.816,-0.408, 0.0],
                             [0.0  , 0.0  , 0.0  , 0.0],
                             [0.0  , 0.0  , 0.0  , 1.0]],
                             [1.0/cam.scaling[0], 1.0/cam.scaling[1], 1.0/cam.scaling[2], 1.0])
       
       co = GameLogic.getCurrentController()
       cam = co.getOwner()
       cam.setProjectionMatrix(Perspective(cam)))

Parameters:

matrix (4x4 matrix.) - The new projection matrix for this camera.

Instance Variable Details

camera_to_world

This camera's camera to world transform. (read only) Regenerated every frame from the camera's position and orientation.

Type:: 4x4 Matrix [[float]]

modelview_matrix

This camera's 4x4 model view matrix. (read only) Regenerated every frame from the camera's position and orientation.

Type:: 4x4 Matrix [[float]]

perspective

True if this camera has a perspective transform.

If perspective is False, this camera has an orthographic transform.

Note that the orthographic transform is faked by multiplying the lens attribute by 100.0 and translating the camera 100.0 along the z axis.

This is the same as Blender. If you want a true orthographic transform, see setProjectionMatrix.

Type:: boolean

world_to_camera

This camera's world to camera transform. (read only) Regenerated every frame from the camera's position and orientation. This is camera_to_world inverted.

Type:: 4x4 Matrix [[float]]