/* * Copyright (C) 2018 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.hardware.graphics.bufferqueue@2.0; import android.hardware.graphics.common@1.2::HardwareBuffer; import android.hardware.graphics.common@1.2::HardwareBufferDescription; import android.hardware.graphics.common@1.2::Rect; import IProducerListener; /** * Ref: frameworks/native/include/gui/IGraphicBufferProducer.h: * IGraphicBufferProducer * This is a wrapper/wrapped HAL interface for the actual binder interface. */ interface IGraphicBufferProducer { /** * Sets the maximum number of buffers that can be dequeued at one time. If * this method succeeds, any new buffer slots shall be both unallocated and * owned by the buffer queue, i.e., they are not owned by the producer or * the consumer. Calling this may cause some buffer slots to be emptied. If * the caller is caching the contents of the buffer slots, it must empty * that cache after calling this method. * * @p maxDequeuedBuffers must not be less than the number of currently * dequeued buffer slots; otherwise, the returned @p status shall be * `BAD_VALUE`. * * @p maxDequeuedBuffers must 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(ANATIVEWINDOW_QUERY_MIN_UNDEQUEUED_BUFFERS)`. * * Before calling setMaxDequeuedBufferCount(), the caller must make sure * that * - @p maxDequeuedBuffers is greater than or equal to 1. * - @p maxDequeuedBuffers is greater than or equal to the number of * currently dequeued buffer slots. * If any of these conditions do not hold, or if the request to set the new * maximum number of dequeued buffers cannot be accomplished for any other * reasons, `BAD_VALUE` shall be returned in @p status. * * @param maxDequeuedBuffers The desired number of buffers that can be * dequeued at one time. * @return status Status of the call. */ setMaxDequeuedBufferCount( int32_t maxDequeuedBuffers ) generates ( Status status ); /** * Assigns a newly created buffer to the given slot index. The client is * expected to mirror the slot-to-buffer mapping so that it is not necessary * to transfer a `HardwareBuffer` object for every dequeue operation. * * If @p slot is not a valid slot index corresponding to a dequeued buffer, * the call shall fail with @p status set to `BAD_VALUE`. * * @param slot Slot index. * @return status Status of the call. * @return buffer New buffer associated to the given slot index. * @return generationNumber Generation number of the buffer. If * requestBuffer() is called immediately after dequeueBuffer() returns * with `bufferNeedsReallocation` set to `true`, @p generationNumber must * match the current generation number of the buffer queue previously * set by setGenerationNumber(). Otherwise, @p generationNumber may not * match the current generation number of the buffer queue. */ requestBuffer( int32_t slot ) generates ( Status status, HardwareBuffer buffer, uint32_t generationNumber ); /** * Sets the async flag: whether 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 may internally allocate an additional buffer to allow * for the asynchronous behavior. If it is not enabled, queue/dequeue calls * may block. * * Changing the async flag may affect the number of available slots. If the * adjustment to the number of slots cannot be made, @p status shall be set * to `BAD_VALUE`. * * @param async True if the asynchronous operation is desired; false * otherwise. * @return status Status of the call. */ setAsyncMode( bool async ) generates ( Status status ); /** * Input data for dequeueBuffer() specifying desired attributes of a buffer * to dequeue. * * This structure contains 4 fields from * +llndk libnativewindow#AHardwareBuffer_Desc. * * 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 may not be reported * until updateTexImage() is called. * * If `width` and `height` are both zero, the default dimensions shall be * used. If only one of `width` and `height` is zero, dequeueBuffer() shall * return `BAD_VALUE` in `status`. * * If `format` is zero, the default format shall be used. * * `usage` shall be merged with the usage flags set from the consumer side. * * @sa +llndk libnativewindow#AHardwareBuffer_Desc. */ struct DequeueBufferInput { uint32_t width; uint32_t height; uint32_t format; uint64_t usage; }; /** * Output data for dequeueBuffer(). * * A `DequeueBufferOutput` object returned from dequeueBuffer() shall be * valid if and only if `status` returned from the same call is `OK`. */ struct DequeueBufferOutput { /** * The number of frames that have elapsed since the buffer was last * queued. */ uint64_t bufferAge; /** * Whether the client must call requestBuffer(). */ bool bufferNeedsReallocation; /** * Whether the client must discard the mirrored slot-to-buffer * mapping. */ bool releaseAllBuffers; /** * Fence associated with the buffer. * * If this is an empty fence, the buffer may be written immediately; * otherwise, the buffer must not be written to until the fence signals. */ Fence fence; }; /** * Requests a new buffer slot for the client to use. Ownership of the slot * is transfered to the client, meaning that the server shall not use the * contents of the buffer associated with that slot. * * On success, @p status shall be `OK`, and @p output shall contain valid * information of the call. Otherwise, the contents of @p output are * meaningless. * * The slot index returned in @p slot may or may not contain a buffer * (client-side). If the slot is empty, the client must 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 with `output.releaseAllBuffers` set to `true`, * the client is expected to release all of the mirrored slot-to-buffer * mappings. * * If dequeueBuffer() returns with `output.bufferNeedsReallocation` set to * `true`, the client is expected to call requestBuffer() immediately. * * The returned `output.fence` shall 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 an empty fence, the buffer may be * written immediately. * * This call shall 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 shall return `WOULD_BLOCK` in @p status if no buffer * is available. * * If a dequeue operation shall cause certain conditions on the number of * buffers to be violated (such as the maximum number of dequeued buffers), * @p status shall be set to `INVALID_OPERATION` to indicate failure. * * If a dequeue operation cannot be completed within the time period * previously set by setDequeueTimeout(), the return @p status shall * `TIMED_OUT`. * * See @ref DequeueBufferInput for more information on the @p input * parameter. * * @param input See #DequeueBufferInput for more information. * @return status Status of the call. * @return slot Slot index. * @return output See #DequeueBufferOutput for more information. * * @sa queueBuffer(), requestBuffer(). */ dequeueBuffer( DequeueBufferInput input ) generates ( Status status, int32_t slot, DequeueBufferOutput output ); /** * Attempts to remove all ownership of the buffer in the given slot from the * buffer queue. * * If this call succeeds, the slot shall be freed, and there shall be no way * to obtain the buffer from this interface. The freed slot shall 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 buffer (i.e., must have called requestBuffer()). * * @param slot Slot index. * @return status Status of the call. */ detachBuffer( int32_t slot ) generates ( Status status ); /** * Dequeues a buffer slot, requests the buffer associated to the slot, and * detaches it from the buffer queue. This is equivalent to calling * dequeueBuffer(), requestBuffer(), and detachBuffer() in succession except * for two things: * 1. It is unnecessary to provide a #DequeueBufferInput object. * 2. The call shall not block, since if it cannot find an appropriate * buffer to return, it shall return an error instead. * * Only slots that are free but still contain a buffer shall be considered, * and the oldest of those shall be returned. @p buffer is equivalent to the * buffer that would be returned from requestBuffer(), and @p fence is * equivalent to the fence that would be returned from dequeueBuffer(). * * @return status Status of the call. * @return buffer Buffer just released from the buffer queue. * @return fence Fence associated to @p buffer. * * @sa dequeueBuffer(), requestBuffer(), detachBuffer(). */ detachNextBuffer( ) generates ( Status status, HardwareBuffer buffer, Fence fence ); /** * Attempts to transfer ownership of a buffer to the buffer queue. * * If this call succeeds, it shall be as if this buffer was dequeued from the * returned slot index. As such, this call shall fail if attaching this * buffer would cause too many buffers to be simultaneously dequeued. * * If the returned @p releaseAllBuffers is `true`, the caller is expected to * release all of the mirrored slot-to-buffer mappings. * * See dequeueBuffer() for conditions that may cause the call to fail. * * @param buffer Buffer to attach to the buffer queue. * @param generationNumber Generation number of the buffer. If this does not * match the current generation number of the buffer queue, the call * must fail with @p status set to `BAD_VALUE`. * @return status Status of the call. * @return slot Slot index assigned to @p buffer. * @return releaseAllBuffers Whether the caller is expected to release all * of the mirrored slot-to-buffer mappings. * * @sa dequeueBuffer(). */ attachBuffer( HardwareBuffer buffer, uint32_t generationNumber ) generates ( Status status, int32_t slot, bool releaseAllBuffers ); struct QueueBufferInput { /** * Timestamp in nanoseconds. */ int64_t timestamp; /** * Whether the timestamp was synthesized at queue time. */ bool isAutoTimestamp; /** * Dataspace of the contents. * * @sa +ndk libnativewindow#ADataSpace. */ int32_t dataSpace; /** * Crop rectangle that is used as a hint to the consumer. */ Rect crop; /** * Transformation flags. * * @sa +ndk libnativewindow#ANativeWindowTransform. */ int32_t transform; /** * The sticky transform set in Surface (only used by the LEGACY camera * mode). * * @sa +ndk libnativewindow#ANativeWindowTransform. */ int32_t stickyTransform; /** * Fence that the consumer must wait on before reading the buffer. An * empty fence indicates that the buffer is ready immediately. */ Fence fence; /** * List of rectangular pieces covering the damage region. */ vec surfaceDamage; }; /** * Information about the queued buffer. `QueueBufferOutput` is used in both * queueBuffer() and connect(). */ struct QueueBufferOutput { /** * Default width of a buffer in the buffer queue. */ uint32_t width; /** * Default height of a buffer in the buffer queue. */ uint32_t height; /** * The transform hint of the buffer queue. * * @sa +ndk libnativewindow#ANativeWindowTransform. */ int32_t transformHint; /** * The number of pending buffers in the buffer queue. If this is * returned from queueBuffer(), the number shall include the buffer that * has just been queued. */ uint32_t numPendingBuffers; /** * The frame number of the next frame. The buffer queue maintains this * number and makes sure that it is increasing for every successful * queueBuffer() call. */ uint64_t nextFrameNumber; /** * After a successful queueBuffer() call, #bufferReplaced shall be set to * true if the queued buffer replaced a previously queued buffer that * has not been consumed. */ bool bufferReplaced; }; /** * 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 buffer queue. * * @p status may be set to `BAD_VALUE` if any of the following conditions * hold: * - The buffer queue is operating in the asynchronous mode, and the * buffer count was smaller than the maximum number of buffers that can * be allocated at once. * - @p slot is an invalid slot index, i.e., the slot is not owned by the * client by previously calling dequeueBuffer(), requestBuffer() or * attachBuffer(). * - The crop rectangle is not contained in the buffer. * * Upon success, the output shall be filled with meaningful values * (refer to the documentation of @ref QueueBufferOutput). * * @param slot Slot index. * @param input See @ref QueueBufferInput. * @return status Status of the call. * @return output See @ref QueueBufferOutput. * * @sa #QueueBufferInput, #QueueBufferOutput, dequeueBuffer(). */ queueBuffer( int32_t slot, QueueBufferInput input ) generates ( Status status, QueueBufferOutput output ); /** * Indicates that the client does not wish to fill in the buffer associated * with the slot and transfers ownership of the slot back to the server. The * buffer is not queued for use by the consumer. * * If @p fence is not an empty fence, the buffer shall not be overwritten * until the fence signals. @p fence is usually obtained from * dequeueBuffer(). * * @param slot Slot index. * @param fence Fence for the canceled buffer. * @return status Status of the call. */ cancelBuffer( int32_t slot, Fence fence ) generates ( Status status ); /** * Retrieves information for this surface. * * @param what What to query. @p what must be one of the values in * +llndk libnativewindow#ANativeWindowQuery. * @return status Status of the call. * @return value The value queried. The set of possible values depends on * the value of @p what. * * @sa +llndk libnativewindow#ANativeWindowQuery. */ query( int32_t what ) generates ( int32_t result, int32_t value ); /** * Attempts to connect the client as a producer of the buffer queue. * This method must be called before any other methods in this interface. * * If the buffer queue does not have a consumer ready (connected), the * return @p status shall be `NO_INIT`. * * If any of the following conditions hold, the error code `BAD_VALUE` shall * be reported in @p status: * - The producer is already connected. * - The number of available slots cannot be adjusted to accommodate the * supplied value of @p producerControlledByApp. * * @param listener An optional callback object that can be provided if the * client wants to be notified when the consumer releases a buffer back * to the buffer queue. * @param api How the client shall write to buffers. * @param producerControlledByApp `true` if the producer is hosted by an * untrusted process (typically application-forked processes). If both * the producer and the consumer are controlled by app, the buffer queue * shall operate in the asynchronous mode regardless of the async flag * set by setAsyncMode(). * @return status Status of the call. * @return output See #QueueBufferOutput for more information. * * @sa #QueueBufferOutput, disconnect(), setAsyncMode(). */ connect( IProducerListener listener, ConnectionType api, bool producerControlledByApp ) generates ( Status status, QueueBufferOutput output ); /** * Attempts to disconnect the client from the producer end of the buffer * queue. * * Calling this method shall cause any subsequent calls to other * @ref IGraphicBufferProducer methods apart from connect() to fail. * A successful connect() call afterwards may allow other methods to succeed * again. * * Disconnecting from an abandoned buffer queue is legal and is considered a * no-op. * * @param api The type of connection to disconnect. Supplying the value of * `CURRENTLY_CONNECTED` to @p api has the same effect as supplying the * current connection type. If the producer end is not connected, * supplying `CURRENTLY_CONNECTED` shall result in a successful no-op * call. * @return status Status of the call. * * @sa connect(). */ disconnect( ConnectionType api ) generates ( Status status ); /** * Allocates buffers based on the given dimensions, format and usage. * * This function shall allocate up to the maximum number of buffers * permitted by the current buffer queue configuration. It shall 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. * * A value of 0 in @p width, @p height or @p format indicates that the * buffer queue can pick the default value. * * @param width Width of buffers to allocate. * @param height Height of buffers to allocate. * @param format Format of buffers to allocate. * @param usage Usage of bufferes to allocate. * @return status Status of the call. */ allocateBuffers( uint32_t width, uint32_t height, uint32_t format, uint64_t usage ) 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 shall * 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() shall block or return an * error. * * @param allow Whether to allow new buffers to be allocated in * dequeueBuffer(). * @return status Status of the call. */ allowAllocation( bool allow ) generates ( Status status ); /** * Sets the current generation number of the buffer queue. * * This generation number shall be inserted into any buffers allocated by the * buffer queue, and any attempts to attach a buffer with a different * generation number shall fail. Buffers already in the queue are not * affected and shall retain their current generation number. The generation * number defaults to 0, i.e., buffers allocated before the first call to * setGenerationNumber() shall be given 0 as their generation numbers. * * @param generationNumber New generation number. The client must make sure * that @p generationNumber is different from the previous generation * number if it wants to deprecate old buffers. * @return status Status of the call. */ setGenerationNumber( uint32_t generationNumber ) generates ( Status status ); /** * Sets how long dequeueBuffer() shall wait for a buffer to become available * before returning an error `TIMED_OUT`. * * This timeout also affects the attachBuffer() call, which shall block if * there is not a free slot available into which the attached buffer can be * placed. * * By default, the buffer queue shall wait forever, which is equivalent to * setting @p timeoutNs equal to any negative number (such as `-1`). If * @p timeoutNs is non-negative, setDequeueTimeout() shall disable * non-blocking mode and its corresponding spare buffer (which is used to * ensure a buffer is always available). * * Changing the dequeue timeout may affect the number of buffers. (See * setAsyncMode().) If the adjustment to the number of buffers inside the * buffer queue is not feasible, @p status shall be set to `BAD_VALUE`. * * @param timeoutNs Amount of time dequeueBuffer() is allowed to block * before returning `TIMED_OUT`. If @p timeoutNs is negative, * dequeueBuffer() shall not be able to return `TIMED_OUT`. Instead, it * may block forever or return `WOULD_BLOCK`. * @return status Status of the call. * * @sa dequeueBuffer(), setAsyncMode(), query(). */ setDequeueTimeout( int64_t timeoutNs ) generates ( Status status ); /** * Returns a unique id for this buffer queue. * * @return id System-wide unique id of the buffer queue. */ getUniqueId( ) generates ( uint64_t id ); /** * Returns the name of the connected consumer. * * \note This is used for debugging only. * * @return name Name of the consumer. */ getConsumerName( ) generates ( string name ); };