/*
* Copyright (C) 2014 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.hardware.camera2.params;
import static com.android.internal.util.Preconditions.*;
import android.graphics.PointF;
import android.hardware.camera2.CameraCharacteristics;
import android.hardware.camera2.CameraDevice;
import android.hardware.camera2.CameraMetadata;
import android.hardware.camera2.CaptureRequest;
import android.hardware.camera2.utils.HashCodeHelpers;
import java.util.Arrays;
/**
* Immutable class for describing a {@code 2 x M x 3} tonemap curve of floats.
*
* <p>This defines red, green, and blue curves that the {@link CameraDevice} will
* use as the tonemapping/contrast/gamma curve when {@link CaptureRequest#TONEMAP_MODE} is
* set to {@link CameraMetadata#TONEMAP_MODE_CONTRAST_CURVE}.</p>
*
* <p>The total number of points {@code (Pin, Pout)} for each color channel can be no more than
* {@link CameraCharacteristics#TONEMAP_MAX_CURVE_POINTS}.</p>
*
* <p>The coordinate system for each point is within the inclusive range
* [{@value #LEVEL_BLACK}, {@value #LEVEL_WHITE}].</p>
*
* @see CaptureRequest#TONEMAP_CURVE_BLUE
* @see CaptureRequest#TONEMAP_CURVE_GREEN
* @see CaptureRequest#TONEMAP_CURVE_RED
* @see CameraMetadata#TONEMAP_MODE_CONTRAST_CURVE
* @see CameraCharacteristics#TONEMAP_MAX_CURVE_POINTS
*/
public final class TonemapCurve {
/**
* Lower bound tonemap value corresponding to pure black for a single color channel.
*/
public static final float LEVEL_BLACK = 0.0f;
/**
* Upper bound tonemap value corresponding to a pure white for a single color channel.
*/
public static final float LEVEL_WHITE = 1.0f;
/**
* Number of elements in a {@code (Pin, Pout)} point;
*/
public static final int POINT_SIZE = 2;
/**
* Index of the red color channel curve.
*/
public static final int CHANNEL_RED = 0;
/**
* Index of the green color channel curve.
*/
public static final int CHANNEL_GREEN = 1;
/**
* Index of the blue color channel curve.
*/
public static final int CHANNEL_BLUE = 2;
/**
* Create a new immutable TonemapCurve instance.
*
* <p>Values are stored as a contiguous array of {@code (Pin, Pout)} points.</p>
*
* <p>All parameters may have independent length but should have at most
* {@link CameraCharacteristics#TONEMAP_MAX_CURVE_POINTS} * {@value #POINT_SIZE} elements and
* at least 2 * {@value #POINT_SIZE} elements.</p>
*
* <p>All sub-elements must be in the inclusive range of
* [{@value #LEVEL_BLACK}, {@value #LEVEL_WHITE}].</p>
*
* <p>This constructor copies the array contents and does not retain ownership of the array.</p>
*
* @param red An array of elements whose length is divisible by {@value #POINT_SIZE}
* @param green An array of elements whose length is divisible by {@value #POINT_SIZE}
* @param blue An array of elements whose length is divisible by {@value #POINT_SIZE}
*
* @throws IllegalArgumentException
* if any of input array length is invalid,
* or if any of the elements in the array are not in the range of
* [{@value #LEVEL_BLACK}, {@value #LEVEL_WHITE}]
* @throws NullPointerException
* if any of the parameters are {@code null}
*/
public TonemapCurve(float[] red, float[] green, float[] blue) {
// TODO: maxCurvePoints check?
checkNotNull(red, "red must not be null");
checkNotNull(green, "green must not be null");
checkNotNull(blue, "blue must not be null");
checkArgumentArrayLengthDivisibleBy(red, POINT_SIZE, "red");
checkArgumentArrayLengthDivisibleBy(green, POINT_SIZE, "green");
checkArgumentArrayLengthDivisibleBy(blue, POINT_SIZE, "blue");
checkArgumentArrayLengthNoLessThan(red, MIN_CURVE_LENGTH, "red");
checkArgumentArrayLengthNoLessThan(green, MIN_CURVE_LENGTH, "green");
checkArgumentArrayLengthNoLessThan(blue, MIN_CURVE_LENGTH, "blue");
checkArrayElementsInRange(red, LEVEL_BLACK, LEVEL_WHITE, "red");
checkArrayElementsInRange(green, LEVEL_BLACK, LEVEL_WHITE, "green");
checkArrayElementsInRange(blue, LEVEL_BLACK, LEVEL_WHITE, "blue");
mRed = Arrays.copyOf(red, red.length);
mGreen = Arrays.copyOf(green, green.length);
mBlue = Arrays.copyOf(blue, blue.length);
}
private static void checkArgumentArrayLengthDivisibleBy(float[] array,
int divisible, String arrayName) {
if (array.length % divisible != 0) {
throw new IllegalArgumentException(arrayName + " size must be divisible by "
+ divisible);
}
}
private static int checkArgumentColorChannel(int colorChannel) {
switch (colorChannel) {
case CHANNEL_RED:
case CHANNEL_GREEN:
case CHANNEL_BLUE:
break;
default:
throw new IllegalArgumentException("colorChannel out of range");
}
return colorChannel;
}
private static void checkArgumentArrayLengthNoLessThan(float[] array, int minLength,
String arrayName) {
if (array.length < minLength) {
throw new IllegalArgumentException(arrayName + " size must be at least "
+ minLength);
}
}
/**
* Get the number of points stored in this tonemap curve for the specified color channel.
*
* @param colorChannel one of {@link #CHANNEL_RED}, {@link #CHANNEL_GREEN}, {@link #CHANNEL_BLUE}
* @return number of points stored in this tonemap for that color's curve (>= 0)
*
* @throws IllegalArgumentException if {@code colorChannel} was out of range
*/
public int getPointCount(int colorChannel) {
checkArgumentColorChannel(colorChannel);
return getCurve(colorChannel).length / POINT_SIZE;
}
/**
* Get the point for a color channel at a specified index.
*
* <p>The index must be at least 0 but no greater than {@link #getPointCount(int)} for
* that {@code colorChannel}.</p>
*
* <p>All returned coordinates in the point are between the range of
* [{@value #LEVEL_BLACK}, {@value #LEVEL_WHITE}].</p>
*
* @param colorChannel {@link #CHANNEL_RED}, {@link #CHANNEL_GREEN}, or {@link #CHANNEL_BLUE}
* @param index at least 0 but no greater than {@code getPointCount(colorChannel)}
* @return the {@code (Pin, Pout)} pair mapping the tone for that index
*
* @throws IllegalArgumentException if {@code colorChannel} or {@code index} was out of range
*
* @see #LEVEL_BLACK
* @see #LEVEL_WHITE
*/
public PointF getPoint(int colorChannel, int index) {
checkArgumentColorChannel(colorChannel);
if (index < 0 || index >= getPointCount(colorChannel)) {
throw new IllegalArgumentException("index out of range");
}
final float[] curve = getCurve(colorChannel);
final float pIn = curve[index * POINT_SIZE + OFFSET_POINT_IN];
final float pOut = curve[index * POINT_SIZE + OFFSET_POINT_OUT];
return new PointF(pIn, pOut);
}
/**
* Copy the color curve for a single color channel from this tonemap curve into the destination.
*
* <p>
* <!--The output is encoded the same as in the constructor -->
* Values are stored as packed {@code (Pin, Pout}) points, and there are a total of
* {@link #getPointCount} points for that respective channel.</p>
*
* <p>All returned coordinates are between the range of
* [{@value #LEVEL_BLACK}, {@value #LEVEL_WHITE}].</p>
*
* @param destination
* an array big enough to hold at least {@link #getPointCount} {@code *}
* {@link #POINT_SIZE} elements after the {@code offset}
* @param offset
* a non-negative offset into the array
* @throws NullPointerException
* If {@code destination} was {@code null}
* @throws IllegalArgumentException
* If offset was negative
* @throws ArrayIndexOutOfBoundsException
* If there's not enough room to write the elements at the specified destination and
* offset.
*
* @see CaptureRequest#TONEMAP_CURVE_BLUE
* @see CaptureRequest#TONEMAP_CURVE_RED
* @see CaptureRequest#TONEMAP_CURVE_GREEN
* @see #LEVEL_BLACK
* @see #LEVEL_WHITE
*/
public void copyColorCurve(int colorChannel, float[] destination,
int offset) {
checkArgumentNonnegative(offset, "offset must not be negative");
checkNotNull(destination, "destination must not be null");
if (destination.length + offset < getPointCount(colorChannel) * POINT_SIZE) {
throw new ArrayIndexOutOfBoundsException("destination too small to fit elements");
}
float[] curve = getCurve(colorChannel);
System.arraycopy(curve, /*srcPos*/0, destination, offset, curve.length);
}
/**
* Check if this TonemapCurve is equal to another TonemapCurve.
*
* <p>Two matrices are equal if and only if all of their elements are
* {@link Object#equals equal}.</p>
*
* @return {@code true} if the objects were equal, {@code false} otherwise
*/
@Override
public boolean equals(Object obj) {
if (obj == null) {
return false;
}
if (this == obj) {
return true;
}
if (obj instanceof TonemapCurve) {
final TonemapCurve other = (TonemapCurve) obj;
return Arrays.equals(mRed, other.mRed) &&
Arrays.equals(mGreen, other.mGreen) &&
Arrays.equals(mBlue, other.mBlue);
}
return false;
}
/**
* {@inheritDoc}
*/
@Override
public int hashCode() {
if (mHashCalculated) {
// Avoid re-calculating hash. Data is immutable so this is both legal and faster.
return mHashCode;
}
mHashCode = HashCodeHelpers.hashCode(mRed, mGreen, mBlue);
mHashCalculated = true;
return mHashCode;
}
/**
* Return the TonemapCurve as a string representation.
*
* <p> {@code "TonemapCurve{R:[(%f, %f), (%f, %f) ... (%f, %f)], G:[(%f, %f), (%f, %f) ...
* (%f, %f)], B:[(%f, %f), (%f, %f) ... (%f, %f)]}"},
* where each {@code (%f, %f)} respectively represents one point of the corresponding
* tonemap curve. </p>
*
* @return string representation of {@link TonemapCurve}
*/
@Override
public String toString() {
StringBuilder sb = new StringBuilder("TonemapCurve{");
sb.append("R:");
sb.append(curveToString(CHANNEL_RED));
sb.append(", G:");
sb.append(curveToString(CHANNEL_GREEN));
sb.append(", B:");
sb.append(curveToString(CHANNEL_BLUE));
sb.append("}");
return sb.toString();
}
private String curveToString(int colorChannel) {
checkArgumentColorChannel(colorChannel);
StringBuilder sb = new StringBuilder("[");
float[] curve = getCurve(colorChannel);
int pointCount = curve.length / POINT_SIZE;
for (int i = 0, j = 0; i < pointCount; i++, j += 2) {
sb.append("(");
sb.append(curve[j]);
sb.append(", ");
sb.append(curve[j+1]);
sb.append("), ");
}
// trim extra ", " at the end. Guaranteed to work because pointCount >= 2
sb.setLength(sb.length() - 2);
sb.append("]");
return sb.toString();
}
private float[] getCurve(int colorChannel) {
switch (colorChannel) {
case CHANNEL_RED:
return mRed;
case CHANNEL_GREEN:
return mGreen;
case CHANNEL_BLUE:
return mBlue;
default:
throw new AssertionError("colorChannel out of range");
}
}
private final static int OFFSET_POINT_IN = 0;
private final static int OFFSET_POINT_OUT = 1;
private final static int TONEMAP_MIN_CURVE_POINTS = 2;
private final static int MIN_CURVE_LENGTH = TONEMAP_MIN_CURVE_POINTS * POINT_SIZE;
private final float[] mRed;
private final float[] mGreen;
private final float[] mBlue;
private int mHashCode;
private boolean mHashCalculated = false;
}
|
