Class Projection

A 4×4 matrix for 3D projective transformations.

Projection

Remarks

A 4×4 matrix used for 3D projective transformations. It can represent transformations such as translation, rotation, scaling, shearing, and perspective division. It consists of four Vector4 columns.

For purely linear transformations (translation, rotation, and scale), it is recommended to use Transform3D, as it is more performant and requires less memory.

Used internally as Camera3D's projection matrix.

Constructors

Projection

Constructs a default-initialized Projection identical to IDENTITY.

Note: In C#, this constructs a Projection identical to ZERO.

Projection Projection

Projection(Projection)

Constructs a Projection as a copy of the given Projection.

Projection Projection(Projection from)

Parameters

from Projection

Projection(Transform3D)

Constructs a Projection as a copy of the given Transform3D.

Projection Projection(Transform3D from)

Parameters

from Transform3D

Projection(Vector4, Vector4, Vector4, Vector4)

Constructs a Projection from four Vector4 values (matrix columns).

Projection Projection(Vector4 x_axis, Vector4 y_axis, Vector4 z_axis, Vector4 w_axis)

Parameters

x_axis Vector4

y_axis Vector4

z_axis Vector4

w_axis Vector4

Fields

IDENTITY

A Projection with no transformation defined. When applied to other data structures, no transformation is performed.

const IDENTITY = Projection(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1)

ZERO

A Projection with all values initialized to 0. When applied to other data structures, they will be zeroed.

const ZERO = Projection(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0)

Properties

w

The projection matrix's W vector (column 3). Equivalent to array index 3.

var w : Vector4 = Vector4(0, 0, 0, 1)

Property Value

Vector4

x

The projection matrix's X vector (column 0). Equivalent to array index 0.

var x : Vector4 = Vector4(1, 0, 0, 0)

Property Value

Vector4

y

The projection matrix's Y vector (column 1). Equivalent to array index 1.

var y : Vector4 = Vector4(0, 1, 0, 0)

Property Value

Vector4

z

The projection matrix's Z vector (column 2). Equivalent to array index 2.

var z : Vector4 = Vector4(0, 0, 1, 0)

Property Value

Vector4

Methods

create_depth_correction(bool)

Qualifiers: static

Creates a new Projection that projects positions from a depth range of -1 to 1 to one that ranges from 0 to 1, and flips the projected positions vertically, according to flip_y.

Projection create_depth_correction(bool flip_y)

Parameters

flip_y bool

create_fit_aabb(AABB)

Qualifiers: static

Creates a new Projection that scales a given projection to fit around a given AABB in projection space.

Projection create_fit_aabb(AABB aabb)

Parameters

aabb AABB

create_for_hmd(int, float, float, float, float, float, float, float)

Qualifiers: static

Creates a new Projection for projecting positions onto a head-mounted display with the given X:Y aspect ratio, distance between eyes, display width, distance to lens, oversampling factor, and depth clipping planes.

eye creates the projection for the left eye when set to 1, or the right eye when set to 2.

Projection create_for_hmd(int eye, float aspect, float intraocular_dist, float display_width, float display_to_lens, float oversample, float z_near, float z_far)

Parameters

eye int

aspect float

intraocular_dist float

display_width float

display_to_lens float

oversample float

z_near float

z_far float

create_frustum(float, float, float, float, float, float)

Qualifiers: static

Creates a new Projection that projects positions in a frustum with the given clipping planes.

Projection create_frustum(float left, float right, float bottom, float top, float z_near, float z_far)

Parameters

left float

right float

bottom float

top float

z_near float

z_far float

create_frustum_aspect(float, float, Vector2, float, float, bool)

Qualifiers: static

Creates a new Projection that projects positions in a frustum with the given size, X:Y aspect ratio, offset, and clipping planes.

flip_fov determines whether the projection's field of view is flipped over its diagonal.

Projection create_frustum_aspect(float size, float aspect, Vector2 offset, float z_near, float z_far, bool flip_fov)

Parameters

size float

aspect float

offset Vector2

z_near float

z_far float

flip_fov bool

create_light_atlas_rect(Rect2)

Qualifiers: static

Creates a new Projection that projects positions into the given Rect2.

Projection create_light_atlas_rect(Rect2 rect)

Parameters

rect Rect2

create_orthogonal(float, float, float, float, float, float)

Qualifiers: static

Creates a new Projection that projects positions using an orthogonal projection with the given clipping planes.

Projection create_orthogonal(float left, float right, float bottom, float top, float z_near, float z_far)

Parameters

left float

right float

bottom float

top float

z_near float

z_far float

create_orthogonal_aspect(float, float, float, float, bool)

Qualifiers: static

Creates a new Projection that projects positions using an orthogonal projection with the given size, X:Y aspect ratio, and clipping planes.

flip_fov determines whether the projection's field of view is flipped over its diagonal.

Projection create_orthogonal_aspect(float size, float aspect, float z_near, float z_far, bool flip_fov)

Parameters

size float

aspect float

z_near float

z_far float

flip_fov bool

create_perspective(float, float, float, float, bool)

Qualifiers: static

