/* * Copyright (C) 2017 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@1.0; import android.hardware.media@1.0::Fence; import android.hardware.media@1.0::AnwBuffer; import android.hardware.media@1.0::Rect; import android.hardware.media@1.0::Region; import android.hardware.graphics.common@1.0::Dataspace; import android.hardware.graphics.common@1.0::PixelFormat; import IProducerListener; /** * Ref: frameworks/native/include/gui/IGraphicBufferProducer.h: * IGraphicBufferProducer * This is a wrapper/wrapped HAL interface for the actual binder interface. */ interface IGraphicBufferProducer { /** * Type for return values of functions in IGraphicBufferProducer. */ typedef int32_t Status; /** * Ref: frameworks/native/include/ui/FenceTime.h: FenceTime::Snapshot * * An atomic snapshot of the FenceTime that is flattenable. */ struct FenceTimeSnapshot { enum State : int32_t { EMPTY, FENCE, SIGNAL_TIME, }; State state; Fence fence; int64_t signalTimeNs; }; /** * 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. */ 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: CompositorTiming * * The most recent compositor timing info sent from consumer to producer * through a HIDL interface. */ struct CompositorTiming { int64_t deadlineNs; int64_t intervalNs; int64_t presentLatencyNs; }; /** * Ref: frameworks/native/include/gui/FrameTimestamp.h: FrameEventHistoryDelta * * A collection of updates from consumer to producer that can be sent * through a HIDL interface. */ struct FrameEventHistoryDelta { vec deltas; CompositorTiming compositorTiming; }; /** * Modes for disconnection. */ enum DisconnectMode : int32_t { /** Disconnect only the specified API. */ API, /** Disconnect any API originally connected from the process calling * disconnect. */ ALL_LOCAL }; struct QueueBufferInput { /** A monotonically increasing value in nanoseconds. */ int64_t timestamp; /** Whether the timestamp was synthesized at queue time. */ int32_t isAutoTimestamp; /** Description of the contents, interpretation depends on format. */ Dataspace dataSpace; /** A crop rectangle that's used as a hint to the consumer. */ Rect crop; /** A set of flags from NATIVE_WINDOW_SCALING_* in . */ int32_t scalingMode; /** A set of flags from NATIVE_WINDOW_TRANSFORM_* in . */ uint32_t transform; /** The sticky transform set in Surface (only used by the LEGACY camera * mode). */ uint32_t stickyTransform; /** A fence that the consumer must wait on before reading the buffer; * set this to Fence::NO_FENCE if the buffer is ready immediately. */ Fence fence; Region surfaceDamage; /** Whether or not the latest frame timestamps should be retrieved from * the consumer. */ bool getFrameTimestamps; }; struct QueueBufferOutput { uint32_t width; uint32_t height; uint32_t transformHint; uint32_t numPendingBuffers; uint64_t nextFrameNumber; bool bufferReplaced; FrameEventHistoryDelta frameTimestamps; }; /** * 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 */ requestBuffer( int32_t slot ) generates ( Status status, AnwBuffer buffer ); /** * 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. */ setMaxDequeuedBufferCount( int32_t maxDequeuedBuffers ) 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. */ setAsyncMode( bool async ) generates ( Status status ); /** * 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 , 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). */ dequeueBuffer( uint32_t width, uint32_t height, PixelFormat format, uint32_t usage, bool getFrameTimestamps ) generates ( Status status, int32_t slot, Fence fence, FrameEventHistoryDelta outTimestamps ); /** * 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 (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. */ detachBuffer( int32_t slot ) generates ( Status status ); /** * 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. */ detachNextBuffer( ) generates ( Status status, AnwBuffer buffer, Fence fence ); /** * 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. */ attachBuffer( AnwBuffer buffer ) generates ( Status status, int32_t slot ); /** * 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 */ queueBuffer( int32_t slot, QueueBufferInput input ) generates ( Status status, QueueBufferOutput output ); /** * 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 */ cancelBuffer( int32_t slot, Fence fence ) generates ( Status status ); /** * query retrieves some information for this surface * 'what' tokens allowed are that of NATIVE_WINDOW_* in * * 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 */ query( int32_t what ) generates ( int32_t result, int32_t value ); /** * 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 * * 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. */ connect( IProducerListener listener, int32_t api, bool producerControlledByApp ) generates ( Status status, QueueBufferOutput output ); /** * 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 * * 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 */ disconnect( int32_t api, DisconnectMode mode ) 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. */ setSidebandStream( handle stream ) generates ( Status status ); /** * 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. */ allocateBuffers( uint32_t width, uint32_t height, PixelFormat format, uint32_t usage ); /** * 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. */ allowAllocation( bool allow ) 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. */ setGenerationNumber( uint32_t generationNumber ) generates ( Status status ); /** * Returns the name of the connected consumer. */ getConsumerName( ) generates ( string name ); /** * 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. */ setSharedBufferMode( bool sharedBufferMode ) 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. */ setAutoRefresh( bool autoRefresh ) 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. */ setDequeueTimeout( int64_t timeoutNs ) generates ( Status status ); /** * 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. */ getLastQueuedBuffer( ) generates ( Status status, AnwBuffer buffer, Fence fence, float[16] transformMatrix ); /** * Gets the frame events that haven't already been retrieved. */ getFrameTimestamps( ) generates ( FrameEventHistoryDelta timeStamps ); /** * Returns a unique id for this BufferQueue. */ getUniqueId( ) generates ( Status status, uint64_t outId ); };