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 
17 package android.graphics;
18 
19 import android.annotation.NonNull;
20 import android.annotation.Nullable;
21 import android.compat.annotation.UnsupportedAppUsage;
22 
23 /**
24  * A color filter that transforms colors through a 4x5 color matrix. This filter
25  * can be used to change the saturation of pixels, convert from YUV to RGB, etc.
26  *
27  * @see ColorMatrix
28  */
29 public class ColorMatrixColorFilter extends ColorFilter {
30     @UnsupportedAppUsage
31     private final ColorMatrix mMatrix = new ColorMatrix();
32 
33     /**
34      * Create a color filter that transforms colors through a 4x5 color matrix.
35      *
36      * @param matrix 4x5 matrix used to transform colors. It is copied into
37      *               the filter, so changes made to the matrix after the filter
38      *               is constructed will not be reflected in the filter.
39      */
ColorMatrixColorFilter(@onNull ColorMatrix matrix)40     public ColorMatrixColorFilter(@NonNull ColorMatrix matrix) {
41         mMatrix.set(matrix);
42     }
43 
44     /**
45      * Create a color filter that transforms colors through a 4x5 color matrix.
46      *
47      * @param array Array of floats used to transform colors, treated as a 4x5
48      *              matrix. The first 20 entries of the array are copied into
49      *              the filter. See ColorMatrix.
50      */
ColorMatrixColorFilter(@onNull float[] array)51     public ColorMatrixColorFilter(@NonNull float[] array) {
52         if (array.length < 20) {
53             throw new ArrayIndexOutOfBoundsException();
54         }
55         mMatrix.set(array);
56     }
57 
58     /**
59      * Copies the ColorMatrix from the filter into the passed ColorMatrix.
60      *
61      * @param colorMatrix Set to the current value of the filter's ColorMatrix.
62      */
getColorMatrix(ColorMatrix colorMatrix)63     public void getColorMatrix(ColorMatrix colorMatrix) {
64         colorMatrix.set(mMatrix);
65     }
66 
67     /**
68      * Copies the provided color matrix to be used by this filter.
69      *
70      * If the specified color matrix is null, this filter's color matrix will be reset to the
71      * identity matrix.
72      *
73      * @param matrix A {@link ColorMatrix} or null
74      *
75      * @see #getColorMatrix(ColorMatrix)
76      * @see #setColorMatrixArray(float[])
77      * @see ColorMatrix#reset()
78      *
79      * @hide
80      */
81     @UnsupportedAppUsage
setColorMatrix(@ullable ColorMatrix matrix)82     public void setColorMatrix(@Nullable ColorMatrix matrix) {
83         discardNativeInstance();
84         if (matrix == null) {
85             mMatrix.reset();
86         } else {
87             mMatrix.set(matrix);
88         }
89     }
90 
91     /**
92      * Copies the provided color matrix to be used by this filter.
93      *
94      * If the specified color matrix is null, this filter's color matrix will be reset to the
95      * identity matrix.
96      *
97      * @param array Array of floats used to transform colors, treated as a 4x5
98      *              matrix. The first 20 entries of the array are copied into
99      *              the filter. See {@link ColorMatrix}.
100      *
101      * @see #getColorMatrix(ColorMatrix)
102      * @see #setColorMatrix(ColorMatrix)
103      * @see ColorMatrix#reset()
104      *
105      * @throws ArrayIndexOutOfBoundsException if the specified array's
106      *         length is < 20
107      *
108      * @hide
109      */
110     @UnsupportedAppUsage
setColorMatrixArray(@ullable float[] array)111     public void setColorMatrixArray(@Nullable float[] array) {
112         // called '...Array' so that passing null isn't ambiguous
113         discardNativeInstance();
114         if (array == null) {
115             mMatrix.reset();
116         } else {
117             if (array.length < 20) {
118                 throw new ArrayIndexOutOfBoundsException();
119             }
120             mMatrix.set(array);
121         }
122     }
123 
124     @Override
createNativeInstance()125     long createNativeInstance() {
126         return nativeColorMatrixFilter(mMatrix.getArray());
127     }
128 
nativeColorMatrixFilter(float[] array)129     private static native long nativeColorMatrixFilter(float[] array);
130 }
131