Creates a new Projection that projects positions using a perspective projection with the given Y-axis field of view (in degrees), X:Y aspect ratio, and clipping planes.

flip_fov determines whether the projection's field of view is flipped over its diagonal.

Projection create_perspective(float fovy, float aspect, float z_near, float z_far, bool flip_fov)

Parameters

fovy float

aspect float

z_near float

z_far float

flip_fov bool

create_perspective_hmd(float, float, float, float, bool, int, float, float)

Qualifiers: static

Creates a new Projection that projects positions using a perspective projection with the given Y-axis field of view (in degrees), X:Y aspect ratio, and clipping distances. The projection is adjusted for a head-mounted display with the given distance between eyes and distance to a point that can be focused on.

eye creates the projection for the left eye when set to 1, or the right eye when set to 2.

flip_fov determines whether the projection's field of view is flipped over its diagonal.

Projection create_perspective_hmd(float fovy, float aspect, float z_near, float z_far, bool flip_fov, int eye, float intraocular_dist, float convergence_dist)

Parameters

fovy float

aspect float

z_near float

z_far float

flip_fov bool

eye int

intraocular_dist float

convergence_dist float

determinant

Qualifiers: const

Returns a scalar value that is the signed factor by which areas are scaled by this matrix. If the sign is negative, the matrix flips the orientation of the area.

The determinant can be used to calculate the invertibility of a matrix or solve linear systems of equations involving the matrix, among other applications.

float determinant

flipped_y

Qualifiers: const

Returns a copy of this Projection with the signs of the values of the Y column flipped.

Projection flipped_y

get_aspect

Qualifiers: const

Returns the X:Y aspect ratio of this Projection's viewport.

float get_aspect

get_far_plane_half_extents

Qualifiers: const

Returns the dimensions of the far clipping plane of the projection, divided by two.

Vector2 get_far_plane_half_extents

get_fov

Qualifiers: const

Returns the horizontal field of view of the projection (in degrees).

float get_fov

get_fovy(float, float)

Qualifiers: static

Returns the vertical field of view of the projection (in degrees) associated with the given horizontal field of view (in degrees) and aspect ratio.

Note: Unlike most methods of Projection, aspect is expected to be 1 divided by the X:Y aspect ratio.

float get_fovy(float fovx, float aspect)

Parameters

fovx float

aspect float

get_lod_multiplier

Qualifiers: const

Returns the factor by which the visible level of detail is scaled by this Projection.

float get_lod_multiplier

get_pixels_per_meter(int)

Qualifiers: const

Returns the number of pixels with the given pixel width displayed per meter, after this Projection is applied.

int get_pixels_per_meter(int for_pixel_width)

Parameters

for_pixel_width int

get_projection_plane(int)

Qualifiers: const

Returns the clipping plane of this Projection whose index is given by plane.

plane should be equal to one of Projection.PLANE_NEAR, Projection.PLANE_FAR, Projection.PLANE_LEFT, Projection.PLANE_TOP, Projection.PLANE_RIGHT, or Projection.PLANE_BOTTOM.

Plane get_projection_plane(int plane)

Parameters

plane int

get_viewport_half_extents

Qualifiers: const

Returns the dimensions of the viewport plane that this Projection projects positions onto, divided by two.

Vector2 get_viewport_half_extents

get_z_far

Qualifiers: const

Returns the distance for this Projection beyond which positions are clipped.

float get_z_far

get_z_near

Qualifiers: const

Returns the distance for this Projection before which positions are clipped.

float get_z_near

inverse

Qualifiers: const

Returns a Projection that performs the inverse of this Projection's projective transformation.

Projection inverse

is_orthogonal

Qualifiers: const

Returns true if this Projection performs an orthogonal projection.

bool is_orthogonal

jitter_offseted(Vector2)

Qualifiers: const

Returns a Projection with the X and Y values from the given Vector2 added to the first and second values of the final column respectively.

Projection jitter_offseted(Vector2 offset)

Parameters

offset Vector2

perspective_znear_adjusted(float)

Qualifiers: const

Returns a Projection with the near clipping distance adjusted to be new_znear.

Note: The original Projection must be a perspective projection.

Projection perspective_znear_adjusted(float new_znear)

Parameters

new_znear float

Operators

!= (Projection)

Returns true if the projections are not equal.

Note: Due to floating-point precision errors, this may return true, even if the projections are virtually equal. An is_equal_approx method may be added in a future version of Godot.

bool != (Projection right)

Parameters

right Projection

* (Projection)

Returns a Projection that applies the combined transformations of this Projection and right.

Projection * (Projection right)

Parameters

right Projection

* (Vector4)

Projects (multiplies) the given Vector4 by this Projection matrix.

Vector4 * (Vector4 right)

Parameters

right Vector4

== (Projection)

Returns true if the projections are equal.

Note: Due to floating-point precision errors, this may return false, even if the projections are virtually equal. An is_equal_approx method may be added in a future version of Godot.

bool == (Projection right)

Parameters

right Projection

[] (int)

Returns the column of the Projection with the given index.

Indices are in the following order: x, y, z, w.

Vector4 [] (int index)

Parameters

index int