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