stingray.Camera object reference

Description

Represents a game camera.

Constructors and accessors

stingray.Oculus.camera() stingray.SteamVR.camera() stingray.Unit.camera()

Related sample code

Appkit: /camera_wrapper.lua Character template: /player.lua Gear VR template: /gear_vr.lua Google VR template: /google_vr.lua

Other related reference items

	stingray.Application.render_world() stingray.Hololens.initialize() stingray.Oculus.initialize() stingray.Oculus.set_camera() stingray.SteamVR.initialize() stingray.SteamVR.set_camera() stingray.World.set_frustum_inspector_camera()
	Core

Related help topics

	Building Levels > Organize level objects in categories
	Creating Gameplay > Scripting with Lua > Starting Lua from scratch: using a custom boot script > Example Boot Script

Functions

far_range ( self ) : number Returns the far range value of the camera.

Parameters

self :

stingray.Camera

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see Object lifetimes and userdata binding, or this page in the Lua documentation.

Returns

number

The far range value.

get_data ( self, indices ) : any Retrieves the data set at the specified indices within the camera's script data object.

Parameters

self :	stingray.Camera	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see Object lifetimes and userdata binding, or this page in the Lua documentation.
indices :	any(integer, string)+	One or more indices for the data, which may be integers or strings. The + notation indicates that there may be one or more instances of the specified type. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.

Returns

any	The data previously stored at the specified sequence of indices.

Similar to Unit.get_data().

Other related reference items

stingray.Camera.set_data()

has_data ( self, indices ) : boolean Indicates whether or not any data has been saved at the specified indices in the camera's script data object.

Parameters

self :	stingray.Camera	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see Object lifetimes and userdata binding, or this page in the Lua documentation.
indices :	any(integer, string)+	One or more indices for the data, which may be integers or strings. The + notation indicates that there may be one or more instances of the specified type. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.

Returns

boolean

Returns true if a data value is stored at the specified sequence of indices, or false otherwise.

Similar to Unit.has_data().

inside_frustum ( self, w ) : number Indicates whether the Vector3 w is inside the camera's frustum.

Parameters

self :	stingray.Camera	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see Object lifetimes and userdata binding, or this page in the Lua documentation.
w :	stingray.Vector3	A point that is tested.

Returns

number

A positive value indicates that the point is inside the frustum, and specifies how many meters inside the frustum the point is. A negative value indicates that the point is outside the frustum, and specifies how far outside the frustum the point is.

mode ( self ) : integer Returns the camera mode.

Parameters

self :

stingray.Camera

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see Object lifetimes and userdata binding, or this page in the Lua documentation.

Returns

integer

One of the defined mode type values.

near_range ( self ) : number Returns the near range value of the camera.

Parameters

self :

stingray.Camera

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see Object lifetimes and userdata binding, or this page in the Lua documentation.

Returns

number

The near range value.

projection ( self, aspect_ratio ) : stingray.Matrix4x4 Computes a projection matrix for the camera given an aspect ratio

Parameters

self :	stingray.Camera	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see Object lifetimes and userdata binding, or this page in the Lua documentation.
aspect_ratio :	number	The target aspect ratio

Returns

stingray.Matrix4x4

The compound projection matrix

Based on the Camera's mode, will generate a valid projection matrix. The aspect ratio is a number in the interval ]0.0, 1.0]

projection_type ( self ) : integer Returns the projection type of the camera.

Parameters

self :

stingray.Camera

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see Object lifetimes and userdata binding, or this page in the Lua documentation.

Returns

integer

One of the defined projection type values.

screen_to_world ( self, p, d, window, viewport_size ) : stingray.Vector3 Converts a point p from screen coordinates to world coordinates.

Parameters

self :	stingray.Camera	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see Object lifetimes and userdata binding, or this page in the Lua documentation.
p :	stingray.Vector3	A point in screen coordinates (x, y, 0)
d :	number	Depth of point
window :	stingray.Window?	The window to test. Optional; if not specified, uses the largest application window. The ? notation indicates that this type is optional: there may be zero or one instances of it.
viewport_size :	stingray.Vector2?	Size of viewport. Optional; if not specified uses window back buffer size The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

stingray.Vector3

The converted point in world coordinates.

In screen coordinates, the (X,Y) values are the pixel positions of the point on the screen and the Z value is unused. The depth value indicates the depth into the screen where the point lies (the distance from the camera plane), in meters.

Related sample code

Picking a unit with the mouse

