Package: android.hardware.graphics.bufferqueue@1.0

IGraphicBufferProducer

interface IGraphicBufferProducer

Ref:frameworks/native/include/gui/IGraphicBufferProducer.h:IGraphicBufferProducer This is a wrapper/wrapped HAL interface for the actual binder interface.

Properties

Status

typedef int32_t Status

Type for return values of functions in IGraphicBufferProducer.

DisconnectMode

enum DisconnectMode: int32_t

Modes for disconnection.

Details
Members
API
Disconnect only the specified API.
ALL_LOCAL
Disconnect any API originally connected from the process calling disconnect.

FenceTimeSnapshot

struct FenceTimeSnapshot {enum State; State state; Fence fence; int64_t signalTimeNs}

Ref:frameworks/native/include/ui/FenceTime.h:FenceTime::Snapshot

An atomic snapshot of the FenceTime that is flattenable.

Details
Members
State
state
fence
signalTimeNs

FrameEventsDelta

struct FrameEventsDelta {uint32_t index; uint64_t frameNumber; bool addPostCompositeCalled; bool addRetireCalled; bool addReleaseCalled; int64_t postedTimeNs; int64_t requestedPresentTimeNs; int64_t latchTimeNs; int64_t firstRefreshStartTimeNs; int64_t lastRefreshStartTimeNs; int64_t dequeueReadyTime; FenceTimeSnapshot gpuCompositionDoneFence; FenceTimeSnapshot displayPresentFence; FenceTimeSnapshot displayRetireFence; FenceTimeSnapshot releaseFence}

Ref:frameworks/native/include/gui/FrameTimestamp.h:FrameEventsDelta

A single frame update from the consumer to producer that can be sent through a HIDL interface.Although this may be sent multiple times for the same frame as new timestamps are set, Fences only need to be sent once.

Details
Members
index
frameNumber
addPostCompositeCalled
addRetireCalled
addReleaseCalled
postedTimeNs
requestedPresentTimeNs
latchTimeNs
firstRefreshStartTimeNs
lastRefreshStartTimeNs
dequeueReadyTime
gpuCompositionDoneFence
displayPresentFence
displayRetireFence
releaseFence

CompositorTiming

struct CompositorTiming {int64_t deadlineNs; int64_t intervalNs; int64_t presentLatencyNs}

Ref:frameworks/native/include/gui/FrameTimestamp.h:CompositorTiming

The most recent compositor timing info sent from consumer to producer through a HIDL interface.

Details
Members
deadlineNs
intervalNs
presentLatencyNs

FrameEventHistoryDelta

struct FrameEventHistoryDelta {vec deltas; CompositorTiming compositorTiming}

Ref:frameworks/native/include/gui/FrameTimestamp.h:FrameEventHistoryDelta

A collection of updates from consumer to producer that can be sent through a HIDL interface.

Details
Members
deltas
compositorTiming

QueueBufferInput

struct QueueBufferInput {int64_t timestamp; int32_t isAutoTimestamp; Dataspace dataSpace; Rect crop; int32_t scalingMode; uint32_t transform; uint32_t stickyTransform; Fence fence; Region surfaceDamage; bool getFrameTimestamps}
Details
Members
timestamp
A monotonically increasing value in nanoseconds.
isAutoTimestamp
Whether the timestamp was synthesized at queue time.
dataSpace
Description of the contents, interpretation depends on format.
crop
A crop rectangle that's used as a hint to the consumer.
scalingMode
A set of flags from NATIVE_WINDOW_SCALING_* in<window.h>.
transform
A set of flags from NATIVE_WINDOW_TRANSFORM_* in<window.h>.
stickyTransform
The sticky transform set in Surface(only used by the LEGACY camera mode).
fence
A fence that the consumer must wait on before reading the buffer;set this to Fence::NO_FENCE if the buffer is ready immediately.
surfaceDamage
getFrameTimestamps
Whether or not the latest frame timestamps should be retrieved from the consumer.

QueueBufferOutput

struct QueueBufferOutput {uint32_t width; uint32_t height; uint32_t transformHint; uint32_t numPendingBuffers; uint64_t nextFrameNumber; bool bufferReplaced; FrameEventHistoryDelta frameTimestamps}
Details
Members
width
height
transformHint
numPendingBuffers
nextFrameNumber
bufferReplaced
frameTimestamps

Methods

requestBuffer

requestBuffer (int32_t slot)
generates (Status status, AnwBuffer buffer)

