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 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-planar format 118 * @since 12 119 */ 120 NATIVEBUFFER_PIXEL_FMT_YCBCR_422_SP, 121 /** 122 * YCRCB422 semi-planar format 123 * @since 12 124 */ 125 NATIVEBUFFER_PIXEL_FMT_YCRCB_422_SP, 126 /** 127 * YCBCR420 semi-planar format 128 * @since 12 129 */ 130 NATIVEBUFFER_PIXEL_FMT_YCBCR_420_SP, 131 /** 132 * YCRCB420 semi-planar format 133 * @since 12 134 */ 135 NATIVEBUFFER_PIXEL_FMT_YCRCB_420_SP, 136 /** 137 * YCBCR422 planar format 138 * @since 12 139 */ 140 NATIVEBUFFER_PIXEL_FMT_YCBCR_422_P, 141 /** 142 * YCRCB422 planar format 143 * @since 12 144 */ 145 NATIVEBUFFER_PIXEL_FMT_YCRCB_422_P, 146 /** 147 * YCBCR420 planar format 148 * @since 12 149 */ 150 NATIVEBUFFER_PIXEL_FMT_YCBCR_420_P, 151 /** 152 * YCRCB420 planar 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 * BLOB format 198 * @since 15 199 */ 200 NATIVEBUFFER_PIXEL_FMT_BLOB, 201 /** 202 * RGBA16 float format 203 * @since 15 204 */ 205 NATIVEBUFFER_PIXEL_FMT_RGBA16_FLOAT, 206 /** 207 * vendor mask format 208 * @since 12 209 */ 210 NATIVEBUFFER_PIXEL_FMT_VENDER_MASK = 0X7FFF0000, 211 NATIVEBUFFER_PIXEL_FMT_BUTT = 0X7FFFFFFF /// < Invalid pixel format */ 212 } OH_NativeBuffer_Format; 213 214 /** 215 * @brief Indicates the transform type of a native buffer. 216 * 217 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 218 * @since 12 219 * @version 1.0 220 */ 221 typedef enum OH_NativeBuffer_TransformType { 222 NATIVEBUFFER_ROTATE_NONE = 0, /**< No rotation */ 223 NATIVEBUFFER_ROTATE_90, /**< Rotation by 90 degrees */ 224 NATIVEBUFFER_ROTATE_180, /**< Rotation by 180 degrees */ 225 NATIVEBUFFER_ROTATE_270, /**< Rotation by 270 degrees */ 226 NATIVEBUFFER_FLIP_H, /**< Flip horizontally */ 227 NATIVEBUFFER_FLIP_V, /**< Flip vertically */ 228 NATIVEBUFFER_FLIP_H_ROT90, /**< Flip horizontally and rotate 90 degrees */ 229 NATIVEBUFFER_FLIP_V_ROT90, /**< Flip vertically and rotate 90 degrees */ 230 NATIVEBUFFER_FLIP_H_ROT180, /**< Flip horizontally and rotate 180 degrees */ 231 NATIVEBUFFER_FLIP_V_ROT180, /**< Flip vertically and rotate 180 degrees */ 232 NATIVEBUFFER_FLIP_H_ROT270, /**< Flip horizontally and rotate 270 degrees */ 233 NATIVEBUFFER_FLIP_V_ROT270, /**< Flip vertically and rotate 270 degrees */ 234 } OH_NativeBuffer_TransformType; 235 236 /** 237 * @brief Indicates the color gamut of a native buffer. 238 * 239 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 240 * @since 12 241 * @version 1.0 242 */ 243 typedef enum OH_NativeBuffer_ColorGamut { 244 NATIVEBUFFER_COLOR_GAMUT_NATIVE = 0, /**< Native or default */ 245 NATIVEBUFFER_COLOR_GAMUT_STANDARD_BT601 = 1, /**< Standard BT601 */ 246 NATIVEBUFFER_COLOR_GAMUT_STANDARD_BT709 = 2, /**< Standard BT709 */ 247 NATIVEBUFFER_COLOR_GAMUT_DCI_P3 = 3, /**< DCI P3 */ 248 NATIVEBUFFER_COLOR_GAMUT_SRGB = 4, /**< SRGB */ 249 NATIVEBUFFER_COLOR_GAMUT_ADOBE_RGB = 5, /**< Adobe RGB */ 250 NATIVEBUFFER_COLOR_GAMUT_DISPLAY_P3 = 6, /**< Display P3 */ 251 NATIVEBUFFER_COLOR_GAMUT_BT2020 = 7, /**< BT2020 */ 252 NATIVEBUFFER_COLOR_GAMUT_BT2100_PQ = 8, /**< BT2100 PQ */ 253 NATIVEBUFFER_COLOR_GAMUT_BT2100_HLG = 9, /**< BT2100 HLG */ 254 NATIVEBUFFER_COLOR_GAMUT_DISPLAY_BT2020 = 10, /**< Display BT2020 */ 255 } OH_NativeBuffer_ColorGamut; 256 257 /** 258 * @brief <b>OH_NativeBuffer</b> config. \n 259 * Used to allocating new <b>OH_NativeBuffer</b> and query parameters if existing ones. 260 * 261 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 262 * @since 9 263 * @version 1.0 264 */ 265 typedef struct { 266 int32_t width; ///< Width in pixels 267 int32_t height; ///< Height in pixels 268 int32_t format; ///< One of PixelFormat 269 int32_t usage; ///< Combination of buffer usage 270 int32_t stride; ///< the stride of memory 271 } OH_NativeBuffer_Config; 272 273 /** 274 * @brief Holds info for a single image plane. \n 275 * 276 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 277 * @since 12 278 * @version 1.0 279 */ 280 typedef struct { 281 uint64_t offset; ///< Offset in bytes of plane. 282 uint32_t rowStride; ///< Distance in bytes from the first value of one row of the image to the first value of the next row. 283 uint32_t columnStride; ///< Distance in bytes from the first value of one column of the image to the first value of the next column. 284 } OH_NativeBuffer_Plane; 285 286 /** 287 * @brief Holds all image planes. \n 288 * 289 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 290 * @since 12 291 * @version 1.0 292 */ 293 typedef struct { 294 uint32_t planeCount; ///< Number of distinct planes. 295 OH_NativeBuffer_Plane planes[4]; ///< Array of image planes. 296 } OH_NativeBuffer_Planes; 297 298 /** 299 * @brief Alloc a <b>OH_NativeBuffer</b> that matches the passed BufferRequestConfig. \n 300 * A new <b>OH_NativeBuffer</b> instance is created each time this function is called.\n 301 * This interface needs to be used in conjunction with <b>OH_NativeBuffer_Unreference</b>, 302 * otherwise memory leaks will occur.\n 303 * This interface is a non-thread-safe type interface.\n 304 * 305 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 306 * @param config Indicates the pointer to a <b>BufferRequestConfig</b> instance. 307 * @return Returns the pointer to the <b>OH_NativeBuffer</b> instance created if the operation is successful, \n 308 * returns <b>NULL</b> otherwise. 309 * @since 9 310 * @version 1.0 311 */ 312 OH_NativeBuffer* OH_NativeBuffer_Alloc(const OH_NativeBuffer_Config* config); 313 314 /** 315 * @brief Adds the reference count of a OH_NativeBuffer.\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 buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance. 322 * @return Returns an error code, 0 is success, otherwise, failed. 323 * @since 9 324 * @version 1.0 325 */ 326 int32_t OH_NativeBuffer_Reference(OH_NativeBuffer *buffer); 327 328 /** 329 * @brief Decreases the reference count of a OH_NativeBuffer and, when the reference count reaches 0, 330 * destroys this OH_NativeBuffer.\n 331 * This interface is a non-thread-safe type interface.\n 332 * 333 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 334 * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance. 335 * @return Returns an error code, 0 is success, otherwise, failed. 336 * @since 9 337 * @version 1.0 338 */ 339 int32_t OH_NativeBuffer_Unreference(OH_NativeBuffer *buffer); 340 341 /** 342 * @brief Return a config of the OH_NativeBuffer in the passed OHNativeBufferConfig struct.\n 343 * This interface is a non-thread-safe type interface.\n 344 * 345 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 346 * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance. 347 * @param config Indicates the pointer to the <b>NativeBufferConfig</b> of the buffer. 348 * @return <b>void</b> 349 * @since 9 350 * @version 1.0 351 */ 352 void OH_NativeBuffer_GetConfig(OH_NativeBuffer *buffer, OH_NativeBuffer_Config* config); 353 354 /** 355 * @brief Provide direct cpu access to the OH_NativeBuffer in the process's address space.\n 356 * This interface needs to be used in conjunction with <b>OH_NativeBuffer_Unmap</b>.\n 357 * This interface is a non-thread-safe type interface.\n 358 * 359 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 360 * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance. 361 * @param virAddr Indicates the address of the <b>OH_NativeBuffer</b> in virtual memory. 362 * @return Returns an error code, 0 is success, otherwise, failed. 363 * @since 9 364 * @version 1.0 365 */ 366 367 int32_t OH_NativeBuffer_Map(OH_NativeBuffer *buffer, void **virAddr); 368 369 /** 370 * @brief Remove direct cpu access ability of the OH_NativeBuffer in the process's address space.\n 371 * This interface is a non-thread-safe type interface.\n 372 * 373 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 374 * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance. 375 * @return Returns an error code, 0 is success, otherwise, failed. 376 * @since 9 377 * @version 1.0 378 */ 379 int32_t OH_NativeBuffer_Unmap(OH_NativeBuffer *buffer); 380 381 /** 382 * @brief Get the system wide unique sequence number of the OH_NativeBuffer.\n 383 * This interface is a non-thread-safe type interface.\n 384 * 385 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 386 * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance. 387 * @return Returns the sequence number, which is unique for each OH_NativeBuffer. 388 * @since 9 389 * @version 1.0 390 */ 391 uint32_t OH_NativeBuffer_GetSeqNum(OH_NativeBuffer *buffer); 392 393 /** 394 * @brief Provide direct cpu access to the potentially multi-planar OH_NativeBuffer in the process's address space.\n 395 * This interface is a non-thread-safe type interface.\n 396 * 397 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 398 * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance. 399 * @param virAddr Indicates the address of the <b>OH_NativeBuffer</b> in virtual memory. 400 * @param outPlanes Indicates all image planes that contain the pixel data. 401 * @return Returns an error code, 0 is success, otherwise, failed. 402 * @since 12 403 * @version 1.0 404 */ 405 int32_t OH_NativeBuffer_MapPlanes(OH_NativeBuffer *buffer, void **virAddr, OH_NativeBuffer_Planes *outPlanes); 406 407 /** 408 * @brief Converts an <b>OHNativeWindowBuffer</b> instance to an <b>OH_NativeBuffer</b>.\n 409 * This interface is a non-thread-safe type interface.\n 410 * 411 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 412 * @param nativeWindowBuffer Indicates the pointer to a <b>OHNativeWindowBuffer</b> instance. 413 * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> pointer. 414 * @return Returns an error code, 0 is success, otherwise, failed. 415 * @since 12 416 * @version 1.0 417 */ 418 int32_t OH_NativeBuffer_FromNativeWindowBuffer(OHNativeWindowBuffer *nativeWindowBuffer, OH_NativeBuffer **buffer); 419 420 /** 421 * @brief Set the color space of the OH_NativeBuffer.\n 422 * This interface is a non-thread-safe type interface.\n 423 * 424 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 425 * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance. 426 * @param colorSpace Indicates the color space of native buffer, see <b>OH_NativeBuffer_ColorSpace</b>. 427 * @return Returns an error code, 0 is success, otherwise, failed. 428 * @since 11 429 * @version 1.0 430 */ 431 int32_t OH_NativeBuffer_SetColorSpace(OH_NativeBuffer *buffer, OH_NativeBuffer_ColorSpace colorSpace); 432 433 /** 434 * @brief Get the color space of the OH_NativeBuffer.\n 435 * This interface is a non-thread-safe type interface.\n 436 * 437 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 438 * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance. 439 * @param colorSpace Indicates the color space of native buffer, see <b>OH_NativeBuffer_ColorSpace</b>. 440 * @return {@link NATIVE_ERROR_OK} 0 - Success. 441 * {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - buffer is NULL. 442 * {@link NATIVE_ERROR_BUFFER_STATE_INVALID} 41207000 - Incorrect colorSpace state. 443 * @since 12 444 * @version 1.0 445 */ 446 int32_t OH_NativeBuffer_GetColorSpace(OH_NativeBuffer *buffer, OH_NativeBuffer_ColorSpace *colorSpace); 447 448 /** 449 * @brief Set the metadata type 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 metadataKey Indicates the metadata type of native buffer, see <b>OH_NativeBuffer_MetadataKey</b>. 455 * @param size Indicates the size of a uint8_t vector. 456 * @param metadata Indicates the pointer to a uint8_t vector. 457 * @return {@link NATIVE_ERROR_OK} 0 - Success. 458 * {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - buffer or metadata is NULL. 459 * {@link NATIVE_ERROR_BUFFER_STATE_INVALID} 41207000 - Incorrect metadata state. 460 * {@link NATIVE_ERROR_UNSUPPORTED} 50102000 - Unsupported metadata key. 461 * @since 12 462 * @version 1.0 463 */ 464 int32_t OH_NativeBuffer_SetMetadataValue(OH_NativeBuffer *buffer, OH_NativeBuffer_MetadataKey metadataKey, 465 int32_t size, uint8_t *metadata); 466 467 /** 468 * @brief Set the metadata type of the OH_NativeBuffer.\n 469 * This interface is a non-thread-safe type interface.\n 470 * 471 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 472 * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance. 473 * @param metadataKey Indicates the metadata type of native buffer, see <b>OH_NativeBuffer_MetadataKey</b>. 474 * @param size Indicates the size of a uint8_t vector. 475 * @param metadata Indicates the pointer to a uint8_t vector. 476 * @return {@link NATIVE_ERROR_OK} 0 - Success. 477 * {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - buffer, metadata, or size is NULL. 478 * {@link NATIVE_ERROR_BUFFER_STATE_INVALID} 41207000 - Incorrect metadata state. 479 * {@link NATIVE_ERROR_UNSUPPORTED} 50102000 - Unsupported metadata key. 480 * @since 12 481 * @version 1.0 482 */ 483 int32_t OH_NativeBuffer_GetMetadataValue(OH_NativeBuffer *buffer, OH_NativeBuffer_MetadataKey metadataKey, 484 int32_t *size, uint8_t **metadata); 485 486 #ifdef __cplusplus 487 } 488 #endif 489 490 /** @} */ 491 #endif