• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 图片编码
2<!--Kit: Image Kit-->
3<!--Subsystem: Multimedia-->
4<!--Owner: @aulight02-->
5<!--Designer: @liyang_bryan-->
6<!--Tester: @xchaosioda-->
7<!--Adviser: @zengyawen-->
8
9> **说明：**
10>
11> 当前开发指导使用的接口为[Image](../../reference/apis-image-kit/capi-image.md)模块下的C API，可完成图片编解码，图片接收器，处理图像数据等功能。这部分API在API 11之前发布，在后续的版本不再增加新功能，**不再推荐使用**。<br>
12> 开发者可使用[Image_NativeModule](../../reference/apis-image-kit/capi-image-nativemodule.md)模块下的C API，不仅提供上述图片框架基础功能，还可以完成多图编解码等新特性，相关开发指导请参考[图片开发指导(C/C++)](image-source-c.md)节点下的内容。这部分API从API 12开始支持，并将持续演进，**推荐开发者使用**。<br>
13> 两套C API不建议同时使用，在部分场景下存在不兼容的问题。
14
15开发者可以调用本模块的Native API接口，完成图片编码，即将PixelMap压缩成不同格式的图片文件。
16
17当前支持编码为JPEG、WebP、PNG和 HEIF（不同硬件设备支持情况不同）格式。
18
19**适用场景**
20
21- 图片编码转换。
22
23  通过传入ImageSource，封装成想要的格式。
24- 图片编辑。
25
26  编辑PixelMap后导出图片文件的场景，需要编码成对应图片格式文件。
27
28## 开发指导
29
30详细的API说明请参考[ImagePacker API参考](../../reference/apis-image-kit/capi-image-packer-mdk-h.md)。
31
32参考以下示例代码，完成图片编码的全流程，包括：创建编码器、初始化资源、编码过程、销毁资源。
33
34在应用开发过程中，开发者应按一定顺序调用方法，执行对应操作，否则系统可能会抛出异常或生成其他未定义的行为。具体顺序可参考下列开发步骤及对应说明。
35
36如下为图片编码调用关系图：
37
38![Invoking relationship of image native encode](figures/image-encode-native.png)
39
40### 在 CMake 脚本中链接动态库
41
42``` cmake
43target_link_libraries(sample PUBLIC libimage_packer_ndk.z.so)
44```
45
46### 开发步骤
47
481. 引入编码器头文件：image_packer_mdk.h。
49
50   ```cpp
51   // 引入编码器image_packer_mdk.h头文件。
52   #include "multimedia/image_framework/image_packer_mdk.h"
53   ```
54
552. 创建编码器实例对象。
56
57   应用需要napi_env来创建编码器。
58
59   ```cpp
60   // 使用napi_value 承接创建的编码器对象。
61   napi_value packer;
62   // 通过 napi_env 创建编码器，返回result为 IMAGE_RESULT_SUCCESS则创建成功。
63   int32_t result = OH_ImagePacker_Create(env, &packer);
64   ```
65
663. 初始化资源。
67
68   通过OH_ImagePacker_InitNative来初始化编码器实例对象。
69
70   ```cpp
71   // 通过 napi_env 及上述创建的编码器对象初始化实例对象。
72   ImagePacker_Native* nativePacker = OH_ImagePacker_InitNative(env, packer);
73   ```
74
754. 编码。
76
77   编码接口入参包括：
78
79   - 上述过程中获取的实例对象（ImagePacker_Native）。
80
81   - 需要编码的图像源（napi_value）, PixelMap或ImageSource（未调用过CreatePixelMap）的实例对象均可。
82
83   - 编码参数：包括编码格式与编码质量。
84
85      > **说明：**
86      > 根据MIME标准，标准编码格式为image/jpeg。当使用image编码时，编码参数中的编码格式format设置为image/jpeg，image编码后的文件扩展名可设为.jpg或.jpeg，可在支持image/jpeg解码的平台上使用。
87
88   编码接口可按输出方式分为向缓存区（内存）输出和向文件输出两种接口，入参均为上述内容。
89   应用可根据输出的不同需求选择编码接口。
90
91   例如向缓存区（内存）输出：
92
93   ```cpp
94   // 编码参数。
95   struct ImagePacker_Opts_ opts;
96   // 配置编码格式（必须）。
97   opts.format = "image/jpeg";
98   // 配置编码质量（必须）。
99   opts.quality = 100;
100   // 配置输出的缓存区大小为4k（缓存区大小视应用场景定）。
101   size_t bufferSize = 4*1024;
102   // 申请图片编码缓存区。
103   uint8_t* outData = (uint8_t *)(malloc(bufferSize));
104   // 开始对输入source进行编码过程，返回result为 IMAGE_RESULT_SUCCESS则编码成功，同时bufferSize中包含编码实际使用缓存区大小。
105   int32_t result = OH_ImagePacker_PackToData(nativePacker, source, &opts, outData, &bufferSize);
106   ```
107
108   例如向文件输出：
109
110   ```cpp
111   // 编码参数。
112   struct ImagePacker_Opts_ opts;
113   // 配置编码格式（必须）。
114   opts.format = "image/jpeg";
115   // 配置编码质量（必须）。
116   opts.quality = 100;
117   // 打开需要输出的文件（请确保应用有权限访问这个路径）。
118   int fd = open("/data/test.jpg", O_RDWR | O_CREAT, S_IRUSR | S_IWUSR);
119   if (fd >= 0) {
120      // 开始对输入source进行编码过程，返回result为 IMAGE_RESULT_SUCCESS则编码成功。
121      int32_t result = OH_ImagePacker_PackToFile(nativePacker, source, &opts, fd);
122      // 关闭输出文件。
123      close(fd);
124   }
125   ```
126
1275. 销毁编码器实例，释放资源。
128
129   > **说明**：
130   > 资源不能重复销毁。
131
132   ```c++
133   // 调用OH_ImagePacker_Release, 销毁编码器。
134   int32_t ret = OH_ImagePacker_Release(nativePacker);
135   if (result != IMAGE_RESULT_SUCCESS) {
136       // 异常处理。
137   } else {
138       nativePacker = NULL; //不可重复destroy。
139   }
140   ```
141