requestBuffer requests a new buffer for the given index.The server(i.e.the IProducerListener implementation)assigns the newly created buffer to the given slot index, and the client is expected to mirror the slot->buffer mapping so that it's not necessary to transfer an AnwBuffer for every dequeue operation.

The slot must be in the range of[0, NUM_BUFFER_SLOTS).

Return of a value other than NO_ERROR means an error has occurred:* NO_INIT - the buffer queue has been abandoned or the producer is not connected.* BAD_VALUE - one of the two conditions occurred:* slot was out of range(see above)* buffer specified by the slot is not dequeued

Details
Parameters
slot
Generates
status
buffer

setMaxDequeuedBufferCount

setMaxDequeuedBufferCount (int32_t maxDequeuedBuffers)
generates (Status status)

setMaxDequeuedBufferCount sets the maximum number of buffers that can be dequeued by the producer at one time.If this method succeeds, any new buffer slots will be both unallocated and owned by the BufferQueue object(i.e.they are not owned by the producer or consumer). Calling this may also cause some buffer slots to be emptied.If the caller is caching the contents of the buffer slots, it should empty that cache after calling this method.

This function should not be called with a value of maxDequeuedBuffers that is less than the number of currently dequeued buffer slots.Doing so will result in a BAD_VALUE error.

The buffer count should be at least 1(inclusive), but at most(NUM_BUFFER_SLOTS - the minimum undequeued buffer count )(exclusive). The minimum undequeued buffer count can be obtained by calling query(NATIVE_WINDOW_MIN_UNDEQUEUED_BUFFERS).

Return of a value other than NO_ERROR means an error has occurred:* NO_INIT - the buffer queue has been abandoned.* BAD_VALUE - one of the below conditions occurred:* bufferCount was out of range(see above). * client would have more than the requested number of dequeued buffers after this call.* this call would cause the maxBufferCount value to be exceeded.* failure to adjust the number of available slots.

Details
Parameters
maxDequeuedBuffers
Generates
status

setAsyncMode

setAsyncMode (bool async)
generates (Status status)

Set the async flag if the producer intends to asynchronously queue buffers without blocking.Typically this is used for triple-buffering and/or when the swap interval is set to zero.

Enabling async mode will internally allocate an additional buffer to allow for the asynchronous behavior.If it is not enabled queue/dequeue calls may block.

Return of a value other than NO_ERROR means an error has occurred:* NO_INIT - the buffer queue has been abandoned.* BAD_VALUE - one of the following has occurred:* this call would cause the maxBufferCount value to be exceeded * failure to adjust the number of available slots.

Details
Parameters
async
Generates
status

dequeueBuffer

dequeueBuffer (uint32_t width, uint32_t height, PixelFormat format, uint32_t usage, bool getFrameTimestamps)
generates (Status status, int32_t slot, Fence fence, FrameEventHistoryDelta outTimestamps)

dequeueBuffer requests a new buffer slot for the client to use.Ownership of the slot is transfered to the client, meaning that the server will not use the contents of the buffer associated with that slot.

The slot index returned may or may not contain a buffer(client-side). If the slot is empty the client should call requestBuffer to assign a new buffer to that slot.

Once the client is done filling this buffer, it is expected to transfer buffer ownership back to the server with either cancelBuffer on the dequeued slot or to fill in the contents of its associated buffer contents and call queueBuffer.

If dequeueBuffer returns the BUFFER_NEEDS_REALLOCATION flag, the client is expected to call requestBuffer immediately.

If dequeueBuffer returns the RELEASE_ALL_BUFFERS flag, the client is expected to release all of the mirrored slot->buffer mappings.

The fence parameter will be updated to hold the fence associated with the buffer.The contents of the buffer must not be overwritten until the fence signals.If the fence is Fence::NO_FENCE, the buffer may be written immediately.

The width and height parameters must be no greater than the minimum of GL_MAX_VIEWPORT_DIMS and GL_MAX_TEXTURE_SIZE(see:glGetIntegerv). An error due to invalid dimensions might not be reported until updateTexImage() is called.If width and height are both zero, the default values specified by setDefaultBufferSize() are used instead.

If the format is 0, the default format will be used.

The usage argument specifies gralloc buffer usage flags.The values are enumerated in<gralloc.h>, e.g.GRALLOC_USAGE_HW_RENDER.These will be merged with the usage flags specified by IGraphicBufferConsumer::setConsumerUsageBits.

This call will block until a buffer is available to be dequeued.If both the producer and consumer are controlled by the app, then this call can never block and will return WOULD_BLOCK if no buffer is available.

