stingray.Matrix4x4 object reference

Description

Represents a 4x4 matrix that stores both the position and the orientation of an object.

NOTE: Matrix4x4 objects are temporary. You can only use them in the frame in which they were generated. If you need to save a Matrix4x4 across multiple frames, use a Matrix4x4Box instead. For more information, see Object Lifetimes and Userdata Binding.

Constructors and accessors

stingray.Actor.pose() stingray.AnimationBlenderComponent.delta_transform() stingray.AnimationStateMachineComponent.get_constraint_target() stingray.Camera.local_pose() stingray.Camera.projection() stingray.Camera.world_pose() stingray.GearVR.hmd_local_pose() stingray.GearVR.hmd_world_pose() stingray.GoogleVR.hmd_local_pose() stingray.GoogleVR.hmd_world_pose() stingray.Hololens.head_pose() stingray.Level.pose() stingray.Light.local_pose() stingray.Light.world_pose() stingray.LODObject.local_pose() stingray.LODObject.world_pose() stingray.Math.merge_boxes() stingray.Matrix4x4() stingray.Matrix4x4.copy() stingray.Matrix4x4.from_axes() stingray.Matrix4x4.from_elements() stingray.Matrix4x4.from_quaternion() stingray.Matrix4x4.from_quaternion_position() stingray.Matrix4x4.from_translation() stingray.Matrix4x4.identity() stingray.Matrix4x4.inverse() stingray.Matrix4x4.lerp() stingray.Matrix4x4.multiply() stingray.Matrix4x4.zero() stingray.Matrix4x4Box.unbox() stingray.Mesh.box() stingray.Mesh.local_pose() stingray.Mesh.world_pose() stingray.MeshComponent.oobb() stingray.Oculus.controller_local_pose() stingray.Oculus.controller_world_pose() stingray.Oculus.hmd_local_pose() stingray.Oculus.hmd_world_pose() stingray.Oculus.tracking_space_pose() stingray.Quaternion.matrix4x4() stingray.SceneGraphComponent.local_pose() stingray.SceneGraphComponent.world_pose() stingray.SceneGraphNode.local_pose() stingray.SceneGraphNode.world_pose() stingray.Script.deserialize() stingray.SteamVR.controller_local_pose() stingray.SteamVR.controller_world_pose() stingray.SteamVR.hmd_local_pose() stingray.SteamVR.hmd_world_pose() stingray.SteamVR.tracking_space_pose() stingray.TransformComponent.local_pose() stingray.TransformComponent.world_pose() stingray.Unit.animation_get_constraint_target() stingray.Unit.animation_wanted_root_pose() stingray.Unit.box() stingray.Unit.delta_pose() stingray.Unit.local_pose() stingray.Unit.world_pose() stingray.World.debug_camera_pose()

Related sample code

Appkit: /camera_wrapper.lua Appkit: /unit_controller.lua Basic template: /player.lua Character template: /player.lua Vehicle template: /player.lua Oculus VR template: /flow_callbacks.lua Oculus VR template: /player.lua Steam VR template: /flow_callbacks.lua Steam VR template: /player.lua

