PixiJS

Class: Filter

PIXI.Filter

Filter is a special type of WebGL shader that is applied to the screen.

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.

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 Framebuffer space 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 texture coordinate in 0-1 space, you have to map it to Framebuffer normalized space. Multiply by outputFrame.zw to get pixel coordinate in part of Framebuffer. Divide by inputSize.xy to get Framebuffer normalized space (input sampler space)

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(modifigedTextureCoord, 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.

new PIXI.Filter (vertexSrc, fragmentSrc, uniforms)

Filter.js:143
Name Type Description
vertexSrc string optional

The source of the vertex shader.
fragmentSrc string optional

The source of the fragment shader.
uniforms object optional

Custom uniforms to use to augment the built-in ones.

Extends

Members

PIXI.Filter.defaultFragmentSrc string staticconstant

The default fragment shader source

PIXI.Filter.defaultVertexSrc string staticconstant

The default vertex shader source

PIXI.Filter.SOURCE_KEY_MAP object protectedstatic

Used for caching shader IDs

autoFit boolean

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 number

Sets the blendmode of the filter

Default Value:
  • PIXI.BLEND_MODES.NORMAL

enabled boolean

If enabled is true the filter is applied, if false it will not.

legacy boolean readonly

Legacy filters use position and uvs from attributes

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.

state PIXI.State

The WebGL state the filter requires to render

uniforms object readonly inherited

Shader uniform values, shortcut for uniformGroup.uniforms

Methods

apply (filterManager, input, output, clear, currentState)

Filter.js:214

Applies the filter

Name Type Description
filterManager PIXI.systems.FilterSystem

The renderer to retrieve the filter from
input PIXI.RenderTexture

The input render target.
output PIXI.RenderTexture

The target to output to.
clear boolean

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