xref: /hardware/interfaces/graphics/bufferqueue/1.0/IGraphicBufferProducer.hal

/*
 * 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<FrameEventsDelta> 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 <window.h>. */
        int32_t scalingMode;
        /** A set of flags from NATIVE_WINDOW_TRANSFORM_* in <window.h>. */
        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 <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).
     */
    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<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.
     */
    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 <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
     */
    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 <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.
     */
    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 <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
     */
    disconnect(
            int32_t api,
            DisconnectMode mode /** = DisconnectMode::API */
        ) 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
        );

};