Module GameTypes :: Class KX_Camera

Class KX_Camera

PyObjectPlus --+            
               |            
          CValue --+        
                   |        
         SCA_IObject --+    
                       |    
           KX_GameObject --+
                           |
                          KX_Camera

A Camera object.

Instance Methods

[hide private]

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

setOnTop()
Set this cameras viewport ontop of all other viewport.

source code

setViewport(left, bottom, right, top)
Sets the region of this viewport on the screen in pixels.

source code

list [x, y]

getScreenPosition(arg)
Gets the position of an object projected on screen space.

source code

3d vector

getScreenVect(x, y)
Gets the vector from the camera position in the screen coordinate direction.

source code

KX_GameObject

getScreenRay(x, y, dist, property)
Look towards a screen coordinate (x,y) and find first object hit within dist that matches prop.

source code

Deprecated

matrix (4x4 list)

getProjectionMatrix()
Returns the camera's projection matrix.

source code

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

source code

enableViewport(viewport)
Use this camera to draw a viewport on the screen (for split screen games or overlay scenes).

source code

Property Access

Inherited from KX_GameObject

alignAxisToVect(vect, axis, factor)
Aligns any of the game object's axis along the given vector.

source code

applyForce(force, local=0)
Sets the game object's force.

source code

applyImpulse(point, impulse)
Applies an impulse to the game object.

source code

applyMovement(movement, local=0)
Sets the game object's movement.

source code

applyRotation(rotation, local=0)
Sets the game object's rotation.

source code

applyTorque(torque, local=0)
Sets the game object's torque.

source code

disableRigidBody()
Disables rigid body physics for this object.

source code

enableRigidBody()
Enables rigid body physics for this object.

source code

endObject()
Delete this object, can be used inpace of the EndObject Actuator.

source code

list [vx, vy, vz]

getAngularVelocity(local=0)
Gets the game object's angular velocity.

source code

3d vector.

getAxisVect(vect)
Returns the axis vector rotates by the objects worldspace orientation.

source code

float

getDistanceTo(other)
Returns the distance to another object or point.

source code

list [vx, vy, vz]

getLinearVelocity(local=0)
Gets the game object's linear velocity.

source code

getPhysicsId()
Returns the user data object associated with this game object's physics controller.

source code

list [fx, fy, fz]

getReactionForce()
Gets the game object's reaction force.

source code

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.

source code

list [vx, vy, vz]

getVelocity(point)
Gets the game object's velocity at the specified point.

source code

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.

source code

KX_GameObject

rayCastTo(other, dist, prop)
Look towards another point/object and find first object hit within dist that matches prop.

source code

boolean

reinstancePhysicsMesh(gameObject, meshObject)
Updates the physics system with the changed mesh.

source code

removeParent()
Removes this objects parent.

source code

replaceMesh(mesh, useDisplayMesh=True, usePhysicsMesh=False)
Replace the mesh of this object with a new mesh.

source code

restoreDynamics()
Resumes physics for this object.

source code

sendMessage(subject, body='', to='')
Sends a message. source code

setAngularVelocity(velocity, local=0)
Sets the game object's angular velocity.

source code

setCollisionMargin(margin)
Set the objects collision margin.

source code

setLinearVelocity(velocity, local=0)
Sets the game object's linear velocity.

source code

setOcclusion(occlusion, recursive)
Sets the game object's occlusion capability.

source code

setParent(parent, compound, ghost)
Sets this object's parent.

source code

setVisible(visible, recursive)
Sets the game object's visible flag.

source code

suspendDynamics()
Suspends physics for this object.

source code

CListValue of KX_GameObject

getChildren()
Return a list of immediate children of this object.

source code

CListValue of KX_GameObject

getChildrenRecursive()
Return a list of children of this object, including all their childrens children.

source code

float

getMass()
Gets the game object's mass.

source code

KX_MeshProxy

getMesh(mesh)
Gets the mesh object for this object.

source code

3x3 rotation matrix

getOrientation()
Gets the game object's orientation.

source code

KX_GameObject

getParent()
Gets this object's parent.

source code

list [x, y, z]

getPosition()
Gets the game object's position.

source code

int

getState()
Gets the game object's state bitmask.

source code

boolean

getVisible()
Gets the game object's visible flag.

source code

setOrientation(orn)
Sets the game object's orientation.

source code

setPosition(pos)
Sets the game object's position.

source code

setState(state)
Sets the game object's state flag.

source code

setWorldPosition(pos)
Sets the game object's position in world coordinates regardless if the object is root or child.

source code

get(key, default=None)
Return the value matching key, or the default value if its not found.

source code

list

getPropertyNames()
Gets a list of all property names.

source code

