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