HardwareBuffer
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 |
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 |
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 |
---|
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 |
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 | |
---|---|
Constants
BLOB
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
public static final int DS_24UI8
Format: 24 bits depth, 8 bits stencil
Constant Value: 50 (0x00000032)
DS_FP32UI8
public static final int DS_FP32UI8
Format: 32 bits depth, 8 bits stencil
Constant Value: 52 (0x00000034)
D_16
public static final int D_16
Format: 16 bits depth
Constant Value: 48 (0x00000030)
D_24
public static final int D_24
Format: 24 bits depth
Constant Value: 49 (0x00000031)
D_FP32
public static final int D_FP32
Format: 32 bits depth
Constant Value: 51 (0x00000033)
RGBA_10101010
public static final int RGBA_10101010
Format: 10 bits each red, green, blue, alpha
Constant Value: 59 (0x0000003b)
RGBA_1010102
public static final int RGBA_1010102
Format: 10 bits each red, green, blue, 2 bits alpha
Constant Value: 43 (0x0000002b)
RGBA_8888
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
public static final int RGBA_FP16
Format: 16 bits each red, green, blue, alpha
Constant Value: 22 (0x00000016)
RGBX_8888
public static final int RGBX_8888
Format: 8 bits each red, green, blue, alpha, alpha is always 0xFF
Constant Value: 2 (0x00000002)
RGB_565
public static final int RGB_565
Format: 5 bits each red and blue, 6 bits green, no alpha
Constant Value: 4 (0x00000004)
RGB_888
public static final int RGB_888
Format: 8 bits each red, green, blue, no alpha
Constant Value: 3 (0x00000003)
RG_1616
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
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
public static final int R_8
Format: 8 bits red
Constant Value: 56 (0x00000038)
S_UI8
public static final int S_UI8
Format: 8 bits stencil
Constant Value: 53 (0x00000035)
USAGE_COMPOSER_OVERLAY
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
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
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
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
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
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
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
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
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
public static final long USAGE_GPU_MIPMAP_COMPLETE
Usage: The buffer contains a complete mipmap hierarchy
Constant Value: 67108864 (0x0000000004000000)
USAGE_GPU_SAMPLED_IMAGE
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
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
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
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
public static final int YCBCR_420_888
Format: Planar YCbCr 420; must have an even width and height
Constant Value: 35 (0x00000023)
YCBCR_P010
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
Public methods
close
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:
create
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
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
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
public int getHeight ()
Returns the height of this buffer in pixels.
Returns | |
---|---|
int |
getId
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
public int getLayers ()
Returns the number of layers in this buffer.
Returns | |
---|---|
int |
getUsage
public long getUsage ()
Returns the usage flags of the usage hints set on this buffer.
Returns | |
---|---|
long |
getWidth
public int getWidth ()
Returns the width of this buffer in pixels.
Returns | |
---|---|
int |
isClosed
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:
isSupported
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
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
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 |