1# preview_output.h 2<!--Kit: Camera Kit--> 3<!--Subsystem: Multimedia--> 4<!--Owner: @qano--> 5<!--SE: @leo_ysl--> 6<!--TSE: @xchaosioda--> 7 8## Overview 9 10The file declares the preview output concepts. 11 12**File to include**: <ohcamera/preview_output.h> 13 14**Library**: libohcamera.so 15 16**System capability**: SystemCapability.Multimedia.Camera.Core 17 18**Since**: 11 19 20**Related module**: [OH_Camera](capi-oh-camera.md) 21 22## Summary 23 24### Structs 25 26| Name| typedef Keyword| Description| 27| -- | -- | -- | 28| [PreviewOutput_Callbacks](capi-oh-camera-previewoutput-callbacks.md) | PreviewOutput_Callbacks | Describes the callbacks related to preview output.| 29| [Camera_PreviewOutput](capi-oh-camera-camera-previewoutput.md) | Camera_PreviewOutput | Describes the preview output object.<br>You can use [OH_CameraManager_CreatePreviewOutput](capi-camera-manager-h.md#oh_cameramanager_createpreviewoutput) to create such an object. | 30 31### Functions 32 33| Name| typedef Keyword| Description| 34| -- | -- | -- | 35| [typedef void (\*OH_PreviewOutput_OnFrameStart)(Camera_PreviewOutput* previewOutput)](#oh_previewoutput_onframestart) | OH_PreviewOutput_OnFrameStart | Defines the callback defined in the [PreviewOutput_Callbacks](capi-oh-camera-previewoutput-callbacks.md) struct and used to report preview output frame start events.| 36| [typedef void (\*OH_PreviewOutput_OnFrameEnd)(Camera_PreviewOutput* previewOutput, int32_t frameCount)](#oh_previewoutput_onframeend) | OH_PreviewOutput_OnFrameEnd | Defines the callback defined in the [PreviewOutput_Callbacks](capi-oh-camera-previewoutput-callbacks.md) struct and used to report preview output frame end events.| 37| [typedef void (\*OH_PreviewOutput_OnError)(Camera_PreviewOutput* previewOutput, Camera_ErrorCode errorCode)](#oh_previewoutput_onerror) | OH_PreviewOutput_OnError | Defines the callback defined in the [PreviewOutput_Callbacks](capi-oh-camera-previewoutput-callbacks.md) struct and used to report preview output errors.| 38| [Camera_ErrorCode OH_PreviewOutput_RegisterCallback(Camera_PreviewOutput* previewOutput,PreviewOutput_Callbacks* callback)](#oh_previewoutput_registercallback) | - | Registers a callback to listen for preview output events.| 39| [Camera_ErrorCode OH_PreviewOutput_UnregisterCallback(Camera_PreviewOutput* previewOutput,PreviewOutput_Callbacks* callback)](#oh_previewoutput_unregistercallback) | - | Unregisters the callback used to listen for preview output events.| 40| [Camera_ErrorCode OH_PreviewOutput_Start(Camera_PreviewOutput* previewOutput)](#oh_previewoutput_start) | - | Starts preview output.| 41| [Camera_ErrorCode OH_PreviewOutput_Stop(Camera_PreviewOutput* previewOutput)](#oh_previewoutput_stop) | - | Stops preview output.| 42| [Camera_ErrorCode OH_PreviewOutput_Release(Camera_PreviewOutput* previewOutput)](#oh_previewoutput_release) | - | Releases a PreviewOutput instance.| 43| [Camera_ErrorCode OH_PreviewOutput_GetActiveProfile(Camera_PreviewOutput* previewOutput, Camera_Profile** profile)](#oh_previewoutput_getactiveprofile) | - | Obtains the profile of a PreviewOutput instance.| 44| [Camera_ErrorCode OH_PreviewOutput_DeleteProfile(Camera_Profile* profile)](#oh_previewoutput_deleteprofile) | - | Deletes the profile of a PreviewOutput instance.| 45| [Camera_ErrorCode OH_PreviewOutput_GetPreviewRotation(Camera_PreviewOutput* previewOutput, int displayRotation,Camera_ImageRotation* imageRotation)](#oh_previewoutput_getpreviewrotation) | - | Obtains the preview rotation angle.| 46| [Camera_ErrorCode OH_PreviewOutput_SetPreviewRotation(Camera_PreviewOutput* previewOutput,Camera_ImageRotation previewRotation, bool isDisplayLocked)](#oh_previewoutput_setpreviewrotation) | - | Sets the preview rotation angle.| 47| [Camera_ErrorCode OH_PreviewOutput_GetSupportedFrameRates(Camera_PreviewOutput* previewOutput,Camera_FrameRateRange** frameRateRange, uint32_t* size)](#oh_previewoutput_getsupportedframerates) | - | Obtains the list of frame rates supported by a PreviewOutput instance.| 48| [Camera_ErrorCode OH_PreviewOutput_DeleteFrameRates(Camera_PreviewOutput* previewOutput,Camera_FrameRateRange* frameRateRange)](#oh_previewoutput_deleteframerates) | - | Deletes the frame rate list.| 49| [Camera_ErrorCode OH_PreviewOutput_SetFrameRate(Camera_PreviewOutput* previewOutput,int32_t minFps, int32_t maxFps)](#oh_previewoutput_setframerate) | - | Sets the frame rates for a PreviewOutput instance.| 50| [Camera_ErrorCode OH_PreviewOutput_GetActiveFrameRate(Camera_PreviewOutput* previewOutput,Camera_FrameRateRange* frameRateRange)](#oh_previewoutput_getactiveframerate) | - | Obtains the active frame rates of a PreviewOutput instance.| 51 52## Function Description 53 54### OH_PreviewOutput_OnFrameStart() 55 56``` 57typedef void (*OH_PreviewOutput_OnFrameStart)(Camera_PreviewOutput* previewOutput) 58``` 59 60**Description** 61 62Defines the callback defined in the [PreviewOutput_Callbacks](capi-oh-camera-previewoutput-callbacks.md) struct and used to report preview output frame start events. 63 64**Since**: 11 65 66 67**Parameters** 68 69| Name| Description| 70| -- | -- | 71| [Camera_PreviewOutput](capi-oh-camera-camera-previewoutput.md)* previewOutput | Pointer to the PreviewOutput instance that transfers the callback.| 72 73### OH_PreviewOutput_OnFrameEnd() 74 75``` 76typedef void (*OH_PreviewOutput_OnFrameEnd)(Camera_PreviewOutput* previewOutput, int32_t frameCount) 77``` 78 79**Description** 80 81Defines the callback defined in the [PreviewOutput_Callbacks](capi-oh-camera-previewoutput-callbacks.md) struct and used to report preview output frame end events. 82 83**Since**: 11 84 85 86**Parameters** 87 88| Name| Description| 89| -- | -- | 90| [Camera_PreviewOutput](capi-oh-camera-camera-previewoutput.md)* previewOutput | Pointer to the PreviewOutput instance that transfers the callback.| 91| int32_t frameCount | Number of frames to be included in the callback.| 92 93### OH_PreviewOutput_OnError() 94 95``` 96typedef void (*OH_PreviewOutput_OnError)(Camera_PreviewOutput* previewOutput, Camera_ErrorCode errorCode) 97``` 98 99**Description** 100 101Defines the callback defined in the [PreviewOutput_Callbacks](capi-oh-camera-previewoutput-callbacks.md) struct and used to report preview output errors. 102 103**Since**: 11 104 105 106**Parameters** 107 108| Name| Description| 109| -- | -- | 110| [Camera_PreviewOutput](capi-oh-camera-camera-previewoutput.md)* previewOutput | Pointer to the PreviewOutput instance that transfers the callback.| 111| [Camera_ErrorCode](capi-camera-h.md#camera_errorcode) errorCode | Error code reported during preview output.| 112 113**See also** 114 115[CAMERA_SERVICE_FATAL_ERROR](capi-camera-h.md#camera_errorcode) 116 117### OH_PreviewOutput_RegisterCallback() 118 119``` 120Camera_ErrorCode OH_PreviewOutput_RegisterCallback(Camera_PreviewOutput* previewOutput,PreviewOutput_Callbacks* callback) 121``` 122 123**Description** 124 125Registers a callback to listen for preview output events. 126 127**Since**: 11 128 129 130**Parameters** 131 132| Name| Description| 133| -- | -- | 134| [Camera_PreviewOutput](capi-oh-camera-camera-previewoutput.md)* previewOutput | Pointer to the target PreviewOutput instance.| 135| [PreviewOutput_Callbacks](capi-oh-camera-previewoutput-callbacks.md)* callback | Pointer to the target callback.| 136 137**Returns** 138 139| Type| Description| 140| -- | -- | 141| [Camera_ErrorCode](capi-camera-h.md#camera_errorcode) | **CAMERA_OK**: The operation is successful.<br>**CAMERA_INVALID_ARGUMENT**: A parameter is missing or the parameter type is incorrect.| 142 143### OH_PreviewOutput_UnregisterCallback() 144 145``` 146Camera_ErrorCode OH_PreviewOutput_UnregisterCallback(Camera_PreviewOutput* previewOutput,PreviewOutput_Callbacks* callback) 147``` 148 149**Description** 150 151Unregisters the callback used to listen for preview output events. 152 153**Since**: 11 154 155 156**Parameters** 157 158| Name| Description| 159| -- | -- | 160| [Camera_PreviewOutput](capi-oh-camera-camera-previewoutput.md)* previewOutput | Pointer to the target PreviewOutput instance.| 161| [PreviewOutput_Callbacks](capi-oh-camera-previewoutput-callbacks.md)* callback | Pointer to the target callback.| 162 163**Returns** 164 165| Type| Description| 166| -- | -- | 167| [Camera_ErrorCode](capi-camera-h.md#camera_errorcode) | **CAMERA_OK**: The operation is successful.<br>**CAMERA_INVALID_ARGUMENT**: A parameter is missing or the parameter type is incorrect.| 168 169### OH_PreviewOutput_Start() 170 171``` 172Camera_ErrorCode OH_PreviewOutput_Start(Camera_PreviewOutput* previewOutput) 173``` 174 175**Description** 176 177Starts preview output. 178 179**Since**: 11 180 181 182**Parameters** 183 184| Name| Description| 185| -- | -- | 186| [Camera_PreviewOutput](capi-oh-camera-camera-previewoutput.md)* previewOutput | Pointer to the PreviewOutput instance to start.| 187 188**Returns** 189 190| Type| Description| 191| -- | -- | 192| [Camera_ErrorCode](capi-camera-h.md#camera_errorcode) | **CAMERA_OK**: The operation is successful.<br>**CAMERA_INVALID_ARGUMENT**: A parameter is missing or the parameter type is incorrect.<br>**CAMERA_SESSION_NOT_CONFIG**: The capture session is not configured.<br>**CAMERA_SERVICE_FATAL_ERROR**: A fatal error occurs in the camera service.| 193 194### OH_PreviewOutput_Stop() 195 196``` 197Camera_ErrorCode OH_PreviewOutput_Stop(Camera_PreviewOutput* previewOutput) 198``` 199 200**Description** 201 202Stops preview output. 203 204**Since**: 11 205 206 207**Parameters** 208 209| Name| Description| 210| -- | -- | 211| [Camera_PreviewOutput](capi-oh-camera-camera-previewoutput.md)* previewOutput | Pointer to the PreviewOutput instance to stop.| 212 213**Returns** 214 215| Type| Description| 216| -- | -- | 217| [Camera_ErrorCode](capi-camera-h.md#camera_errorcode) | **CAMERA_OK**: The operation is successful.<br>**CAMERA_INVALID_ARGUMENT**: A parameter is missing or the parameter type is incorrect.<br>**CAMERA_SERVICE_FATAL_ERROR**: A fatal error occurs in the camera service.| 218 219### OH_PreviewOutput_Release() 220 221``` 222Camera_ErrorCode OH_PreviewOutput_Release(Camera_PreviewOutput* previewOutput) 223``` 224 225**Description** 226 227Releases a PreviewOutput instance. 228 229**Since**: 11 230 231 232**Parameters** 233 234| Name| Description| 235| -- | -- | 236| [Camera_PreviewOutput](capi-oh-camera-camera-previewoutput.md)* previewOutput | Pointer to the PreviewOutput instance to release.| 237 238**Returns** 239 240| Type| Description| 241| -- | -- | 242| [Camera_ErrorCode](capi-camera-h.md#camera_errorcode) | **CAMERA_OK**: The operation is successful.<br>**CAMERA_INVALID_ARGUMENT**: A parameter is missing or the parameter type is incorrect.<br>**CAMERA_SERVICE_FATAL_ERROR**: A fatal error occurs in the camera service.| 243 244### OH_PreviewOutput_GetActiveProfile() 245 246``` 247Camera_ErrorCode OH_PreviewOutput_GetActiveProfile(Camera_PreviewOutput* previewOutput, Camera_Profile** profile) 248``` 249 250**Description** 251 252Obtains the profile of a PreviewOutput instance. 253 254**Since**: 12 255 256 257**Parameters** 258 259| Name| Description| 260| -- | -- | 261| [Camera_PreviewOutput](capi-oh-camera-camera-previewoutput.md)* previewOutput | Pointer to the PreviewOutput instance for which the profile is to be obtained.| 262| [Camera_Profile](capi-oh-camera-camera-profile.md)** profile | Double pointer to the preview output profile obtained.| 263 264**Returns** 265 266| Type| Description| 267| -- | -- | 268| [Camera_ErrorCode](capi-camera-h.md#camera_errorcode) | **CAMERA_OK**: The operation is successful.<br>**CAMERA_INVALID_ARGUMENT**: A parameter is missing or the parameter type is incorrect.<br>**CAMERA_SERVICE_FATAL_ERROR**: A fatal error occurs in the camera service.| 269 270### OH_PreviewOutput_DeleteProfile() 271 272``` 273Camera_ErrorCode OH_PreviewOutput_DeleteProfile(Camera_Profile* profile) 274``` 275 276**Description** 277 278Deletes the profile of a PreviewOutput instance. 279 280**Since**: 12 281 282 283**Parameters** 284 285| Name| Description| 286| -- | -- | 287| [Camera_Profile](capi-oh-camera-camera-profile.md)* profile | Pointer to the profile to delete.| 288 289**Returns** 290 291| Type| Description| 292| -- | -- | 293| [Camera_ErrorCode](capi-camera-h.md#camera_errorcode) | **CAMERA_OK**: The operation is successful.<br>**CAMERA_INVALID_ARGUMENT**: A parameter is missing or the parameter type is incorrect.| 294 295### OH_PreviewOutput_GetPreviewRotation() 296 297``` 298Camera_ErrorCode OH_PreviewOutput_GetPreviewRotation(Camera_PreviewOutput* previewOutput, int displayRotation,Camera_ImageRotation* imageRotation) 299``` 300 301**Description** 302 303Obtains the preview rotation angle. 304 305**Since**: 12 306 307 308**Parameters** 309 310| Name| Description| 311| -- | -- | 312| [Camera_PreviewOutput](capi-oh-camera-camera-previewoutput.md)* previewOutput | Pointer to the PreviewOutput instance used to obtain the rotation angle.| 313| int displayRotation | Rotation angle of the display.| 314| [Camera_ImageRotation](capi-camera-h.md#camera_imagerotation)* imageRotation | Pointer to the preview rotation angle.| 315 316**Returns** 317 318| Type| Description| 319| -- | -- | 320| [Camera_ErrorCode](capi-camera-h.md#camera_errorcode) | **CAMERA_OK**: The operation is successful.<br>**CAMERA_INVALID_ARGUMENT**: A parameter is missing or the parameter type is incorrect.<br>**CAMERA_SERVICE_FATAL_ERROR**: A fatal error occurs in the camera service.| 321 322### OH_PreviewOutput_SetPreviewRotation() 323 324``` 325Camera_ErrorCode OH_PreviewOutput_SetPreviewRotation(Camera_PreviewOutput* previewOutput,Camera_ImageRotation previewRotation, bool isDisplayLocked) 326``` 327 328**Description** 329 330Sets the preview rotation angle. 331 332**Since**: 12 333 334 335**Parameters** 336 337| Name| Description| 338| -- | -- | 339| [Camera_PreviewOutput](capi-oh-camera-camera-previewoutput.md)* previewOutput | Pointer to the PreviewOutput instance used to set the rotation angle.| 340| [Camera_ImageRotation](capi-camera-h.md#camera_imagerotation) previewRotation | Preview rotation angle.| 341| bool isDisplayLocked | Whether the display is locked. **true** if locked, **false** otherwise.| 342 343**Returns** 344 345| Type| Description| 346| -- | -- | 347| [Camera_ErrorCode](capi-camera-h.md#camera_errorcode) | **CAMERA_OK**: The operation is successful.<br>**CAMERA_INVALID_ARGUMENT**: A parameter is missing or the parameter type is incorrect.<br>**CAMERA_SERVICE_FATAL_ERROR**: A fatal error occurs in the camera service.| 348 349### OH_PreviewOutput_GetSupportedFrameRates() 350 351``` 352Camera_ErrorCode OH_PreviewOutput_GetSupportedFrameRates(Camera_PreviewOutput* previewOutput,Camera_FrameRateRange** frameRateRange, uint32_t* size) 353``` 354 355**Description** 356 357Obtains the list of frame rates supported by a PreviewOutput instance. 358 359**Since**: 12 360 361 362**Parameters** 363 364| Name| Description| 365| -- | -- | 366| [Camera_PreviewOutput](capi-oh-camera-camera-previewoutput.md)* previewOutput | Pointer to the PreviewOutput instance used to obtain the frame rates.| 367| [Camera_FrameRateRange](capi-oh-camera-camera-frameraterange.md)** frameRateRange | Double pointer to the list of frame rates, if the function is successfully called.| 368| uint32_t* size | Pointer to the size of the list of frame rates.| 369 370**Returns** 371 372| Type| Description| 373| -- | -- | 374| [Camera_ErrorCode](capi-camera-h.md#camera_errorcode) | **CAMERA_OK**: The operation is successful.<br>**CAMERA_INVALID_ARGUMENT**: A parameter is missing or the parameter type is incorrect.<br>**CAMERA_SERVICE_FATAL_ERROR**: A fatal error occurs in the camera service.| 375 376### OH_PreviewOutput_DeleteFrameRates() 377 378``` 379Camera_ErrorCode OH_PreviewOutput_DeleteFrameRates(Camera_PreviewOutput* previewOutput,Camera_FrameRateRange* frameRateRange) 380``` 381 382**Description** 383 384Deletes the frame rate list. 385 386**Since**: 12 387 388 389**Parameters** 390 391| Name| Description| 392| -- | -- | 393| [Camera_PreviewOutput](capi-oh-camera-camera-previewoutput.md)* previewOutput | Pointer to the target PreviewOutput instance.| 394| [Camera_FrameRateRange](capi-oh-camera-camera-frameraterange.md)* frameRateRange | Pointer to the list of frame rates to delete.| 395 396**Returns** 397 398| Type| Description| 399| -- | -- | 400| [Camera_ErrorCode](capi-camera-h.md#camera_errorcode) | **CAMERA_OK**: The operation is successful.<br>**CAMERA_INVALID_ARGUMENT**: A parameter is missing or the parameter type is incorrect.| 401 402### OH_PreviewOutput_SetFrameRate() 403 404``` 405Camera_ErrorCode OH_PreviewOutput_SetFrameRate(Camera_PreviewOutput* previewOutput,int32_t minFps, int32_t maxFps) 406``` 407 408**Description** 409 410Sets the frame rates for a PreviewOutput instance. 411 412**Since**: 12 413 414 415**Parameters** 416 417| Name| Description| 418| -- | -- | 419| [Camera_PreviewOutput](capi-oh-camera-camera-previewoutput.md)* previewOutput | Pointer to the PreviewOutput instance used to set the frame rates.| 420| int32_t minFps | Minimum frame rate.| 421| int32_t maxFps | Maximum frame rate.| 422 423**Returns** 424 425| Type| Description| 426| -- | -- | 427| [Camera_ErrorCode](capi-camera-h.md#camera_errorcode) | **CAMERA_OK**: The operation is successful.<br>**CAMERA_INVALID_ARGUMENT**: A parameter is missing or the parameter type is incorrect.| 428 429### OH_PreviewOutput_GetActiveFrameRate() 430 431``` 432Camera_ErrorCode OH_PreviewOutput_GetActiveFrameRate(Camera_PreviewOutput* previewOutput,Camera_FrameRateRange* frameRateRange) 433``` 434 435**Description** 436 437Obtains the active frame rates of a PreviewOutput instance. 438 439**Since**: 12 440 441 442**Parameters** 443 444| Name| Description| 445| -- | -- | 446| [Camera_PreviewOutput](capi-oh-camera-camera-previewoutput.md)* previewOutput | Pointer to the PreviewOutput instance used to obtain the active frame rates.| 447| [Camera_FrameRateRange](capi-oh-camera-camera-frameraterange.md)* frameRateRange | Pointer to the frame rate range, which is defined in the [Camera_FrameRateRange](capi-oh-camera-camera-frameraterange.md) struct, if the function is successfully called.| 448 449**Returns** 450 451| Type| Description| 452| -- | -- | 453| [Camera_ErrorCode](capi-camera-h.md#camera_errorcode) | **CAMERA_OK**: The operation is successful.<br>**CAMERA_INVALID_ARGUMENT**: A parameter is missing or the parameter type is incorrect.<br>**CAMERA_SERVICE_FATAL_ERROR**: A fatal error occurs in the camera service.| 454