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     // setBufferFreedListener sets the listener object that will be notified
61     // when an old buffer is being freed.
62     void setBufferFreedListener(const wp<BufferFreedListener>& listener);
63 
64     // Gets the next graphics buffer from the producer, filling out the
65     // passed-in BufferItem structure. Returns NO_BUFFER_AVAILABLE if the queue
66     // of buffers is empty, and INVALID_OPERATION if the maximum number of
67     // buffers is already acquired.
68     //
69     // Only a fixed number of buffers can be acquired at a time, determined by
70     // the construction-time bufferCount parameter. If INVALID_OPERATION is
71     // returned by acquireBuffer, then old buffers must be returned to the
72     // queue by calling releaseBuffer before more buffers can be acquired.
73     //
74     // If waitForFence is true, and the acquired BufferItem has a valid fence object,
75     // acquireBuffer will wait on the fence with no timeout before returning.
76     status_t acquireBuffer(BufferItem* item, nsecs_t presentWhen,
77             bool waitForFence = true);
78 
79     // Returns an acquired buffer to the queue, allowing it to be reused. Since
80     // only a fixed number of buffers may be acquired at a time, old buffers
81     // must be released by calling releaseBuffer to ensure new buffers can be
82     // acquired by acquireBuffer. Once a BufferItem is released, the caller must
83     // not access any members of the BufferItem, and should immediately remove
84     // all of its references to the BufferItem itself.
85     status_t releaseBuffer(const BufferItem &item,
86             const sp<Fence>& releaseFence = Fence::NO_FENCE);
87 
88    private:
89     void freeBufferLocked(int slotIndex) override;
90 
91     // mBufferFreedListener is the listener object that will be called when
92     // an old buffer is being freed. If it is not NULL it will be called from
93     // freeBufferLocked.
94     wp<BufferFreedListener> mBufferFreedListener;
95 };
96 
97 } // namespace android
98 
99 #endif // ANDROID_GUI_CPUCONSUMER_H
100