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\@syscap SystemCapability.Graphic.Graphic2D.OH_NativeBuffer 9 10**Since** 11 129 13 14 15## Summary 16 17 18### Files 19 20| Name| Description| 21| -------- | -------- | 22| [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| 23 24 25### Structs 26 27| Name| Description| 28| -------- | -------- | 29| [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.| 30 31 32### Types 33 34| Name| Description| 35| -------- | -------- | 36| [OH_NativeBuffer](#oh_nativebuffer) | Provides the declaration of an **OH_NativeBuffer** struct.| 37 38### Enums 39 40| Name| Description| 41| -------- | -------- | 42| [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.| 43| [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.| 44 45### Functions 46 47| Name| Description| 48| -------- | -------- | 49| [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.| 50| [OH_NativeBuffer_Reference](#oh_nativebuffer_reference) ([OH_NativeBuffer](#oh_nativebuffer) \*buffer) | Increases the reference count of an **OH_NativeBuffer** instance by 1.| 51| [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.| 52| [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.| 53| [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.| 54| [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.| 55| [OH_NativeBuffer_GetSeqNum](#oh_nativebuffer_getseqnum) ([OH_NativeBuffer](#oh_nativebuffer) \*buffer) | Obtains the sequence number of an **OH_NativeBuffer** instance.| 56 57 58## Type Description 59 60 61### OH_NativeBuffer 62 63 64``` 65typedef struct OH_NativeBuffer OH_NativeBuffer 66``` 67 68**Description** 69 70Provides the declaration of an **OH_NativeBuffer** struct. 71 72## Enum Description 73 74 75### OH_NativeBuffer_Format 76 77``` 78enum OH_NativeBuffer_Format 79``` 80 81**Description** 82 83Enumerates the **OH_NativeBuffer** formats. 84 85\@SysCap SystemCapability.Graphic.Graphic2D.NativeBuffer 86 87| Value| Description| 88| -------- | -------- | 89| NATIVEBUFFER_PIXEL_FMT_RGB_565 | RGB565.| 90| NATIVEBUFFER_PIXEL_FMT_RGBA_5658 | RGBA5658.| 91| NATIVEBUFFER_PIXEL_FMT_RGBX_4444 | RGBX4444.| 92| NATIVEBUFFER_PIXEL_FMT_RGBA_4444 | RGBA4444.| 93| NATIVEBUFFER_PIXEL_FMT_RGB_444 | RGB444.| 94| NATIVEBUFFER_PIXEL_FMT_RGBX_5551 | RGBX5551.| 95| NATIVEBUFFER_PIXEL_FMT_RGBA_5551 | RGBA5551.| 96| NATIVEBUFFER_PIXEL_FMT_RGB_555 | RGB555.| 97| NATIVEBUFFER_PIXEL_FMT_RGBX_8888 | RGBX8888.| 98| NATIVEBUFFER_PIXEL_FMT_RGBA_8888 | RGBA8888.| 99| NATIVEBUFFER_PIXEL_FMT_RGB_888 | RGB888.| 100| NATIVEBUFFER_PIXEL_FMT_BGR_565 | BGR565.| 101| NATIVEBUFFER_PIXEL_FMT_BGRX_4444 | BGRX4444.| 102| NATIVEBUFFER_PIXEL_FMT_BGRA_4444 | BGRA4444.| 103| NATIVEBUFFER_PIXEL_FMT_BGRX_5551 | BGRX5551.| 104| NATIVEBUFFER_PIXEL_FMT_BGRA_5551 | BGRA5551.| 105| NATIVEBUFFER_PIXEL_FMT_BGRX_8888 | BGRX8888.| 106| NATIVEBUFFER_PIXEL_FMT_BGRA_8888 | BGRA8888.| 107| NATIVEBUFFER_PIXEL_FMT_BUTT | Invalid format.| 108 109**Since** 110 11110 112 113 114### OH_NativeBuffer_Usage 115 116``` 117enum OH_NativeBuffer_Usage 118``` 119 120**Description** 121 122Enumerates the **OH_NativeBuffer** usages. 123 124\@SysCap SystemCapability.Graphic.Graphic2D.NativeBuffer 125 126| Value| Description| 127| -------- | -------- | 128| NATIVEBUFFER_USAGE_CPU_READ | Read by the CPU.| 129| NATIVEBUFFER_USAGE_CPU_WRITE | Write by the CPU.| 130| NATIVEBUFFER_USAGE_MEM_DMA | Direct memory access to the buffer.| 131 132**Since** 133 13410 135 136 137## Function Description 138 139 140### OH_NativeBuffer_Alloc() 141 142 143``` 144OH_NativeBuffer* OH_NativeBuffer_Alloc (const OH_NativeBuffer_Config * config) 145``` 146 147**Description** 148 149Creates an **OH_NativeBuffer** instance based on an **OH_NativeBuffer_Config** struct. A new **OH_NativeBuffer** instance is created each time this function is called. 150 151\@syscap SystemCapability.Graphic.Graphic2D.OH_NativeBuffer 152 153**Parameters** 154 155| Name| Description| 156| -------- | -------- | 157| config | Pointer to an **OH_NativeBuffer_Config** instance.| 158 159**Returns** 160 161Returns the pointer to the **OH_NativeBuffer** instance created if the operation is successful; returns **NULL** otherwise. 162 163 164### OH_NativeBuffer_GetConfig() 165 166 167``` 168void OH_NativeBuffer_GetConfig (OH_NativeBuffer * buffer, OH_NativeBuffer_Config * config ) 169``` 170 171**Description** 172 173Obtains the attributes of an **OH_NativeBuffer** instance. 174 175\@syscap SystemCapability.Graphic.Graphic2D.OH_NativeBuffer 176 177**Parameters** 178 179| Name| Description| 180| -------- | -------- | 181| buffer | Pointer to an **OH_NativeBuffer** instance.| 182| config | Pointer to an **OH_NativeBuffer_Config** instance, which is used to receive the attributes of **OH_NativeBuffer**.| 183 184 185### OH_NativeBuffer_GetSeqNum() 186 187 188``` 189uint32_t OH_NativeBuffer_GetSeqNum (OH_NativeBuffer * buffer) 190``` 191 192**Description** 193 194Obtains the sequence number of an **OH_NativeBuffer** instance. 195 196\@syscap SystemCapability.Graphic.Graphic2D.OH_NativeBuffer 197 198**Parameters** 199 200| Name| Description| 201| -------- | -------- | 202| buffer | Pointer to an **OH_NativeBuffer** instance.| 203 204**Returns** 205 206Returns the unique sequence number of the **OH_NativeBuffer** instance. 207 208 209### OH_NativeBuffer_Map() 210 211 212``` 213int32_t OH_NativeBuffer_Map (OH_NativeBuffer * buffer, void ** virAddr ) 214``` 215 216**Description** 217 218Maps the ION memory corresponding to an **OH_NativeBuffer** instance to the process address space. 219 220\@syscap SystemCapability.Graphic.Graphic2D.OH_NativeBuffer 221 222**Parameters** 223 224| Name| Description| 225| -------- | -------- | 226| buffer | Pointer to an **OH_NativeBuffer** instance.| 227| virAddr | Double pointer to the address of the virtual memory.| 228 229**Returns** 230 231Returns **0** if the operation is successful. 232 233 234### OH_NativeBuffer_Reference() 235 236 237``` 238int32_t OH_NativeBuffer_Reference (OH_NativeBuffer * buffer) 239``` 240 241**Description** 242 243Increases the reference count of an **OH_NativeBuffer** instance by 1. 244 245\@syscap SystemCapability.Graphic.Graphic2D.OH_NativeBuffer 246 247**Parameters** 248 249| Name| Description| 250| -------- | -------- | 251| buffer | Pointer to an **OH_NativeBuffer** instance.| 252 253**Returns** 254 255Returns **0** if the operation is successful. 256 257 258### OH_NativeBuffer_Unmap() 259 260 261``` 262int32_t OH_NativeBuffer_Unmap (OH_NativeBuffer * buffer) 263``` 264 265**Description** 266 267Unmaps the ION memory corresponding to an **OH_NativeBuffer** instance from the process address space. 268 269\@syscap SystemCapability.Graphic.Graphic2D.OH_NativeBuffer 270 271**Parameters** 272 273| Name| Description| 274| -------- | -------- | 275| buffer | Pointer to an **OH_NativeBuffer** instance.| 276 277**Returns** 278 279Returns **0** if the operation is successful. 280 281 282### OH_NativeBuffer_Unreference() 283 284 285``` 286int32_t OH_NativeBuffer_Unreference (OH_NativeBuffer * buffer) 287``` 288 289**Description** 290 291Decreases the reference count of an **OH_NativeBuffer** instance by 1 and, when the reference count reaches 0, destroys the instance. 292 293\@syscap SystemCapability.Graphic.Graphic2D.OH_NativeBuffer 294 295**Parameters** 296 297| Name| Description| 298| -------- | -------- | 299| buffer | Pointer to an **OH_NativeBuffer** instance.| 300 301**Returns** 302 303Returns **0** if the operation is successful. 304