Struct Projection

Namespace

Godot

Assembly

GodotSharp.dll

A 4x4 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 has a lower memory footprint. Used internally as Camera3D's projection matrix.

public struct Projection : IEquatable<Projection>

Implements

IEquatable<Projection>

Inherited Members

object.GetType()

object.Equals(object, object)

object.ReferenceEquals(object, object)

Constructors

Projection(Transform3D)

Constructs a new Projection from a Transform3D.

public Projection(Transform3D transform)

Parameters

transform Transform3D

The Transform3D.

Projection(Vector4, Vector4, Vector4, Vector4)

Constructs a projection from 4 vectors (matrix columns).

public Projection(Vector4 x, Vector4 y, Vector4 z, Vector4 w)

Parameters

x Vector4

The X column, or column index 0.

y Vector4

The Y column, or column index 1.

z Vector4

The Z column, or column index 2.

w Vector4

The W column, or column index 3.

Fields

W

The projection's W column. Also accessible by using the index position [3].

public Vector4 W

Field Value

Vector4

X

The projection's X column. Also accessible by using the index position [0].

public Vector4 X

Field Value

Vector4

Y

The projection's Y column. Also accessible by using the index position [1].

public Vector4 Y

Field Value

Vector4

Z

The projection's Z column. Also accessible by using the index position [2].

public Vector4 Z

Field Value

Vector4

Properties

Identity

The identity projection, with no distortion applied. This is used as a replacement for Projection() in GDScript. Do not use new Projection() with no arguments in C#, because it sets all values to zero.

public static Projection Identity { get; }

Property Value

Projection

Equivalent to new Projection(new Vector4(1, 0, 0, 0), new Vector4(0, 1, 0, 0), new Vector4(0, 0, 1, 0), new Vector4(0, 0, 0, 1)).

this[int]

Access whole columns in the form of Vector4.

public Vector4 this[int column] { readonly get; set; }

Parameters

column int

Which column vector.

Property Value

Vector4

Exceptions

ArgumentOutOfRangeException

column is not 0, 1, 2 or 3.

this[int, int]

Access single values.

public float this[int column, int row] { readonly get; set; }

Parameters

column int

Which column vector.

row int

Which row of the column.

Property Value

float

Exceptions

ArgumentOutOfRangeException

column or row are not 0, 1, 2 or 3.

Zero

Zero projection, a projection with all components set to 0.

public static Projection Zero { get; }

Property Value

Projection

Equivalent to new Projection(Vector4.Zero, Vector4.Zero, Vector4.Zero, Vector4.Zero).

Methods

CreateDepthCorrection(bool)

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 flipY.

public static Projection CreateDepthCorrection(bool flipY)

Parameters

flipY bool

If the projection should be flipped vertically.

Returns

Projection

The created projection.

CreateFitAabb(Aabb)

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

public static Projection CreateFitAabb(Aabb aabb)

Parameters

aabb Aabb

The Aabb to fit the projection around.

Returns

Projection

The created projection.

CreateForHmd(int, float, float, float, float, float, float, float)

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.

public static Projection CreateForHmd(int eye, float aspect, float intraocularDist, float displayWidth, float displayToLens, float oversample, float zNear, float zFar)

Parameters

eye int

The eye to create the projection for. The left eye when set to 1, the right eye when set to 2.

aspect float

The aspect ratio.

intraocularDist float

The distance between the eyes.

displayWidth float

The display width.

displayToLens float

The distance to the lens.

oversample float

The oversampling factor.

zNear float

The near clipping distance.

zFar float

The far clipping distance.

Returns

Projection

The created projection.

CreateFrustum(float, float, float, float, float, float)

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

public static Projection CreateFrustum(float left, float right, float bottom, float top, float depthNear, float depthFar)

Parameters

left float

The left clipping distance.

right float

The right clipping distance.

bottom float

The bottom clipping distance.

top float

The top clipping distance.

depthNear float

The near clipping distance.

depthFar float

The far clipping distance.

Returns

Projection

The created projection.

CreateFrustumAspect(float, float, Vector2, float, float, bool)

Creates a new Projection that projects positions in a frustum with the given size, X:Y aspect ratio, offset, and clipping planes. flipFov determines whether the projection's field of view is flipped over its diagonal.

