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