1 /*
2  * Copyright (C) 2007 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_GRAPHIC_BUFFER_H
18 #define ANDROID_GRAPHIC_BUFFER_H
19 
20 #include <stdint.h>
21 #include <sys/types.h>
22 
23 #include <string>
24 
25 #include <ui/ANativeObjectBase.h>
26 #include <ui/PixelFormat.h>
27 #include <ui/Rect.h>
28 #include <utils/Flattenable.h>
29 #include <utils/RefBase.h>
30 
31 #include <nativebase/nativebase.h>
32 
33 #include <hardware/gralloc.h>
34 
35 namespace android {
36 
37 class DetachedBufferHandle;
38 class GraphicBufferMapper;
39 
40 // ===========================================================================
41 // GraphicBuffer
42 // ===========================================================================
43 
44 class GraphicBuffer
45     : public ANativeObjectBase<ANativeWindowBuffer, GraphicBuffer, RefBase>,
46       public Flattenable<GraphicBuffer>
47 {
48     friend class Flattenable<GraphicBuffer>;
49 public:
50 
51     enum {
52         USAGE_SW_READ_NEVER     = GRALLOC_USAGE_SW_READ_NEVER,
53         USAGE_SW_READ_RARELY    = GRALLOC_USAGE_SW_READ_RARELY,
54         USAGE_SW_READ_OFTEN     = GRALLOC_USAGE_SW_READ_OFTEN,
55         USAGE_SW_READ_MASK      = GRALLOC_USAGE_SW_READ_MASK,
56 
57         USAGE_SW_WRITE_NEVER    = GRALLOC_USAGE_SW_WRITE_NEVER,
58         USAGE_SW_WRITE_RARELY   = GRALLOC_USAGE_SW_WRITE_RARELY,
59         USAGE_SW_WRITE_OFTEN    = GRALLOC_USAGE_SW_WRITE_OFTEN,
60         USAGE_SW_WRITE_MASK     = GRALLOC_USAGE_SW_WRITE_MASK,
61 
62         USAGE_SOFTWARE_MASK     = USAGE_SW_READ_MASK|USAGE_SW_WRITE_MASK,
63 
64         USAGE_PROTECTED         = GRALLOC_USAGE_PROTECTED,
65 
66         USAGE_HW_TEXTURE        = GRALLOC_USAGE_HW_TEXTURE,
67         USAGE_HW_RENDER         = GRALLOC_USAGE_HW_RENDER,
68         USAGE_HW_2D             = GRALLOC_USAGE_HW_2D,
69         USAGE_HW_COMPOSER       = GRALLOC_USAGE_HW_COMPOSER,
70         USAGE_HW_VIDEO_ENCODER  = GRALLOC_USAGE_HW_VIDEO_ENCODER,
71         USAGE_HW_MASK           = GRALLOC_USAGE_HW_MASK,
72 
73         USAGE_CURSOR            = GRALLOC_USAGE_CURSOR,
74     };
75 
76     static sp<GraphicBuffer> from(ANativeWindowBuffer *);
77 
78 
79     // Create a GraphicBuffer to be unflatten'ed into or be reallocated.
80     GraphicBuffer();
81 
82     // Create a GraphicBuffer by allocating and managing a buffer internally.
83     // This function is privileged.  See reallocate for details.
84     GraphicBuffer(uint32_t inWidth, uint32_t inHeight, PixelFormat inFormat,
85             uint32_t inLayerCount, uint64_t inUsage,
86             std::string requestorName = "<Unknown>");
87 
88     // Create a GraphicBuffer from an existing handle.
89     enum HandleWrapMethod : uint8_t {
90         // Wrap and use the handle directly.  It assumes the handle has been
91         // registered and never fails.  The handle must have a longer lifetime
92         // than this wrapping GraphicBuffer.
93         //
94         // This can be used when, for example, you want to wrap a handle that
95         // is already managed by another GraphicBuffer.
96         WRAP_HANDLE,
97 
98         // Take ownership of the handle and use it directly.  It assumes the
99         // handle has been registered and never fails.
100         //
101         // This can be used to manage an already registered handle with
102         // GraphicBuffer.
103         TAKE_HANDLE,
104 
105         // Take onwership of an unregistered handle and use it directly.  It
106         // can fail when the buffer does not register.  There is no ownership
107         // transfer on failures.
108         //
109         // This can be used to, for example, create a GraphicBuffer from a
110         // handle returned by Parcel::readNativeHandle.
111         TAKE_UNREGISTERED_HANDLE,
112 
113         // Make a clone of the handle and use the cloned handle.  It can fail
114         // when cloning fails or when the buffer does not register.  There is
115         // never ownership transfer.
116         //
117         // This can be used to create a GraphicBuffer from a handle that
118         // cannot be used directly, such as one from hidl_handle.
119         CLONE_HANDLE,
120     };
121     GraphicBuffer(const native_handle_t* handle, HandleWrapMethod method,
122             uint32_t width, uint32_t height,
123             PixelFormat format, uint32_t layerCount,
124             uint64_t usage, uint32_t stride);
125 
126     // These functions are deprecated because they only take 32 bits of usage
GraphicBuffer(const native_handle_t * handle,HandleWrapMethod method,uint32_t width,uint32_t height,PixelFormat format,uint32_t layerCount,uint32_t usage,uint32_t stride)127     GraphicBuffer(const native_handle_t* handle, HandleWrapMethod method,
128             uint32_t width, uint32_t height,
129             PixelFormat format, uint32_t layerCount,
130             uint32_t usage, uint32_t stride)
131         : GraphicBuffer(handle, method, width, height, format, layerCount,
132                 static_cast<uint64_t>(usage), stride) {}
133     GraphicBuffer(uint32_t inWidth, uint32_t inHeight, PixelFormat inFormat,
134             uint32_t inLayerCount, uint32_t inUsage, uint32_t inStride,
135             native_handle_t* inHandle, bool keepOwnership);
136     GraphicBuffer(uint32_t inWidth, uint32_t inHeight, PixelFormat inFormat,
137             uint32_t inUsage, std::string requestorName = "<Unknown>");
138 
139     // return status
140     status_t initCheck() const;
141 
getWidth()142     uint32_t getWidth() const           { return static_cast<uint32_t>(width); }
getHeight()143     uint32_t getHeight() const          { return static_cast<uint32_t>(height); }
getStride()144     uint32_t getStride() const          { return static_cast<uint32_t>(stride); }
getUsage()145     uint64_t getUsage() const           { return usage; }
getPixelFormat()146     PixelFormat getPixelFormat() const  { return format; }
getLayerCount()147     uint32_t getLayerCount() const      { return static_cast<uint32_t>(layerCount); }
getBounds()148     Rect getBounds() const              { return Rect(width, height); }
getId()149     uint64_t getId() const              { return mId; }
150 
getGenerationNumber()151     uint32_t getGenerationNumber() const { return mGenerationNumber; }
setGenerationNumber(uint32_t generation)152     void setGenerationNumber(uint32_t generation) {
153         mGenerationNumber = generation;
154     }
155 
156     // This function is privileged.  It requires access to the allocator
157     // device or service, which usually involves adding suitable selinux
158     // rules.
159     status_t reallocate(uint32_t inWidth, uint32_t inHeight,
160             PixelFormat inFormat, uint32_t inLayerCount, uint64_t inUsage);
161 
162     bool needsReallocation(uint32_t inWidth, uint32_t inHeight,
163             PixelFormat inFormat, uint32_t inLayerCount, uint64_t inUsage);
164 
165     status_t lock(uint32_t inUsage, void** vaddr);
166     status_t lock(uint32_t inUsage, const Rect& rect, void** vaddr);
167     // For HAL_PIXEL_FORMAT_YCbCr_420_888
168     status_t lockYCbCr(uint32_t inUsage, android_ycbcr *ycbcr);
169     status_t lockYCbCr(uint32_t inUsage, const Rect& rect,
170             android_ycbcr *ycbcr);
171     status_t unlock();
172     status_t lockAsync(uint32_t inUsage, void** vaddr, int fenceFd);
173     status_t lockAsync(uint32_t inUsage, const Rect& rect, void** vaddr,
174             int fenceFd);
175     status_t lockAsync(uint64_t inProducerUsage, uint64_t inConsumerUsage,
176             const Rect& rect, void** vaddr, int fenceFd);
177     status_t lockAsyncYCbCr(uint32_t inUsage, android_ycbcr *ycbcr,
178             int fenceFd);
179     status_t lockAsyncYCbCr(uint32_t inUsage, const Rect& rect,
180             android_ycbcr *ycbcr, int fenceFd);
181     status_t unlockAsync(int *fenceFd);
182 
183     ANativeWindowBuffer* getNativeBuffer() const;
184 
185     // for debugging
186     static void dumpAllocationsToSystemLog();
187 
188     // Flattenable protocol
189     size_t getFlattenedSize() const;
190     size_t getFdCount() const;
191     status_t flatten(void*& buffer, size_t& size, int*& fds, size_t& count) const;
192     status_t unflatten(void const*& buffer, size_t& size, int const*& fds, size_t& count);
193 
194     // Sets and takes DetachedBuffer. Should only be called from BufferHub.
195     bool isDetachedBuffer() const;
196     status_t setDetachedBufferHandle(std::unique_ptr<DetachedBufferHandle> detachedBuffer);
197     std::unique_ptr<DetachedBufferHandle> takeDetachedBufferHandle();
198 
199 private:
200     ~GraphicBuffer();
201 
202     enum {
203         ownNone   = 0,
204         ownHandle = 1,
205         ownData   = 2,
206     };
207 
getBufferMapper()208     inline const GraphicBufferMapper& getBufferMapper() const {
209         return mBufferMapper;
210     }
getBufferMapper()211     inline GraphicBufferMapper& getBufferMapper() {
212         return mBufferMapper;
213     }
214     uint8_t mOwner;
215 
216 private:
217     friend class Surface;
218     friend class BpSurface;
219     friend class BnSurface;
220     friend class LightRefBase<GraphicBuffer>;
221     GraphicBuffer(const GraphicBuffer& rhs);
222     GraphicBuffer& operator = (const GraphicBuffer& rhs);
223     const GraphicBuffer& operator = (const GraphicBuffer& rhs) const;
224 
225     status_t initWithSize(uint32_t inWidth, uint32_t inHeight,
226             PixelFormat inFormat, uint32_t inLayerCount,
227             uint64_t inUsage, std::string requestorName);
228 
229     status_t initWithHandle(const native_handle_t* handle,
230             HandleWrapMethod method, uint32_t width, uint32_t height,
231             PixelFormat format, uint32_t layerCount,
232             uint64_t usage, uint32_t stride);
233 
234     void free_handle();
235 
236     GraphicBufferMapper& mBufferMapper;
237     ssize_t mInitCheck;
238 
239     // numbers of fds/ints in native_handle_t to flatten
240     uint32_t mTransportNumFds;
241     uint32_t mTransportNumInts;
242 
243     uint64_t mId;
244 
245     // Stores the generation number of this buffer. If this number does not
246     // match the BufferQueue's internal generation number (set through
247     // IGBP::setGenerationNumber), attempts to attach the buffer will fail.
248     uint32_t mGenerationNumber;
249 
250     // Stores a BufferHub handle that can be used to re-attach this GraphicBuffer back into a
251     // BufferHub producer/consumer set. In terms of GraphicBuffer's relationship with BufferHub,
252     // there are three different modes:
253     // 1. Legacy mode: GraphicBuffer is not backed by BufferHub and mDetachedBufferHandle must be
254     //    invalid.
255     // 2. Detached mode: GraphicBuffer is backed by BufferHub, but not part of a producer/consumer
256     //    set. In this mode, mDetachedBufferHandle must be valid.
257     // 3. Attached mode: GraphicBuffer is backed by BufferHub and it's part of a producer/consumer
258     //    set. In this mode, mDetachedBufferHandle must be invalid.
259     std::unique_ptr<DetachedBufferHandle> mDetachedBufferHandle;
260 };
261 
262 }; // namespace android
263 
264 #endif // ANDROID_GRAPHIC_BUFFER_H
265