1# Deferred Photo Delivery (C/C++)
2
3As an important feature of the camera, deferred photo delivery enables the system, after receiving a photo capture task from an application, to report images of different quality levels in multiple phases.
4
5- In the first phase, the system promptly delivers an image that has undergone lightweight processing, offering a balance between reduced quality and swift image availability. The application receives a PhotoAsset object through the callback. Through this object, the application can call the media library APIs to read the image or flush the image to the disk.
6- In the second phase, the camera framework enhances the image to achieve full quality, either in response to the application's request for higher quality or when the system is not busy. The enhanced image is then sent back to the media library to replace the previously provided one.
7
8## How to Develop
9
10Read [Camera](../../reference/apis-camera-kit/_o_h___camera.md) for the API reference.
11
121. Import the NDK, which provides camera-related attributes and methods.
13
14   ```c++
15    // Include the NDK header files.
16   #include <cstdint>
17   #include <cstdlib>
18   #include <cstring>
19   #include <string.h>
20   #include <memory>
21   #include "hilog/log.h"
22   #include "napi/native_api.h"
23   #include "camera_manager.h"
24   #include <multimedia/media_library/media_asset_manager_capi.h>
25   #include <multimedia/media_library/media_asset_change_request_capi.h>
26   #include <multimedia/media_library/media_access_helper_capi.h>
27   #include <multimedia/image_framework/image/image_packer_native.h>
28   ```
29
302. Link the dynamic libraries in the CMake script.
31
32   ```txt
33   target_link_libraries(entry PUBLIC
34       libace_napi.z.so
35       libhilog_ndk.z.so
36       libohcamera.so
37       libimage_source.so
38       libmedia_asset_manager.so
39       libimage_packer.so
40   )
41   ```
42
433. Initialize the camera and trigger photo capture. For details, see [Photo Capture (C/C++)](./native-camera-shooting.md).
44
454. Register a deferred photo delivery callback, which is defined as **PhotoAssetAvailable**. Compared with one-time photo capture, only the callback registered is different.
46
47   > **NOTE**
48   >
49   > If the **PhotoAssetAvailable** callback has been registered and the **PhotoAvailable** callback is registered after the session starts, the stream will be restarted. In this case, only the **PhotoAssetAvailable** callback takes effect.
50   >
51   > Therefore, you are not advised to register both **PhotoAssetAvailable** and **PhotoAvailable**.
52
53   Register **PhotoAssetAvailableCallback** to receive images delivered in both phases.
54
55   The development process is as follows:
56
57   - Register the callback before the session commits the configuration.
58   - Obtain a media asset through the callback.
59   - Through the media asset, either save the images or request images and after service processing, save them through a buffer or display them. For details, see step 5 in [Photo Capture (C/C++)](./native-camera-shooting.md).
60   - Unregister the callback when it is no longer required.
61
62   ```c++
63   // Method 1: Call the media library API to save the images.
64   void mediaLibSavePhoto(OH_MediaAsset *mediaAsset) {
65       if (mediaAsset == nullptr) {
66           OH_LOG_ERROR(LOG_APP, "mediaAsset is nullptr!");
67       }
68       // Create a media asset change request object.
69       OH_MediaAssetChangeRequest *changeRequest = OH_MediaAssetChangeRequest_Create(mediaAsset);
70       if (changeRequest == nullptr) {
71           OH_LOG_ERROR(LOG_APP, "changeRequest is nullptr!");
72       }
73       // Request to save the image.
74       MediaLibrary_ErrorCode errCode =
75           OH_MediaAssetChangeRequest_SaveCameraPhoto(changeRequest, MEDIA_LIBRARY_IMAGE_JPEG);
76       OH_LOG_INFO(LOG_APP, "SaveCameraPhoto get errCode:%{public}d", errCode);
77       // Initiate a request.
78       errCode = OH_MediaAccessHelper_ApplyChanges(changeRequest);
79       OH_LOG_INFO(LOG_APP, "ApplyChanges get errCode:%{public}d", errCode);
80   }
81
82   // Method 2: Call the media library API to request images.
83   // Called when the image source is ready.
84   OH_MediaAsset *g_mediaAsset_;
85   void OnImageDataPrepared(MediaLibrary_ErrorCode result, MediaLibrary_RequestId requestId,
86                            MediaLibrary_MediaQuality mediaQuality, MediaLibrary_MediaContentType type,
87                            OH_ImageSourceNative *imageSourceNative) {
88       if (imageSourceNative == nullptr) {
89           OH_LOG_ERROR(LOG_APP, "OnImageDataPrepared: imageSourceNative is nullptr!");
90           return;
91       }
92      if (mediaQuality == MediaLibrary_MediaQuality::MEDIA_LIBRARY_QUALITY_FAST) {
93           OH_LOG_INFO(LOG_APP, "OnImageDataPrepared: Using fast media quality.");
94       } else if (mediaQuality == MediaLibrary_MediaQuality::MEDIA_LIBRARY_QUALITY_FULL) {
95           OH_LOG_INFO(LOG_APP, "OnImageDataPrepared: Using full media quality.");
96       }
97       // Create OH_PixelmapNative through OH_ImageSourceNative.
98       OH_PixelmapNative *pixelmapNative = nullptr;
99       OH_DecodingOptions *decodingOptions = nullptr;
100       Image_ErrorCode imageErr = IMAGE_SUCCESS;
101       imageErr = OH_ImageSourceNative_CreatePixelmap(imageSourceNative, decodingOptions, &pixelmapNative);
102       if (imageErr != IMAGE_SUCCESS) {
103           OH_LOG_ERROR(LOG_APP, "OnImageDataPrepared: CreatePixelmap failed.");
104           return;
105       }
106       // Create an image packer and set packing options.
107       OH_ImagePackerNative *imagePacker;
108       OH_ImagePackerNative_Create(&imagePacker);
109       OH_PackingOptions *options;
110       OH_PackingOptions_Create(&options);
111       char format[] = "image/jpeg";
112       Image_MimeType image_MimeType = {format, strlen(format)};
113       OH_PackingOptions_SetMimeType(options, &image_MimeType);
114       OH_PackingOptions_SetQuality (options, 100); // Highest quality: 100
115       size_t bufferSize = 3072 * 4096; // If a value greater than the size after encoding is passed, a new value will be assigned after encoding.
116       // Parse the image buffer.
117       auto buffer = std::make_unique<uint8_t[]>(bufferSize);
118       imageErr = OH_ImagePackerNative_PackToDataFromPixelmap(imagePacker, options, pixelmapNative, buffer.get(), &bufferSize);
119       OH_LOG_INFO(LOG_APP, "OnImageDataPrepared: packToData ret code:%{public}u outsize:%{public}zu", imageErr, bufferSize);
120       if (g_mediaAsset_ == nullptr) {
121           OH_LOG_ERROR(LOG_APP,  "OnImageDataPrepared: get current mediaAsset failed!");
122       }
123       // Call the media library API to save images in the buffer.
124       OH_MediaAssetChangeRequest *changeRequest = OH_MediaAssetChangeRequest_Create(g_mediaAsset_);
125       MediaLibrary_ErrorCode mediaErr = OH_MediaAssetChangeRequest_AddResourceWithBuffer(changeRequest,
126           MEDIA_LIBRARY_IMAGE_RESOURCE, buffer.get(), bufferSize);
127       OH_LOG_INFO(LOG_APP,  "OnImageDataPrepared: AddResourceWithBuffer get errCode:%{public}d", mediaErr);
128       mediaErr = OH_MediaAssetChangeRequest_SaveCameraPhoto(changeRequest, MEDIA_LIBRARY_IMAGE_JPEG);
129       OH_LOG_INFO(LOG_APP,  "OnImageDataPrepared: SaveCameraPhoto get errCode:%{public}d", mediaErr);
130       mediaErr = OH_MediaAccessHelper_ApplyChanges(changeRequest);
131       OH_LOG_INFO(LOG_APP,  "OnImageDataPrepared: ApplyChanges get errCode:%{public}d", mediaErr);
132   }
133
134   void mediaLibRequestBuffer(Camera_PhotoOutput *photoOutput, OH_MediaAsset *mediaAsset) {
135       if (photoOutput == nullptr) {
136           OH_LOG_ERROR(LOG_APP, "photoOutput is nullptr!");
137       }
138       if (mediaAsset == nullptr) {
139           OH_LOG_ERROR(LOG_APP, "mediaAsset is nullptr!");
140       }
141       // Create a media asset manager.
142       OH_MediaAssetManager *mediaAssetManager = OH_MediaAssetManager_Create();
143       if (mediaAssetManager == nullptr) {
144           OH_LOG_ERROR(LOG_APP, "mediaAssetManager is nullptr!");
145       }
146       // Set the parameters for requesting images.
147       MediaLibrary_RequestOptions requestOptions;
148       // Configure the policy mode based on service requirements to request image assets.
149       // MEDIA_LIBRARY_FAST_MODE: callback for receiving the first-phase image.
150       // MEDIA_LIBRARY_HIGH_QUALITY_MODE: callback for receiving the second-phase image.
151       // MEDIA_LIBRARY_BALANCED_MODE: callback for receiving both images.
152       requestOptions.deliveryMode = MEDIA_LIBRARY_FAST_MODE;
153       MediaLibrary_RequestId requestId;
154       // Request the image asset. Call onImageDataPrepared when it is ready.
155       MediaLibrary_ErrorCode result = OH_MediaAssetManager_RequestImage(mediaAssetManager, mediaAsset, requestOptions, &requestId, OnImageDataPrepared);
156       if (result != MEDIA_LIBRARY_OK) {
157           OH_LOG_ERROR(LOG_APP, "OH_MediaAssetManager_RequestImage failed.");
158       }
159   }
160
161   // Deferred phot delivery callback.
162   void OnPhotoAssetAvailable(Camera_PhotoOutput *photoOutput, OH_MediaAsset *mediaAsset) {
163       OH_LOG_INFO(LOG_APP, "OnPhotoAssetAvailable start!");
164       if (mediaAsset == nullptr) {
165           OH_LOG_ERROR(LOG_APP, "OnPhotoAssetAvailable mediaAsset nullptr!");
166       }
167       // Processing method 1: Call the media library API to save the image in the first phase. After the image in the second phase is ready, the media library proactively replaces the image flushed.
168       //     mediaLibSavePhoto(mediaAsset);
169       // Processing method 2: Call the media library API to request an image asset, obtain the buffer of the first-phase or second-phase image, and save the image in the buffer after service processing.
170       g_mediaAsset_ = mediaAsset;
171       mediaLibRequestBuffer(photoOutput, mediaAsset);
172   }
173
174   // Register the PhotoAssetAvailableCallback callback.
175   Camera_ErrorCode PhotoOutputRegisterPhotoAssetAvailableCallback(Camera_PhotoOutput *photoOutput) {
176       Camera_ErrorCode ret = OH_PhotoOutput_RegisterPhotoAssetAvailableCallback(photoOutput, OnPhotoAssetAvailable);
177       if (ret != CAMERA_OK) {
178           OH_LOG_ERROR("OH_PhotoOutput_RegisterPhotoAssetAvailableCallback failed.");
179       }
180       return ret;
181   }
182   ```
183