1/*
2 * Copyright (C) 2023 Huawei Device Co., Ltd.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 *     http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16/**
17 * @addtogroup OH_Camera
18 * @{
19 *
20 * @brief Provide the definition of the C interface for the camera module.
21 *
22 * @syscap SystemCapability.Multimedia.Camera.Core
23 *
24 * @since 11
25 * @version 1.0
26 */
27
28/**
29 * @file photo_output.h
30 *
31 * @brief Declare the photo output concepts.
32 *
33 * @library libohcamera.so
34 * @kit CameraKit
35 * @syscap SystemCapability.Multimedia.Camera.Core
36 * @since 11
37 * @version 1.0
38 */
39
40#ifndef NATIVE_INCLUDE_CAMERA_PHOTOOUTPUT_H
41#define NATIVE_INCLUDE_CAMERA_PHOTOOUTPUT_H
42
43#include <stdint.h>
44#include <stdio.h>
45#include "camera.h"
46#include "photo_native.h"
47#include "multimedia/media_library/media_asset_base_capi.h"
48
49#ifdef __cplusplus
50extern "C" {
51#endif
52
53/**
54 * @brief Photo output object
55 *
56 * A pointer can be created using {@link Camera_PhotoOutput} method.
57 *
58 * @since 11
59 * @version 1.0
60 */
61typedef struct Camera_PhotoOutput Camera_PhotoOutput;
62
63/**
64 * @brief Photo output frame start callback to be called in {@link PhotoOutput_Callbacks}.
65 *
66 * @param photoOutput the {@link Camera_PhotoOutput} which deliver the callback.
67 * @since 11
68 */
69typedef void (*OH_PhotoOutput_OnFrameStart)(Camera_PhotoOutput* photoOutput);
70
71/**
72 * @brief Photo output frame shutter callback to be called in {@link PhotoOutput_Callbacks}.
73 *
74 * @param photoOutput the {@link Camera_PhotoOutput} which deliver the callback.
75 * @param info the {@link Camera_FrameShutterInfo} which delivered by the callback.
76 * @since 11
77 */
78typedef void (*OH_PhotoOutput_OnFrameShutter)(Camera_PhotoOutput* photoOutput, Camera_FrameShutterInfo* info);
79
80/**
81 * @brief Photo output frame end callback to be called in {@link PhotoOutput_Callbacks}.
82 *
83 * @param photoOutput the {@link Camera_PhotoOutput} which deliver the callback.
84 * @param frameCount the frame count which delivered by the callback.
85 * @since 11
86 */
87typedef void (*OH_PhotoOutput_OnFrameEnd)(Camera_PhotoOutput* photoOutput, int32_t frameCount);
88
89/**
90 * @brief Photo output error callback to be called in {@link PhotoOutput_Callbacks}.
91 *
92 * @param photoOutput the {@link Camera_PhotoOutput} which deliver the callback.
93 * @param errorCode the {@link Camera_ErrorCode} of the photo output.
94 *
95 * @see CAMERA_SERVICE_FATAL_ERROR
96 * @since 11
97 */
98typedef void (*OH_PhotoOutput_OnError)(Camera_PhotoOutput* photoOutput, Camera_ErrorCode errorCode);
99
100/**
101 * @brief Photo output capture end callback.
102 *
103 * @param photoOutput the {@link Camera_PhotoOutput} which deliver the callback.
104 * @param frameCount the frameCount which is delivered by the callback.
105 * @since 12
106 */
107typedef void (*OH_PhotoOutput_CaptureEnd) (Camera_PhotoOutput* photoOutput, int32_t frameCount);
108
109/**
110 * @brief Photo output capture start with infomation callback.
111 *
112 * @param photoOutput the {@link Camera_PhotoOutput} which deliver the callback.
113 * @param Info the {@link Camera_CaptureStartInfo} which is delivered by the callback..
114 * @since 12
115 */
116typedef void (*OH_PhotoOutput_CaptureStartWithInfo) (Camera_PhotoOutput* photoOutput, Camera_CaptureStartInfo* Info);
117
118/**
119 * @brief Photo output eframe shutter end callback.
120 *
121 * @param photoOutput the {@link Camera_PhotoOutput} which deliver the callback.
122 * @param Info the {@link Camera_CaptureStartInfo} which is delivered by the callback.
123 * @since 12
124 */
125typedef void (*OH_PhotoOutput_OnFrameShutterEnd) (Camera_PhotoOutput* photoOutput, Camera_FrameShutterInfo* Info);
126
127/**
128 * @brief Photo output capture ready callback.
129 *
130 * @param photoOutput the {@link Camera_PhotoOutput} which deliver the callback.
131 * @since 12
132 */
133typedef void (*OH_PhotoOutput_CaptureReady) (Camera_PhotoOutput* photoOutput);
134
135/**
136 * @brief Photo output estimated capture duration callback.
137 *
138 * @param photoOutput the {@link Camera_PhotoOutput} which deliver the callback.
139 * @param duration the duration which is delivered by the callback.
140 * @since 12
141 */
142typedef void (*OH_PhotoOutput_EstimatedCaptureDuration) (Camera_PhotoOutput* photoOutput, int64_t duration);
143
144/**
145 * @brief Photo output available high-resolution images callback.
146 *
147 * @param photoOutput the {@link Camera_PhotoOutput} which deliver the callback.
148 * @param photo the {@link OH_PhotoNative} which delivered by the callback.
149 * @since 12
150 */
151typedef void (*OH_PhotoOutput_PhotoAvailable)(Camera_PhotoOutput* photoOutput, OH_PhotoNative* photo);
152
153/**
154 * @brief Photo output photo asset available callback.
155 *
156 * @param photoOutput the {@link Camera_PhotoOutput} which deliver the callback.
157 * @param photoAsset the {@link OH_MediaAsset} which delivered by the callback.
158 * @since 12
159 */
160typedef void (*OH_PhotoOutput_PhotoAssetAvailable)(Camera_PhotoOutput* photoOutput, OH_MediaAsset* photoAsset);
161
162/**
163 * @brief A listener for photo output.
164 *
165 * @see OH_PhotoOutput_RegisterCallback
166 * @since 11
167 * @version 1.0
168 */
169typedef struct PhotoOutput_Callbacks {
170    /**
171     * Photo output frame start event.
172     */
173    OH_PhotoOutput_OnFrameStart onFrameStart;
174
175    /**
176     * Photo output frame shutter event.
177     */
178    OH_PhotoOutput_OnFrameShutter onFrameShutter;
179
180    /**
181     * Photo output frame end event.
182     */
183    OH_PhotoOutput_OnFrameEnd onFrameEnd;
184
185    /**
186     * Photo output error event.
187     */
188    OH_PhotoOutput_OnError onError;
189} PhotoOutput_Callbacks;
190
191/**
192 * @brief Register photo output change event callback.
193 *
194 * @param photoOutput the {@link Camera_PhotoOutput} instance.
195 * @param callback the {@link PhotoOutput_Callbacks} to be registered.
196 * @return {@link #CAMERA_OK} if the method call succeeds.
197 *         {@link #INVALID_ARGUMENT} if parameter missing or parameter type incorrect.
198 * @since 11
199 */
200Camera_ErrorCode OH_PhotoOutput_RegisterCallback(Camera_PhotoOutput* photoOutput, PhotoOutput_Callbacks* callback);
201
202/**
203 * @brief Unregister photo output change event callback.
204 *
205 * @param photoOutput the {@link Camera_PhotoOutput} instance.
206 * @param callback the {@link PhotoOutput_Callbacks} to be unregistered.
207 * @return {@link #CAMERA_OK} if the method call succeeds.
208 *         {@link #INVALID_ARGUMENT} if parameter missing or parameter type incorrect.
209 * @since 11
210 */
211Camera_ErrorCode OH_PhotoOutput_UnregisterCallback(Camera_PhotoOutput* photoOutput, PhotoOutput_Callbacks* callback);
212
213/**
214 * @brief Register capture start event callback.
215 *
216 * @param photoOutput the {@link Camera_PhotoOutput} instance.
217 * @param callback the {@link OH_PhotoOutput_CaptureStartWithInfo} to be registered.
218 * @return {@link #CAMERA_OK} if the method call succeeds.
219 *         {@link #CAMERA_INVALID_ARGUMENT} if parameter missing or parameter type incorrect.
220 * @since 12
221 */
222Camera_ErrorCode OH_PhotoOutput_RegisterCaptureStartWithInfoCallback(Camera_PhotoOutput* photoOutput,
223    OH_PhotoOutput_CaptureStartWithInfo callback);
224
225/**
226 * @brief Gets the photo rotation angle.
227 *
228 * @param photoOutput the {@link Camera_PhotoOutput} instance which used to get the photo rotation angle.
229 * @param deviceDegree the current device rotation degree.
230 * @param imageRotation the {@link Camera_ImageRotation} result of photo rotation angle.
231 * @return {@link #CAMERA_OK} if the method call succeeds.
232 *         {@link #CAMERA_INVALID_ARGUMENT} if parameter missing or parameter type incorrect.
233 *         {@link #CAMERA_SERVICE_FATAL_ERROR} if camera service fatal error.
234 * @since 12
235 */
236Camera_ErrorCode OH_PhotoOutput_GetPhotoRotation(Camera_PhotoOutput* photoOutput, int deviceDegree,
237    Camera_ImageRotation* imageRotation);
238
239/**
240 * @brief Unregister capture start event callback.
241 *
242 * @param photoOutput the {@link Camera_PhotoOutput} instance.
243 * @param callback the {@link OH_PhotoOutput_CaptureStartWithInfo} to be unregistered.
244 * @return {@link #CAMERA_OK} if the method call succeeds.
245 *         {@link #CAMERA_INVALID_ARGUMENT} if parameter missing or parameter type incorrect.
246 * @since 12
247 */
248Camera_ErrorCode OH_PhotoOutput_UnregisterCaptureStartWithInfoCallback(Camera_PhotoOutput* photoOutput,
249    OH_PhotoOutput_CaptureStartWithInfo callback);
250
251/**
252 * @brief Register capture end event callback.
253 *
254 * @param photoOutput the {@link Camera_PhotoOutput} instance.
255 * @param callback the {@link OH_PhotoOutput_CaptureEnd} to be registered.
256 * @return {@link #CAMERA_OK} if the method call succeeds.
257 *         {@link #CAMERA_INVALID_ARGUMENT} if parameter missing or parameter type incorrect.
258 * @since 12
259 */
260Camera_ErrorCode OH_PhotoOutput_RegisterCaptureEndCallback(Camera_PhotoOutput* photoOutput,
261    OH_PhotoOutput_CaptureEnd callback);
262
263/**
264 * @brief Unregister capture end event callback.
265 *
266 * @param photoOutput the {@link Camera_PhotoOutput} instance.
267 * @param callback the {@link OH_PhotoOutput_CaptureEnd} to be unregistered.
268 * @return {@link #CAMERA_OK} if the method call succeeds.
269 *         {@link #CAMERA_INVALID_ARGUMENT} if parameter missing or parameter type incorrect.
270 * @since 12
271 */
272Camera_ErrorCode OH_PhotoOutput_UnregisterCaptureEndCallback(Camera_PhotoOutput* photoOutput,
273    OH_PhotoOutput_CaptureEnd callback);
274
275/**
276 * @brief Register frame shutter end event callback.
277 *
278 * @param photoOutput the {@link Camera_PhotoOutput} instance.
279 * @param callback the {@link OH_PhotoOutput_OnFrameShutterEnd} to be registered.
280 * @return {@link #CAMERA_OK} if the method call succeeds.
281 *         {@link #CAMERA_INVALID_ARGUMENT} if parameter missing or parameter type incorrect.
282 * @since 12
283 */
284Camera_ErrorCode OH_PhotoOutput_RegisterFrameShutterEndCallback(Camera_PhotoOutput* photoOutput,
285    OH_PhotoOutput_OnFrameShutterEnd callback);
286
287/**
288 * @brief Unregister frame shutter end event callback.
289 *
290 * @param photoOutput the {@link Camera_PhotoOutput} instance.
291 * @param callback the {@link OH_PhotoOutput_OnFrameShutterEnd} to be unregistered.
292 * @return {@link #CAMERA_OK} if the method call succeeds.
293 *         {@link #CAMERA_INVALID_ARGUMENT} if parameter missing or parameter type incorrect.
294 * @since 12
295 */
296Camera_ErrorCode OH_PhotoOutput_UnregisterFrameShutterEndCallback(Camera_PhotoOutput* photoOutput,
297    OH_PhotoOutput_OnFrameShutterEnd callback);
298
299/**
300 * @brief Register capture ready event callback. After receiving the callback, can proceed to the next capture.
301 *
302 * @param photoOutput the {@link Camera_PhotoOutput} instance.
303 * @param callback the {@link OH_PhotoOutput_CaptureReady} to be registered.
304 * @return {@link #CAMERA_OK} if the method call succeeds.
305 *         {@link #CAMERA_INVALID_ARGUMENT} if parameter missing or parameter type incorrect.
306 * @since 12
307 */
308Camera_ErrorCode OH_PhotoOutput_RegisterCaptureReadyCallback(Camera_PhotoOutput* photoOutput,
309    OH_PhotoOutput_CaptureReady callback);
310
311/**
312 * @brief Unregister capture ready event callback.
313 *
314 * @param photoOutput the {@link Camera_PhotoOutput} instance.
315 * @param callback the {@link OH_PhotoOutput_CaptureReady} to be unregistered.
316 * @return {@link #CAMERA_OK} if the method call succeeds.
317 *         {@link #CAMERA_INVALID_ARGUMENT} if parameter missing or parameter type incorrect.
318 * @since 12
319 */
320Camera_ErrorCode OH_PhotoOutput_UnregisterCaptureReadyCallback(Camera_PhotoOutput* photoOutput,
321    OH_PhotoOutput_CaptureReady callback);
322
323/**
324 * @brief Register estimated capture duration event callback.
325 *
326 * @param photoOutput the {@link Camera_PhotoOutput} instance.
327 * @param callback the {@link OH_PhotoOutput_EstimatedCaptureDuration} to be registered.
328 * @return {@link #CAMERA_OK} if the method call succeeds.
329 *         {@link #CAMERA_INVALID_ARGUMENT} if parameter missing or parameter type incorrect.
330 * @since 12
331 */
332Camera_ErrorCode OH_PhotoOutput_RegisterEstimatedCaptureDurationCallback(Camera_PhotoOutput* photoOutput,
333    OH_PhotoOutput_EstimatedCaptureDuration callback);
334
335/**
336 * @brief Unregister estimated capture duration event callback.
337 *
338 * @param photoOutput the {@link Camera_PhotoOutput} instance.
339 * @param callback the {@link OH_PhotoOutput_EstimatedCaptureDuration} to be unregistered.
340 * @return {@link #CAMERA_OK} if the method call succeeds.
341 *         {@link #CAMERA_INVALID_ARGUMENT} if parameter missing or parameter type incorrect.
342 * @since 12
343 */
344Camera_ErrorCode OH_PhotoOutput_UnregisterEstimatedCaptureDurationCallback(Camera_PhotoOutput* photoOutput,
345    OH_PhotoOutput_EstimatedCaptureDuration callback);
346
347/**
348 * @brief Register photo output photo available callback.
349 *
350 * @param photoOutput the {@link Camera_PhotoOutput} instance.
351 * @param callback the {@link OH_PhotoOutput_PhotoAvailable} to be registered.
352 * @return {@link #CAMERA_OK} if the method call succeeds.
353 *         {@link #INVALID_ARGUMENT} if parameter missing or parameter type incorrect.
354 * @since 12
355 */
356Camera_ErrorCode OH_PhotoOutput_RegisterPhotoAvailableCallback(Camera_PhotoOutput* photoOutput,
357    OH_PhotoOutput_PhotoAvailable callback);
358
359/**
360 * @brief Unregister photo output photo available callback.
361 *
362 * @param photoOutput the {@link Camera_PhotoOutput} instance.
363 * @param callback the {@link PhotoOutput_Callbacks} to be unregistered.
364 * @return {@link #CAMERA_OK} if the method call succeeds.
365 *         {@link #INVALID_ARGUMENT} if parameter missing or parameter type incorrect.
366 * @since 12
367 */
368Camera_ErrorCode OH_PhotoOutput_UnregisterPhotoAvailableCallback(Camera_PhotoOutput* photoOutput,
369    OH_PhotoOutput_PhotoAvailable callback);
370
371/**
372 * @brief Register photo output photo asset available callback.
373 *
374 * @param photoOutput the {@link Camera_PhotoOutput} instance.
375 * @param callback the {@link OH_PhotoOutput_PhotoAssetAvailable} to be registered.
376 * @return {@link #CAMERA_OK} if the method call succeeds.
377 *         {@link #INVALID_ARGUMENT} if parameter missing or parameter type incorrect.
378 * @since 12
379 */
380Camera_ErrorCode OH_PhotoOutput_RegisterPhotoAssetAvailableCallback(Camera_PhotoOutput* photoOutput,
381    OH_PhotoOutput_PhotoAssetAvailable callback);
382
383/**
384 * @brief Unregister photo output photo asset available callback.
385 *
386 * @param photoOutput the {@link Camera_PhotoOutput} instance.
387 * @param callback the {@link OH_PhotoOutput_PhotoAssetAvailable} to be unregistered.
388 * @return {@link #CAMERA_OK} if the method call succeeds.
389 *         {@link #INVALID_ARGUMENT} if parameter missing or parameter type incorrect.
390 * @since 12
391 */
392Camera_ErrorCode OH_PhotoOutput_UnregisterPhotoAssetAvailableCallback(Camera_PhotoOutput* photoOutput,
393    OH_PhotoOutput_PhotoAssetAvailable callback);
394
395/**
396 * @brief Capture photo.
397 *
398 * @param photoOutput the {@link Camera_PhotoOutput} instance which used to capture photo.
399 * @return {@link #CAMERA_OK} if the method call succeeds.
400 *         {@link #INVALID_ARGUMENT} if parameter missing or parameter type incorrect.
401 *         {@link #CAMERA_SESSION_NOT_RUNNING} if the capture session not running.
402 *         {@link #CAMERA_SERVICE_FATAL_ERROR} if camera service fatal error.
403 * @since 11
404 */
405Camera_ErrorCode OH_PhotoOutput_Capture(Camera_PhotoOutput* photoOutput);
406
407/**
408 * @brief Capture photo with capture setting.
409 *
410 * @param photoOutput the {@link Camera_PhotoOutput} instance which used to capture photo.
411 * @param setting the {@link Camera_PhotoCaptureSetting} to used to capture photo.
412 * @return {@link #CAMERA_OK} if the method call succeeds.
413 *         {@link #INVALID_ARGUMENT} if parameter missing or parameter type incorrect.
414 *         {@link #CAMERA_SESSION_NOT_RUNNING} if the capture session not running.
415 *         {@link #CAMERA_SERVICE_FATAL_ERROR} if camera service fatal error.
416 * @since 11
417 */
418Camera_ErrorCode OH_PhotoOutput_Capture_WithCaptureSetting(Camera_PhotoOutput* photoOutput,
419    Camera_PhotoCaptureSetting setting);
420
421/**
422 * @brief Release photo output.
423 *
424 * @param photoOutput the {@link Camera_PhotoOutput} instance to released.
425 * @return {@link #CAMERA_OK} if the method call succeeds.
426 *         {@link #INVALID_ARGUMENT} if parameter missing or parameter type incorrect.
427 *         {@link #CAMERA_SERVICE_FATAL_ERROR} if camera service fatal error.
428 * @since 11
429 */
430Camera_ErrorCode OH_PhotoOutput_Release(Camera_PhotoOutput* photoOutput);
431
432/**
433 * @brief Check whether to support mirror photo.
434 *
435 * @param photoOutput the {@link Camera_PhotoOutput} instance which used to check whether mirror supported.
436 * @param isSupported the result of whether mirror supported.
437 * @return {@link #CAMERA_OK} if the method call succeeds.
438 *         {@link #INVALID_ARGUMENT} if parameter missing or parameter type incorrect.
439 *         {@link #CAMERA_SERVICE_FATAL_ERROR} if camera service fatal error.
440 * @since 11
441 */
442Camera_ErrorCode OH_PhotoOutput_IsMirrorSupported(Camera_PhotoOutput* photoOutput, bool* isSupported);
443
444/**
445 * @brief Enable mirror for photo capture.
446 *
447 * @param photoOutput the {@link Camera_PhotoOutput} instance which used to configure mirror.
448 * @param enabled the flag indicates whether mirror is enabled.
449 * @return {@link #CAMERA_OK} if the method call succeeds.
450 *         {@link #INVALID_ARGUMENT} if parameter missing or parameter type incorrect.
451 *         {@link #CAMERA_SERVICE_FATAL_ERROR} if camera service fatal error.
452 * @since 13
453 */
454Camera_ErrorCode OH_PhotoOutput_EnableMirror(Camera_PhotoOutput* photoOutput, bool enabled);
455
456/**
457 * @brief Get active photo output profile.
458 *
459 * @param photoOutput the {@link Camera_PhotoOutput} instance to deliver active profile.
460 * @param profile the active {@link Camera_Profile} to be filled if the method call succeeds.
461 * @return {@link #CAMERA_OK} if the method call succeeds.
462 *         {@link #CAMERA_INVALID_ARGUMENT} if parameter missing or parameter type incorrect.
463 *         {@link #CAMERA_SERVICE_FATAL_ERROR} if camera service fatal error.
464 * @since 12
465 */
466Camera_ErrorCode OH_PhotoOutput_GetActiveProfile(Camera_PhotoOutput* photoOutput, Camera_Profile** profile);
467
468/**
469 * @brief Delete photo profile instance.
470 *
471 * @param profile the {@link Camera_Profile} instance to deleted.
472 * @return {@link #CAMERA_OK} if the method call succeeds.
473 *         {@link #CAMERA_INVALID_ARGUMENT} if parameter missing or parameter type incorrect.
474 * @since 12
475 */
476Camera_ErrorCode OH_PhotoOutput_DeleteProfile(Camera_Profile* profile);
477
478/**
479 * @brief Check whether to support moving photo.
480 *
481 * @param photoOutput the {@link Camera_PhotoOutput} instance which used to check whether moving photo supported.
482 * @param isSupported the result of whether moving photo supported.
483 * @return {@link #CAMERA_OK} if the method call succeeds.
484 *         {@link #INVALID_ARGUMENT} if parameter missing or parameter type incorrect.
485 *         {@link #CAMERA_SERVICE_FATAL_ERROR} if camera service fatal error.
486 * @since 12
487 */
488Camera_ErrorCode OH_PhotoOutput_IsMovingPhotoSupported(Camera_PhotoOutput* photoOutput, bool* isSupported);
489
490/**
491 * @brief Enable moving photo or not.
492 *
493 * @param photoOutput the {@link Camera_PhotoOutput} instance which used to enable moving photo or not.
494 * @param enabled the flag of enable moving photo or not.
495 * @return {@link #CAMERA_OK} if the method call succeeds.
496 *         {@link #INVALID_ARGUMENT} if parameter missing or parameter type incorrect.
497 *         {@link #CAMERA_SERVICE_FATAL_ERROR} if camera service fatal error.
498 * @since 12
499 */
500Camera_ErrorCode OH_PhotoOutput_EnableMovingPhoto(Camera_PhotoOutput* photoOutput, bool enabled);
501
502#ifdef __cplusplus
503}
504#endif
505
506#endif // NATIVE_INCLUDE_CAMERA_PHOTOOUTPUT_H
507/** @} */