Home | History | Annotate | Download | only in gui 
      1 /*
      2  * Copyright (C) 2012 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_BUFFERITEMCONSUMER_H
     18 #define ANDROID_GUI_BUFFERITEMCONSUMER_H
     19 
     20 #include <gui/ConsumerBase.h>
     21 #include <gui/BufferQueue.h>
     22 
     23 #define ANDROID_GRAPHICS_BUFFERITEMCONSUMER_JNI_ID "mBufferItemConsumer"
     24 
     25 namespace android {
     26 
     27 class String8;
     28 
     29 /**
     30  * BufferItemConsumer is a BufferQueue consumer endpoint that allows clients
     31  * access to the whole BufferItem entry from BufferQueue. Multiple buffers may
     32  * be acquired at once, to be used concurrently by the client. This consumer can
     33  * operate either in synchronous or asynchronous mode.
     34  */
     35 class BufferItemConsumer: public ConsumerBase
     36 {
     37   public:
     38     typedef ConsumerBase::FrameAvailableListener FrameAvailableListener;
     39 
     40     struct BufferFreedListener : public virtual RefBase {
     41         virtual void onBufferFreed(const wp<GraphicBuffer>& graphicBuffer) = 0;
     42     };
     43 
     44     enum { DEFAULT_MAX_BUFFERS = -1 };
     45     enum { INVALID_BUFFER_SLOT = BufferQueue::INVALID_BUFFER_SLOT };
     46     enum { NO_BUFFER_AVAILABLE = BufferQueue::NO_BUFFER_AVAILABLE };
     47 
     48     // Create a new buffer item consumer. The consumerUsage parameter determines
     49     // the consumer usage flags passed to the graphics allocator. The
     50     // bufferCount parameter specifies how many buffers can be locked for user
     51     // access at the same time.
     52     // controlledByApp tells whether this consumer is controlled by the
     53     // application.
     54     BufferItemConsumer(const sp<IGraphicBufferConsumer>& consumer,
     55             uint64_t consumerUsage, int bufferCount = DEFAULT_MAX_BUFFERS,
     56             bool controlledByApp = false);
     57 
     58     ~BufferItemConsumer() override;
     59 
     60     // set the name of the BufferItemConsumer that will be used to identify it in
     61     // log messages.
     62     void setName(const String8& name);
     63 
     64     // setBufferFreedListener sets the listener object that will be notified
     65     // when an old buffer is being freed.
     66     void setBufferFreedListener(const wp<BufferFreedListener>& listener);
     67 
     68     // Gets the next graphics buffer from the producer, filling out the
     69     // passed-in BufferItem structure. Returns NO_BUFFER_AVAILABLE if the queue
     70     // of buffers is empty, and INVALID_OPERATION if the maximum number of
     71     // buffers is already acquired.
     72     //
     73     // Only a fixed number of buffers can be acquired at a time, determined by
     74     // the construction-time bufferCount parameter. If INVALID_OPERATION is
     75     // returned by acquireBuffer, then old buffers must be returned to the
     76     // queue by calling releaseBuffer before more buffers can be acquired.
     77     //
     78     // If waitForFence is true, and the acquired BufferItem has a valid fence object,
     79     // acquireBuffer will wait on the fence with no timeout before returning.
     80     status_t acquireBuffer(BufferItem* item, nsecs_t presentWhen,
     81             bool waitForFence = true);
     82 
     83     // Returns an acquired buffer to the queue, allowing it to be reused. Since
     84     // only a fixed number of buffers may be acquired at a time, old buffers
     85     // must be released by calling releaseBuffer to ensure new buffers can be
     86     // acquired by acquireBuffer. Once a BufferItem is released, the caller must
     87     // not access any members of the BufferItem, and should immediately remove
     88     // all of its references to the BufferItem itself.
     89     status_t releaseBuffer(const BufferItem &item,
     90             const sp<Fence>& releaseFence = Fence::NO_FENCE);
     91 
     92    private:
     93     void freeBufferLocked(int slotIndex) override;
     94 
     95     // mBufferFreedListener is the listener object that will be called when
     96     // an old buffer is being freed. If it is not NULL it will be called from
     97     // freeBufferLocked.
     98     wp<BufferFreedListener> mBufferFreedListener;
     99 };
    100 
    101 } // namespace android
    102 
    103 #endif // ANDROID_GUI_CPUCONSUMER_H
    104