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 image 18 * @{ 19 * 20 * @brief Provides APIs for access to the image interface. 21 * 22 * @since 12 23 */ 24 25 /** 26 * @file image_source_native.h 27 * 28 * @brief Declares APIs for decoding an image source into a pixel map. 29 * 30 * @library libimage_source.so 31 * @kit ImageKit 32 * @syscap SystemCapability.Multimedia.Image.ImageSource 33 * @since 12 34 */ 35 36 #ifndef INTERFACES_KITS_NATIVE_INCLUDE_IMAGE_IMAGE_SOURCE_NATIVE_H_ 37 #define INTERFACES_KITS_NATIVE_INCLUDE_IMAGE_IMAGE_SOURCE_NATIVE_H_ 38 #include "image_common.h" 39 40 #include "pixelmap_native.h" 41 #include "picture_native.h" 42 #include "rawfile/raw_file.h" 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 48 /** 49 * @brief Defines an image source object for the image interface. 50 * 51 * @since 12 52 */ 53 struct OH_ImageSourceNative; 54 typedef struct OH_ImageSourceNative OH_ImageSourceNative; 55 56 /** 57 * @brief Defines image source infomation 58 * {@link OH_ImageSourceInfo_Create}. 59 * 60 * @since 12 61 */ 62 struct OH_ImageSource_Info; 63 typedef struct OH_ImageSource_Info OH_ImageSource_Info; 64 65 /** 66 * @brief Defines decoding options for picture 67 * {@link OH_DecodingOptionsForPicture_Create}. 68 * 69 * @since 13 70 */ 71 struct OH_DecodingOptionsForPicture; 72 73 /** 74 * @brief Defines decoding options for picture 75 * {@link OH_DecodingOptionsForPicture_Create}. 76 * 77 * @since 13 78 */ 79 typedef struct OH_DecodingOptionsForPicture OH_DecodingOptionsForPicture; 80 81 /** 82 * @brief Enumerates decoding dynamic range.. 83 * 84 * @since 12 85 */ 86 typedef enum { 87 /* 88 * Dynamic range depends on the image. 89 */ 90 IMAGE_DYNAMIC_RANGE_AUTO = 0, 91 /* 92 * Standard dynamic range. 93 */ 94 IMAGE_DYNAMIC_RANGE_SDR = 1, 95 /* 96 * High dynamic range. 97 */ 98 IMAGE_DYNAMIC_RANGE_HDR = 2, 99 } IMAGE_DYNAMIC_RANGE; 100 101 /** 102 * @brief Create a pointer for OH_ImageSource_Info struct. 103 * 104 * @param info The OH_ImageSource_Info pointer will be operated. 105 * @return Returns {@link Image_ErrorCode} 106 * @since 12 107 */ 108 Image_ErrorCode OH_ImageSourceInfo_Create(OH_ImageSource_Info **info); 109 110 /** 111 * @brief Get width number for OH_ImageSource_Info struct. 112 * 113 * @param info The OH_ImageSource_Info pointer will be operated. 114 * @param width the number of image width. 115 * @return Returns {@link Image_ErrorCode} 116 * @since 12 117 */ 118 Image_ErrorCode OH_ImageSourceInfo_GetWidth(OH_ImageSource_Info *info, uint32_t *width); 119 120 /** 121 * @brief Get height number for OH_ImageSource_Info struct. 122 * 123 * @param info The OH_ImageSource_Info pointer will be operated. 124 * @param height the number of image height. 125 * @return Returns {@link Image_ErrorCode} 126 * @since 12 127 */ 128 Image_ErrorCode OH_ImageSourceInfo_GetHeight(OH_ImageSource_Info *info, uint32_t *height); 129 130 /** 131 * @brief Get isHdr for OH_ImageSource_Info struct. 132 * 133 * @param info The OH_ImageSource_Info pointer will be operated. Pointer connot be null. 134 * @param isHdr Whether the image has a high dynamic range. 135 * @return Returns {@link Image_ErrorCode} IMAGE_SUCCESS - The operation is successful. 136 * returns {@link Image_ErrorCode} IMAGE_BAD_PARAMETER - Parameter error.Possible causes:Parameter verification failed. 137 * @since 12 138 */ 139 Image_ErrorCode OH_ImageSourceInfo_GetDynamicRange(OH_ImageSource_Info *info, bool *isHdr); 140 141 /** 142 * @brief delete OH_ImageSource_Info pointer. 143 * 144 * @param info The OH_ImageSource_Info pointer will be operated. 145 * @return Returns {@link Image_ErrorCode} 146 * @since 12 147 */ 148 Image_ErrorCode OH_ImageSourceInfo_Release(OH_ImageSource_Info *info); 149 150 /** 151 * @brief Defines the options for decoding the image source. 152 * It is used in {@link OH_ImageSourceNative_CreatePixelmap}. 153 * 154 * @since 12 155 */ 156 struct OH_DecodingOptions; 157 typedef struct OH_DecodingOptions OH_DecodingOptions; 158 159 /** 160 * @brief Create a pointer for OH_DecodingOptions struct. 161 * 162 * @param options The OH_DecodingOptions pointer will be operated. 163 * @return Returns {@link Image_ErrorCode} 164 * @since 12 165 */ 166 Image_ErrorCode OH_DecodingOptions_Create(OH_DecodingOptions **options); 167 168 /** 169 * @brief Get pixelFormat number for OH_DecodingOptions struct. 170 * 171 * @param options The OH_DecodingOptions pointer will be operated. 172 * @param pixelFormat the number of image pixelFormat. 173 * @return Returns {@link Image_ErrorCode} 174 * @since 12 175 */ 176 Image_ErrorCode OH_DecodingOptions_GetPixelFormat(OH_DecodingOptions *options, 177 int32_t *pixelFormat); 178 179 /** 180 * @brief Set pixelFormat number for OH_DecodingOptions struct. 181 * 182 * @param options The OH_DecodingOptions pointer will be operated. 183 * @param pixelFormat the number of image pixelFormat. 184 * @return Returns {@link Image_ErrorCode} 185 * @since 12 186 */ 187 Image_ErrorCode OH_DecodingOptions_SetPixelFormat(OH_DecodingOptions *options, 188 int32_t pixelFormat); 189 190 /** 191 * @brief Get index number for OH_DecodingOptions struct. 192 * 193 * @param options The OH_DecodingOptions pointer will be operated. 194 * @param index the number of image index. 195 * @return Returns {@link Image_ErrorCode} 196 * @since 12 197 */ 198 Image_ErrorCode OH_DecodingOptions_GetIndex(OH_DecodingOptions *options, uint32_t *index); 199 200 /** 201 * @brief Set index number for OH_DecodingOptions struct. 202 * 203 * @param options The OH_DecodingOptions pointer will be operated. 204 * @param index the number of image index. 205 * @return Returns {@link Image_ErrorCode} 206 * @since 12 207 */ 208 Image_ErrorCode OH_DecodingOptions_SetIndex(OH_DecodingOptions *options, uint32_t index); 209 210 /** 211 * @brief Get rotate number for OH_DecodingOptions struct. 212 * 213 * @param options The OH_DecodingOptions pointer will be operated. 214 * @param rotate the number of image rotate. 215 * @return Returns {@link Image_ErrorCode} 216 * @since 12 217 */ 218 Image_ErrorCode OH_DecodingOptions_GetRotate(OH_DecodingOptions *options, float *rotate); 219 220 /** 221 * @brief Set rotate number for OH_DecodingOptions struct. 222 * 223 * @param options The OH_DecodingOptions pointer will be operated. 224 * @param rotate the number of image rotate. 225 * @return Returns {@link Image_ErrorCode} 226 * @since 12 227 */ 228 Image_ErrorCode OH_DecodingOptions_SetRotate(OH_DecodingOptions *options, float rotate); 229 230 /** 231 * @brief Get desiredSize number for OH_DecodingOptions struct. 232 * 233 * @param options The OH_DecodingOptions pointer will be operated. 234 * @param desiredSize the number of image desiredSize. 235 * @return Returns {@link Image_ErrorCode} 236 * @since 12 237 */ 238 Image_ErrorCode OH_DecodingOptions_GetDesiredSize(OH_DecodingOptions *options, 239 Image_Size *desiredSize); 240 241 /** 242 * @brief Set desiredSize number for OH_DecodingOptions struct. 243 * 244 * @param options The OH_DecodingOptions pointer will be operated. 245 * @param desiredSize the number of image desiredSize. 246 * @return Returns {@link Image_ErrorCode} 247 * @since 12 248 */ 249 Image_ErrorCode OH_DecodingOptions_SetDesiredSize(OH_DecodingOptions *options, 250 Image_Size *desiredSize); 251 252 /** 253 * @brief Set desiredRegion number for OH_DecodingOptions struct. 254 * 255 * @param options The OH_DecodingOptions pointer will be operated. 256 * @param desiredRegion the number of image desiredRegion. 257 * @return Returns {@link Image_ErrorCode} 258 * @since 12 259 */ 260 Image_ErrorCode OH_DecodingOptions_GetDesiredRegion(OH_DecodingOptions *options, 261 Image_Region *desiredRegion); 262 263 /** 264 * @brief Set desiredRegion number for OH_DecodingOptions struct. 265 * 266 * @param options The OH_DecodingOptions pointer will be operated. 267 * @param desiredRegion the number of image desiredRegion. 268 * @return Returns {@link Image_ErrorCode} 269 * @since 12 270 */ 271 Image_ErrorCode OH_DecodingOptions_SetDesiredRegion(OH_DecodingOptions *options, 272 Image_Region *desiredRegion); 273 274 /** 275 * @brief Set desiredDynamicRange number for OH_DecodingOptions struct. 276 * 277 * @param options The OH_DecodingOptions pointer will be operated. Pointer connot be null. 278 * @param desiredDynamicRange the number of desired dynamic range {@link IMAGE_DYNAMIC_RANGE}. Pointer connot be null. 279 * @return Returns {@link Image_ErrorCode} IMAGE_SUCCESS - The operation is successful. 280 * returns {@link Image_ErrorCode} IMAGE_BAD_PARAMETER - Parameter error.Possible causes:Parameter verification failed. 281 * @since 12 282 */ 283 Image_ErrorCode OH_DecodingOptions_GetDesiredDynamicRange(OH_DecodingOptions *options, 284 int32_t *desiredDynamicRange); 285 286 /** 287 * @brief Set desiredDynamicRange number for OH_DecodingOptions struct. 288 * 289 * @param options The OH_DecodingOptions pointer will be operated. Pointer connot be null. 290 * @param desiredDynamicRange the number of desired dynamic range {@link IMAGE_DYNAMIC_RANGE}. 291 * @return Returns {@link Image_ErrorCode} IMAGE_SUCCESS - The operation is successful. 292 * returns {@link Image_ErrorCode} IMAGE_BAD_PARAMETER - Parameter error.Possible causes:Parameter verification failed. 293 * @since 12 294 */ 295 Image_ErrorCode OH_DecodingOptions_SetDesiredDynamicRange(OH_DecodingOptions *options, 296 int32_t desiredDynamicRange); 297 298 /** 299 * @brief delete OH_DecodingOptions pointer. 300 * 301 * @param options The OH_DecodingOptions pointer will be operated. 302 * @return Returns {@link Image_ErrorCode} 303 * @since 12 304 */ 305 Image_ErrorCode OH_DecodingOptions_Release(OH_DecodingOptions *options); 306 307 /** 308 * @brief Creates an ImageSource pointer. 309 * 310 * @param uri Indicates a pointer to the image source URI. Only a file URI or Base64 URI is accepted. 311 * @param uriSize Indicates the length of the image source URI. 312 * @param res Indicates a pointer to the <b>ImageSource</b> object created at the C++ native layer. 313 * @return Returns {@link Image_ErrorCode} 314 * @since 12 315 */ 316 Image_ErrorCode OH_ImageSourceNative_CreateFromUri(char *uri, size_t uriSize, OH_ImageSourceNative **res); 317 318 /** 319 * @brief Creates an void pointer 320 * 321 * @param fd Indicates the image source file descriptor. 322 * @param res Indicates a void pointer to the <b>ImageSource</b> object created at the C++ native layer. 323 * @return Returns {@link Image_ErrorCode} 324 * @since 12 325 */ 326 Image_ErrorCode OH_ImageSourceNative_CreateFromFd(int32_t fd, OH_ImageSourceNative **res); 327 328 /** 329 * @brief Creates an void pointer 330 * 331 * @param data Indicates a pointer to the image source data. Only a formatted packet data or Base64 data is accepted. 332 * @param dataSize Indicates the size of the image source data. 333 * @param res Indicates a void pointer to the <b>ImageSource</b> object created at the C++ native layer. 334 * @return Returns {@link Image_ErrorCode} 335 * @since 12 336 */ 337 Image_ErrorCode OH_ImageSourceNative_CreateFromData(uint8_t *data, size_t dataSize, OH_ImageSourceNative **res); 338 339 /** 340 * @brief Creates an void pointer 341 * 342 * @param rawFile Indicates the raw file's file descriptor. 343 * @param res Indicates a void pointer to the <b>ImageSource</b> object created at the C++ native layer. 344 * @return Returns {@link Image_ErrorCode} 345 * @since 12 346 */ 347 Image_ErrorCode OH_ImageSourceNative_CreateFromRawFile(RawFileDescriptor *rawFile, OH_ImageSourceNative **res); 348 349 /** 350 * @brief Decodes an void pointer 351 * based on the specified {@link OH_DecodingOptions} struct. 352 * 353 * @param source Indicates a void pointer(from ImageSource pointer convert). 354 * @param options Indicates a pointer to the options for decoding the image source. 355 * For details, see {@link OH_DecodingOptions}. 356 * @param resPixMap Indicates a void pointer to the <b>Pixelmap</b> object obtained at the C++ native layer. 357 * @return Returns {@link Image_ErrorCode} 358 * @since 12 359 */ 360 Image_ErrorCode OH_ImageSourceNative_CreatePixelmap(OH_ImageSourceNative *source, OH_DecodingOptions *options, 361 OH_PixelmapNative **pixelmap); 362 363 /** 364 * @brief Decodes an void pointer 365 * the <b>Pixelmap</b> objects at the C++ native layer 366 * based on the specified {@link OH_DecodingOptions} struct. 367 * 368 * @param source Indicates a void pointer(from ImageSource pointer convert). 369 * @param options Indicates a pointer to the options for decoding the image source. 370 * For details, see {@link OH_DecodingOptions}. 371 * @param resVecPixMap Indicates a pointer array to the <b>Pixelmap</b> objects obtained at the C++ native layer. 372 * It cannot be a null pointer. 373 * @param size Indicates a size of resVecPixMap. User can get size from {@link OH_ImageSourceNative_GetFrameCount}. 374 * @return Returns {@link Image_ErrorCode} 375 * @since 12 376 */ 377 Image_ErrorCode OH_ImageSourceNative_CreatePixelmapList(OH_ImageSourceNative *source, OH_DecodingOptions *options, 378 OH_PixelmapNative *resVecPixMap[], size_t size); 379 380 /** 381 * @brief Create Picture pointer from ImageSource 382 * based on the specified {@link OH_DecodingOptionsForPicture} struct. 383 * 384 * @param source Indicates a void pointer(from ImageSource pointer convert). 385 * @param options Indicates a pointer to the options for decoding the image source. 386 * For details, see {@link OH_DecodingOptionsForPicture}. 387 * @param picture Indicates a void pointer to the <b>Picture</b> object obtained at the C++ native layer. 388 * @return Image functions result code. 389 * {@link IMAGE_SUCCESS} if the execution is successful. 390 * {@link IMAGE_BAD_PARAMETER} source is nullptr, or picture is nullptr. 391 * {@link IMAGE_DECODE_FAILED} decode failed. 392 * @since 13 393 */ 394 Image_ErrorCode OH_ImageSourceNative_CreatePicture(OH_ImageSourceNative *source, OH_DecodingOptionsForPicture *options, 395 OH_PictureNative **picture); 396 397 /** 398 * @brief Obtains the delay time list from some <b>ImageSource</b> objects (such as GIF image sources). 399 * 400 * @param source Indicates a void pointer(from ImageSource pointer convert). 401 * @param delayTimeList Indicates a pointer to the delay time list obtained. It cannot be a null pointer. 402 * @param size Indicates a size of delayTimeList. User can get size from {@link OH_ImageSourceNative_GetFrameCount}. 403 * @return Returns {@link Image_ErrorCode} 404 * @since 12 405 */ 406 Image_ErrorCode OH_ImageSourceNative_GetDelayTimeList(OH_ImageSourceNative *source, int32_t *delayTimeList, size_t size); 407 408 /** 409 * @brief Obtains image source information from an <b>ImageSource</b> object by index. 410 * 411 * @param source Indicates a void pointer(from ImageSource pointer convert). 412 * @param index Indicates the index of the frame. 413 * @param info Indicates a pointer to the image source information obtained. 414 * For details, see {@link OH_ImageSource_Info}. 415 * @return Returns {@link Image_ErrorCode} 416 * @since 12 417 */ 418 Image_ErrorCode OH_ImageSourceNative_GetImageInfo(OH_ImageSourceNative *source, int32_t index, 419 OH_ImageSource_Info *info); 420 421 /** 422 * @brief Obtains the value of an image property from an <b>ImageSource</b> object. 423 * 424 * @param source Indicates a void pointer(from ImageSource pointer convert). 425 * @param key Indicates a pointer to the property. For details, see {@link Image_String}., key is an exif constant. 426 * Release after use ImageSource, see {@link OH_ImageSourceNative_Release}. 427 * @param value Indicates a pointer to the value obtained.The user can pass in a null pointer and zero size, 428 * we will allocate memory, but user must free memory after use. 429 * @return Returns {@link Image_ErrorCode} 430 * @since 12 431 */ 432 Image_ErrorCode OH_ImageSourceNative_GetImageProperty(OH_ImageSourceNative *source, Image_String *key, 433 Image_String *value); 434 435 /** 436 * @brief Modifies the value of an image property of an <b>ImageSource</b> object. 437 * @param source Indicates a void pointer(from ImageSource pointer convert). 438 * @param key Indicates a pointer to the property. For details, see {@link Image_String}., key is an exif constant. 439 * Release after use ImageSource, see {@link OH_ImageSourceNative_Release}. 440 * @param value Indicates a pointer to the new value of the property. 441 * @return Returns {@link Image_ErrorCode} 442 * @since 12 443 */ 444 Image_ErrorCode OH_ImageSourceNative_ModifyImageProperty(OH_ImageSourceNative *source, Image_String *key, 445 Image_String *value); 446 447 /** 448 * @brief Obtains the number of frames from an <b>ImageSource</b> object. 449 * 450 * @param source Indicates a pointer to the {@link OH_ImageSource} object at the C++ native layer. 451 * @param res Indicates a pointer to the number of frames obtained. 452 * @return Returns {@link Image_ErrorCode} 453 * @since 12 454 */ 455 Image_ErrorCode OH_ImageSourceNative_GetFrameCount(OH_ImageSourceNative *source, uint32_t *frameCount); 456 457 /** 458 * @brief Releases an <b>ImageSourc</b> object. 459 * 460 * @param source Indicates a ImageSource pointer. 461 * @return Returns {@link Image_ErrorCode} 462 * @since 12 463 */ 464 Image_ErrorCode OH_ImageSourceNative_Release(OH_ImageSourceNative *source); 465 466 /** 467 * @brief Create a pointer for OH_DecodingOptionsForPicture struct. 468 * 469 * @param options The OH_DecodingOptionsForPicture pointer will be operated. 470 * @return Image functions result code. 471 * {@link IMAGE_SUCCESS} if the execution is successful. 472 * {@link IMAGE_BAD_PARAMETER} options is nullptr. 473 * @since 13 474 */ 475 Image_ErrorCode OH_DecodingOptionsForPicture_Create(OH_DecodingOptionsForPicture **options); 476 477 /** 478 * @brief Obtains the desired auxiliary pictures of decoding options. 479 * 480 * @param options The OH_DecodingOptionsForPicture pointer will be operated. 481 * @param desiredAuxiliaryPictures The desired auxiliary pictures in DecodingOptionsForPicture. 482 * @param length The length of desired auxiliary pictures. 483 * @return Image functions result code. 484 * {@link IMAGE_SUCCESS} if the execution is successful. 485 * {@link IMAGE_BAD_PARAMETER} options is nullptr, desiredAuxiliaryPictures is nullptr, 486 * or length is invalid. 487 * @since 13 488 */ 489 Image_ErrorCode OH_DecodingOptionsForPicture_GetDesiredAuxiliaryPictures(OH_DecodingOptionsForPicture *options, 490 Image_AuxiliaryPictureType **desiredAuxiliaryPictures, size_t *length); 491 492 /** 493 * @brief Set decoding options desired auxiliary pictures. 494 * 495 * @param options The OH_DecodingOptionsForPicture pointer will be operated. 496 * @param desiredAuxiliaryPictures The desired auxiliary pictures will be set. 497 * @param length The length of desired auxiliary pictures. 498 * @return Image functions result code. 499 * {@link IMAGE_SUCCESS} if the execution is successful. 500 * {@link IMAGE_BAD_PARAMETER} options is nullptr, desiredAuxiliaryPictures is nullptr, 501 * or length is invalid. 502 * @since 13 503 */ 504 Image_ErrorCode OH_DecodingOptionsForPicture_SetDesiredAuxiliaryPictures(OH_DecodingOptionsForPicture *options, 505 Image_AuxiliaryPictureType *desiredAuxiliaryPictures, size_t length); 506 507 /** 508 * @brief Releases an <b>DecodingOptionsForPicture</b> object. 509 * 510 * @param options Indicates a DecodingOptionsForPicture pointer. 511 * @return Image functions result code. 512 * {@link IMAGE_SUCCESS} if the execution is successful. 513 * {@link IMAGE_BAD_PARAMETER} options is nullptr. 514 * @since 13 515 */ 516 Image_ErrorCode OH_DecodingOptionsForPicture_Release(OH_DecodingOptionsForPicture *options); 517 #ifdef __cplusplus 518 }; 519 #endif 520 /** @} */ 521 #endif // INTERFACES_KITS_NATIVE_INCLUDE_IMAGE_IMAGE_SOURCE_NATIVE_H_