Class MatrixStack

constructor

• new MatrixStack(rapid: Rapid): MatrixStack

  Creates a new MatrixStack and initializes its state.

  Parameters

  • rapid: Rapid

  Returns MatrixStack

curLocalM

currStack

curWorldM

matrix

rapid

stack

applyTransform

• applyTransform(
      transform: ITransformOptions,
      width?: number,
      height?: number,
      customMatrix?: number,
      worldMatrix?: number,
      localMatrix?: number,
  ): void

  Parameters

  • transform: ITransformOptions
  • Optionalwidth: number
  • Optionalheight: number
  • OptionalcustomMatrix: number
  • OptionalworldMatrix: number
  • OptionallocalMatrix: number

  Returns void

• applyTransform(
      x: number,
      y: number,
      scaleX?: number,
      scaleY?: number,
      rotation?: number,
      originX?: number,
      originY?: number,
      width?: number,
      height?: number,
      offsetX?: number,
      offsetY?: number,
      customMatrix?: number,
      worldMatrix?: number,
      localMatrix?: number,
  ): void

  Parameters

  • x: number
  • y: number
  • OptionalscaleX: number
  • OptionalscaleY: number
  • Optionalrotation: number
  • OptionaloriginX: number
  • OptionaloriginY: number
  • Optionalwidth: number
  • Optionalheight: number
  • OptionaloffsetX: number
  • OptionaloffsetY: number
  • OptionalcustomMatrix: number
  • OptionalworldMatrix: number
  • OptionallocalMatrix: number

  Returns void

getGlobalPosition

• getGlobalPosition(): { x: number; y: number }

  Extracts the global position (translation) from the current world matrix.

  Returns { x: number; y: number }

  An object containing x and y global coordinates.

getGlobalRotation

• getGlobalRotation(): number

  Extracts the global rotation (in radians) from the current world matrix.

  Returns number

  The global rotation in radians.

getGlobalScale

• getGlobalScale(): { x: number; y: number }

  Extracts the global scale from the current world matrix.

  Returns { x: number; y: number }

  An object containing x and y global scale factors.

getTransform

• getTransform(): Float32Array

  Returns the current world matrix as Float32Array [a, b, c, d, tx, ty].

  Returns Float32Array

identity

• identity(): void

  Sets the current local and world matrices to the identity matrix.

  Returns void

localToWorld

• localToWorld(x: number, y: number): { x: number; y: number }

  Transforms a point from local coordinates to world coordinates. Uses the current world matrix to apply the transformation.

  Parameters

  • x: number

    Local x coordinate.

  • y: number

    Local y coordinate.

  Returns { x: number; y: number }

  The transformed point in world coordinates.

reset

• reset(): void

  Resets the entire stack state context, clearing matrices and step actions.

  Returns void

restore

• restore(): void

  Restores the matrix state from the top of the stack. Equivalent to context.restore().

  Returns void

restoreAll

• restoreAll(): void

  Returns void

retainMatrix

• retainMatrix<T extends number | MatrixSaveState>(matrix: T): T

  Removes a matrix from the frame recycle queue so it remains valid across reset() calls.

  Passing a MatrixSaveState retains its local and world matrices; parent is not retained because it belongs to the parent stack state. Retained matrices must eventually be released with matrix.free().

  Type Parameters

  • T extends number | MatrixSaveState

  Parameters

  • matrix: T

    A matrix ID or the state returned by save().

  Returns T

  The supplied ID or state, preserving its input type.

rotate

• rotate(radians: number): void

  Rotates the current local and world matrices by the given radians.

  Parameters

  • radians: number

    The rotation angle in radians.

  Returns void

rotateWithOffset

• rotateWithOffset(radians: number, offsetX: number, offsetY: number): void

  Rotates the current local and world matrices around a pivot point that is offset from the matrix origin by (offsetX, offsetY).

  This is a convenience wrapper around the common translate → rotate → translate-back pattern, avoiding manual coordinate juggling at the call site.

  Parameters

  • radians: number

    The rotation angle in radians.

  • offsetX: number

    The x component of the pivot point in local space.

  • offsetY: number

    The y component of the pivot point in local space.

  Returns void

  Example

  // Rotate a 64×64 sprite around its centre
  stack.rotateWithOffset(angle, 32, 32);
  Copy

save

• save(
      matrixWorld?: number | MatrixSaveState,
      matrixLocal?: number,
  ): MatrixSaveState

  Saves the current matrix state and pushes it onto the stack. Equivalent to context.save(). Provided matrix IDs are used directly and remain caller-owned; only matrices created by this call are queued for recycling by reset().

  Parameters

  • OptionalmatrixWorld: number | MatrixSaveState

    Optional world matrix ID or saved state from this store; defaults to parent * local.

  • OptionalmatrixLocal: number

    Optional local matrix ID from this store; defaults to identity.

  Returns MatrixSaveState

  Matrix IDs for the saved parent, local, and world transforms.

scale

• scale(scaleX: number, scaleY?: number): void

  Scales the current local and world matrices by scaleX and scaleY.

  Parameters

  • scaleX: number

    Scaling factor along the x-axis.

  • scaleY: number = scaleX

    Scaling factor along the y-axis.

  Returns void

setTransform

• setTransform(f: Float32Array): void

  Directly overwrites the current world matrix with the given 6-element 2D transform.

  Parameters

  • f: Float32Array

  Returns void

toCSSMatrix

• toCSSMatrix(): string

  Returns string

transformPoint

• transformPoint(x: number, y: number): { x: number; y: number }

  Parameters

  • x: number
  • y: number

  Returns { x: number; y: number }

translate

• translate(x: number, y: number): void

  Translates the current local and world matrices by x and y.

  Parameters

  • x: number

    Translation along the x-axis.

  • y: number

    Translation along the y-axis.

  Returns void

worldToLocal

• worldToLocal(x: number, y: number): { x: number; y: number }

  Transforms a point from world coordinates to local coordinates. Useful for hit testing against objects placed in world space.

  Parameters

  • x: number

    World x coordinate.

  • y: number

    World y coordinate.

  Returns { x: number; y: number }

  The transformed point in local coordinates.