xref: /interface/sdk_c/multimedia/video_processing_engine/image_processing.h

/*
 * Copyright (c) 2024 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * @addtogroup ImageProcessing
 * @{
 *
 * @brief Provide APIs for image quality processing.
 *
 * @since 13
 */

/**
 * @file image_processing.h
 *
 * @brief Declare image processing functions.
 *
 * Provides SDR content processing for images, including color space conversion, metadata generation
 * and image scaling.
 *
 * @library libimage_processing.so
 * @syscap SystemCapability.Multimedia.VideoProcessingEngine
 * @kit ImageKit
 * @since 13
 */

#ifndef VIDEO_PROCESSING_ENGINE_C_API_IMAGE_PROCESSING_H
#define VIDEO_PROCESSING_ENGINE_C_API_IMAGE_PROCESSING_H

#include <stdint.h>
#include <stdbool.h>
#include "image_processing_types.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief Initialize global environment for image processing.
 *
 * This function is optional. \n
 * Typically, this function is called once when the host process is started to initialize the global environment for
 * image processing, which can reduce the time of {@link OH_ImageProcessing_Create}. \n
 * To deinitialize global environment, call {@link OH_ImageProcessing_DeinitializeEnvironment}.
 *
 * @return {@link IMAGE_PROCESSING_SUCCESS} if initialization is successful. \n
 * {@link IMAGE_PROCESSING_ERROR_INITIALIZE_FAILED} if initialization is failed. \n
 * You can check if the device GPU is working properly.
 * @since 13
 */
ImageProcessing_ErrorCode OH_ImageProcessing_InitializeEnvironment(void);

/**
 * @brief Deinitialize global environment for image processing.
 *
 * This function is required if {@link OH_ImageProcessing_InitializeEnvironment} is called. Typically, this
 * function is called when the host process is about to exit to deinitialize the global environment, which is
 * initialized by calling {@link OH_ImageProcessing_InitializeEnvironment}. \n
 * If there is some image processing instance existing, this function should not be called. \n
 * If the {@link OH_ImageProcessing_InitializeEnvironment} is not called, this function should not be called.
 *
 * @return {@link IMAGE_PROCESSING_SUCCESS} if deinitialization is successful. \n
 * {@link IMAGE_PROCESSING_ERROR_OPERATION_NOT_PERMITTED} if some image processing instance is not destroyed or
 * {@link OH_ImageProcessing_InitializeEnvironment} is not called. \n
 * @since 13
 */
ImageProcessing_ErrorCode OH_ImageProcessing_DeinitializeEnvironment(void);

/**
 * @brief Query whether the image color space conversion is supported.
 *
 * @param sourceImageInfo Input image color space information pointer.
 * @param destinationImageInfo Output image color space information pointer.
 * @return <b>true</b> if the color space conversion is supported. \n
 * <b>false</b> if the the color space conversion is unsupported.
 * @since 13
 */
bool OH_ImageProcessing_IsColorSpaceConversionSupported(
    const ImageProcessing_ColorSpaceInfo* sourceImageInfo,
    const ImageProcessing_ColorSpaceInfo* destinationImageInfo);

/**
 * @brief Query whether the image composition is supported.
 *
 * @param sourceImageInfo Input image color space information pointer.
 * @param sourceGainmapInfo Input gainmap color space information pointer.
 * @param destinationImageInfo Output image color space information pointer.
 * @return <b>true</b> if the image composition is supported. \n
 * <b>false</b> if the image composition is unsupported.
 * @since 13
 */
bool OH_ImageProcessing_IsCompositionSupported(
    const ImageProcessing_ColorSpaceInfo* sourceImageInfo,
    const ImageProcessing_ColorSpaceInfo* sourceGainmapInfo,
    const ImageProcessing_ColorSpaceInfo* destinationImageInfo);

/**
 * @brief Query whether the image decomposition is supported.
 *
 * @param sourceImageInfo Input image color space information pointer.
 * @param destinationImageInfo Output image color space information pointer.
 * @param destinationGainmapInfo Output gainmap information pointer.
 * @return <b>true</b> if the image decomposition is supported. \n
 * <b>false</b> if the image decomposition is unsupported.
 * @since 13
 */
