GetElementMatrix

This function gets an element's transform matrix. This contains 16 float values that multiplied to a point will give you the point transformed. It is most useful for matrix calculations such as calculating offsets. For further information, please refer to a tutorial of matrices in computer graphics programming.

[[{{{image}}}|link=|]]	Note: The matrix returned by this function is not setup correctly for some calculations. unless the legacy argument is set to false

[[{{{image}}}|link=|]]	Tip: For matrix manipulation which goes beyond the basic examples given on this page, see the Lua matrix library.

Syntax

table getElementMatrix ( element theElement [, bool legacy = true ] )       

Required Arguments

• theElement: The element which you wish to retrieve the matrix for

Optional Arguments

• legacy : Set to false to return correctly setup matrix. (i.e. Last column in the first 3 rows set to zero.)

Returns

Returns a multi-dimensional array containing a 4x4 matrix. Returns false if the element is not streamed in, and not a vehicle or ped.

Example

This example creates a utility function that turns an offset into a position that is relative to the specified element.

function getPositionFromElementOffset(element,offX,offY,offZ)
	local m = getElementMatrix ( element )  -- Get the matrix
	local x = offX * m[1][1] + offY * m[2][1] + offZ * m[3][1] + m[4][1]  -- Apply transform
	local y = offX * m[1][2] + offY * m[2][2] + offZ * m[3][2] + m[4][2]
	local z = offX * m[1][3] + offY * m[2][3] + offZ * m[3][3] + m[4][3]
	return x, y, z                               -- Return the transformed point
end

-- Get the position of a point 3 units to the left of the element:
x,y,z = getPositionFromElementOffset(element,3,0,0)

-- Get the position of a point 2 units in front of the element:
x,y,z = getPositionFromElementOffset(element,0,2,0)

-- Get the position of a point 1 unit above the element:
x,y,z = getPositionFromElementOffset(element,0,0,1)

This example creates some more matrix utility functions

function getMatrixLeft(m)
        return m[1][1], m[1][2], m[1][3]
end
function getMatrixForward(m)
        return m[2][1], m[2][2], m[2][3]
end
function getMatrixUp(m)
        return m[3][1], m[3][2], m[3][3]
end
function getMatrixPosition(m)
        return m[4][1], m[4][2], m[4][3]
end

local mat = getElementMatrix(element)  -- Get the matrix
x,y,z = getMatrixLeft(mat)     -- Get the matrix left direction
x,y,z = getMatrixForward(mat)  -- Get the matrix forward direction
x,y,z = getMatrixUp(mat)       -- Get the matrix up direction

This example allows you to get the element matrix of an element that is outside your stream range.

function getMatrix(posX, posY, posZ, rotX, rotY, rotZ)
	local rx, ry, rz = math.rad(rotX), math.rad(rotY), math.rad(rotZ)
	local matrix = {}
	matrix[1] = {}
	matrix[1][1] = math.cos(rz)*math.cos(ry) - math.sin(rz)*math.sin(rx)*math.sin(ry)
	matrix[1][2] = math.cos(ry)*math.sin(rz) + math.cos(rz)*math.sin(rx)*math.sin(ry)
	matrix[1][3] = -math.cos(rx)*math.sin(ry)
	
	matrix[2] = {}
	matrix[2][1] = -math.cos(rx)*math.sin(rz)
	matrix[2][2] = math.cos(rz)*math.cos(rx)
	matrix[2][3] = math.sin(rx)
	
	matrix[3] = {}
	matrix[3][1] = math.cos(rz)*math.sin(ry) + math.cos(ry)*math.sin(rz)*math.sin(rx)
	matrix[3][2] = math.sin(rz)*math.sin(ry) - math.cos(rz)*math.cos(ry)*math.sin(rx)
	matrix[3][3] = math.cos(rx)*math.cos(ry)
	
	matrix[4] = {}
	matrix[4][1], matrix[4][2], matrix[4][3] = posX, posY, posZ -- this is kinda useless but is used to have the same structure as getElementMatrix
	
	return matrix
end

local posX, posY, posZ = getElementPosition(element)
local rotX, rotY, rotZ = getElementRotation(element)
local mat = getMatrix(posX, posY, posZ, rotX, rotY, rotZ) -- this gives the same result as getElementMatrix(element), but also works if the element is not streamed in

See Also

• getElementBoneMatrix
• getElementBonePosition
• getElementBoneRotation
ADDED/UPDATED IN VERSION 1.6.0 r22741:
getElementBoneQuaternion
• getElementBoundingBox
• getElementDistanceFromCentreOfMassToBaseOfModel
• getElementLighting
• getElementRadius
• isElementCollidableWith
• isElementLocal
• isElementOnScreen
• isElementStreamable
• isElementStreamedIn
• isElementSyncer
• isElementWaitingForGroundToLoad
• setElementBoneMatrix
• setElementBonePosition
• setElementBoneRotation
ADDED/UPDATED IN VERSION 1.6.0 r22741:
setElementBoneQuaternion
• setElementCollidableWith
• setElementStreamable
• updateElementRpHAnim


• Shared
• attachElements
• createElement
• destroyElement
• detachElements
• getAttachedElements
• getElementAlpha
• getElementAttachedOffsets
• getElementAttachedTo
• getElementByIndex
• getElementByID
• getElementChild
• getElementChildren
• getElementChildrenCount
• getElementCollisionsEnabled
• getElementColShape
• getElementData
• getAllElementData
• hasElementData
• getElementDimension
• getElementHealth
• getElementID
• getElementInterior
• getElementMatrix
• getElementModel
• getElementParent
• getElementPosition
• getElementRotation
• getElementsByType
• getElementsWithinColShape
• getElementsWithinRange
• getElementType
• getElementVelocity
• getLowLODElement
• getRootElement
• isElement
• isElementAttached
• isElementCallPropagationEnabled
• isElementDoubleSided
• isElementFrozen
• isElementInWater
• isElementLowLOD
• isElementWithinColShape
• isElementWithinMarker
• setElementAlpha
• setElementAngularVelocity
• getElementAngularVelocity
• setElementAttachedOffsets
• setElementCallPropagationEnabled
• setElementCollisionsEnabled
• setElementData
• setElementDimension
• setElementDoubleSided
• setElementFrozen
• setElementHealth
• setElementID
• setElementInterior
• setElementModel
• setElementParent
• setElementPosition
• setElementRotation
• setElementVelocity
• setLowLODElement
• getPedContactElement
• getResourceDynamicElementRoot
• getResourceRootElement