Other related reference items

	stingray.Cloud stingray.SaveSystem
	stingray.Matrix4x4Box
	rotation2D
	stingray.Actor.debug_draw() stingray.Actor.pose() stingray.Actor.teleport_pose() stingray.ActorComponent.create_capsule() stingray.ActorComponent.create_plane() stingray.ActorComponent.create_sphere() stingray.ActorComponent.create_sphere() stingray.AnimationStateMachineComponent.set_constraint_target() stingray.Camera.set_local() stingray.Camera.set_local_pose() stingray.EntityManager.spawn() stingray.GearVR.set_layer_pose() stingray.GearVR.set_tracking_space_pose() stingray.GoogleVR.set_tracking_space_pose() stingray.Gui.bitmap_3d() stingray.Gui.bitmap_3d_uv() stingray.Gui.move() stingray.Gui.rect_3d() stingray.Gui.text_3d() stingray.Gui.update_bitmap_3d() stingray.Gui.update_bitmap_3d_uv() stingray.Gui.update_rect_3d() stingray.Gui.update_text_3d() stingray.Gui.update_video_3d() stingray.Gui.video_3d() stingray.GwNavBoxObstacle.set_transform() stingray.GwNavWorld.create() stingray.Level.pose() stingray.Light.set_local_pose() stingray.LineObject.add_axes() stingray.LineObject.add_box() stingray.LODObject.set_local_pose() stingray.Material.set_matrix4x4() stingray.Math.box_intersects_frustum() stingray.Math.box_in_frustum() stingray.Math.merge_boxes() stingray.Math.point_in_box() stingray.Math.ray_box_intersection() stingray.Matrix4x4Box.store() stingray.Mesh.set_local_pose() stingray.Oculus.set_layer_pose() stingray.Oculus.set_tracking_space_pose() stingray.PhysicsWorld.create_joint() stingray.PhysicsWorld.overlap() stingray.PhysicsWorld.set_observer() stingray.Quaternion.from_matrix4x4() stingray.Quaternion.matrix4x4() stingray.SceneGraphComponent.set_local_pose() stingray.SceneGraphNode.set_local_pose() stingray.Script.serialize() stingray.SteamVR.set_layer_pose() stingray.SteamVR.set_tracking_space_pose() stingray.TransformComponent.link() stingray.TransformComponent.link_to_scene_graph() stingray.TransformComponent.set_local_pose() stingray.Unit.animation_set_constraint_target() stingray.Unit.set_local_pose() stingray.Unit.teleport_local_pose() stingray.World.create_world_gui() stingray.World.link_particles() stingray.World.spawn_unit() stingray.WwiseWorld.make_auto_source() stingray.WwiseWorld.make_manual_source() stingray.WwiseWorld.set_listener() stingray.WwiseWorld.set_source_pose() stingray.WwiseWorld.trigger_event()
	Math

Functions

axis ( m, i ) : stingray.Vector3 Retrieves the local X, Y, or Z axis of the matrix.

Parameters

m :	stingray.Matrix4x4	The matrix whose axis will be returned.
i :	integer	The index of the axis to retrieve. Use 1 to get the X axis, 2 for the Y axis, or 3 for the Z axis.

Returns

stingray.Vector3

The axis at the specified index.

copy ( m ) : stingray.Matrix4x4 Returns a new copy of the specified matrix, with the same rotation and translation values.

Parameters

m :

stingray.Matrix4x4

The matrix to copy.

Returns

stingray.Matrix4x4

The newly created matrix.

element ( m, i, j ) : number Returns the element at index (i, j) in the matrix.

Parameters

m :	stingray.Matrix4x4	The matrix whose element will be returned.
i :	integer	The row index. Use 1 to access the local X axis rotation, 2 for the local Y axis rotation, 3 for the local Z axis rotation, or 4 for the translation.
j :	integer	The column index. Use 1 to access the global X component, 2 for the global Y component, 3 for the global Z component, or 4 for the translation.

Returns

number

The value of the element with the specified indices.

Indices are 1-based, so for example, element(1,2) returns the Y-component (2) of the X-axis (1) stored in the matrix.

equal ( m1, m2 ) : boolean Indicates whether or not two matrices are equivalent.

Parameters

m1 :	stingray.Matrix4x4	The first matrix.
m2 :	stingray.Matrix4x4	The second matrix.

Returns

boolean

Returns true if the two matrices are identical, or false otherwise.

forward ( m ) : stingray.Vector3 Returns the forward (Y) axis of the specified matrix.

Parameters

m :

stingray.Matrix4x4

The matrix whose axis value will be returned.

Returns

stingray.Vector3

The forward axis of the matrix.

from_axes ( x, y, z, t ) : stingray.Matrix4x4 Returns a matrix that represents the specified rotation and translation.

Parameters

x :	stingray.Vector3	The orientation of the local X axis.
y :	stingray.Vector3	The orientation of the local Y axis.
z :	stingray.Vector3	The orientation of the local Z axis.
t :	stingray.Vector3	The translation that will be stored in the new matrix.

