Class: ProjectionSystem

PIXI.ProjectionSystem

System plugin to the renderer to manage the projection matrix.

The projectionMatrix is a global uniform provided to all shaders. It is used to transform points in world space to normalized device coordinates.

new PIXI.ProjectionSystem (renderer)

Name Type Description
renderer PIXI.Renderer

The renderer this System works for.

Extends

  • PIXI.System

Implements

Members

defaultFrame PIXI.Rectangle readonly

Default destination frame

This is not used internally. It is not advised to use this feature specifically unless you know what you're doing. The update method will default to this frame if you do not pass the destination frame.

Default Value:
  • undefined

destinationFrame PIXI.Rectangle readonly

The destination frame used to calculate the current projection matrix.

The destination frame is the rectangle in the render-target into which contents are rendered. If rendering to the screen, the origin is on the top-left. If rendering to a framebuffer, the origin is on the bottom-left. This "flipping" phenomenon is because of WebGL convention for (shader) texture coordinates, where the bottom-left corner is (0,0). It allows display-objects to map their (0,0) position in local-space (top-left) to (0,0) in texture space (bottom-left). In other words, a sprite's top-left corner actually renders the texture's bottom-left corner. You will also notice this when using a tool like SpectorJS to view your textures at runtime.

The destination frame's dimensions (width,height) should be equal to the source frame. This is because, otherwise, the contents will be scaled to fill the destination frame. Similarly, the destination frame's (x,y) coordinates are (0,0) unless you know what you're doing.

Default Value:
  • undefined

projectionMatrix PIXI.Matrix readonly

Projection matrix

This matrix can be used to transform points from world space to normalized device coordinates, and is calculated from the sourceFrame → destinationFrame mapping provided.

The renderer's globalUniforms keeps a reference to this, and so it is available for all shaders to use as a uniform.

sourceFrame PIXI.Rectangle readonly

The source frame used to calculate the current projection matrix.

The source frame is the rectangle in world space containing the contents to be rendered.

Default Value:
  • undefined

transform PIXI.Matrix

A transform to be appended to the projection matrix.

This can be used to transform points in world-space one last time before they are outputted by the shader. You can use to rotate the whole scene, for example. Remember to clear it once you've rendered everything.

Default Value:
  • undefined

Methods

calculateProjection (destinationFrame, sourceFrame, resolution, root) void

Calculates the projectionMatrix to map points inside sourceFrame to inside destinationFrame.

Name Type Description
destinationFrame PIXI.Rectangle

The destination frame in the render-target.

sourceFrame PIXI.Rectangle

The source frame in world space.

resolution Number

The render-target's resolution, i.e. ratio of CSS to physical pixels.

root boolean

Whether rendering into the screen. Otherwise, if rendering to a framebuffer, the projection is y-flipped.

setTransform (matrix) void

Sets the transform of the active render target to the given matrix

Name Type Description
matrix PIXI.Matrix

The transformation matrix

update (destinationFrame, sourceFrame, resolution, root) void

Updates the projection-matrix based on the sourceFrame → destinationFrame mapping provided.

NOTE: It is expected you call renderer.framebuffer.setViewport(destinationFrame) after this. This is because the framebuffer viewport converts shader vertex output in normalized device coordinates to window coordinates.

NOTE-2: RenderTextureSystem#bind updates the projection-matrix when you bind a render-texture. It is expected that you dirty the current bindings when calling this manually.

Name Type Description
destinationFrame PIXI.Rectangle

The rectangle in the render-target to render the contents into. If rendering to the canvas, the origin is on the top-left; if rendering to a render-texture, the origin is on the bottom-left.

sourceFrame PIXI.Rectangle

The rectangle in world space that contains the contents being rendered.

resolution Number

The resolution of the render-target, which is the ratio of world-space (or CSS) pixels to physical pixels.

root boolean

Whether the render-target is the screen. This is required because rendering to textures is y-flipped (i.e. upside down relative to the screen).