Added in API level 26

Summary: Constants | Inherited Constants | Fields | Methods | Protected Methods | Inherited Methods

HardwareBuffer

---

Kotlin |Java

public final class HardwareBuffer
extends Object implements Parcelable, AutoCloseable

java.lang.Object
↳	android.hardware.HardwareBuffer

---

HardwareBuffer wraps a native AHardwareBuffer object, which is a low-level object representing a memory buffer accessible by various hardware units. HardwareBuffer allows sharing buffers across different application processes. In particular, HardwareBuffers may be mappable to memory accessible to various hardware systems, such as the GPU, a sensor or context hub, or other auxiliary processing units. For more information, see the NDK documentation for AHardwareBuffer.

Summary

Constants
int	BLOB Format: opaque format used for raw data transfer; must have a height of 1
int	DS_24UI8 Format: 24 bits depth, 8 bits stencil
int	DS_FP32UI8 Format: 32 bits depth, 8 bits stencil
int	D_16 Format: 16 bits depth
int	D_24 Format: 24 bits depth
int	D_FP32 Format: 32 bits depth
int	RGBA_10101010 Format: 10 bits each red, green, blue, alpha
int	RGBA_1010102 Format: 10 bits each red, green, blue, 2 bits alpha
int	RGBA_8888 Value is RGBA_8888, RGBA_FP16, RGBA_1010102, RGBX_8888, RGB_888, RGB_565, BLOB, YCBCR_420_888, D_16, D_24, DS_24UI8, D_FP32, DS_FP32UI8, S_UI8, YCBCR_P010, R_8, R_16, RG_1616, or RGBA_10101010
int	RGBA_FP16 Format: 16 bits each red, green, blue, alpha
int	RGBX_8888 Format: 8 bits each red, green, blue, alpha, alpha is always 0xFF
int	RGB_565 Format: 5 bits each red and blue, 6 bits green, no alpha
int	RGB_888 Format: 8 bits each red, green, blue, no alpha
int	RG_1616 Format: 16 bits each red, green.
int	R_16 Format: 16 bits red.
int	R_8 Format: 8 bits red
int	S_UI8 Format: 8 bits stencil
long	USAGE_COMPOSER_OVERLAY The buffer will be used as a hardware composer overlay layer.
long	USAGE_CPU_READ_OFTEN Usage: The buffer will often be read by the CPU
long	USAGE_CPU_READ_RARELY Value is either 0 or a combination of USAGE_CPU_READ_RARELY, USAGE_CPU_READ_OFTEN, USAGE_CPU_WRITE_RARELY, USAGE_CPU_WRITE_OFTEN, USAGE_GPU_SAMPLED_IMAGE, USAGE_GPU_COLOR_OUTPUT, USAGE_COMPOSER_OVERLAY, USAGE_PROTECTED_CONTENT, USAGE_VIDEO_ENCODE, USAGE_GPU_DATA_BUFFER, USAGE_SENSOR_DIRECT_DATA, USAGE_GPU_CUBE_MAP, USAGE_GPU_MIPMAP_COMPLETE, and USAGE_FRONT_BUFFER
long	USAGE_CPU_WRITE_OFTEN Usage: The buffer will often be written to by the CPU
long	USAGE_CPU_WRITE_RARELY Usage: The buffer will sometimes be written to by the CPU
long	USAGE_FRONT_BUFFER Usage: The buffer is used for front-buffer rendering.
long	USAGE_GPU_COLOR_OUTPUT Usage: The buffer will be written to by the GPU
long	USAGE_GPU_CUBE_MAP Usage: The buffer will be used as a cube map texture
long	USAGE_GPU_DATA_BUFFER Usage: The buffer will be used as a shader storage or uniform buffer object
long	USAGE_GPU_MIPMAP_COMPLETE Usage: The buffer contains a complete mipmap hierarchy
long	USAGE_GPU_SAMPLED_IMAGE Usage: The buffer will be read from by the GPU
long	USAGE_PROTECTED_CONTENT Usage: The buffer must not be used outside of a protected hardware path
long	USAGE_SENSOR_DIRECT_DATA Usage: The buffer will be used for sensor direct data
long	USAGE_VIDEO_ENCODE Usage: The buffer will be read by a hardware video encoder
int	YCBCR_420_888 Format: Planar YCbCr 420; must have an even width and height
int	YCBCR_P010 Android YUV P010 format.

Inherited constants

