MeteringRectangle

public final class MeteringRectangle
extends Object

java.lang.Object
   ↳ android.hardware.camera2.params.MeteringRectangle


An immutable class to represent a rectangle (x, y, width, height) with an additional weight component.

The rectangle is defined to be inclusive of the specified coordinates.

When used with a CaptureRequest, the coordinate system is based on the active pixel array, with (0,0) being the top-left pixel in the active pixel array, and (android.sensor.info.activeArraySize.width - 1, android.sensor.info.activeArraySize.height - 1) being the bottom-right pixel in the active pixel array.

The weight must range from .METERING_WEIGHT_MIN to .METERING_WEIGHT_MAX inclusively, and represents a weight for every pixel in the area. This means that a large metering area with the same weight as a smaller area will have more effect in the metering result. Metering areas can partially overlap and the camera device will add the weights in the overlap rectangle.

If all rectangles have 0 weight, then no specific metering area needs to be used by the camera device. If the metering rectangle is outside the used android.scaler.cropRegion returned in capture result metadata, the camera device will ignore the sections outside the rectangle and output the used sections in the result metadata.

Summary

Constants

int METERING_WEIGHT_DONT_CARE

Weights set to this value will cause the camera device to ignore this rectangle.

int METERING_WEIGHT_MAX

The maximum value of valid metering weight.

int METERING_WEIGHT_MIN

The minimum value of valid metering weight.

Public constructors

MeteringRectangle(int x, int y, int width, int height, int meteringWeight)

Create a new metering rectangle.

MeteringRectangle(Point xy, Size dimensions, int meteringWeight)

Create a new metering rectangle.

MeteringRectangle(Rect rect, int meteringWeight)

Create a new metering rectangle.

Public methods

boolean equals(Object other)

Indicates whether some other object is "equal to" this one.

boolean equals(MeteringRectangle other)

Compare two metering rectangles to see if they are equal.

int getHeight()

Return the height of the rectangle.

int getMeteringWeight()

Return the metering weight of the rectangle.

Rect getRect()

Convenience method to create a Rect from this metering rectangle.

Size getSize()

Convenience method to create the size from this metering rectangle.

Point getUpperLeftPoint()

Convenience method to create the upper-left (X,Y) coordinate as a Point.

int getWidth()

Return the width of the rectangle.

int getX()

Return the X coordinate of the left side of the rectangle.

int getY()

Return the Y coordinate of the upper side of the rectangle.

int hashCode()

Returns a hash code value for the object.

String toString()

Return the metering rectangle as a string representation "(x:%d, y:%d, w:%d, h:%d, wt:%d)" where each %d respectively represents the x, y, width, height, and weight points.

Inherited methods

Constants

METERING_WEIGHT_DONT_CARE

Added in API level 21
public static final int METERING_WEIGHT_DONT_CARE

Weights set to this value will cause the camera device to ignore this rectangle. If all metering rectangles are weighed with 0, the camera device will choose its own metering rectangles.

Constant Value: 0 (0x00000000)

METERING_WEIGHT_MAX

Added in API level 21
public static final int METERING_WEIGHT_MAX

The maximum value of valid metering weight.

Constant Value: 1000 (0x000003e8)

METERING_WEIGHT_MIN

Added in API level 21
public static final int METERING_WEIGHT_MIN

The minimum value of valid metering weight.

Constant Value: 0 (0x00000000)

Public constructors

MeteringRectangle

Added in API level 21
public MeteringRectangle (int x, 
                int y, 
                int width, 
                int height, 
                int meteringWeight)

Create a new metering rectangle.

Parameters
x int: coordinate >= 0

y int: coordinate >= 0

width int: width >= 0

height int: height >= 0

meteringWeight int: weight between .METERING_WEIGHT_MIN and .METERING_WEIGHT_MAX inclusively

Throws
IllegalArgumentException if any of the parameters were negative

MeteringRectangle

Added in API level 21
public MeteringRectangle (Point xy, 
                Size dimensions, 
                int meteringWeight)

Create a new metering rectangle.

The point xy's data is copied; the reference is not retained.

Parameters
xy Point: a non-null Point with both x,y >= 0

dimensions Size: a non-null Size with width, height >= 0

meteringWeight int: weight >= 0

Throws
IllegalArgumentException if any of the parameters were negative
NullPointerException if any of the arguments were null

MeteringRectangle

Added in API level 21
public MeteringRectangle (Rect rect, 
                int meteringWeight)

Create a new metering rectangle.

The rectangle data is copied; the reference is not retained.

Parameters
rect Rect: a non-null rectangle with all x,y,w,h dimensions >= 0

meteringWeight int: weight >= 0

Throws
IllegalArgumentException if any of the parameters were negative
NullPointerException if any of the arguments were null

Public methods

equals

Added in API level 21
public boolean equals (Object other)

Indicates whether some other object is "equal to" this one.

The equals method implements an equivalence relation on non-null object references:

  • It is reflexive: for any non-null reference value x, x.equals(x) should return true.
  • It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
  • It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
  • It is consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
  • For any non-null reference value x, x.equals(null) should return false.

An equivalence relation partitions the elements it operates on into equivalence classes; all the members of an equivalence class are equal to each other. Members of an equivalence class are substitutable for each other, at least for some purposes.

Parameters
other Object: the reference object with which to compare.

Returns
boolean true if this object is the same as the obj argument; false otherwise.

equals

Added in API level 21
public boolean equals (MeteringRectangle other)

Compare two metering rectangles to see if they are equal. Two weighted rectangles are only considered equal if each of their components (x, y, width, height, weight) is respectively equal.

Parameters
other MeteringRectangle: Another MeteringRectangle

Returns
boolean true if the metering rectangles are equal, false otherwise

getHeight

Added in API level 21
public int getHeight ()

Return the height of the rectangle.

Returns
int height >= 0

getMeteringWeight

Added in API level 21
public int getMeteringWeight ()

Return the metering weight of the rectangle.

Returns
int weight >= 0

getRect

Added in API level 21
public Rect getRect ()

Convenience method to create a Rect from this metering rectangle.

This strips away the weight from the rectangle.

Returns
Rect a new Rect with non-negative x1, y1, x2, y2

getSize

Added in API level 21
public Size getSize ()

Convenience method to create the size from this metering rectangle.

This strips away the X,Y,weight from the rectangle.

Returns
Size a new Size with non-negative width and height

getUpperLeftPoint

Added in API level 21
public Point getUpperLeftPoint ()

Convenience method to create the upper-left (X,Y) coordinate as a Point.

Returns
Point a new (x,y) Point with both x,y >= 0

getWidth

Added in API level 21
public int getWidth ()

Return the width of the rectangle.

Returns
int width >= 0

getX

Added in API level 21
public int getX ()

Return the X coordinate of the left side of the rectangle.

Returns
int x coordinate >= 0

getY

Added in API level 21
public int getY ()

Return the Y coordinate of the upper side of the rectangle.

Returns
int y coordinate >= 0

hashCode

Added in API level 21
public int hashCode ()

Returns a hash code value for the object. This method is supported for the benefit of hash tables such as those provided by HashMap.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the equals method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.

Returns
int a hash code value for this object.

toString

Added in API level 21
public String toString ()

Return the metering rectangle as a string representation "(x:%d, y:%d, w:%d, h:%d, wt:%d)" where each %d respectively represents the x, y, width, height, and weight points.

Returns
String string representation of the metering rectangle