include/gui/IGraphicBufferConsumer.h

   1 /*
   2  * Copyright (C) 2013 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_IGRAPHICBUFFERCONSUMER_H
  18 #define ANDROID_GUI_IGRAPHICBUFFERCONSUMER_H
  19
  20 #include <stdint.h>
  21 #include <sys/types.h>
  22
  23 #include <utils/Errors.h>
  24 #include <utils/RefBase.h>
  25 #include <utils/Timers.h>
  26
  27 #include <binder/IInterface.h>
  28 #include <ui/Rect.h>
  29
  30 namespace android {
  31 // ----------------------------------------------------------------------------
  32
  33 class IConsumerListener;
  34 class GraphicBuffer;
  35 class Fence;
  36
  37 class IGraphicBufferConsumer : public IInterface {
  38
  39 public:
  40
  41     // public facing structure for BufferSlot
  42     class BufferItem : public Flattenable<BufferItem> {
  43         friend class Flattenable<BufferItem>;
  44         size_t getPodSize() const;
  45         size_t getFlattenedSize() const;
  46         size_t getFdCount() const;
  47         status_t flatten(void*& buffer, size_t& size, int*& fds, size_t& count) const;
  48         status_t unflatten(void const*& buffer, size_t& size, int const*& fds, size_t& count);
  49
  50     public:
  51         enum { INVALID_BUFFER_SLOT = -1 };
  52         BufferItem();
  53
  54         // mGraphicBuffer points to the buffer allocated for this slot, or is NULL
  55         // if the buffer in this slot has been acquired in the past (see
  56         // BufferSlot.mAcquireCalled).
  57         sp<GraphicBuffer> mGraphicBuffer;
  58
  59         // mFence is a fence that will signal when the buffer is idle.
  60         sp<Fence> mFence;
  61
  62         // mCrop is the current crop rectangle for this buffer slot.
  63         Rect mCrop;
  64
  65         // mTransform is the current transform flags for this buffer slot.
  66         uint32_t mTransform;
  67
  68         // mScalingMode is the current scaling mode for this buffer slot.
  69         uint32_t mScalingMode;
  70
  71         // mTimestamp is the current timestamp for this buffer slot. This gets
  72         // to set by queueBuffer each time this slot is queued.
  73         int64_t mTimestamp;
  74
  75         // mFrameNumber is the number of the queued frame for this slot.
  76         uint64_t mFrameNumber;
  77
  78         // mBuf is the slot index of this buffer
  79         int mBuf;
  80
  81         // mIsDroppable whether this buffer was queued with the
  82         // property that it can be replaced by a new buffer for the purpose of
  83         // making sure dequeueBuffer() won't block.
  84         // i.e.: was the BufferQueue in "mDequeueBufferCannotBlock" when this buffer
  85         // was queued.
  86         bool mIsDroppable;
  87
  88         // Indicates whether this buffer has been seen by a consumer yet
  89         bool mAcquireCalled;
  90     };
  91
  92
  93     // acquireBuffer attempts to acquire ownership of the next pending buffer in
  94     // the BufferQueue.  If no buffer is pending then it returns -EINVAL.  If a
  95     // buffer is successfully acquired, the information about the buffer is
  96     // returned in BufferItem.  If the buffer returned had previously been
  97     // acquired then the BufferItem::mGraphicBuffer field of buffer is set to
  98     // NULL and it is assumed that the consumer still holds a reference to the
  99     // buffer.
 100     //
 101     // If presentWhen is nonzero, it indicates the time when the buffer will
 102     // be displayed on screen.  If the buffer's timestamp is farther in the
 103     // future, the buffer won't be acquired, and PRESENT_LATER will be
 104     // returned.  The presentation time is in nanoseconds, and the time base
 105     // is CLOCK_MONOTONIC.
 106     virtual status_t acquireBuffer(BufferItem *buffer, nsecs_t presentWhen) = 0;
 107
 108     // releaseBuffer releases a buffer slot from the consumer back to the
 109     // BufferQueue.  This may be done while the buffer's contents are still
 110     // being accessed.  The fence will signal when the buffer is no longer
 111     // in use. frameNumber is used to indentify the exact buffer returned.
 112     //
 113     // If releaseBuffer returns STALE_BUFFER_SLOT, then the consumer must free
 114     // any references to the just-released buffer that it might have, as if it
 115     // had received a onBuffersReleased() call with a mask set for the released
 116     // buffer.
 117     //
 118     // Note that the dependencies on EGL will be removed once we switch to using
 119     // the Android HW Sync HAL.
 120     virtual status_t releaseBuffer(int buf, uint64_t frameNumber,
 121             EGLDisplay display, EGLSyncKHR fence,
 122             const sp<Fence>& releaseFence) = 0;
 123
 124     // consumerConnect connects a consumer to the BufferQueue.  Only one
 125     // consumer may be connected, and when that consumer disconnects the
 126     // BufferQueue is placed into the "abandoned" state, causing most
 127     // interactions with the BufferQueue by the producer to fail.
 128     // controlledByApp indicates whether the consumer is controlled by
 129     // the application.
 130     //
 131     // consumer may not be NULL.
 132     virtual status_t consumerConnect(const sp<IConsumerListener>& consumer, bool controlledByApp) = 0;
 133
 134     // consumerDisconnect disconnects a consumer from the BufferQueue. All
 135     // buffers will be freed and the BufferQueue is placed in the "abandoned"
 136     // state, causing most interactions with the BufferQueue by the producer to
 137     // fail.
 138     virtual status_t consumerDisconnect() = 0;
 139
 140     // getReleasedBuffers sets the value pointed to by slotMask to a bit mask
 141     // indicating which buffer slots have been released by the BufferQueue
 142     // but have not yet been released by the consumer.
 143     //
 144     // This should be called from the onBuffersReleased() callback.
 145     virtual status_t getReleasedBuffers(uint32_t* slotMask) = 0;
 146
 147     // setDefaultBufferSize is used to set the size of buffers returned by
 148     // dequeueBuffer when a width and height of zero is requested.  Default
 149     // is 1x1.
 150     virtual status_t setDefaultBufferSize(uint32_t w, uint32_t h) = 0;
 151
 152     // setDefaultMaxBufferCount sets the default value for the maximum buffer
 153     // count (the initial default is 2). If the producer has requested a
 154     // buffer count using setBufferCount, the default buffer count will only
 155     // take effect if the producer sets the count back to zero.
 156     //
 157     // The count must be between 2 and NUM_BUFFER_SLOTS, inclusive.
 158     virtual status_t setDefaultMaxBufferCount(int bufferCount) = 0;
 159
 160     // disableAsyncBuffer disables the extra buffer used in async mode
 161     // (when both producer and consumer have set their "isControlledByApp"
 162     // flag) and has dequeueBuffer() return WOULD_BLOCK instead.
 163     //
 164     // This can only be called before consumerConnect().
 165     virtual status_t disableAsyncBuffer() = 0;
 166
 167     // setMaxAcquiredBufferCount sets the maximum number of buffers that can
 168     // be acquired by the consumer at one time (default 1).  This call will
 169     // fail if a producer is connected to the BufferQueue.
 170     virtual status_t setMaxAcquiredBufferCount(int maxAcquiredBuffers) = 0;
 171
 172     // setConsumerName sets the name used in logging
 173     virtual void setConsumerName(const String8& name) = 0;
 174
 175     // setDefaultBufferFormat allows the BufferQueue to create
 176     // GraphicBuffers of a defaultFormat if no format is specified
 177     // in dequeueBuffer.  Formats are enumerated in graphics.h; the
 178     // initial default is HAL_PIXEL_FORMAT_RGBA_8888.
 179     virtual status_t setDefaultBufferFormat(uint32_t defaultFormat) = 0;
 180
 181     // setConsumerUsageBits will turn on additional usage bits for dequeueBuffer.
 182     // These are merged with the bits passed to dequeueBuffer.  The values are
 183     // enumerated in gralloc.h, e.g. GRALLOC_USAGE_HW_RENDER; the default is 0.
 184     virtual status_t setConsumerUsageBits(uint32_t usage) = 0;
 185
 186     // setTransformHint bakes in rotation to buffers so overlays can be used.
 187     // The values are enumerated in window.h, e.g.
 188     // NATIVE_WINDOW_TRANSFORM_ROT_90.  The default is 0 (no transform).
 189     virtual status_t setTransformHint(uint32_t hint) = 0;
 190
 191     // dump state into a string
 192     virtual void dump(String8& result, const char* prefix) const = 0;
 193
 194 public:
 195     DECLARE_META_INTERFACE(GraphicBufferConsumer);
 196 };
 197
 198 // ----------------------------------------------------------------------------
 199
 200 class BnGraphicBufferConsumer : public BnInterface<IGraphicBufferConsumer>
 201 {
 202 public:
 203     virtual status_t    onTransact( uint32_t code,
 204                                     const Parcel& data,
 205                                     Parcel* reply,
 206                                     uint32_t flags = 0);
 207 };
 208
 209 // ----------------------------------------------------------------------------
 210 }; // namespace android
 211
 212 #endif // ANDROID_GUI_IGRAPHICBUFFERCONSUMER_H