NVIDIA DeepStream SDK API Reference

6.4 Release
NvBufSurfTransform Types and Functions

Detailed Description

Defines types and functions of the NvBufSurfTransform application programming interface.

Data Structures

struct  NvBufSurfTransformRect
 Holds the coordinates of a rectangle. More...
 
struct  _NvBufSurfTransformConfigParams
 Holds configuration parameters for a transform/composite session. More...
 
struct  _NvBufSurfaceTransformParams
 Holds transform parameters for a transform call. More...
 
struct  _NvBufSurfTransformCompositeParams
 Holds composite parameters for a composite call. More...
 
struct  _NvBufSurfTransform_ColorParams
 
struct  _NvBufSurfTransformCompositeBlendParams
 Holds composite blend parameters for a composite blender call. More...
 
struct  _NvBufSurfTransformCompositeBlendParamsEx
 Holds extended composite blend parameters for NvBufSurfTransformMultiInputBufCompositeBlend and NvBufSurfTransformMultiInputBufCompositeBlendAsync API. More...
 

Typedefs

typedef struct _NvBufSurfTransformConfigParams NvBufSurfTransformConfigParams
 Holds configuration parameters for a transform/composite session. More...
 
typedef struct _NvBufSurfaceTransformParams NvBufSurfTransformParams
 Holds transform parameters for a transform call. More...
 
typedef struct _NvBufSurfTransformCompositeParams NvBufSurfTransformCompositeParams
 Holds composite parameters for a composite call. More...
 
typedef struct _NvBufSurfTransform_ColorParams NvBufSurfTransform_ColorParams
 
typedef struct _NvBufSurfTransformCompositeBlendParams NvBufSurfTransformCompositeBlendParams
 Holds composite blend parameters for a composite blender call. More...
 
typedef struct _NvBufSurfTransformCompositeBlendParamsEx NvBufSurfTransformCompositeBlendParamsEx
 Holds extended composite blend parameters for NvBufSurfTransformMultiInputBufCompositeBlend and NvBufSurfTransformMultiInputBufCompositeBlendAsync API. More...
 
typedef struct NvBufSurfTransformSyncObj * NvBufSurfTransformSyncObj_t
 Holds the information about synchronization objects for asynchronous transform/composite APIs. More...
 

Enumerations

enum  NvBufSurfTransform_Compute {
  NvBufSurfTransformCompute_Default,
  NvBufSurfTransformCompute_GPU,
  NvBufSurfTransformCompute_VIC
}
 Specifies compute devices used by NvBufSurfTransform. More...
 
enum  NvBufSurfTransform_Flip {
  NvBufSurfTransform_None,
  NvBufSurfTransform_Rotate90,
  NvBufSurfTransform_Rotate180,
  NvBufSurfTransform_Rotate270,
  NvBufSurfTransform_FlipX,
  NvBufSurfTransform_FlipY,
  NvBufSurfTransform_Transpose,
  NvBufSurfTransform_InvTranspose
}
 Specifies video flip methods. More...
 
enum  NvBufSurfTransform_Inter {
  NvBufSurfTransformInter_Nearest = 0,
  NvBufSurfTransformInter_Bilinear,
  NvBufSurfTransformInter_Algo1,
  NvBufSurfTransformInter_Algo2,
  NvBufSurfTransformInter_Algo3,
  NvBufSurfTransformInter_Algo4,
  NvBufSurfTransformInter_Default
}
 Specifies video interpolation methods. More...
 
enum  NvBufSurfTransform_Error {
  NvBufSurfTransformError_ROI_Error = -4,
  NvBufSurfTransformError_Invalid_Params = -3,
  NvBufSurfTransformError_Execution_Error = -2,
  NvBufSurfTransformError_Unsupported = -1,
  NvBufSurfTransformError_Success = 0
}
 Specifies error codes returned by NvBufSurfTransform functions. More...
 
enum  NvBufSurfTransform_Transform_Flag {
  NVBUFSURF_TRANSFORM_CROP_SRC = 1,
  NVBUFSURF_TRANSFORM_CROP_DST = 1 << 1,
  NVBUFSURF_TRANSFORM_FILTER = 1 << 2,
  NVBUFSURF_TRANSFORM_FLIP = 1 << 3,
  NVBUFSURF_TRANSFORM_NORMALIZE = 1 << 4,
  NVBUFSURF_TRANSFORM_ALLOW_ODD_CROP = 1 << 5
}
 Specifies transform types. More...
 
