status_t unflatten(void const*& buffer, size_t& size, int const*& fds, size_t& count);
public:
+ // The default value of mBuf, used to indicate this doesn't correspond to a slot.
enum { INVALID_BUFFER_SLOT = -1 };
BufferItem();
Rect mCrop;
// mTransform is the current transform flags for this buffer slot.
+ // refer to NATIVE_WINDOW_TRANSFORM_* in <window.h>
uint32_t mTransform;
// mScalingMode is the current scaling mode for this buffer slot.
+ // refer to NATIVE_WINDOW_SCALING_* in <window.h>
uint32_t mScalingMode;
// mTimestamp is the current timestamp for this buffer slot. This gets
- // to set by queueBuffer each time this slot is queued.
+ // to set by queueBuffer each time this slot is queued. This value
+ // is guaranteed to be monotonically increasing for each newly
+ // acquired buffer.
int64_t mTimestamp;
// mIsAutoTimestamp indicates whether mTimestamp was generated
// mFrameNumber is the number of the queued frame for this slot.
uint64_t mFrameNumber;
- // mBuf is the slot index of this buffer
+ // mBuf is the slot index of this buffer (default INVALID_BUFFER_SLOT).
int mBuf;
// mIsDroppable whether this buffer was queued with the
bool mTransformToDisplayInverse;
};
+ enum {
+ // Returned by releaseBuffer, after which the consumer must
+ // free any references to the just-released buffer that it might have.
+ STALE_BUFFER_SLOT = 1,
+ // Returned by dequeueBuffer if there are no pending buffers available.
+ NO_BUFFER_AVAILABLE,
+ // Returned by dequeueBuffer if it's too early for the buffer to be acquired.
+ PRESENT_LATER,
+ };
// acquireBuffer attempts to acquire ownership of the next pending buffer in
- // the BufferQueue. If no buffer is pending then it returns -EINVAL. If a
- // buffer is successfully acquired, the information about the buffer is
- // returned in BufferItem. If the buffer returned had previously been
+ // the BufferQueue. If no buffer is pending then it returns
+ // NO_BUFFER_AVAILABLE. If a buffer is successfully acquired, the
+ // information about the buffer is returned in BufferItem.
+ //
+ // If the buffer returned had previously been
// acquired then the BufferItem::mGraphicBuffer field of buffer is set to
// NULL and it is assumed that the consumer still holds a reference to the
// buffer.
//
- // If presentWhen is nonzero, it indicates the time when the buffer will
+ // If presentWhen is non-zero, it indicates the time when the buffer will
// be displayed on screen. If the buffer's timestamp is farther in the
// future, the buffer won't be acquired, and PRESENT_LATER will be
// returned. The presentation time is in nanoseconds, and the time base
// is CLOCK_MONOTONIC.
- virtual status_t acquireBuffer(BufferItem *buffer, nsecs_t presentWhen) = 0;
+ //
+ // Return of NO_ERROR means the operation completed as normal.
+ //
+ // Return of a positive value means the operation could not be completed
+ // at this time, but the user should try again later:
+ // * NO_BUFFER_AVAILABLE - no buffer is pending (nothing queued by producer)
+ // * PRESENT_LATER - the buffer's timestamp is farther in the future
+ //
+ // Return of a negative value means an error has occurred:
+ // * INVALID_OPERATION - too many buffers have been acquired
+ virtual status_t acquireBuffer(BufferItem* buffer, nsecs_t presentWhen) = 0;
// releaseBuffer releases a buffer slot from the consumer back to the
// BufferQueue. This may be done while the buffer's contents are still
//
// Note that the dependencies on EGL will be removed once we switch to using
// the Android HW Sync HAL.
+ //
+ // Return of NO_ERROR means the operation completed as normal.
+ //
+ // Return of a positive value means the operation could not be completed
+ // at this time, but the user should try again later:
+ // * STALE_BUFFER_SLOT - see above (second paragraph)
+ //
+ // Return of a negative value means an error has occurred:
+ // * BAD_VALUE - one of the following could've happened:
+ // * the buffer slot was invalid
+ // * the fence was NULL
+ // * the buffer slot specified is not in the acquired state
virtual status_t releaseBuffer(int buf, uint64_t frameNumber,
EGLDisplay display, EGLSyncKHR fence,
const sp<Fence>& releaseFence) = 0;
// the application.
//
// consumer may not be NULL.
+ //
+ // Return of a value other than NO_ERROR means an error has occurred:
+ // * NO_INIT - the buffer queue has been abandoned
+ // * BAD_VALUE - a NULL consumer was provided
virtual status_t consumerConnect(const sp<IConsumerListener>& consumer, bool controlledByApp) = 0;
// consumerDisconnect disconnects a consumer from the BufferQueue. All
// buffers will be freed and the BufferQueue is placed in the "abandoned"
// state, causing most interactions with the BufferQueue by the producer to
// fail.
+ //
+ // Return of a value other than NO_ERROR means an error has occurred:
+ // * BAD_VALUE - no consumer is currently connected
virtual status_t consumerDisconnect() = 0;
- // getReleasedBuffers sets the value pointed to by slotMask to a bit mask
- // indicating which buffer slots have been released by the BufferQueue
- // but have not yet been released by the consumer.
+ // getReleasedBuffers sets the value pointed to by slotMask to a bit set.
+ // Each bit index with a 1 corresponds to a released buffer slot with that
+ // index value. In particular, a released buffer is one that has
+ // been released by the BufferQueue but have not yet been released by the consumer.
//
// This should be called from the onBuffersReleased() callback.
+ //
+ // Return of a value other than NO_ERROR means an error has occurred:
+ // * NO_INIT - the buffer queue has been abandoned.
virtual status_t getReleasedBuffers(uint32_t* slotMask) = 0;
// setDefaultBufferSize is used to set the size of buffers returned by
// dequeueBuffer when a width and height of zero is requested. Default
// is 1x1.
+ //
+ // Return of a value other than NO_ERROR means an error has occurred:
+ // * BAD_VALUE - either w or h was zero
virtual status_t setDefaultBufferSize(uint32_t w, uint32_t h) = 0;
// setDefaultMaxBufferCount sets the default value for the maximum buffer
// take effect if the producer sets the count back to zero.
//
// The count must be between 2 and NUM_BUFFER_SLOTS, inclusive.
+ //
+ // Return of a value other than NO_ERROR means an error has occurred:
+ // * BAD_VALUE - bufferCount was out of range (see above).
virtual status_t setDefaultMaxBufferCount(int bufferCount) = 0;
// disableAsyncBuffer disables the extra buffer used in async mode
// flag) and has dequeueBuffer() return WOULD_BLOCK instead.
//
// This can only be called before consumerConnect().
+ //
+ // Return of a value other than NO_ERROR means an error has occurred:
+ // * INVALID_OPERATION - attempting to call this after consumerConnect.
virtual status_t disableAsyncBuffer() = 0;
// setMaxAcquiredBufferCount sets the maximum number of buffers that can
// be acquired by the consumer at one time (default 1). This call will
// fail if a producer is connected to the BufferQueue.
+ //
+ // maxAcquiredBuffers must be (inclusive) between 1 and MAX_MAX_ACQUIRED_BUFFERS.
+ //
+ // Return of a value other than NO_ERROR means an error has occurred:
+ // * BAD_VALUE - maxAcquiredBuffers was out of range (see above).
+ // * INVALID_OPERATION - attempting to call this after a producer connected.
virtual status_t setMaxAcquiredBufferCount(int maxAcquiredBuffers) = 0;
// setConsumerName sets the name used in logging
// GraphicBuffers of a defaultFormat if no format is specified
// in dequeueBuffer. Formats are enumerated in graphics.h; the
// initial default is HAL_PIXEL_FORMAT_RGBA_8888.
+ //
+ // Return of a value other than NO_ERROR means an unknown error has occurred.
virtual status_t setDefaultBufferFormat(uint32_t defaultFormat) = 0;
// setConsumerUsageBits will turn on additional usage bits for dequeueBuffer.
// These are merged with the bits passed to dequeueBuffer. The values are
// enumerated in gralloc.h, e.g. GRALLOC_USAGE_HW_RENDER; the default is 0.
+ //
+ // Return of a value other than NO_ERROR means an unknown error has occurred.
virtual status_t setConsumerUsageBits(uint32_t usage) = 0;
// setTransformHint bakes in rotation to buffers so overlays can be used.
// The values are enumerated in window.h, e.g.
// NATIVE_WINDOW_TRANSFORM_ROT_90. The default is 0 (no transform).
+ //
+ // Return of a value other than NO_ERROR means an unknown error has occurred.
virtual status_t setTransformHint(uint32_t hint) = 0;
// dump state into a string
DECLARE_META_INTERFACE(GraphicBufferProducer);
enum {
+ // A flag returned by dequeueBuffer when the client needs to call
+ // requestBuffer immediately thereafter.
BUFFER_NEEDS_REALLOCATION = 0x1,
+ // A flag returned by dequeueBuffer when all mirrored slots should be
+ // released by the client. This flag should always be processed first.
RELEASE_ALL_BUFFERS = 0x2,
};
// 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 a
// GraphicBuffer 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.
+ // * BAD_VALUE - one of the two conditions occurred:
+ // * slot was out of range (see above)
+ // * buffer specified by the slot is not dequeued
virtual status_t requestBuffer(int slot, sp<GraphicBuffer>* buf) = 0;
// setBufferCount sets the number of buffer slots available. Calling this
// will also cause all buffer slots to be emptied. The caller should empty
// its mirrored copy of the buffer slots when calling this method.
+ //
+ // This function should not be called when there are any dequeued buffer
+ // slots, doing so will result in a BAD_VALUE error returned.
+ //
+ // The buffer count should be at most NUM_BUFFER_SLOTS, but at least
+ // the minimum undequeued buffer count (inclusive). The minimum value
+ // 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 has one or more buffers dequeued
virtual status_t setBufferCount(int bufferCount) = 0;
// 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. If the slot is empty the client
- // should call requestBuffer to assign a new buffer to that slot. The client
- // is expected to either call cancelBuffer on the dequeued slot or to fill
- // in the contents of its associated buffer contents and call queueBuffer.
- // If dequeueBuffer return BUFFER_NEEDS_REALLOCATION, the client is
+ // 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 NULL, the buffer may be written
+ // fence signals. If the fence is Fence::NO_FENCE, the buffer may be written
// immediately.
//
- // The async parameter sets whether we're in asynchrnous mode for this
- // deququeBuffer() call.
- virtual status_t dequeueBuffer(int *slot, sp<Fence>* fence, bool async,
+ // The async parameter sets whether we're in asynchronous mode for this
+ // dequeueBuffer() call.
+ //
+ // 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.
+ //
+ // The pixel formats are enumerated in <graphics.h>, e.g.
+ // HAL_PIXEL_FORMAT_RGBA_8888. 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.
+ //
+ // Return of a negative means an error has occurred:
+ // * NO_INIT - the buffer queue has been abandoned.
+ // * BAD_VALUE - one of the below conditions occurred:
+ // * both in async mode and buffer count was less than the
+ // max numbers of buffers that can be allocated at once
+ // * attempting dequeue more than one buffer at a time
+ // without setting the buffer count with setBufferCount()
+ // * -EBUSY - attempting to dequeue too many buffers at a time
+ // * 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.
+ //
+ // All other negative values are an unknown error returned downstream
+ // from the graphics allocator (typically errno).
+ virtual status_t dequeueBuffer(int* slot, sp<Fence>* fence, bool async,
uint32_t w, uint32_t h, uint32_t format, uint32_t usage) = 0;
// 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. In addition, a timestamp must be provided by the
- // client for this buffer. The timestamp is measured in nanoseconds, and
- // must be monotonically increasing. Its other properties (zero point, etc)
+ // 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 async parameter sets whether we're queuing a buffer in asynchronous mode.
+ // 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).
//
- // outWidth, outHeight and outTransform are filled with the default width
- // and height of the window and current transform applied to buffers,
- // respectively.
+ // 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:
+ // * 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
struct QueueBufferInput : public Flattenable<QueueBufferInput> {
friend class Flattenable<QueueBufferInput>;
inline QueueBufferInput(const Parcel& parcel);
+ // timestamp - a monotonically increasing value in nanoseconds
+ // isAutoTimestamp - if the timestamp was synthesized at queue time
+ // 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>
+ // async - if the buffer is queued in asynchronous 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
inline QueueBufferInput(int64_t timestamp, bool isAutoTimestamp,
const Rect& crop, int scalingMode, uint32_t transform, bool async,
const sp<Fence>& fence)
};
// QueueBufferOutput must be a POD structure
- struct QueueBufferOutput {
+ struct __attribute__ ((__packed__)) QueueBufferOutput {
inline QueueBufferOutput() { }
+ // outWidth - filled with default width applied to the buffer
+ // outHeight - filled with default height applied to the buffer
+ // outTransformHint - filled with default transform applied to the buffer
+ // outNumPendingBuffers - num buffers queued that haven't yet been acquired
+ // (counting the currently queued buffer)
inline void deflate(uint32_t* outWidth,
uint32_t* outHeight,
uint32_t* outTransformHint,
// 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 buffer will not be overwritten until the fence signals. The fence
+ // will usually be the one obtained from dequeueBuffer.
virtual void cancelBuffer(int slot, const sp<Fence>& fence) = 0;
// query retrieves some information for this surface
- // 'what' tokens allowed are that of android_natives.h
+ // '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
virtual int query(int what, int* value) = 0;
// connect attempts to connect a client API to the IGraphicBufferProducer.
// This must be called before any other IGraphicBufferProducer methods are
- // called except for getAllocator.
+ // 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.
//
- // outWidth, outHeight and outTransform are filled with the default width
- // and height of the window and current transform applied to buffers,
- // respectively. The token needs to be any binder object that lives in the
+ // The token needs to be any opaque binder object that lives in the
// producer process -- it is solely used for obtaining a death notification
// when the producer is killed.
+ //
+ // 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).
+ // * 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.
virtual status_t connect(const sp<IBinder>& token,
int api, bool producerControlledByApp, QueueBufferOutput* output) = 0;
//
// This method will fail if the the IGraphicBufferProducer is not currently
// connected to the specified client API.
+ //
+ // The api should be one of the NATIVE_WINDOW_API_* values in <window.h>
+ //
+ // 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
virtual status_t disconnect(int api) = 0;
};
OSDN Git Service
