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.
 
boxInsideFrustum(box)
Tests the given box against the view frustum.
boolean
pointInsideFrustum(point)
Tests the given point against the view frustum.
matrix (4x4 list)
getCameraToWorld()
Returns the camera-to-world transform.
matrix (4x4 list)
getWorldToCamera()
Returns the world-to-camera transform.
matrix (4x4 list)
getProjectionMatrix()
Returns the camera's projection matrix.
 
setProjectionMatrix(matrix)
Sets the camera's projection matrix.
 
enableViewport(viewport)
Use this camera to draw a viewport on the screen (for split screen games or overlay scenes).
 
setOnTop()
Set this cameras viewport ontop of all other viewport.
 
setViewport(left, bottom, right, top)
Sets the region of this viewport on the screen in pixels.
 
alignAxisToVect(vect, axis)
Aligns any of the game object's axis along the given vector. (Inherited from KX_GameObject.KX_GameObject)
 
applyForce(force, local=0)
Sets the game object's force. (Inherited from KX_GameObject.KX_GameObject)
 
applyImpulse(point, impulse)
Applies an impulse to the game object. (Inherited from KX_GameObject.KX_GameObject)
 
applyMovement(movement, local=0)
Sets the game object's movement. (Inherited from KX_GameObject.KX_GameObject)
 
applyRotation(rotation, local=0)
Sets the game object's rotation. (Inherited from KX_GameObject.KX_GameObject)
 
applyTorque(torque, local=0)
Sets the game object's torque. (Inherited from KX_GameObject.KX_GameObject)
 
disableRigidBody()
Disables rigid body physics for this object. (Inherited from KX_GameObject.KX_GameObject)
 
enableRigidBody()
Enables rigid body physics for this object. (Inherited from KX_GameObject.KX_GameObject)
 
endObject()
Delete this object, can be used inpace of the EndObject Actuator. (Inherited from KX_GameObject.KX_GameObject)
list [vx, vy, vz]
getAngularVelocity(local=0)
Gets the game object's angular velocity. (Inherited from KX_GameObject.KX_GameObject)
3d vector.
getAxisVect(vect)
Returns the axis vector rotates by the objects worldspace orientation. (Inherited from KX_GameObject.KX_GameObject)
CListValue of KX_GameObject
getChildren()
Return a list of immediate children of this object. (Inherited from KX_GameObject.KX_GameObject)
CListValue of KX_GameObject
getChildrenRecursive()
Return a list of children of this object, including all their childrens children. (Inherited from KX_GameObject.KX_GameObject)
float
getDistanceTo(other)
Returns the distance to another object or point. (Inherited from KX_GameObject.KX_GameObject)
list [vx, vy, vz]
getLinearVelocity(local=0)
Gets the game object's linear velocity. (Inherited from KX_GameObject.KX_GameObject)
float
getMass()
Gets the game object's mass. (Inherited from KX_GameObject.KX_GameObject)
KX_MeshProxy
getMesh(mesh)
Gets the mesh object for this object. (Inherited from KX_GameObject.KX_GameObject)
3x3 rotation matrix
getOrientation()
Gets the game object's orientation. (Inherited from KX_GameObject.KX_GameObject)
KX_GameObject
getParent()
Gets this object's parent. (Inherited from KX_GameObject.KX_GameObject)
 
getPhysicsId()
Returns the user data object associated with this game object's physics controller. (Inherited from KX_GameObject.KX_GameObject)
list [x, y, z]
getPosition()
Gets the game object's position. (Inherited from KX_GameObject.KX_GameObject)
list
getPropertyNames()
Gets a list of all property names. (Inherited from KX_GameObject.KX_GameObject)
list [fx, fy, fz]
getReactionForce()
Gets the game object's reaction force. (Inherited from KX_GameObject.KX_GameObject)
int
getState()
Gets the game object's state bitmask. (Inherited from KX_GameObject.KX_GameObject)
3-tuple (float, 3-tuple (x,y,z), 3-tuple (x,y,z))
getVectTo(other)
Returns the vector and the distance to another object or point. (Inherited from KX_GameObject.KX_GameObject)
list [vx, vy, vz]
getVelocity(point)
Gets the game object's velocity at the specified point. (Inherited from KX_GameObject.KX_GameObject)
boolean
getVisible()
Gets the game object's visible flag. (Inherited from KX_GameObject.KX_GameObject)
3-tuple (KX_GameObject, 3-tuple (x,y,z), 3-tuple (nx,ny,nz)) or 4-tuple (KX_GameObject, 3-tuple (x,y,z), 3-tuple (nx,ny,nz), KX_PolyProxy)
rayCast(objto, objfrom, dist, prop, face, xray, poly)
Look from a point/object to another point/object and find first object hit within dist that matches prop. (Inherited from KX_GameObject.KX_GameObject)
KX_GameObject
rayCastTo(other, dist, prop)
Look towards another point/object and find first object hit within dist that matches prop. (Inherited from KX_GameObject.KX_GameObject)
 
removeParent()
Removes this objects parent. (Inherited from KX_GameObject.KX_GameObject)
 
replaceMesh(mesh_name)
Replace the mesh of this object with a new mesh. (Inherited from KX_GameObject.KX_GameObject)
 
restoreDynamics()
Resumes physics for this object. (Inherited from KX_GameObject.KX_GameObject)
 
sendMessage(subject, body='', to='')
Sends a message. (Inherited from KX_GameObject.KX_GameObject)
 
setAngularVelocity(velocity, local=0)
Sets the game object's angular velocity. (Inherited from KX_GameObject.KX_GameObject)
 
setCollisionMargin(margin)
Set the objects collision margin. (Inherited from KX_GameObject.KX_GameObject)
 