Returns

stingray.Matrix4x4

The newly created matrix.

Related sample code

Vehicle template: /vehicle_follow_cam.lua

from_elements ( xx, xy, xz, yx, yy, yz, zx, zy, zz, tx, ty, tz ) : stingray.Matrix4x4 Creates a matrix with x-axis (xx, xy, xz), y-axis (yx, yy, yz), z-axis (zx, zy, zz) and translation (tx, ty, tz).

Parameters

xx :	number	The magnitude of the local X axis along the global X axis.
xy :	number	The magnitude of the local X axis along the global Y axis.
xz :	number	The magnitude of the local X axis along the global Z axis.
yx :	number	The magnitude of the local Y axis along the global X axis.
yy :	number	The magnitude of the local Y axis along the global Y axis.
yz :	number	The magnitude of the local Y axis along the global Z axis.
zx :	number	The magnitude of the local Z axis along the global X axis.
zy :	number	The magnitude of the local Z axis along the global Y axis.
zz :	number	The magnitude of the local Z axis along the global Z axis.
tx :	number	The translation along the global X axis.
ty :	number	The translation along the global Y axis.
tz :	number	The translation along the global Z axis.

Returns

stingray.Matrix4x4

The newly created matrix.

Equivalent to Matrix4x4().

from_quaternion ( q ) : stingray.Matrix4x4 Returns a matrix that represents the specified rotation, with no translation.

Parameters

q :

stingray.Quaternion

The rotation that will be stored in the new matrix.

Returns

stingray.Matrix4x4

The newly created matrix.

from_quaternion_position ( q, t ) : stingray.Matrix4x4 Returns a matrix that represents the specified rotation and translation.

Parameters

q :	stingray.Quaternion	The rotation that will be stored in the new matrix.
t :	stingray.Vector3	The translation that will be stored in the new matrix.

Returns

stingray.Matrix4x4

The newly created matrix.

from_translation ( t ) : stingray.Matrix4x4 Returns a matrix that represents the specified translation, with no rotation.

Parameters

t :

stingray.Vector3

The translation that will be stored in the new matrix.

Returns

stingray.Matrix4x4

The newly created matrix.

identity ( ) : stingray.Matrix4x4 Returns the identity matrix, which represents an object with no translation and no rotation.

Parameters

This function does not accept any parameters.

Returns

stingray.Matrix4x4

The identity matrix.

Related sample code

Basic template: /main_menu.lua Character template: /main_menu.lua Vehicle template: /main_menu.lua Oculus VR template: /main_menu.lua Oculus VR template: /project.lua Steam VR template: /project.lua

Other related reference items

stingray.Gui

inverse ( m ) : stingray.Matrix4x4 Returns the inverse of the specified matrix.

Parameters

m :

stingray.Matrix4x4

The matrix to invert.

Returns

stingray.Matrix4x4

The inverted matrix.

is_valid ( m ) : boolean Indicates whether or not the matrix is composed entirely of valid values.

Parameters

m :

stingray.Matrix4x4

The matrix to validate.

Returns

boolean

Returns true if all components of the matrix are valid numbers, or false if any component is #NaN or #INF.

is_valid_for_physics ( m ) : boolean Indicates whether or not the matrix can be applied to a physics object.

Parameters

m :

stingray.Matrix4x4

The matrix to validate.

Returns

boolean

Returns true if this matrix can be applied to a physics object, or false otherwise.

For example, a matrix may be unfit for use with physics objects if it contains shearing (non-orthogonal axes) or other unexpected geometry.

lerp ( m1, m2, t ) : stingray.Matrix4x4 Produces a new matrix by interpolating, or "lerping", between the two specified matrices.

Parameters

m1 :	stingray.Matrix4x4	The first matrix.
m2 :	stingray.Matrix4x4	The second matrix.
t :	number	The ratio, or interpolation point, between the two matrices. May be any value between 0 and 1 inclusive. Values closer to 0 produce matrices closer to m1; values closer to 1 produce matrices closer to m2.