A non-negative value with flags set(see above)will be returned upon success as status.

Return of a negative means an error has occurred:* NO_INIT - the buffer queue has been abandoned or the producer is not connected.* BAD_VALUE - both in async mode and buffer count was less than the max numbers of buffers that can be allocated at once.* INVALID_OPERATION - cannot attach the buffer because it would cause too many buffers to be dequeued, either because the producer already has a single buffer dequeued and did not set a buffer count, or because a buffer count was set and this call would cause it to be exceeded.* WOULD_BLOCK - no buffer is currently available, and blocking is disabled since both the producer/consumer are controlled by app * NO_MEMORY - out of memory, cannot allocate the graphics buffer.* TIMED_OUT - the timeout set by setDequeueTimeout was exceeded while waiting for a buffer to become available.

All other negative values are an unknown error returned downstream from the graphics allocator(typically errno).

Details
Parameters
width
height
format
usage
getFrameTimestamps
Generates
status
slot
fence
outTimestamps

detachBuffer

detachBuffer (int32_t slot)
generates (Status status)

detachBuffer attempts to remove all ownership of the buffer in the given slot from the buffer queue.If this call succeeds, the slot will be freed, and there will be no way to obtain the buffer from this interface.The freed slot will remain unallocated until either it is selected to hold a freshly allocated buffer in dequeueBuffer or a buffer is attached to the slot.The buffer must have already been dequeued, and the caller must already possesses the sp<AnwBuffer >(i.e ., must have called requestBuffer).

Return of a value other than NO_ERROR means an error has occurred:* NO_INIT - the buffer queue has been abandoned or the producer is not connected.* BAD_VALUE - the given slot number is invalid, either because it is out of the range[0, NUM_BUFFER_SLOTS), or because the slot it refers to is not currently dequeued and requested.

Details
Parameters
slot
Generates
status

detachNextBuffer

detachNextBuffer ()
generates (Status status, AnwBuffer buffer, Fence fence)

detachNextBuffer is equivalent to calling dequeueBuffer, requestBuffer, and detachBuffer in sequence, except for two things:

1)It is unnecessary to know the dimensions, format, or usage of the next buffer.2)It will not block, since if it cannot find an appropriate buffer to return, it will return an error instead.

Only slots that are free but still contain an AnwBuffer will be considered, and the oldest of those will be returned.buffer is equivalent to buffer from the requestBuffer call, and fence is equivalent to fence from the dequeueBuffer call.

Return of a value other than NO_ERROR means an error has occurred:* NO_INIT - the buffer queue has been abandoned or the producer is not connected.* BAD_VALUE - either outBuffer or outFence were NULL.* NO_MEMORY - no slots were found that were both free and contained a AnwBuffer.

Details
Generates
status
buffer
fence

attachBuffer

attachBuffer (AnwBuffer buffer)
generates (Status status, int32_t slot)

attachBuffer attempts to transfer ownership of a buffer to the buffer queue.If this call succeeds, it will be as if this buffer was dequeued from the returned slot number.As such, this call will fail if attaching this buffer would cause too many buffers to be simultaneously dequeued.

If attachBuffer returns the RELEASE_ALL_BUFFERS flag, the caller is expected to release all of the mirrored slot->buffer mappings.

A non-negative value with flags set(see above)will be returned upon success.

Return of a negative value means an error has occurred:* NO_INIT - the buffer queue has been abandoned or the producer is not connected.* BAD_VALUE - outSlot or buffer were NULL, invalid combination of async mode and buffer count override, or the generation number of the buffer did not match the buffer queue.* INVALID_OPERATION - cannot attach the buffer because it would cause too many buffers to be dequeued, either because the producer already has a single buffer dequeued and did not set a buffer count, or because a buffer count was set and this call would cause it to be exceeded.* WOULD_BLOCK - no buffer slot is currently available, and blocking is disabled since both the producer/consumer are controlled by the app.* TIMED_OUT - the timeout set by setDequeueTimeout was exceeded while waiting for a slot to become available.

Details
Parameters
buffer
Generates
status
slot

queueBuffer

queueBuffer (int32_t slot, QueueBufferInput input)
generates (Status status, QueueBufferOutput output)

queueBuffer indicates that the client has finished filling in the contents of the buffer associated with slot and transfers ownership of that slot back to the server.

It is not valid to call queueBuffer on a slot that is not owned by the client or one for which a buffer associated via requestBuffer(an attempt to do so will fail with a return value of BAD_VALUE).