setLinearVelocity(velocity, local=0)
Sets the game object's linear velocity. (Inherited from KX_GameObject.KX_GameObject)
 
setOcclusion(occlusion, recursive)
Sets the game object's occlusion capability. (Inherited from KX_GameObject.KX_GameObject)
 
setOrientation(orn)
Sets the game object's orientation. (Inherited from KX_GameObject.KX_GameObject)
 
setParent(parent)
Sets this object's parent. (Inherited from KX_GameObject.KX_GameObject)
 
setPosition(pos)
Sets the game object's position. (Inherited from KX_GameObject.KX_GameObject)
 
setState(state)
Sets the game object's state flag. (Inherited from KX_GameObject.KX_GameObject)
 
setVisible(visible, recursive)
Sets the game object's visible flag. (Inherited from KX_GameObject.KX_GameObject)
 
setWorldPosition(pos)
Sets the game object's position in world coordinates regardless if the object is root or child. (Inherited from KX_GameObject.KX_GameObject)
 
suspendDynamics()
Suspends physics for this object. (Inherited from KX_GameObject.KX_GameObject)
Instance Variables
list actuators
a list of SCA_IActuator objects. (Inherited from KX_GameObject.KX_GameObject)
4x4 Matrix [[float]] camera_to_world
This camera's camera to world transform.
list of SCA_ISensor. controllers
a list of SCA_IController objects. (Inherited from KX_GameObject.KX_GameObject)
float far
The camera's far clip distance.
boolean frustum_culling
True if this camera is frustum culling.
bool isValid
Retuerns fails when the object has been removed from the scene and can no longer be used. (Inherited from KX_GameObject.KX_GameObject)
float lens
The camera's lens value.
float linVelocityMax
Clamp the maximum linear velocity to prevent objects moving beyond a set speed. (Inherited from KX_GameObject.KX_GameObject)
float linVelocityMin
Enforces the object keeps moving at a minimum velocity. (Inherited from KX_GameObject.KX_GameObject)
list [ix, iy, iz] localInertia
the object's inertia vector in local coordinates. (Inherited from KX_GameObject.KX_GameObject)
3x3 Matrix [[float]] localOrientation
The object's local orientation. (Inherited from KX_GameObject.KX_GameObject)
list [x, y, z] localPosition
The object's local position. (Inherited from KX_GameObject.KX_GameObject)
list [sx, sy, sz] localScaling
The object's local scaling factor. (Inherited from KX_GameObject.KX_GameObject)
float mass
The object's mass (Inherited from KX_GameObject.KX_GameObject)
list of KX_MeshProxy meshes
a list meshes for this object. (Inherited from KX_GameObject.KX_GameObject)
4x4 Matrix [[float]] modelview_matrix
This camera's 4x4 model view matrix.
string. name
The object's name. (Inherited from KX_GameObject.KX_GameObject)
float near
The camera's near clip distance.
boolean occlusion
occlusion capability flag. (Inherited from KX_GameObject.KX_GameObject)
3x3 Matrix [[float]] On write: local orientation, on read: world orientation orientation
The object's orientation. (Inherited from KX_GameObject.KX_GameObject)
KX_GameObject or None parent
The object's parent object. (Inherited from KX_GameObject.KX_GameObject)
boolean perspective
True if this camera has a perspective transform.
list [x, y, z] On write: local position, on read: world position position
The object's position. (Inherited from KX_GameObject.KX_GameObject)
4x4 Matrix [[float]] projection_matrix
This camera's 4x4 projection matrix.
list [sx, sy, sz] On write: local scaling, on read: world scaling scaling
The object's scaling factor. (Inherited from KX_GameObject.KX_GameObject)
list sensors
a list of SCA_ISensor objects. (Inherited from KX_GameObject.KX_GameObject)
int state
the game object's state bitmask, using the first 30 bits, one bit must always be set. (Inherited from KX_GameObject.KX_GameObject)
float timeOffset
adjust the slowparent delay at runtime. (Inherited from KX_GameObject.KX_GameObject)
boolean visible
visibility flag. (Inherited from KX_GameObject.KX_GameObject)
3x3 Matrix [[float]] worldOrientation
The object's world orientation. (Inherited from KX_GameObject.KX_GameObject)
list [x, y, z] worldPosition
The object's world position. (Inherited from KX_GameObject.KX_GameObject)
list [sx, sy, sz] worldScaling
The object's world scaling factor. (Inherited from KX_GameObject.KX_GameObject)
4x4 Matrix [[float]] world_to_camera
This camera's world to camera transform.
    Constants
  INSIDE
see sphereInsideFrustum() and boxInsideFrustum()
  INTERSECT
see sphereInsideFrustum() and boxInsideFrustum()
  OUTSIDE
see sphereInsideFrustum() and boxInsideFrustum()
Method Details

sphereInsideFrustum(centre, radius)

 

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)

 

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)

 

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()

 

Returns the camera-to-world transform.

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

getWorldToCamera()

 

Returns the world-to-camera transform.

This returns the inverse matrix of getCameraToWorld().

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

getProjectionMatrix()

 

Returns the camera's projection matrix.

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

setProjectionMatrix(matrix)

 

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.

enableViewport(viewport)

 

Use this camera to draw a viewport on the screen (for split screen games or overlay scenes). The viewport region is defined with setViewport.

Parameters:
  • viewport (bool) - the new viewport status

setViewport(left, bottom, right, top)

 

Sets the region of this viewport on the screen in pixels.

Use Rasterizer.getWindowHeight Rasterizer.getWindowWidth to calculate values relative to the entire display.

Parameters:
  • top (int)
  • bottom (int)
  • right (int)
  • left (int)

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]]