• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Using Image_NativeModule to Receive Images
2<!--Kit: Image Kit-->
3<!--Subsystem: Multimedia-->
4<!--Owner: @aulight02-->
5<!--SE: @liyang_bryan-->
6<!--TSE: @xchaosioda-->
7
8You can use the **ImageReceiver** class to obtain the surface ID of a component, read the latest image or the next image, and release ImageReceiver instances. For details about the sample code of camera preview implemented with the use of the camera API, see [Secondary Processing of Preview Streams (C/C++)](../camera/native-camera-preview-imageReceiver.md).
9
10> **NOTE**
11>
12> The ImageReceiver merely serves as the recipient and consumer of images. The properties set in ImageReceiver, such as size and format, do not actually take effect. Image properties need to be configured on the sending side (the producer), such as when setting up the preview profiles for a [preview stream (C/C++)](../camera/native-camera-preview.md).
13
14## How to Develop
15
16### Adding Dependencies
17
18Open the **src/main/cpp/CMakeLists.txt** file of the native project, add **libohimage.so**, **libimage_receiver.so**, **libnative_image.so**, and **libhilog_ndk.z.so** (on which the log APIs depend) to the **target_link_libraries** dependency.
19
20```txt
21target_link_libraries(entry PUBLIC libhilog_ndk.z.so libohimage.so libimage_receiver.so libnative_image.so)
22```
23
24### Calling the Native APIs
25
26For details about the APIs, see [Image_NativeModule](../../reference/apis-image-kit/capi-image-nativemodule.md).
27
28Create a native C++ application in DevEco Studio. The project created by default contains the **index.ets** file, and a **hello.cpp** or **napi_init.cpp** file is generated in the **entry\src\main\cpp** directory. In this example, the generated file is **hello.cpp**. Implement the C APIs in **hello.cpp**. Refer to the sample code below.
29
30```c++
31#include <hilog/log.h>
32#include <multimedia/image_framework/image/image_native.h>
33#include <multimedia/image_framework/image/image_receiver_native.h>
34
35#undef LOG_DOMAIN
36#define LOG_DOMAIN 0x3200
37
38#undef LOG_TAG
39#define LOG_TAG "MY_TAG"
40
41#define IMAGE_WIDTH 320
42#define IMAGE_HEIGHT 480
43#define IMAGE_CAPACITY 2
44
45static OH_ImageReceiverNative* receiver = nullptr;
46static OH_ImageReceiverOptions* options = nullptr;
47
48static void OnCallback(OH_ImageReceiverNative *receiver)
49{
50    // Callback for processing the received image data.
51    OH_LOG_INFO(LOG_APP, "ImageReceiverNativeCTest buffer avaliable.");
52
53    // Read the next image object of OH_ImageReceiverNative.
54    OH_ImageNative* image = nullptr;
55    Image_ErrorCode errCode = OH_ImageReceiverNative_ReadNextImage(receiver, &image);
56    // You can also call OH_ImageReceiverNative_ReadLatestImage to obtain image data.
57    if (errCode != IMAGE_SUCCESS) {
58        OH_LOG_ERROR(LOG_APP, "ImageReceiverNativeCTest get image receiver next image failed, errCode: %{public}d.", errCode);
59        OH_ImageReceiverOptions_Release(options);
60        OH_ImageReceiverNative_Release(receiver);
61        return;
62    }
63
64    // The application processes the image data.
65    // ...
66
67    // Release the OH_ImageNative instance.
68    errCode = OH_ImageNative_Release(image);
69    if (errCode != IMAGE_SUCCESS) {
70        OH_LOG_ERROR(LOG_APP, "ImageReceiverNativeCTest release image native failed, errCode: %{public}d.", errCode);
71    }
72}
73
74static void ImageReceiverNativeCTest()
75{
76    // Create an OH_ImageReceiverOptions instance.
77    Image_ErrorCode errCode = OH_ImageReceiverOptions_Create(&options);
78    if (errCode != IMAGE_SUCCESS) {
79        OH_LOG_ERROR(LOG_APP, "ImageReceiverNativeCTest create image receiver options failed, errCode: %{public}d.", errCode);
80        return;
81    }
82
83    Image_Size imgSize;
84    imgSize.width = IMAGE_WIDTH;
85    imgSize.height = IMAGE_HEIGHT;
86
87    // Set the size property in OH_ImageReceiverOptions. This property is a mandatory input parameter and does not actually take effect. Image properties are determined by the producer, for example, the camera.
88    errCode = OH_ImageReceiverOptions_SetSize(options, imgSize);
89    if (errCode != IMAGE_SUCCESS) {
90        OH_LOG_ERROR(LOG_APP, "ImageReceiverNativeCTest set image receiver options size failed, errCode: %{public}d.", errCode);
91        OH_ImageReceiverOptions_Release(options);
92        return;
93    }
94
95    // Set the capacity property of OH_ImageReceiverOptions.
96    errCode = OH_ImageReceiverOptions_SetCapacity(options, IMAGE_CAPACITY);
97    if (errCode != IMAGE_SUCCESS) {
98        OH_LOG_ERROR(LOG_APP, "ImageReceiverNativeCTest set image receiver options capacity failed, errCode: %{public}d.", errCode);
99        OH_ImageReceiverOptions_Release(options);
100        return;
101    }
102
103    // Read the size property in OH_ImageReceiverOptions. This property does not actually take effect. Image properties are determined by the producer, for example, the camera.
104    Image_Size imgSizeRead;
105    errCode = OH_ImageReceiverOptions_GetSize(options, &imgSizeRead);
106    if (errCode != IMAGE_SUCCESS) {
107        OH_LOG_ERROR(LOG_APP, "ImageReceiverNativeCTest get image receiver options size failed, errCode: %{public}d.", errCode);
108        OH_ImageReceiverOptions_Release(options);
109        return;
110    }
111
112    // Check whether the size read is the preset value. The size read does not take effect actually. The image width and height are determined by the producer, for example, the camera.
113    if (imgSizeRead.width != IMAGE_WIDTH || imgSizeRead.height != IMAGE_HEIGHT) {
114        OH_LOG_ERROR(LOG_APP, "ImageReceiverNativeCTest get image receiver options size failed, width: %{public}d, height: %{public}d.", imgSizeRead.width, imgSizeRead.height);
115        OH_ImageReceiverOptions_Release(options);
116        return;
117    }
118
119    // Read the capacity attribute of OH_ImageReceiverOptions.
120    int32_t capacity = 0;
121    errCode = OH_ImageReceiverOptions_GetCapacity(options, &capacity);
122    if (errCode != IMAGE_SUCCESS) {
123        OH_LOG_ERROR(LOG_APP, "ImageReceiverNativeCTest get image receiver options capacity failed, errCode: %{public}d.", errCode);
124        OH_ImageReceiverOptions_Release(options);
125        return;
126    }
127
128    // Check whether the capacity read is the same as the capacity set.
129    if (capacity != IMAGE_CAPACITY) {
130        OH_LOG_ERROR(LOG_APP, "ImageReceiverNativeCTest get image receiver options capacity failed, capacity: %{public}d.", capacity);
131        OH_ImageReceiverOptions_Release(options);
132        return;
133    }
134
135    // Create an OH_ImageReceiverNative instance.
136    errCode = OH_ImageReceiverNative_Create(options, &receiver);
137    if (errCode != IMAGE_SUCCESS) {
138        OH_LOG_ERROR(LOG_APP, "ImageReceiverNativeCTest create image receiver failed, errCode: %{public}d.", errCode);
139        OH_ImageReceiverOptions_Release(options);
140        return;
141    }
142
143    // Register a callback event. Each time a new image is received, the callback event is triggered.
144    uint64_t surfaceID = 0;
145    errCode = OH_ImageReceiverNative_On(receiver, OnCallback);
146    if (errCode != IMAGE_SUCCESS) {
147        OH_LOG_ERROR(LOG_APP, "ImageReceiverNativeCTest image receiver on failed, errCode: %{public}d.", errCode);
148        OH_ImageReceiverOptions_Release(options);
149        OH_ImageReceiverNative_Release(receiver);
150        return;
151    }
152
153    // Read the surface ID attribute of OH_ImageReceiverNative.
154    errCode = OH_ImageReceiverNative_GetReceivingSurfaceId(receiver, &surfaceID);
155    if (errCode != IMAGE_SUCCESS) {
156        OH_LOG_ERROR(LOG_APP, "ImageReceiverNativeCTest get image receiver surfaceID failed, errCode: %{public}d.", errCode);
157        OH_ImageReceiverOptions_Release(options);
158        OH_ImageReceiverNative_Release(receiver);
159        return;
160    }
161    OH_LOG_INFO(LOG_APP, "ImageReceiverNativeCTest get image receiver surfaceID: %{public}llu.", surfaceID);
162
163    // Read the size attribute of OH_ImageReceiverNative.
164    errCode = OH_ImageReceiverNative_GetSize(receiver, &imgSizeRead);
165    if (errCode != IMAGE_SUCCESS) {
166        OH_LOG_ERROR(LOG_APP, "ImageReceiverNativeCTest get image receiver size failed, errCode: %{public}d.", errCode);
167        OH_ImageReceiverOptions_Release(options);
168        OH_ImageReceiverNative_Release(receiver);
169        return;
170    }
171    OH_LOG_INFO(LOG_APP, "ImageReceiverNativeCTest get image receiver size: width = %{public}d, height = %{public}d.", imgSizeRead.width, imgSizeRead.height);
172
173    // Read the capacity attribute of OH_ImageReceiverNative.
174    errCode = OH_ImageReceiverNative_GetCapacity(receiver, &capacity);
175    if (errCode != IMAGE_SUCCESS) {
176        OH_LOG_ERROR(LOG_APP, "ImageReceiverNativeCTest get image receiver capacity failed, errCode: %{public}d.", errCode);
177        OH_ImageReceiverOptions_Release(options);
178        OH_ImageReceiverNative_Release(receiver);
179        return;
180    }
181    OH_LOG_INFO(LOG_APP, "ImageReceiverNativeCTest get image receiver capacity: %{public}d.", capacity);
182
183    // Release the OH_ImageReceiverOptions instance.
184    errCode = OH_ImageReceiverOptions_Release(options);
185    if (errCode != IMAGE_SUCCESS) {
186        OH_LOG_ERROR(LOG_APP, "ImageReceiverNativeCTest release image receiver options failed, errCode: %{public}d.", errCode);
187    }
188}
189
190// Release ImageReceiverNative resources at a proper time.
191static void ImageReceiverRelease()
192{
193    // Unregister the callback event registered by calling OH_ImageReceiverNative_On.
194    Image_ErrorCode errCode = OH_ImageReceiverNative_Off(receiver);
195    if (errCode != IMAGE_SUCCESS) {
196        OH_LOG_ERROR(LOG_APP, "ImageReceiverNativeCTest image receiver off failed, errCode: %{public}d.", errCode);
197    }
198
199    // Release the OH_ImageReceiverOptions instance.
200    errCode = OH_ImageReceiverNative_Release(receiver);
201    if (errCode != IMAGE_SUCCESS) {
202        OH_LOG_ERROR(LOG_APP, "ImageReceiverNativeCTest release image receiver failed, errCode: %{public}d.", errCode);
203    }
204}
205```
206