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