Struct MatrixStack

pub struct MatrixStack(/* private fields */);

Implementations

impl MatrixStack

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

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)

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 function 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 function will directly return a pointer to that matrix, otherwise if the function returns None then matrix will be initialized to match the current transform of self.

<note>``matrix will be left untouched if a direct pointer is returned.</note>

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.

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

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

<note>The transform represented by a MatrixEntry is immutable.</note>

<note>``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.</note>

Returns

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

pub fn get_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)

pub fn load_identity(&self)

Resets the current matrix to the identity matrix.

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

Multiplies the current matrix by the given matrix.

matrix

the matrix to multiply with the current model-view

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 <emphasis>distance</emphasis> to the near clipping plane (will be <emphasis>negative</emphasis> if the plane is behind the viewer)

far

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

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.

<note>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.</note>

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)

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.

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.

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.

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

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

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

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.

matrix

A Matrix replace the current matrix value with

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

Multiplies the current matrix by one that translates along all three axes according to the given values.

x

Distance to translate along the x-axis

y

Distance to translate along the y-axis

z

Distance to translate along the z-axis

Trait Implementations

impl Clone for MatrixStack

fn clone(&self) -> MatrixStack

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for MatrixStack

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for MatrixStack

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Hash for MatrixStack

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for MatrixStack

fn cmp(&self, other: &MatrixStack) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<T: ObjectType> PartialEq<T> for MatrixStack

fn eq(&self, other: &T) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: ObjectType> PartialOrd<T> for MatrixStack

fn partial_cmp(&self, other: &T) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl StaticType for MatrixStack

fn static_type() -> Type

Returns the type identifier of Self.

impl Eq for MatrixStack

impl IsA<Object> for MatrixStack