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     explicit 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 
releaseBuffer(int buf,uint64_t frameNumber,EGLDisplay display,EGLSyncKHR fence,const sp<Fence> & releaseFence)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 
consumerConnect(const sp<IConsumerListener> & consumer,bool controlledByApp)165     virtual status_t consumerConnect(const sp<IConsumerListener>& consumer,
166             bool controlledByApp) {
167         return connect(consumer, controlledByApp);
168     }
169 
consumerDisconnect()170     virtual status_t consumerDisconnect() { return disconnect(); }
171 
172     // End functions required for backwards compatibility
173 
174     // Value used to determine if present time is valid.
175     constexpr static int MAX_REASONABLE_NSEC = 1'000'000'000ULL; // 1 second
176 
177 private:
178     sp<BufferQueueCore> mCore;
179 
180     // This references mCore->mSlots. Lock mCore->mMutex while accessing.
181     BufferQueueDefs::SlotsType& mSlots;
182 
183     // This is a cached copy of the name stored in the BufferQueueCore.
184     // It's updated during setConsumerName.
185     String8 mConsumerName;
186 
187 }; // class BufferQueueConsumer
188 
189 } // namespace android
190 
191 #endif
192