1# Native Buffer Development (C/C++) 2 3## When to Use 4 5The native buffer module provides APIs that you can use to apply for, use, and release the shared memory, and query memory properties. 6 7The following scenario is common for native buffer development: 8 9Use the native buffer APIs to create an **OH_NativeBuffer** instance, obtain memory properties, and map the corresponding ION memory to the process address space. 10 11## Available APIs 12 13| API| Description| 14| -------- | -------- | 15| OH_NativeBuffer_Alloc (const OH_NativeBuffer_Config \*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.| 16| OH_NativeBuffer_Reference (OH_NativeBuffer \*buffer) | Increases the reference count of an **OH_NativeBuffer** instance by 1.| 17| OH_NativeBuffer_Unreference (OH_NativeBuffer \*buffer) | Decreases the reference count of an **OH_NativeBuffer** instance by 1 and, when the reference count reaches 0, destroys the instance.| 18| OH_NativeBuffer_GetConfig (OH_NativeBuffer \*buffer, OH_NativeBuffer_Config \*config) | Obtains the properties of an **OH_NativeBuffer** instance.| 19| OH_NativeBuffer_Map (OH_NativeBuffer \*buffer, void \*\*virAddr) | Maps the ION memory allocated to an **OH_NativeBuffer** instance to the process address space.| 20| OH_NativeBuffer_Unmap (OH_NativeBuffer \*buffer) | Unmaps the ION memory allocated to an **OH_NativeBuffer** instance from the process address space.| 21| OH_NativeBuffer_GetSeqNum (OH_NativeBuffer \*buffer) | Obtains the sequence number of an **OH_NativeBuffer** instance.| 22 23For details about the APIs, see [native_buffer](../reference/apis-arkgraphics2d/_o_h___native_buffer.md). 24 25## How to Develop 26 27The following describes how to use the aforementioned APIs to create an **OH_NativeBuffer** instance, obtain memory properties, and map the corresponding ION memory to the process address space. 28 29**Adding Dynamic Link Libraries** 30 31Add the following library to **CMakeLists.txt**: 32```txt 33libnative_buffer.so 34``` 35 36**Including Header Files** 37```c++ 38#include <native_buffer/native_buffer.h> 39``` 40 411. Create an **OH_NativeBuffer** instance. 42 ```c++ 43 #include <iostream> 44 45 OH_NativeBuffer_Config config { 46 .width = 0x100, 47 .height = 0x100, 48 }; 49 OH_NativeBuffer* buffer = OH_NativeBuffer_Alloc(&config); 50 if (buffer == nullptr) { 51 std::cout << "OH_NativeBuffer_Alloc Failed" << std::endl; 52 } 53 ``` 54 552. If the application needs to access the memory space of the **OH_NativeBuffer** instance, map the ION memory allocated to the instance to the process address space by calling **OH_NativeBuffer_Map**. 56 ```c++ 57 // Map the ION memory to the process address space. 58 void* virAddr = nullptr; 59 int32_t ret = OH_NativeBuffer_Map(buffer, &virAddr); // After mapping, the start address of the memory is returned through the parameter virAddr. 60 if (ret != 0) { 61 std::cout << "OH_NativeBuffer_Map Failed" << std::endl; 62 } 63 64 // Unmap the ION memory from the process address space when it is no longer needed. 65 ret = OH_NativeBuffer_Unmap(buffer); 66 if (ret != 0) { 67 std::cout << "OH_NativeBuffer_Unmap Failed" << std::endl; 68 } 69 ``` 70 713. Obtain the memory properties. 72 ```c++ 73 // Obtain the properties of the OH_NativeBuffer instance. 74 OH_NativeBuffer_Config config2 = {}; 75 OH_NativeBuffer_GetConfig(buffer, &config2); 76 // Obtain the sequence number of the OH_NativeBuffer instance. 77 uint32_t hwBufferID = OH_NativeBuffer_GetSeqNum(buffer); 78 ``` 79 804. Destroy the **OH_NativeBuffer** instance. 81 ```c++ 82 // Call OH_NativeBuffer_Unreference to decrease the reference count by 1. When the reference count reaches 0, the instance is destroyed. 83 ret = OH_NativeBuffer_Unreference(buffer); 84 if (ret != 0) { 85 std::cout << "OH_NativeBuffer_Unreference Failed" << std::endl; 86 } 87 ``` 88