1/* 2 * Copyright (c) 2024 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 ImageProcessing 18 * @{ 19 * 20 * @brief Provide APIs for image quality processing. 21 * 22 * @since 13 23 */ 24 25/** 26 * @file image_processing.h 27 * 28 * @brief Declare image processing functions. 29 * 30 * Provides SDR content processing for images, including color space conversion, metadata generation 31 * and image scaling. 32 * 33 * @library libimage_processing.so 34 * @syscap SystemCapability.Multimedia.VideoProcessingEngine 35 * @kit ImageKit 36 * @since 13 37 */ 38 39#ifndef VIDEO_PROCESSING_ENGINE_C_API_IMAGE_PROCESSING_H 40#define VIDEO_PROCESSING_ENGINE_C_API_IMAGE_PROCESSING_H 41 42#include <stdint.h> 43#include <stdbool.h> 44#include "image_processing_types.h" 45 46#ifdef __cplusplus 47extern "C" { 48#endif 49 50/** 51 * @brief Initialize global environment for image processing. 52 * 53 * This function is optional. \n 54 * Typically, this function is called once when the host process is started to initialize the global environment for 55 * image processing, which can reduce the time of {@link OH_ImageProcessing_Create}. \n 56 * To deinitialize global environment, call {@link OH_ImageProcessing_DeinitializeEnvironment}. 57 * 58 * @return {@link IMAGE_PROCESSING_SUCCESS} if initialization is successful. \n 59 * {@link IMAGE_PROCESSING_ERROR_INITIALIZE_FAILED} if initialization is failed. \n 60 * You can check if the device GPU is working properly. 61 * @since 13 62 */ 63ImageProcessing_ErrorCode OH_ImageProcessing_InitializeEnvironment(void); 64 65/** 66 * @brief Deinitialize global environment for image processing. 67 * 68 * This function is required if {@link OH_ImageProcessing_InitializeEnvironment} is called. Typically, this 69 * function is called when the host process is about to exit to deinitialize the global environment, which is 70 * initialized by calling {@link OH_ImageProcessing_InitializeEnvironment}. \n 71 * If there is some image processing instance existing, this function should not be called. \n 72 * If the {@link OH_ImageProcessing_InitializeEnvironment} is not called, this function should not be called. 73 * 74 * @return {@link IMAGE_PROCESSING_SUCCESS} if deinitialization is successful. \n 75 * {@link IMAGE_PROCESSING_ERROR_OPERATION_NOT_PERMITTED} if some image processing instance is not destroyed or 76 * {@link OH_ImageProcessing_InitializeEnvironment} is not called. \n 77 * @since 13 78 */ 79ImageProcessing_ErrorCode OH_ImageProcessing_DeinitializeEnvironment(void); 80 81/** 82 * @brief Query whether the image color space conversion is supported. 83 * 84 * @param sourceImageInfo Input image color space information pointer. 85 * @param destinationImageInfo Output image color space information pointer. 86 * @return <b>true</b> if the color space conversion is supported. \n 87 * <b>false</b> if the the color space conversion is unsupported. 88 * @since 13 89 */ 90bool OH_ImageProcessing_IsColorSpaceConversionSupported( 91 const ImageProcessing_ColorSpaceInfo* sourceImageInfo, 92 const ImageProcessing_ColorSpaceInfo* destinationImageInfo); 93 94/** 95 * @brief Query whether the image composition is supported. 96 * 97 * @param sourceImageInfo Input image color space information pointer. 98 * @param sourceGainmapInfo Input gainmap color space information pointer. 99 * @param destinationImageInfo Output image color space information pointer. 100 * @return <b>true</b> if the image composition is supported. \n 101 * <b>false</b> if the image composition is unsupported. 102 * @since 13 103 */ 104bool OH_ImageProcessing_IsCompositionSupported( 105 const ImageProcessing_ColorSpaceInfo* sourceImageInfo, 106 const ImageProcessing_ColorSpaceInfo* sourceGainmapInfo, 107 const ImageProcessing_ColorSpaceInfo* destinationImageInfo); 108 109/** 110 * @brief Query whether the image decomposition is supported. 111 * 112 * @param sourceImageInfo Input image color space information pointer. 113 * @param destinationImageInfo Output image color space information pointer. 114 * @param destinationGainmapInfo Output gainmap information pointer. 115 * @return <b>true</b> if the image decomposition is supported. \n 116 * <b>false</b> if the image decomposition is unsupported. 117 * @since 13 118 */ 119bool OH_ImageProcessing_IsDecompositionSupported( 120 const ImageProcessing_ColorSpaceInfo* sourceImageInfo, 121 const ImageProcessing_ColorSpaceInfo* destinationImageInfo, 122 const ImageProcessing_ColorSpaceInfo* destinationGainmapInfo); 123 124/** 125 * @brief Query whether the image metadata generation is supported. 126 * 127 * @param sourceImageInfo Input image color space information pointer. 128 * @return <b>true</b> if the image metadata generation is supported.. \n 129 * <b>false</b> if the image metadata generation is unsupported. 130 * @since 13 131 */ 132bool OH_ImageProcessing_IsMetadataGenerationSupported( 133 const ImageProcessing_ColorSpaceInfo* sourceImageInfo); 134 135/** 136 * @brief Create an image processing instance. 137 * 138 * @param imageProcessor Output parameter. The *imageProcessor points to a new image processing object. 139 * The *imageProcessor must be null before passed in. 140 * @param type Use IMAGE_PROCESSING_TYPE_XXX to specify the processing type. The processing type of the instance can not 141 * be changed. 142 * @return {@link IMAGE_PROCESSING_SUCCESS} if creating an image processing successfully. \n 143 * {@link IMAGE_PROCESSING_ERROR_UNSUPPORTED_PROCESSING} if the type is not supported. For example, if metadata 144 * generation is not supported by vendor, it returns unsupported processing. \n 145 * {@link IMAGE_PROCESSING_ERROR_CREATE_FAILED} if failed to create an image processing. \n 146 * {@link IMAGE_PROCESSING_ERROR_INVALID_INSTANCE} if instance is null or <b>*</b>instance is <b>not</b> null. \n 147 * {@link IMAGE_PROCESSING_ERROR_INVALID_PARAMETER} if type is invalid. \n 148 * @since 13 149 */ 150ImageProcessing_ErrorCode OH_ImageProcessing_Create(OH_ImageProcessing** imageProcessor, int32_t type); 151 152/** 153 * @brief Destroy the image processing instance. 154 * 155 * @param imageProcessor An image processing instance pointer. It is recommended setting the 156 * instance pointer to null after the instance is destroyed. 157 * @return {@link IMAGE_PROCESSING_SUCCESS} if the instance is destroyed successfully. \n 158 * {@link IMAGE_PROCESSING_ERROR_INVALID_INSTANCE} if instance is null or not an image processing instance. 159 * @since 13 160 */ 161ImageProcessing_ErrorCode OH_ImageProcessing_Destroy(OH_ImageProcessing* imageProcessor); 162 163/** 164 * @brief Set parameter for image processing. 165 * 166 * Add parameter identified by the specified parameter key. 167 * 168 * @param imageProcessor An image processing instance pointer. 169 * @param parameter The parameter for image processing. 170 * @return {@link IMAGE_PROCESSING_SUCCESS} if setting parameter is successful. \n 171 * {@link IMAGE_PROCESSING_ERROR_INVALID_INSTANCE} if instance is null or not an image processing instance. \n 172 * {@link IMAGE_PROCESSING_ERROR_INVALID_PARAMETER} if the parameter is null. \n 173 * {@link IMAGE_PROCESSING_ERROR_INVALID_VALUE} if some property of the parameter is invalid. For example, the parameter 174 * contains unsupported parameter key or value. \n 175 * {@link IMAGE_PROCESSING_ERROR_NO_MEMORY} if memory allocation failed. 176 * @since 13 177 */ 178ImageProcessing_ErrorCode OH_ImageProcessing_SetParameter(OH_ImageProcessing* imageProcessor, 179 const OH_AVFormat* parameter); 180 181/** 182 * @brief Get parameter of image processing. 183 * 184 * Get parameter identified by the specified parameter key. 185 * 186 * @param imageProcessor An image processing instance pointer. 187 * @param parameter The parameter used by the image processing instance. 188 * @return {@link IMAGE_PROCESSING_SUCCESS} if getting parameter is successful. \n 189 * {@link IMAGE_PROCESSING_ERROR_INVALID_INSTANCE} if instance is null or not an image processing instance. \n 190 * {@link IMAGE_PROCESSING_ERROR_INVALID_PARAMETER} if the parameter is null. \n 191 * @since 13 192 */ 193ImageProcessing_ErrorCode OH_ImageProcessing_GetParameter(OH_ImageProcessing* imageProcessor, 194 OH_AVFormat* parameter); 195 196/** 197 * @brief Conversion between single-layer images. 198 * 199 * The function generate the destinationImage from sourceImage. It include the colorspace conversion from 200 * HDR image to SDR image, SDR image to HDR image, SDR image to SDR image and HDR image to HDR image. 201 * 202 * @param imageProcessor An image processing instance pointer. The instance should be created with 203 * type {@link IMAGE_PROCESSING_TYPE_COLOR_SPACE_CONVERSION}. 204 * @param sourceImage Input image pointer. 205 * @param destinationImage Output image pointer. 206 * @return {@link IMAGE_PROCESSING_SUCCESS} if processing image is successful. \n 207 * {@link IMAGE_PROCESSING_ERROR_INVALID_INSTANCE} if instance is null or not an image processing instance. \n 208 * {@link IMAGE_PROCESSING_ERROR_INVALID_PARAMETER} if the image is null. \n 209 * {@link IMAGE_PROCESSING_ERROR_INVALID_VALUE} if some property of image is invalid. For example, the color space 210 * of the image is unsupported. \n 211 * {@link IMAGE_PROCESSING_ERROR_UNSUPPORTED_PROCESSING} if the processing is not supported. \n 212 * {@link IMAGE_PROCESSING_ERROR_PROCESS_FAILED} if processing error occurs. \n 213 * {@link IMAGE_PROCESSING_ERROR_NO_MEMORY} if memory allocation failed. 214 * @since 13 215 */ 216ImageProcessing_ErrorCode OH_ImageProcessing_ConvertColorSpace(OH_ImageProcessing* imageProcessor, 217 OH_PixelmapNative* sourceImage, OH_PixelmapNative* destinationImage); 218 219/** 220 * @brief Composition from dual-layer HDR images to single-layer HDR images. 221 * 222 * The function generate the destinationImage from sourceImage and sourceGainmap. 223 * 224 * @param imageProcessor An image processing instance pointer. The instance should be created with 225 * type {@link IMAGE_PROCESSING_TYPE_COMPOSITION}. 226 * @param sourceImage Input image pointer. 227 * @param sourceGainmap Input gainmap pointer. 228 * @param destinationImage Output image pointer. 229 * @return {@link IMAGE_PROCESSING_SUCCESS} if processing image is successful. \n 230 * {@link IMAGE_PROCESSING_ERROR_INVALID_INSTANCE} if instance is null or not an image processing instance. \n 231 * {@link IMAGE_PROCESSING_ERROR_INVALID_PARAMETER} if the image is null. \n 232 * {@link IMAGE_PROCESSING_ERROR_INVALID_VALUE} if some property of image is invalid. For example, the color space 233 * of the image is unsupported. \n 234 * {@link IMAGE_PROCESSING_ERROR_UNSUPPORTED_PROCESSING} if the processing is not supported. \n 235 * {@link IMAGE_PROCESSING_ERROR_PROCESS_FAILED} if processing error occurs. \n 236 * {@link IMAGE_PROCESSING_ERROR_NO_MEMORY} if memory allocation failed. 237 * @since 13 238 */ 239ImageProcessing_ErrorCode OH_ImageProcessing_Compose(OH_ImageProcessing* imageProcessor, 240 OH_PixelmapNative* sourceImage, OH_PixelmapNative* sourceGainmap, OH_PixelmapNative* destinationImage); 241 242/** 243 * @brief Decomposition from single-layer HDR images to dual-layer HDR images. 244 * 245 * The function generate the destinationImage and destinationGainmap from sourceImage. 246 * 247 * @param imageProcessor An image processing instance pointer. The instance should be created with 248 * type {@link IMAGE_PROCESSING_TYPE_DECOMPOSITION}. 249 * @param sourceImage Input image pointer. 250 * @param destinationImage Output image pointer. 251 * @param destinationGainmap Output gainmap pointer. 252 * @return {@link IMAGE_PROCESSING_SUCCESS} if processing image is successful. \n 253 * {@link IMAGE_PROCESSING_ERROR_INVALID_INSTANCE} if instance is null or not an image processing instance. \n 254 * {@link IMAGE_PROCESSING_ERROR_INVALID_PARAMETER} if the image is null. \n 255 * {@link IMAGE_PROCESSING_ERROR_INVALID_VALUE} if some property of image is invalid. For example, the color space 256 * of the image is unsupported. \n 257 * {@link IMAGE_PROCESSING_ERROR_UNSUPPORTED_PROCESSING} if the processing is not supported. \n 258 * {@link IMAGE_PROCESSING_ERROR_PROCESS_FAILED} if processing error occurs. \n 259 * {@link IMAGE_PROCESSING_ERROR_NO_MEMORY} if memory allocation failed. 260 * @since 13 261 */ 262ImageProcessing_ErrorCode OH_ImageProcessing_Decompose(OH_ImageProcessing* imageProcessor, 263 OH_PixelmapNative* sourceImage, OH_PixelmapNative* destinationImage, OH_PixelmapNative* destinationGainmap); 264 265/** 266 * @brief Metadata Generation for HDR images. 267 * 268 * The function generate metadata for the sourceImage. 269 * 270 * @param imageProcessor An image processing instance pointer. The instance should be created with 271 * type {@link IMAGE_PROCESSING_TYPE_METADATA_GENERATION}. 272 * @param sourceImage Input image pointer. 273 * @return {@link IMAGE_PROCESSING_SUCCESS} if processing image is successful. \n 274 * {@link IMAGE_PROCESSING_ERROR_INVALID_INSTANCE} if instance is null or not an image processing instance. \n 275 * {@link IMAGE_PROCESSING_ERROR_INVALID_PARAMETER} if the image is null. \n 276 * {@link IMAGE_PROCESSING_ERROR_INVALID_VALUE} if some property of image is invalid. For example, the color space 277 * of the image is unsupported. \n 278 * {@link IMAGE_PROCESSING_ERROR_UNSUPPORTED_PROCESSING} if the processing is not supported. \n 279 * {@link IMAGE_PROCESSING_ERROR_PROCESS_FAILED} if processing error occurs. \n 280 * {@link IMAGE_PROCESSING_ERROR_NO_MEMORY} if memory allocation failed. 281 * @since 13 282 */ 283ImageProcessing_ErrorCode OH_ImageProcessing_GenerateMetadata(OH_ImageProcessing* imageProcessor, 284 OH_PixelmapNative* sourceImage); 285 286/** 287 * @brief Clarity enhancement for images. 288 * 289 * The function generate the destinationImage from sourceImage with necessary scaling operation according to the size 290 * preset in the sourceImage and destinationImage. Different levels of scaling methonds are provided to balance 291 * performance and image quality. 292 * 293 * @param imageProcessor An image processing instance pointer. The instance should be created with 294 * type {@link IMAGE_PROCESSING_TYPE_DETAIL_ENHANCER}. 295 * @param sourceImage Input image pointer. 296 * @param destinationImage Output image pointer. 297 * @return {@link IMAGE_PROCESSING_SUCCESS} if processing image is successful. \n 298 * {@link IMAGE_PROCESSING_ERROR_INVALID_INSTANCE} if instance is null or not an image processing instance. \n 299 * {@link IMAGE_PROCESSING_ERROR_INVALID_PARAMETER} if the image is null. \n 300 * {@link IMAGE_PROCESSING_ERROR_INVALID_VALUE} if some property of image is invalid. For example, the color space 301 * of the image is unsupported. \n 302 * {@link IMAGE_PROCESSING_ERROR_UNSUPPORTED_PROCESSING} if the processing is not supported. \n 303 * {@link IMAGE_PROCESSING_ERROR_PROCESS_FAILED} if processing error occurs. \n 304 * {@link IMAGE_PROCESSING_ERROR_NO_MEMORY} if memory allocation failed. 305 * @since 13 306 */ 307ImageProcessing_ErrorCode OH_ImageProcessing_EnhanceDetail(OH_ImageProcessing* imageProcessor, 308 OH_PixelmapNative* sourceImage, OH_PixelmapNative* destinationImage); 309#ifdef __cplusplus 310} 311#endif 312 313#endif // VIDEO_PROCESSING_ENGINE_C_API_IMAGE_PROCESSING_H 314/** @} */ 315