enum  NvBufSurfTransform_Composite_Flag {
  NVBUFSURF_TRANSFORM_COMPOSITE = 1,
  NVBUFSURF_TRANSFORM_BLEND = 1 << 1,
  NVBUFSURF_TRANSFORM_COMPOSITE_FILTER = 1 << 2
}
 Specifies types of composition operations. More...
 

Functions

NvBufSurfTransform_Error NvBufSurfTransformSetSessionParams (NvBufSurfTransformConfigParams *config_params)
 Sets user-defined session parameters. More...
 
NvBufSurfTransform_Error NvBufSurfTransformGetSessionParams (NvBufSurfTransformConfigParams *config_params)
 Gets the session parameters used by NvBufSurfTransform(). More...
 
NvBufSurfTransform_Error NvBufSurfTransform (NvBufSurface *src, NvBufSurface *dst, NvBufSurfTransformParams *transform_params)
 Performs a transformation on batched input images. More...
 
NvBufSurfTransform_Error NvBufSurfTransformComposite (NvBufSurface *src, NvBufSurface *dst, NvBufSurfTransformCompositeParams *composite_params)
 Composites batched input images. More...
 
NvBufSurfTransform_Error NvBufSurfTransformAsync (NvBufSurface *src, NvBufSurface *dst, NvBufSurfTransformParams *transform_params, NvBufSurfTransformSyncObj_t *sync_obj)
 An asynchronous (non-blocking) transformation on batched input images. More...
 
NvBufSurfTransform_Error NvBufSurfTransformCompositeAsync (NvBufSurface *src, NvBufSurface *dst, NvBufSurfTransformCompositeParams *composite_params, NvBufSurfTransformSyncObj_t *sync_obj)
 Composites batched input images Asynchronously (non-blocking). More...
 
NvBufSurfTransform_Error NvBufSurfTransformCompositeBlend (NvBufSurface *src0, NvBufSurface *src1, NvBufSurface *alpha, NvBufSurface *dst, NvBufSurfTransformCompositeBlendParams *blend_params)
 Composites/Blends batched input images. More...
 
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) More...
 
NvBufSurfTransform_Error NvBufSurfTransformMultiInputBufCompositeBlendAsync (NvBufSurface **src, NvBufSurface *dst, NvBufSurfTransformCompositeBlendParamsEx *composite_blend_params, NvBufSurfTransformSyncObj_t *sync_obj)
 Performs Composition and Blending on multiple input images(batch size=1) and provide single output image(batch size=1) Asynchronously (non-blocking). More...
 
NvBufSurfTransform_Error NvBufSurfTransformSyncObjWait (NvBufSurfTransformSyncObj_t sync_obj, uint32_t time_out)
 Wait on the synchronization object. More...
 
NvBufSurfTransform_Error NvBufSurfTransformSyncObjDestroy (NvBufSurfTransformSyncObj_t *sync_obj)
 Destroy the synchronization object. More...
 
NvBufSurfTransform_Error NvBufSurfTransformSetDefaultSession (void)
 Sets the default transform session as the current session for all upcoming transforms. More...
 

Typedef Documentation

◆ NvBufSurfTransform_ColorParams

◆ NvBufSurfTransformCompositeBlendParams

Holds composite blend parameters for a composite blender call.

◆ NvBufSurfTransformCompositeBlendParamsEx

Holds extended composite blend parameters for NvBufSurfTransformMultiInputBufCompositeBlend and NvBufSurfTransformMultiInputBufCompositeBlendAsync API.

◆ NvBufSurfTransformCompositeParams

Holds composite parameters for a composite call.

◆ NvBufSurfTransformConfigParams

Holds configuration parameters for a transform/composite session.

◆ NvBufSurfTransformParams

Holds transform parameters for a transform call.

◆ NvBufSurfTransformSyncObj_t

typedef struct NvBufSurfTransformSyncObj* NvBufSurfTransformSyncObj_t

Holds the information about synchronization objects for asynchronous transform/composite APIs.

Definition at line 282 of file nvbufsurftransform.h.