In addition, the input must be described by the client(as documented below). Any other properties(zero point, etc)are client-dependent, and should be documented by the client.

The slot must be in the range of[0, NUM_BUFFER_SLOTS).

Upon success, the output will be filled with meaningful values(refer to the documentation below).

Return of a value other than NO_ERROR means an error has occurred:* NO_INIT - the buffer queue has been abandoned or the producer is not connected.* BAD_VALUE - one of the below conditions occurred:* fence was NULL * scaling mode was unknown * both in async mode and buffer count was less than the max numbers of buffers that can be allocated at once * slot index was out of range(see above). * the slot was not in the dequeued state * the slot was enqueued without requesting a buffer * crop rect is out of bounds of the buffer dimensions

Details
Parameters
slot
input
Generates
status
output

cancelBuffer

cancelBuffer (int32_t slot, Fence fence)
generates (Status status)

cancelBuffer indicates that the client does not wish to fill in the buffer associated with slot and transfers ownership of the slot back to the server.

The buffer is not queued for use by the consumer.

The slot must be in the range of[0, NUM_BUFFER_SLOTS).

The buffer will not be overwritten until the fence signals.The fence will usually be the one obtained from dequeueBuffer.

Return of a value other than NO_ERROR means an error has occurred:* NO_INIT - the buffer queue has been abandoned or the producer is not connected.* BAD_VALUE - one of the below conditions occurred:* fence was NULL * slot index was out of range(see above). * the slot was not in the dequeued state

Details
Parameters
slot
fence
Generates
status

query

query (int32_t what)
generates (int32_t result, int32_t value)

query retrieves some information for this surface 'what' tokens allowed are that of NATIVE_WINDOW_* in<window.h>

Return of a value other than NO_ERROR means an error has occurred:* NO_INIT - the buffer queue has been abandoned.* BAD_VALUE - what was out of range

Details
Parameters
what
Generates
result
value

connect

connect (IProducerListener listener, int32_t api, bool producerControlledByApp)
generates (Status status, QueueBufferOutput output)

connect attempts to connect a client API to the IGraphicBufferProducer.This must be called before any other IGraphicBufferProducer methods are called except for getAllocator.A consumer must be already connected.

This method will fail if the connect was previously called on the IGraphicBufferProducer and no corresponding disconnect call was made.

The listener is an optional binder callback object that can be used if the producer wants to be notified when the consumer releases a buffer back to the BufferQueue.It is also used to detect the death of the producer.If only the latter functionality is desired, there is a DummyProducerListener class in IProducerListener.h that can be used.

The api should be one of the NATIVE_WINDOW_API_* values in<window.h>

The producerControlledByApp should be set to true if the producer is hosted by an untrusted process(typically app_process-forked processes). If both the producer and the consumer are app-controlled then all buffer queues will operate in async mode regardless of the async flag.

Upon success, the output will be filled with meaningful data(refer to QueueBufferOutput documentation above).

Return of a value other than NO_ERROR means an error has occurred:* NO_INIT - one of the following occurred:* the buffer queue was abandoned * no consumer has yet connected * BAD_VALUE - one of the following has occurred:* the producer is already connected * api was out of range(see above). * output was NULL.* Failure to adjust the number of available slots.This can happen because of trying to allocate/deallocate the async buffer in response to the value of producerControlledByApp.* DEAD_OBJECT - the token is hosted by an already-dead process

Additional negative errors may be returned by the internals, they should be treated as opaque fatal unrecoverable errors.

Details
Parameters
listener
api
producerControlledByApp
Generates
status
output

disconnect

disconnect (int32_t api, DisconnectModemode/**=DisconnectMode::API */)
generates (Status status)

disconnect attempts to disconnect a client API from the IGraphicBufferProducer.Calling this method will cause any subsequent calls to other IGraphicBufferProducer methods to fail except for getAllocator and connect.Successfully calling connect after this will allow the other methods to succeed again.

The api should be one of the NATIVE_WINDOW_API_* values in<window.h>

Alternatively if mode is AllLocal, then the API value is ignored, and any API connected from the same PID calling disconnect will be disconnected.

Disconnecting from an abandoned IGraphicBufferProducer is legal and is considered a no-op.

Return of a value other than NO_ERROR means an error has occurred:* BAD_VALUE - one of the following has occurred:* the api specified does not match the one that was connected * api was out of range(see above). * DEAD_OBJECT - the token is hosted by an already-dead process

Details
Parameters
api
*/
Generates
status

