• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Image Encoding (C/C++)
2
3You can call the native APIs provided by the **ImagePacker** module to encode images, that is, to compress a **PixelMap** object into an image in the desired format.
4
5Currently, JPEG, WebP, and PNG encoding formats are supported.
6
7**Usage Scenario**
8
9- Image codec conversion
10
11  Import an image source, and encapsulate it into the desired format.
12- Image editing
13
14  Edit a **PixelMap** object, and export an image in the desired format.
15
16## How to Develop
17
18Read [ImagePacker](../reference/apis-image-kit/image__packer__mdk_8h.md) for the API reference.
19
20Refer to the code snippet below to complete the entire image encoding process, including creating an encoder, initializing resources, performing encoding, and destroying the encoder.
21
22During application development, you must call the APIs in the defined sequence. Otherwise, an exception or undefined behavior may occur.
23
24The figure below shows the call relationship of image encoding.
25
26![Call relationship of image encoding](figures/image-encode-native.png)
27
28### Linking the Dynamic Library in the CMake Script
29
30``` cmake
31target_link_libraries(sample PUBLIC libimage_packer_ndk.z.so)
32```
33
34### How to Develop
35
361. Add the header file **image_packer_mdk.h**.
37
38   ```cpp
39   // Add the header file image_packer_mdk.h.
40   #include "multimedia/image_framework/image_packer_mdk.h"
41   ```
422. Create an encoder instance.
43
44   You must use napi_env to create an encoder.
45
46   ```cpp
47   // Use napi_value to undertake the created encoder instance.
48   napi_value packer;
49   // Use napi_env to create an encoder. If result is IMAGE_RESULT_SUCCESS, the encoder is created.
50   int32_t result = OH_ImagePacker_Create(env, packer);
51   ```
523. Initialize resources.
53
54   Call **OH_ImagePacker_InitNative** to initialize the native encoder instance.
55
56   ```cpp
57   // Initialize the native instance through napi_env and the created encoder instance.
58   ImagePacker_Native* nativePacker = OH_ImagePacker_InitNative(env, packer);
59   ```
604. Perform encoding.
61
62   The following input parameters are provided for the encoding APIs:
63
64   - **ImagePacker_Native** instance obtained
65
66   - Image source (napi_value), **PixelMap** object, or** ImageSource** object (when **CreatePixelMap** is not called yet) to be encoded
67
68   - Encoding parameters, including the encoding format and encoding quality
69
70
71   The encoding APIs can output data to the buffer (memory) or a file. They have the same input parameters, as described previously. You can select either of them as required.
72
73   Example: output data to the buffer (memory)
74   ```cpp
75   // Encoding parameters
76   struct ImagePacker_Opts opts;
77   // (Mandatory) Configure the encoding format.
78   opts.format = "image/jpeg";
79   // (Mandatory) Configure the encoding quality.
80   opts.quality = 100;
81   // Set the output buffer size, for example, to 4 KB.
82   size_t bufferSize = 4*1024;
83   // Apply for a buffer for image encoding.
84   uint8_t* outData = (uint8_t *)(malloc(bufferSize));
85   // Start to encode the input source. If IMAGE_RESULT_SUCCESS is returned, the encoding is successful. In this case, bufferSize indicates the size of the buffer used for encoding.
86   int32_t result = OH_ImagePacker_PackToData(nativePacker, source, &opts, outData, &bufferSize);
87   ```
88   Example: output data to a file
89   ```cpp
90   // Encoding parameters
91   struct ImagePacker_Opts opts;
92   // (Mandatory) Configure the encoding format.
93   opts.format = "image/jpeg";
94   // (Mandatory) Configure the encoding quality.
95   opts.quality = 100;
96   // Open the file to which the data will be written. (Ensure that the application has the permission to access the file path.)
97   int fd = open("/data/test.jpg", O_RDWR | O_CREAT, S_IRUSR | S_IWUSR);
98   if (fd >= 0) {
99      // Start to encode the input source. If IMAGE_RESULT_SUCCESS is returned, the encoding is successful.
100      int32_t result = OH_ImagePacker_PackToFile(nativePacker, source, &opts, fd);
101      // Close the file.
102      close(fd);
103   }
104   ```
1055. Destroy the encoder instance and release resources.
106
107   > **NOTE**
108   >
109   > You only need to call the API once.
110
111   ```c++
112   // Call OH_ImagePacker_Release to destroy the encoder.
113   int32_t ret = OH_ImagePacker_Release(nativePacker);
114   if (result != IMAGE_RESULT_SUCCESS) {
115       // Exception handling.
116   } else {
117       nativePacker = NULL; // The encoder cannot be destroyed repeatedly.
118   }
119   ```
120