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 Set format number for DecodingOptions struct. 114 * 115 * @param options The DecodingOptions pointer will be operated. 116 * @param format the number of image format. 117 * @return Returns {@link Image_ErrorCode} 118 * @since 12 119 */ 120 Image_ErrorCode OH_PackingOptions_SetMimeType(OH_PackingOptions *options, 121 Image_MimeType *format); 122 123 /** 124 * @brief Get quality for DecodingOptions struct. 125 * 126 * @param options The DecodingOptions pointer will be operated. 127 * @param quality the number of image quality. 128 * @return Returns {@link Image_ErrorCode} 129 * @since 12 130 */ 131 Image_ErrorCode OH_PackingOptions_GetQuality(OH_PackingOptions *options, 132 uint32_t *quality); 133 134 /** 135 * @brief Set quality number for DecodingOptions struct. 136 * 137 * @param options The DecodingOptions pointer will be operated. 138 * @param quality the number of image quality. 139 * @return Returns {@link Image_ErrorCode} 140 * @since 12 141 */ 142 Image_ErrorCode OH_PackingOptions_SetQuality(OH_PackingOptions *options, 143 uint32_t quality); 144 /** 145 * @brief Get needsPackProperties for OH_PackingOptions struct. 146 * 147 * @param options The OH_PackingOptions pointer will be operated. 148 * @param needsPackProperties Whether the image properties can be saved, like Exif. 149 * @return Returns {@link Image_ErrorCode} 150 * @since 12 151 */ 152 Image_ErrorCode OH_PackingOptions_GetNeedsPackProperties(OH_PackingOptions *options, 153 bool *needsPackProperties); 154 155 /** 156 * @brief Set needsPackProperties for OH_PackingOptions struct. 157 * 158 * @param options The OH_PackingOptions pointer will be operated. 159 * @param needsPackProperties Whether the image properties can be saved, like Exif. 160 * @return Returns {@link Image_ErrorCode} 161 * @since 12 162 */ 163 Image_ErrorCode OH_PackingOptions_SetNeedsPackProperties(OH_PackingOptions *options, 164 bool needsPackProperties); 165 166 /** 167 * @brief Get desiredDynamicRange for PackingOptions struct. 168 * 169 * @param options The PackingOptions pointer will be operated. 170 * @param desiredDynamicRange The number of dynamic range {@link IMAGE_PACKER_DYNAMIC_RANGE}. 171 * @return Returns {@link Image_ErrorCode} 172 * @since 12 173 */ 174 Image_ErrorCode OH_PackingOptions_GetDesiredDynamicRange(OH_PackingOptions *options, int32_t* desiredDynamicRange); 175 176 /** 177 * @brief Set desiredDynamicRange number for PackingOptions struct. 178 * 179 * @param options The PackingOptions pointer will be operated. 180 * @param desiredDynamicRange The number of dynamic range {@link IMAGE_PACKER_DYNAMIC_RANGE}. 181 * @return Returns {@link Image_ErrorCode} 182 * @since 12 183 */ 184 Image_ErrorCode OH_PackingOptions_SetDesiredDynamicRange(OH_PackingOptions *options, int32_t desiredDynamicRange); 185 186 /** 187 * @brief Set Loop number for PackingOptions struct. 188 * 189 * @param options The PackingOptions pointer will be operated. 190 * @param loop The number of image loop. 191 * @return Returns {@link Image_ErrorCode} 192 * @since 12 193 */ 194 Image_ErrorCode OH_PackingOptions_SetLoop(OH_PackingOptions *options, uint16_t loop); 195 196 /** 197 * @brief Get Loop number for PackingOptions struct. 198 * 199 * @param options The PackingOptions pointer will be operated. 200 * @param loop The number of image loop. 201 * @return Returns {@link Image_ErrorCode} 202 * @since 12 203 */ 204 Image_ErrorCode OH_PackingOptions_GetLoop(OH_PackingOptions *options, uint16_t *loop); 205 206 /** 207 * @brief Set DelayTimes number for PackingOptions struct. 208 * 209 * @param options The PackingOptions pointer will be operated. 210 * @param delayTimes The number of image delayTimes. 211 * @param delayTimesSize The number of image delayTimesSize. 212 * @return Returns {@link Image_ErrorCode} 213 * @since 12 214 */ 215 Image_ErrorCode OH_PackingOptions_SetDelayTimes(OH_PackingOptions *options, uint16_t* delayTimes, 216 uint32_t delayTimesSize); 217 218 /** 219 * @brief Get DelayTimes number for PackingOptions struct. 220 * 221 * @param options The PackingOptions pointer will be operated. 222 * @param delayTimes The number of image delayTimes. 223 * @param delayTimesSize The number of image delayTimesSize. 224 * @return Returns {@link Image_ErrorCode} 225 * @since 12 226 */ 227 Image_ErrorCode OH_PackingOptions_GetDelayTimes(OH_PackingOptions *options, uint16_t* delayTimes, 228 uint32_t *delayTimesSize); 229 230 /** 231 * @brief Set DisposalTypes number for PackingOptions struct. 232 * 233 * @param options The PackingOptions pointer will be operated. 234 * @param disposalTypes The number of image disposalTypes. 235 * @param disposalTypesSize The number of image disposalTypesSize. 236 * @return Returns {@link Image_ErrorCode} 237 * @since 12 238 */ 239 Image_ErrorCode OH_PackingOptions_SetDisposalTypes(OH_PackingOptions *options, uint16_t* disposalTypes, 240 uint32_t disposalTypesSize); 241 242 /** 243 * @brief Get DisposalTypes number for PackingOptions struct. 244 * 245 * @param options The PackingOptions pointer will be operated. 246 * @param disposalTypes The number of image disposalTypes. 247 * @param disposalTypesSize The number of image disposalTypesSize. 248 * @return Returns {@link Image_ErrorCode} 249 * @since 12 250 */ 251 Image_ErrorCode OH_PackingOptions_GetDisposalTypes(OH_PackingOptions *options, uint16_t* disposalTypes, 252 uint32_t* disposalTypesSize); 253 254 /** 255 * @brief delete DecodingOptions pointer. 256 * 257 * @param options The DecodingOptions pointer will be operated. 258 * @return Returns {@link Image_ErrorCode} 259 * @since 12 260 */ 261 Image_ErrorCode OH_PackingOptions_Release(OH_PackingOptions *options); 262 263 /** 264 * @brief Create a pointer for OH_PackingOptionsForSequence struct. 265 * 266 * @param options The OH_PackingOptionsForSequence pointer will be operated. 267 * @return Image functions result code. 268 * {@link IMAGE_SUCCESS} if the execution is successful. 269 * {@link IMAGE_BAD_PARAMETER} options is nullptr. 270 * @since 12 271 */ 272 Image_ErrorCode OH_PackingOptionsForSequence_Create(OH_PackingOptionsForSequence **options); 273 274 /** 275 * @brief Set FrameCount number for OH_PackingOptionsForSequence struct. 276 * 277 * @param options The OH_PackingOptionsForSequence pointer will be operated. 278 * @param frameCount The number of image frameCount. 279 * @return Image functions result code. 280 * {@link IMAGE_SUCCESS} if the execution is successful. 281 * {@link IMAGE_BAD_PARAMETER} options is nullptr. 282 * @since 12 283 */ 284 Image_ErrorCode OH_PackingOptionsForSequence_SetFrameCount(OH_PackingOptionsForSequence *options, 285 uint32_t frameCount); 286 287 /** 288 * @brief Get 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 or frameCount is nullptr. 295 * @since 12 296 */ 297 Image_ErrorCode OH_PackingOptionsForSequence_GetFrameCount(OH_PackingOptionsForSequence *options, 298 uint32_t *frameCount); 299 300 /** 301 * @brief Set DelayTimeList number for OH_PackingOptionsForSequence struct. 302 * 303 * @param options The OH_PackingOptionsForSequence pointer will be operated. 304 * @param delayTimeList The pointer of image delayTime list. 305 * @param delayTimeListLength The number of image delayTimeListLength. 306 * @return Image functions result code. 307 * {@link IMAGE_SUCCESS} if the execution is successful. 308 * {@link IMAGE_BAD_PARAMETER} options or delayTimeList is nullptr. 309 * @since 12 310 */ 311 Image_ErrorCode OH_PackingOptionsForSequence_SetDelayTimeList(OH_PackingOptionsForSequence *options, 312 int32_t *delayTimeList, size_t delayTimeListLength); 313 314 /** 315 * @brief Get DelayTimeList number for OH_PackingOptionsForSequence struct. 316 * 317 * @param options The OH_PackingOptionsForSequence pointer will be operated. 318 * @param delayTimeList The pointer of image delayTime list. 319 * @param delayTimeListLength The number of image delayTimeListLength. 320 * @return Image functions result code. 321 * {@link IMAGE_SUCCESS} if the execution is successful. 322 * {@link IMAGE_BAD_PARAMETER} options or delayTimeList is nullptr. 323 * @since 12 324 */ 325 Image_ErrorCode OH_PackingOptionsForSequence_GetDelayTimeList(OH_PackingOptionsForSequence *options, 326 int32_t *delayTimeList, size_t delayTimeListLength); 327 328 /** 329 * @brief Set DisposalTypes number for OH_PackingOptionsForSequence struct. 330 * 331 * @param options The OH_PackingOptionsForSequence pointer will be operated. 332 * @param disposalTypes The pointer of image disposalTypes. 333 * @param disposalTypesLength The number of image disposalTypesLength. 334 * @return Image functions result code. 335 * {@link IMAGE_SUCCESS} if the execution is successful. 336 * {@link IMAGE_BAD_PARAMETER} options or disposalTypes is nullptr. 337 * @since 12 338 */ 339 Image_ErrorCode OH_PackingOptionsForSequence_SetDisposalTypes(OH_PackingOptionsForSequence *options, 340 uint32_t *disposalTypes, size_t disposalTypesLength); 341 342 /** 343 * @brief Get DisposalTypes number for OH_PackingOptionsForSequence struct. 344 * 345 * @param options The OH_PackingOptionsForSequence pointer will be operated. 346 * @param disposalTypes The pointer of image disposalTypes. 347 * @param disposalTypesLength The number of image disposalTypesLength. 348 * @return Image functions result code. 349 * {@link IMAGE_SUCCESS} if the execution is successful. 350 * {@link IMAGE_BAD_PARAMETER} options or disposalTypes is nullptr. 351 * @since 12 352 */ 353 Image_ErrorCode OH_PackingOptionsForSequence_GetDisposalTypes(OH_PackingOptionsForSequence *options, 354 uint32_t *disposalTypes, size_t disposalTypesLength); 355 356 /** 357 * @brief Set LoopCount number for OH_PackingOptionsForSequence struct. 358 * 359 * @param options The OH_PackingOptionsForSequence pointer will be operated. 360 * @param loopCount The number of image loopCount. 361 * @return Image functions result code. 362 * {@link IMAGE_SUCCESS} if the execution is successful. 363 * {@link IMAGE_BAD_PARAMETER} options is nullptr. 364 * @since 12 365 */ 366 Image_ErrorCode OH_PackingOptionsForSequence_SetLoopCount(OH_PackingOptionsForSequence *options, uint32_t loopCount); 367 368 /** 369 * @brief Get LoopCount number for OH_PackingOptionsForSequence struct. 370 * 371 * @param options The OH_PackingOptionsForSequence pointer will be operated. 372 * @param loopCount The number of image loopCount. 373 * @return Image functions result code. 374 * {@link IMAGE_SUCCESS} if the execution is successful. 375 * {@link IMAGE_BAD_PARAMETER} options or loopCount is nullptr. 376 * @since 12 377 */ 378 Image_ErrorCode OH_PackingOptionsForSequence_GetLoopCount(OH_PackingOptionsForSequence *options, uint32_t *loopCount); 379 380 /** 381 * @brief delete OH_PackingOptionsForSequence pointer. 382 * 383 * @param options The OH_PackingOptionsForSequence pointer will be operated. 384 * @return Image functions result code. 385 * {@link IMAGE_SUCCESS} if the execution is successful. 386 * {@link IMAGE_BAD_PARAMETER} options is nullptr. 387 * @since 12 388 */ 389 Image_ErrorCode OH_PackingOptionsForSequence_Release(OH_PackingOptionsForSequence *options); 390 391 /** 392 * @brief Create a pointer for OH_ImagePackerNative struct. 393 * 394 * @param options The OH_ImagePackerNative pointer will be operated. 395 * @return Returns {@link Image_ErrorCode} 396 * @since 12 397 */ 398 Image_ErrorCode OH_ImagePackerNative_Create(OH_ImagePackerNative **imagePacker); 399 400 /** 401 * @brief Encoding an <b>ImageSource</b> into the data with required format. 402 * 403 * @param imagePacker The imagePacker to use for packing. 404 * @param options Indicates the encoding {@link OH_PackingOptions}. 405 * @param imageSource The imageSource to be packed. 406 * @param outData The output data buffer to store the packed image. 407 * @param size A pointer to the size of the output data buffer. 408 * @return Returns {@link Image_ErrorCode} 409 * @since 12 410 */ 411 Image_ErrorCode OH_ImagePackerNative_PackToDataFromImageSource(OH_ImagePackerNative *imagePacker, 412 OH_PackingOptions *options, OH_ImageSourceNative *imageSource, uint8_t *outData, size_t *size); 413 414 /** 415 * @brief Encoding a <b>Pixelmap</b> into the data with required format. 416 * 417 * @param imagePacker The imagePacker to use for packing. 418 * @param options Indicates the encoding {@link OH_PackingOptions}. 419 * @param pixelmap The pixelmap to be packed. 420 * @param outData The output data buffer to store the packed image. 421 * @param size A pointer to the size of the output data buffer. 422 * @return Returns {@link Image_ErrorCode} 423 * @since 12 424 */ 425 Image_ErrorCode OH_ImagePackerNative_PackToDataFromPixelmap(OH_ImagePackerNative *imagePacker, 426 OH_PackingOptions *options, OH_PixelmapNative *pixelmap, uint8_t *outData, size_t *size); 427 428 /** 429 * @brief Encoding an <b>ImageSource</b> into the a file with fd with required format. 430 * 431 * @param imagePacker The image packer to use for packing. 432 * @param options Indicates the encoding {@link OH_PackingOptions}. 433 * @param imageSource The imageSource to be packed. 434 * @param fd Indicates a writable file descriptor. 435 * @return Returns {@link Image_ErrorCode} 436 * @since 12 437 */ 438 Image_ErrorCode OH_ImagePackerNative_PackToFileFromImageSource(OH_ImagePackerNative *imagePacker, 439 OH_PackingOptions *options, OH_ImageSourceNative *imageSource, int32_t fd); 440 441 /** 442 * @brief Encoding a <b>Pixelmap</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 pixelmap The pixelmap 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_PackToFileFromPixelmap(OH_ImagePackerNative *imagePacker, 452 OH_PackingOptions *options, OH_PixelmapNative *pixelmap, int32_t fd); 453 454 /** 455 * @brief Releases an imagePacker object. 456 * 457 * @param imagePacker A pointer to the image packer object to be released. 458 * @return Returns {@link Image_ErrorCode} 459 * @since 12 460 */ 461 Image_ErrorCode OH_ImagePackerNative_Release(OH_ImagePackerNative *imagePacker); 462 463 /** 464 * @brief Encoding a <b>Picture</b> into the data with required format. 465 * 466 * @param imagePacker The imagePacker to use for packing. 467 * @param options Indicates the encoding {@link OH_PackingOptions}. 468 * @param picture The picture to be packed. 469 * @param outData The output data buffer to store the packed image. 470 * @param size A pointer to the size of the output data buffer. 471 * @return Image functions result code. 472 * {@link IMAGE_SUCCESS} if the execution is successful. 473 * {@link IMAGE_BAD_PARAMETER} imagePacker is nullptr, or picture is nullptr, or outData is nullptr, 474 * or size is invalid. 475 * {@link IMAGE_ENCODE_FAILED} encode failed. 476 * @since 13 477 */ 478 Image_ErrorCode OH_ImagePackerNative_PackToDataFromPicture(OH_ImagePackerNative *imagePacker, 479 OH_PackingOptions *options, OH_PictureNative *picture, uint8_t *outData, size_t *size); 480 481 /** 482 * @brief Encoding a <b>PixelMap</b> sequence into the data 483 * 484 * @param imagePacker The imagePacker to use for packing. 485 * @param options Indicates the encoding {@link OH_PackingOptionsForSequence}. 486 * @param pixelmapSequence The pixelmap sequence to be packed. 487 * @param sequenceLength The pixelmap sequence size to be packed. 488 * @param outData The output data buffer to store the packed image. 489 * @param outDataSize A pointer to the size of the output data buffer. 490 * @return Image functions result code. 491 * {@link IMAGE_SUCCESS} if the execution is successful. 492 * {@link IMAGE_BAD_PARAMETER} one of the pointer type parameters is nullptr, or size/length is invalid 493 * {@link IMAGE_ENCODE_FAILED} encode failed. 494 * @since 13 495 */ 496 Image_ErrorCode OH_ImagePackerNative_PackToDataFromPixelmapSequence(OH_ImagePackerNative *imagePacker, 497 OH_PackingOptionsForSequence *options, OH_PixelmapNative **pixelmapSequence, 498 size_t sequenceLength, uint8_t *outData, size_t *outDataSize); 499 500 /** 501 * @brief Encoding a <b>Picture</b> into the a file with fd with required format. 502 * 503 * @param imagePacker The imagePacker to use for packing. 504 * @param options Indicates the encoding {@link OH_PackingOptions}. 505 * @param picture The picture to be packed. 506 * @param fd Indicates a writable file descriptor. 507 * @return Image functions result code. 508 * {@link IMAGE_SUCCESS} if the execution is successful. 509 * {@link IMAGE_BAD_PARAMETER} imagePacker is nullptr, or picture is nullptr, or fd is invalid. 510 * {@link IMAGE_ENCODE_FAILED} encode failed. 511 * @since 13 512 */ 513 Image_ErrorCode OH_ImagePackerNative_PackToFileFromPicture(OH_ImagePackerNative *imagePacker, 514 OH_PackingOptions *options, OH_PictureNative *picture, int32_t fd); 515 516 /** 517 * @brief Encoding a <b>PixelMap</b> sequence into the a file with fd 518 * 519 * @param imagePacker The image packer to use for packing. 520 * @param options Indicates the encoding {@link OH_PackingOptionsForSequence}. 521 * @param pixelmapSequence The pixelmap sequence to be packed. 522 * @param sequenceLength The pixelmap sequence size to be packed. 523 * @param fd Indicates a writable file descriptor. 524 * @return Image functions result code. 525 * {@link IMAGE_SUCCESS} if the execution is successful. 526 * {@link IMAGE_BAD_PARAMETER} one of the pointer type parameters is nullptr, or length is invalid 527 * {@link IMAGE_ENCODE_FAILED} encode failed. 528 * @since 12 529 */ 530 Image_ErrorCode OH_ImagePackerNative_PackToFileFromPixelmapSequence(OH_ImagePackerNative *imagePacker, 531 OH_PackingOptionsForSequence *options, OH_PixelmapNative **pixelmapSequence, size_t sequenceLength, int32_t fd); 532 533 #ifdef __cplusplus 534 }; 535 #endif 536 /* *@} */ 537 #endif // INTERFACES_KITS_NATIVE_INCLUDE_IMAGE_IMAGE_PACKER_NATIVE_H