From interface android.os.Parcelable int CONTENTS_FILE_DESCRIPTOR Descriptor bit used with describeContents(): indicates that the Parcelable object's flattened representation includes a file descriptor. int PARCELABLE_WRITE_RETURN_VALUE Flag for use with writeToParcel(Parcel, int): the object being written is a return value, that is the result of a function such as "Parcelable someFunction()", "void someFunction(out Parcelable)", or "void someFunction(inout Parcelable)".

Fields
public static final Creator<HardwareBuffer>	CREATOR

Public methods
void	close() Destroys this buffer immediately.
static HardwareBuffer	create(int width, int height, int format, int layers, long usage) Creates a new HardwareBuffer instance.
int	describeContents() Describe the kinds of special objects contained in this Parcelable instance's marshaled representation.
int	getFormat() Returns the @Format of this buffer.
int	getHeight() Returns the height of this buffer in pixels.
long	getId() Returns the system-wide unique id for this buffer This can be useful as a cache key for associating additional objects with a given HardwareBuffer, such as associating an imported EGLImage with the target HardwareBuffer when processing a stream of buffers from ImageReader.
int	getLayers() Returns the number of layers in this buffer.
long	getUsage() Returns the usage flags of the usage hints set on this buffer.
int	getWidth() Returns the width of this buffer in pixels.
boolean	isClosed() Indicates whether this buffer has been closed.
static boolean	isSupported(int width, int height, int format, int layers, long usage) Queries whether the given buffer description is supported by the system.
void	writeToParcel(Parcel dest, int flags) Flatten this object in to a Parcel.

Protected methods
void	finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.

Inherited methods
From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
From interface android.os.Parcelable abstract int describeContents() Describe the kinds of special objects contained in this Parcelable instance's marshaled representation. abstract void writeToParcel(Parcel dest, int flags) Flatten this object in to a Parcel.
From interface java.lang.AutoCloseable abstract void close() Closes this resource, relinquishing any underlying resources.

Constants

BLOB

Added in API level 26

public static final int BLOB

Format: opaque format used for raw data transfer; must have a height of 1

Constant Value: 33 (0x00000021)

DS_24UI8

Added in API level 28

public static final int DS_24UI8

Format: 24 bits depth, 8 bits stencil

Constant Value: 50 (0x00000032)

DS_FP32UI8

Added in API level 28

public static final int DS_FP32UI8

Format: 32 bits depth, 8 bits stencil

Constant Value: 52 (0x00000034)

D_16

Added in API level 28

public static final int D_16

Format: 16 bits depth

Constant Value: 48 (0x00000030)

D_24

Added in API level 28

public static final int D_24

Format: 24 bits depth

Constant Value: 49 (0x00000031)

D_FP32

Added in API level 28

public static final int D_FP32

Format: 32 bits depth

Constant Value: 51 (0x00000033)

RGBA_10101010

Added in API level 35

public static final int RGBA_10101010

Format: 10 bits each red, green, blue, alpha

Constant Value: 59 (0x0000003b)

RGBA_1010102

Added in API level 26

public static final int RGBA_1010102

Format: 10 bits each red, green, blue, 2 bits alpha

Constant Value: 43 (0x0000002b)

RGBA_8888

Added in API level 26

public static final int RGBA_8888

Value is RGBA_8888, RGBA_FP16, RGBA_1010102, RGBX_8888, RGB_888, RGB_565, BLOB, YCBCR_420_888, D_16, D_24, DS_24UI8, D_FP32, DS_FP32UI8, S_UI8, YCBCR_P010, R_8, R_16, RG_1616, or RGBA_10101010

Constant Value: 1 (0x00000001)

RGBA_FP16

Added in API level 26

public static final int RGBA_FP16

Format: 16 bits each red, green, blue, alpha

Constant Value: 22 (0x00000016)

RGBX_8888

Added in API level 26

public static final int RGBX_8888

Format: 8 bits each red, green, blue, alpha, alpha is always 0xFF

Constant Value: 2 (0x00000002)

RGB_565

Added in API level 26

public static final int RGB_565

Format: 5 bits each red and blue, 6 bits green, no alpha

Constant Value: 4 (0x00000004)

RGB_888

Added in API level 26

public static final int RGB_888

Format: 8 bits each red, green, blue, no alpha

Constant Value: 3 (0x00000003)

RG_1616

Added in API level 35

public static final int RG_1616

Format: 16 bits each red, green. When sampled on the GPU this is represented as an unsigned integer instead of implicit unsigned normalize. For more information see https://www.khronos.org/opengl/wiki/Normalized_Integer