set_data ( self, indices, indices, indices, value ) set_data ( self, indices, indices, value ) set_data ( self, indices, value ) Stores the specified value in the camera's script data object, at a location determined by the specified indices.

Parameters

self :	stingray.Camera	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see Object lifetimes and userdata binding, or this page in the Lua documentation.
indices :	any(integer, string)	One or more indices for the data, which may be integers or strings. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.
value :	any	The value to store.

Returns

This function does not return any values.

You can retrieve the data later by passing the same indices in a call to get_data(). Similar to Unit.set_data().

set_far_range ( self, range ) Sets the far range value of the camera.

Parameters

self :	stingray.Camera	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see Object lifetimes and userdata binding, or this page in the Lua documentation.
range :	number	The far range value set.

Returns

This function does not return any values.

set_frustum ( self, left, right, down, up, index ) Sets the frustum dimensions for the perspective view.

Parameters

self :	stingray.Camera	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see Object lifetimes and userdata binding, or this page in the Lua documentation.
left :	number	The left value of the view volume.
right :	number	The right value of the view volume.
down :	number	The bottom value of the view volume.
up :	number	The top value of the view volume.
index :	number?	Optional? Sub camera index. If not specified defaults to 1. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

This function does not return any values.

set_frustum_half_angles ( self, left_tan, right_tan, down_tan, up_tan, index ) Sets the frustum dimensions for the perspective view using half angles (in radians).

Parameters

self :	stingray.Camera	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see Object lifetimes and userdata binding, or this page in the Lua documentation.
left_tan :	number	The left value of the view volume.
right_tan :	number	The right value of the view volume.
down_tan :	number	The bottom value of the view volume.
up_tan :	number	The top value of the view volume.
index :	number?	Optional? Sub camera index. If not specified defaults to 1. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

This function does not return any values.

set_local ( self, m, index ) Offsets camera world pose.

Parameters

self :	stingray.Camera	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see Object lifetimes and userdata binding, or this page in the Lua documentation.
m :	stingray.Matrix4x4	Local transform to apply to camera world.
index :	number?	Optional? Sub camera index. If not specified defaults to 1. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

This function does not return any values.

i.e. Used during stereo rendering in order to compute left and right eye poses.

set_mode ( self, mode ) Sets the camera mode.

Parameters

self :	stingray.Camera	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see Object lifetimes and userdata binding, or this page in the Lua documentation.
mode :	integer	The camera mode. Can be one of the defined mode type values.

Returns

This function does not return any values.

set_near_range ( self, range ) Sets the near range value of the camera.

Parameters

self :	stingray.Camera	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see Object lifetimes and userdata binding, or this page in the Lua documentation.
range :	number	The near range value set.

Returns

This function does not return any values.

set_orthographic_view ( self, min_x, max_x, min_z, max_z, index ) Sets the minimum and maximum coordinates for the orthographic view.

Parameters

self :	stingray.Camera	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see Object lifetimes and userdata binding, or this page in the Lua documentation.
min_x :	number	The minimum x value of the view volume.
max_x :	number	The maximum x value of the view volume.
min_z :	number	The minimum z value of the view volume.
max_z :	number	The maximum z value of the view volume.
index :	number?	Optional? Sub camera index. If not specified defaults to 1. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

This function does not return any values.

set_projection_type ( self, projection_type ) Sets the projection type of the camera.

Parameters

self :	stingray.Camera	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see Object lifetimes and userdata binding, or this page in the Lua documentation.
projection_type :	integer	The projection type. Can be one of the defined projection type values.

Returns

This function does not return any values.

set_vertical_fov ( self, fov, index ) Sets the vertical Field of View angle of the camera.

Parameters

self :	stingray.Camera	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see Object lifetimes and userdata binding, or this page in the Lua documentation.
fov :	number	The Field of View angle.
index :	number?	Optional? Sub camera index. If not specified defaults to 1. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

This function does not return any values.

vertical_fov ( self, index ) : number Returns the vertical Field of View angle set for the camera.

Parameters

self :	stingray.Camera	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see Object lifetimes and userdata binding, or this page in the Lua documentation.
index :	number?	Optional? Sub camera index. If not specified defaults to 1. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

number

The Field of View angle.

world_to_screen ( self, w, window, viewport_size ) : stingray.Vector3, number Converts a point w from world coordinates to screen coordinates.

Parameters

