Camera API documentation

Messages to control camera components and camera focus.

Version: beta

FUNCTIONS
camera.get_aspect_ratio() get aspect ratio
camera.get_auto_aspect_ratio() get auto aspect ratio
camera.get_cameras() get all camera URLs
camera.get_enabled() get enabled
camera.get_far_z() get far z
camera.get_fov() get field of view
camera.get_near_z() get near z
camera.get_orthographic_zoom() get orthographic zoom
camera.get_projection() get projection matrix
camera.get_view() get view matrix
camera.set_aspect_ratio() set aspect ratio
camera.set_auto_aspect_ratio() set auto aspect ratio
camera.set_far_z() set far z
camera.set_fov() set field of view
camera.set_near_z() set near z
camera.set_orthographic_zoom() set orthographic zoom
MESSAGES
set_camera sets camera properties
PROPERTIES
aspect_ratio float camera aspect ratio
far_z float camera far_z
fov float camera fov
near_z float camera near_z
orthographic_zoom float camera orthographic_zoom
projection float camera projection
view float camera view

Functions

camera.get_aspect_ratio()

camera.get_aspect_ratio(camera)

Gets the effective aspect ratio of the camera. If auto aspect ratio is enabled, returns the aspect ratio calculated from the current render target dimensions. Otherwise returns the manually set aspect ratio.

PARAMETERS

camera url
number
nil
 camera id

RETURNS

aspect_ratio number
 the effective aspect ratio.

camera.get_auto_aspect_ratio()

camera.get_auto_aspect_ratio(camera)

Returns whether auto aspect ratio is enabled. When enabled, the camera automatically calculates aspect ratio from render target dimensions. When disabled, uses the manually set aspect ratio value.

PARAMETERS

camera url
number
nil
 camera id

RETURNS

auto_aspect_ratio boolean
 true if auto aspect ratio is enabled

camera.get_cameras()

camera.get_cameras()

This function returns a table with all the camera URLs that have been registered in the render context.

PARAMETERS

None

RETURNS

cameras table
 a table with all camera URLs

EXAMPLES

for k,v in pairs(camera.get_cameras()) do
    render.set_camera(v)
    render.draw(...)
    render.set_camera()
end

camera.get_enabled()

camera.get_enabled(camera)

get enabled

PARAMETERS

camera url
number
nil
 camera id

RETURNS

flag boolean
 true if the camera is enabled

camera.get_far_z()

camera.get_far_z(camera)

get far z

PARAMETERS

camera url
number
nil
 camera id

RETURNS

far_z number
 the far z.

camera.get_fov()

camera.get_fov(camera)

get field of view

PARAMETERS

camera url
number
nil
 camera id

RETURNS

fov number
 the field of view.

camera.get_near_z()

camera.get_near_z(camera)

get near z

PARAMETERS

camera url
number
nil
 camera id

RETURNS

near_z number
 the near z.

camera.get_orthographic_zoom()

camera.get_orthographic_zoom(camera)

get orthographic zoom

PARAMETERS

camera url
number
nil
 camera id

RETURNS

orthographic_zoom number
 the zoom level when the camera uses orthographic projection.

camera.get_projection()

camera.get_projection(camera)

get projection matrix

PARAMETERS

camera url
number
nil
 camera id

RETURNS

projection matrix4
 the projection matrix.

camera.get_view()

camera.get_view(camera)

get view matrix

PARAMETERS

camera url
number
nil
 camera id

RETURNS

view matrix4
 the view matrix.

camera.set_aspect_ratio()

camera.set_aspect_ratio(camera,aspect_ratio)

Sets the manual aspect ratio for the camera. This value is only used when auto aspect ratio is disabled. To disable auto aspect ratio and use this manual value, call camera.set_auto_aspect_ratio(camera, false).

PARAMETERS

camera url
number
nil
 camera id
aspect_ratio number
 the manual aspect ratio value.

camera.set_auto_aspect_ratio()

camera.set_auto_aspect_ratio(camera,auto_aspect_ratio)

Enables or disables automatic aspect ratio calculation. When enabled (true), the camera automatically calculates aspect ratio from render target dimensions. When disabled (false), uses the manually set aspect ratio value.

PARAMETERS

camera url
number
nil
 camera id
auto_aspect_ratio boolean
 true to enable auto aspect ratio

camera.set_far_z()

camera.set_far_z(camera,far_z)

set far z

PARAMETERS

camera url
number
nil
 camera id
far_z number
 the far z.

camera.set_fov()

camera.set_fov(camera,fov)

set field of view

PARAMETERS

camera url
number
nil
 camera id
fov number
 the field of view.

camera.set_near_z()

camera.set_near_z(camera,near_z)

set near z

PARAMETERS

camera url
number
nil
 camera id
near_z number
 the near z.

camera.set_orthographic_zoom()

camera.set_orthographic_zoom(camera,orthographic_zoom)

set orthographic zoom

PARAMETERS

camera url
number
nil
 camera id
orthographic_zoom number
 the zoom level when the camera uses orthographic projection.

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 boolean
 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})

Properties

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

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

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

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