Camera API documentation

Version: stable

MESSAGE
set_camera sets camera properties
acquire_camera_focus makes the receiving camera become the active camera
release_camera_focus deactivates the receiving camera
PROPERTIES
fov float camera fov
near_z float camera near_z
far_z float camera far_z
orthographic_zoom float camera orthographic_zoom
projection float camera projection
view float camera view
aspect_ratio float camera aspect ratio

Messages

set_camera

Post this message to a camera-component to set its properties at run-time.

aspect_ratio number aspect ratio of the screen (width divided by height)
fov number field of view of the lens, measured as the angle in radians between the right and left edge
near_z number position of the near clipping plane (distance from camera along relative z)
far_z number position of the far clipping plane (distance from camera along relative z)
orthographic_projection bool set to use an orthographic projection
orthographic_zoom number zoom level when the camera is using an orthographic projection

EXAMPLES

In the examples, it is assumed that the instance of the script has a camera-component with id "camera". 
msg.post("#camera", "set_camera", {aspect_ratio = 16/9, fov = math.pi * 0.5, near_z = 0.1, far_z = 500})

acquire_camera_focus

Post this message to a camera-component to activate it. Several cameras can be active at the same time, but only the camera that was last activated will be used for rendering. When the camera is deactivated (see release_camera_focus), the previously activated camera will again be used for rendering automatically. The reason it is called "camera focus" is the similarity to how acquiring input focus works (see acquire_input_focus).

EXAMPLES

In the examples, it is assumed that the instance of the script has a camera-component with id "camera". 
msg.post("#camera", "acquire_camera_focus")

release_camera_focus

Post this message to a camera-component to deactivate it. The camera is then removed from the active cameras. See acquire_camera_focus for more information how the active cameras are used in rendering.

EXAMPLES

In the examples, it is assumed that the instance of the script has a camera-component with id "camera". 
msg.post("#camera", "release_camera_focus")

Properties

fov

Vertical field of view of the camera. The type of the property is float.

EXAMPLES

function init(self)
  local fov = go.get("#camera", "fov")
  go.set("#camera", "fov", fov + 0.1)
  go.animate("#camera", "fov", go.PLAYBACK_ONCE_PINGPONG, 1.2, go.EASING_LINEAR, 1)
end

near_z

Camera frustum near plane. The type of the property is float.

EXAMPLES

function init(self)
  local near_z = go.get("#camera", "near_z")
  go.set("#camera", "near_z", 10)
end

far_z

Camera frustum far plane. The type of the property is float.

EXAMPLES

function init(self)
  local far_z = go.get("#camera", "far_z")
  go.set("#camera", "far_z", 10)
end

orthographic_zoom

Zoom level when using an orthographic projection. The type of the property is float.

EXAMPLES

function init(self)
  local orthographic_zoom = go.get("#camera", "orthographic_zoom")
  go.set("#camera", "orthographic_zoom", 2.0)
  go.animate("#camera", "orthographic_zoom", go.PLAYBACK_ONCE_PINGPONG, 0.5, go.EASING_INOUTQUAD, 2)
end

projection

READ ONLY The calculated projection matrix of the camera. The type of the property is matrix4.

EXAMPLES

function init(self)
  local projection = go.get("#camera", "projection")
end

view

READ ONLY The calculated view matrix of the camera. The type of the property is matrix4.

EXAMPLES

function init(self)
  local view = go.get("#camera", "view")
end

aspect_ratio

The ratio between the frustum width and height. Used when calculating the projection of a perspective camera. The type of the property is number.

EXAMPLES

function init(self)
  local aspect_ratio = go.get("#camera", "aspect_ratio")
  go.set("#camera", "aspect_ratio", 1.2)
end