Struct dx::platform::core::MatrixStack

source · [−]

pub struct MatrixStack {}

Implementations

source

impl MatrixStack

source

pub fn new(ctx: &Context) -> MatrixStack

Allocates a new MatrixStack that can be used to build up transformations relating to objects in a scenegraph like hierarchy. (See the description of MatrixStack and MatrixEntry for more details of what a matrix stack is best suited for)

When a MatrixStack is first allocated it is conceptually positioned at the root of your scenegraph hierarchy. As you traverse your scenegraph then you should call MatrixStack::push whenever you move down a level and MatrixStack::pop whenever you move back up a level towards the root.

Once you have allocated a MatrixStack you can get a reference to the current transformation for the current position in the hierarchy by calling MatrixStack::get_entry.

Once you have allocated a MatrixStack you can apply operations such as rotate, scale and translate to modify the current transform for the current position in the hierarchy by calling MatrixStack::rotate, MatrixStack::scale and MatrixStack::translate.

`ctx`

A Context

Returns

A newly allocated MatrixStack

source

pub fn frustum(
    &self,
    left: f32,
    right: f32,
    bottom: f32,
    top: f32,
    z_near: f32,
    z_far: f32
)

Replaces the current matrix with a perspective matrix for a given viewing frustum defined by 4 side clip planes that all cross through the origin and 2 near and far clip planes.

`left`

X position of the left clipping plane where it intersects the near clipping plane

`right`

X position of the right clipping plane where it intersects the near clipping plane

`bottom`

Y position of the bottom clipping plane where it intersects the near clipping plane

`top`

Y position of the top clipping plane where it intersects the near clipping plane

`z_near`

The distance to the near clipping plane (Must be positive)

`z_far`

The distance to the far clipping plane (Must be positive)

source

pub fn get(&self) -> (Matrix, Matrix )

Resolves the current self transform into a Matrix by combining the operations that have been applied to build up the current transform.

There are two possible ways that this fn may return its result depending on whether the stack is able to directly point to an internal Matrix or whether the result needs to be composed of multiple operations.

If an internal matrix contains the required result then this fn will directly return a pointer to that matrix, otherwise if the fn returns None then matrix will be initialized to match the current transform of self.

matrix will be left untouched if a direct pointer is returned.

`matrix`

The potential destination for the current matrix

Returns

A direct pointer to the current transform or None and in that case matrix will be initialized with the value of the current transform.

source

pub fn entry(&self) -> Option<MatrixEntry>

Gets a reference to the current transform represented by a MatrixEntry pointer.

The transform represented by a MatrixEntry is immutable.

MatrixEntrys are reference counted using MatrixEntry::ref and MatrixEntry::unref and you should call MatrixEntry::unref when you are finished with and entry you get via MatrixStack::get_entry.

Returns

A pointer to the MatrixEntry representing the current matrix stack transform.

source

pub fn inverse(&self) -> (bool, Matrix )

Gets the inverse transform of the current matrix and uses it to initialize a new Matrix.

`inverse`

The destination for a 4x4 inverse transformation matrix

Returns

true if the inverse was successfully calculated or false for degenerate transformations that can’t be inverted (in this case the inverse matrix will simply be initialized with the identity matrix)

source

pub fn load_identity(&self)

Resets the current matrix to the identity matrix.

source

pub fn multiply(&self, matrix: &Matrix)

Multiplies the current matrix by the given matrix.

`matrix`

the matrix to multiply with the current model-view

source

pub fn orthographic(
    &self,
    x_1: f32,
    y_1: f32,
    x_2: f32,
    y_2: f32,
    near: f32,
    far: f32
)

Replaces the current matrix with an orthographic projection matrix.

`x_1`

The x coordinate for the first vertical clipping plane

`y_1`

The y coordinate for the first horizontal clipping plane

`x_2`

The x coordinate for the second vertical clipping plane

`y_2`

The y coordinate for the second horizontal clipping plane

`near`

The distance to the near clipping plane (will be negative if the plane is behind the viewer)

`far`

The distance to the far clipping plane (will be negative if the plane is behind the viewer)

source

pub fn perspective(&self, fov_y: f32, aspect: f32, z_near: f32, z_far: f32)

Replaces the current matrix with a perspective matrix based on the provided values.

You should be careful not to have too great a z_far / z_near ratio since that will reduce the effectiveness of depth testing since there wont be enough precision to identify the depth of objects near to each other.

`fov_y`

Vertical field of view angle in degrees.

`aspect`

The (width over height) aspect ratio for display

`z_near`

The distance to the near clipping plane (Must be positive, and must not be 0)

`z_far`

The distance to the far clipping plane (Must be positive)

source

pub fn pop(&self)

Restores the previous transform that was last saved by calling MatrixStack::push.

This is usually called while traversing a scenegraph whenever you return up one level in the graph towards the root node.

source

pub fn push(&self)

Saves the current transform and starts a new transform that derives from the current transform.

This is usually called while traversing a scenegraph whenever you traverse one level deeper. MatrixStack::pop can then be called when going back up one layer to restore the previous transform of an ancestor.

source

pub fn rotate(&self, angle: f32, x: f32, y: f32, z: f32)

Multiplies the current matrix by one that rotates the around the axis-vector specified by x, y and z. The rotation follows the right-hand thumb rule so for example rotating by 10 degrees about the axis-vector (0, 0, 1) causes a small counter-clockwise rotation.

`angle`

Angle in degrees to rotate.

`x`

X-component of vertex to rotate around.

`y`

Y-component of vertex to rotate around.

`z`

Z-component of vertex to rotate around.

source

pub fn rotate_euler(&self, euler: &Euler)

Multiplies the current matrix by one that rotates according to the rotation described by euler.

`euler`

A Euler

source

pub fn rotate_quaternion(&self, quaternion: &Quaternion)

Multiplies the current matrix by one that rotates according to the rotation described by quaternion.

`quaternion`

A Quaternion

source

pub fn scale(&self, x: f32, y: f32, z: f32)

Multiplies the current matrix by one that scales the x, y and z axes by the given values.

`x`

Amount to scale along the x-axis

`y`

Amount to scale along the y-axis

`z`

Amount to scale along the z-axis

source

pub fn set(&self, matrix: &Matrix)

Replaces the current self matrix value with the value of matrix. This effectively discards any other operations that were applied since the last time MatrixStack::push was called or since the stack was initialized.