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_packer_native.h 27 * 28 * @brief Declares APIs for encoding image into data or file. 29 * 30 * @library libimage_packer.so 31 * @syscap SystemCapability.Multimedia.Image.ImagePacker 32 * @since 12 33 */ 34 35 #ifndef INTERFACES_KITS_NATIVE_INCLUDE_IMAGE_IMAGE_PACKER_NATIVE_H 36 #define INTERFACES_KITS_NATIVE_INCLUDE_IMAGE_IMAGE_PACKER_NATIVE_H 37 #include "image_common.h" 38 #include "image_source_native.h" 39 #include "pixelmap_native.h" 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 45 /** 46 * @brief Define a ImagePacker struct type, used for ImagePacker pointer controls. 47 * 48 * @since 12 49 */ 50 struct OH_ImagePackerNative; 51 typedef struct OH_ImagePackerNative OH_ImagePackerNative; 52 53 /** 54 * @brief Defines the image packing options. 55 * 56 * @since 12 57 */ 58 struct OH_PackingOptions; 59 typedef struct OH_PackingOptions OH_PackingOptions; 60 61 /** 62 * @brief Defines the image sequence packing options. 63 * 64 * @since 12 65 */ 66 struct OH_PackingOptionsForSequence; 67 68 /** 69 * @brief Defines the image sequence packing options. 70 * 71 * @since 12 72 */ 73 typedef struct OH_PackingOptionsForSequence OH_PackingOptionsForSequence; 74 75 /** 76 * @brief Enumerates packing dynamic range. 77 * 78 * @since 12 79 */ 80 typedef enum { 81 /* 82 * Packing according to the content of the image. 83 */ 84 IMAGE_PACKER_DYNAMIC_RANGE_AUTO = 0, 85 /* 86 * Packing to standard dynamic range. 87 */ 88 IMAGE_PACKER_DYNAMIC_RANGE_SDR = 1, 89 } IMAGE_PACKER_DYNAMIC_RANGE; 90 91 /** 92 * @brief Create a pointer for PackingOptions struct. 93 * 94 * @param options The PackingOptions pointer will be operated. 95 * @return Returns {@link Image_ErrorCode} 96 * @since 12 97 */ 98 Image_ErrorCode OH_PackingOptions_Create(OH_PackingOptions **options); 99 100 /** 101 * @brief Get mime type for DecodingOptions struct. 102 * 103 * @param options The DecodingOptions pointer will be operated. 104 * @param format the number of image format.The user can pass in a null pointer and zero size, we will allocate memory, 105 * but user must free memory after use. 106 * @return Returns {@link Image_ErrorCode} 107 * @since 12 108 */ 109 Image_ErrorCode OH_PackingOptions_GetMimeType(OH_PackingOptions *options, 110 Image_MimeType *format); 111 112 /** 113 * @brief Get MIME type from OH_PackingOptions. The output format.data is null-terminated. 114 * 115 * @param options The OH_PackingOptions pointer to be queried. 116 * @param format MimeType set in the OH_PackingOptions. 117 * @return Returns function result code. 118 * {@link IMAGE_SUCCESS} if the execution is successful. 119 * {@link IMAGE_PACKER_INVALID_PARAMETER} if options or format is nullptr. 120 * @since 19 121 */ 122 Image_ErrorCode OH_PackingOptions_GetMimeTypeWithNull(OH_PackingOptions *options, 123 Image_MimeType *format); 124 125 /** 126 * @brief Set format number for DecodingOptions struct. 127 * 128 * @param options The DecodingOptions pointer will be operated. 129 * @param format the number of image format. 130 * @return Returns {@link Image_ErrorCode} 131 * @since 12 132 */ 133 Image_ErrorCode OH_PackingOptions_SetMimeType(OH_PackingOptions *options, 134 Image_MimeType *format); 135 136 /** 137 * @brief Get quality for DecodingOptions struct. 138 * 139 * @param options The DecodingOptions pointer will be operated. 140 * @param quality the number of image quality. 141 * @return Returns {@link Image_ErrorCode} 142 * @since 12 143 */ 144 Image_ErrorCode OH_PackingOptions_GetQuality(OH_PackingOptions *options, 145 uint32_t *quality); 146 147 /** 148 * @brief Set quality number for DecodingOptions struct. 149 * 150 * @param options The DecodingOptions pointer will be operated. 151 * @param quality the number of image quality. 152 * @return Returns {@link Image_ErrorCode} 153 * @since 12 154 */ 155 Image_ErrorCode OH_PackingOptions_SetQuality(OH_PackingOptions *options, 156 uint32_t quality); 157 /** 158 * @brief Get needsPackProperties for OH_PackingOptions struct. 159 * 160 * @param options The OH_PackingOptions pointer will be operated. 161 * @param needsPackProperties Whether the image properties can be saved, like Exif. 162 * @return Returns {@link Image_ErrorCode} 163 * @since 12 164 */ 165 Image_ErrorCode OH_PackingOptions_GetNeedsPackProperties(OH_PackingOptions *options, 166 bool *needsPackProperties); 167 168 /** 169 * @brief Set needsPackProperties for OH_PackingOptions struct. 170 * 171 * @param options The OH_PackingOptions pointer will be operated. 172 * @param needsPackProperties Whether the image properties can be saved, like Exif. 173 * @return Returns {@link Image_ErrorCode} 174 * @since 12 175 */ 176 Image_ErrorCode OH_PackingOptions_SetNeedsPackProperties(OH_PackingOptions *options, 177 bool needsPackProperties); 178 179 /** 180 * @brief Get desiredDynamicRange for PackingOptions struct. 181 * 182 * @param options The PackingOptions pointer will be operated. 183 * @param desiredDynamicRange The number of dynamic range {@link IMAGE_PACKER_DYNAMIC_RANGE}. 184 * @return Returns {@link Image_ErrorCode} 185 * @since 12 186 */ 187 Image_ErrorCode OH_PackingOptions_GetDesiredDynamicRange(OH_PackingOptions *options, int32_t* desiredDynamicRange); 188 189 /** 190 * @brief Set desiredDynamicRange number for PackingOptions struct. 191 * 192 * @param options The PackingOptions pointer will be operated. 193 * @param desiredDynamicRange The number of dynamic range {@link IMAGE_PACKER_DYNAMIC_RANGE}. 194 * @return Returns {@link Image_ErrorCode} 195 * @since 12 196 */ 197 Image_ErrorCode OH_PackingOptions_SetDesiredDynamicRange(OH_PackingOptions *options, int32_t desiredDynamicRange); 198 199 /** 200 * @brief Set Loop number for PackingOptions struct. 201 * 202 * @param options The PackingOptions pointer will be operated. 203 * @param loop The number of image loop. 204 * @return Returns {@link Image_ErrorCode} 205 * @since 12 206 */ 207 Image_ErrorCode OH_PackingOptions_SetLoop(OH_PackingOptions *options, uint16_t loop); 208 209 /** 210 * @brief Get Loop number for PackingOptions struct. 211 * 212 * @param options The PackingOptions pointer will be operated. 213 * @param loop The number of image loop. 214 * @return Returns {@link Image_ErrorCode} 215 * @since 12 216 */ 217 Image_ErrorCode OH_PackingOptions_GetLoop(OH_PackingOptions *options, uint16_t *loop); 218 219 /** 220 * @brief Set DelayTimes number for PackingOptions struct. 221 * 222 * @param options The PackingOptions pointer will be operated. 223 * @param delayTimes The number of image delayTimes. 224 * @param delayTimesSize The number of image delayTimesSize. 225 * @return Returns {@link Image_ErrorCode} 226 * @since 12 227 */ 228 Image_ErrorCode OH_PackingOptions_SetDelayTimes(OH_PackingOptions *options, uint16_t* delayTimes, 229 uint32_t delayTimesSize); 230 231 /** 232 * @brief Get DelayTimes number for PackingOptions struct. 233 * 234 * @param options The PackingOptions pointer will be operated. 235 * @param delayTimes The number of image delayTimes. 236 * @param delayTimesSize The number of image delayTimesSize. 237 * @return Returns {@link Image_ErrorCode} 238 * @since 12 239 */ 240 Image_ErrorCode OH_PackingOptions_GetDelayTimes(OH_PackingOptions *options, uint16_t* delayTimes, 241 uint32_t *delayTimesSize); 242 243 /** 244 * @brief Set DisposalTypes number for PackingOptions struct. 245 * 246 * @param options The PackingOptions pointer will be operated. 247 * @param disposalTypes The number of image disposalTypes. 248 * @param disposalTypesSize The number of image disposalTypesSize. 249 * @return Returns {@link Image_ErrorCode} 250 * @since 12 251 */ 252 Image_ErrorCode OH_PackingOptions_SetDisposalTypes(OH_PackingOptions *options, uint16_t* disposalTypes, 253 uint32_t disposalTypesSize); 254 255 /** 256 * @brief Get DisposalTypes number for PackingOptions struct. 257 * 258 * @param options The PackingOptions pointer will be operated. 259 * @param disposalTypes The number of image disposalTypes. 260 * @param disposalTypesSize The number of image disposalTypesSize. 261 * @return Returns {@link Image_ErrorCode} 262 * @since 12 263 */ 264 Image_ErrorCode OH_PackingOptions_GetDisposalTypes(OH_PackingOptions *options, uint16_t* disposalTypes, 265 uint32_t* disposalTypesSize); 266 267 /** 268 * @brief delete DecodingOptions pointer. 269 * 270 * @param options The DecodingOptions pointer will be operated. 271 * @return Returns {@link Image_ErrorCode} 272 * @since 12 273 */ 274 Image_ErrorCode OH_PackingOptions_Release(OH_PackingOptions *options); 275 276 /** 277 * @brief Create a pointer for OH_PackingOptionsForSequence struct. 278 * 279 * @param options The OH_PackingOptionsForSequence pointer will be operated. 280 * @return Image functions result code. 281 * {@link IMAGE_SUCCESS} if the execution is successful. 282 * {@link IMAGE_BAD_PARAMETER} options is nullptr. 283 * @since 12 284 */ 285 Image_ErrorCode OH_PackingOptionsForSequence_Create(OH_PackingOptionsForSequence **options); 286 287 /** 288 * @brief Set FrameCount number for OH_PackingOptionsForSequence struct. 289 * 290 * @param options The OH_PackingOptionsForSequence pointer will be operated. 291 * @param frameCount The number of image frameCount. 292 * @return Image functions result code. 293 * {@link IMAGE_SUCCESS} if the execution is successful. 294 * {@link IMAGE_BAD_PARAMETER} options is nullptr. 295 * @since 12 296 */ 297 Image_ErrorCode OH_PackingOptionsForSequence_SetFrameCount(OH_PackingOptionsForSequence *options, 298 uint32_t frameCount); 299 300 /** 301 * @brief Get FrameCount number for OH_PackingOptionsForSequence struct. 302 * 303 * @param options The OH_PackingOptionsForSequence pointer will be operated. 304 * @param frameCount The number of image frameCount. 305 * @return Image functions result code. 306 * {@link IMAGE_SUCCESS} if the execution is successful. 307 * {@link IMAGE_BAD_PARAMETER} options or frameCount is nullptr. 308 * @since 12 309 */ 310 Image_ErrorCode OH_PackingOptionsForSequence_GetFrameCount(OH_PackingOptionsForSequence *options, 311 uint32_t *frameCount); 312 313 /** 314 * @brief Set DelayTimeList number for OH_PackingOptionsForSequence struct. 315 * 316 * @param options The OH_PackingOptionsForSequence pointer will be operated. 317 * @param delayTimeList The pointer of image delayTime list. 318 * @param delayTimeListLength The number of image delayTimeListLength. 319 * @return Image functions result code. 320 * {@link IMAGE_SUCCESS} if the execution is successful. 321 * {@link IMAGE_BAD_PARAMETER} options or delayTimeList is nullptr. 322 * @since 12 323 */ 324 Image_ErrorCode OH_PackingOptionsForSequence_SetDelayTimeList(OH_PackingOptionsForSequence *options, 325 int32_t *delayTimeList, size_t delayTimeListLength); 326 327 /** 328 * @brief Get DelayTimeList number for OH_PackingOptionsForSequence struct. 329 * 330 * @param options The OH_PackingOptionsForSequence pointer will be operated. 331 * @param delayTimeList The pointer of image delayTime list. 332 * @param delayTimeListLength The number of image delayTimeListLength. 333 * @return Image functions result code. 334 * {@link IMAGE_SUCCESS} if the execution is successful. 335 * {@link IMAGE_BAD_PARAMETER} options or delayTimeList is nullptr. 336 * @since 12 337 */ 338 Image_ErrorCode OH_PackingOptionsForSequence_GetDelayTimeList(OH_PackingOptionsForSequence *options, 339 int32_t *delayTimeList, size_t delayTimeListLength); 340 341 /** 342 * @brief Set DisposalTypes number for OH_PackingOptionsForSequence struct. 343 * 344 * @param options The OH_PackingOptionsForSequence pointer will be operated. 345 * @param disposalTypes The pointer of image disposalTypes. 346 * @param disposalTypesLength The number of image disposalTypesLength. 347 * @return Image functions result code. 348 * {@link IMAGE_SUCCESS} if the execution is successful. 349 * {@link IMAGE_BAD_PARAMETER} options or disposalTypes is nullptr. 350 * @since 12 351 */ 352 Image_ErrorCode OH_PackingOptionsForSequence_SetDisposalTypes(OH_PackingOptionsForSequence *options, 353 uint32_t *disposalTypes, size_t disposalTypesLength); 354 355 /** 356 * @brief Get DisposalTypes number for OH_PackingOptionsForSequence struct. 357 * 358 * @param options The OH_PackingOptionsForSequence pointer will be operated. 359 * @param disposalTypes The pointer of image disposalTypes. 360 * @param disposalTypesLength The number of image disposalTypesLength. 361 * @return Image functions result code. 362 * {@link IMAGE_SUCCESS} if the execution is successful. 363 * {@link IMAGE_BAD_PARAMETER} options or disposalTypes is nullptr. 364 * @since 12 365 */ 366 Image_ErrorCode OH_PackingOptionsForSequence_GetDisposalTypes(OH_PackingOptionsForSequence *options, 367 uint32_t *disposalTypes, size_t disposalTypesLength); 368 369 /** 370 * @brief Set LoopCount number for OH_PackingOptionsForSequence struct. 371 * 372 * @param options The OH_PackingOptionsForSequence pointer will be operated. 373 * @param loopCount The number of image loopCount. 374 * @return Image functions result code. 375 * {@link IMAGE_SUCCESS} if the execution is successful. 376 * {@link IMAGE_BAD_PARAMETER} options is nullptr. 377 * @since 12 378 */ 379 Image_ErrorCode OH_PackingOptionsForSequence_SetLoopCount(OH_PackingOptionsForSequence *options, uint32_t loopCount); 380 381 /** 382 * @brief Get LoopCount number for OH_PackingOptionsForSequence struct. 383 * 384 * @param options The OH_PackingOptionsForSequence pointer will be operated. 385 * @param loopCount The number of image loopCount. 386 * @return Image functions result code. 387 * {@link IMAGE_SUCCESS} if the execution is successful. 388 * {@link IMAGE_BAD_PARAMETER} options or loopCount is nullptr. 389 * @since 12 390 */ 391 Image_ErrorCode OH_PackingOptionsForSequence_GetLoopCount(OH_PackingOptionsForSequence *options, uint32_t *loopCount); 392 393 /** 394 * @brief delete OH_PackingOptionsForSequence pointer. 395 * 396 * @param options The OH_PackingOptionsForSequence pointer will be operated. 397 * @return Image functions result code. 398 * {@link IMAGE_SUCCESS} if the execution is successful. 399 * {@link IMAGE_BAD_PARAMETER} options is nullptr. 400 * @since 12 401 */ 402 Image_ErrorCode OH_PackingOptionsForSequence_Release(OH_PackingOptionsForSequence *options); 403 404 /** 405 * @brief Create a pointer for OH_ImagePackerNative struct. 406 * 407 * @param options The OH_ImagePackerNative pointer will be operated. 408 * @return Returns {@link Image_ErrorCode} 409 * @since 12 410 */ 411 Image_ErrorCode OH_ImagePackerNative_Create(OH_ImagePackerNative **imagePacker); 412 413 /** 414 * @brief Encoding an <b>ImageSource</b> into the data with required format. 415 * 416 * @param imagePacker The imagePacker to use for packing. 417 * @param options Indicates the encoding {@link OH_PackingOptions}. 418 * @param imageSource The imageSource to be packed. 419 * @param outData The output data buffer to store the packed image. 420 * @param size A pointer to the size of the output data buffer. 421 * @return Returns {@link Image_ErrorCode} 422 * @since 12 423 */ 424 Image_ErrorCode OH_ImagePackerNative_PackToDataFromImageSource(OH_ImagePackerNative *imagePacker, 425 OH_PackingOptions *options, OH_ImageSourceNative *imageSource, uint8_t *outData, size_t *size); 426 427 /** 428 * @brief Encoding a <b>Pixelmap</b> into the data with required format. 429 * 430 * @param imagePacker The imagePacker to use for packing. 431 * @param options Indicates the encoding {@link OH_PackingOptions}. 432 * @param pixelmap The pixelmap to be packed. 433 * @param outData The output data buffer to store the packed image. 434 * @param size A pointer to the size of the output data buffer. 435 * @return Returns {@link Image_ErrorCode} 436 * @since 12 437 */ 438 Image_ErrorCode OH_ImagePackerNative_PackToDataFromPixelmap(OH_ImagePackerNative *imagePacker, 439 OH_PackingOptions *options, OH_PixelmapNative *pixelmap, uint8_t *outData, size_t *size); 440 441 /** 442 * @brief Encoding an <b>ImageSource</b> into the a file with fd with required format. 443 * 444 * @param imagePacker The image packer to use for packing. 445 * @param options Indicates the encoding {@link OH_PackingOptions}. 446 * @param imageSource The imageSource to be packed. 447 * @param fd Indicates a writable file descriptor. 448 * @return Returns {@link Image_ErrorCode} 449 * @since 12 450 */ 451 Image_ErrorCode OH_ImagePackerNative_PackToFileFromImageSource(OH_ImagePackerNative *imagePacker, 452 OH_PackingOptions *options, OH_ImageSourceNative *imageSource, int32_t fd); 453 454 /** 455 * @brief Encoding a <b>Pixelmap</b> into the a file with fd with required format 456 * 457 * @param imagePacker The image packer to use for packing. 458 * @param options Indicates the encoding {@link OH_PackingOptions}. 459 * @param pixelmap The pixelmap to be packed. 460 * @param fd Indicates a writable file descriptor. 461 * @return Returns {@link Image_ErrorCode} 462 * @since 12 463 */ 464 Image_ErrorCode OH_ImagePackerNative_PackToFileFromPixelmap(OH_ImagePackerNative *imagePacker, 465 OH_PackingOptions *options, OH_PixelmapNative *pixelmap, int32_t fd); 466 467 /** 468 * @brief Releases an imagePacker object. 469 * 470 * @param imagePacker A pointer to the image packer object to be released. 471 * @return Returns {@link Image_ErrorCode} 472 * @since 12 473 */ 474 Image_ErrorCode OH_ImagePackerNative_Release(OH_ImagePackerNative *imagePacker); 475 476 /** 477 * @brief Encoding a <b>Picture</b> into the data with required format. 478 * 479 * @param imagePacker The imagePacker to use for packing. 480 * @param options Indicates the encoding {@link OH_PackingOptions}. 481 * @param picture The picture to be packed. 482 * @param outData The output data buffer to store the packed image. 483 * @param size A pointer to the size of the output data buffer. 484 * @return Image functions result code. 485 * {@link IMAGE_SUCCESS} if the execution is successful. 486 * {@link IMAGE_BAD_PARAMETER} imagePacker is nullptr, or picture is nullptr, or outData is nullptr, 487 * or size is invalid. 488 * {@link IMAGE_ENCODE_FAILED} encode failed. 489 * @since 13 490 */ 491 Image_ErrorCode OH_ImagePackerNative_PackToDataFromPicture(OH_ImagePackerNative *imagePacker, 492 OH_PackingOptions *options, OH_PictureNative *picture, uint8_t *outData, size_t *size); 493 494 /** 495 * @brief Encoding a <b>PixelMap</b> sequence into the data 496 * 497 * @param imagePacker The imagePacker to use for packing. 498 * @param options Indicates the encoding {@link OH_PackingOptionsForSequence}. 499 * @param pixelmapSequence The pixelmap sequence to be packed. 500 * @param sequenceLength The pixelmap sequence size to be packed. 501 * @param outData The output data buffer to store the packed image. 502 * @param outDataSize A pointer to the size of the output data buffer. 503 * @return Image functions result code. 504 * {@link IMAGE_SUCCESS} if the execution is successful. 505 * {@link IMAGE_BAD_PARAMETER} one of the pointer type parameters is nullptr, or size/length is invalid 506 * {@link IMAGE_ENCODE_FAILED} encode failed. 507 * @since 13 508 */ 509 Image_ErrorCode OH_ImagePackerNative_PackToDataFromPixelmapSequence(OH_ImagePackerNative *imagePacker, 510 OH_PackingOptionsForSequence *options, OH_PixelmapNative **pixelmapSequence, 511 size_t sequenceLength, uint8_t *outData, size_t *outDataSize); 512 513 /** 514 * @brief Encoding a <b>Picture</b> into the a file with fd with required format. 515 * 516 * @param imagePacker The imagePacker to use for packing. 517 * @param options Indicates the encoding {@link OH_PackingOptions}. 518 * @param picture The picture to be packed. 519 * @param fd Indicates a writable file descriptor. 520 * @return Image functions result code. 521 * {@link IMAGE_SUCCESS} if the execution is successful. 522 * {@link IMAGE_BAD_PARAMETER} imagePacker is nullptr, or picture is nullptr, or fd is invalid. 523 * {@link IMAGE_ENCODE_FAILED} encode failed. 524 * @since 13 525 */ 526 Image_ErrorCode OH_ImagePackerNative_PackToFileFromPicture(OH_ImagePackerNative *imagePacker, 527 OH_PackingOptions *options, OH_PictureNative *picture, int32_t fd); 528 529 /** 530 * @brief Encoding a <b>PixelMap</b> sequence into the a file with fd 531 * 532 * @param imagePacker The image packer to use for packing. 533 * @param options Indicates the encoding {@link OH_PackingOptionsForSequence}. 534 * @param pixelmapSequence The pixelmap sequence to be packed. 535 * @param sequenceLength The pixelmap sequence size to be packed. 536 * @param fd Indicates a writable file descriptor. 537 * @return Image functions result code. 538 * {@link IMAGE_SUCCESS} if the execution is successful. 539 * {@link IMAGE_BAD_PARAMETER} one of the pointer type parameters is nullptr, or length is invalid 540 * {@link IMAGE_ENCODE_FAILED} encode failed. 541 * @since 12 542 */ 543 Image_ErrorCode OH_ImagePackerNative_PackToFileFromPixelmapSequence(OH_ImagePackerNative *imagePacker, 544 OH_PackingOptionsForSequence *options, OH_PixelmapNative **pixelmapSequence, size_t sequenceLength, int32_t fd); 545 546 /** 547 * @brief Obtains the image formats (MIME types) that can be encoded. 548 * 549 * @param supportedFormat An array of the supported image formats. 550 * @param length Length of supportedFormats. 551 * @return Image functions result code. 552 * {@link IMAGE_SUCCESS} if the execution is successful. 553 * {@link IMAGE_PACKER_BAD_PARAMETER} if supportedFormats or length is nullptr. 554 * @since 20 555 */ 556 Image_ErrorCode OH_ImagePackerNative_GetSupportedFormats(Image_MimeType** supportedFormat, size_t* length); 557 558 #ifdef __cplusplus 559 }; 560 #endif 561 /* *@} */ 562 #endif // INTERFACES_KITS_NATIVE_INCLUDE_IMAGE_IMAGE_PACKER_NATIVE_H