Returns

stingray.Matrix4x4

The resulting matrix.

This is done by lerping the translation and rotation separately. Scale, etc., are not lerped.

multiply ( m1, m2 ) : stingray.Matrix4x4 Multiplies two matrices.

Parameters

m1 :	stingray.Matrix4x4	The first matrix to multiply.
m2 :	stingray.Matrix4x4	The second matrix to multiply.

Returns

stingray.Matrix4x4

The product of the multiplication.

This will create the composite transform of the individual matrix transforms.

right ( m ) : stingray.Vector3 Returns the right (X) axis of the specified matrix.

Parameters

m :

stingray.Matrix4x4

The matrix whose axis value will be returned.

Returns

stingray.Vector3

The right axis of the matrix.

rotation ( m ) : stingray.Quaternion Retrieves the rotation of the matrix.

Parameters

m :

stingray.Matrix4x4

The matrix whose rotation will be returned.

Returns

stingray.Quaternion

The rotation of the matrix.

Related sample code

Oculus VR template: /project.lua Steam VR template: /project.lua

scale ( m ) : stingray.Vector3 Retrieves the scale of the matrix.

Parameters

m :

stingray.Matrix4x4

The matrix whose scale will be returned.

Returns

stingray.Vector3

The scale of the matrix.

Related sample code

Oculus VR template: /project.lua Steam VR template: /project.lua

set_axis ( m, i, v ) Sets the local X, Y, or Z axis of the matrix.

Parameters

m :	stingray.Matrix4x4	The matrix whose axis will be set.
i :	integer	The index of the axis to set. Use 1 to get the X axis, 2 for the Y axis, or 3 for the Z axis.
v :	stingray.Vector3	The axis value to set.

Returns

This function does not return any values.

set_element ( m, i, j, value ) Sets a new value for the element at index (i, j) in the matrix.

Parameters

m :	stingray.Matrix4x4	The matrix whose element will be set.
i :	integer	The row index. Use 1 to set the local X axis rotation, 2 for the local Y axis rotation, 3 for the local Z axis rotation, or 4 for the translation.
j :	integer	The column index. Use 1 to set the global X component, 2 for the global Y component, 3 for the global Z component, or 4 for the translation.
value :	number	The value to set for the element with the specified indices.

Returns

This function does not return any values.

Indices are 1-based, so for example, set_element(1,2) sets the Y-component (2) of the X-axis (1) stored in the matrix.

set_forward ( m, forward ) Sets the forward (Y) axis of the specified matrix.

Parameters

m :	stingray.Matrix4x4	The matrix whose axis value will be set.
forward :	stingray.Vector3	The new forward axis of the matrix.

Returns

This function does not return any values.

set_right ( m, right ) Sets the right (X) axis of the specified matrix.

Parameters

m :	stingray.Matrix4x4	The matrix whose axis value will be set.
right :	stingray.Vector3	The new right axis of the matrix.

Returns

This function does not return any values.

set_rotation ( m, r ) Sets the rotation of the matrix.

Parameters

m :	stingray.Matrix4x4	The matrix whose rotation will be set.
r :	stingray.Quaternion	The new rotation of the matrix.

Returns

This function does not return any values.

set_scale ( m, s ) Sets the scale of the matrix.

Parameters

m :	stingray.Matrix4x4	The matrix whose scale will be set.
s :	stingray.Vector3	The new scale of the matrix.

Returns

This function does not return any values.

Related sample code

Oculus VR template: /project.lua Steam VR template: /project.lua

set_translation ( m, t ) Sets the translation of the matrix.

Parameters

m :	stingray.Matrix4x4	The matrix whose translation will be set.
t :	stingray.Vector3	The new translation of the matrix.

Returns

This function does not return any values.

Related sample code

Oculus VR template: /project.lua

set_up ( m, up ) Sets the up (Z) axis of the specified matrix.

Parameters

m :	stingray.Matrix4x4	The matrix whose axis value will be set.
up :	stingray.Vector3	The new up axis of the matrix.

Returns

