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
35namespace android {
36
37class DetachedBufferHandle;
38class GraphicBufferMapper;
39
40// ===========================================================================
41// GraphicBuffer
42// ===========================================================================
43
44class GraphicBuffer
45    : public ANativeObjectBase<ANativeWindowBuffer, GraphicBuffer, RefBase>,
46      public Flattenable<GraphicBuffer>
47{
48    friend class Flattenable<GraphicBuffer>;
49public:
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
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
142    uint32_t getWidth() const           { return static_cast<uint32_t>(width); }
143    uint32_t getHeight() const          { return static_cast<uint32_t>(height); }
144    uint32_t getStride() const          { return static_cast<uint32_t>(stride); }
145    uint64_t getUsage() const           { return usage; }
146    PixelFormat getPixelFormat() const  { return format; }
147    uint32_t getLayerCount() const      { return static_cast<uint32_t>(layerCount); }
148    Rect getBounds() const              { return Rect(width, height); }
149    uint64_t getId() const              { return mId; }
150
151    uint32_t getGenerationNumber() const { return mGenerationNumber; }
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
199private:
200    ~GraphicBuffer();
201
202    enum {
203        ownNone   = 0,
204        ownHandle = 1,
205        ownData   = 2,
206    };
207
208    inline const GraphicBufferMapper& getBufferMapper() const {
209        return mBufferMapper;
210    }
211    inline GraphicBufferMapper& getBufferMapper() {
212        return mBufferMapper;
213    }
214    uint8_t mOwner;
215
216private:
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