boolean

has_key(key)
Return True if the key is found.

source code

Inherited from CValue

string

getName()
Returns the name of the CValue.

source code

Inherited from PyObjectPlus

bool

isA(game_type)
Check if this is a type or a subtype game_type.

source code

Instance Variables

[hide private]

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, False for an orthographic projection.

4x4 Matrix [[float]]

projection_matrix
This camera's 4x4 projection matrix.

bool

useViewport
True when the camera is used as a viewport, set True to enable a viewport for this camera.

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

Property Access

Inherited from KX_GameObject

list

actuators
a list of SCA_IActuator with string/index lookups and iterator support.

CListValue of KX_GameObject's

children
direct children of this object, (read-only).

CListValue of KX_GameObject's

childrenRecursive
all children of this object including childrens children, (read-only).

list of SCA_ISensor.

controllers
a sequence of SCA_IController objects with string/index lookups and iterator support.

float

linVelocityMax
Clamp the maximum linear velocity to prevent objects moving beyond a set speed.

float

linVelocityMin
Enforces the object keeps moving at a minimum velocity.

list [ix, iy, iz]

localInertia
the object's inertia vector in local coordinates.

3x3 Matrix [[float]]

localOrientation
The object's local orientation.

list [x, y, z]

localPosition
The object's local position.

list [sx, sy, sz]

localScale
The object's local scaling factor.

float

mass
The object's mass

list of KX_MeshProxy

meshes
a list meshes for this object.

string

name
The name of this CValue derived object (read-only).

boolean

occlusion
occlusion capability flag.

3x3 Matrix [[float]] On write: local orientation, on read: world orientation

orientation
The object's orientation.

KX_GameObject or None

parent
The object's parent object.

list [x, y, z] On write: local position, on read: world position

position
The object's position.

list [sx, sy, sz] On write: local scaling, on read: world scaling

scaling
The object's scaling factor.

list

sensors
a sequence of SCA_ISensor objects with string/index lookups and iterator support.

int

state
the game object's state bitmask, using the first 30 bits, one bit must always be set.

float

timeOffset
adjust the slowparent delay at runtime.

boolean

visible
visibility flag.

3x3 Matrix [[float]]

worldOrientation
The object's world orientation.

list [x, y, z]

worldPosition
The object's world position.

list [sx, sy, sz]

worldScale
The object's world scaling factor.

dict

attrDict
get the objects internal python attribute dictionary for direct (faster) access.

Inherited from PyObjectPlus

bool

invalid
Test if the object has been freed by the game engine and is no longer valid.

Method Details

[hide private]

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.owner
       
       # 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

Note: when the camera is first initialized the result will be invalid because the projection matrix has not been set.

boxInsideFrustum(box)

source code

Tests the given box against the view frustum.

Example:

       import GameLogic
       co = GameLogic.getCurrentController()
       cam = co.owner
       
       # 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

Note: when the camera is first initialized the result will be invalid because the projection matrix has not been set.

pointInsideFrustum(point)

source code

Tests the given point against the view frustum.

Example:

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

       # 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.

Note: when the camera is first initialized the result will be invalid because the projection matrix has not been set.

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.

Deprecated: Use the projection_matrix attribute instead.

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.owner
       cam.setProjectionMatrix(Perspective(cam)))

Parameters:

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

Deprecated: Use the projection_matrix attribute instead.

enableViewport(viewport)

source code

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

Deprecated: Use the useViewport attribute instead.

setViewport(left, bottom, right, top)

source code

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

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

getScreenPosition(arg)

source code

Gets the position of an object projected on screen space.

Example: # For an object in the middle of the screen, coord = [0.5,0.5] coord = camera.getScreenPosition(object)

Parameters:

arg - KX_GameObject, object name or list [x, y, z]

Returns: list [x, y]

the object's position in screen coordinates.

getScreenVect(x, y)

source code

Gets the vector from the camera position in the screen coordinate direction.

Example: # Gets the vector of the camera front direction: m_vect = camera.getScreenVect(0.5,0.5)

Returns: 3d vector: the vector from a screen coordinate.

getScreenRay(x, y, dist, property)

source code

Look towards a screen coordinate (x,y) and find first object hit within dist that matches prop. The ray is similar to KX_GameObject->rayCastTo.

Example: # Gets an object with a property "wall" in front of the camera within a distance of 100: target = camera.getScreenRay(0.5,0.5,100,"wall")

Parameters:

dist (float) - max distance to look (can be negative => look behind); 0 or omitted => detect up to other
property (string) - property name that object must have; can be omitted => detect any object

Returns: KX_GameObject

the first object hit or None if no object or object does not match prop

Instance Variable Details

[hide private]

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

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