bool OH_ImageProcessing_IsDecompositionSupported(
    const ImageProcessing_ColorSpaceInfo* sourceImageInfo,
    const ImageProcessing_ColorSpaceInfo* destinationImageInfo,
    const ImageProcessing_ColorSpaceInfo* destinationGainmapInfo);

/**
 * @brief Query whether the image metadata generation is supported.
 *
 * @param sourceImageInfo Input image color space information pointer.
 * @return <b>true</b> if the image metadata generation is supported.. \n
 * <b>false</b> if the image metadata generation is unsupported.
 * @since 13
 */
bool OH_ImageProcessing_IsMetadataGenerationSupported(
    const ImageProcessing_ColorSpaceInfo* sourceImageInfo);

/**
 * @brief Create an image processing instance.
 *
 * @param imageProcessor Output parameter. The *imageProcessor points to a new image processing object.
 * The *imageProcessor must be null before passed in.
 * @param type Use IMAGE_PROCESSING_TYPE_XXX to specify the processing type. The processing type of the instance can not
 * be changed.
 * @return {@link IMAGE_PROCESSING_SUCCESS} if creating an image processing successfully. \n
 * {@link IMAGE_PROCESSING_ERROR_UNSUPPORTED_PROCESSING} if the type is not supported. For example, if metadata
 * generation is not supported by vendor, it returns unsupported processing. \n
 * {@link IMAGE_PROCESSING_ERROR_CREATE_FAILED} if failed to create an image processing. \n
 * {@link IMAGE_PROCESSING_ERROR_INVALID_INSTANCE} if instance is null or <b>*</b>instance is <b>not</b> null. \n
 * {@link IMAGE_PROCESSING_ERROR_INVALID_PARAMETER} if type is invalid. \n
 * @since 13
 */
ImageProcessing_ErrorCode OH_ImageProcessing_Create(OH_ImageProcessing** imageProcessor, int32_t type);

/**
 * @brief Destroy the image processing instance.
 *
 * @param imageProcessor An image processing instance pointer. It is recommended setting the
 * instance pointer to null after the instance is destroyed.
 * @return {@link IMAGE_PROCESSING_SUCCESS} if the instance is destroyed successfully. \n
 * {@link IMAGE_PROCESSING_ERROR_INVALID_INSTANCE} if instance is null or not an image processing instance.
 * @since 13
 */
ImageProcessing_ErrorCode OH_ImageProcessing_Destroy(OH_ImageProcessing* imageProcessor);

/**
 * @brief Set parameter for image processing.
 *
 * Add parameter identified by the specified parameter key.
 *
 * @param imageProcessor An image processing instance pointer.
 * @param parameter The parameter for image processing.
 * @return {@link IMAGE_PROCESSING_SUCCESS} if setting parameter is successful. \n
 * {@link IMAGE_PROCESSING_ERROR_INVALID_INSTANCE} if instance is null or not an image processing instance. \n
 * {@link IMAGE_PROCESSING_ERROR_INVALID_PARAMETER} if the parameter is null. \n
 * {@link IMAGE_PROCESSING_ERROR_INVALID_VALUE} if some property of the parameter is invalid. For example, the parameter
 * contains unsupported parameter key or value. \n
 * {@link IMAGE_PROCESSING_ERROR_NO_MEMORY} if memory allocation failed.
 * @since 13
 */
ImageProcessing_ErrorCode OH_ImageProcessing_SetParameter(OH_ImageProcessing* imageProcessor,
    const OH_AVFormat* parameter);

/**
 * @brief Get parameter of image processing.
 *
 * Get parameter identified by the specified parameter key.
 *
 * @param imageProcessor An image processing instance pointer.
 * @param parameter The parameter used by the image processing instance.
 * @return {@link IMAGE_PROCESSING_SUCCESS} if getting parameter is successful. \n
 * {@link IMAGE_PROCESSING_ERROR_INVALID_INSTANCE} if instance is null or not an image processing instance. \n
 * {@link IMAGE_PROCESSING_ERROR_INVALID_PARAMETER} if the parameter is null. \n
 * @since 13
 */
