tecs.gfx.camera3d
A perspective camera maps a right-handed 3D world to one viewport.
World +X points right, +Y points up, and the default camera looks along -Z. The camera orientation is a quaternion in (x, y, z, w) order that turns camera-local coordinates into world coordinates. Position and orientation are caller-writable fields:
const camera = tecs.gfx.newCamera3D({
x = 0,
y = 2,
z = 6,
verticalFov = math.rad(60),
})
camera.rotationY = math.sin(math.rad(15) * 0.5)
camera.rotationW = math.cos(math.rad(15) * 0.5)matrix writes a column-major world-to-clip matrix with depth in [0, 1], and inverseMatrix writes its clip-to-world inverse. matrices writes both from one camera calculation for code that needs the pair. Each result uses a separate camera-owned sixteen-float array and remains valid until that same result is written again.
Module contents
Constructors
| Constructor | Description |
|---|---|
newCamera3D |
Types
| Type | Kind | Description |
|---|---|---|
Camera3D | record | Represents one perspective view into a right-handed 3D world. |
Options | type | Defines optional perspective-camera construction values. |
Constructors#
newCamera3Dconstructor#
Arguments
| Name | Type | Description |
|---|---|---|
options | Options? |
Returns
| Type | Description |
|---|---|
Camera3D |
Types#
Camera3Drecord#
record Camera3D
x: number = 0
y: number = 0
z: number = 0
rotationX: number = 0
rotationY: number = 0
rotationZ: number = 0
rotationW: number = 1
verticalFov: number = 1.0471975511965976
near: number = 0.1
far: number = 1000
matrix: function(exclusive self: Camera3D, width: number, height: number): {[integer]: number}
inverseMatrix: function(exclusive self: Camera3D, width: number, height: number): {[integer]: number}
matrices: function(
exclusive self: Camera3D,
width: number,
height: number
): ({[integer]: number}, {[integer]: number})
endRepresents one perspective view into a right-handed 3D world.
Methods
matrix#
matrix: function(exclusive self: Camera3D, width: number, height: number): {[integer]: number}Writes the column-major world-to-clip matrix for a viewport.
The method normalizes the camera quaternion while calculating the view, without modifying the caller's fields. Clip depth maps near to zero and far to one.
Arguments
| Name | Type | Description |
|---|---|---|
exclusive self | Camera3D | |
width | number | The positive viewport width in pixels. |
height | number | The positive viewport height in pixels. |
Returns
| Type | Description |
|---|---|
{[integer]: number} | The camera's own sixteen-float array, valid until the next call on this camera. |
inverseMatrix#
inverseMatrix: function(exclusive self: Camera3D, width: number, height: number): {[integer]: number}Writes the column-major clip-to-world matrix for a viewport.
This is the exact inverse of matrix at the same dimensions. Clip x and y range from negative one to one, clip z ranges from zero to one, and the caller divides the resulting xyz by w.
Arguments
| Name | Type | Description |
|---|---|---|
exclusive self | Camera3D | |
width | number | The positive viewport width in pixels. |
height | number | The positive viewport height in pixels. |
Returns
| Type | Description |
|---|---|
{[integer]: number} | The camera's own sixteen-float array, valid until the next call to |
matrices#
matrices: function(
exclusive self: Camera3D,
width: number,
height: number
): ({[integer]: number}, {[integer]: number})Writes the world-to-clip matrix and its clip-to-world inverse.
This method normalizes the camera quaternion and derives the projection once, then writes both arrays. Use it when both matrices describe the same view.
Arguments
| Name | Type | Description |
|---|---|---|
exclusive self | Camera3D | |
width | number | The positive viewport width in pixels. |
height | number | The positive viewport height in pixels. |
Returns
| Type | Description |
|---|---|
{[integer]: number} | The camera's own world-to-clip sixteen-float array, valid until the next call to |
{[integer]: number} | The camera's own clip-to-world sixteen-float array, valid until the next call to |
Fields
rotationX#
rotationX: numberCaller-writable. Sets the local-to-world orientation quaternion x component.
rotationY#
rotationY: numberCaller-writable. Sets the local-to-world orientation quaternion y component.
rotationZ#
rotationZ: numberCaller-writable. Sets the local-to-world orientation quaternion z component.
rotationW#
rotationW: numberCaller-writable. Sets the local-to-world orientation quaternion scalar component.
verticalFov#
verticalFov: numberCaller-writable. Sets the vertical field of view in radians between zero and pi.
Optionstype#
type Options = {
--- Caller-writable. Sets the world-space x coordinate and defaults to zero.
x: number?,
--- Caller-writable. Sets the world-space y coordinate and defaults to zero.
y: number?,
--- Caller-writable. Sets the world-space z coordinate and defaults to zero.
z: number?,
--- Caller-writable. Sets the orientation quaternion x component and
--- defaults to zero.
rotationX: number?,
--- Caller-writable. Sets the orientation quaternion y component and
--- defaults to zero.
rotationY: number?,
--- Caller-writable. Sets the orientation quaternion z component and
--- defaults to zero.
rotationZ: number?,
--- Caller-writable. Sets the orientation quaternion scalar component and
--- defaults to one.
rotationW: number?,
--- Caller-writable. Sets the vertical field of view in radians and
--- defaults to pi divided by three.
verticalFov: number?,
--- Caller-writable. Sets the positive near-plane distance and defaults to
--- 0.1 world units.
near: number?,
--- Caller-writable. Sets the far-plane distance and defaults to 1000 world units.
far: number?
}Defines optional perspective-camera construction values.