Provide GPU powered texture effects.
Summary
Syntax
var effects = TextureEffects.create({
graphicsDevice : gd,
mathDevice : md
});
Summary
Apply a distortion effect based on a given distortion texture.
Syntax
var success = effects.applyDistort({
source : sourceTexture,
distortion : distortionTexture,
destination : renderTarget,
strength : 10,
transform : [ x1, x2, y1, y2, t1, t2]
});
The Texture object defining the distortion to be applied.
The red channel of the texture is used to define the local x-coordinate distortion. A post-normalized value of 0 specifying full distortion to the left, and 1 full distortion to the right.
The green channel is used for y-distortion. whilst blue and any alpha channel present are ignored.
The maximum displacement in pixels that will be applied to the source texture.
The default value if none is specified is 10.
A 2x3 transformation matrix used to transform texture coordinates before a look-up is performed into the distortion texture. As per usual, this transformation matrix is stored in column major order
transform = [x1, x2, y1, y2, t1, t2]
// equivalent to matrix:
// [ x1 y1 t1 ]
// [ x2 y2 t2 ]
This can be used to scale/shear/rotate/translate the texture look-ups with the inverse transform being applied to the displacement vectors obtained from the distortion texture.
This transformation occurs in the normalized coordinate space of the textures. For example to rotate the distortion effect clockwise about the center of the source texture we could use a transformation matrix
var cos = Math.cos(angle);
var sin = Math.sin(angle);
var transform = [cos, -sin, sin, cos, (1 - cos + sin) / 2, (1 - cos - sin) / 2];
Since this is a transformation applied to the texture look-ups, should you wish to scale the distortion effect by 2 for instance, you would need to scale the texture look-ups by 0.5.
This call will fail with false if the input texture or render targets are not well defined, or if the source of distortion texture are equal to the destination’s colorTexture0, or if the destination does not have a colorTexture0.
Summary
Apply a high quality Gaussian blur effect.
Syntax
var success = effects.applyGaussianBlur({
source : sourceTexture,
blurTarget : blurRenderTarget,
destination : renderTarget,
blurRadius : 5,
});
The RenderTarget object to which the intermediate result of the blur will be rendered. The rendering will be made to the render target’s colorTexture0 texture object.
This render target’s texture should have the same dimensions as the destination for best results.
Specify the blurring radius in pixels for the effect.
Default value is 5.
This call will fail with false if the input texture or render targets are not well defined, or if the source texture is equal to the blurTarget colorTexture0, or if the blurTarget is equal to the destination, or if the render targets do not have a colorTexture0.
Note that destination.colorTexture0 is permitted to be equal to source so we can blur a render target to itself using the intermediate blurring render target
effects.applyGaussianBlur({
source : destination.colorTexture0,
blurTarget : intermediateTarget,
destination : destination
});
This effect uses 18 texture look-ups in each blurring pass performing a horizontal blur to the intermediate target, and then a vertical blur to the destination.
Summary
Apply a bloom effect.
Syntax
var success = effects.applyBloom({
source : sourceTexture,
blurTarget1 : blurRenderTarget1,
blurTarget2 : blurRenderTarget2,
destination : renderTarget,
blurRadius : 20,
bloomThreshold : 0.65,
thresholdCutoff : 3,
bloomIntensity : 1.2,
bloomSaturation : 1.2,
originalIntensity : 1.0,
originalSaturation : 1.0
});
The first RenderTarget object to which the intermediate result of the bloom will be rendered. The rendering will be made to the render target’s colorTexture0 texture object.
This render target need not be the same size as the source, smaller dimensions give comparable results with less cost.
The second RenderTarget object to which the intermediate result of the bloom will be rendered. The rendering will be made to the render target’s colorTexture0 texture object.
This render target should be the same size as blurTarget1.
Specifies the blurring radius in pixels for the effect’s blur passes.
Default value is 20.
Specifies a luminance threshold to discard regions of the source not bright enough to be bloomed.
This value should be given in the range [0,1].
Default value is 0.65.
Specifies the cutoff speed for how quickly the bloom effect dissipates below the threshold.
This can take any value though the range of values that give noticeable differences is roughly [-3,6] with -3 being no noticeable cutoff, and 6 being no noticeable difference from an instant cutoff.
Specifies a scaling factor to multiply the bloom effect with in merging step.
This value should be positive.
Default value is 1.2.
Specifies a scaling factor for the saturation of the bloom effect in merging step.
Default value is 1.2.
Specifies a scaling factor to multiply the source with in merging step.
This value should be positive.
Default value is 1.0.
Specifies a scaling factor for the saturation of the source in merging step.
Default value is 1.0.
This call will fail with false if the input texture or render targets are not well defined, or if the source texture is equal to blurTarget1’s colorTexture0, or if blurTarget1 is equal to blurTarget2 or blurTarget1 is equal to destination or if any render target does not have a colorTexture0.
This effect first performs a threshold copy into blurTarget1, and then invokes the Gaussian blur rendering first into blurTarget2, and then back to blurTarget1. Finally the source, and blurTarget1 are merged together into the destination.
Summary
Apply a color matrix effect, transforming RGB color values in source texture by given matrix.
Syntax
var success = effects.applyColorMatrix({
source : sourceTexture,
destination : renderTarget,
colorMatrix : [ r1, r2, r3, g1, g2, g3, b1, b2, b3, addR, addG, addB ]
});
The 3x4 matrix used to transform RGB color values. This matrix is given as usual in column major order and is compatible with Matrix43 objects and may be composed by multiplication.
// [outR] ( r1 g1 b1 addR )[inR]
// [outG] = ( r2 g2 b2 addG )[inG]
// [outB] ( r3 g3 b3 addB )[inB]
// [outA] ( 0 0 0 1 )[inA]
This call will fail with false if the source, or destination parameters are not well defined, or the source texture is equal to the destination colorTexture0, or the destination does not have a colorTexture0.
Summary
Create color matrix to transform colors into gray-scale.
Syntax
var colorMatrix = effects.grayScaleMatrix();
// or
effects.grayScaleMatrix(colorMatrix);
This transformation maps colors to their luminance value.
Summary
Create color matrix to transform colors into sepia.
Syntax
var colorMatrix = effects.sepiaMatrix();
// or
effects.sepiaMatrix(colorMatrix);
Summary
Create color matrix to transform colors into their negative.
Syntax
var colorMatrix = effects.negativeMatrix();
// or
effects.negativeMatrix(colorMatrix);
Summary
Create color matrix to transform colors by scaling their saturation.
Syntax
var colorMatrix = effects.saturationMatrix(saturationScale);
// or
effects.saturationMatrix(saturationScale, colorMatrix);
The saturation scaling to compute color matrix.
A scaling of 1 will create an identity mapping.
A scaling of 0 will create a grayScaleMatrix
A scaling of -1 will map colors to their complements.
This transformation preserves color luminance. When scaling is positive the color hue will also be preserved, whilst for negative values the color hue will be rotated 180 degrees.
Summary
Create a color matrix to transform colors by rotation of their hue.
Syntax
var colorMatrix = effects.hueMatrix(hueRotation);
// or
effects.hueMatrix(hueRotation, colorMatrix);
The rotation in clockwise radians to apply to color hues.
A normalized rotation of 0 will create an identity mapping.
A normalized rotation of Math.PI / 2 will map colors to their complements.
This transformation preserves color luminance and saturation.
Summary
Create a color matrix to transform colors by offsetting their brightness.
Syntax
var colorMatrix = effects.brightnessMatrix(brightnessOffset);
// or
effects.brightnessMatrix(brightnessOffset, colorMatrix);
The brightness offset as a normalized color value.
An offset of -1 will map colors to black.
An offset of 0 will create an identity mapping.
An offset of 1 will map colors to white.
This transformation preserves color hue.
Summary
Create a color matrix to transform colors by offsetting their red, green or blue values.
Syntax
var colorMatrix = effects.additiveMatrix(colorOffset);
// or
effects.additiveMatrix(colorOffset, colorMatrix);
A JavaScript array of length 3. With red, green and blue elements as offsets:
An offset of -1 will completely remove the color.
An offset of 0 will create an identity mapping.
An offset of 1 will map the color to its full value. For example, a colorOffset value of [-1, 1, -1] will result in a matrix which always outputs a green color [0, 1, 0] (after clamping to the range [0, 1]).
Summary
Create a color matrix to transform colors by scaling their contrast.
Syntax
var colorMatrix = effects.contrastMatrix(contrastScale);
// or
effects.contrastMatrix(contrastScale, colorMatrix);
The contrast scaling to create color matrix with.
A scaling of 0 will map colors to gray.
A scaling of 1 will create an identity mapping.
This transformation preserves color hue.