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