Constant Value: 58 (0x0000003a)

R_16

Added in API level 35

public static final int R_16

Format: 16 bits red. When sampled on the GPU this is represented as an unsigned integer instead of implicit unsigned normalize. For more information see https://www.khronos.org/opengl/wiki/Normalized_Integer

Constant Value: 57 (0x00000039)

R_8

Added in API level 35

public static final int R_8

Format: 8 bits red

Constant Value: 56 (0x00000038)

S_UI8

Added in API level 28

public static final int S_UI8

Format: 8 bits stencil

Constant Value: 53 (0x00000035)

USAGE_COMPOSER_OVERLAY

Added in API level 33

public static final long USAGE_COMPOSER_OVERLAY

The buffer will be used as a hardware composer overlay layer. That is, it will be displayed using the system compositor via SurfaceControl This flag is currently only needed when using SurfaceControl.Transaction.setBuffer(SurfaceControl, HardwareBuffer) to set a buffer. In all other cases, the framework adds this flag internally to buffers that could be presented in a composer overlay.

Constant Value: 2048 (0x0000000000000800)

USAGE_CPU_READ_OFTEN

Added in API level 26

public static final long USAGE_CPU_READ_OFTEN

Usage: The buffer will often be read by the CPU

Constant Value: 3 (0x0000000000000003)

USAGE_CPU_READ_RARELY

Added in API level 26

public static final long USAGE_CPU_READ_RARELY

Value is either 0 or a combination of USAGE_CPU_READ_RARELY, USAGE_CPU_READ_OFTEN, USAGE_CPU_WRITE_RARELY, USAGE_CPU_WRITE_OFTEN, USAGE_GPU_SAMPLED_IMAGE, USAGE_GPU_COLOR_OUTPUT, USAGE_COMPOSER_OVERLAY, USAGE_PROTECTED_CONTENT, USAGE_VIDEO_ENCODE, USAGE_GPU_DATA_BUFFER, USAGE_SENSOR_DIRECT_DATA, USAGE_GPU_CUBE_MAP, USAGE_GPU_MIPMAP_COMPLETE, and USAGE_FRONT_BUFFER

Constant Value: 2 (0x0000000000000002)

USAGE_CPU_WRITE_OFTEN

Added in API level 26

public static final long USAGE_CPU_WRITE_OFTEN

Usage: The buffer will often be written to by the CPU

Constant Value: 48 (0x0000000000000030)

USAGE_CPU_WRITE_RARELY

Added in API level 26

public static final long USAGE_CPU_WRITE_RARELY

Usage: The buffer will sometimes be written to by the CPU

Constant Value: 32 (0x0000000000000020)

USAGE_FRONT_BUFFER

Added in API level 33

public static final long USAGE_FRONT_BUFFER

Usage: The buffer is used for front-buffer rendering. When front-buffering rendering is specified, different usages may adjust their behavior as a result. For example, when used as USAGE_GPU_COLOR_OUTPUT the buffer will behave similar to a single-buffered window. When used with USAGE_COMPOSER_OVERLAY, the system will try to prioritize the buffer receiving an overlay plane & avoid caching it in intermediate composition buffers.

Constant Value: 4294967296 (0x0000000100000000)

USAGE_GPU_COLOR_OUTPUT

Added in API level 26

public static final long USAGE_GPU_COLOR_OUTPUT

Usage: The buffer will be written to by the GPU

Constant Value: 512 (0x0000000000000200)

USAGE_GPU_CUBE_MAP

Added in API level 28

public static final long USAGE_GPU_CUBE_MAP

Usage: The buffer will be used as a cube map texture

Constant Value: 33554432 (0x0000000002000000)

USAGE_GPU_DATA_BUFFER

Added in API level 26

public static final long USAGE_GPU_DATA_BUFFER

Usage: The buffer will be used as a shader storage or uniform buffer object

Constant Value: 16777216 (0x0000000001000000)

USAGE_GPU_MIPMAP_COMPLETE

Added in API level 28

public static final long USAGE_GPU_MIPMAP_COMPLETE

Usage: The buffer contains a complete mipmap hierarchy

Constant Value: 67108864 (0x0000000004000000)

USAGE_GPU_SAMPLED_IMAGE

Added in API level 26

public static final long USAGE_GPU_SAMPLED_IMAGE

Usage: The buffer will be read from by the GPU

Constant Value: 256 (0x0000000000000100)

USAGE_PROTECTED_CONTENT

