• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * Copyright (c) 2022 Huawei Device Co., Ltd.
3  * Licensed under the Apache License, Version 2.0 (the "License");
4  * you may not use this file except in compliance with the License.
5  * You may obtain a copy of the License at
6  *
7  *     http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software
10  * distributed under the License is distributed on an "AS IS" BASIS,
11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  * See the License for the specific language governing permissions and
13  * limitations under the License.
14  */
15 
16 /**
17  * @addtogroup OH_NativeBuffer
18  * @{
19  *
20  * @brief Provides the native buffer capability.
21  *
22  * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
23  * @since 9
24  * @version 1.0
25  */
26 
27 /**
28  * @file native_buffer.h
29  *
30  * @brief Defines the functions for obtaining and using a native buffer.
31  *
32  * @kit ArkGraphics2D
33  * @library libnative_buffer.so
34  * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
35  * @since 9
36  * @version 1.0
37  */
38 
39 #ifndef NDK_INCLUDE_NATIVE_BUFFER_H_
40 #define NDK_INCLUDE_NATIVE_BUFFER_H_
41 
42 #include <stdint.h>
43 #include <native_window/external_window.h>
44 #include <native_buffer/buffer_common.h>
45 
46 #ifdef __cplusplus
47 extern "C" {
48 #endif
49 
50 struct OH_NativeBuffer;
51 typedef struct OH_NativeBuffer OH_NativeBuffer;
52 
53 /**
54  * @brief Indicates the usage of a native buffer.
55  *
56  * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
57  * @since 10
58  * @version 1.0
59  */
60 typedef enum OH_NativeBuffer_Usage {
61     NATIVEBUFFER_USAGE_CPU_READ = (1ULL << 0),        /// < CPU read buffer */
62     NATIVEBUFFER_USAGE_CPU_WRITE = (1ULL << 1),       /// < CPU write memory */
63     NATIVEBUFFER_USAGE_MEM_DMA = (1ULL << 3),         /// < Direct memory access (DMA) buffer */
64     /**
65      * MMZ with cache
66      * @since 20
67      */
68     NATIVEBUFFER_USAGE_MEM_MMZ_CACHE = (1ULL << 5),
69     NATIVEBUFFER_USAGE_HW_RENDER = (1ULL << 8),       /// < For GPU write case */
70     NATIVEBUFFER_USAGE_HW_TEXTURE = (1ULL << 9),      /// < For GPU read case */
71     NATIVEBUFFER_USAGE_CPU_READ_OFTEN = (1ULL << 16), /// < Often be mapped for direct CPU reads */
72     NATIVEBUFFER_USAGE_ALIGNMENT_512 = (1ULL << 18),  /// < 512 bytes alignment */
73 } OH_NativeBuffer_Usage;
74 
75 /**
76  * @brief Indicates the format of a native buffer.
77  *
78  * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
79  * @since 10
80  * @version 1.0
81  */
82 typedef enum OH_NativeBuffer_Format {
83     /**
84      * CLUT8 format
85      * @since 12
86      */
87     NATIVEBUFFER_PIXEL_FMT_CLUT8 = 0,
88     /**
89      * CLUT1 format
90      * @since 12
91      */
92     NATIVEBUFFER_PIXEL_FMT_CLUT1,
93     /**
94      * CLUT4 format
95      * @since 12
96      */
97     NATIVEBUFFER_PIXEL_FMT_CLUT4,
98     NATIVEBUFFER_PIXEL_FMT_RGB_565 = 3,               /// < RGB565 format */
99     NATIVEBUFFER_PIXEL_FMT_RGBA_5658,                 /// < RGBA5658 format */
100     NATIVEBUFFER_PIXEL_FMT_RGBX_4444,                 /// < RGBX4444 format */
101     NATIVEBUFFER_PIXEL_FMT_RGBA_4444,                 /// < RGBA4444 format */
102     NATIVEBUFFER_PIXEL_FMT_RGB_444,                   /// < RGB444 format */
103     NATIVEBUFFER_PIXEL_FMT_RGBX_5551,                 /// < RGBX5551 format */
104     NATIVEBUFFER_PIXEL_FMT_RGBA_5551,                 /// < RGBA5551 format */
105     NATIVEBUFFER_PIXEL_FMT_RGB_555,                   /// < RGB555 format */
106     NATIVEBUFFER_PIXEL_FMT_RGBX_8888,                 /// < RGBX8888 format */
107     NATIVEBUFFER_PIXEL_FMT_RGBA_8888,                 /// < RGBA8888 format */
108     NATIVEBUFFER_PIXEL_FMT_RGB_888,                   /// < RGB888 format */
109     NATIVEBUFFER_PIXEL_FMT_BGR_565,                   /// < BGR565 format */
110     NATIVEBUFFER_PIXEL_FMT_BGRX_4444,                 /// < BGRX4444 format */
111     NATIVEBUFFER_PIXEL_FMT_BGRA_4444,                 /// < BGRA4444 format */
112     NATIVEBUFFER_PIXEL_FMT_BGRX_5551,                 /// < BGRX5551 format */
113     NATIVEBUFFER_PIXEL_FMT_BGRA_5551,                 /// < BGRA5551 format */
114     NATIVEBUFFER_PIXEL_FMT_BGRX_8888,                 /// < BGRX8888 format */
115     NATIVEBUFFER_PIXEL_FMT_BGRA_8888,                 /// < BGRA8888 format */
116     /**
117      * YUV422 interleaved format
118      * @since 12
119      */
120     NATIVEBUFFER_PIXEL_FMT_YUV_422_I,
121     /**
122      * YCBCR422 semi-planar format
123      * @since 12
124      */
125     NATIVEBUFFER_PIXEL_FMT_YCBCR_422_SP,
126     /**
127      * YCRCB422 semi-planar format
128      * @since 12
129      */
130     NATIVEBUFFER_PIXEL_FMT_YCRCB_422_SP,
131     /**
132      * YCBCR420 semi-planar format
133      * @since 12
134      */
135     NATIVEBUFFER_PIXEL_FMT_YCBCR_420_SP,
136     /**
137      * YCRCB420 semi-planar format
138      * @since 12
139      */
140     NATIVEBUFFER_PIXEL_FMT_YCRCB_420_SP,
141     /**
142      * YCBCR422 planar format
143      * @since 12
144      */
145     NATIVEBUFFER_PIXEL_FMT_YCBCR_422_P,
146     /**
147      * YCRCB422 planar format
148      * @since 12
149      */
150     NATIVEBUFFER_PIXEL_FMT_YCRCB_422_P,
151     /**
152      * YCBCR420 planar format
153      * @since 12
154      */
155     NATIVEBUFFER_PIXEL_FMT_YCBCR_420_P,
156     /**
157      * YCRCB420 planar format
158      * @since 12
159      */
160     NATIVEBUFFER_PIXEL_FMT_YCRCB_420_P,
161     /**
162      * YUYV422 packed format
163      * @since 12
164      */
165     NATIVEBUFFER_PIXEL_FMT_YUYV_422_PKG,
166     /**
167      * UYVY422 packed format
168      * @since 12
169      */
170     NATIVEBUFFER_PIXEL_FMT_UYVY_422_PKG,
171     /**
172      * YVYU422 packed format
173      * @since 12
174      */
175     NATIVEBUFFER_PIXEL_FMT_YVYU_422_PKG,
176     /**
177      * VYUY422 packed format
178      * @since 12
179      */
180     NATIVEBUFFER_PIXEL_FMT_VYUY_422_PKG,
181     /**
182      * RGBA_1010102 packed format
183      * @since 12
184      */
185     NATIVEBUFFER_PIXEL_FMT_RGBA_1010102,
186     /**
187      * YCBCR420 semi-planar 10bit packed format
188      * @since 12
189      */
190     NATIVEBUFFER_PIXEL_FMT_YCBCR_P010,
191     /**
192      * YCRCB420 semi-planar 10bit packed format
193      * @since 12
194      */
195     NATIVEBUFFER_PIXEL_FMT_YCRCB_P010,
196     /**
197      * Raw 10bit packed format
198      * @since 12
199      */
200     NATIVEBUFFER_PIXEL_FMT_RAW10,
201     /**
202      * BLOB format
203      * @since 15
204      */
205     NATIVEBUFFER_PIXEL_FMT_BLOB,
206     /**
207      * RGBA16 float format
208      * @since 15
209      */
210     NATIVEBUFFER_PIXEL_FMT_RGBA16_FLOAT,
211     /**
212      * Y8 format
213      * @since 20
214      */
215     NATIVEBUFFER_PIXEL_FMT_Y8 = 40,
216     /**
217      * Y16 format
218      * @since 20
219      */
220     NATIVEBUFFER_PIXEL_FMT_Y16 = 41,
221     /**
222      * vendor mask format
223      * @since 12
224      */
225     NATIVEBUFFER_PIXEL_FMT_VENDER_MASK = 0X7FFF0000,
226     NATIVEBUFFER_PIXEL_FMT_BUTT = 0X7FFFFFFF          /// < Invalid pixel format */
227 } OH_NativeBuffer_Format;
228 
229 /**
230  * @brief Indicates the transform type of a native buffer.
231  *
232  * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
233  * @since 12
234  * @version 1.0
235  */
236 typedef enum OH_NativeBuffer_TransformType {
237     NATIVEBUFFER_ROTATE_NONE = 0,         /**< No rotation */
238     NATIVEBUFFER_ROTATE_90,               /**< Rotation by 90 degrees */
239     NATIVEBUFFER_ROTATE_180,              /**< Rotation by 180 degrees */
240     NATIVEBUFFER_ROTATE_270,              /**< Rotation by 270 degrees */
241     NATIVEBUFFER_FLIP_H,                  /**< Flip horizontally */
242     NATIVEBUFFER_FLIP_V,                  /**< Flip vertically */
243     NATIVEBUFFER_FLIP_H_ROT90,            /**< Flip horizontally and rotate 90 degrees */
244     NATIVEBUFFER_FLIP_V_ROT90,            /**< Flip vertically and rotate 90 degrees */
245     NATIVEBUFFER_FLIP_H_ROT180,           /**< Flip horizontally and rotate 180 degrees */
246     NATIVEBUFFER_FLIP_V_ROT180,           /**< Flip vertically and rotate 180 degrees */
247     NATIVEBUFFER_FLIP_H_ROT270,           /**< Flip horizontally and rotate 270 degrees */
248     NATIVEBUFFER_FLIP_V_ROT270,           /**< Flip vertically and rotate 270 degrees */
249 } OH_NativeBuffer_TransformType;
250 
251 /**
252  * @brief Indicates the color gamut of a native buffer.
253  *
254  * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
255  * @since 12
256  * @version 1.0
257  */
258 typedef enum OH_NativeBuffer_ColorGamut {
259     NATIVEBUFFER_COLOR_GAMUT_NATIVE = 0,            /**< Native or default */
260     NATIVEBUFFER_COLOR_GAMUT_STANDARD_BT601 = 1,    /**< Standard BT601 */
261     NATIVEBUFFER_COLOR_GAMUT_STANDARD_BT709 = 2,    /**< Standard BT709 */
262     NATIVEBUFFER_COLOR_GAMUT_DCI_P3 = 3,            /**< DCI P3 */
263     NATIVEBUFFER_COLOR_GAMUT_SRGB = 4,              /**< SRGB */
264     NATIVEBUFFER_COLOR_GAMUT_ADOBE_RGB = 5,         /**< Adobe RGB */
265     NATIVEBUFFER_COLOR_GAMUT_DISPLAY_P3 = 6,        /**< Display P3 */
266     NATIVEBUFFER_COLOR_GAMUT_BT2020 = 7,            /**< BT2020 */
267     NATIVEBUFFER_COLOR_GAMUT_BT2100_PQ = 8,         /**< BT2100 PQ */
268     NATIVEBUFFER_COLOR_GAMUT_BT2100_HLG = 9,        /**< BT2100 HLG */
269     NATIVEBUFFER_COLOR_GAMUT_DISPLAY_BT2020 = 10,   /**< Display BT2020 */
270 } OH_NativeBuffer_ColorGamut;
271 
272 /**
273  * @brief <b>OH_NativeBuffer</b> config. \n
274  * Used to allocating new <b>OH_NativeBuffer</b> and query parameters if existing ones.
275  *
276  * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
277  * @since 9
278  * @version 1.0
279  */
280 typedef struct {
281     int32_t width;           ///< Width in pixels
282     int32_t height;          ///< Height in pixels
283     int32_t format;          ///< One of PixelFormat
284     int32_t usage;           ///< Combination of buffer usage
285     int32_t stride;          ///< the stride of memory in bytes
286 } OH_NativeBuffer_Config;
287 
288 /**
289  * @brief Holds info for a single image plane. \n
290  *
291  * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
292  * @since 12
293  * @version 1.0
294  */
295 typedef struct {
296     uint64_t offset;         ///< Offset in bytes of plane.
297     uint32_t rowStride;      ///< Distance in bytes from the first value of one row of the image to the first value of the next row.
298     uint32_t columnStride;   ///< Distance in bytes from the first value of one column of the image to the first value of the next column.
299 } OH_NativeBuffer_Plane;
300 
301 /**
302  * @brief Holds all image planes. \n
303  *
304  * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
305  * @since 12
306  * @version 1.0
307  */
308 typedef struct {
309     uint32_t planeCount;              ///< Number of distinct planes.
310     OH_NativeBuffer_Plane planes[4];  ///< Array of image planes.
311 } OH_NativeBuffer_Planes;
312 
313 /**
314  * @brief Alloc a <b>OH_NativeBuffer</b> that matches the passed BufferRequestConfig. \n
315  * A new <b>OH_NativeBuffer</b> instance is created each time this function is called.\n
316  * This interface needs to be used in conjunction with <b>OH_NativeBuffer_Unreference</b>,
317  * otherwise memory leaks will occur.\n
318  * This interface is a non-thread-safe type interface.\n
319  *
320  * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
321  * @param config Indicates the pointer to a <b>BufferRequestConfig</b> instance.
322  * @return Returns the pointer to the <b>OH_NativeBuffer</b> instance created if the operation is successful, \n
323  * returns <b>NULL</b> otherwise.
324  * @since 9
325  * @version 1.0
326  */
327 OH_NativeBuffer* OH_NativeBuffer_Alloc(const OH_NativeBuffer_Config* config);
328 
329 /**
330  * @brief Adds the reference count of a OH_NativeBuffer.\n
331  * This interface needs to be used in conjunction with <b>OH_NativeBuffer_Unreference</b>,
332  * otherwise memory leaks will occur.\n
333  * This interface is a non-thread-safe type interface.\n
334  *
335  * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
336  * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance.
337  * @return Returns an error code, 0 is success, otherwise, failed.
338  * @since 9
339  * @version 1.0
340  */
341 int32_t OH_NativeBuffer_Reference(OH_NativeBuffer *buffer);
342 
343 /**
344  * @brief Decreases the reference count of a OH_NativeBuffer and, when the reference count reaches 0,
345  * destroys this OH_NativeBuffer.\n
346  * This interface is a non-thread-safe type interface.\n
347  *
348  * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
349  * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance.
350  * @return Returns an error code, 0 is success, otherwise, failed.
351  * @since 9
352  * @version 1.0
353  */
354 int32_t OH_NativeBuffer_Unreference(OH_NativeBuffer *buffer);
355 
356 /**
357  * @brief Return a config of the OH_NativeBuffer in the passed OHNativeBufferConfig struct.\n
358  * This interface is a non-thread-safe type interface.\n
359  *
360  * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
361  * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance.
362  * @param config Indicates the pointer to the <b>NativeBufferConfig</b> of the buffer.
363  * @return <b>void</b>
364  * @since 9
365  * @version 1.0
366  */
367 void OH_NativeBuffer_GetConfig(OH_NativeBuffer *buffer, OH_NativeBuffer_Config* config);
368 
369 /**
370  * @brief Provide direct cpu access to the OH_NativeBuffer in the process's address space.\n
371  * This interface needs to be used in conjunction with <b>OH_NativeBuffer_Unmap</b>.\n
372  * This interface is a non-thread-safe type interface.\n
373  *
374  * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
375  * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance.
376  * @param virAddr Indicates the address of the <b>OH_NativeBuffer</b> in virtual memory.
377  * @return Returns an error code, 0 is success, otherwise, failed.
378  * @since 9
379  * @version 1.0
380  */
381 
382 int32_t OH_NativeBuffer_Map(OH_NativeBuffer *buffer, void **virAddr);
383 
384 /**
385  * @brief Remove direct cpu access ability of the OH_NativeBuffer in the process's address space.\n
386  * This interface is a non-thread-safe type interface.\n
387  *
388  * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
389  * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance.
390  * @return Returns an error code, 0 is success, otherwise, failed.
391  * @since 9
392  * @version 1.0
393  */
394 int32_t OH_NativeBuffer_Unmap(OH_NativeBuffer *buffer);
395 
396 /**
397  * @brief Get the system wide unique sequence number of the OH_NativeBuffer.\n
398  * This interface is a non-thread-safe type interface.\n
399  *
400  * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
401  * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance.
402  * @return Returns the sequence number, which is unique for each OH_NativeBuffer.
403  * @since 9
404  * @version 1.0
405  */
406 uint32_t OH_NativeBuffer_GetSeqNum(OH_NativeBuffer *buffer);
407 
408 /**
409  * @brief Provide direct cpu access to the potentially multi-planar OH_NativeBuffer in the process's address space.\n
410  * This interface is a non-thread-safe type interface.\n
411  *
412  * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
413  * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance.
414  * @param virAddr Indicates the address of the <b>OH_NativeBuffer</b> in virtual memory.
415  * @param outPlanes Indicates all image planes that contain the pixel data.
416  * @return Returns an error code, 0 is success, otherwise, failed.
417  * @since 12
418  * @version 1.0
419  */
420 int32_t OH_NativeBuffer_MapPlanes(OH_NativeBuffer *buffer, void **virAddr, OH_NativeBuffer_Planes *outPlanes);
421 
422 /**
423  * @brief Converts an <b>OHNativeWindowBuffer</b> instance to an <b>OH_NativeBuffer</b>.\n
424  * This interface is a non-thread-safe type interface.\n
425  *
426  * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
427  * @param nativeWindowBuffer Indicates the pointer to a <b>OHNativeWindowBuffer</b> instance.
428  * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> pointer.
429  * @return Returns an error code, 0 is success, otherwise, failed.
430  * @since 12
431  * @version 1.0
432  */
433 int32_t OH_NativeBuffer_FromNativeWindowBuffer(OHNativeWindowBuffer *nativeWindowBuffer, OH_NativeBuffer **buffer);
434 
435 /**
436  * @brief Set the color space of the OH_NativeBuffer.\n
437  * This interface is a non-thread-safe type interface.\n
438  *
439  * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
440  * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance.
441  * @param colorSpace Indicates the color space of native buffer, see <b>OH_NativeBuffer_ColorSpace</b>.
442  * @return Returns an error code, 0 is success, otherwise, failed.
443  * @since 11
444  * @version 1.0
445  */
446 int32_t OH_NativeBuffer_SetColorSpace(OH_NativeBuffer *buffer, OH_NativeBuffer_ColorSpace colorSpace);
447 
448 /**
449  * @brief Get the color space of the OH_NativeBuffer.\n
450  * This interface is a non-thread-safe type interface.\n
451  *
452  * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
453  * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance.
454  * @param colorSpace Indicates the color space of native buffer, see <b>OH_NativeBuffer_ColorSpace</b>.
455  * @return {@link NATIVE_ERROR_OK} 0 - Success.
456  *     {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - buffer is NULL.
457  *     {@link NATIVE_ERROR_BUFFER_STATE_INVALID} 41207000 - Incorrect colorSpace state.
458  * @since 12
459  * @version 1.0
460  */
461 int32_t OH_NativeBuffer_GetColorSpace(OH_NativeBuffer *buffer, OH_NativeBuffer_ColorSpace *colorSpace);
462 
463 /**
464  * @brief Set the metadata type of the OH_NativeBuffer.\n
465  * This interface is a non-thread-safe type interface.\n
466  *
467  * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
468  * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance.
469  * @param metadataKey Indicates the metadata type of native buffer, see <b>OH_NativeBuffer_MetadataKey</b>.
470  * @param size Indicates the size of a uint8_t vector.
471  * @param metadata Indicates the pointer to a uint8_t vector.
472  * @return {@link NATIVE_ERROR_OK} 0 - Success.
473  *     {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - buffer or metadata is NULL.
474  *     {@link NATIVE_ERROR_BUFFER_STATE_INVALID} 41207000 - Incorrect metadata state.
475  *     {@link NATIVE_ERROR_UNSUPPORTED} 50102000 - Unsupported metadata key.
476  * @since 12
477  * @version 1.0
478  */
479 int32_t OH_NativeBuffer_SetMetadataValue(OH_NativeBuffer *buffer, OH_NativeBuffer_MetadataKey metadataKey,
480     int32_t size, uint8_t *metadata);
481 
482 /**
483  * @brief Set the metadata type of the OH_NativeBuffer.\n
484  * This interface is a non-thread-safe type interface.\n
485  *
486  * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
487  * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance.
488  * @param metadataKey Indicates the metadata type of native buffer, see <b>OH_NativeBuffer_MetadataKey</b>.
489  * @param size Indicates the size of a uint8_t vector.
490  * @param metadata Indicates the pointer to a uint8_t vector.
491  * @return {@link NATIVE_ERROR_OK} 0 - Success.
492  *     {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - buffer, metadata, or size is NULL.
493  *     {@link NATIVE_ERROR_BUFFER_STATE_INVALID} 41207000 - Incorrect metadata state.
494  *     {@link NATIVE_ERROR_UNSUPPORTED} 50102000 - Unsupported metadata key.
495  * @since 12
496  * @version 1.0
497  */
498 int32_t OH_NativeBuffer_GetMetadataValue(OH_NativeBuffer *buffer, OH_NativeBuffer_MetadataKey metadataKey,
499     int32_t *size, uint8_t **metadata);
500 
501 #ifdef __cplusplus
502 }
503 #endif
504 
505 /** @} */
506 #endif