Enumeration Type Documentation

◆ NvBufSurfTransform_Composite_Flag

Specifies types of composition operations.

Enumerator
NVBUFSURF_TRANSFORM_COMPOSITE 

Specifies a flag to describe the requested compositing operation.

NVBUFSURF_TRANSFORM_BLEND 

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_COMPOSITE_FILTER 

Specifies a composite to set the filter type.

Definition at line 136 of file nvbufsurftransform.h.

◆ NvBufSurfTransform_Compute

Specifies compute devices used by NvBufSurfTransform.

Enumerator
NvBufSurfTransformCompute_Default 

Specifies VIC as a compute device for Jetson or dGPU for an x86_64 system.

NvBufSurfTransformCompute_GPU 

Specifies that the GPU is the compute device.

NvBufSurfTransformCompute_VIC 

Specifies that the VIC as a compute device.

Supported only for Jetson.

Definition at line 40 of file nvbufsurftransform.h.

◆ NvBufSurfTransform_Error

Specifies error codes returned by NvBufSurfTransform functions.

Enumerator
NvBufSurfTransformError_ROI_Error 

Specifies an error in source or destination ROI.

NvBufSurfTransformError_Invalid_Params 

Specifies invalid input parameters.

NvBufSurfTransformError_Execution_Error 

Specifies a runtime execution error.

NvBufSurfTransformError_Unsupported 

Specifies an unsupported feature or format.

NvBufSurfTransformError_Success 

Specifies a successful operation.

Definition at line 100 of file nvbufsurftransform.h.

◆ NvBufSurfTransform_Flip

Specifies video flip methods.

Enumerator
NvBufSurfTransform_None 

Specifies no video flip.

NvBufSurfTransform_Rotate90 

Specifies rotating 90 degrees clockwise.

NvBufSurfTransform_Rotate180 

Specifies rotating 180 degree clockwise.

NvBufSurfTransform_Rotate270 

Specifies rotating 270 degree clockwise.

NvBufSurfTransform_FlipX 

Specifies video flip with respect to the X-axis.

NvBufSurfTransform_FlipY 

Specifies video flip with respect to the Y-axis.

NvBufSurfTransform_Transpose 

Specifies video flip transpose.

NvBufSurfTransform_InvTranspose 

Specifies video flip inverse transpose.

Definition at line 55 of file nvbufsurftransform.h.

◆ NvBufSurfTransform_Inter

Specifies video interpolation methods.

Enumerator
NvBufSurfTransformInter_Nearest 

Specifies Nearest Interpolation Method interpolation.

NvBufSurfTransformInter_Bilinear 

Specifies Bilinear Interpolation Method interpolation.

NvBufSurfTransformInter_Algo1 

Specifies GPU-Cubic, VIC-5 Tap interpolation.

NvBufSurfTransformInter_Algo2 

Specifies GPU-Super, VIC-10 Tap interpolation.

NvBufSurfTransformInter_Algo3 

Specifies GPU-Lanzos, VIC-Smart interpolation.

NvBufSurfTransformInter_Algo4 

Specifies GPU-Ignored, VIC-Nicest interpolation.

NvBufSurfTransformInter_Default 

Specifies GPU-Nearest, VIC-Nearest interpolation.

Definition at line 79 of file nvbufsurftransform.h.

◆ NvBufSurfTransform_Transform_Flag

Specifies transform types.

Enumerator
NVBUFSURF_TRANSFORM_CROP_SRC 

Specifies a transform to crop the source rectangle.

NVBUFSURF_TRANSFORM_CROP_DST 

Specifies a transform to crop the destination rectangle.

NVBUFSURF_TRANSFORM_FILTER 

Specifies a transform to set the filter type.

NVBUFSURF_TRANSFORM_FLIP 

Specifies a transform to set the flip method.

NVBUFSURF_TRANSFORM_NORMALIZE 

Specifies a transform to normalize output.

NVBUFSURF_TRANSFORM_ALLOW_ODD_CROP 

Specifies a transform to allow odd crop.

Definition at line 117 of file nvbufsurftransform.h.

Function Documentation

◆ NvBufSurfTransform()

NvBufSurfTransform_Error NvBufSurfTransform ( NvBufSurface src,
NvBufSurface dst,
NvBufSurfTransformParams transform_params 
)

