GLKMatrixStack Reference

Framework
GLKit/GLKMath.h
Declared in
GLKMatrixStack.h

Overview

The GLKMatrixStack type defines an opaque Core Foundation type that provides a stack of 4x4 matrices. A stack of matrices allows your application to push a new matrix on the top of the stack, manipulate it, use it to render geometry, and then pop it off the stack to restore the previous matrix. This behavior is useful when implementing hierarchical animation systems.

Functions by Task

Creating Matrix Stacks

Manipulating the Stack

Getting Information About the Top Matrix on the Stack

Modifying the Top Matrix on the Stack

Functions

GLKMatrixStackCreate

Allocates and returns a new matrix stack.

GLKMatrixStackRef GLKMatrixStackCreate (
   CFAllocatorRef alloc
);
Parameters
alloc

The allocator to use to allocate the matrix stack.

Return Value

A new matrix stack, or NULL if an error occurred.

Discussion

A matrix stack is a Core Foundation type. Ownership follows “The Create Rule” in Memory Management Programming Guide for Core Foundation.

A matrix stack is initialized with a single identity matrix on the top of the stack.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKMatrixStack.h

GLKMatrixStackGetMatrix2

Returns the top left 2x2 corner of the top matrix.

GLKMatrix2 GLKMatrixStackGetMatrix2 (
   GLKMatrixStackRef stack
);
Parameters
stack

A matrix stack.

Return Value

A 2x2 matrix created by taking the top left corner of the top matrix.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKMatrixStack.h

GLKMatrixStackGetMatrix3

Returns the top left 3x3 corner of the top matrix.

GLKMatrix3 GLKMatrixStackGetMatrix3 (
   GLKMatrixStackRef stack
);
Parameters
stack

A matrix stack.

Return Value

A 3x3 matrix created by taking the top left corner of the top matrix.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKMatrixStack.h

GLKMatrixStackGetMatrix3Inverse

Fetches the top left 3x3 corner of the top matrix and returns its inverse.

GLKMatrix3 GLKMatrixStackGetMatrix3Inverse (
   GLKMatrixStackRef stack
);
Parameters
stack

A matrix stack.

Return Value

A 3x3 matrix created by taking the top left corner of the top matrix and returning its inverse.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKMatrixStack.h

GLKMatrixStackGetMatrix3InverseTranspose

Fetches the top left 3x3 corner of the top matrix and returns its inverse transpose.

GLKMatrix3 GLKMatrixStackGetMatrix3InverseTranspose (
   GLKMatrixStackRef stack
);
Parameters
stack

A matrix stack.

Return Value

A 3x3 matrix created by taking the top left corner of the top matrix and returning its inverse transpose.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKMatrixStack.h

GLKMatrixStackGetMatrix4

Returns a copy of the top matrix on the stack.

GLKMatrix4 GLKMatrixStackGetMatrix4 (
   GLKMatrixStackRef stack
);
Parameters
stack

A matrix stack.

Return Value

The top matrix.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKMatrixStack.h

GLKMatrixStackGetMatrix4Inverse

Returns the inverse of the top matrix.

GLKMatrix4 GLKMatrixStackGetMatrix4Inverse (
   GLKMatrixStackRef stack
);
Parameters
stack

A matrix stack.

Return Value

The top matrix’s inverse.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKMatrixStack.h

GLKMatrixStackGetMatrix4InverseTranspose

Returns the inverse transpose of the top matrix.

GLKMatrix4 GLKMatrixStackGetMatrix4InverseTranspose (
   GLKMatrixStackRef stack
);
Parameters
stack

A matrix stack.

Return Value

The top matrix’s inverse transpose.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKMatrixStack.h

GLKMatrixStackGetTypeID

Returns the Core Foundation type for a matrix stack.

CFTypeID GLKMatrixStackGetTypeID (
   void
);
Return Value

A Core Foundation Type.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKMatrixStack.h

GLKMatrixStackLoadMatrix4

Replaces the contents of the top matrix with a new matrix.

void GLKMatrixStackLoadMatrix4 (
   GLKMatrixStackRef stack,
   GLKMatrix4 matrix
);
Parameters
stack

A matrix stack.

matrix

The matrix whose contents should be loaded onto the stack.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKMatrixStack.h

GLKMatrixStackMultiplyMatrix4

Replaces the contents of the top matrix with a matrix calculated by multiplying the contents of the top matrix by another matrix.

void GLKMatrixStackMultiplyMatrix4 (
   GLKMatrixStackRef stack,
   GLKMatrix4 matrix
);
Parameters
stack

A matrix stack.

matrix

The matrix multiplicand.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKMatrixStack.h

GLKMatrixStackMultiplyMatrixStack

Replaces the contents of the top matrix with a matrix calculated by multiplying the contents of the top matrix by the top matrix of another matrix stack.

void GLKMatrixStackMultiplyMatrixStack (
   GLKMatrixStackRef stackLeft,
   GLKMatrixStackRef stackRight
);
Parameters
stackLeft

A matrix stack to modify.

stackRight

A matrix stack whose top matrix is to be used as the multiplicand.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKMatrixStack.h

GLKMatrixStackPop

Removes the topmost entry from the stack.

void GLKMatrixStackPop (
   GLKMatrixStackRef stack
);
Parameters
stack

A matrix stack.

Discussion

This function does nothing if the stack is already empty.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKMatrixStack.h

GLKMatrixStackPush

Push a copy of the topmost matrix onto the top of the stack.

void GLKMatrixStackPush (
   GLKMatrixStackRef stack
);
Parameters
stack

A matrix stack.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKMatrixStack.h

GLKMatrixStackRotate

Replaces the contents of the top matrix with a matrix calculated by composing the top matrix with a rotation around an arbitrary axis.

