PIXI.Filter
class Filter extends PIXI.Shader
A filter is a special shader that applies post-processing effects to an input texture and writes into an output render-target.
Example of the BlurFilter.
Usage
Filters can be applied to any DisplayObject or Container.
PixiJS' FilterSystem
renders the container into temporary Framebuffer,
then filter renders it to the screen.
Multiple filters can be added to the filters
array property and stacked on each other.
const filter = new PIXI.Filter(myShaderVert, myShaderFrag, { myUniform: 0.5 });
const container = new PIXI.Container();
container.filters = [filter];
Previous Version Differences
In PixiJS v3, a filter was always applied to whole screen.
In PixiJS v4, a filter can be applied only part of the screen. Developers had to create a set of uniforms to deal with coordinates.
In PixiJS v5 combines both approaches. Developers can use normal coordinates of v3 and then allow filter to use partial Framebuffers, bringing those extra uniforms into account.
Also be aware that we have changed default vertex shader, please consult Wiki.
Frames
The following table summarizes the coordinate spaces used in the filtering pipeline:
Coordinate Space | Description |
---|---|
Texture Coordinates | The texture (or UV) coordinates in the input base-texture's space. These are normalized into the (0,1) range along both axes. |
World Space | A point in the same space as the world bounds of any display-object (i.e. in the scene graph's space). |
Physical Pixels | This is base-texture's space with the origin on the top-left. You can calculate these by multiplying the texture coordinates by the dimensions of the texture. |
Built-in Uniforms
PixiJS viewport uses screen (CSS) coordinates, (0, 0, renderer.screen.width, renderer.screen.height)
,
and projectionMatrix
uniform maps it to the gl viewport.
uSampler
The most important uniform is the input texture that container was rendered into. Important note: as with all Framebuffers in PixiJS, both input and output are premultiplied by alpha.
By default, input normalized coordinates are passed to fragment shader with vTextureCoord
.
Use it to sample the input.
const fragment = `
varying vec2 vTextureCoord;
uniform sampler2D uSampler;
void main(void)
{
gl_FragColor = texture2D(uSampler, vTextureCoord);
}
`;
const myFilter = new PIXI.Filter(null, fragment);
This filter is just one uniform less than AlphaFilter.
outputFrame
The outputFrame
holds the rectangle where filter is applied in screen (CSS) coordinates.
It's the same as renderer.screen
for a fullscreen filter.
Only a part of outputFrame.zw
size of temporary Framebuffer is used,
(0, 0, outputFrame.width, outputFrame.height)
,
Filters uses this quad to normalized (0-1) space, its passed into aVertexPosition
attribute.
To calculate vertex position in screen space using normalized (0-1) space:
vec4 filterVertexPosition( void )
{
vec2 position = aVertexPosition * max(outputFrame.zw, vec2(0.)) + outputFrame.xy;
return vec4((projectionMatrix * vec3(position, 1.0)).xy, 0.0, 1.0);
}
inputSize
Temporary framebuffer is different, it can be either the size of screen, either power-of-two.
The inputSize.xy
are size of temporary framebuffer that holds input.
The inputSize.zw
is inverted, it's a shortcut to evade division inside the shader.
Set inputSize.xy = outputFrame.zw
for a fullscreen filter.
To calculate input normalized coordinate, you have to map it to filter normalized space.
Multiply by outputFrame.zw
to get input coordinate.
Divide by inputSize.xy
to get input normalized coordinate.
vec2 filterTextureCoord( void )
{
return aVertexPosition * (outputFrame.zw * inputSize.zw); // same as /inputSize.xy
}
resolution
The resolution
is the ratio of screen (CSS) pixels to real pixels.
inputPixel
inputPixel.xy
is the size of framebuffer in real pixels, same as inputSize.xy * resolution
inputPixel.zw
is inverted inputPixel.xy
.
It's handy for filters that use neighbour pixels, like FXAAFilter.
inputClamp
If you try to get info from outside of used part of Framebuffer - you'll get undefined behaviour. For displacements, coordinates has to be clamped.
The inputClamp.xy
is left-top pixel center, you may ignore it, because we use left-top part of Framebuffer
inputClamp.zw
is bottom-right pixel center.
vec4 color = texture2D(uSampler, clamp(modifiedTextureCoord, inputClamp.xy, inputClamp.zw))
OR
vec4 color = texture2D(uSampler, min(modifigedTextureCoord, inputClamp.zw))
Additional Information
Complete documentation on Filter usage is located in the Wiki.
Since PixiJS only had a handful of built-in filters, additional filters can be downloaded here from the PixiJS Filters repository.
Constructor
new PIXI.Filter(vertexSrc: string, fragmentSrc: string, uniforms: Dict) → {}
Name | Type | Attributes | Description |
---|---|---|---|
vertexSrc | string |
<optional> |
The source of the vertex shader. |
fragmentSrc | string |
<optional> |
The source of the fragment shader. |
uniforms | Dict<any> |
<optional> |
Custom uniforms to use to augment the built-in ones. |
Summary
Properties from Filter
string |
|
string |
|
Dict<string> |
Used for caching shader IDs. |
boolean |
|
PIXI.BLEND_MODES |
|
boolean |
If enabled is true the filter is applied, if false it will not. |
boolean |
|
PIXI.MSAA_QUALITY |
The samples of the filter. |
number |
|
number |
|
PIXI.State |
The WebGL state the filter requires to render. |
Methods from Filter
void |
|
Properties inherited from Shader
PIXI.Program |
Program that the shader uses. |
Dict<any> |
|
Public Properties
static defaultFragmentSrc: string
The default fragment shader source
autoFit: boolean = true
If enabled, PixiJS will fit the filter area into boundaries for better performance. Switch it off if it does not work for specific shader.
blendMode: PIXI.BLEND_MODES = PIXI.BLEND_MODES.NORMAL
Sets the blend mode of the filter.
enabled: boolean
If enabled is true the filter is applied, if false it will not.
legacy: boolean
Legacy filters use position and uvs from attributes (set by filter system)
padding: number
The padding of the filter. Some filters require extra space to breath such as a blur. Increasing this will add extra width and height to the bounds of the object that the filter is applied to.
resolution: number
The resolution of the filter. Setting this to be lower will lower the quality but increase the performance of the filter.
Public Methods
apply(filterManager: PIXI.FilterSystem, input: PIXI.RenderTexture, output: PIXI.RenderTexture, clearMode: PIXI.CLEAR_MODES, _currentState: object) → {void}
Applies the filter
Name | Type | Attributes | Description |
---|---|---|---|
filterManager | PIXI.FilterSystem |
The renderer to retrieve the filter from |
|
input | PIXI.RenderTexture |
The input render target. |
|
output | PIXI.RenderTexture |
The target to output to. |
|
clearMode | PIXI.CLEAR_MODES |
<optional> |
Should the output be cleared before rendering to it. |
_currentState | object |
<optional> |
It's current state of filter. There are some useful properties in the currentState : target, filters, sourceFrame, destinationFrame, renderTarget, resolution |
Type | Description |
---|---|
void |