Performs a transformation on batched input images.

If user-defined session parameters are to be used, call NvBufSurfTransformSetSessionParams() before calling this function.

Parameters
[in]srcA pointer to input batched buffers to be transformed.
[out]dstA pointer to a caller-allocated location where transformed output is to be stored.
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.
Parameters
[in]transform_paramsA pointer to an 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.
Returns
An NvBufSurfTransform_Error value indicating success or failure.

◆ NvBufSurfTransformAsync()

NvBufSurfTransform_Error NvBufSurfTransformAsync ( NvBufSurface src,
NvBufSurface dst,
NvBufSurfTransformParams transform_params,
NvBufSurfTransformSyncObj_t sync_obj 
)

An asynchronous (non-blocking) transformation on batched input images.

If user-defined session parameters are to be used, call NvBufSurfTransformSetSessionParams() before calling this function.

Parameters
[in]srcA pointer to input batched buffers to be transformed.
[out]dstA pointer to a caller-allocated location where transformed output is to be stored.
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.
Parameters
[in]transform_paramsA pointer to an 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.
[out]sync_objA pointer to an NvBufSurfTransformSyncObj structure which holds synchronization information of the current transform call. NvBufSurfTransfromSyncObjWait() API to be called on this object to wait for transformation to complete. NvBufSurfTransformSyncObjDestroy API should be called after NvBufSurfTransformSyncObjWait API to release the objects If the parameter is NULL, the call would return only after the transform is complete.
Returns
An NvBufSurfTransform_Error value indicating success or failure.

◆ NvBufSurfTransformComposite()

NvBufSurfTransform_Error NvBufSurfTransformComposite ( NvBufSurface src,
NvBufSurface dst,
NvBufSurfTransformCompositeParams composite_params 
)

Composites batched input images.

The compositer scales and stitches batched buffers indicated by src into a single destination buffer, dst.

If user-defined session parameters are to be used, call NvBufSurfTransformSetSessionParams() before calling this function.

Parameters
[in]srcA pointer to input batched buffers to be transformed.
[out]dstA pointer a caller-allocated location (a single buffer) where composited output is to be stored.
[in]composite_paramsA pointer to an NvBufSurfTransformCompositeParams structure which specifies the compositing operation to be performed, e.g., the source and destination rectangles in src and dst.
Returns
An NvBufSurfTransform_Error value indicating success or failure.

◆ NvBufSurfTransformCompositeAsync()

NvBufSurfTransform_Error NvBufSurfTransformCompositeAsync ( NvBufSurface src,
NvBufSurface dst,
NvBufSurfTransformCompositeParams composite_params,
NvBufSurfTransformSyncObj_t sync_obj 
)

Composites batched input images Asynchronously (non-blocking).

The compositer scales and stitches batched buffers indicated by src into a single destination buffer, dst.

If user-defined session parameters are to be used, call NvBufSurfTransformSetSessionParams() before calling this function.

Parameters
[in]srcA pointer to input batched buffers to be composited.
[out]dstA pointer a caller-allocated location (a single buffer) where composited output is to be stored.
[in]composite_paramsA pointer to an NvBufSurfTransformCompositeParams structure which specifies the compositing operation to be performed, e.g., the source and destination rectangles in src and dst.
[out]sync_objA pointer to an 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. NvBufSurfTransformSyncObjDestroy API should be called after NvBufSurfTransformSyncObjWait API to release the objects If the parameter is NULL, the call would return only after the composite is complete.
Returns
An NvBufSurfTransform_Error value indicating success or failure.

◆ NvBufSurfTransformCompositeBlend()

NvBufSurfTransform_Error NvBufSurfTransformCompositeBlend ( NvBufSurface src0,
NvBufSurface src1,
NvBufSurface alpha,
NvBufSurface dst,
NvBufSurfTransformCompositeBlendParams blend_params 
)

Composites/Blends batched input images.

The compositer scales and blends batched buffers indicated by src0 with src1 into a batched destination buffer dst using alpha as the blending weights. A Linear interpolation operation is performed to get the final pix value each of src0, src1, alpha and dst have one to one mapping For each pixel the following linear interpolation is performed. dst = ( src0* alpha + src1* (255.0 - alpha))/255.0 If user-defined session parameters are to be used, call NvBufSurfTransformSetSessionParams() before calling this function.

