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