1# OH_NativeBuffer 2 3 4## Overview 5 6The **OH_NativeBuffer** module provides the capabilities of **NativeBuffer**. Using the functions provided by this module, you can apply for, use, and release the shared memory, and query its attributes. 7 8**System capability**: SystemCapability.Graphic.Graphic2D.NativeBuffer 9 10**Since**: 9 11 12 13## Summary 14 15 16### Files 17 18| Name| Description| 19| -------- | -------- | 20| [native_buffer.h](native__buffer_8h.md) | Declares the functions for obtaining and using **NativeBuffer**.<br>**File to include**: <native_buffer/native_buffer.h><br>**Library**: libnative_buffer.so| 21 22 23### Structs 24 25| Name| Description| 26| -------- | -------- | 27| [OH_NativeBuffer_Config](_o_h___native_buffer___config.md) | Defines the **OH_NativeBuffer** attribute configuration, which is used when you apply for a new **OH_NativeBuffer** instance or query the attributes of an existing instance.| 28 29 30### Types 31 32| Name| Description| 33| -------- | -------- | 34| [OH_NativeBuffer](#oh_nativebuffer) | Provides the declaration of an **OH_NativeBuffer** struct.| 35 36 37### Enums 38 39| Name| Description| 40| -------- | -------- | 41| [OH_NativeBuffer_Usage](#oh_nativebuffer_usage) { NATIVEBUFFER_USAGE_CPU_READ = (1ULL << 0), NATIVEBUFFER_USAGE_CPU_WRITE = (1ULL << 1), NATIVEBUFFER_USAGE_MEM_DMA = (1ULL << 3) } | Enumerates the **OH_NativeBuffer** usages.| 42| [OH_NativeBuffer_Format](#oh_nativebuffer_format) {<br>NATIVEBUFFER_PIXEL_FMT_RGB_565 = 3, NATIVEBUFFER_PIXEL_FMT_RGBA_5658, NATIVEBUFFER_PIXEL_FMT_RGBX_4444, NATIVEBUFFER_PIXEL_FMT_RGBA_4444,<br>NATIVEBUFFER_PIXEL_FMT_RGB_444, NATIVEBUFFER_PIXEL_FMT_RGBX_5551, NATIVEBUFFER_PIXEL_FMT_RGBA_5551, NATIVEBUFFER_PIXEL_FMT_RGB_555,<br>NATIVEBUFFER_PIXEL_FMT_RGBX_8888, NATIVEBUFFER_PIXEL_FMT_RGBA_8888, NATIVEBUFFER_PIXEL_FMT_RGB_888, NATIVEBUFFER_PIXEL_FMT_BGR_565,<br>NATIVEBUFFER_PIXEL_FMT_BGRX_4444, NATIVEBUFFER_PIXEL_FMT_BGRA_4444, NATIVEBUFFER_PIXEL_FMT_BGRX_5551, NATIVEBUFFER_PIXEL_FMT_BGRA_5551,<br>NATIVEBUFFER_PIXEL_FMT_BGRX_8888, NATIVEBUFFER_PIXEL_FMT_BGRA_8888, NATIVEBUFFER_PIXEL_FMT_BUTT = 0X7FFFFFFF<br>} | Enumerates the **OH_NativeBuffer** formats.| 43| [OH_NativeBuffer_ColorSpace](#oh_nativebuffer_colorspace) {<br>OH_COLORSPACE_NONE, OH_COLORSPACE_BT601_EBU_FULL, OH_COLORSPACE_BT601_SMPTE_C_FULL, OH_COLORSPACE_BT709_FULL,<br>OH_COLORSPACE_BT2020_HLG_FULL, OH_COLORSPACE_BT2020_PQ_FULL, OH_COLORSPACE_BT601_EBU_LIMIT, OH_COLORSPACE_BT601_SMPTE_C_LIMIT,<br>OH_COLORSPACE_BT709_LIMIT, OH_COLORSPACE_BT2020_HLG_LIMIT, OH_COLORSPACE_BT2020_PQ_LIMIT, OH_COLORSPACE_SRGB_FULL,<br>OH_COLORSPACE_P3_FULL, OH_COLORSPACE_P3_HLG_FULL, OH_COLORSPACE_P3_PQ_FULL, OH_COLORSPACE_ADOBERGB_FULL,<br>OH_COLORSPACE_SRGB_LIMIT, OH_COLORSPACE_P3_LIMIT, OH_COLORSPACE_P3_HLG_LIMIT, OH_COLORSPACE_P3_PQ_LIMIT,<br>OH_COLORSPACE_ADOBERGB_LIMIT, OH_COLORSPACE_LINEAR_SRGB, OH_COLORSPACE_LINEAR_BT709, OH_COLORSPACE_LINEAR_P3,<br>OH_COLORSPACE_LINEAR_BT2020, OH_COLORSPACE_DISPLAY_SRGB, OH_COLORSPACE_DISPLAY_P3_SRGB, OH_COLORSPACE_DISPLAY_P3_HLG,<br>OH_COLORSPACE_DISPLAY_P3_PQ, OH_COLORSPACE_DISPLAY_BT2020_SRGB, OH_COLORSPACE_DISPLAY_BT2020_HLG, OH_COLORSPACE_DISPLAY_BT2020_PQ<br>} | Enumerates the color spaces of an **OH_NativeBuffer** instance.| 44 45 46### Functions 47 48| Name| Description| 49| -------- | -------- | 50| [OH_NativeBuffer_Alloc](#oh_nativebuffer_alloc) (const [OH_NativeBuffer_Config](_o_h___native_buffer___config.md) \*config) | Creates an **OH_NativeBuffer** instance based on an **OH_NativeBuffer_Config** struct. A new **OH_NativeBuffer** instance is created each time this function is called.| 51| [OH_NativeBuffer_Reference](#oh_nativebuffer_reference) ([OH_NativeBuffer](#oh_nativebuffer) \*buffer) | Increases the reference count of an **OH_NativeBuffer** instance by 1.| 52| [OH_NativeBuffer_Unreference](#oh_nativebuffer_unreference) ([OH_NativeBuffer](#oh_nativebuffer) \*buffer) | Decreases the reference count of an **OH_NativeBuffer** instance by 1 and, when the reference count reaches 0, destroys the instance.| 53| [OH_NativeBuffer_GetConfig](#oh_nativebuffer_getconfig) ([OH_NativeBuffer](#oh_nativebuffer) \*buffer, [OH_NativeBuffer_Config](_o_h___native_buffer___config.md) \*config) | Obtains the attributes of an **OH_NativeBuffer** instance.| 54| [OH_NativeBuffer_Map](#oh_nativebuffer_map) ([OH_NativeBuffer](#oh_nativebuffer) \*buffer, void \*\*virAddr) | Maps the ION memory corresponding to an **OH_NativeBuffer** instance to the process address space.| 55| [OH_NativeBuffer_Unmap](#oh_nativebuffer_unmap) ([OH_NativeBuffer](#oh_nativebuffer) \*buffer) | Unmaps the ION memory corresponding to an **OH_NativeBuffer** instance from the process address space.| 56| [OH_NativeBuffer_GetSeqNum](#oh_nativebuffer_getseqnum) ([OH_NativeBuffer](#oh_nativebuffer) \*buffer) | Obtains the sequence number of an **OH_NativeBuffer** instance.| 57| [OH_NativeBuffer_SetColorSpace](#oh_nativebuffer_setcolorspace) ([OH_NativeBuffer](#oh_nativebuffer) \*buffer, [OH_NativeBuffer_ColorSpace](#oh_nativebuffer_colorspace) colorSpace) | Sets the color space for an **OH_NativeBuffer** instance.| 58 59 60## Type Description 61 62 63### OH_NativeBuffer 64 65``` 66typedef struct OH_NativeBufferOH_NativeBuffer 67``` 68 69**Description** 70 71Provides the declaration of an **OH_NativeBuffer** struct. 72 73**Since**: 9 74 75 76## Enum Description 77 78 79### OH_NativeBuffer_ColorSpace 80 81``` 82enum OH_NativeBuffer_ColorSpace 83``` 84 85**Description** 86 87Indicates the color space of a native buffer. 88 89**System capability**: SystemCapability.Graphic.Graphic2D.NativeBuffer 90 91**Since**: 11 92 93| Value| Description| 94| -------- | -------- | 95| OH_COLORSPACE_NONE | No color space is available.| 96| OH_COLORSPACE_BT601_EBU_FULL | The color gamut is BT601_P, the transfer function is BT709, the conversion matrix is BT601_P, and the data range is RANGE_FULL.| 97| OH_COLORSPACE_BT601_SMPTE_C_FULL | The color gamut is BT601_N, the transfer function is BT709, the conversion matrix is BT601_N, and the data range is RANGE_FULL.| 98| OH_COLORSPACE_BT709_FULL | The color gamut is BT709, the transfer function is BT709, the conversion matrix is BT709, and the data range is RANGE_FULL.| 99| OH_COLORSPACE_BT2020_HLG_FULL | The color gamut is BT2020, the transfer function is HLG, the conversion matrix is BT2020, and the data range is RANGE_FULL.| 100| OH_COLORSPACE_BT2020_PQ_FULL | The color gamut is BT2020, the transfer function is PQ, the conversion matrix is BT2020, and the data range is RANGE_FULL.| 101| OH_COLORSPACE_BT601_EBU_LIMIT | The color gamut is BT601_P, the transfer function is BT709, the conversion matrix is BT601_P, and the data range is RANGE_LIMITED.| 102| OH_COLORSPACE_BT601_SMPTE_C_LIMIT | The color gamut is BT601_N, the transfer function is BT709, the conversion matrix is BT601_N, and the data range is RANGE_LIMITED.| 103| OH_COLORSPACE_BT709_LIMIT | The color gamut is BT709, the transfer function is BT709, the conversion matrix is BT709, and the data range is RANGE_LIMITED.| 104| OH_COLORSPACE_BT2020_HLG_LIMIT | The color gamut is BT2020, the transfer function is HLG, the conversion matrix is BT2020, and the data range is RANGE_LIMITED.| 105| OH_COLORSPACE_BT2020_PQ_LIMIT | The color gamut is BT2020, the transfer function is PQ, the conversion matrix is BT2020, and the data range is RANGE_LIMITED.| 106| OH_COLORSPACE_SRGB_FULL | The color gamut is SRGB, the transfer function is SRGB, the conversion matrix is BT601_N, and the data range is RANGE_FULL.| 107| OH_COLORSPACE_P3_FULL | The color gamut is P3_D65, the transfer function is SRGB, the conversion matrix is P3, and the data range is RANGE_FULL.| 108| OH_COLORSPACE_P3_HLG_FULL | The color gamut is P3_D65, the transfer function is HLG, the conversion matrix is P3, and the data range is RANGE_FULL.| 109| OH_COLORSPACE_P3_PQ_FULL | The color gamut is P3_D65, the transfer function is PQ, the conversion matrix is P3, and the data range is RANGE_FULL.| 110| OH_COLORSPACE_ADOBERGB_FULL | The color gamut is ADOBERGB, the transfer function is ADOBERGB, the conversion matrix is ADOBERGB, and the data range is RANGE_FULL.| 111| OH_COLORSPACE_SRGB_LIMIT | The color gamut is SRGB, the transfer function is SRGB, the conversion matrix is BT601_N, and the data range is RANGE_LIMITED.| 112| OH_COLORSPACE_P3_LIMIT | The color gamut is P3_D65, the transfer function is SRGB, the conversion matrix is P3, and the data range is RANGE_LIMITED.| 113| OH_COLORSPACE_P3_HLG_LIMIT | The color gamut is P3_D65, the transfer function is HLG, the conversion matrix is P3, and the data range is RANGE_LIMITED.| 114| OH_COLORSPACE_P3_PQ_LIMIT | The color gamut is P3_D65, the transfer function is PQ, the conversion matrix is P3, and the data range is RANGE_LIMITED.| 115| OH_COLORSPACE_ADOBERGB_LIMIT | The color gamut is ADOBERGB, the transfer function is ADOBERGB, the conversion matrix is ADOBERGB, and the data range is RANGE_LIMITED.| 116| OH_COLORSPACE_LINEAR_SRGB | The color gamut is SRGB, and the transfer function is LINEAR.| 117| OH_COLORSPACE_LINEAR_BT709 | It is equivalent to **OH_COLORSPACE_LINEAR_SRGB**.| 118| OH_COLORSPACE_LINEAR_P3 | The color gamut is P3_D65, and the transfer function is LINEAR.| 119| OH_COLORSPACE_LINEAR_BT2020 | The color gamut is BT2020, and the transfer function is LINEAR.| 120| OH_COLORSPACE_DISPLAY_SRGB | It is equivalent to **OH_COLORSPACE_SRGB_FULL**.| 121| OH_COLORSPACE_DISPLAY_P3_SRGB | It is equivalent to **OH_COLORSPACE_P3_FULL**.| 122| OH_COLORSPACE_DISPLAY_P3_HLG | It is equivalent to **OH_COLORSPACE_P3_HLG_FULL**.| 123| OH_COLORSPACE_DISPLAY_P3_PQ | It is equivalent to **OH_COLORSPACE_P3_PQ_FULL**.| 124| OH_COLORSPACE_DISPLAY_BT2020_SRGB | The color gamut is BT2020, the transfer function is SRGB, the conversion matrix is BT2020, and the data range is RANGE_FULL.| 125| OH_COLORSPACE_DISPLAY_BT2020_HLG | It is equivalent to **OH_COLORSPACE_BT2020_HLG_FULL**.| 126| OH_COLORSPACE_DISPLAY_BT2020_PQ | It is equivalent to **OH_COLORSPACE_BT2020_PQ_FULL**.| 127 128 129### OH_NativeBuffer_Format 130 131``` 132enum OH_NativeBuffer_Format 133``` 134 135**Description** 136 137Enumerates the **OH_NativeBuffer** formats. 138 139**System capability**: SystemCapability.Graphic.Graphic2D.NativeBuffer 140 141**Since**: 10 142 143| Value| Description| 144| -------- | -------- | 145| NATIVEBUFFER_PIXEL_FMT_RGB_565 | RGB565.| 146| NATIVEBUFFER_PIXEL_FMT_RGBA_5658 | RGBA5658.| 147| NATIVEBUFFER_PIXEL_FMT_RGBX_4444 | RGBX4444.| 148| NATIVEBUFFER_PIXEL_FMT_RGBA_4444 | RGBA4444.| 149| NATIVEBUFFER_PIXEL_FMT_RGB_444 | RGB444.| 150| NATIVEBUFFER_PIXEL_FMT_RGBX_5551 | RGBX5551.| 151| NATIVEBUFFER_PIXEL_FMT_RGBA_5551 | RGBA5551.| 152| NATIVEBUFFER_PIXEL_FMT_RGB_555 | RGB555.| 153| NATIVEBUFFER_PIXEL_FMT_RGBX_8888 | RGBX8888.| 154| NATIVEBUFFER_PIXEL_FMT_RGBA_8888 | RGBA8888.| 155| NATIVEBUFFER_PIXEL_FMT_RGB_888 | RGB888.| 156| NATIVEBUFFER_PIXEL_FMT_BGR_565 | BGR565.| 157| NATIVEBUFFER_PIXEL_FMT_BGRX_4444 | BGRX4444.| 158| NATIVEBUFFER_PIXEL_FMT_BGRA_4444 | BGRA4444.| 159| NATIVEBUFFER_PIXEL_FMT_BGRX_5551 | BGRX5551.| 160| NATIVEBUFFER_PIXEL_FMT_BGRA_5551 | BGRA5551.| 161| NATIVEBUFFER_PIXEL_FMT_BGRX_8888 | BGRX8888.| 162| NATIVEBUFFER_PIXEL_FMT_BGRA_8888 | BGRA8888.| 163| NATIVEBUFFER_PIXEL_FMT_BUTT | Invalid format.| 164 165 166### OH_NativeBuffer_Usage 167 168``` 169enum OH_NativeBuffer_Usage 170``` 171 172**Description** 173 174Enumerates the **OH_NativeBuffer** usages. 175 176**System capability**: SystemCapability.Graphic.Graphic2D.NativeBuffer 177 178**Since**: 10 179 180| Value| Description| 181| -------- | -------- | 182| NATIVEBUFFER_USAGE_CPU_READ | Read by the CPU.| 183| NATIVEBUFFER_USAGE_CPU_WRITE | Write by the CPU.| 184| NATIVEBUFFER_USAGE_MEM_DMA | Direct memory access to the buffer.| 185 186 187## Function Description 188 189 190### OH_NativeBuffer_Alloc() 191 192``` 193OH_NativeBuffer* OH_NativeBuffer_Alloc (const OH_NativeBuffer_Config * config) 194``` 195 196**Description** 197 198Creates an **OH_NativeBuffer** instance based on an **OH_NativeBuffer_Config** struct. A new **OH_NativeBuffer** instance is created each time this function is called. 199 200**System capability**: SystemCapability.Graphic.Graphic2D.NativeBuffer 201 202**Since**: 9 203 204**Parameters** 205 206| Name| Description| 207| -------- | -------- | 208| config | Pointer to an **OH_NativeBuffer_Config** instance.| 209 210**Returns** 211 212Returns the pointer to the **OH_NativeBuffer** instance created if the operation is successful; returns **NULL** otherwise. 213 214 215### OH_NativeBuffer_GetConfig() 216 217``` 218void OH_NativeBuffer_GetConfig (OH_NativeBuffer * buffer, OH_NativeBuffer_Config * config ) 219``` 220 221**Description** 222 223Obtains the attributes of an **OH_NativeBuffer** instance. 224 225**System capability**: SystemCapability.Graphic.Graphic2D.NativeBuffer 226 227**Since**: 9 228 229**Parameters** 230 231| Name| Description| 232| -------- | -------- | 233| buffer | Pointer to an **OH_NativeBuffer** instance.| 234| config | Pointer to an **OH_NativeBuffer_Config** instance, which is used to receive the attributes of **OH_NativeBuffer**.| 235 236 237### OH_NativeBuffer_GetSeqNum() 238 239``` 240uint32_t OH_NativeBuffer_GetSeqNum (OH_NativeBuffer * buffer) 241``` 242 243**Description** 244 245Obtains the sequence number of an **OH_NativeBuffer** instance. 246 247**System capability**: SystemCapability.Graphic.Graphic2D.NativeBuffer 248 249**Since**: 9 250 251**Parameters** 252 253| Name| Description| 254| -------- | -------- | 255| buffer | Pointer to an **OH_NativeBuffer** instance.| 256 257**Returns** 258 259Returns the unique sequence number of the **OH_NativeBuffer** instance. 260 261 262### OH_NativeBuffer_Map() 263 264``` 265int32_t OH_NativeBuffer_Map (OH_NativeBuffer * buffer, void ** virAddr ) 266``` 267 268**Description** 269 270Maps the ION memory corresponding to an **OH_NativeBuffer** instance to the process address space. 271 272**System capability**: SystemCapability.Graphic.Graphic2D.NativeBuffer 273 274**Since**: 9 275 276**Parameters** 277 278| Name| Description| 279| -------- | -------- | 280| buffer | Pointer to an **OH_NativeBuffer** instance.| 281| virAddr | Double pointer to the address of the virtual memory.| 282 283**Returns** 284 285Returns **0** if the operation is successful. 286 287 288### OH_NativeBuffer_Reference() 289 290``` 291int32_t OH_NativeBuffer_Reference (OH_NativeBuffer * buffer) 292``` 293 294**Description** 295 296Increases the reference count of an **OH_NativeBuffer** instance by 1. 297 298**System capability**: SystemCapability.Graphic.Graphic2D.NativeBuffer 299 300**Since**: 9 301 302**Parameters** 303 304| Name| Description| 305| -------- | -------- | 306| buffer | Pointer to an **OH_NativeBuffer** instance.| 307 308**Returns** 309 310Returns **0** if the operation is successful. 311 312 313### OH_NativeBuffer_SetColorSpace() 314 315``` 316int32_t OH_NativeBuffer_SetColorSpace (OH_NativeBuffer * buffer, OH_NativeBuffer_ColorSpace colorSpace ) 317``` 318 319**Description** 320 321Sets the color space for an **OH_NativeBuffer** instance. 322 323**System capability**: SystemCapability.Graphic.Graphic2D.NativeBuffer 324 325**Since**: 11 326 327**Parameters** 328 329| Name| Description| 330| -------- | -------- | 331| buffer | Pointer to an **OH_NativeBuffer** instance.| 332| colorSpace | Color space to set. The value is obtained from **OH_NativeBuffer_ColorSpace**.| 333 334**Returns** 335 336Returns **0** if the operation is successful. 337 338 339### OH_NativeBuffer_Unmap() 340 341``` 342int32_t OH_NativeBuffer_Unmap (OH_NativeBuffer * buffer) 343``` 344 345**Description** 346 347Unmaps the ION memory corresponding to an **OH_NativeBuffer** instance from the process address space. 348 349**System capability**: SystemCapability.Graphic.Graphic2D.NativeBuffer 350 351**Since**: 9 352 353**Parameters** 354 355| Name| Description| 356| -------- | -------- | 357| buffer | Pointer to an **OH_NativeBuffer** instance.| 358 359**Returns** 360 361Returns **0** if the operation is successful. 362 363 364### OH_NativeBuffer_Unreference() 365 366``` 367int32_t OH_NativeBuffer_Unreference (OH_NativeBuffer * buffer) 368``` 369 370**Description** 371 372Decreases the reference count of an **OH_NativeBuffer** instance by 1 and, when the reference count reaches 0, destroys the instance. 373 374**System capability**: SystemCapability.Graphic.Graphic2D.NativeBuffer 375 376**Since**: 9 377 378**Parameters** 379 380| Name| Description| 381| -------- | -------- | 382| buffer | Pointer to an **OH_NativeBuffer** instance.| 383 384**Returns** 385 386Returns **0** if the operation is successful. 387