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 13 66 */ 67 struct OH_PackingOptionsForSequence; 68 69 /** 70 * @brief Defines the image sequence packing options. 71 * 72 * @since 13 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 Set format number for OH_PackingOptions struct. 115 * 116 * @param options The OH_PackingOptions pointer will be operated. 117 * @param format the number of image format. 118 * @return Returns {@link Image_ErrorCode} 119 * @since 12 120 */ 121 Image_ErrorCode OH_PackingOptions_SetMimeType(OH_PackingOptions *options, 122 Image_MimeType *format); 123 124 /** 125 * @brief Get quality for OH_PackingOptions struct. 126 * 127 * @param options The OH_PackingOptions pointer will be operated. 128 * @param quality The number of image quality. 129 * @return Returns {@link Image_ErrorCode} 130 * @since 12 131 */ 132 Image_ErrorCode OH_PackingOptions_GetQuality(OH_PackingOptions *options, 133 uint32_t *quality); 134 135 /** 136 * @brief Set quality number for OH_PackingOptions struct. 137 * 138 * @param options The OH_PackingOptions pointer will be operated. 139 * @param quality The number of image quality. 140 * @return Returns {@link Image_ErrorCode} 141 * @since 12 142 */ 143 Image_ErrorCode OH_PackingOptions_SetQuality(OH_PackingOptions *options, 144 uint32_t quality); 145 146 /** 147 * @brief Get needsPackProperties for OH_PackingOptions struct. 148 * 149 * @param options The OH_PackingOptions pointer will be operated. 150 * @param needsPackProperties Whether the image properties can be saved, like Exif. 151 * @return Returns {@link Image_ErrorCode} 152 * @since 12 153 */ 154 Image_ErrorCode OH_PackingOptions_GetNeedsPackProperties(OH_PackingOptions *options, 155 bool *needsPackProperties); 156 157 /** 158 * @brief Set 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_SetNeedsPackProperties(OH_PackingOptions *options, 166 bool needsPackProperties); 167 168 /** 169 * @brief Get desiredDynamicRange for PackingOptions struct. 170 * 171 * @param options The PackingOptions pointer will be operated. Pointer connot be null. 172 * @param desiredDynamicRange The number of dynamic range {@link IMAGE_PACKER_DYNAMIC_RANGE}. Pointer connot be null. 173 * @return Returns {@link Image_ErrorCode} IMAGE_SUCCESS - The operation is successful. 174 * returns {@link Image_ErrorCode} IMAGE_BAD_PARAMETER - Parameter error.Possible causes:Parameter verification failed. 175 * @since 12 176 */ 177 Image_ErrorCode OH_PackingOptions_GetDesiredDynamicRange(OH_PackingOptions *options, int32_t* desiredDynamicRange); 178 179 /** 180 * @brief Set desiredDynamicRange number for PackingOptions struct. 181 * 182 * @param options The PackingOptions pointer will be operated. Pointer connot be null. 183 * @param desiredDynamicRange The number of dynamic range {@link IMAGE_PACKER_DYNAMIC_RANGE}. 184 * @return Returns {@link Image_ErrorCode} IMAGE_SUCCESS - The operation is successful. 185 * returns {@link Image_ErrorCode} IMAGE_BAD_PARAMETER - Parameter error.Possible causes:Parameter verification failed. 186 * @since 12 187 */ 188 Image_ErrorCode OH_PackingOptions_SetDesiredDynamicRange(OH_PackingOptions *options, int32_t desiredDynamicRange); 189 190 /** 191 * @brief delete OH_PackingOptions pointer. 192 * 193 * @param options The OH_PackingOptions pointer will be operated. 194 * @return Returns {@link Image_ErrorCode} 195 * @since 12 196 */ 197 Image_ErrorCode OH_PackingOptions_Release(OH_PackingOptions *options); 198 199 /** 200 * @brief Create a pointer for OH_PackingOptionsForSequence struct. 201 * 202 * @param options The OH_PackingOptionsForSequence pointer will be operated. 203 * @return Image functions result code. 204 * {@link IMAGE_SUCCESS} if the execution is successful. 205 * {@link IMAGE_BAD_PARAMETER} options is nullptr. 206 * @since 13 207 */ 208 Image_ErrorCode OH_PackingOptionsForSequence_Create(OH_PackingOptionsForSequence **options); 209 210 /** 211 * @brief Set FrameCount number for OH_PackingOptionsForSequence struct. 212 * 213 * @param options The OH_PackingOptionsForSequence pointer will be operated. 214 * @param frameCount The number of image frameCount. 215 * @return Image functions result code. 216 * {@link IMAGE_SUCCESS} if the execution is successful. 217 * {@link IMAGE_BAD_PARAMETER} options is nullptr. 218 * @since 13 219 */ 220 Image_ErrorCode OH_PackingOptionsForSequence_SetFrameCount(OH_PackingOptionsForSequence *options, 221 uint32_t frameCount); 222 223 /** 224 * @brief Get 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 or frameCount is nullptr. 231 * @since 13 232 */ 233 Image_ErrorCode OH_PackingOptionsForSequence_GetFrameCount(OH_PackingOptionsForSequence *options, 234 uint32_t *frameCount); 235 236 /** 237 * @brief Set DelayTimeList number for OH_PackingOptionsForSequence struct. 238 * 239 * @param options The OH_PackingOptionsForSequence pointer will be operated. 240 * @param delayTimeList The pointer of image delayTime list. 241 * @param delayTimeListLength The number of image delayTimeListLength. 242 * @return Image functions result code. 243 * {@link IMAGE_SUCCESS} if the execution is successful. 244 * {@link IMAGE_BAD_PARAMETER} options or delayTimeList is nullptr. 245 * @since 13 246 */ 247 Image_ErrorCode OH_PackingOptionsForSequence_SetDelayTimeList(OH_PackingOptionsForSequence *options, 248 int32_t *delayTimeList, size_t delayTimeListLength); 249 250 /** 251 * @brief Get DelayTimeList number for OH_PackingOptionsForSequence struct. 252 * 253 * @param options The OH_PackingOptionsForSequence pointer will be operated. 254 * @param delayTimeList The pointer of image delayTime list. 255 * @param delayTimeListLength The number of image delayTimeListLength. 256 * @return Image functions result code. 257 * {@link IMAGE_SUCCESS} if the execution is successful. 258 * {@link IMAGE_BAD_PARAMETER} options or delayTimeList is nullptr. 259 * @since 13 260 */ 261 Image_ErrorCode OH_PackingOptionsForSequence_GetDelayTimeList(OH_PackingOptionsForSequence *options, 262 int32_t *delayTimeList, size_t delayTimeListLength); 263 264 /** 265 * @brief Set DisposalTypes number for OH_PackingOptionsForSequence struct. 266 * 267 * @param options The OH_PackingOptionsForSequence pointer will be operated. 268 * @param disposalTypes The pointer of image disposalTypes. 269 * @param disposalTypesLength The number of image disposalTypesLength. 270 * @return Image functions result code. 271 * {@link IMAGE_SUCCESS} if the execution is successful. 272 * {@link IMAGE_BAD_PARAMETER} options or disposalTypes is nullptr. 273 * @since 13 274 */ 275 Image_ErrorCode OH_PackingOptionsForSequence_SetDisposalTypes(OH_PackingOptionsForSequence *options, 276 uint32_t *disposalTypes, size_t disposalTypesLength); 277 278 /** 279 * @brief Get DisposalTypes number for OH_PackingOptionsForSequence struct. 280 * 281 * @param options The OH_PackingOptionsForSequence pointer will be operated. 282 * @param disposalTypes The pointer of image disposalTypes. 283 * @param disposalTypesLength The number of image disposalTypesLength. 284 * @return Image functions result code. 285 * {@link IMAGE_SUCCESS} if the execution is successful. 286 * {@link IMAGE_BAD_PARAMETER} options or disposalTypes is nullptr. 287 * @since 13 288 */ 289 Image_ErrorCode OH_PackingOptionsForSequence_GetDisposalTypes(OH_PackingOptionsForSequence *options, 290 uint32_t *disposalTypes, size_t disposalTypesLength); 291 292 /** 293 * @brief Set LoopCount number for OH_PackingOptionsForSequence struct. 294 * 295 * @param options The OH_PackingOptionsForSequence pointer will be operated. 296 * @param loopCount The number of image loopCount. 297 * @return Image functions result code. 298 * {@link IMAGE_SUCCESS} if the execution is successful. 299 * {@link IMAGE_BAD_PARAMETER} options is nullptr. 300 * @since 13 301 */ 302 Image_ErrorCode OH_PackingOptionsForSequence_SetLoopCount(OH_PackingOptionsForSequence *options, uint32_t loopCount); 303 304 /** 305 * @brief Get LoopCount number for OH_PackingOptionsForSequence struct. 306 * 307 * @param options The OH_PackingOptionsForSequence pointer will be operated. 308 * @param loopCount The number of image loopCount. 309 * @return Image functions result code. 310 * {@link IMAGE_SUCCESS} if the execution is successful. 311 * {@link IMAGE_BAD_PARAMETER} options or loopCount is nullptr. 312 * @since 13 313 */ 314 Image_ErrorCode OH_PackingOptionsForSequence_GetLoopCount(OH_PackingOptionsForSequence *options, uint32_t *loopCount); 315 316 /** 317 * @brief delete OH_PackingOptionsForSequence pointer. 318 * 319 * @param options The OH_PackingOptionsForSequence pointer will be operated. 320 * @return Image functions result code. 321 * {@link IMAGE_SUCCESS} if the execution is successful. 322 * {@link IMAGE_BAD_PARAMETER} options is nullptr. 323 * @since 13 324 */ 325 Image_ErrorCode OH_PackingOptionsForSequence_Release(OH_PackingOptionsForSequence *options); 326 327 /** 328 * @brief Create a pointer for OH_ImagePackerNative struct. 329 * 330 * @param options The OH_ImagePackerNative pointer will be operated. 331 * @return Returns {@link Image_ErrorCode} 332 * @since 12 333 */ 334 Image_ErrorCode OH_ImagePackerNative_Create(OH_ImagePackerNative **imagePacker); 335 336 /** 337 * @brief Encoding an <b>ImageSource</b> into the data with required format. 338 * 339 * @param imagePacker The imagePacker to use for packing. 340 * @param options Indicates the encoding {@link OH_PackingOptions}. 341 * @param imageSource The imageSource to be packed. 342 * @param outData The output data buffer to store the packed image. 343 * @param size A pointer to the size of the output data buffer. 344 * @return Returns {@link Image_ErrorCode} 345 * @since 12 346 */ 347 Image_ErrorCode OH_ImagePackerNative_PackToDataFromImageSource(OH_ImagePackerNative *imagePacker, 348 OH_PackingOptions *options, OH_ImageSourceNative *imageSource, uint8_t *outData, size_t *size); 349 350 /** 351 * @brief Encoding a <b>Pixelmap</b> into the data with required format. 352 * 353 * @param imagePacker The imagePacker to use for packing. 354 * @param options Indicates the encoding {@link OH_PackingOptions}. 355 * @param pixelmap The pixelmap to be packed. 356 * @param outData The output data buffer to store the packed image. 357 * @param size A pointer to the size of the output data buffer. 358 * @return Returns {@link Image_ErrorCode} 359 * @since 12 360 */ 361 Image_ErrorCode OH_ImagePackerNative_PackToDataFromPixelmap(OH_ImagePackerNative *imagePacker, 362 OH_PackingOptions *options, OH_PixelmapNative *pixelmap, uint8_t *outData, size_t *size); 363 364 /** 365 * @brief Encoding a <b>Picture</b> into the data with required format. 366 * 367 * @param imagePacker The imagePacker to use for packing. 368 * @param options Indicates the encoding {@link OH_PackingOptions}. 369 * @param picture The picture to be packed. 370 * @param outData The output data buffer to store the packed image. 371 * @param size A pointer to the size of the output data buffer. 372 * @return Image functions result code. 373 * {@link IMAGE_SUCCESS} if the execution is successful. 374 * {@link IMAGE_BAD_PARAMETER} imagePacker is nullptr, or picture is nullptr, or outData is nullptr, 375 * or size is invalid. 376 * {@link IMAGE_ENCODE_FAILED} encode failed. 377 * @since 13 378 */ 379 Image_ErrorCode OH_ImagePackerNative_PackToDataFromPicture(OH_ImagePackerNative *imagePacker, 380 OH_PackingOptions *options, OH_PictureNative *picture, uint8_t *outData, size_t *size); 381 382 /** 383 * @brief Encoding a <b>PixelMap</b> sequence into the data 384 * 385 * @param imagePacker The imagePacker to use for packing. 386 * @param options Indicates the encoding {@link OH_PackingOptionsForSequence}. 387 * @param pixelmapSequence The pixelmap sequence to be packed. 388 * @param sequenceLength The pixelmap sequence size to be packed. 389 * @param outData The output data buffer to store the packed image. 390 * @param outDataSize A pointer to the size of the output data buffer. 391 * @return Image functions result code. 392 * {@link IMAGE_SUCCESS} if the execution is successful. 393 * {@link IMAGE_BAD_PARAMETER} one of the pointer type parameters is nullptr, or size/length is invalid 394 * {@link IMAGE_ENCODE_FAILED} encode failed. 395 * @since 13 396 */ 397 Image_ErrorCode OH_ImagePackerNative_PackToDataFromPixelmapSequence(OH_ImagePackerNative *imagePacker, 398 OH_PackingOptionsForSequence *options, OH_PixelmapNative **pixelmapSequence, 399 size_t sequenceLength, uint8_t *outData, size_t *outDataSize); 400 401 /** 402 * @brief Encoding an <b>ImageSource</b> into the a file with fd with required format. 403 * 404 * @param imagePacker The image packer to use for packing. 405 * @param options Indicates the encoding {@link OH_PackingOptions}. 406 * @param imageSource The imageSource to be packed. 407 * @param fd Indicates a writable file descriptor. 408 * @return Returns {@link Image_ErrorCode} 409 * @since 12 410 */ 411 Image_ErrorCode OH_ImagePackerNative_PackToFileFromImageSource(OH_ImagePackerNative *imagePacker, 412 OH_PackingOptions *options, OH_ImageSourceNative *imageSource, int32_t fd); 413 414 /** 415 * @brief Encoding a <b>Pixelmap</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 pixelmap The pixelmap 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_PackToFileFromPixelmap(OH_ImagePackerNative *imagePacker, 425 OH_PackingOptions *options, OH_PixelmapNative *pixelmap, int32_t fd); 426 427 /** 428 * @brief Encoding a <b>Picture</b> into the a file with fd with required format. 429 * 430 * @param imagePacker The imagePacker to use for packing. 431 * @param options Indicates the encoding {@link OH_PackingOptions}. 432 * @param picture The picture to be packed. 433 * @param fd Indicates a writable file descriptor. 434 * @return Image functions result code. 435 * {@link IMAGE_SUCCESS} if the execution is successful. 436 * {@link IMAGE_BAD_PARAMETER} imagePacker is nullptr, or picture is nullptr, or fd is invalid. 437 * {@link IMAGE_ENCODE_FAILED} encode failed. 438 * @since 13 439 */ 440 Image_ErrorCode OH_ImagePackerNative_PackToFileFromPicture(OH_ImagePackerNative *imagePacker, 441 OH_PackingOptions *options, OH_PictureNative *picture, int32_t fd); 442 443 /** 444 * @brief Encoding a <b>PixelMap</b> sequence into the a file with fd 445 * 446 * @param imagePacker The image packer to use for packing. 447 * @param options Indicates the encoding {@link OH_PackingOptionsForSequence}. 448 * @param pixelmapSequence The pixelmap sequence to be packed. 449 * @param sequenceLength The pixelmap sequence size to be packed. 450 * @param fd Indicates a writable file descriptor. 451 * @return Image functions result code. 452 * {@link IMAGE_SUCCESS} if the execution is successful. 453 * {@link IMAGE_BAD_PARAMETER} one of the pointer type parameters is nullptr, or length is invalid 454 * {@link IMAGE_ENCODE_FAILED} encode failed. 455 * @since 13 456 */ 457 Image_ErrorCode OH_ImagePackerNative_PackToFileFromPixelmapSequence(OH_ImagePackerNative *imagePacker, 458 OH_PackingOptionsForSequence *options, OH_PixelmapNative **pixelmapSequence, size_t sequenceLength, int32_t fd); 459 460 /** 461 * @brief Releases an imagePacker object. 462 * 463 * @param imagePacker A pointer to the image packer object to be released. 464 * @return Returns {@link Image_ErrorCode} 465 * @since 12 466 */ 467 Image_ErrorCode OH_ImagePackerNative_Release(OH_ImagePackerNative *imagePacker); 468 469 #ifdef __cplusplus 470 }; 471 #endif 472 /* *@} */ 473 #endif // INTERFACES_KITS_NATIVE_INCLUDE_IMAGE_IMAGE_PACKER_NATIVE_H_