Package: android.hardware.graphics.mapper@2.0

IMapper

interface IMapper

Properties

BufferDescriptorInfo

struct BufferDescriptorInfo {uint32_t width; uint32_t height; uint32_t layerCount; PixelFormat format; bitfield usage}
Details
Members
width
The width specifies how many columns of pixels must be in the allocated buffer, but does not necessarily represent the offset in columns between the same column in adjacent rows.The rows may be padded.
height
The height specifies how many rows of pixels must be in the allocated buffer.
layerCount
The number of image layers that must be in the allocated buffer.
format
Buffer pixel format.
usage
Buffer usage mask;valid flags can be found in the definition of BufferUsage.

Rect

struct Rect {int32_t left; int32_t top; int32_t width; int32_t height}
Details
Members
left
top
width
height

Methods

createDescriptor

createDescriptor (BufferDescriptorInfo descriptorInfo)
generates (Error error, BufferDescriptor descriptor)

Creates a buffer descriptor.The descriptor can be used with IAllocator to allocate buffers.

Since the buffer descriptor fully describes a buffer, any device dependent or device independent checks must be performed here whenever possible.Specifically, when layered buffers are not supported, this function must return UNSUPPORTED if layerCount is great than 1.

Details
Parameters
descriptorInfo
specifies the attributes of the descriptor.
Generates
error
is NONE upon success.Otherwise, BAD_VALUE when any of the specified attributes is invalid or conflicting.NO_RESOURCES when the creation cannot be fullfilled at this time.UNSUPPORTED when any of the specified attributes is not supported.
descriptor
is the newly created buffer descriptor.
Annotations
entry
callflow
next="*"

importBuffer

importBuffer (handle rawHandle)
generates (Error error, pointer buffer)

Imports a raw buffer handle to create an imported buffer handle for use with the rest of the mapper or with other in-process libraries.

A buffer handle is considered raw when it is cloned(e.g ., with native_handle_clone)from another buffer handle locally, or when it is received from another HAL server/client or another process.A raw buffer handle must not be used to access the underlying graphics buffer.It must be imported to create an imported handle first.

This function must at least validate the raw handle before creating the imported handle.It must also support importing the same raw handle multiple times to create multiple imported handles.The imported handle must be considered valid everywhere in the process, including in another instance of the mapper.

Because of passthrough HALs, a raw buffer handle received from a HAL may actually have been imported in the process.importBuffer must treat such a handle as if it is raw and must not return BAD_BUFFER.The returned handle is independent from the input handle as usual, and freeBuffer must be called on it when it is no longer needed.

Details
Parameters
rawHandle
is the raw buffer handle to import.
Generates
error
is NONE upon success.Otherwise, BAD_BUFFER when the raw handle is invalid.NO_RESOURCES when the raw handle cannot be imported at this time.
buffer
is the imported buffer handle and has the type buffer_handle_t.
Annotations
entry
callflow
next="*"

freeBuffer

freeBuffer (pointer buffer)
generates (Error error)

Frees a buffer handle.Buffer handles returned by importBuffer must be freed with this function when no longer needed.

This function must free up all resources allocated by importBuffer for the imported handle.For example, if the imported handle was created with native_handle_create, this function must call native_handle_close and native_handle_delete.

Details
Parameters
buffer
Generates
error
is NONE upon success.Otherwise, BAD_BUFFER when the buffer is invalid.
Annotations
exit
callflow
next="*"

lock

lock (pointer buffer, bitfield<BufferUsage> cpuUsage, Rect accessRegion, handle acquireFence)
generates (Error error, pointer data)

Locks the given buffer for the specified CPU usage.

Locking the same buffer simultaneously from multiple threads is permitted, but if any of the threads attempt to lock the buffer for writing, the behavior is undefined, except that it must not cause process termination or block the client indefinitely.Leaving the buffer content in an indeterminate state or returning an error are both acceptable.

The client must not modify the content of the buffer outside of accessRegion, and the device need not guarantee that content outside of accessRegion is valid for reading.The result of reading or writing outside of accessRegion is undefined, except that it must not cause process termination.

data will be filled with a pointer to the locked buffer memory.This address will represent the top-left corner of the entire buffer, even if accessRegion does not begin at the top-left corner.

Details
Parameters
buffer
is the buffer to lock.
cpuUsage
specifies one or more CPU usage flags to request.
accessRegion
is the portion of the buffer that the client intends to access.
acquireFence
, when non-empty, is a handle containing a file descriptor referring to a sync fence object, which will be signaled when it is safe for the mapper to lock the buffer.If it is already safe to lock, acquireFence is empty.
Generates
error
is NONE upon success.Otherwise, BAD_BUFFER when the buffer is invalid or is incompatible with this function.BAD_VALUE when cpuUsage is 0, contains non-CPU usage flags, or is incompatible with the buffer.NO_RESOURCES when the buffer cannot be locked at this time, but locking may succeed at a future time.
data
is a CPU-accessible pointer to the buffer data.
Annotations
callflow
next="unlock"

lockYCbCr

lockYCbCr (pointer buffer, bitfield<BufferUsage> cpuUsage, Rect accessRegion, handle acquireFence)
generates (Error error, YCbCrLayout layout)

This is largely the same as lock(), except that instead of returning a pointer directly to the buffer data, it returns an YCbCrLayout struct describing how to access the data planes.

This function must work on buffers with PixelFormat::YCbCr_*_888 if supported by the device, as well as with any other formats requested by multimedia codecs when they are configured with a flexible-YUV-compatible color format.

Details
Parameters
buffer
is the buffer to lock.
cpuUsage
specifies one or more CPU usage flags to request.
accessRegion
is the portion of the buffer that the client intends to access.
acquireFence
, when non-empty, is a handle containing a file descriptor referring to a sync fence object, which will be signaled when it is safe for the mapper to lock the buffer.If it is already safe to lock, acquireFence is empty.
Generates
error
is NONE upon success.Otherwise, BAD_BUFFER when the buffer is invalid or is incompatible with this function.BAD_VALUE when cpuUsage is 0, contains non-CPU usage flags, or is incompatible with the buffer.NO_RESOURCES when the buffer cannot be locked at this time, but locking may succeed at a future time.
layout
is the data layout of the buffer.
Annotations
callflow
next="unlock"

unlock

unlock (pointer buffer)
generates (Error error, handle releaseFence)

Unlocks a buffer to indicate all CPU accesses to the buffer have completed.

Details
Parameters
buffer
is the buffer to unlock.
Generates
error
is NONE upon success.Otherwise, BAD_BUFFER when the buffer is invalid or not locked.
releaseFence
, when non-empty, is a handle containing a file descriptor referring to a sync fence object.The sync fence object will be signaled when the mapper has completed any pending work.
Annotations
callflow
next="*"