/*
* Copyright (c) 2019-2023, NVIDIA CORPORATION. All rights reserved.
*
* NVIDIA Corporation and its licensors retain all intellectual property
* and proprietary rights in and to this software, related documentation
* and any modifications thereto. Any use, reproduction, disclosure or
* distribution of this software and related documentation without an express
* license agreement from NVIDIA Corporation is strictly prohibited.
*
*/
/**
* @file nvbufsurftransform.h
* <b>NvBufSurfTransform Interface </b>
*
* This file specifies the NvBufSurfTransform image transformation APIs.
*
* The NvBufSurfTransform API provides methods to set and get session parameters
* and to transform and composite APIs.
*/
#ifndef NVBUFSURFTRANSFORM_H_
#define NVBUFSURFTRANSFORM_H_
#include "nvbufsurface.h"
#ifdef __cplusplus
extern "C" {
#endif
typedef struct CUstream_st* cudaStream_t; //!< Forward declaration of cudaStream_t.
/** @defgroup ds_bbb NvBufSurfTransform Types and Functions
* Defines types and functions of the \ref NvBufSurfTransform
* application programming interface.
* @ingroup ds_nvbuf_api
* @{ */
/**
* Specifies compute devices used by \ref NvBufSurfTransform.
*/
typedef enum
{
/** Specifies VIC as a compute device for Jetson or dGPU for an x86_64
system. */
NvBufSurfTransformCompute_Default,
/** Specifies that the GPU is the compute device. */
NvBufSurfTransformCompute_GPU,
/** Specifies that the VIC as a compute device. Supported only for Jetson. */
NvBufSurfTransformCompute_VIC
} NvBufSurfTransform_Compute;
/**
* Specifies video flip methods.
*/
typedef enum
{
/** Specifies no video flip. */
NvBufSurfTransform_None,
/** Specifies rotating 90 degrees clockwise. */
NvBufSurfTransform_Rotate90,
/** Specifies rotating 180 degree clockwise. */
NvBufSurfTransform_Rotate180,
/** Specifies rotating 270 degree clockwise. */
NvBufSurfTransform_Rotate270,
/** Specifies video flip with respect to the X-axis. */
NvBufSurfTransform_FlipX,
/** Specifies video flip with respect to the Y-axis. */
NvBufSurfTransform_FlipY,
/** Specifies video flip transpose. */
NvBufSurfTransform_Transpose,
/** Specifies video flip inverse transpose. */
NvBufSurfTransform_InvTranspose,
} NvBufSurfTransform_Flip;
/**
* Specifies video interpolation methods.
*/
typedef enum
{
/** Specifies Nearest Interpolation Method interpolation. */
NvBufSurfTransformInter_Nearest = 0,
/** Specifies Bilinear Interpolation Method interpolation. */
NvBufSurfTransformInter_Bilinear,
/** Specifies GPU-Cubic, VIC-5 Tap interpolation. */
NvBufSurfTransformInter_Algo1,
/** Specifies GPU-Super, VIC-10 Tap interpolation. */
NvBufSurfTransformInter_Algo2,
/** Specifies GPU-Lanzos, VIC-Smart interpolation. */
NvBufSurfTransformInter_Algo3,
/** Specifies GPU-Ignored, VIC-Nicest interpolation. */
NvBufSurfTransformInter_Algo4,
/** Specifies GPU-Nearest, VIC-Nearest interpolation. */
NvBufSurfTransformInter_Default
} NvBufSurfTransform_Inter;
/**
* Specifies error codes returned by \ref NvBufSurfTransform functions.
*/
typedef enum
{
/** Specifies an error in source or destination ROI. */
NvBufSurfTransformError_ROI_Error = -4,
/** Specifies invalid input parameters. */
NvBufSurfTransformError_Invalid_Params = -3,
/** Specifies a runtime execution error. */
NvBufSurfTransformError_Execution_Error = -2,
/** Specifies an unsupported feature or format. */
NvBufSurfTransformError_Unsupported = -1,
/** Specifies a successful operation. */
NvBufSurfTransformError_Success = 0
} NvBufSurfTransform_Error;
/**
* Specifies transform types.
*/
typedef enum {
/** Specifies a transform to crop the source rectangle. */
NVBUFSURF_TRANSFORM_CROP_SRC = 1,
/** Specifies a transform to crop the destination rectangle. */
NVBUFSURF_TRANSFORM_CROP_DST = 1 << 1,
/** Specifies a transform to set the filter type. */
NVBUFSURF_TRANSFORM_FILTER = 1 << 2,
/** Specifies a transform to set the flip method. */
NVBUFSURF_TRANSFORM_FLIP = 1 << 3,
/** Specifies a transform to normalize output. */
NVBUFSURF_TRANSFORM_NORMALIZE = 1 << 4,
/** Specifies a transform to allow odd crop. */
NVBUFSURF_TRANSFORM_ALLOW_ODD_CROP = 1 << 5
} NvBufSurfTransform_Transform_Flag;
/**
* Specifies types of composition operations.
*/
typedef enum {
/** Specifies a flag to describe the requested compositing operation. */
NVBUFSURF_TRANSFORM_COMPOSITE = 1,
/** Specifies a flag to describe the requested blending operation.
* This flag is applicable for NvBufSurfTransformMultiInputBufCompositeBlend
* and NvBufSurfTransformMultiInputBufCompositeBlendAsync API to support
* blending operation in upcoming releases.
*/
NVBUFSURF_TRANSFORM_BLEND = 1 << 1,
/** Specifies a composite to set the filter type. */
NVBUFSURF_TRANSFORM_COMPOSITE_FILTER = 1 << 2,
} NvBufSurfTransform_Composite_Flag;
/**
* Holds the coordinates of a rectangle.
*/
typedef struct
{
/** Holds the rectangle top. */
uint32_t top;
/** Holds the rectangle left side. */
uint32_t left;
/** Holds the rectangle width. */
uint32_t width;
/** Holds the rectangle height. */
uint32_t height;
}NvBufSurfTransformRect;
/**
* Holds configuration parameters for a transform/composite session.
*/
typedef struct _NvBufSurfTransformConfigParams
{
/** Holds the mode of operation: VIC (Jetson) or GPU (iGPU + dGPU)
If VIC is configured, \a gpu_id is ignored. */
NvBufSurfTransform_Compute compute_mode;
/** Holds the GPU ID to be used for processing. */
int32_t gpu_id;
/** User configure stream to be used. If NULL, the default stream is used.
Ignored if VIC is used. */
cudaStream_t cuda_stream;
} NvBufSurfTransformConfigParams;
/**
* Holds transform parameters for a transform call.
*/
typedef struct _NvBufSurfaceTransformParams
{
/** Holds a flag that indicates which transform parameters are valid. */
uint32_t transform_flag;
/** Holds the flip method. */
NvBufSurfTransform_Flip transform_flip;
/** Holds a transform filter. */
NvBufSurfTransform_Inter transform_filter;
/** Holds a pointer to a list of source rectangle coordinates for
a crop operation. */
NvBufSurfTransformRect *src_rect;
/** Holds a pointer to list of destination rectangle coordinates for
a crop operation. */
NvBufSurfTransformRect *dst_rect;
}NvBufSurfTransformParams;
/**
* Holds composite parameters for a composite call.
*/
typedef struct _NvBufSurfTransformCompositeParams
{
/** Holds a flag that indicates which composition parameters are valid. */
uint32_t composite_flag;
/** Holds the number of input buffers to be composited. */
uint32_t input_buf_count;
/** Holds source rectangle coordinates of input buffers for compositing. */
NvBufSurfTransformRect *src_comp_rect;
/** Holds destination rectangle coordinates of input buffers for
compositing. */
NvBufSurfTransformRect *dst_comp_rect;
/** Holds a composite filter. */
NvBufSurfTransform_Inter composite_filter;
}NvBufSurfTransformCompositeParams;
typedef struct _NvBufSurfTransform_ColorParams {
double red; /**< Holds the red component of color.
Value must be in the range 0.0-1.0. */
double green; /**< Holds the green component of color.
Value must be in the range 0.0-1.0.*/
double blue; /**< Holds the blue component of color.
Value must be in the range 0.0-1.0.*/
double alpha; /**< Holds the alpha component of color.
Value must be in the range 0.0-1.0.*/
} NvBufSurfTransform_ColorParams;
/**
* Holds composite blend parameters for a composite blender call.
*/
typedef struct _NvBufSurfTransformCompositeBlendParams
{
/** Holds a flag that indicates which composition parameters are valid. */
uint32_t composite_blend_flag;
/** Holds the number of input buffers to be composited. */
uint32_t input_buf_count;
/** Holds a blend/composite filter applicable only */
NvBufSurfTransform_Inter composite_blend_filter;
/** Holds background color list for blending if background buffer is absent, if NULL
* it wont be used, background buffer is expected to be NULL, if blending with
* static color is required
*/
NvBufSurfTransform_ColorParams *color_bg;
/** Holds a boolean flag list indicating whether blending to be done for particular buffer,
* if NULL, blending will be on all buffers, if valid value API expects at least numFilled
* size list and each element can take value 0 or 1
*/
uint32_t *perform_blending;
}NvBufSurfTransformCompositeBlendParams;
/**
* Holds extended composite blend parameters for NvBufSurfTransformMultiInputBufCompositeBlend
* and NvBufSurfTransformMultiInputBufCompositeBlendAsync API
*/
typedef struct _NvBufSurfTransformCompositeBlendParamsEx
{
/** Holds legacy composite blend parameters */
NvBufSurfTransformCompositeBlendParams params;
/** Holds source rectangle coordinates of input buffers for compositing. */
NvBufSurfTransformRect *src_comp_rect;
/** Holds destination rectangle coordinates of input buffers for compositing. */
NvBufSurfTransformRect *dst_comp_rect;
/** Holds composite filters to use for composition/blending. */
NvBufSurfTransform_Inter *composite_blend_filter;
/** Holds alpha values of input buffers for the blending. */
float *alpha;
/** reserved fields. */
void *reserved[STRUCTURE_PADDING];
}NvBufSurfTransformCompositeBlendParamsEx;
/**
** Holds the information about synchronization objects for asynchronous
* transform/composite APIs
*
*/
typedef struct NvBufSurfTransformSyncObj* NvBufSurfTransformSyncObj_t;
/**
* \brief Sets user-defined session parameters.
*
* If user-defined session parameters are set, they override the
* NvBufSurfTransform() function's default session.
*
* @param[in] config_params A pointer to a structure that is populated
* with the session parameters to be used.
*
* @return An \ref NvBufSurfTransform_Error value indicating
* success or failure.
*/
NvBufSurfTransform_Error NvBufSurfTransformSetSessionParams
(NvBufSurfTransformConfigParams *config_params);
/**
* \brief Gets the session parameters used by NvBufSurfTransform().
*
* @param[out] config_params A pointer to a caller-allocated structure to be
* populated with the session parameters used.
*
* @return An \ref NvBufSurfTransform_Error value indicating
* success or failure.
*/
NvBufSurfTransform_Error NvBufSurfTransformGetSessionParams
(NvBufSurfTransformConfigParams *config_params);
/**
* \brief Performs a transformation on batched input images.
*
* If user-defined session parameters are to be used, call
* NvBufSurfTransformSetSessionParams() before calling this function.
*
* @param[in] src A pointer to input batched buffers to be transformed.
* @param[out] dst A pointer to a caller-allocated location where
* transformed output is to be stored.
* @par When destination cropping is performed, memory outside
* the crop location is not touched, and may contain stale
* information. The caller must perform a memset before
* calling this function if stale information must be
* eliminated.
* @param[in] transform_params
* A pointer to an \ref NvBufSurfTransformParams structure
* which specifies the type of transform to be performed. They
* may include any combination of scaling, format conversion,
* and cropping for both source and destination.
* Flipping and rotation are supported on VIC.
* @return An \ref NvBufSurfTransform_Error value indicating
* success or failure.
*/
NvBufSurfTransform_Error NvBufSurfTransform (NvBufSurface *src, NvBufSurface *dst,
NvBufSurfTransformParams *transform_params);
/**
* \brief Composites batched input images.
*
* The compositer scales and stitches
* batched buffers indicated by \a src into a single destination buffer, \a dst.
*
* If user-defined session parameters are to be used, call
* NvBufSurfTransformSetSessionParams() before calling this function.
*
* @param[in] src A pointer to input batched buffers to be transformed.
* @param[out] dst A pointer a caller-allocated location (a single buffer)
* where composited output is to be stored.
* @param[in] composite_params
* A pointer to an \ref NvBufSurfTransformCompositeParams
* structure which specifies the compositing operation to be
* performed, e.g., the source and destination rectangles
* in \a src and \a dst.
* @return An \ref NvBufSurfTransform_Error value indicating success or failure.
*/
NvBufSurfTransform_Error NvBufSurfTransformComposite (NvBufSurface *src,
NvBufSurface *dst, NvBufSurfTransformCompositeParams *composite_params);
/**
* \brief An asynchronous (non-blocking) transformation on batched input images.
*
* If user-defined session parameters are to be used, call
* NvBufSurfTransformSetSessionParams() before calling this function.
*
* @param[in] src A pointer to input batched buffers to be transformed.
* @param[out] dst A pointer to a caller-allocated location where
* transformed output is to be stored.
* @par When destination cropping is performed, memory outside
* the crop location is not touched, and may contain stale
* information. The caller must perform a memset before
* calling this function if stale information must be
* eliminated.
* @param[in] transform_params
* A pointer to an \ref NvBufSurfTransformParams structure
* which specifies the type of transform to be performed. They
* may include any combination of scaling, format conversion,
* and cropping for both source and destination.
* Flipping and rotation are supported on VIC/GPU.
* @param[out] sync_objs
* A pointer to an \ref NvBufSurfTransformSyncObj structure
* which holds synchronization information of the current
* transform call. \ref NvBufSurfTransfromSyncObjWait() API to be
* called on this object to wait for transformation to complete.
* \ref NvBufSurfTransformSyncObjDestroy API should be called after
* \ref NvBufSurfTransformSyncObjWait API to release the objects
* If the parameter is NULL, the call would return only after
* the transform is complete.
* @return An \ref NvBufSurfTransform_Error value indicating
* success or failure.
*/
NvBufSurfTransform_Error NvBufSurfTransformAsync (NvBufSurface *src,
NvBufSurface *dst, NvBufSurfTransformParams *transform_params,
NvBufSurfTransformSyncObj_t *sync_obj);
/**
* \brief Composites batched input images Asynchronously (non-blocking).
*
* The compositer scales and stitches
* batched buffers indicated by \a src into a single destination buffer, \a dst.
*
* If user-defined session parameters are to be used, call
* NvBufSurfTransformSetSessionParams() before calling this function.
*
* @param[in] src A pointer to input batched buffers to be composited.
* @param[out] dst A pointer a caller-allocated location (a single buffer)
* where composited output is to be stored.
* @param[in] composite_params
* A pointer to an \ref NvBufSurfTransformCompositeParams
* structure which specifies the compositing operation to be
* performed, e.g., the source and destination rectangles
* in \a src and \a dst.
* @param[out] sync_objs
* A pointer to an \ref NvBufSurfTransformSyncObj structure
* which holds synchronization information of the current
* composite call. ref\ NvBufSurfTransfromSyncObjWait() API to be
* called on this object to wait for composition to complete.
* \ref NvBufSurfTransformSyncObjDestroy API should be called after
* \ref NvBufSurfTransformSyncObjWait API to release the objects
* If the parameter is NULL, the call would return only after
* the composite is complete.
* @return An \ref NvBufSurfTransform_Error value indicating success or failure.
*/
NvBufSurfTransform_Error NvBufSurfTransformCompositeAsync (NvBufSurface *src,
NvBufSurface *dst, NvBufSurfTransformCompositeParams *composite_params,
NvBufSurfTransformSyncObj_t *sync_obj);
/**
* \brief Composites/Blends batched input images
*
* The compositer scales and blends
* batched buffers indicated by \a src0 with \a src1 into a batched
* destination buffer \a dst using \a alpha as the blending weights.
* A Linear interpolation operation is performed to get the final pix value
* each of \a src0, \a src1, \a alpha and \a dst have one to one mapping
* For each pixel the following linear interpolation is performed.
* \a dst = ( \a src0* \a alpha + \a src1* (255.0 - \a alpha))/255.0
* If user-defined session parameters are to be used, call
* NvBufSurfTransformSetSessionParams() before calling this function.
*
* @param[in] src0 A pointer to input batched buffers to be blend.
* @param[in] src1 A pointer to input batched buffers to be blend with.
* @param[in] alpha A pointer to input batched buffers which has blending weights.
* @param[out] dst A pointer to output batched buffers where blended composite
* output is stored
* @param[in] blend_params
* A pointer to an \ref NvBufSurfTransformCompositeBlendParams
* structure which specifies the compositing operation to be
* performed
* @return An \ref NvBufSurfTransform_Error value indicating success or failure.
*/
NvBufSurfTransform_Error NvBufSurfTransformCompositeBlend(NvBufSurface *src0,
NvBufSurface *src1, NvBufSurface *alpha, NvBufSurface *dst,
NvBufSurfTransformCompositeBlendParams *blend_params);
/**
* Performs Composition and Blending on multiple input images(batch size=1) and provide
* single output image(batch size=1)
*
* Composites and blends batched(batch size=1) input buffers pointed by src pointer.
* Compositer scales, stitches and blends batched buffers pointed by src into single
* dst buffer (batch size=1), the parameters for composition and blending is provided
* by composite_blend_params.
* Use NvBufSurfTransformSetSessionParams before each call, if user defined
* session parameters are to be used.
* It is different than the NvBufSurfTransformCompositeBlend API and It is currently
* supported on Jetson only.
*
* @param[in] src pointer (multiple buffer) to input batched(batch size=1) buffers to be transformed.
* @param[out] dst pointer (single buffer) where composited output would be stored.
* @param[in] composite_blend_params pointer to NvBufSurfTransformCompositeBlendParamsEx structure.
*
* @return NvBufSurfTransform_Error indicating success or failure.
*/
NvBufSurfTransform_Error NvBufSurfTransformMultiInputBufCompositeBlend (NvBufSurface **src,
NvBufSurface *dst, NvBufSurfTransformCompositeBlendParamsEx *composite_blend_params);
/**
* Performs Composition and Blending on multiple input images(batch size=1) and provide
* single output image(batch size=1) Asynchronously (non-blocking).
*
* Composites and blends batched(batch size=1) input buffers pointed by src pointer.
* Compositer scales, stitches and blends batched buffers pointed by src into single
* dst buffer (batch size=1), the parameters for composition and blending is provided
* by composite_blend_params.
* Use NvBufSurfTransformSetSessionParams before each call, if user defined
* session parameters are to be used.
* It is different than the NvBufSurfTransformCompositeBlend API and It is currently
* supported on Jetson only.
*
* @param[in] src pointer (multiple buffer) to input batched(batch size=1) buffers to be transformed.
* @param[out] dst pointer (single buffer) where composited output would be stored.
* @param[in] composite_blend_params pointer to NvBufSurfTransformCompositeParams structure.
* @param[out] sync_objs
* A pointer to an \ref NvBufSurfTransformSyncObj structure
* which holds synchronization information of the current
* composite call. ref\ NvBufSurfTransfromSyncObjWait() API to be
* called on this object to wait for composition to complete.
* \ref NvBufSurfTransformSyncObjDestroy API should be called after
* \ref NvBufSurfTransformSyncObjWait API to release the objects
* If the parameter is NULL, the call would return only after
* the composite is complete.
*
* @return NvBufSurfTransform_Error indicating success or failure.
*/
NvBufSurfTransform_Error NvBufSurfTransformMultiInputBufCompositeBlendAsync (NvBufSurface **src,
NvBufSurface *dst, NvBufSurfTransformCompositeBlendParamsEx *composite_blend_params,
NvBufSurfTransformSyncObj_t *sync_obj);
/**
* \brief Wait on the synchroization object.
*
* The API waits on the synchronization object to finish the corresponding
* processing of transform/composite calls or returns on time_out
*
*
* @param[in] sync_obj A pointer to sync object on which the API should wait
* @param[in] time_out Maximum time in ms API should wait before returning, only
* Only applicable for VIC as of now.
* @return An \ref NvBufSurfTransform_Error value indicating success or failure.
*/
NvBufSurfTransform_Error NvBufSurfTransformSyncObjWait(
NvBufSurfTransformSyncObj_t sync_obj, uint32_t time_out);
/**
* \brief Destroy the synchroization object.
*
* The API deletes the sync_obj which was used for previous transform/composite
* Asynchronous calls
*
* @param[in] sync_obj A pointer sync_obj, which the API will delete
* @return An \ref NvBufSurfTransform_Error value indicating success or failure.
*
*/
NvBufSurfTransform_Error NvBufSurfTransformSyncObjDestroy(
NvBufSurfTransformSyncObj_t* sync_obj);
/**
* \brief Sets the default transform session as the current session for all upcoming transforms.
*
* @return An \ref NvBufSurfTransform_Error value indicating
* success or failure.
*/
NvBufSurfTransform_Error NvBufSurfTransformSetDefaultSession(void);
/** @} */
#ifdef __cplusplus
}
#endif
#endif