The Pipeline Manager is responsible for the creation, activation, running and destruction of WebGL Pipelines and Post FX Pipelines in Phaser 3.
The WebGLRenderer
owns a single instance of the Pipeline Manager, which you can access
via the WebGLRenderer.pipelines
property.
By default, there are 9 pipelines installed into the Pipeline Manager when Phaser boots:
You can add your own custom pipeline via the PipelineManager.add
method. Pipelines are
identified by unique string-based keys.
new PipelineManager(renderer)
name | type | description |
---|---|---|
renderer | Phaser.Renderer.WebGL.WebGLRenderer |
A reference to the WebGL Renderer that owns this Pipeline Manager. |
A constant-style reference to the Bitmap Mask Pipeline Instance.
This is the default Phaser 3 mask pipeline and is used Game Objects using
a Bitmap Mask. This property is set during the boot
method.
A constant-style reference to the FX Pipeline Instance.
This is the default Phaser 3 FX pipeline and is used by the WebGL Renderer to manage
Game Objects with special effects enabled. This property is set during the boot
method.
A constant-style reference to the Mobile Pipeline Instance.
This is the default Phaser 3 mobile pipeline and is used by the WebGL Renderer to manage
camera effects and more on mobile devices. This property is set during the boot
method.
A constant-style reference to the Multi Pipeline Instance.
This is the default Phaser 3 pipeline and is used by the WebGL Renderer to manage
camera effects and more. This property is set during the boot
method.
A constant-style reference to the Utility Pipeline Instance.
This map stores all pipeline classes available in this manager.
The Utility Class must always come first.
Current pipeline in use by the WebGLRenderer.
The default Game Object pipeline.
The amount in which each target frame will increase.
Defaults to 32px but can be overridden in the config.
A reference to the Full Frame 1 Render Target that belongs to the
Utility Pipeline. This property is set during the boot
method.
This Render Target is the full size of the renderer.
You can use this directly in Post FX Pipelines for multi-target effects. However, be aware that these targets are shared between all post fx pipelines.
A reference to the Full Frame 2 Render Target that belongs to the
Utility Pipeline. This property is set during the boot
method.
This Render Target is the full size of the renderer.
You can use this directly in Post FX Pipelines for multi-target effects. However, be aware that these targets are shared between all post fx pipelines.
A reference to the Half Frame 1 Render Target that belongs to the
Utility Pipeline. This property is set during the boot
method.
This Render Target is half the size of the renderer.
You can use this directly in Post FX Pipelines for multi-target effects. However, be aware that these targets are shared between all post fx pipelines.
A reference to the Half Frame 2 Render Target that belongs to the
Utility Pipeline. This property is set during the boot
method.
This Render Target is half the size of the renderer.
You can use this directly in Post FX Pipelines for multi-target effects. However, be aware that these targets are shared between all post fx pipelines.
The largest render target dimension before we just use a full-screen target.
This map stores all pipeline instances in this manager.
This is populated with the default pipelines in the boot
method.
This map stores all Post FX Pipeline classes available in this manager.
As of v3.60 this is now populated by default with the following Post FX Pipelines:
These are added as part of the boot process.
If you do not wish to add them, specify disableFX: true
in your game config.
See the FX Controller class for more details about each FX.
The previous WebGLPipeline that was in use.
This is set when clearPipeline
is called and restored in rebindPipeline
if none is given.
An array of RenderTarget instances that belong to this pipeline.
A reference to the WebGL Renderer instance.
The Render Target index. Used internally by the methods in this class. Do not modify directly.
Adds a pipeline instance to this Pipeline Manager.
The name of the instance must be unique within this manager.
Make sure to pass an instance to this method, not a base class.
For example, you should pass it like this:
this.add('yourName', new CustomPipeline(game));`
and not like this:
this.add('yourName', CustomPipeline);`
To add a Post Pipeline, see addPostPipeline
instead.
name | type | description |
---|---|---|
name | string |
A unique string-based key for the pipeline within the manager. |
pipeline | Phaser.Renderer.WebGL.WebGLPipeline |
A pipeline instance which must extend |
The pipeline instance that was passed.
Adds a Post Pipeline to this Pipeline Manager.
Make sure to pass a base class to this method, not an instance.
For example, you should pass it like this:
this.addPostPipeline('yourName', CustomPipeline);`
and not like this:
this.addPostPipeline('yourName', new CustomPipeline());`
To add a regular pipeline, see the add
method instead.
name | type | description |
---|---|---|
name | string |
A unique string-based key for the pipeline within the manager. |
pipeline | function |
A pipeline class which must extend |
This Pipeline Manager.
Draws the source1
and source2
Render Targets to the target
Render Target
using a linear blend effect, which is controlled by the strength
parameter.
The draw itself is handled by the Utility Pipeline.
name | type | arguments | Default | description |
---|---|---|---|---|
source1 | Phaser.Renderer.WebGL.RenderTarget |
The first source Render Target. |
||
source2 | Phaser.Renderer.WebGL.RenderTarget |
The second source Render Target. |
||
target | Phaser.Renderer.WebGL.RenderTarget | <optional> |
The target Render Target. |
|
strength | number | <optional> | 1 |
The strength of the blend. |
clearAlpha | boolean | <optional> | true |
Clear the alpha channel when running |
This Pipeline Manager instance.
Draws the source1
and source2
Render Targets to the target
Render Target
using an additive blend effect, which is controlled by the strength
parameter.
The draw itself is handled by the Utility Pipeline.
name | type | arguments | Default | description |
---|---|---|---|---|
source1 | Phaser.Renderer.WebGL.RenderTarget |
The first source Render Target. |
||
source2 | Phaser.Renderer.WebGL.RenderTarget |
The second source Render Target. |
||
target | Phaser.Renderer.WebGL.RenderTarget | <optional> |
The target Render Target. |
|
strength | number | <optional> | 1 |
The strength of the blend. |
clearAlpha | boolean | <optional> | true |
Clear the alpha channel when running |
This Pipeline Manager instance.
Copy the source
Render Target to the target
Render Target.
The difference with this copy is that no resizing takes place. If the source
Render Target is larger than the target
then only a portion the same size as
the target
dimensions is copied across.
You can optionally set the brightness factor of the copy.
name | type | arguments | Default | description |
---|---|---|---|---|
source | Phaser.Renderer.WebGL.RenderTarget |
The source Render Target. |
||
target | Phaser.Renderer.WebGL.RenderTarget |
The target Render Target. |
||
brightness | number | <optional> | 1 |
The brightness value applied to the frame copy. |
clear | boolean | <optional> | true |
Clear the target before copying? |
clearAlpha | boolean | <optional> | true |
Clear the alpha channel when running |
eraseMode | boolean | <optional> | false |
Erase source from target using ERASE Blend Mode? |
This Pipeline Manager instance.
Internal boot handler, called by the WebGLRenderer durings its boot process.
Adds all of the default pipelines, based on the game config, and then calls
the boot
method on each one of them.
Finally, the default pipeline is set.
name | type | description |
---|---|---|
pipelineConfig | Phaser.Types.Core.PipelineConfig |
The pipeline configuration object as set in the Game Config. |
defaultPipeline | string |
The name of the default Game Object pipeline, as set in the Game Config |
autoMobilePipeline | boolean |
Automatically set the default pipeline to mobile if non-desktop detected? |
Flushes the current pipeline being used and then clears it, along with the
the current shader program and vertex buffer from the WebGLRenderer
.
Then resets the blend mode to NORMAL.
Call this before jumping to your own gl context handler, and then call rebind
when
you wish to return control to Phaser again.
Clears the given Render Target.
name | type | arguments | Default | description |
---|---|---|---|---|
target | Phaser.Renderer.WebGL.RenderTarget |
The Render Target to clear. |
||
clearAlpha | boolean | <optional> | true |
Clear the alpha channel when running |
This Pipeline Manager instance.
Copy the source
Render Target to the target
Render Target.
You can optionally set the brightness factor of the copy.
The difference between this method and drawFrame
is that this method
uses a faster copy shader, where only the brightness can be modified.
If you need color level manipulation, see drawFrame
instead.
The copy itself is handled by the Utility Pipeline.
name | type | arguments | Default | description |
---|---|---|---|---|
source | Phaser.Renderer.WebGL.RenderTarget |
The source Render Target. |
||
target | Phaser.Renderer.WebGL.RenderTarget | <optional> |
The target Render Target. |
|
brightness | number | <optional> | 1 |
The brightness value applied to the frame copy. |
clear | boolean | <optional> | true |
Clear the target before copying? |
clearAlpha | boolean | <optional> | true |
Clear the alpha channel when running |
This Pipeline Manager instance.
Binds the source
Render Target and then copies a section of it to the target
Render Target.
This method is extremely fast because it uses gl.copyTexSubImage2D
and doesn't
require the use of any shaders. Remember the coordinates are given in standard WebGL format,
where x and y specify the lower-left corner of the section, not the top-left. Also, the
copy entirely replaces the contents of the target texture, no 'merging' or 'blending' takes
place.
name | type | arguments | Default | description |
---|---|---|---|---|
source | Phaser.Renderer.WebGL.RenderTarget |
The source Render Target. |
||
target | Phaser.Renderer.WebGL.RenderTarget |
The target Render Target. |
||
x | number |
The x coordinate of the lower left corner where to start copying. |
||
y | number |
The y coordinate of the lower left corner where to start copying. |
||
width | number |
The width of the texture. |
||
height | number |
The height of the texture. |
||
clear | boolean | <optional> | true |
Clear the target before copying? |
clearAlpha | boolean | <optional> | true |
Clear the alpha channel when running |
This Pipeline Manager instance.
Pops the framebuffer from the renderers FBO stack and sets that as the active target,
then draws the source
Render Target to it. It then resets the renderer textures.
This should be done when you need to draw the final results of a pipeline to the game
canvas, or the next framebuffer in line on the FBO stack. You should only call this once
in the onDraw
handler and it should be the final thing called. Be careful not to call
this if you need to actually use the pipeline shader, instead of the copy shader. In
those cases, use the bindAndDraw
method.
name | type | description |
---|---|---|
source | Phaser.Renderer.WebGL.RenderTarget |
The Render Target to draw from. |
Destroy the Pipeline Manager, cleaning up all related resources and references.
Copy the source
Render Target to the target
Render Target, using the
given Color Matrix.
The difference between this method and copyFrame
is that this method
uses a color matrix shader, where you have full control over the luminance
values used during the copy. If you don't need this, you can use the faster
copyFrame
method instead.
The copy itself is handled by the Utility Pipeline.
name | type | arguments | Default | description |
---|---|---|---|---|
source | Phaser.Renderer.WebGL.RenderTarget |
The source Render Target. |
||
target | Phaser.Renderer.WebGL.RenderTarget | <optional> |
The target Render Target. |
|
clearAlpha | boolean | <optional> | true |
Clear the alpha channel when running |
colorMatrix | Phaser.Display.ColorMatrix | <optional> |
The Color Matrix to use when performing the draw. |
This Pipeline Manager instance.
Flushes the current pipeline, if one is bound.
Returns true
if the current pipeline is forced to use texture unit zero.
true
if the current pipeline is forced to use texture unit zero.
Returns the pipeline instance based on the given name, or instance.
If no instance, or matching name, exists in this manager, it returns undefined
.
name | type | description |
---|---|---|
pipeline | string | Phaser.Renderer.WebGL.WebGLPipeline |
Either the string-based name of the pipeline to get, or a pipeline instance to look-up. |
The pipeline instance, or undefined
if not found.
Gets a matching Render Target, the same size as the one the Sprite was drawn to, useful for double-buffer style effects such as blurs.
The Render Target swap frame.
Returns a new instance of the post pipeline based on the given name, or class.
If no instance, or matching name, exists in this manager, it returns undefined
.
name | type | arguments | description |
---|---|---|---|
pipeline | string | function | Phaser.Renderer.WebGL.Pipelines.PostFXPipeline |
Either the string-based name of the pipeline to get, or a pipeline instance, or class to look-up. |
|
gameObject | Phaser.GameObjects.GameObject | <optional> |
If this post pipeline is being installed into a Game Object or Camera, this is a reference to it. |
config | object | <optional> |
Optional pipeline data object that is set in to the |
The pipeline instance, or undefined
if not found.
Gets a Render Target the right size to render the Sprite on.
If the Sprite exceeds the size of the renderer, the Render Target will only ever be the maximum size of the renderer.
name | type | description |
---|---|---|
size | number |
The maximum dimension required. |
A Render Target large enough to fit the sprite.
Gets a matching Render Target, the same size as the one the Sprite was drawn to, useful for double-buffer style effects such as blurs.
The Render Target swap frame.
Checks if a pipeline is present in this Pipeline Manager.
name | type | description |
---|---|---|
pipeline | string | Phaser.Renderer.WebGL.WebGLPipeline |
Either the string-based name of the pipeline to get, or a pipeline instance to look-up. |
true
if the given pipeline is loaded, otherwise false
.
Checks to see if the given pipeline is already the active pipeline, both within this Pipeline Manager and also has the same shader set in the Renderer.
name | type | arguments | description |
---|---|---|---|
pipeline | Phaser.Renderer.WebGL.WebGLPipeline |
The pipeline instance to be checked. |
|
currentShader | Phaser.Renderer.WebGL.WebGLShader | <optional> |
The shader to set as being current. |
true
if the given pipeline is already the current pipeline, otherwise false
.
This method is called by the WebGLPipeline.batchQuad
method, right after a quad
belonging to a Game Object has been added to the batch.
It is also called directly bu custom Game Objects, such as Nine Slice or Mesh, from their render methods.
It causes a batch flush, then calls the postBatch
method on the Post FX Pipelines
belonging to the Game Object.
It should be preceeded by a call to preBatch
to start the process.
name | type | description |
---|---|---|
gameObject | Phaser.GameObjects.GameObject |
The Game Object that was just added to the batch. |
Called at the end of the WebGLRenderer.postRenderCamera
method.
If the Camera has post pipelines set, it will flush the batch and then call the
postBatch
method on the post-fx pipelines belonging to the Camera.
name | type | description |
---|---|---|
camera | Phaser.Cameras.Scene2D.Camera |
The Camera that was just rendered. |
This method is called by the WebGLPipeline.batchQuad
method, right before a quad
belonging to a Game Object is about to be added to the batch.
It is also called directly bu custom Game Objects, such as Nine Slice or Mesh, from their render methods.
It causes a batch flush, then calls the preBatch
method on the Post FX Pipelines
belonging to the Game Object.
It should be followed by a call to postBatch
to complete the process.
name | type | description |
---|---|---|
gameObject | Phaser.GameObjects.GameObject |
The Game Object about to be batched. |
Called at the start of the WebGLRenderer.preRenderCamera
method.
If the Camera has post pipelines set, it will flush the batch and then call the
preBatch
method on the post-fx pipelines belonging to the Camera.
name | type | description |
---|---|---|
camera | Phaser.Cameras.Scene2D.Camera |
The Camera about to be rendered. |
Use this to reset the gl context to the state that Phaser requires to continue rendering.
Calling this will:
DEPTH_TEST
, CULL_FACE
and STENCIL_TEST
.You should call this if you have previously called clear
, and then wish to return
rendering control to Phaser again.
name | type | arguments | description |
---|---|---|---|
pipeline | Phaser.Renderer.WebGL.WebGLPipeline | <optional> |
The pipeline instance to be rebound. If not given, the previous pipeline will be bound. |
Removes a pipeline instance based on the given name.
If no pipeline matches the name, this method does nothing.
Note that the pipeline will not be flushed or destroyed, it's simply removed from this manager.
name | type | arguments | Default | description |
---|---|---|---|---|
name | string |
The name of the pipeline to be removed. |
||
removeClass | boolean | <optional> | true |
Remove the pipeline class as well as the instance? |
removePostPipelineClass | boolean | <optional> | true |
Remove the post pipeline class as well as the instance? |
Sets the current pipeline to be used by the WebGLRenderer
.
This method accepts a pipeline instance as its parameter, not the name.
If the pipeline isn't already the current one it will call WebGLPipeline.bind
and then onBind
.
You cannot set Post FX Pipelines using this method. To use a Post FX Pipeline, you should apply it to either a Camera, Container or other supporting Game Object.
name | type | arguments | description |
---|---|---|---|
pipeline | Phaser.Renderer.WebGL.WebGLPipeline |
The pipeline instance to be set as current. |
|
gameObject | Phaser.GameObjects.GameObject | <optional> |
The Game Object that invoked this pipeline, if any. |
currentShader | Phaser.Renderer.WebGL.WebGLShader | <optional> |
The shader to set as being current. |
The pipeline that was set, or undefined if it couldn't be set.
Sets the default pipeline being used by Game Objects.
If no instance, or matching name, exists in this manager, it returns undefined
.
You can use this to override the default pipeline, for example by forcing the Mobile or Multi Tint Pipelines, which is especially useful for development testing.
Make sure you call this method before creating any Game Objects, as it will only impact Game Objects created after you call it.
name | type | description |
---|---|---|
pipeline | string | Phaser.Renderer.WebGL.WebGLPipeline |
Either the string-based name of the pipeline to get, or a pipeline instance to look-up. |
The pipeline instance that was set as default, or undefined
if not found.
Sets the FX Pipeline to be the currently bound pipeline.
The FX Pipeline instance.
Sets the Multi Pipeline to be the currently bound pipeline.
This is the default Phaser 3 rendering pipeline.
The Multi Pipeline instance.
Sets the Utility Pipeline to be the currently bound pipeline.
name | type | arguments | description |
---|---|---|---|
currentShader | Phaser.Renderer.WebGL.WebGLShader | <optional> |
The shader to set as being current. |
The Utility Pipeline instance.