ColorMatrixColorFilter.java revision 8a6ad4a89d1b9ed61d3ec6f5bc12d479bc8d9f3b 
1/*
2 * Copyright (C) 2007 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.graphics;
18
19import android.annotation.NonNull;
20import android.annotation.Nullable;
21
22/**
23 * A color filter that transforms colors through a 4x5 color matrix. This filter
24 * can be used to change the saturation of pixels, convert from YUV to RGB, etc.
25 *
26 * @see ColorMatrix
27 */
28public class ColorMatrixColorFilter extends ColorFilter {
29    private final ColorMatrix mMatrix = new ColorMatrix();
30
31    /**
32     * Create a color filter that transforms colors through a 4x5 color matrix.
33     *
34     * @param matrix 4x5 matrix used to transform colors. It is copied into
35     *               the filter, so changes made to the matrix after the filter
36     *               is constructed will not be reflected in the filter.
37     */
38    public ColorMatrixColorFilter(@NonNull ColorMatrix matrix) {
39        mMatrix.set(matrix);
40    }
41
42    /**
43     * Create a color filter that transforms colors through a 4x5 color matrix.
44     *
45     * @param array Array of floats used to transform colors, treated as a 4x5
46     *              matrix. The first 20 entries of the array are copied into
47     *              the filter. See ColorMatrix.
48     */
49    public ColorMatrixColorFilter(@NonNull float[] array) {
50        if (array.length < 20) {
51            throw new ArrayIndexOutOfBoundsException();
52        }
53        mMatrix.set(array);
54    }
55
56    /**
57     * Copies the ColorMatrix from the filter into the passed ColorMatrix.
58     *
59     * @param colorMatrix Set to the current value of the filter's ColorMatrix.
60     */
61    public void getColorMatrix(ColorMatrix colorMatrix) {
62        colorMatrix.set(mMatrix);
63    }
64
65    /**
66     * Copies the provided color matrix to be used by this filter.
67     *
68     * If the specified color matrix is null, this filter's color matrix will be reset to the
69     * identity matrix.
70     *
71     * @param matrix A {@link ColorMatrix} or null
72     *
73     * @see #getColorMatrix(ColorMatrix)
74     * @see #setColorMatrixArray(float[])
75     * @see ColorMatrix#reset()
76     *
77     * @hide
78     */
79    public void setColorMatrix(@Nullable ColorMatrix matrix) {
80        discardNativeInstance();
81        if (matrix == null) {
82            mMatrix.reset();
83        } else {
84            mMatrix.set(matrix);
85        }
86    }
87
88    /**
89     * Copies the provided color matrix to be used by this filter.
90     *
91     * If the specified color matrix is null, this filter's color matrix will be reset to the
92     * identity matrix.
93     *
94     * @param array Array of floats used to transform colors, treated as a 4x5
95     *              matrix. The first 20 entries of the array are copied into
96     *              the filter. See {@link ColorMatrix}.
97     *
98     * @see #getColorMatrix(ColorMatrix)
99     * @see #setColorMatrix(ColorMatrix)
100     * @see ColorMatrix#reset()
101     *
102     * @throws ArrayIndexOutOfBoundsException if the specified array's
103     *         length is < 20
104     *
105     * @hide
106     */
107    public void setColorMatrixArray(@Nullable float[] array) {
108        // called '...Array' so that passing null isn't ambiguous
109        discardNativeInstance();
110        if (array == null) {
111            mMatrix.reset();
112        } else {
113            if (array.length < 20) {
114                throw new ArrayIndexOutOfBoundsException();
115            }
116            mMatrix.set(array);
117        }
118    }
119
120    @Override
121    long createNativeInstance() {
122        return nativeColorMatrixFilter(mMatrix.getArray());
123    }
124
125    private static native long nativeColorMatrixFilter(float[] array);
126}
127