Parameters
[in]src0A pointer to input batched buffers to be blend.
[in]src1A pointer to input batched buffers to be blend with.
[in]alphaA pointer to input batched buffers which has blending weights.
[out]dstA pointer to output batched buffers where blended composite output is stored
[in]blend_paramsA pointer to an NvBufSurfTransformCompositeBlendParams structure which specifies the compositing operation to be performed
Returns
An NvBufSurfTransform_Error value indicating success or failure.

◆ NvBufSurfTransformGetSessionParams()

NvBufSurfTransform_Error NvBufSurfTransformGetSessionParams ( NvBufSurfTransformConfigParams config_params)

Gets the session parameters used by NvBufSurfTransform().

Parameters
[out]config_paramsA pointer to a caller-allocated structure to be populated with the session parameters used.
Returns
An NvBufSurfTransform_Error value indicating success or failure.

◆ NvBufSurfTransformMultiInputBufCompositeBlend()

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)

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.

Parameters
[in]srcpointer (multiple buffer) to input batched(batch size=1) buffers to be transformed.
[out]dstpointer (single buffer) where composited output would be stored.
[in]composite_blend_paramspointer to NvBufSurfTransformCompositeBlendParamsEx structure.
Returns
NvBufSurfTransform_Error indicating success or failure.

◆ NvBufSurfTransformMultiInputBufCompositeBlendAsync()

NvBufSurfTransform_Error NvBufSurfTransformMultiInputBufCompositeBlendAsync ( NvBufSurface **  src,
NvBufSurface dst,
NvBufSurfTransformCompositeBlendParamsEx composite_blend_params,
NvBufSurfTransformSyncObj_t sync_obj 
)

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.

Parameters
[in]srcpointer (multiple buffer) to input batched(batch size=1) buffers to be transformed.
[out]dstpointer (single buffer) where composited output would be stored.
[in]composite_blend_paramspointer to NvBufSurfTransformCompositeParams structure.
[out]sync_objA pointer to an 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. NvBufSurfTransformSyncObjDestroy API should be called after NvBufSurfTransformSyncObjWait API to release the objects If the parameter is NULL, the call would return only after the composite is complete.
Returns
NvBufSurfTransform_Error indicating success or failure.

◆ NvBufSurfTransformSetDefaultSession()

NvBufSurfTransform_Error NvBufSurfTransformSetDefaultSession ( void  )

Sets the default transform session as the current session for all upcoming transforms.

Returns
An NvBufSurfTransform_Error value indicating success or failure.

◆ NvBufSurfTransformSetSessionParams()

NvBufSurfTransform_Error NvBufSurfTransformSetSessionParams ( NvBufSurfTransformConfigParams config_params)

Sets user-defined session parameters.

If user-defined session parameters are set, they override the NvBufSurfTransform() function's default session.

Parameters
[in]config_paramsA pointer to a structure that is populated with the session parameters to be used.
Returns
An NvBufSurfTransform_Error value indicating success or failure.

◆ NvBufSurfTransformSyncObjDestroy()

NvBufSurfTransform_Error NvBufSurfTransformSyncObjDestroy ( NvBufSurfTransformSyncObj_t sync_obj)

Destroy the synchronization object.

The API deletes the sync_obj which was used for previous transform/composite Asynchronous calls

Parameters
[in]sync_objA pointer sync_obj, which the API will delete
Returns
An NvBufSurfTransform_Error value indicating success or failure.

Referenced by nvdsinferserver::BaseBatchBuffer::waitForSyncObj().

◆ NvBufSurfTransformSyncObjWait()

NvBufSurfTransform_Error NvBufSurfTransformSyncObjWait ( NvBufSurfTransformSyncObj_t  sync_obj,
uint32_t  time_out 
)

Wait on the synchronization object.

The API waits on the synchronization object to finish the corresponding processing of transform/composite calls or returns on time_out

Parameters
[in]sync_objA pointer to sync object on which the API should wait
[in]time_outMaximum time in ms API should wait before returning, only Only applicable for VIC as of now.
Returns
An NvBufSurfTransform_Error value indicating success or failure.

Referenced by nvdsinferserver::BaseBatchBuffer::waitForSyncObj().