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_CPUCONSUMER_H
18 #define ANDROID_GUI_CPUCONSUMER_H
19 
20 #include <system/window.h>
21 
22 #include <gui/ConsumerBase.h>
23 #include <gui/BufferQueue.h>
24 
25 #include <utils/Vector.h>
26 
27 
28 namespace android {
29 
30 class BufferQueue;
31 class GraphicBuffer;
32 class String8;
33 
34 /**
35  * CpuConsumer is a BufferQueue consumer endpoint that allows direct CPU
36  * access to the underlying gralloc buffers provided by BufferQueue. Multiple
37  * buffers may be acquired by it at once, to be used concurrently by the
38  * CpuConsumer owner. Sets gralloc usage flags to be software-read-only.
39  * This queue is synchronous by default.
40  */
41 
42 class CpuConsumer : public ConsumerBase
43 {
44   public:
45     typedef ConsumerBase::FrameAvailableListener FrameAvailableListener;
46 
47     struct LockedBuffer {
48         uint8_t    *data;
49         uint32_t    width;
50         uint32_t    height;
51         PixelFormat format;
52         uint32_t    stride;
53         Rect        crop;
54         uint32_t    transform;
55         uint32_t    scalingMode;
56         int64_t     timestamp;
57         android_dataspace dataSpace;
58         uint64_t    frameNumber;
59         // this is the same as format, except for formats that are compatible with
60         // a flexible format (e.g. HAL_PIXEL_FORMAT_YCbCr_420_888). In the latter
61         // case this contains that flexible format
62         PixelFormat flexFormat;
63         // Values below are only valid when using HAL_PIXEL_FORMAT_YCbCr_420_888
64         // or compatible format, in which case LockedBuffer::data
65         // contains the Y channel, and stride is the Y channel stride. For other
66         // formats, these will all be 0.
67         uint8_t    *dataCb;
68         uint8_t    *dataCr;
69         uint32_t    chromaStride;
70         uint32_t    chromaStep;
71 
LockedBufferLockedBuffer72         LockedBuffer() :
73             data(nullptr),
74             width(0),
75             height(0),
76             format(PIXEL_FORMAT_NONE),
77             stride(0),
78             crop(Rect::EMPTY_RECT),
79             transform(0),
80             scalingMode(NATIVE_WINDOW_SCALING_MODE_FREEZE),
81             timestamp(0),
82             dataSpace(HAL_DATASPACE_UNKNOWN),
83             frameNumber(0),
84             flexFormat(PIXEL_FORMAT_NONE),
85             dataCb(nullptr),
86             dataCr(nullptr),
87             chromaStride(0),
88             chromaStep(0)
89         {}
90     };
91 
92     // Create a new CPU consumer. The maxLockedBuffers parameter specifies
93     // how many buffers can be locked for user access at the same time.
94     CpuConsumer(const sp<IGraphicBufferConsumer>& bq,
95             size_t maxLockedBuffers, bool controlledByApp = false);
96 
97     // Gets the next graphics buffer from the producer and locks it for CPU use,
98     // filling out the passed-in locked buffer structure with the native pointer
99     // and metadata. Returns BAD_VALUE if no new buffer is available, and
100     // NOT_ENOUGH_DATA if the maximum number of buffers is already locked.
101     //
102     // Only a fixed number of buffers can be locked at a time, determined by the
103     // construction-time maxLockedBuffers parameter. If INVALID_OPERATION is
104     // returned by lockNextBuffer, then old buffers must be returned to the queue
105     // by calling unlockBuffer before more buffers can be acquired.
106     status_t lockNextBuffer(LockedBuffer *nativeBuffer);
107 
108     // Returns a locked buffer to the queue, allowing it to be reused. Since
109     // only a fixed number of buffers may be locked at a time, old buffers must
110     // be released by calling unlockBuffer to ensure new buffers can be acquired by
111     // lockNextBuffer.
112     status_t unlockBuffer(const LockedBuffer &nativeBuffer);
113 
114   private:
115     // Maximum number of buffers that can be locked at a time
116     const size_t mMaxLockedBuffers;
117 
118     // Tracking for buffers acquired by the user
119     struct AcquiredBuffer {
120         static constexpr uintptr_t kUnusedId = 0;
121 
122         // Need to track the original mSlot index and the buffer itself because
123         // the mSlot entry may be freed/reused before the acquired buffer is
124         // released.
125         int mSlot;
126         sp<GraphicBuffer> mGraphicBuffer;
127         uintptr_t mLockedBufferId;
128 
AcquiredBufferAcquiredBuffer129         AcquiredBuffer() :
130                 mSlot(BufferQueue::INVALID_BUFFER_SLOT),
131                 mLockedBufferId(kUnusedId) {
132         }
133 
resetAcquiredBuffer134         void reset() {
135             mSlot = BufferQueue::INVALID_BUFFER_SLOT;
136             mGraphicBuffer.clear();
137             mLockedBufferId = kUnusedId;
138         }
139     };
140 
141     size_t findAcquiredBufferLocked(uintptr_t id) const;
142 
143     status_t lockBufferItem(const BufferItem& item, LockedBuffer* outBuffer) const;
144 
145     Vector<AcquiredBuffer> mAcquiredBuffers;
146 
147     // Count of currently locked buffers
148     size_t mCurrentLockedBuffers;
149 };
150 
151 } // namespace android
152 
153 #endif // ANDROID_GUI_CPUCONSUMER_H
154