• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Image Encoding
2<!--Kit: Image Kit-->
3<!--Subsystem: Multimedia-->
4<!--Owner: @aulight02-->
5<!--SE: @liyang_bryan-->
6<!--TSE: @xchaosioda-->
7
8You 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.
9
10Currently, images can be encoded only into the JPEG, WebP, PNG, or HEIF format (depending on the hardware).
11
12**Usage Scenario**
13
14- Image codec conversion
15
16  Import an image source, and encapsulate it into the desired format.
17- Image editing
18
19  Edit a PixelMap object, and export an image in the desired format.
20
21## How to Develop
22
23Read the [API reference](../../reference/apis-image-kit/capi-image-packer-mdk-h.md) for APIs related to image encoding.
24
25Refer to the code snippet below to complete the entire image encoding process, including creating an encoder, initializing resources, performing encoding, and destroying the encoder.
26
27During application development, you must call the APIs in the defined sequence. Otherwise, an exception or undefined behavior may occur.
28
29The figure below shows the call relationship of image encoding.
30
31![Call relationship of image encoding](figures/image-encode-native.png)
32
33### Linking the Dynamic Library in the CMake Script
34
35``` cmake
36target_link_libraries(sample PUBLIC libimage_packer_ndk.z.so)
37```
38
39### How to Develop
40
411. Add the header file **image_packer_mdk.h**.
42
43   ```cpp
44   // Add the header file image_packer_mdk.h.
45   #include "multimedia/image_framework/image_packer_mdk.h"
46   ```
47
482. Create an encoder instance.
49
50   You must use napi_env to create an encoder.
51
52   ```cpp
53   // Use napi_value to undertake the created encoder instance.
54   napi_value packer;
55   // Use napi_env to create an encoder. If result is IMAGE_RESULT_SUCCESS, the encoder is created.
56   int32_t result = OH_ImagePacker_Create(env, &packer);
57   ```
58
593. Initialize resources.
60
61   Call **OH_ImagePacker_InitNative** to initialize the encoder instance.
62
63   ```cpp
64   // Initialize the instance through napi_env and the created encoder instance.
65   ImagePacker_Native* nativePacker = OH_ImagePacker_InitNative(env, packer);
66   ```
67
684. Perform encoding.
69
70   The following input parameters are provided for the encoding APIs:
71
72   - ImagePacker_Native instance obtained
73
74   - Image source (napi_value), PixelMap object, or ImageSource object (when **CreatePixelMap** is not called yet) to be encoded
75
76   - Encoding parameters, including the encoding format and encoding quality
77
78      > **NOTE**
79      >
80      > According to the MIME protocol, the standard encoding format is image/jpeg. When the APIs provided by the image module are used for encoding, **format** of the encoding parameters must be set to **image/jpeg**. The file name extension of the encoded image file can be .jpg or .jpeg, and the file can be used on platforms that support image/jpeg decoding.
81
82   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.
83
84   Example: output data to the buffer (memory)
85
86   ```cpp
87   // Encoding parameters.
88   struct ImagePacker_Opts_ opts;
89   // (Mandatory) Configure the encoding format.
90   opts.format = "image/jpeg";
91   // (Mandatory) Configure the encoding quality.
92   opts.quality = 100;
93   // Set the output buffer size, for example, to 4 KB.
94   size_t bufferSize = 4*1024;
95   // Apply for a buffer for image encoding.
96   uint8_t* outData = (uint8_t *)(malloc(bufferSize));
97   // 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.
98   int32_t result = OH_ImagePacker_PackToData(nativePacker, source, &opts, outData, &bufferSize);
99   ```
100
101   Example: output data to a file
102
103   ```cpp
104   // Encoding parameters.
105   struct ImagePacker_Opts_ opts;
106   // (Mandatory) Configure the encoding format.
107   opts.format = "image/jpeg";
108   // (Mandatory) Configure the encoding quality.
109   opts.quality = 100;
110   // Open the file to which the data will be written. (Ensure that the application has the permission to access the file path.)
111   int fd = open("/data/test.jpg", O_RDWR | O_CREAT, S_IRUSR | S_IWUSR);
112   if (fd >= 0) {
113      // Start to encode the input source. If IMAGE_RESULT_SUCCESS is returned, the encoding is successful.
114      int32_t result = OH_ImagePacker_PackToFile(nativePacker, source, &opts, fd);
115      // Close the file.
116      close(fd);
117   }
118   ```
119
1205. Destroy the encoder instance and release resources.
121
122   > **NOTE**
123   >
124   > You only need to call the API once.
125
126   ```c++
127   // Call OH_ImagePacker_Release to destroy the encoder.
128   int32_t ret = OH_ImagePacker_Release(nativePacker);
129   if (result != IMAGE_RESULT_SUCCESS) {
130       // Handle exceptions.
131   } else {
132       nativePacker = NULL; // The encoder cannot be destroyed repeatedly.
133   }
134   ```
135