self :	stingray.Camera	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see Object lifetimes and userdata binding, or this page in the Lua documentation.
w :	stingray.Vector3	A point in world coordinates.
window :	stingray.Window?	The window to test. Optional; if not specified, uses the largest application window. The ? notation indicates that this type is optional: there may be zero or one instances of it.
viewport_size :	stingray.Vector2?	Size of viewport. Optional; if not specified uses window back buffer size The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

stingray.Vector3	The converted point in screen coordinates.
number	The converted point depth value

In screen coordinates, the (X,Y) values are the pixel positions of the point on the screen and the Z value is unused. The depth value indicates the depth into the screen where the point lies (the distance from the camera plane), in meters.

Scene placement

The functions in this group control the placement of an object of this type in the scene.

local_pose ( self ) : stingray.Matrix4x4 Returns the position and orientation of the specified scene graph object in local space: i.e. relative to its parent in the scene graph.

Parameters

self :

stingray.Camera

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see Object lifetimes and userdata binding, or this page in the Lua documentation.

Returns

stingray.Matrix4x4

The position and orientation of the object in local space.

local_position ( self ) : stingray.Vector3 Returns the position of the specified scene graph object in local space: i.e. relative to its parent in the scene graph.

Parameters

self :

stingray.Camera

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see Object lifetimes and userdata binding, or this page in the Lua documentation.

Returns

stingray.Vector3

The position of the object in local space.

local_rotation ( self ) : stingray.Quaternion Returns the orientation of the specified scene graph object in local space: i.e. relative to its parent in the scene graph.

Parameters

self :

stingray.Camera

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see Object lifetimes and userdata binding, or this page in the Lua documentation.

Returns

stingray.Quaternion

The rotation of the object in local space.

node ( self ) : integer Returns the ID of the specified object within the scene graph.

Parameters

self :

stingray.Camera

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see Object lifetimes and userdata binding, or this page in the Lua documentation.

Returns

integer

The ID of the specified object in the scene graph.

set_local_pose ( self, pose ) Sets the position and orientation of the specified scene graph object in local space: i.e. relative to its parent in the scene graph.

Parameters

self :	stingray.Camera	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see Object lifetimes and userdata binding, or this page in the Lua documentation.
pose :	stingray.Matrix4x4	The new position and orientation for the object in local space.

Returns

This function does not return any values.

Related sample code

Basic template: /main_menu.lua Character template: /main_menu.lua Vehicle template: /main_menu.lua

set_local_position ( self, position ) Sets the position of the specified scene graph object in local space: i.e. relative to its parent in the scene graph.

Parameters

self :	stingray.Camera	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see Object lifetimes and userdata binding, or this page in the Lua documentation.
position :	stingray.Vector3	The new position for the object in local space.

Returns

This function does not return any values.

Related sample code

Vehicle template: /vehicle_follow_cam.lua

set_local_rotation ( self, rotation ) Sets the orientation of the specified scene graph object in local space: i.e. relative to its parent in the scene graph.

Parameters

self :	stingray.Camera	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see Object lifetimes and userdata binding, or this page in the Lua documentation.
rotation :	stingray.Quaternion	The new rotation for the object in local space.

Returns

This function does not return any values.

Related sample code

Vehicle template: /vehicle_follow_cam.lua

world_pose ( self ) : stingray.Matrix4x4 Returns the position and orientation of the specified scene graph object in world space.

Parameters

self :

stingray.Camera

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see Object lifetimes and userdata binding, or this page in the Lua documentation.

Returns

stingray.Matrix4x4

The position and orientation of the object in world space.

Related sample code

Gear VR template: /project.lua Google VR template: /project.lua

world_position ( self ) : stingray.Vector3 Returns the position of the specified scene graph object in world space.

Parameters

self :

stingray.Camera

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see Object lifetimes and userdata binding, or this page in the Lua documentation.

Returns

stingray.Vector3

The position of the object in world space.

Related sample code

Picking a unit with the mouse

world_rotation ( self ) : stingray.Quaternion Returns the rotation of the specified scene graph object in world space.

Parameters

self :

stingray.Camera

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see Object lifetimes and userdata binding, or this page in the Lua documentation.

Returns

stingray.Quaternion

The rotation of the object in world space.

Mode types

Defines the different modes a camera can use.

You can set up a camera to a specific mode by calling set_mode().

MONO : integer Specifies a monoscopic camera.

STEREO : integer Specifies a stereoscopic camera.

Projection types

Defines the different types of projection that a camera can use.

You can set up a camera to use one of these projection modes by calling set_projection_type().

ORTHOGRAPHIC : integer Specifies an orthographic camera.

PERSPECTIVE : integer Specifies a perspective camera.