public static Projection CreateFrustumAspect(float size, float aspect, Vector2 offset, float depthNear, float depthFar, bool flipFov)

Parameters

size float

The frustum size.

aspect float

The aspect ratio.

offset Vector2

The offset to apply.

depthNear float

The near clipping distance.

depthFar float

The far clipping distance.

flipFov bool

If the field of view is flipped over the projection's diagonal.

Returns

Projection

The created projection.

CreateLightAtlasRect(Rect2)

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

public static Projection CreateLightAtlasRect(Rect2 rect)

Parameters

rect Rect2

The Rect2 to project positions into.

Returns

Projection

The created projection.

CreateOrthogonal(float, float, float, float, float, float)

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

public static Projection CreateOrthogonal(float left, float right, float bottom, float top, float zNear, float zFar)

Parameters

left float

The left clipping distance.

right float

The right clipping distance.

bottom float

The bottom clipping distance.

top float

The top clipping distance.

zNear float

The near clipping distance.

zFar float

The far clipping distance.

Returns

Projection

The created projection.

CreateOrthogonalAspect(float, float, float, float, bool)

Creates a new Projection that projects positions using an orthogonal projection with the given size, X:Y aspect ratio, and clipping planes. flipFov determines whether the projection's field of view is flipped over its diagonal.

public static Projection CreateOrthogonalAspect(float size, float aspect, float zNear, float zFar, bool flipFov)

Parameters

size float

The frustum size.

aspect float

The aspect ratio.

zNear float

The near clipping distance.

zFar float

The far clipping distance.

flipFov bool

If the field of view is flipped over the projection's diagonal.

Returns

Projection

The created projection.

CreatePerspective(float, float, float, float, bool)

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. flipFov determines whether the projection's field of view is flipped over its diagonal.

public static Projection CreatePerspective(float fovyDegrees, float aspect, float zNear, float zFar, bool flipFov)

Parameters

fovyDegrees float

The vertical field of view (in degrees).

aspect float

The aspect ratio.

zNear float

The near clipping distance.

zFar float

The far clipping distance.

flipFov bool

If the field of view is flipped over the projection's diagonal.

Returns

Projection

The created projection.

CreatePerspectiveHmd(float, float, float, float, bool, int, float, float)

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. flipFov determines whether the projection's field of view is flipped over its diagonal.

public static Projection CreatePerspectiveHmd(float fovyDegrees, float aspect, float zNear, float zFar, bool flipFov, int eye, float intraocularDist, float convergenceDist)

Parameters

fovyDegrees float

The vertical field of view (in degrees).

aspect float

The aspect ratio.

zNear float

The near clipping distance.

zFar float

The far clipping distance.

flipFov bool

If the field of view is flipped over the projection's diagonal.

eye int

The eye to create the projection for. The left eye when set to 1, the right eye when set to 2.

intraocularDist float

The distance between the eyes.

convergenceDist float

The distance to a point of convergence that can be focused on.

Returns

Projection

The created projection.

Determinant()

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.

public readonly float Determinant()

Returns

float

The determinant calculated from this projection.

Equals(Projection)

Returns true if the projections are exactly equal.

public readonly bool Equals(Projection other)

Parameters

other Projection

The other projection.

Returns

bool

Whether or not the projections are exactly equal.

Equals(object?)

Returns true if the projection is exactly equal to the given object (obj).

public override readonly bool Equals(object? obj)

Parameters

obj object

The object to compare with.

Returns

bool

Whether or not the vector and the object are equal.

FlippedY()

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

public readonly Projection FlippedY()

Returns

Projection

The flipped projection.

GetAspect()

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

public readonly float GetAspect()

Returns

float

The aspect ratio from this projection's viewport.

GetFarPlaneHalfExtents()

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

public readonly Vector2 GetFarPlaneHalfExtents()

Returns

Vector2

The half extents for this projection's far plane.

GetFov()

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

public readonly float GetFov()

Returns

float

The horizontal field of view of this projection.

GetFovy(float, float)

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

public static float GetFovy(float fovx, float aspect)

Parameters

fovx float

The horizontal field of view (in degrees).

aspect float

The aspect ratio.

Returns

float

The vertical field of view of this projection.

GetHashCode()

Serves as the hash function for Projection.

