1 /*
2  * Copyright (C) 2014 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.hardware.camera2.params;
18 
19 import static com.android.internal.util.Preconditions.checkNotNull;
20 
21 import java.util.Arrays;
22 
23 /**
24  * Immutable class to store a 4-element vector of integers corresponding to a 2x2 pattern
25  * of color channel offsets used for the black level offsets of each color channel.
26  *
27  * For a camera device with
28  * {@link android.hardware.camera2.CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_MONOCHROME
29  * MONOCHROME} capability, all 4 elements of the pattern will have the same value.
30  */
31 public final class BlackLevelPattern {
32 
33     /**
34      * The number of offsets in this vector.
35      */
36     public static final int COUNT = 4;
37 
38     /**
39      * Create a new {@link BlackLevelPattern} from a given offset array.
40      *
41      * <p>The given offset array must contain offsets for each color channel in
42      * a 2x2 pattern corresponding to the color filter arrangement.  Offsets are
43      * given in row-column scan order.</p>
44      *
45      * @param offsets an array containing a 2x2 pattern of offsets.
46      *
47      * @throws IllegalArgumentException if the given array has an incorrect length.
48      * @throws NullPointerException if the given array is null.
49      * @hide
50      */
BlackLevelPattern(int[] offsets)51     public BlackLevelPattern(int[] offsets) {
52         if (offsets == null) {
53             throw new NullPointerException("Null offsets array passed to constructor");
54         }
55         if (offsets.length < COUNT) {
56             throw new IllegalArgumentException("Invalid offsets array length");
57         }
58         mCfaOffsets = Arrays.copyOf(offsets, COUNT);
59     }
60 
61     /**
62      * Return the color channel offset for a given index into the array of raw pixel values.
63      *
64      * @param column the column index in the the raw pixel array.
65      * @param row the row index in the raw pixel array.
66      * @return a color channel offset.
67      *
68      * @throws IllegalArgumentException if a column or row given is negative.
69      */
getOffsetForIndex(int column, int row)70     public int getOffsetForIndex(int column, int row) {
71         if (row < 0 || column < 0) {
72             throw new IllegalArgumentException("column, row arguments must be positive");
73         }
74         return mCfaOffsets[((row & 1) << 1) | (column & 1)];
75     }
76 
77     /**
78      * Copy the ColorChannel offsets into the destination vector.
79      *
80      * <p>Offsets are given in row-column scan order for a given 2x2 color pattern.</p>
81      *
82      * @param destination an array big enough to hold at least {@value #COUNT} elements after the
83      *          {@code offset}
84      * @param offset a non-negative offset into the array
85      *
86      * @throws IllegalArgumentException if the offset is invalid.
87      * @throws ArrayIndexOutOfBoundsException if the destination vector is too small.
88      * @throws NullPointerException if the destination is null.
89      */
copyTo(int[] destination, int offset)90     public void copyTo(int[] destination, int offset) {
91         checkNotNull(destination, "destination must not be null");
92         if (offset < 0) {
93             throw new IllegalArgumentException("Null offset passed to copyTo");
94         }
95         if (destination.length - offset < COUNT) {
96             throw new ArrayIndexOutOfBoundsException("destination too small to fit elements");
97         }
98         for (int i = 0; i < COUNT; ++i) {
99             destination[offset + i] = mCfaOffsets[i];
100         }
101     }
102 
103     /**
104      * Check if this {@link BlackLevelPattern} is equal to another {@link BlackLevelPattern}.
105      *
106      * <p>Two vectors are only equal if and only if each of the respective elements is equal.</p>
107      *
108      * @return {@code true} if the objects were equal, {@code false} otherwise
109      */
110     @Override
equals(Object obj)111     public boolean equals(Object obj) {
112         if (obj == null) {
113             return false;
114         } else if (this == obj) {
115             return true;
116         } else if (obj instanceof BlackLevelPattern) {
117             final BlackLevelPattern other = (BlackLevelPattern) obj;
118             return Arrays.equals(other.mCfaOffsets, mCfaOffsets);
119         }
120         return false;
121     }
122 
123     /**
124      * {@inheritDoc}
125      */
126     @Override
hashCode()127     public int hashCode() {
128         return Arrays.hashCode(mCfaOffsets);
129     }
130 
131     /**
132      * Return this {@link BlackLevelPattern} as a string representation.
133      *
134      * <p> {@code "BlackLevelPattern([%d, %d], [%d, %d])"}, where each {@code %d} represents one
135      * black level offset of a color channel. The values are in the same order as channels listed
136      * for the CFA layout key (see
137      * {@link android.hardware.camera2.CameraCharacteristics#SENSOR_INFO_COLOR_FILTER_ARRANGEMENT}).
138      * </p>
139      *
140      * <p>A {@link
141      * android.hardware.camera2.CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_MONOCHROME
142      * MONOCHROME} camera only has one channel. As a result, the returned string will contain 4
143      * identical values.
144      * </p>
145      *
146      * @return string representation of {@link BlackLevelPattern}
147      *
148      * @see android.hardware.camera2.CameraCharacteristics#SENSOR_INFO_COLOR_FILTER_ARRANGEMENT
149      */
150     @Override
toString()151     public String toString() {
152         return String.format("BlackLevelPattern([%d, %d], [%d, %d])", mCfaOffsets[0],
153                 mCfaOffsets[1], mCfaOffsets[2], mCfaOffsets[3]);
154     }
155 
156     private final int[] mCfaOffsets;
157 }
158