This function does not return any values.

set_x ( m, x ) Sets the X axis of the specified matrix.

Parameters

m :	stingray.Matrix4x4	The matrix whose axis value will be set.
x :	stingray.Vector3	The new X axis of the matrix.

Returns

This function does not return any values.

set_y ( m, y ) Sets the Y axis of the specified matrix.

Parameters

m :	stingray.Matrix4x4	The matrix whose axis value will be set.
y :	stingray.Vector3	The new Y axis of the matrix.

Returns

This function does not return any values.

set_z ( m, z ) Sets the Z axis of the specified matrix.

Parameters

m :	stingray.Matrix4x4	The matrix whose axis value will be set.
z :	stingray.Vector3	The new Z axis of the matrix.

Returns

This function does not return any values.

to_elements ( m ) : number, number, number, number, number, number, number, number, number, number, number, number Decomposes a Matrix4x4 into the orientations of its X, Y, Z axes and its translation.

Parameters

m :

stingray.Matrix4x4

The matrix to break down into its elements.

Returns

number	The magnitude of the local X axis along the global X axis.
number	The magnitude of the local X axis along the global Y axis.
number	The magnitude of the local X axis along the global Z axis.
number	The magnitude of the local Y axis along the global X axis.
number	The magnitude of the local Y axis along the global Y axis.
number	The magnitude of the local Y axis along the global Z axis.
number	The magnitude of the local Z axis along the global X axis.
number	The magnitude of the local Z axis along the global Y axis.
number	The magnitude of the local Z axis along the global Z axis.
number	The translation along the global X axis.
number	The translation along the global Y axis.
number	The translation along the global Z axis.

to_string ( m ) : string Returns a string representation of the specified matrix.

Parameters

m :

stingray.Matrix4x4

The matrix to return as a string.

Returns

string

The string representation.

Use this function only for debugging purposes.

transform ( m, p ) : stingray.Vector3 Transforms the specified point using the specified matrix.

Parameters

m :	stingray.Matrix4x4	The matrix to use for the transform.
p :	stingray.Vector3	The position to be transformed.

Returns

stingray.Vector3

The new position, after being transformed by the matrix.

Related sample code

Appkit: /unit_controller.lua

transform_without_translation ( m, v ) : stingray.Vector3 Transforms the specified vector using the specified matrix, without translating the vector.

Parameters

m :	stingray.Matrix4x4	The matrix to use for the transform.
v :	stingray.Vector3	The vector to be transformed.

Returns

stingray.Vector3

The new position, after being transformed by the matrix.

This function may be useful when translating directions (rather than positions) between two different coordinate systems.

translation ( m ) : stingray.Vector3 Retrieves the translation of the matrix.

Parameters

m :

stingray.Matrix4x4

The matrix whose translation will be returned.

Returns

stingray.Vector3

The translation of the matrix.

Related sample code

Oculus VR template: /project.lua Steam VR template: /project.lua

up ( m ) : stingray.Vector3 Returns the up (Z) axis of the specified matrix.

Parameters

m :

stingray.Matrix4x4

The matrix whose axis value will be returned.

Returns

stingray.Vector3

The up axis of the matrix.

x ( m ) : stingray.Vector3 Returns the X axis of the specified matrix.

Parameters

m :

stingray.Matrix4x4

The matrix whose axis value will be returned.

Returns

stingray.Vector3

The X axis of the matrix.

y ( m ) : stingray.Vector3 Returns the Y axis of the specified matrix.

Parameters

m :

stingray.Matrix4x4

The matrix whose axis value will be returned.

Returns

stingray.Vector3

The Y axis of the matrix.

z ( m ) : stingray.Vector3 Returns the Z axis of the specified matrix.

Parameters

m :

stingray.Matrix4x4

The matrix whose axis value will be returned.

Returns

stingray.Vector3

The Z axis of the matrix.

zero ( ) : stingray.Matrix4x4 Returns the zero matrix, with all fields initialized to zero.

Parameters

This function does not accept any parameters.

Returns

stingray.Matrix4x4

The zero matrix.