Android APIs
public final class

MeteringRectangle

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

Class Overview

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(MeteringRectangle other)
Compare two metering rectangles to see if they are equal.
boolean equals(Object other)
Compares this instance with the specified object and indicates 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 an integer hash code for this 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.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int METERING_WEIGHT_DONT_CARE

Added in API level 21

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)

public static final int METERING_WEIGHT_MAX

Added in API level 21

The maximum value of valid metering weight.

Constant Value: 1000 (0x000003e8)

public static final int METERING_WEIGHT_MIN

Added in API level 21

The minimum value of valid metering weight.

Constant Value: 0 (0x00000000)

Public Constructors

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

Added in API level 21

Create a new metering rectangle.

Parameters
x coordinate >= 0
y coordinate >= 0
width width >= 0
height height >= 0
meteringWeight weight between .METERING_WEIGHT_MIN and .METERING_WEIGHT_MAX inclusively
Throws
IllegalArgumentException if any of the parameters were negative

public MeteringRectangle (Point xy, Size dimensions, int meteringWeight)

Added in API level 21

Create a new metering rectangle.

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

Parameters
xy a non-null Point with both x,y >= 0
dimensions a non-null Size with width, height >= 0
meteringWeight weight >= 0
Throws
IllegalArgumentException if any of the parameters were negative
NullPointerException if any of the arguments were null

public MeteringRectangle (Rect rect, int meteringWeight)

Added in API level 21

Create a new metering rectangle.

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

Parameters
rect a non-null rectangle with all x,y,w,h dimensions >= 0
meteringWeight weight >= 0
Throws
IllegalArgumentException if any of the parameters were negative
NullPointerException if any of the arguments were null

Public Methods

public boolean equals (MeteringRectangle other)

Added in API level 21

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 Another MeteringRectangle
Returns
  • true if the metering rectangles are equal, false otherwise

public boolean equals (Object other)

Added in API level 21

Compares this instance with the specified object and indicates if they are equal. In order to be equal, o must represent the same object as this instance using a class-specific comparison. The general contract is that this comparison should be reflexive, symmetric, and transitive. Also, no object reference other than null is equal to null.

The default implementation returns true only if this == o. See Writing a correct equals method if you intend implementing your own equals method.

The general contract for the equals and hashCode() methods is that if equals returns true for any two objects, then hashCode() must return the same value for these objects. This means that subclasses of Object usually override either both methods or neither of them.

Parameters
other the object to compare this instance with.
Returns
  • true if the specified object is equal to this Object; false otherwise.

public int getHeight ()

Added in API level 21

Return the height of the rectangle.

Returns
  • height >= 0

public int getMeteringWeight ()

Added in API level 21

Return the metering weight of the rectangle.

Returns
  • weight >= 0

public Rect getRect ()

Added in API level 21

Convenience method to create a Rect from this metering rectangle.

This strips away the weight from the rectangle.

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

public Size getSize ()

Added in API level 21

Convenience method to create the size from this metering rectangle.

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

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

public Point getUpperLeftPoint ()

Added in API level 21

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

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

public int getWidth ()

Added in API level 21

Return the width of the rectangle.

Returns
  • width >= 0

public int getX ()

Added in API level 21

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

Returns
  • x coordinate >= 0

public int getY ()

Added in API level 21

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

Returns
  • y coordinate >= 0

public int hashCode ()

Added in API level 21

Returns an integer hash code for this object. By contract, any two objects for which equals(Object) returns true must return the same hash code value. This means that subclasses of Object usually override both methods or neither method.

Note that hash values must not change over time unless information used in equals comparisons also changes.

See Writing a correct hashCode method if you intend implementing your own hashCode method.

Returns
  • this object's hash code.

public String toString ()

Added in API level 21

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 representation of the metering rectangle