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