void GLKMatrixStackRotate (
   GLKMatrixStackRef stack,
   float radians,
   float x,
   float y,
   float z
);
Parameters
stack

A matrix stack.

radians

The angle of the rotation (a positive angle is counterclockwise).

x

The x coordinate of the rotation axis.

y

The y coordinate of the rotation axis.

z

The z coordinate of the rotation axis.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKMatrixStack.h

GLKMatrixStackRotateWithVector3

Replaces the contents of the top matrix with a matrix calculated by composing the top matrix with a rotation around an arbitrary axis.

void GLKMatrixStackRotateWithVector3 (
   GLKMatrixStackRef stack,
   float radians,
   GLKVector3 axisVector
);
Parameters
stack

A matrix stack.

radians

The angle of the rotation (a positive angle is counterclockwise).

axisVector

A vector whose x,y and z coordinates are used as the axis of rotation.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKMatrixStack.h

GLKMatrixStackRotateWithVector4

Replaces the contents of the top matrix with a matrix calculated by composing the top matrix with a rotation around an arbitrary axis.

void GLKMatrixStackRotateWithVector4 (
   GLKMatrixStackRef stack,
   float radians,
   GLKVector4 axisVector
);
Parameters
stack

A matrix stack.

radians

The angle of the rotation (a positive angle is counterclockwise).

axisVector

A vector whose x,y and z coordinates are used as the axis of rotation.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKMatrixStack.h

GLKMatrixStackRotateX

Replaces the contents of the top matrix with a matrix calculated by composing the top matrix with a rotation around the positive-x axis.

void GLKMatrixStackRotateX (
   GLKMatrixStackRef stack,
   float radians
);
Parameters
stack

A matrix stack.

radians

The angle of the rotation (a positive angle is counterclockwise).

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKMatrixStack.h

GLKMatrixStackRotateY

Replaces the contents of the top matrix with a matrix calculated by composing the top matrix with a rotation around the positive-y axis.

void GLKMatrixStackRotateY (
   GLKMatrixStackRef stack,
   float radians
);
Parameters
stack

A matrix stack.

radians

The angle of the rotation (a positive angle is counterclockwise).

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKMatrixStack.h

GLKMatrixStackRotateZ

Replaces the contents of the top matrix with a matrix calculated by composing the top matrix with a rotation around the positive-z axis.

void GLKMatrixStackRotateZ (
   GLKMatrixStackRef stack,
   float radians
);
Parameters
stack

A matrix stack.

radians

The angle of the rotation (a positive angle is counterclockwise).

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKMatrixStack.h

GLKMatrixStackScale

Replaces the contents of the top matrix with a matrix calculated by scaling the contents of the top matrix.

void GLKMatrixStackScale (
   GLKMatrixStackRef stack,
   float sx,
   float sy,
   float sz
);
Parameters
stack

A matrix stack.

sx

The scaling factor used to modify the x components.

sy

The scaling factor used to modify the y components.

sz

The scaling factor used to modify the z components.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKMatrixStack.h

GLKMatrixStackScaleWithVector3

Replaces the contents of the top matrix with a matrix calculated by composing the top matrix with a scaling operation.

void GLKMatrixStackScaleWithVector3 (
   GLKMatrixStackRef stack,
   GLKVector3 scaleVector
);
Parameters
stack

A matrix stack.

scaleVector

A vector whose x,y and z components are used to scale the matrix.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKMatrixStack.h

GLKMatrixStackScaleWithVector4

Replaces the contents of the top matrix with a matrix calculated by composing the top matrix with a scaling operation defined by a vector.

void GLKMatrixStackScaleWithVector4 (
   GLKMatrixStackRef stack,
   GLKVector4 scaleVector
);
Parameters
stack

A matrix stack.

scaleVector

A vector whose x,y and z components are used to scale the matrix.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKMatrixStack.h

GLKMatrixStackSize

Returns the number of matrices present on the matrix stack.

int GLKMatrixStackSize (
   GLKMatrixStackRef stack
);
Parameters
stack

A matrix stack.

Return Value

The number of matrices stored on the stack.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKMatrixStack.h

GLKMatrixStackTranslate

Replaces the contents of the top matrix with a matrix calculated by composing the top matrix with a translation operation.

void GLKMatrixStackTranslate (
   GLKMatrixStackRef stack,
   float tx,
   float ty,
   float tz
);
Parameters
stack

A matrix stack.

tx

The amount to translate the position along the x-axis.

ty

The amount to translate the position along the y-axis.

tz

The amount to translate the position along the z-axis.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKMatrixStack.h

GLKMatrixStackTranslateWithVector3

Replaces the contents of the top matrix with a matrix calculated by composing the top matrix with a translation defined by a vector.

void GLKMatrixStackTranslateWithVector3 (
   GLKMatrixStackRef stack,
   GLKVector3 translationVector
);
Parameters
stack

A matrix stack.

translationVector

A vector whose x,y and z components are used to translate the matrix.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKMatrixStack.h

GLKMatrixStackTranslateWithVector4

Replaces the contents of the top matrix with a matrix calculated by composing the top matrix with a translation defined by a vector.

void GLKMatrixStackTranslateWithVector4 (
   GLKMatrixStackRef stack,
   GLKVector4 translationVector
);
Parameters
stack

A matrix stack.

translationVector

A vector whose x,y and z components are used to translate the matrix.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKMatrixStack.h

Data Types

GLKMatrixStackRef

An opaque type that represents a stack of 4x4 matrices.

typedef struct _GLKMatrixStack *GLKMatrixStackRef;
Availability
  • Available in iOS 5.0 and later.
Declared In
GLKMatrixStack.h