setSidebandStream

setSidebandStream (handle stream)
generates (Status status)

Attaches a sideband buffer stream to the IGraphicBufferProducer.

A sideband stream is a device-specific mechanism for passing buffers from the producer to the consumer without using dequeueBuffer/ queueBuffer.If a sideband stream is present, the consumer can choose whether to acquire buffers from the sideband stream or from the queued buffers.

Passing NULL or a different stream handle will detach the previous handle if any.

Details
Parameters
stream
Generates
status

allocateBuffers

allocateBuffers (uint32_t width, uint32_t height, PixelFormat format, uint32_t usage)

Allocates buffers based on the given dimensions/format.

This function will allocate up to the maximum number of buffers permitted by the current BufferQueue configuration.It will use the given format, dimensions, and usage bits, which are interpreted in the same way as for dequeueBuffer, and the async flag must be set the same way as for dequeueBuffer to ensure that the correct number of buffers are allocated.This is most useful to avoid an allocation delay during dequeueBuffer.If there are already the maximum number of buffers allocated, this function has no effect.

Details
Parameters
width
height
format
usage

allowAllocation

allowAllocation (bool allow)
generates (Status status)

Sets whether dequeueBuffer is allowed to allocate new buffers.

Normally dequeueBuffer does not discriminate between free slots which already have an allocated buffer and those which do not, and will allocate a new buffer if the slot doesn't have a buffer or if the slot's buffer doesn't match the requested size, format, or usage.This method allows the producer to restrict the eligible slots to those which already have an allocated buffer of the correct size, format, and usage.If no eligible slot is available, dequeueBuffer will block or return an error as usual.

Details
Parameters
allow
Generates
status

setGenerationNumber

setGenerationNumber (uint32_t generationNumber)
generates (Status status)

Sets the current generation number of the BufferQueue.

This generation number will be inserted into any buffers allocated by the BufferQueue, and any attempts to attach a buffer with a different generation number will fail.Buffers already in the queue are not affected and will retain their current generation number.The generation number defaults to 0.

Details
Parameters
generationNumber
Generates
status

getConsumerName

getConsumerName ()
generates (string name)

Returns the name of the connected consumer.

Details
Generates
name

setSharedBufferMode

setSharedBufferMode (bool sharedBufferMode)
generates (Status status)

Used to enable/disable shared buffer mode.

When shared buffer mode is enabled the first buffer that is queued or dequeued will be cached and returned to all subsequent calls to dequeueBuffer and acquireBuffer.This allows the producer and consumer to simultaneously access the same buffer.

Details
Parameters
sharedBufferMode
Generates
status

setAutoRefresh

setAutoRefresh (bool autoRefresh)
generates (Status status)

Used to enable/disable auto-refresh.

Auto refresh has no effect outside of shared buffer mode.In shared buffer mode, when enabled, it indicates to the consumer that it should attempt to acquire buffers even if it is not aware of any being available.

Details
Parameters
autoRefresh
Generates
status

setDequeueTimeout

setDequeueTimeout (int64_t timeoutNs)
generates (Status status)

Sets how long dequeueBuffer will wait for a buffer to become available before returning an error(TIMED_OUT).

This timeout also affects the attachBuffer call, which will block if there is not a free slot available into which the attached buffer can be placed.

By default, the BufferQueue will wait forever, which is indicated by a timeout of -1.If set(to a value other than -1), this will disable non-blocking mode and its corresponding spare buffer(which is used to ensure a buffer is always available).

Return of a value other than NO_ERROR means an error has occurred:* BAD_VALUE - Failure to adjust the number of available slots.This can happen because of trying to allocate/deallocate the async buffer.

Details
Parameters
timeoutNs
Generates
status

getLastQueuedBuffer

getLastQueuedBuffer ()
generates (Status status, AnwBuffer buffer, Fence fence, float[16] transformMatrix)

Returns the last queued buffer along with a fence which must signal before the contents of the buffer are read.If there are no buffers in the queue, buffer.nativeHandle and fence will be null handles.

transformMatrix is meaningless if buffer.nativeHandle is null.

Details
Generates
status
buffer
fence
transformMatrix

getFrameTimestamps

getFrameTimestamps ()
generates (FrameEventHistoryDelta timeStamps)

Gets the frame events that haven't already been retrieved.

Details
Generates
timeStamps

getUniqueId

getUniqueId ()
generates (Status status, uint64_t outId)

Returns a unique id for this BufferQueue.

Details
Generates
status
outId