1/*
2 * Copyright 2017 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/**
18 * @file hardware_buffer.h
19 */
20
21#ifndef ANDROID_HARDWARE_BUFFER_H
22#define ANDROID_HARDWARE_BUFFER_H
23
24#include <inttypes.h>
25
26#include <sys/cdefs.h>
27
28#include <android/rect.h>
29
30__BEGIN_DECLS
31
32/**
33 * Buffer pixel formats.
34 */
35enum {
36    /**
37     * Corresponding formats:
38     *   Vulkan: VK_FORMAT_R8G8B8A8_UNORM
39     *   OpenGL ES: GL_RGBA8
40     */
41    AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM           = 1,
42
43    /**
44     * Corresponding formats:
45     *   Vulkan: VK_FORMAT_R8G8B8A8_UNORM
46     *   OpenGL ES: GL_RGBA8
47     */
48    AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM           = 2,
49
50    /**
51     * Corresponding formats:
52     *   Vulkan: VK_FORMAT_R8G8B8_UNORM
53     *   OpenGL ES: GL_RGB8
54     */
55    AHARDWAREBUFFER_FORMAT_R8G8B8_UNORM             = 3,
56
57    /**
58     * Corresponding formats:
59     *   Vulkan: VK_FORMAT_R5G6B5_UNORM_PACK16
60     *   OpenGL ES: GL_RGB565
61     */
62    AHARDWAREBUFFER_FORMAT_R5G6B5_UNORM             = 4,
63
64    /**
65     * Corresponding formats:
66     *   Vulkan: VK_FORMAT_R16G16B16A16_SFLOAT
67     *   OpenGL ES: GL_RGBA16F
68     */
69    AHARDWAREBUFFER_FORMAT_R16G16B16A16_FLOAT       = 0x16,
70
71    /**
72     * Corresponding formats:
73     *   Vulkan: VK_FORMAT_A2B10G10R10_UNORM_PACK32
74     *   OpenGL ES: GL_RGB10_A2
75     */
76    AHARDWAREBUFFER_FORMAT_R10G10B10A2_UNORM        = 0x2b,
77
78    /**
79     * An opaque binary blob format that must have height 1, with width equal to
80     * the buffer size in bytes.
81     */
82    AHARDWAREBUFFER_FORMAT_BLOB                     = 0x21,
83};
84
85enum {
86    /* The buffer will never be read by the CPU */
87    AHARDWAREBUFFER_USAGE_CPU_READ_NEVER        = 0UL,
88    /* The buffer will sometimes be read by the CPU */
89    AHARDWAREBUFFER_USAGE_CPU_READ_RARELY       = 2UL,
90    /* The buffer will often be read by the CPU */
91    AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN        = 3UL,
92    /* CPU read value mask */
93    AHARDWAREBUFFER_USAGE_CPU_READ_MASK         = 0xFUL,
94
95    /* The buffer will never be written by the CPU */
96    AHARDWAREBUFFER_USAGE_CPU_WRITE_NEVER       = 0UL << 4,
97    /* The buffer will sometimes be written to by the CPU */
98    AHARDWAREBUFFER_USAGE_CPU_WRITE_RARELY      = 2UL << 4,
99    /* The buffer will often be written to by the CPU */
100    AHARDWAREBUFFER_USAGE_CPU_WRITE_OFTEN       = 3UL << 4,
101    /* CPU write value mask */
102    AHARDWAREBUFFER_USAGE_CPU_WRITE_MASK        = 0xFUL << 4,
103
104    /* The buffer will be read from by the GPU */
105    AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE      = 1UL << 8,
106    /* The buffer will be written to by the GPU */
107    AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT       = 1UL << 9,
108    /* The buffer must not be used outside of a protected hardware path */
109    AHARDWAREBUFFER_USAGE_PROTECTED_CONTENT      = 1UL << 14,
110    /* The buffer will be read by a hardware video encoder */
111    AHARDWAREBUFFER_USAGE_VIDEO_ENCODE           = 1UL << 16,
112    /** The buffer will be used for sensor direct data */
113    AHARDWAREBUFFER_USAGE_SENSOR_DIRECT_DATA     = 1UL << 23,
114    /* The buffer will be used as a shader storage or uniform buffer object*/
115    AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER        = 1UL << 24,
116
117    AHARDWAREBUFFER_USAGE_VENDOR_0  = 1ULL << 28,
118    AHARDWAREBUFFER_USAGE_VENDOR_1  = 1ULL << 29,
119    AHARDWAREBUFFER_USAGE_VENDOR_2  = 1ULL << 30,
120    AHARDWAREBUFFER_USAGE_VENDOR_3  = 1ULL << 31,
121    AHARDWAREBUFFER_USAGE_VENDOR_4  = 1ULL << 48,
122    AHARDWAREBUFFER_USAGE_VENDOR_5  = 1ULL << 49,
123    AHARDWAREBUFFER_USAGE_VENDOR_6  = 1ULL << 50,
124    AHARDWAREBUFFER_USAGE_VENDOR_7  = 1ULL << 51,
125    AHARDWAREBUFFER_USAGE_VENDOR_8  = 1ULL << 52,
126    AHARDWAREBUFFER_USAGE_VENDOR_9  = 1ULL << 53,
127    AHARDWAREBUFFER_USAGE_VENDOR_10 = 1ULL << 54,
128    AHARDWAREBUFFER_USAGE_VENDOR_11 = 1ULL << 55,
129    AHARDWAREBUFFER_USAGE_VENDOR_12 = 1ULL << 56,
130    AHARDWAREBUFFER_USAGE_VENDOR_13 = 1ULL << 57,
131    AHARDWAREBUFFER_USAGE_VENDOR_14 = 1ULL << 58,
132    AHARDWAREBUFFER_USAGE_VENDOR_15 = 1ULL << 59,
133    AHARDWAREBUFFER_USAGE_VENDOR_16 = 1ULL << 60,
134    AHARDWAREBUFFER_USAGE_VENDOR_17 = 1ULL << 61,
135    AHARDWAREBUFFER_USAGE_VENDOR_18 = 1ULL << 62,
136    AHARDWAREBUFFER_USAGE_VENDOR_19 = 1ULL << 63,
137};
138
139typedef struct AHardwareBuffer_Desc {
140    uint32_t    width;      // width in pixels
141    uint32_t    height;     // height in pixels
142    uint32_t    layers;     // number of images
143    uint32_t    format;     // One of AHARDWAREBUFFER_FORMAT_*
144    uint64_t    usage;      // Combination of AHARDWAREBUFFER_USAGE_*
145    uint32_t    stride;     // Stride in pixels, ignored for AHardwareBuffer_allocate()
146    uint32_t    rfu0;       // Initialize to zero, reserved for future use
147    uint64_t    rfu1;       // Initialize to zero, reserved for future use
148} AHardwareBuffer_Desc;
149
150typedef struct AHardwareBuffer AHardwareBuffer;
151
152/**
153 * Allocates a buffer that backs an AHardwareBuffer using the passed
154 * AHardwareBuffer_Desc.
155 *
156 * Returns NO_ERROR on success, or an error number of the allocation fails for
157 * any reason.
158 */
159int AHardwareBuffer_allocate(const AHardwareBuffer_Desc* desc,
160        AHardwareBuffer** outBuffer);
161/**
162 * Acquire a reference on the given AHardwareBuffer object.  This prevents the
163 * object from being deleted until the last reference is removed.
164 */
165void AHardwareBuffer_acquire(AHardwareBuffer* buffer);
166
167/**
168 * Remove a reference that was previously acquired with
169 * AHardwareBuffer_acquire().
170 */
171void AHardwareBuffer_release(AHardwareBuffer* buffer);
172
173/**
174 * Return a description of the AHardwareBuffer in the passed
175 * AHardwareBuffer_Desc struct.
176 */
177void AHardwareBuffer_describe(const AHardwareBuffer* buffer,
178        AHardwareBuffer_Desc* outDesc);
179
180/*
181 * Lock the AHardwareBuffer for reading or writing, depending on the usage flags
182 * passed.  This call may block if the hardware needs to finish rendering or if
183 * CPU caches need to be synchronized, or possibly for other implementation-
184 * specific reasons.  If fence is not negative, then it specifies a fence file
185 * descriptor that will be signaled when the buffer is locked, otherwise the
186 * caller will block until the buffer is available.
187 *
188 * If rect is not NULL, the caller promises to modify only data in the area
189 * specified by rect. If rect is NULL, the caller may modify the contents of the
190 * entire buffer.
191 *
192 * The content of the buffer outside of the specified rect is NOT modified
193 * by this call.
194 *
195 * The buffer usage may only specify AHARDWAREBUFFER_USAGE_CPU_*. If set, then
196 * outVirtualAddress is filled with the address of the buffer in virtual memory,
197 * otherwise this function will fail.
198 *
199 * THREADING CONSIDERATIONS:
200 *
201 * It is legal for several different threads to lock a buffer for read access;
202 * none of the threads are blocked.
203 *
204 * Locking a buffer simultaneously for write or read/write is undefined, but
205 * will neither terminate the process nor block the caller; AHardwareBuffer_lock
206 * may return an error or leave the buffer's content into an indeterminate
207 * state.
208 *
209 * Returns NO_ERROR on success, BAD_VALUE if the buffer is NULL or if the usage
210 * flags are not a combination of AHARDWAREBUFFER_USAGE_CPU_*, or an error
211 * number of the lock fails for any reason.
212 */
213int AHardwareBuffer_lock(AHardwareBuffer* buffer, uint64_t usage,
214        int32_t fence, const ARect* rect, void** outVirtualAddress);
215
216/*
217 * Unlock the AHardwareBuffer; must be called after all changes to the buffer
218 * are completed by the caller. If fence is not NULL then it will be set to a
219 * file descriptor that is signaled when all pending work on the buffer is
220 * completed. The caller is responsible for closing the fence when it is no
221 * longer needed.
222 *
223 * Returns NO_ERROR on success, BAD_VALUE if the buffer is NULL, or an error
224 * number of the lock fails for any reason.
225 */
226int AHardwareBuffer_unlock(AHardwareBuffer* buffer, int32_t* fence);
227
228/*
229 * Send the AHardwareBuffer to an AF_UNIX socket.
230 *
231 * Returns NO_ERROR on success, BAD_VALUE if the buffer is NULL, or an error
232 * number of the lock fails for any reason.
233 */
234int AHardwareBuffer_sendHandleToUnixSocket(const AHardwareBuffer* buffer, int socketFd);
235
236/*
237 * Receive the AHardwareBuffer from an AF_UNIX socket.
238 *
239 * Returns NO_ERROR on success, BAD_VALUE if the buffer is NULL, or an error
240 * number of the lock fails for any reason.
241 */
242int AHardwareBuffer_recvHandleFromUnixSocket(int socketFd, AHardwareBuffer** outBuffer);
243
244__END_DECLS
245
246#endif // ANDROID_HARDWARE_BUFFER_H
247