public override readonly int GetHashCode()

Returns

int

A hash code for this projection.

GetLodMultiplier()

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

public readonly float GetLodMultiplier()

Returns

float

The level of detail factor for this projection.

GetPixelsPerMeter(int)

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

public readonly int GetPixelsPerMeter(int forPixelWidth)

Parameters

forPixelWidth int

The width for each pixel (in meters).

Returns

int

The number of pixels per meter.

GetProjectionPlane(Planes)

Returns the clipping plane of this Projection whose index is given by plane. plane should be equal to one of Near, Far, Left, Top, Right, or Bottom.

public readonly Plane GetProjectionPlane(Projection.Planes plane)

Parameters

plane Projection.Planes

The kind of clipping plane to get from the projection.

Returns

Plane

The clipping plane of this projection.

GetViewportHalfExtents()

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

public readonly Vector2 GetViewportHalfExtents()

Returns

Vector2

The half extents for this projection's viewport plane.

GetZFar()

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

public readonly float GetZFar()

Returns

float

The distance beyond which positions are clipped.

GetZNear()

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

public readonly float GetZNear()

Returns

float

The distance before which positions are clipped.

Inverse()

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

public readonly Projection Inverse()

Returns

Projection

The inverted projection.

IsOrthogonal()

Returns true if this Projection performs an orthogonal projection.

public readonly bool IsOrthogonal()

Returns

bool

If the projection performs an orthogonal projection.

JitterOffseted(Vector2)

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.

public readonly Projection JitterOffseted(Vector2 offset)

Parameters

offset Vector2

The offset to apply to the projection.

Returns

Projection

The offsetted projection.

PerspectiveZNearAdjusted(float)

Returns a Projection with the near clipping distance adjusted to be newZNear. Note: The original Projection must be a perspective projection.

public readonly Projection PerspectiveZNearAdjusted(float newZNear)

Parameters

newZNear float

The near clipping distance to adjust the projection to.

Returns

Projection

The adjusted projection.

ToString()

Converts this Projection to a string.

public override readonly string ToString()

Returns

string

A string representation of this projection.

ToString(string?)

Converts this Projection to a string with the given format.

public readonly string ToString(string? format)

Parameters

format string

Returns

string

A string representation of this projection.

Operators

operator ==(Projection, Projection)

Returns true if the projections are exactly equal.

public static bool operator ==(Projection left, Projection right)

Parameters

left Projection

The left projection.

right Projection

The right projection.

Returns

bool

Whether or not the projections are exactly equal.

explicit operator Transform3D(Projection)

Constructs a new Transform3D from the Projection.

public static explicit operator Transform3D(Projection proj)

Parameters

proj Projection

The Projection.

Returns

Transform3D

operator !=(Projection, Projection)

Returns true if the projections are not exactly equal.

public static bool operator !=(Projection left, Projection right)

Parameters

left Projection

The left projection.

right Projection

The right projection.

Returns

bool

Whether or not the projections are not exactly equal.

operator *(Projection, Projection)

Composes these two projections by multiplying them together. This has the effect of applying the right and then the left projection.

public static Projection operator *(Projection left, Projection right)

Parameters

left Projection

The parent transform.

right Projection

The child transform.

Returns

Projection

The composed projection.

operator *(Projection, Vector3)

Returns a Vector3 transformed (multiplied) by the projection.

public static Vector3 operator *(Projection proj, Vector3 vector)

Parameters

proj Projection

The projection to apply.

vector Vector3

A Vector3 to transform.

Returns

Vector3

The transformed Vector3.

operator *(Projection, Vector4)

Returns a Vector4 transformed (multiplied) by the projection.

public static Vector4 operator *(Projection proj, Vector4 vector)

Parameters

proj Projection

The projection to apply.

vector Vector4

A Vector4 to transform.

Returns

Vector4

The transformed Vector4.

operator *(Vector4, Projection)

Returns a Vector4 transformed (multiplied) by the transpose of the projection. For transforming by inverse of a projection projection.Inverse() * vector can be used instead. See Inverse().

public static Vector4 operator *(Vector4 vector, Projection proj)

Parameters

vector Vector4

A Vector4 to transform.

proj Projection

The projection to apply.

Returns

Vector4

The inversely transformed Vector4.