include/gui/BufferQueueConsumer.h

   1 /*
   2  * Copyright 2014 The Android Open Source Project
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef ANDROID_GUI_BUFFERQUEUECONSUMER_H
  18 #define ANDROID_GUI_BUFFERQUEUECONSUMER_H
  19
  20 #include <EGL/egl.h>
  21 #include <EGL/eglext.h>
  22
  23 #include <gui/BufferQueueDefs.h>
  24 #include <gui/IGraphicBufferConsumer.h>
  25 #include <utils/String8.h>
  26
  27 namespace android {
  28
  29 class BufferQueueCore;
  30
  31 class BufferQueueConsumer : public BnGraphicBufferConsumer {
  32
  33 public:
  34     BufferQueueConsumer(const sp<BufferQueueCore>& core);
  35     ~BufferQueueConsumer() override;
  36
  37     // acquireBuffer attempts to acquire ownership of the next pending buffer in
  38     // the BufferQueue. If no buffer is pending then it returns
  39     // NO_BUFFER_AVAILABLE. If a buffer is successfully acquired, the
  40     // information about the buffer is returned in BufferItem.  If the buffer
  41     // returned had previously been acquired then the BufferItem::mGraphicBuffer
  42     // field of buffer is set to NULL and it is assumed that the consumer still
  43     // holds a reference to the buffer.
  44     //
  45     // If expectedPresent is nonzero, it indicates the time when the buffer
  46     // will be displayed on screen. If the buffer's timestamp is farther in the
  47     // future, the buffer won't be acquired, and PRESENT_LATER will be
  48     // returned.  The presentation time is in nanoseconds, and the time base
  49     // is CLOCK_MONOTONIC.
  50     virtual status_t acquireBuffer(BufferItem* outBuffer,
  51             nsecs_t expectedPresent, uint64_t maxFrameNumber = 0) override;
  52
  53     // See IGraphicBufferConsumer::detachBuffer
  54     virtual status_t detachBuffer(int slot);
  55
  56     // See IGraphicBufferConsumer::attachBuffer
  57     virtual status_t attachBuffer(int* slot, const sp<GraphicBuffer>& buffer);
  58
  59     // releaseBuffer releases a buffer slot from the consumer back to the
  60     // BufferQueue.  This may be done while the buffer's contents are still
  61     // being accessed.  The fence will signal when the buffer is no longer
  62     // in use. frameNumber is used to indentify the exact buffer returned.
  63     //
  64     // If releaseBuffer returns STALE_BUFFER_SLOT, then the consumer must free
  65     // any references to the just-released buffer that it might have, as if it
  66     // had received a onBuffersReleased() call with a mask set for the released
  67     // buffer.
  68     //
  69     // Note that the dependencies on EGL will be removed once we switch to using
  70     // the Android HW Sync HAL.
  71     virtual status_t releaseBuffer(int slot, uint64_t frameNumber,
  72             const sp<Fence>& releaseFence, EGLDisplay display,
  73             EGLSyncKHR fence);
  74
  75     // connect connects a consumer to the BufferQueue.  Only one
  76     // consumer may be connected, and when that consumer disconnects the
  77     // BufferQueue is placed into the "abandoned" state, causing most
  78     // interactions with the BufferQueue by the producer to fail.
  79     // controlledByApp indicates whether the consumer is controlled by
  80     // the application.
  81     //
  82     // consumerListener may not be NULL.
  83     virtual status_t connect(const sp<IConsumerListener>& consumerListener,
  84             bool controlledByApp);
  85
  86     // disconnect disconnects a consumer from the BufferQueue. All
  87     // buffers will be freed and the BufferQueue is placed in the "abandoned"
  88     // state, causing most interactions with the BufferQueue by the producer to
  89     // fail.
  90     virtual status_t disconnect();
  91
  92     // getReleasedBuffers sets the value pointed to by outSlotMask to a bit mask
  93     // indicating which buffer slots have been released by the BufferQueue
  94     // but have not yet been released by the consumer.
  95     //
  96     // This should be called from the onBuffersReleased() callback.
  97     virtual status_t getReleasedBuffers(uint64_t* outSlotMask);
  98
  99     // setDefaultBufferSize is used to set the size of buffers returned by
 100     // dequeueBuffer when a width and height of zero is requested.  Default
 101     // is 1x1.
 102     virtual status_t setDefaultBufferSize(uint32_t width, uint32_t height);
 103
 104     // see IGraphicBufferConsumer::setMaxBufferCount
 105     virtual status_t setMaxBufferCount(int bufferCount);
 106
 107     // setMaxAcquiredBufferCount sets the maximum number of buffers that can
 108     // be acquired by the consumer at one time (default 1).  This call will
 109     // fail if a producer is connected to the BufferQueue.
 110     virtual status_t setMaxAcquiredBufferCount(int maxAcquiredBuffers);
 111
 112     // setConsumerName sets the name used in logging
 113     status_t setConsumerName(const String8& name) override;
 114
 115     // setDefaultBufferFormat allows the BufferQueue to create
 116     // GraphicBuffers of a defaultFormat if no format is specified
 117     // in dequeueBuffer. The initial default is HAL_PIXEL_FORMAT_RGBA_8888.
 118     virtual status_t setDefaultBufferFormat(PixelFormat defaultFormat);
 119
 120     // setDefaultBufferDataSpace allows the BufferQueue to create
 121     // GraphicBuffers of a defaultDataSpace if no data space is specified
 122     // in queueBuffer.
 123     // The initial default is HAL_DATASPACE_UNKNOWN
 124     virtual status_t setDefaultBufferDataSpace(android_dataspace defaultDataSpace);
 125
 126     // setConsumerUsageBits will turn on additional usage bits for dequeueBuffer.
 127     // These are merged with the bits passed to dequeueBuffer.  The values are
 128     // enumerated in gralloc.h, e.g. GRALLOC_USAGE_HW_RENDER; the default is 0.
 129     virtual status_t setConsumerUsageBits(uint64_t usage) override;
 130
 131     // setConsumerIsProtected will turn on an internal bit that indicates whether
 132     // the consumer can handle protected gralloc buffers (i.e. with
 133     // GRALLOC_USAGE_PROTECTED set). IGraphicBufferProducer can query this
 134     // capability using NATIVE_WINDOW_CONSUMER_IS_PROTECTED.
 135     virtual status_t setConsumerIsProtected(bool isProtected);
 136
 137     // setTransformHint bakes in rotation to buffers so overlays can be used.
 138     // The values are enumerated in window.h, e.g.
 139     // NATIVE_WINDOW_TRANSFORM_ROT_90.  The default is 0 (no transform).
 140     virtual status_t setTransformHint(uint32_t hint);
 141
 142     // Retrieve the sideband buffer stream, if any.
 143     status_t getSidebandStream(sp<NativeHandle>* outStream) const override;
 144
 145     // See IGraphicBufferConsumer::getOccupancyHistory
 146     virtual status_t getOccupancyHistory(bool forceFlush,
 147             std::vector<OccupancyTracker::Segment>* outHistory) override;
 148
 149     // See IGraphicBufferConsumer::discardFreeBuffers
 150     virtual status_t discardFreeBuffers() override;
 151
 152     // dump our state in a String
 153     status_t dumpState(const String8& prefix, String8* outResult) const override;
 154
 155     // Functions required for backwards compatibility.
 156     // These will be modified/renamed in IGraphicBufferConsumer and will be
 157     // removed from this class at that time. See b/13306289.
 158
 159     virtual status_t releaseBuffer(int buf, uint64_t frameNumber,
 160             EGLDisplay display, EGLSyncKHR fence,
 161             const sp<Fence>& releaseFence) {
 162         return releaseBuffer(buf, frameNumber, releaseFence, display, fence);
 163     }
 164
 165     virtual status_t consumerConnect(const sp<IConsumerListener>& consumer,
 166             bool controlledByApp) {
 167         return connect(consumer, controlledByApp);
 168     }
 169
 170     virtual status_t consumerDisconnect() { return disconnect(); }
 171
 172     // End functions required for backwards compatibility
 173
 174 private:
 175     sp<BufferQueueCore> mCore;
 176
 177     // This references mCore->mSlots. Lock mCore->mMutex while accessing.
 178     BufferQueueDefs::SlotsType& mSlots;
 179
 180     // This is a cached copy of the name stored in the BufferQueueCore.
 181     // It's updated during setConsumerName.
 182     String8 mConsumerName;
 183
 184 }; // class BufferQueueConsumer
 185
 186 } // namespace android
 187
 188 #endif