1 | import { MSAA_QUALITY } from '@pixi/constants';
|
2 | import { Shader } from '../shader/Shader';
|
3 | import { State } from '../state/State';
|
4 | import type { BLEND_MODES, CLEAR_MODES } from '@pixi/constants';
|
5 | import type { Dict } from '@pixi/utils';
|
6 | import type { RenderTexture } from '../renderTexture/RenderTexture';
|
7 | import type { FilterState } from './FilterState';
|
8 | import type { FilterSystem } from './FilterSystem';
|
9 | /**
|
10 | * A filter is a special shader that applies post-processing effects to an input texture and writes into an output
|
11 | * render-target.
|
12 | *
|
13 | * {@link https://pixijs.io/examples/#/filters-basic/blur.js Example} of the
|
14 | * {@link PIXI.BlurFilter BlurFilter}.
|
15 | *
|
16 | * ### Usage
|
17 | * Filters can be applied to any DisplayObject or Container.
|
18 | * PixiJS' `FilterSystem` renders the container into temporary Framebuffer,
|
19 | * then filter renders it to the screen.
|
20 | * Multiple filters can be added to the `filters` array property and stacked on each other.
|
21 | *
|
22 | * ```js
|
23 | * import { Container, Filter } from 'pixi.js';
|
24 | * const filter = new Filter(myShaderVert, myShaderFrag, { myUniform: 0.5 });
|
25 | * const container = new Container();
|
26 | * container.filters = [filter];
|
27 | * ```
|
28 | *
|
29 | * ### Previous Version Differences
|
30 | *
|
31 | * In PixiJS **v3**, a filter was always applied to _whole screen_.
|
32 | *
|
33 | * In PixiJS **v4**, a filter can be applied _only part of the screen_.
|
34 | * Developers had to create a set of uniforms to deal with coordinates.
|
35 | *
|
36 | * In PixiJS **v5** combines _both approaches_.
|
37 | * Developers can use normal coordinates of v3 and then allow filter to use partial Framebuffers,
|
38 | * bringing those extra uniforms into account.
|
39 | *
|
40 | * Also be aware that we have changed default vertex shader, please consult
|
41 | * {@link https://github.com/pixijs/pixijs/wiki/v5-Creating-filters Wiki}.
|
42 | *
|
43 | * ### Frames
|
44 | *
|
45 | * The following table summarizes the coordinate spaces used in the filtering pipeline:
|
46 | *
|
47 | * <table>
|
48 | * <thead>
|
49 | * <tr>
|
50 | * <th>Coordinate Space</th>
|
51 | * <th>Description</th>
|
52 | * </tr>
|
53 | * </thead>
|
54 | * <tbody>
|
55 | * <tr>
|
56 | * <td>Texture Coordinates</td>
|
57 | * <td>
|
58 | * The texture (or UV) coordinates in the input base-texture's space. These are normalized into the (0,1) range along
|
59 | * both axes.
|
60 | * </td>
|
61 | * </tr>
|
62 | * <tr>
|
63 | * <td>World Space</td>
|
64 | * <td>
|
65 | * A point in the same space as the world bounds of any display-object (i.e. in the scene graph's space).
|
66 | * </td>
|
67 | * </tr>
|
68 | * <tr>
|
69 | * <td>Physical Pixels</td>
|
70 | * <td>
|
71 | * This is base-texture's space with the origin on the top-left. You can calculate these by multiplying the texture
|
72 | * coordinates by the dimensions of the texture.
|
73 | * </td>
|
74 | * </tr>
|
75 | * </tbody>
|
76 | * </table>
|
77 | *
|
78 | * ### Built-in Uniforms
|
79 | *
|
80 | * PixiJS viewport uses screen (CSS) coordinates, `(0, 0, renderer.screen.width, renderer.screen.height)`,
|
81 | * and `projectionMatrix` uniform maps it to the gl viewport.
|
82 | *
|
83 | * **uSampler**
|
84 | *
|
85 | * The most important uniform is the input texture that container was rendered into.
|
86 | * _Important note: as with all Framebuffers in PixiJS, both input and output are
|
87 | * premultiplied by alpha._
|
88 | *
|
89 | * By default, input normalized coordinates are passed to fragment shader with `vTextureCoord`.
|
90 | * Use it to sample the input.
|
91 | *
|
92 | * ```js
|
93 | * import { Filter } from 'pixi.js';
|
94 | * const fragment = `
|
95 | * varying vec2 vTextureCoord;
|
96 | * uniform sampler2D uSampler;
|
97 | * void main(void)
|
98 | * {
|
99 | * gl_FragColor = texture2D(uSampler, vTextureCoord);
|
100 | * }
|
101 | * `;
|
102 | *
|
103 | * const myFilter = new Filter(null, fragment);
|
104 | * ```
|
105 | *
|
106 | * This filter is just one uniform less than {@link PIXI.AlphaFilter AlphaFilter}.
|
107 | *
|
108 | * **outputFrame**
|
109 | *
|
110 | * The `outputFrame` holds the rectangle where filter is applied in screen (CSS) coordinates.
|
111 | * It's the same as `renderer.screen` for a fullscreen filter.
|
112 | * Only a part of `outputFrame.zw` size of temporary Framebuffer is used,
|
113 | * `(0, 0, outputFrame.width, outputFrame.height)`,
|
114 | *
|
115 | * Filters uses this quad to normalized (0-1) space, its passed into `aVertexPosition` attribute.
|
116 | * To calculate vertex position in screen space using normalized (0-1) space:
|
117 | *
|
118 | * ```glsl
|
119 | * vec4 filterVertexPosition( void )
|
120 | * {
|
121 | * vec2 position = aVertexPosition * max(outputFrame.zw, vec2(0.)) + outputFrame.xy;
|
122 | * return vec4((projectionMatrix * vec3(position, 1.0)).xy, 0.0, 1.0);
|
123 | * }
|
124 | * ```
|
125 | *
|
126 | * **inputSize**
|
127 | *
|
128 | * Temporary framebuffer is different, it can be either the size of screen, either power-of-two.
|
129 | * The `inputSize.xy` are size of temporary framebuffer that holds input.
|
130 | * The `inputSize.zw` is inverted, it's a shortcut to evade division inside the shader.
|
131 | *
|
132 | * Set `inputSize.xy = outputFrame.zw` for a fullscreen filter.
|
133 | *
|
134 | * To calculate input normalized coordinate, you have to map it to filter normalized space.
|
135 | * Multiply by `outputFrame.zw` to get input coordinate.
|
136 | * Divide by `inputSize.xy` to get input normalized coordinate.
|
137 | *
|
138 | * ```glsl
|
139 | * vec2 filterTextureCoord( void )
|
140 | * {
|
141 | * return aVertexPosition * (outputFrame.zw * inputSize.zw); // same as /inputSize.xy
|
142 | * }
|
143 | * ```
|
144 | *
|
145 | * **resolution**
|
146 | *
|
147 | * The `resolution` is the ratio of screen (CSS) pixels to real pixels.
|
148 | *
|
149 | * **inputPixel**
|
150 | *
|
151 | * `inputPixel.xy` is the size of framebuffer in real pixels, same as `inputSize.xy * resolution`
|
152 | * `inputPixel.zw` is inverted `inputPixel.xy`.
|
153 | *
|
154 | * It's handy for filters that use neighbour pixels, like {@link PIXI.FXAAFilter FXAAFilter}.
|
155 | *
|
156 | * **inputClamp**
|
157 | *
|
158 | * If you try to get info from outside of used part of Framebuffer - you'll get undefined behaviour.
|
159 | * For displacements, coordinates has to be clamped.
|
160 | *
|
161 | * The `inputClamp.xy` is left-top pixel center, you may ignore it, because we use left-top part of Framebuffer
|
162 | * `inputClamp.zw` is bottom-right pixel center.
|
163 | *
|
164 | * ```glsl
|
165 | * vec4 color = texture2D(uSampler, clamp(modifiedTextureCoord, inputClamp.xy, inputClamp.zw));
|
166 | * ```
|
167 | *
|
168 | * Or:
|
169 | *
|
170 | * ```glsl
|
171 | * vec4 color = texture2D(uSampler, min(modifigedTextureCoord, inputClamp.zw));
|
172 | * ```
|
173 | *
|
174 | * ### Additional Information
|
175 | *
|
176 | * Complete documentation on Filter usage is located in the
|
177 | * {@link https://github.com/pixijs/pixijs/wiki/v5-Creating-filters Wiki}.
|
178 | *
|
179 | * Since PixiJS only had a handful of built-in filters, additional filters can be downloaded
|
180 | * {@link https://github.com/pixijs/pixi-filters here} from the PixiJS Filters repository.
|
181 | * @memberof PIXI
|
182 | */
|
183 | export declare class Filter extends Shader {
|
184 | /**
|
185 | * Default filter resolution for any filter.
|
186 | * @static
|
187 | */
|
188 | static defaultResolution: number | null;
|
189 | /**
|
190 | * Default filter samples for any filter.
|
191 | * @static
|
192 | * @type {PIXI.MSAA_QUALITY|null}
|
193 | * @default PIXI.MSAA_QUALITY.NONE
|
194 | */
|
195 | static defaultMultisample: MSAA_QUALITY | null;
|
196 | /**
|
197 | * The padding of the filter. Some filters require extra space to breath such as a blur.
|
198 | * Increasing this will add extra width and height to the bounds of the object that the
|
199 | * filter is applied to.
|
200 | */
|
201 | padding: number;
|
202 | /**
|
203 | * The samples override of the filter instance.
|
204 | * If set to `null`, the sample count of the current render target is used.
|
205 | * @default PIXI.Filter.defaultMultisample
|
206 | */
|
207 | multisample: MSAA_QUALITY | null;
|
208 | /** If enabled is true the filter is applied, if false it will not. */
|
209 | enabled: boolean;
|
210 | /**
|
211 | * If enabled, PixiJS will fit the filter area into boundaries for better performance.
|
212 | * Switch it off if it does not work for specific shader.
|
213 | * @default true
|
214 | */
|
215 | autoFit: boolean;
|
216 | /**
|
217 | * Legacy filters use position and uvs from attributes (set by filter system)
|
218 | * @readonly
|
219 | */
|
220 | legacy: boolean;
|
221 | /** The WebGL state the filter requires to render. */
|
222 | state: State;
|
223 | protected _resolution: number | null;
|
224 | /**
|
225 | * @param vertexSrc - The source of the vertex shader.
|
226 | * @param fragmentSrc - The source of the fragment shader.
|
227 | * @param uniforms - Custom uniforms to use to augment the built-in ones.
|
228 | */
|
229 | constructor(vertexSrc?: string, fragmentSrc?: string, uniforms?: Dict<any>);
|
230 | /**
|
231 | * Applies the filter
|
232 | * @param {PIXI.FilterSystem} filterManager - The renderer to retrieve the filter from
|
233 | * {PIXI.RenderTexture} input - The input render target.
|
234 | * {PIXI.RenderTexture} output - The target to output to.
|
235 | * {PIXI.CLEAR_MODES} [clearMode] - Should the output be cleared before rendering to it.
|
236 | * @param {object} [_currentState] - It's current state of filter.
|
237 | * There are some useful properties in the currentState :
|
238 | * target, filters, sourceFrame, destinationFrame, renderTarget, resolution
|
239 | */
|
240 | apply(filterManager: FilterSystem, input: RenderTexture, output: RenderTexture, clearMode?: CLEAR_MODES, _currentState?: FilterState): void;
|
241 | /**
|
242 | * Sets the blend mode of the filter.
|
243 | * @default PIXI.BLEND_MODES.NORMAL
|
244 | */
|
245 | get blendMode(): BLEND_MODES;
|
246 | set blendMode(value: BLEND_MODES);
|
247 | /**
|
248 | * The resolution of the filter. Setting this to be lower will lower the quality but
|
249 | * increase the performance of the filter.
|
250 | * If set to `null` or `0`, the resolution of the current render target is used.
|
251 | * @default PIXI.Filter.defaultResolution
|
252 | */
|
253 | get resolution(): number | null;
|
254 | set resolution(value: number | null);
|
255 | /**
|
256 | * The default vertex shader source
|
257 | * @readonly
|
258 | */
|
259 | static get defaultVertexSrc(): string;
|
260 | /**
|
261 | * The default fragment shader source
|
262 | * @readonly
|
263 | */
|
264 | static get defaultFragmentSrc(): string;
|
265 | /** Used for caching shader IDs. */
|
266 | static SOURCE_KEY_MAP: Dict<string>;
|
267 | }
|