ImageProcessing_ErrorCode OH_ImageProcessing_GetParameter(OH_ImageProcessing* imageProcessor,
    OH_AVFormat* parameter);

/**
 * @brief Conversion between single-layer images.
 *
 * The function generate the destinationImage from sourceImage. It include the colorspace conversion from
 * HDR image to SDR image, SDR image to HDR image, SDR image to SDR image and HDR image to HDR image.
 *
 * @param imageProcessor An image processing instance pointer. The instance should be created with
 * type {@link IMAGE_PROCESSING_TYPE_COLOR_SPACE_CONVERSION}.
 * @param sourceImage Input image pointer.
 * @param destinationImage Output image pointer.
 * @return {@link IMAGE_PROCESSING_SUCCESS} if processing image is successful. \n
 * {@link IMAGE_PROCESSING_ERROR_INVALID_INSTANCE} if instance is null or not an image processing instance. \n
 * {@link IMAGE_PROCESSING_ERROR_INVALID_PARAMETER} if the image is null. \n
 * {@link IMAGE_PROCESSING_ERROR_INVALID_VALUE} if some property of image is invalid. For example, the color space
 * of the image is unsupported. \n
 * {@link IMAGE_PROCESSING_ERROR_UNSUPPORTED_PROCESSING} if the processing is not supported. \n
 * {@link IMAGE_PROCESSING_ERROR_PROCESS_FAILED} if processing error occurs. \n
 * {@link IMAGE_PROCESSING_ERROR_NO_MEMORY} if memory allocation failed.
 * @since 13
 */
ImageProcessing_ErrorCode OH_ImageProcessing_ConvertColorSpace(OH_ImageProcessing* imageProcessor,
    OH_PixelmapNative* sourceImage, OH_PixelmapNative* destinationImage);

/**
 * @brief Composition from dual-layer HDR images to single-layer HDR images.
 *
 * The function generate the destinationImage from sourceImage and sourceGainmap.
 *
 * @param imageProcessor An image processing instance pointer. The instance should be created with
 * type {@link IMAGE_PROCESSING_TYPE_COMPOSITION}.
 * @param sourceImage Input image pointer.
 * @param sourceGainmap Input gainmap pointer.
 * @param destinationImage Output image pointer.
 * @return {@link IMAGE_PROCESSING_SUCCESS} if processing image is successful. \n
 * {@link IMAGE_PROCESSING_ERROR_INVALID_INSTANCE} if instance is null or not an image processing instance. \n
 * {@link IMAGE_PROCESSING_ERROR_INVALID_PARAMETER} if the image is null. \n
 * {@link IMAGE_PROCESSING_ERROR_INVALID_VALUE} if some property of image is invalid. For example, the color space
 * of the image is unsupported. \n
 * {@link IMAGE_PROCESSING_ERROR_UNSUPPORTED_PROCESSING} if the processing is not supported. \n
 * {@link IMAGE_PROCESSING_ERROR_PROCESS_FAILED} if processing error occurs. \n
 * {@link IMAGE_PROCESSING_ERROR_NO_MEMORY} if memory allocation failed.
 * @since 13
 */
ImageProcessing_ErrorCode OH_ImageProcessing_Compose(OH_ImageProcessing* imageProcessor,
    OH_PixelmapNative* sourceImage, OH_PixelmapNative* sourceGainmap, OH_PixelmapNative* destinationImage);