Added in API level 26

public static final long USAGE_PROTECTED_CONTENT

Usage: The buffer must not be used outside of a protected hardware path

Constant Value: 16384 (0x0000000000004000)

USAGE_SENSOR_DIRECT_DATA

Added in API level 26

public static final long USAGE_SENSOR_DIRECT_DATA

Usage: The buffer will be used for sensor direct data

Constant Value: 8388608 (0x0000000000800000)

USAGE_VIDEO_ENCODE

Added in API level 26

public static final long USAGE_VIDEO_ENCODE

Usage: The buffer will be read by a hardware video encoder

Constant Value: 65536 (0x0000000000010000)

YCBCR_420_888

Added in API level 30

public static final int YCBCR_420_888

Format: Planar YCbCr 420; must have an even width and height

Constant Value: 35 (0x00000023)

YCBCR_P010

Added in API level 33

public static final int YCBCR_P010

Android YUV P010 format.

P010 is a 4:2:0 YCbCr semiplanar format comprised of a WxH Y plane followed by a Wx(H/2) CbCr plane. Each sample is represented by a 16-bit little-endian value, with the lower 6 bits set to zero.

Constant Value: 54 (0x00000036)

Fields

CREATOR

Added in API level 26

public static final Creator<HardwareBuffer> CREATOR

Public methods

close

Added in API level 26

public void close ()

Destroys this buffer immediately. Calling this method frees up any underlying native resources. After calling this method, this buffer must not be used in any way.

See also:

• isClosed()

create

Added in API level 26

public static HardwareBuffer create (int width, 
                int height, 
                int format, 
                int layers, 
                long usage)

Creates a new HardwareBuffer instance.

Calling this method will throw an IllegalStateException if format is not a supported Format type.

Parameters
width	int: The width in pixels of the buffer Value is 1 or greater
height	int: The height in pixels of the buffer Value is 1 or greater
format	int: The @Format of each pixel Value is RGBA_8888, RGBA_FP16, RGBA_1010102, RGBX_8888, RGB_888, RGB_565, BLOB, YCBCR_420_888, D_16, D_24, DS_24UI8, D_FP32, DS_FP32UI8, S_UI8, YCBCR_P010, R_8, R_16, RG_1616, or RGBA_10101010
layers	int: The number of layers in the buffer Value is 1 or greater
usage	long: The @Usage flags describing how the buffer will be used Value is either 0 or a combination of USAGE_CPU_READ_RARELY, USAGE_CPU_READ_OFTEN, USAGE_CPU_WRITE_RARELY, USAGE_CPU_WRITE_OFTEN, USAGE_GPU_SAMPLED_IMAGE, USAGE_GPU_COLOR_OUTPUT, USAGE_COMPOSER_OVERLAY, USAGE_PROTECTED_CONTENT, USAGE_VIDEO_ENCODE, USAGE_GPU_DATA_BUFFER, USAGE_SENSOR_DIRECT_DATA, USAGE_GPU_CUBE_MAP, USAGE_GPU_MIPMAP_COMPLETE, and USAGE_FRONT_BUFFER

Returns
HardwareBuffer	A HardwareBuffer instance if successful, or throws an IllegalArgumentException if the dimensions passed are invalid (either zero, negative, or too large to allocate), if the format is not supported, if the requested number of layers is less than one or not supported, or if the passed usage flags are not a supported set. This value cannot be null.

describeContents

Added in API level 26

public int describeContents ()

Describe the kinds of special objects contained in this Parcelable instance's marshaled representation. For example, if the object will include a file descriptor in the output of writeToParcel(android.os.Parcel, int), the return value of this method must include the CONTENTS_FILE_DESCRIPTOR bit.

Returns
int	a bitmask indicating the set of special object types marshaled by this Parcelable object instance. Value is either 0 or CONTENTS_FILE_DESCRIPTOR

getFormat

Added in API level 26

public int getFormat ()

Returns the @Format of this buffer.

Returns
int	Value is RGBA_8888, RGBA_FP16, RGBA_1010102, RGBX_8888, RGB_888, RGB_565, BLOB, YCBCR_420_888, D_16, D_24, DS_24UI8, D_FP32, DS_FP32UI8, S_UI8, YCBCR_P010, R_8, R_16, RG_1616, or RGBA_10101010

getHeight

Added in API level 26

public int getHeight ()

Returns the height of this buffer in pixels.

Returns
int

getId

Added in API level 34

public long getId ()

