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 Enumerates packing dynamic range. 63 * 64 * @since 12 65 */ 66 typedef enum { 67 /* 68 * Packing according to the content of the image. 69 */ 70 IMAGE_PACKER_DYNAMIC_RANGE_AUTO = 0, 71 /* 72 * Packing to standard dynamic range. 73 */ 74 IMAGE_PACKER_DYNAMIC_RANGE_SDR = 1, 75 } IMAGE_PACKER_DYNAMIC_RANGE; 76 77 /** 78 * @brief Create a pointer for PackingOptions struct. 79 * 80 * @param options The PackingOptions pointer will be operated. 81 * @return Returns {@link Image_ErrorCode} 82 * @since 12 83 */ 84 Image_ErrorCode OH_PackingOptions_Create(OH_PackingOptions **options); 85 86 /** 87 * @brief Get mime type for DecodingOptions struct. 88 * 89 * @param options The DecodingOptions pointer will be operated. 90 * @param format the number of image format.The user can pass in a null pointer and zero size, we will allocate memory, 91 * but user must free memory after use. 92 * @return Returns {@link Image_ErrorCode} 93 * @since 12 94 */ 95 Image_ErrorCode OH_PackingOptions_GetMimeType(OH_PackingOptions *options, 96 Image_MimeType *format); 97 98 /** 99 * @brief Set format number for DecodingOptions struct. 100 * 101 * @param options The DecodingOptions pointer will be operated. 102 * @param format the number of image format. 103 * @return Returns {@link Image_ErrorCode} 104 * @since 12 105 */ 106 Image_ErrorCode OH_PackingOptions_SetMimeType(OH_PackingOptions *options, 107 Image_MimeType *format); 108 109 /** 110 * @brief Get quality for DecodingOptions struct. 111 * 112 * @param options The DecodingOptions pointer will be operated. 113 * @param quality the number of image quality. 114 * @return Returns {@link Image_ErrorCode} 115 * @since 12 116 */ 117 Image_ErrorCode OH_PackingOptions_GetQuality(OH_PackingOptions *options, 118 uint32_t *quality); 119 120 /** 121 * @brief Set quality number for DecodingOptions struct. 122 * 123 * @param options The DecodingOptions pointer will be operated. 124 * @param quality the number of image quality. 125 * @return Returns {@link Image_ErrorCode} 126 * @since 12 127 */ 128 Image_ErrorCode OH_PackingOptions_SetQuality(OH_PackingOptions *options, 129 uint32_t quality); 130 /** 131 * @brief Get needsPackProperties for OH_PackingOptions struct. 132 * 133 * @param options The OH_PackingOptions pointer will be operated. 134 * @param needsPackProperties Whether the image properties can be saved, like Exif. 135 * @return Returns {@link Image_ErrorCode} 136 * @since 12 137 */ 138 Image_ErrorCode OH_PackingOptions_GetNeedsPackProperties(OH_PackingOptions *options, 139 bool *needsPackProperties); 140 141 /** 142 * @brief Set needsPackProperties for OH_PackingOptions struct. 143 * 144 * @param options The OH_PackingOptions pointer will be operated. 145 * @param needsPackProperties Whether the image properties can be saved, like Exif. 146 * @return Returns {@link Image_ErrorCode} 147 * @since 12 148 */ 149 Image_ErrorCode OH_PackingOptions_SetNeedsPackProperties(OH_PackingOptions *options, 150 bool needsPackProperties); 151 152 /** 153 * @brief Get desiredDynamicRange for PackingOptions struct. 154 * 155 * @param options The PackingOptions pointer will be operated. 156 * @param desiredDynamicRange The number of dynamic range {@link IMAGE_PACKER_DYNAMIC_RANGE}. 157 * @return Returns {@link Image_ErrorCode} 158 * @since 12 159 */ 160 Image_ErrorCode OH_PackingOptions_GetDesiredDynamicRange(OH_PackingOptions *options, int32_t* desiredDynamicRange); 161 162 /** 163 * @brief Set desiredDynamicRange number for PackingOptions struct. 164 * 165 * @param options The PackingOptions pointer will be operated. 166 * @param desiredDynamicRange The number of dynamic range {@link IMAGE_PACKER_DYNAMIC_RANGE}. 167 * @return Returns {@link Image_ErrorCode} 168 * @since 12 169 */ 170 Image_ErrorCode OH_PackingOptions_SetDesiredDynamicRange(OH_PackingOptions *options, int32_t desiredDynamicRange); 171 172 /** 173 * @brief Set Loop number for PackingOptions struct. 174 * 175 * @param options The PackingOptions pointer will be operated. 176 * @param loop The number of image loop. 177 * @return Returns {@link Image_ErrorCode} 178 * @since 12 179 */ 180 Image_ErrorCode OH_PackingOptions_SetLoop(OH_PackingOptions *options, uint16_t loop); 181 182 /** 183 * @brief Get Loop number for PackingOptions struct. 184 * 185 * @param options The PackingOptions pointer will be operated. 186 * @param loop The number of image loop. 187 * @return Returns {@link Image_ErrorCode} 188 * @since 12 189 */ 190 Image_ErrorCode OH_PackingOptions_GetLoop(OH_PackingOptions *options, uint16_t *loop); 191 192 /** 193 * @brief Set DelayTimes number for PackingOptions struct. 194 * 195 * @param options The PackingOptions pointer will be operated. 196 * @param delayTimes The number of image delayTimes. 197 * @param delayTimesSize The number of image delayTimesSize. 198 * @return Returns {@link Image_ErrorCode} 199 * @since 12 200 */ 201 Image_ErrorCode OH_PackingOptions_SetDelayTimes(OH_PackingOptions *options, uint16_t* delayTimes, 202 uint32_t delayTimesSize); 203 204 /** 205 * @brief Get DelayTimes number for PackingOptions struct. 206 * 207 * @param options The PackingOptions pointer will be operated. 208 * @param delayTimes The number of image delayTimes. 209 * @param delayTimesSize The number of image delayTimesSize. 210 * @return Returns {@link Image_ErrorCode} 211 * @since 12 212 */ 213 Image_ErrorCode OH_PackingOptions_GetDelayTimes(OH_PackingOptions *options, uint16_t* delayTimes, 214 uint32_t *delayTimesSize); 215 216 /** 217 * @brief Set DisposalTypes number for PackingOptions struct. 218 * 219 * @param options The PackingOptions pointer will be operated. 220 * @param disposalTypes The number of image disposalTypes. 221 * @param disposalTypesSize The number of image disposalTypesSize. 222 * @return Returns {@link Image_ErrorCode} 223 * @since 12 224 */ 225 Image_ErrorCode OH_PackingOptions_SetDisposalTypes(OH_PackingOptions *options, uint16_t* disposalTypes, 226 uint32_t disposalTypesSize); 227 228 /** 229 * @brief Get DisposalTypes number for PackingOptions struct. 230 * 231 * @param options The PackingOptions pointer will be operated. 232 * @param disposalTypes The number of image disposalTypes. 233 * @param disposalTypesSize The number of image disposalTypesSize. 234 * @return Returns {@link Image_ErrorCode} 235 * @since 12 236 */ 237 Image_ErrorCode OH_PackingOptions_GetDisposalTypes(OH_PackingOptions *options, uint16_t* disposalTypes, 238 uint32_t* disposalTypesSize); 239 240 /** 241 * @brief delete DecodingOptions pointer. 242 * 243 * @param options The DecodingOptions pointer will be operated. 244 * @return Returns {@link Image_ErrorCode} 245 * @since 12 246 */ 247 Image_ErrorCode OH_PackingOptions_Release(OH_PackingOptions *options); 248 249 /** 250 * @brief Create a pointer for OH_ImagePackerNative struct. 251 * 252 * @param options The OH_ImagePackerNative pointer will be operated. 253 * @return Returns {@link Image_ErrorCode} 254 * @since 12 255 */ 256 Image_ErrorCode OH_ImagePackerNative_Create(OH_ImagePackerNative **imagePacker); 257 258 /** 259 * @brief Encoding an <b>ImageSource</b> into the data with required format. 260 * 261 * @param imagePacker The imagePacker to use for packing. 262 * @param options Indicates the encoding {@link OH_PackingOptions}. 263 * @param imageSource The imageSource to be packed. 264 * @param outData The output data buffer to store the packed image. 265 * @param size A pointer to the size of the output data buffer. 266 * @return Returns {@link Image_ErrorCode} 267 * @since 12 268 */ 269 Image_ErrorCode OH_ImagePackerNative_PackToDataFromImageSource(OH_ImagePackerNative *imagePacker, 270 OH_PackingOptions *options, OH_ImageSourceNative *imageSource, uint8_t *outData, size_t *size); 271 272 /** 273 * @brief Encoding a <b>Pixelmap</b> into the data with required format. 274 * 275 * @param imagePacker The imagePacker to use for packing. 276 * @param options Indicates the encoding {@link OH_PackingOptions}. 277 * @param pixelmap The pixelmap to be packed. 278 * @param outData The output data buffer to store the packed image. 279 * @param size A pointer to the size of the output data buffer. 280 * @return Returns {@link Image_ErrorCode} 281 * @since 12 282 */ 283 Image_ErrorCode OH_ImagePackerNative_PackToDataFromPixelmap(OH_ImagePackerNative *imagePacker, 284 OH_PackingOptions *options, OH_PixelmapNative *pixelmap, uint8_t *outData, size_t *size); 285 286 /** 287 * @brief Encoding an <b>ImageSource</b> into the a file with fd with required format. 288 * 289 * @param imagePacker The image packer to use for packing. 290 * @param options Indicates the encoding {@link OH_PackingOptions}. 291 * @param imageSource The imageSource to be packed. 292 * @param fd Indicates a writable file descriptor. 293 * @return Returns {@link Image_ErrorCode} 294 * @since 12 295 */ 296 Image_ErrorCode OH_ImagePackerNative_PackToFileFromImageSource(OH_ImagePackerNative *imagePacker, 297 OH_PackingOptions *options, OH_ImageSourceNative *imageSource, int32_t fd); 298 299 /** 300 * @brief Encoding a <b>Pixelmap</b> into the a file with fd with required format 301 * 302 * @param imagePacker The image packer to use for packing. 303 * @param options Indicates the encoding {@link OH_PackingOptions}. 304 * @param pixelmap The pixelmap to be packed. 305 * @param fd Indicates a writable file descriptor. 306 * @return Returns {@link Image_ErrorCode} 307 * @since 12 308 */ 309 Image_ErrorCode OH_ImagePackerNative_PackToFileFromPixelmap(OH_ImagePackerNative *imagePacker, 310 OH_PackingOptions *options, OH_PixelmapNative *pixelmap, int32_t fd); 311 312 /** 313 * @brief Releases an imagePacker object. 314 * 315 * @param imagePacker A pointer to the image packer object to be released. 316 * @return Returns {@link Image_ErrorCode} 317 * @since 12 318 */ 319 Image_ErrorCode OH_ImagePackerNative_Release(OH_ImagePackerNative *imagePacker); 320 321 /** 322 * @brief Encoding a <b>Picture</b> into the data with required format. 323 * 324 * @param imagePacker The imagePacker to use for packing. 325 * @param options Indicates the encoding {@link OH_PackingOptions}. 326 * @param picture The picture to be packed. 327 * @param outData The output data buffer to store the packed image. 328 * @param size A pointer to the size of the output data buffer. 329 * @return Image functions result code. 330 * {@link IMAGE_SUCCESS} if the execution is successful. 331 * {@link IMAGE_BAD_PARAMETER} imagePacker is nullptr, or picture is nullptr, or outData is nullptr, 332 * or size is invalid. 333 * {@link IMAGE_ENCODE_FAILED} encode failed. 334 * @since 13 335 */ 336 Image_ErrorCode OH_ImagePackerNative_PackToDataFromPicture(OH_ImagePackerNative *imagePacker, 337 OH_PackingOptions *options, OH_PictureNative *picture, uint8_t *outData, size_t *size); 338 339 /** 340 * @brief Encoding a <b>Picture</b> into the a file with fd with required format. 341 * 342 * @param imagePacker The imagePacker to use for packing. 343 * @param options Indicates the encoding {@link OH_PackingOptions}. 344 * @param picture The picture to be packed. 345 * @param fd Indicates a writable file descriptor. 346 * @return Image functions result code. 347 * {@link IMAGE_SUCCESS} if the execution is successful. 348 * {@link IMAGE_BAD_PARAMETER} imagePacker is nullptr, or picture is nullptr, or fd is invalid. 349 * {@link IMAGE_ENCODE_FAILED} encode failed. 350 * @since 13 351 */ 352 Image_ErrorCode OH_ImagePackerNative_PackToFileFromPicture(OH_ImagePackerNative *imagePacker, 353 OH_PackingOptions *options, OH_PictureNative *picture, int32_t fd); 354 355 #ifdef __cplusplus 356 }; 357 #endif 358 /* *@} */ 359 #endif // INTERFACES_KITS_NATIVE_INCLUDE_IMAGE_IMAGE_PACKER_NATIVE_H