/**
 * @brief Decomposition from single-layer HDR images to dual-layer HDR images.
 *
 * The function generate the destinationImage and destinationGainmap from sourceImage.
 *
 * @param imageProcessor An image processing instance pointer. The instance should be created with
 * type {@link IMAGE_PROCESSING_TYPE_DECOMPOSITION}.
 * @param sourceImage Input image pointer.
 * @param destinationImage Output image pointer.
 * @param destinationGainmap Output gainmap pointer.
 * @return {@link IMAGE_PROCESSING_SUCCESS} if processing image is successful. \n
 * {@link IMAGE_PROCESSING_ERROR_INVALID_INSTANCE} if instance is null or not an image processing instance. \n
 * {@link IMAGE_PROCESSING_ERROR_INVALID_PARAMETER} if the image is null. \n
 * {@link IMAGE_PROCESSING_ERROR_INVALID_VALUE} if some property of image is invalid. For example, the color space
 * of the image is unsupported. \n
 * {@link IMAGE_PROCESSING_ERROR_UNSUPPORTED_PROCESSING} if the processing is not supported. \n
 * {@link IMAGE_PROCESSING_ERROR_PROCESS_FAILED} if processing error occurs. \n
 * {@link IMAGE_PROCESSING_ERROR_NO_MEMORY} if memory allocation failed.
 * @since 13
 */
ImageProcessing_ErrorCode OH_ImageProcessing_Decompose(OH_ImageProcessing* imageProcessor,
    OH_PixelmapNative* sourceImage, OH_PixelmapNative* destinationImage, OH_PixelmapNative* destinationGainmap);

/**
 * @brief Metadata Generation for HDR images.
 *
 * The function generate metadata for the sourceImage.
 *
 * @param imageProcessor An image processing instance pointer. The instance should be created with
 * type {@link IMAGE_PROCESSING_TYPE_METADATA_GENERATION}.
 * @param sourceImage Input image pointer.
 * @return {@link IMAGE_PROCESSING_SUCCESS} if processing image is successful. \n
 * {@link IMAGE_PROCESSING_ERROR_INVALID_INSTANCE} if instance is null or not an image processing instance. \n
 * {@link IMAGE_PROCESSING_ERROR_INVALID_PARAMETER} if the image is null. \n
 * {@link IMAGE_PROCESSING_ERROR_INVALID_VALUE} if some property of image is invalid. For example, the color space
 * of the image is unsupported. \n
 * {@link IMAGE_PROCESSING_ERROR_UNSUPPORTED_PROCESSING} if the processing is not supported. \n
 * {@link IMAGE_PROCESSING_ERROR_PROCESS_FAILED} if processing error occurs. \n
 * {@link IMAGE_PROCESSING_ERROR_NO_MEMORY} if memory allocation failed.
 * @since 13
 */
ImageProcessing_ErrorCode OH_ImageProcessing_GenerateMetadata(OH_ImageProcessing* imageProcessor,
    OH_PixelmapNative* sourceImage);

/**
 * @brief Clarity enhancement for images.
 *
 * The function generate the destinationImage from sourceImage with necessary scaling operation according to the size
 * preset in the sourceImage and destinationImage. Different levels of scaling methonds are provided to balance
 * performance and image quality.
 *
 * @param imageProcessor An image processing instance pointer. The instance should be created with
 * type {@link IMAGE_PROCESSING_TYPE_DETAIL_ENHANCER}.
 * @param sourceImage Input image pointer.
 * @param destinationImage Output image pointer.
 * @return {@link IMAGE_PROCESSING_SUCCESS} if processing image is successful. \n
 * {@link IMAGE_PROCESSING_ERROR_INVALID_INSTANCE} if instance is null or not an image processing instance. \n
 * {@link IMAGE_PROCESSING_ERROR_INVALID_PARAMETER} if the image is null. \n
 * {@link IMAGE_PROCESSING_ERROR_INVALID_VALUE} if some property of image is invalid. For example, the color space
 * of the image is unsupported. \n
 * {@link IMAGE_PROCESSING_ERROR_UNSUPPORTED_PROCESSING} if the processing is not supported. \n
 * {@link IMAGE_PROCESSING_ERROR_PROCESS_FAILED} if processing error occurs. \n
 * {@link IMAGE_PROCESSING_ERROR_NO_MEMORY} if memory allocation failed.
 * @since 13
 */
ImageProcessing_ErrorCode OH_ImageProcessing_EnhanceDetail(OH_ImageProcessing* imageProcessor,
    OH_PixelmapNative* sourceImage, OH_PixelmapNative* destinationImage);
#ifdef __cplusplus
}
#endif

#endif // VIDEO_PROCESSING_ENGINE_C_API_IMAGE_PROCESSING_H
/** @} */