final class ColorMatrixFilter
package openfl.filters
extends BitmapFilter
Available on all platforms
The ColorMatrixFilter class lets you apply a 4 x 5 matrix transformation on the RGBA color and alpha values of every pixel in the input image to produce a result with a new set of RGBA color and alpha values. It allows saturation changes, hue rotation, luminance to alpha, and various other effects. You can apply the filter to any display object (that is, objects that inherit from the DisplayObject class), such as MovieClip, SimpleButton, TextField, and Video objects, as well as to BitmapData objects. Note: For RGBA values, the most significant byte represents the red channel value, followed by green, blue, and then alpha.
To create a new color matrix filter, use the syntax new
ColorMatrixFilter(). The use of filters depends on the object to which
you apply the filter:
- To apply filters to movie clips, text fields, buttons, and video, use
the
filtersproperty (inherited from DisplayObject). Setting thefiltersproperty of an object does not modify the object, and you can remove the filter by clearing thefiltersproperty. - To apply filters to BitmapData objects, use the
BitmapData.applyFilter()method. CallingapplyFilter()on a BitmapData object takes the source BitmapData object and the filter object and generates a filtered image as a result.
If you apply a filter to a display object, the cacheAsBitmap property of
the display object is set to true. If you remove all filters, the
original value of cacheAsBitmap is restored.
A filter is not applied if the resulting image exceeds the maximum dimensions. In AIR 1.5 and Flash Player 10, the maximum is 8,191 pixels in width or height, and the total number of pixels cannot exceed 16,777,215 pixels. (So, if an image is 8,191 pixels wide, it can only be 2,048 pixels high.) In Flash Player 9 and earlier and AIR 1.1 and earlier, the limitation is 2,880 pixels in height and 2,880 pixels in width. For example, if you zoom in on a large movie clip with a filter applied, the filter is turned off if the resulting image reaches the maximum dimensions.
Constructor
new(?matrix:Array<Float>)
Initializes a new ColorMatrixFilter instance with the specified parameters.
Variables
matrix:Array<Float>
An array of 20 items for 4 x 5 color transform. The matrix property
cannot be changed by directly modifying its value (for example,
myFilter.matrix[2] = 1;). Instead, you must get a reference to the
array, make the change to the reference, and reset the value.
The color matrix filter separates each source pixel into its red,
green, blue, and alpha components as srcR, srcG, srcB, srcA. To
calculate the result of each of the four channels, the value of each
pixel in the image is multiplied by the values in the transformation
matrix. An offset, between -255 and 255, can optionally be added to
each result (the fifth item in each row of the matrix). The filter
combines each color component back into a single pixel and writes out
the result. In the following formula, a[0] through a[19] correspond to
entries 0 through 19 in the 20-item array that is passed to the
matrix property:
redResult = (a[0] * srcR) + (a[1] * srcG) + (a[2] * srcB) + (a[3] * srcA) + a[4]
greenResult = (a[5] * srcR) + (a[6] * srcG) + (a[7] * srcB) + (a[8] * srcA) + a[9]
blueResult = (a[10] * srcR) + (a[11] * srcG) + (a[12] * srcB) + (a[13] * srcA) + a[14]
alphaResult = (a[15] * srcR) + (a[16] * srcG) + (a[17] * srcB) + (a[18] * srcA) + a[19]For each color value in the array, a value of 1 is equal to 100% of that channel being sent to the output, preserving the value of the color channel.
The calculations are performed on unmultiplied color values. If the input graphic consists of premultiplied color values, those values are automatically converted into unmultiplied color values for this operation.
Two optimized modes are available:
Alpha only. When you pass to the filter a matrix that adjusts only the alpha component, as shown here, the filter optimizes its performance:
1 0 0 0 0
0 1 0 0 0
0 0 1 0 0
0 0 0 N 0 (where N is between 0.0 and 1.0)Faster version. Available only with SSE/AltiVec accelerator-enabled processors, such as Intel® Pentium® 3 and later and Apple® G4 and later. The accelerator is used when the multiplier terms are in the range -15.99 to 15.99 and the adder terms a[4], a[9], a[14], and a[19] are in the range -8000 to 8000.
Throws:
TypeError | The Array is |
|---|