Returns the system-wide unique id for this buffer This can be useful as a cache key for associating additional objects with a given HardwareBuffer, such as associating an imported EGLImage with the target HardwareBuffer when processing a stream of buffers from ImageReader. This can also be useful for doing cross-process buffer caching. As sending a HardwareBuffer over Binder is slower than sending a long, this can be used as reliable cache key after an initial handshake that passes the HardwareBuffers themselves to later be referred to using only the id.

Returns
long

getLayers

Added in API level 26

public int getLayers ()

Returns the number of layers in this buffer.

Returns
int

getUsage

Added in API level 26

public long getUsage ()

Returns the usage flags of the usage hints set on this buffer.

Returns
long

getWidth

Added in API level 26

public int getWidth ()

Returns the width of this buffer in pixels.

Returns
int

isClosed

Added in API level 26

public boolean isClosed ()

Indicates whether this buffer has been closed. A closed buffer cannot be used in any way: the buffer cannot be written to a parcel, etc.

Returns
boolean	True if this HardwareBuffer is in a closed state, false otherwise.

See also:

• close()

isSupported

Added in API level 29

public static boolean isSupported (int width, 
                int height, 
                int format, 
                int layers, 
                long usage)

Queries whether the given buffer description is supported by the system. If this returns true, then the allocation may succeed until resource exhaustion occurs. If this returns false then this combination will never succeed.

Parameters
width	int: The width in pixels of the buffer Value is 1 or greater
height	int: The height in pixels of the buffer Value is 1 or greater
format	int: The @Format of each pixel Value is RGBA_8888, RGBA_FP16, RGBA_1010102, RGBX_8888, RGB_888, RGB_565, BLOB, YCBCR_420_888, D_16, D_24, DS_24UI8, D_FP32, DS_FP32UI8, S_UI8, YCBCR_P010, R_8, R_16, RG_1616, or RGBA_10101010
layers	int: The number of layers in the buffer Value is 1 or greater
usage	long: The @Usage flags describing how the buffer will be used Value is either 0 or a combination of USAGE_CPU_READ_RARELY, USAGE_CPU_READ_OFTEN, USAGE_CPU_WRITE_RARELY, USAGE_CPU_WRITE_OFTEN, USAGE_GPU_SAMPLED_IMAGE, USAGE_GPU_COLOR_OUTPUT, USAGE_COMPOSER_OVERLAY, USAGE_PROTECTED_CONTENT, USAGE_VIDEO_ENCODE, USAGE_GPU_DATA_BUFFER, USAGE_SENSOR_DIRECT_DATA, USAGE_GPU_CUBE_MAP, USAGE_GPU_MIPMAP_COMPLETE, and USAGE_FRONT_BUFFER

Returns
boolean	True if the combination is supported, false otherwise.

writeToParcel

Added in API level 26

public void writeToParcel (Parcel dest, 
                int flags)

Flatten this object in to a Parcel.

Calling this method will throw an IllegalStateException if close() has been previously called.

Parameters
dest	Parcel: The Parcel in which the object should be written.
flags	int: Additional flags about how the object should be written. May be 0 or Parcelable.PARCELABLE_WRITE_RETURN_VALUE.

Protected methods

finalize

Added in API level 26

protected void finalize ()

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. A subclass overrides the finalize method to dispose of system resources or to perform other cleanup.

The general contract of finalize is that it is invoked if and when the Java virtual machine has determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, except as a result of an action taken by the finalization of some other object or class which is ready to be finalized. The finalize method may take any action, including making this object available again to other threads; the usual purpose of finalize, however, is to perform cleanup actions before the object is irrevocably discarded. For example, the finalize method for an object that represents an input/output connection might perform explicit I/O transactions to break the connection before the object is permanently discarded.

The finalize method of class Object performs no special action; it simply returns normally. Subclasses of Object may override this definition.

The Java programming language does not guarantee which thread will invoke the finalize method for any given object. It is guaranteed, however, that the thread that invokes finalize will not be holding any user-visible synchronization locks when finalize is invoked. If an uncaught exception is thrown by the finalize method, the exception is ignored and finalization of that object terminates.

After the finalize method has been invoked for an object, no further action is taken until the Java virtual machine has again determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, including possible actions by other objects or classes which are ready to be finalized, at which point the object may be discarded.

The finalize method is never invoked more than once by a Java virtual machine for any given object.

Any exception thrown by the finalize method causes the finalization of this object to be halted, but is otherwise ignored.

Throws
Throwable