1# NativeBuffer开发指导 (C/C++)
2
3## 场景介绍
4
5NativeBuffer是提供**共享内存**的模块。开发者可以通过`NativeBuffer`接口实现共享内存的申请、使用、属性查询、释放等操作。
6针对NativeBuffer,常见的开发场景如下:
7
8* 通过`NativeBuffer`提供的Native API接口申请`OH_NativeBuffer`实例,获取内存的属性信息,把对应的ION内存映射到进程空间。
9
10## 接口说明
11
12| 接口名 | 描述 |
13| -------- | -------- |
14| OH_NativeBuffer_Alloc (const OH_NativeBuffer_Config \*config) | 通过OH_NativeBuffer_Config创建OH_NativeBuffer实例,每次调用都会产生一个新的OH_NativeBuffer实例。本接口需要与OH_NativeBuffer_Unreference接口配合使用,否则会存在内存泄露。 |
15| OH_NativeBuffer_Reference (OH_NativeBuffer \*buffer) | 将OH_NativeBuffer对象的引用计数增加1。 |
16| OH_NativeBuffer_Unreference (OH_NativeBuffer \*buffer) | 将OH_NativeBuffer对象的引用计数减1,当引用计数为0的时候,该NativeBuffer对象会被析构掉。 |
17| OH_NativeBuffer_GetConfig (OH_NativeBuffer \*buffer, OH_NativeBuffer_Config \*config) | 用于获取OH_NativeBuffer的属性。 |
18| OH_NativeBuffer_Map (OH_NativeBuffer \*buffer, void \*\*virAddr) | 将OH_NativeBuffer对应的ION内存映射到进程空间。 |
19| OH_NativeBuffer_Unmap (OH_NativeBuffer \*buffer) | 将OH_NativeBuffer对应的ION内存从进程空间移除。 |
20| OH_NativeBuffer_GetSeqNum (OH_NativeBuffer \*buffer) | 获取OH_NativeBuffer的序列号。 |
21
22详细的接口说明请参考[native_buffer](../reference/apis-arkgraphics2d/_o_h___native_buffer.md)。
23
24## 开发步骤
25
26以下步骤描述了如何使用`NativeBuffer`提供的Native API接口,创建`OH_NativeBuffer`实例获取内存的属性信息,并把对应的ION内存映射到进程空间。
27
28**添加动态链接库**
29
30CMakeLists.txt中添加以下lib。
31```txt
32libnative_buffer.so
33```
34
35**头文件**
36```c++
37#include <native_buffer/native_buffer.h>
38```
39
401. **创建OH_NativeBuffer实例**。
41    ```c++
42    #include <iostream>
43
44    OH_NativeBuffer_Config config {
45        .width = 0x100,
46        .height = 0x100,
47    };
48    OH_NativeBuffer* buffer = OH_NativeBuffer_Alloc(&config);
49    if (buffer == nullptr) {
50        std::cout << "OH_NativeBuffer_Alloc Failed" << std::endl;
51    }
52    ```
53
542. **将OH_NativeBuffer对应的ION内存映射到进程空间**。
55    应用如需要访问这块buffer的内存空间,需要通过OH_NativeBuffer_Map接口将buffer对应的ION内存映射到进程空间。
56    ```c++
57    // 将ION内存映射到进程空间
58    void* virAddr = nullptr;
59    int32_t ret = OH_NativeBuffer_Map(buffer, &virAddr); // 映射后通过第二个参数virAddr返回内存的首地址
60    if (ret != 0) {
61        std::cout << "OH_NativeBuffer_Map Failed" << std::endl;
62    }
63
64    // 使用后请及时将OH_NativeBuffer对应的ION内存从进程空间移除
65    ret = OH_NativeBuffer_Unmap(buffer);
66    if (ret != 0) {
67        std::cout << "OH_NativeBuffer_Unmap Failed" << std::endl;
68    }
69    ```
70
713. **获取内存的属性信息**。
72    ```c++
73    // 获取OH_NativeBuffer的属性
74    OH_NativeBuffer_Config config2 = {};
75    OH_NativeBuffer_GetConfig(buffer, &config2);
76    // 获取OH_NativeBuffer的序列号
77     uint32_t hwBufferID = OH_NativeBuffer_GetSeqNum(buffer);
78    ```
79
804. **销毁OH_NativeBuffer**。
81    ```c++
82    // 调用OH_NativeBuffer_Unreference引用计数减1,之后buffer的引用计数为0,buffer会销毁
83    ret = OH_NativeBuffer_Unreference(buffer);
84    if (ret != 0) {
85        std::cout << "OH_NativeBuffer_Unreference Failed" << std::endl;
86    }
87    ```