Detailed Description

The 2D Processing API encompasses all NvMedia 2D image processing related functionality.

6

Data Structures
struct	NvMedia2DAttributes
	Attributes structure for NvMedia2DCreate(). More...

struct	NvMedia2DComposeResult
	Stores information returned from NvMedia2DCompose(). More...

struct	NvMedia2DFilterCoefficients5Tap
	Coefficients values structure for 5-tap custom filter. More...

struct	NvMedia2DFilterCoefficients10Tap
	Coefficients values structure for 10-tap custom filter. More...

Macros
#define	NVMEDIA_2D_VERSION_MAJOR 8
	Major version number of NvMedia 2D header. More...

#define	NVMEDIA_2D_VERSION_MINOR 0
	Minor version number of NvMedia 2D header. More...

#define	NVMEDIA_2D_VERSION_PATCH 0
	Patch version number of NvMedia 2D header. More...

Typedefs
typedef uint32_t	NvMedia2DComposeParameters
	Stores configuration for the NvMedia2DCompose() operation. More...

typedef uint32_t	NvMedia2DFilterBuffer
	Stores a filter buffer which coefficients can be configured. More...

typedef struct NvMedia2D	NvMedia2D
	NvMedia2D Context. More...

Enumerations
enum	NvMedia2DFilter { NVMEDIA_2D_FILTER_OFF = 0x1, NVMEDIA_2D_FILTER_LOW, NVMEDIA_2D_FILTER_MEDIUM, NVMEDIA_2D_FILTER_HIGH }
	2D filter mode. More...

enum	NvMedia2DTransform { NVMEDIA_2D_TRANSFORM_NONE = 0x0, NVMEDIA_2D_TRANSFORM_ROTATE_90, NVMEDIA_2D_TRANSFORM_ROTATE_180, NVMEDIA_2D_TRANSFORM_ROTATE_270, NVMEDIA_2D_TRANSFORM_FLIP_HORIZONTAL, NVMEDIA_2D_TRANSFORM_INV_TRANSPOSE, NVMEDIA_2D_TRANSFORM_FLIP_VERTICAL, NVMEDIA_2D_TRANSFORM_TRANSPOSE }
	2D rotation/transform. More...

enum	NvMedia2DBlendMode { NVMEDIA_2D_BLEND_MODE_DISABLED, NVMEDIA_2D_BLEND_MODE_CONSTANT_ALPHA, NVMEDIA_2D_BLEND_MODE_STRAIGHT_ALPHA, NVMEDIA_2D_BLEND_MODE_PREMULTIPLIED_ALPHA }
	Blending to use when compositing surfaces. More...

Functions
NvMediaStatus	NvMedia2DGetVersion (NvMediaVersion *version)
	Returns the version number of the NvMedia 2D library. More...

NvMediaStatus	NvMedia2DCreate (NvMedia2D *handle, NvMedia2DAttributes const const attr)
	Creates a new NvMedia2D context. More...

NvMediaStatus	NvMedia2DDestroy (NvMedia2D *handle)
	Destroys the NvMedia2D context. More...

NvMediaStatus	NvMedia2DGetComposeParameters (NvMedia2D const handle, NvMedia2DComposeParameters params)
	Returns an NvMedia2DComposeParameters instance. More...

NvMediaStatus	NvMedia2DCompose (NvMedia2D const handle, NvMedia2DComposeParameters const params, NvMedia2DComposeResult const result)
	Performs a 2D compose operation. More...

NvMediaStatus	NvMedia2DSetSrcGeometry (NvMedia2D const handle, NvMedia2DComposeParameters const params, uint32_t const index, NvMediaRect const const srcRect, NvMediaRect const *const dstRect, NvMedia2DTransform const transform)
	Sets the geometry for a source layer. More...

NvMediaStatus	NvMedia2DSetSrcFilter (NvMedia2D *const handle, NvMedia2DComposeParameters const params, uint32_t const index, NvMedia2DFilter const filter)
	Sets the filter mode for a source layer. More...

NvMediaStatus	NvMedia2DSetSrcBlendMode (NvMedia2D *const handle, NvMedia2DComposeParameters const params, uint32_t const index, NvMedia2DBlendMode const blendMode, float const constantAlpha)
	Sets the blend mode for a source layer. More...

NvMediaStatus	NvMedia2DCreateFilterBuffer (NvMedia2D const handle, NvMedia2DFilterBuffer const filterBuffer)
	Creates and returns an NvMedia2DFilterBuffer instance. More...

NvMediaStatus	NvMedia2DDestroyFilterBuffer (NvMedia2D *const handle, NvMedia2DFilterBuffer const filterBuffer)
	Destroys an NvMedia2DFilterBuffer instance. More...

NvMediaStatus	NvMedia2DSetFilterBuffer (NvMedia2D *const handle, NvMedia2DComposeParameters const params, NvMedia2DFilterBuffer const filterBuffer)
	Sets the filter buffer for an NvMedia2DComposeParameters instance. More...

NvMediaStatus	NvMedia2DComputeFilterCoefficients5Tap (NvMedia2D const handle, NvMedia2DFilterBuffer const filterBuffer, uint32_t const index, NvMedia2DFilterCoefficients5Tap const const lumaX, NvMedia2DFilterCoefficients5Tap const const lumaY, NvMedia2DFilterCoefficients5Tap const const chromaX, NvMedia2DFilterCoefficients5Tap const *const chromaY)
	Computes the 5-tap filter coefficients for an NvMedia2DFilterBuffer. More...

NvMediaStatus	NvMedia2DComputeFilterCoefficients10Tap (NvMedia2D const handle, NvMedia2DFilterBuffer const filterBuffer, uint32_t const index, NvMedia2DFilterCoefficients10Tap const const lumaX, NvMedia2DFilterCoefficients10Tap const const lumaY, NvMedia2DFilterCoefficients10Tap const const chromaX, NvMedia2DFilterCoefficients10Tap const *const chromaY)
	Computes the 10-tap filter coefficients for an NvMedia2DFilterBuffer. More...

Macro Definition Documentation

◆ NVMEDIA_2D_VERSION_MAJOR

#define NVMEDIA_2D_VERSION_MAJOR 8

Major version number of NvMedia 2D header.

This defines the major version of the API defined in this header. This is intended to be used when validating the version number returned by the NvMedia2DGetVersion() function.

See also: NvMedia2DGetVersion()

Definition at line 47 of file nvmedia_2d.h.

◆ NVMEDIA_2D_VERSION_MINOR

#define NVMEDIA_2D_VERSION_MINOR 0

Minor version number of NvMedia 2D header.

This defines the minor version of the API defined in this header. This is intended to be used when validating the version number returned by the NvMedia2DGetVersion() function.

See also: NvMedia2DGetVersion()

Definition at line 57 of file nvmedia_2d.h.

◆ NVMEDIA_2D_VERSION_PATCH

#define NVMEDIA_2D_VERSION_PATCH 0

Patch version number of NvMedia 2D header.

This defines the patch version of the API defined in this header.

See also: NvMedia2DGetVersion()

Definition at line 65 of file nvmedia_2d.h.

Typedef Documentation

◆ NvMedia2D

typedef struct NvMedia2D NvMedia2D

NvMedia2D Context.

This type represents a context for the NvMedia2D library. This context is an opaque data type that encapsulates the state needed to service the NvMedia2D API calls.

See also: NvMedia2DCreate()

Definition at line 464 of file nvmedia_2d.h.

◆ NvMedia2DComposeParameters

typedef uint32_t NvMedia2DComposeParameters

Stores configuration for the NvMedia2DCompose() operation.

This object stores the information needed to configure the 2D operation that is executed inside the NvMedia2DCompose() function.

The underlying object cannot be instantiated directly by the client. Instead use the NvMedia2DGetComposeParameters() function to retrieve a handle to an available instance.

Value 0 is never a valid handle value, and can be used to initialize an NvMedia2DComposeParameters handle to a known value.

See also: NvMedia2DGetComposeParameters(); NvMedia2DInsertPreNvSciSyncFence(); NvMedia2DSetNvSciSyncObjforEOF(); NvMedia2DSetSrcGeometry(); NvMedia2DSetSrcFilter(); NvMedia2DSetSrcNvSciBufObj(); NvMedia2DSetDstNvSciBufObj(); NvMedia2DCompose()

Definition at line 322 of file nvmedia_2d.h.

◆ NvMedia2DFilterBuffer

typedef uint32_t NvMedia2DFilterBuffer

Stores a filter buffer which coefficients can be configured.

The underlying object cannot be instantiated directly by the client. Instead use the NvMedia2DCreateFilterBuffer() function to create and retrieve a handle to an available instance with resources allocated. Use NvMedia2DDestroyFilterBuffer() function to deallocate resources allocated by NvMedia2DCreateFilterBuffer() and release an instance.

Value 0 is never a valid handle value, and can be used to initialize an NvMedia2DFilterBuffer handle to a known value.

See also: NvMedia2DCreateFilterBuffer; NvMedia2DDestroyFilterBuffer

Definition at line 338 of file nvmedia_2d.h.

Enumeration Type Documentation

◆ NvMedia2DBlendMode

enum NvMedia2DBlendMode

Blending to use when compositing surfaces.

Enumerator
NVMEDIA_2D_BLEND_MODE_DISABLED	Disable blending. The color and alpha channels of the source surfaces are copied to the destination surface as is. The constant alpha factor is ignored. This is the default mode.
NVMEDIA_2D_BLEND_MODE_CONSTANT_ALPHA	Ignore the alpha channel values. Ignore the alpha channel values in the pixel data and only use the constant alpha factor that was passed when configuring blending. The color channels are blended with: `result = src * constantAlpha + dst * (1 - constantAlpha)`
NVMEDIA_2D_BLEND_MODE_STRAIGHT_ALPHA	Treat color and alpha channels independently. Use the product of the alpha channel values in the pixel data and the constant alpha factor to interpolate between color channel values of the blended surfaces. The color channels are blended with: `result = src * srcAlpha * constantAlpha + dst * (1 - srcAlpha * constantAlpha)`
NVMEDIA_2D_BLEND_MODE_PREMULTIPLIED_ALPHA	Treat color channels as having the alpha channel premultiplied. As NVMEDIA_2D_BLEND_MODE_STRAIGHT_ALPHA, but assume color channel values have been premultiplied by the alpha channel value. The color channels are blended with: `result = src * constantAlpha + dst * (1 - srcAlpha * constantAlpha)`

Definition at line 205 of file nvmedia_2d.h.

◆ NvMedia2DFilter

enum NvMedia2DFilter

2D filter mode.

This enum describes the filter modes that are supported by NvMedia 2D.

See also: NvMedia2DSetFilterBuffer()

Enumerator
NVMEDIA_2D_FILTER_OFF	Filtering is disabled. This mode results in nearest-neighbor filtering being used. This is the default mode.
NVMEDIA_2D_FILTER_LOW	Low quality filtering. This mode results in bilinear filtering being used.
NVMEDIA_2D_FILTER_MEDIUM	Medium quality filtering. This mode results in 5-tap filtering being used. By default, the filter used is a Lanczos filter. The coefficients can be overriden with NvMedia2DSetFilterBuffer().
NVMEDIA_2D_FILTER_HIGH	Highest quality filtering. This mode results in 10-tap filtering being used. By default, the filter used is a Lanczos filter. The coefficients can be overriden with NvMedia2DSetFilterBuffer().

Definition at line 73 of file nvmedia_2d.h.

◆ NvMedia2DTransform

enum NvMedia2DTransform

2D rotation/transform.

This enum describes the 2D transform to apply during a blit operation.

Transformations are used to rotate and mirror the source surface of a blit operation. The destination rectangle is not affected by any transformation settings.

NvMediaTransform identifies the transformations that can be applied as a combination of rotation and mirroring.

Specifically, given a hypothetical 2x2 image, applying these operations would yield the following results:

 INPUT                      OUTPUT
 
+---+---+                  +---+---+
| 0 | 1 |     IDENTITY     | 0 | 1 |
+---+---+ ---------------> +---+---+
| 2 | 3 |                  | 2 | 3 |
+---+---+                  +---+---+
 
+---+---+                  +---+---+
| 0 | 1 |    ROTATE_90     | 1 | 3 |
+---+---+ ---------------> +---+---+
| 2 | 3 |                  | 0 | 2 |
+---+---+                  +---+---+
 
+---+---+                  +---+---+
| 0 | 1 |    ROTATE_180    | 3 | 2 |
+---+---+ ---------------> +---+---+
| 2 | 3 |                  | 1 | 0 |
+---+---+                  +---+---+
 
+---+---+                  +---+---+
| 0 | 1 |    ROTATE_270    | 2 | 0 |
+---+---+ ---------------> +---+---+
| 2 | 3 |                  | 3 | 1 |
+---+---+                  +---+---+
 
+---+---+                  +---+---+
| 0 | 1 |  FLIP_HORIZONTAL | 1 | 0 |
+---+---+ ---------------> +---+---+
| 2 | 3 |                  | 3 | 2 |
+---+---+                  +---+---+
 
+---+---+                  +---+---+
| 0 | 1 |  INVTRANSPOSE    | 3 | 1 |
+---+---+ ---------------> +---+---+
| 2 | 3 |                  | 2 | 0 |
+---+---+                  +---+---+
 
+---+---+                  +---+---+
| 0 | 1 |  FLIP_VERTICAL   | 2 | 3 |
+---+---+ ---------------> +---+---+
| 2 | 3 |                  | 0 | 1 |
+---+---+                  +---+---+
 
+---+---+                  +---+---+
| 0 | 1 |    TRANSPOSE     | 0 | 2 |
+---+---+ ---------------> +---+---+
| 2 | 3 |                  | 1 | 3 |
+---+---+                  +---+---+

Enumerator
NVMEDIA_2D_TRANSFORM_NONE	No transform.
NVMEDIA_2D_TRANSFORM_ROTATE_90	Rotate 90 degrees anti-clockwise.
NVMEDIA_2D_TRANSFORM_ROTATE_180	Rotate 180 degrees.
NVMEDIA_2D_TRANSFORM_ROTATE_270	Rotate 270 degrees anti-clockwise.
NVMEDIA_2D_TRANSFORM_FLIP_HORIZONTAL	Flip horizontally (mirror along Y axis).
NVMEDIA_2D_TRANSFORM_INV_TRANSPOSE	Apply inverse transpose (mirror along diagonal axis from top-right to bottom-left).
NVMEDIA_2D_TRANSFORM_FLIP_VERTICAL	Flip vertically (mirror along X axis).
NVMEDIA_2D_TRANSFORM_TRANSPOSE	Apply transpose (mirror along diagonal axis from top-left to bottom-right).

Definition at line 173 of file nvmedia_2d.h.

Function Documentation

◆ NvMedia2DCompose()

NvMediaStatus NvMedia2DCompose	(	NvMedia2D *const	handle,
		NvMedia2DComposeParameters const	params,
		NvMedia2DComposeResult *const	result
	)

Performs a 2D compose operation.

A compose operation transfers pixels from a set of source surfaces to a destination surface, applying a variety of transformations to the pixel values on the way. The surfaces can have different pixel formats. NvMedia 2D does the necessary conversions between the formats.

Note: For a YUV surface type with 16-bit depth, only scale and crop are supported. Pixel format conversion, transformations or multi-surface composition is not supported.

If the dimensions of the source rectangle do not match the dimensions of the destination rectangle, the operation scales the pixels to fit the destination rectangle. The filtering mode for scale defaults to NVMEDIA_2D_FILTER_OFF. Additional filtering modes can be used by setting the corresponding parameter using NvMedia2DSetSrcFilter().

This example performs a straight pixel copy between surfaces of the same dimensions (but not necessarily the same bit depth or color format):

NvMedia2DComposeParameters params;
NvMedia2DGetComposeParameters(handle, &params);
NvMedia2DSetSrcNvSciBufObj(handle, params, 0, srcBuf);
NvMedia2DSetDstNvSciBufObj(handle, params, dstBuf);
NvMedia2DCompose(handle, params, NULL);

Restrictions on dimensions for input and output surfaces:

For 16-bit YUV/YUVX/Y formats:
- Width must be within the range: [16, 8192]
- Height must be within the range: [16, 8192]
For any other supported format:
- Width must be within the range: [16, 16384]
- Height must be within the range: [16, 16384]

Additional restrictions for chroma sub-sampled YUV formats:

444:
- Width: no restriction
- Height: no restriction
422:
- Width:
  - must be a multiple of 2
  - must be at least 32 for 16-bit YUV formats
- Height: no restriction
422R:
- Width: no restriction
- Height:
  - must be a multiple of 2
  - must be at least 32 for 16-bit YUV formats
420:
- Width:
  - must be a multiple of 2
  - must be at least 32 for 16-bit YUV formats
- Height:
  - must be a multiple of 2
  - must be at least 32 for 16-bit YUV formats

Restrictions on the source rectangle:

Must be within the bounds of the source surface.
Width and height must be greater than zero.

Restrictions on the destination rectangle:

Must be within the bounds of the destination surface.
Width and height must be greater than zero.
For 16-bit formats, top-left corner must be zero.
For any YUV format with chroma subsampling different than 444, all corners must be aligned to a a multiple of 2.

Restrictions on concurrency:

There can be a maximum of 16 operations submitted through the same NvMedia2D handle pending simultaneously.

If any of the restrictions are violated, this function will fail with an error code.

Performance considerations:

Using block linear memory layout for surfaces generally provides better performance than pitch linear layout.
Using (semi-)planar YUV formats generally provides better performance than interleaved (Y8U8Y8V8 etc.) formats.
The hardware accelerator utilized by NvMedia 2D accesses the destination surface in 64x16 (width x height) pixel tiles. Using destination surface size and destination rectangle dimensions that are exact multiples of the tile size most optimally aligns with this hardware access pattern.

Parameters

[in]	handle	Pointer to the NvMedia2D context.
[in]	params	An NvMedia2DComposeParameters handle.
[out]	result	Pointer to NvMedia2DComposeResult struct that will be populated with result info. May be NULL.

Returns: An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	Operation submitted successfully.
NVMEDIA_STATUS_BAD_PARAMETER	One of the parameters has an invalid value. This could be: handle is NULL params is invalid some of the compose parameters configured through params have invalid values (see restrictions on parameters).
NVMEDIA_STATUS_NOT_SUPPORTED	Requested operation is not supported by current platform (see restrictions on parameters).
NVMEDIA_STATUS_TIMED_OUT	No space available in the command buffer for this operation, because previous operations are still pending (see restrictions on concurrency). The caller should wait for the least recently submitted operation to complete and then try again.
NVMEDIA_STATUS_ERROR	An internal failure occurred when trying to perform the compose operation. This error indicates the system is potentially in an unrecoverable state.

Precondition

handle must be valid NvMedia2D handle created with NvMedia2DCreate().
params must be valid NvMedia2DComposeParameters handle created with NvMedia2DGetComposeParameters().

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes, with the following conditions:
  - Each thread uses different NvMedia2D handle
- Re-entrant: No
- Async/Sync: Async
Required privileges: None
API group
- Init: No
- Runtime: Yes
- De-Init: No

See also: NvMedia2DComposeParameters; NvMedia2DGetComposeParameters(); NvMedia2DInsertPreNvSciSyncFence(); NvMedia2DSetNvSciSyncObjforEOF(); NvMedia2DSetSrcGeometry(); NvMedia2DSetSrcFilter(); NvMedia2DSetSrcBlendMode(); NvMedia2DSetSrcNvSciBufObj(); NvMedia2DSetDstNvSciBufObj(); NvMedia2DGetEOFNvSciSyncFence()

◆ NvMedia2DComputeFilterCoefficients10Tap()

NvMediaStatus NvMedia2DComputeFilterCoefficients10Tap	(	NvMedia2D *const	handle,
		NvMedia2DFilterBuffer const	filterBuffer,
		uint32_t const	index,
		NvMedia2DFilterCoefficients10Tap const *const	lumaX,
		NvMedia2DFilterCoefficients10Tap const *const	lumaY,
		NvMedia2DFilterCoefficients10Tap const *const	chromaX,
		NvMedia2DFilterCoefficients10Tap const *const	chromaY
	)

Computes the 10-tap filter coefficients for an NvMedia2DFilterBuffer.

This function computes the filter coefficients values for a specific source layer based on the contents of four NvMedia2DFilterCoefficients10Tap structures.

There is no restriction on multiple parameters pointing to the same NvMedia2DFilterCoefficients10Tap structure

Parameters

[in]	handle	Pointer to the NvMedia2D context.
[in]	filterBuffer	An NvMedia2DFilterBuffer handle.
[in]	index	Index of source layer to configure. Must be in range [0, 4].
[in]	lumaX,lumaY	Pointers to NvMedia2DFilterCoefficients10Tap. These configure to the luma component for YUV formats, or all the components for RGB formats. There is one pointer for the horizontal direction, and one pointer for the vertical direction.
[in]	chromaX,chromaY	Pointers to NvMedia2DFilterCoefficients10Tap. These configure the chroma component for YUV formats. There is one pointer for the horizontal direction, and one pointer for the vertical direction.

Returns: An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	Filter buffer was updated successfully.
NVMEDIA_STATUS_BAD_PARAMETER	One of the parameters has an invalid value, either: handle is NULL. filterBuffer is invalid. index is out of range. lumaX is NULL. lumaY is NULL. chromaX is NULL. chromaY is NULL.

Precondition

handle must be valid NvMedia2D handle created with NvMedia2DCreate().
filterBuffer must be valid NvMedia2DFilterBuffer handle created with NvMedia2DCreateFilterBuffer().

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes, with the following conditions:
  - Each thread uses different NvMedia2D handle
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: Yes
- Runtime: Yes
- De-Init: No

See also: NvMedia2DFilterBuffer; NvMedia2DFilterCoefficients10Tap; NvMedia2DCreateFilterBuffer()

◆ NvMedia2DComputeFilterCoefficients5Tap()

NvMediaStatus NvMedia2DComputeFilterCoefficients5Tap	(	NvMedia2D *const	handle,
		NvMedia2DFilterBuffer const	filterBuffer,
		uint32_t const	index,
		NvMedia2DFilterCoefficients5Tap const *const	lumaX,
		NvMedia2DFilterCoefficients5Tap const *const	lumaY,
		NvMedia2DFilterCoefficients5Tap const *const	chromaX,
		NvMedia2DFilterCoefficients5Tap const *const	chromaY
	)

Computes the 5-tap filter coefficients for an NvMedia2DFilterBuffer.

This function computes the filter coefficients values for a specific source layer based on the contents of four NvMedia2DFilterCoefficients5Tap structures.

There is no restriction on multiple parameters pointing to the same NvMedia2DFilterCoefficients5Tap structure

Parameters

[in]	handle	Pointer to the NvMedia2D context.
[in]	filterBuffer	An NvMedia2DFilterBuffer handle.
[in]	index	Index of source layer to configure. Must be in range [0, 4].
[in]	lumaX,lumaY	Pointers to NvMedia2DFilterCoefficients5Tap. These configure to the luma component for YUV formats, or all the components for RGB formats. There is one pointer for the horizontal direction, and one pointer for the vertical direction.
[in]	chromaX,chromaY	Pointers to NvMedia2DFilterCoefficients5Tap. These configure the chroma component for YUV formats. There is one pointer for the horizontal direction, and one pointer for the vertical direction.

Returns: An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	Filter buffer was updated successfully.
NVMEDIA_STATUS_BAD_PARAMETER	One of the parameters has an invalid value, either: handle is NULL. filterBuffer is invalid. index is out of range. lumaX is NULL. lumaY is NULL. chromaX is NULL. chromaY is NULL.

Precondition

handle must be valid NvMedia2D handle created with NvMedia2DCreate().
filterBuffer must be valid NvMedia2DFilterBuffer handle created with NvMedia2DCreateFilterBuffer().

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes, with the following conditions:
  - Each thread uses different NvMedia2D handle
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: Yes
- Runtime: Yes
- De-Init: No

See also: NvMedia2DFilterBuffer; NvMedia2DFilterCoefficients5Tap; NvMedia2DCreateFilterBuffer()

◆ NvMedia2DCreate()

NvMediaStatus NvMedia2DCreate	(	NvMedia2D **	handle,
		NvMedia2DAttributes const *const	attr
	)

Creates a new NvMedia2D context.

This function creates a new instance of an NvMedia2D context, and returns a pointer to that context. Ownership of this context is passed to the caller. When no longer in use, the caller must destroy the context using the NvMedia2DDestroy() function.

Default attributes (when not specified by caller):

numComposeParameters: 1
maxRegisteredBuffers: 64
maxRegisteredSyncs: 16
maxFilterBuffers: 0
flags: 0.

Parameters

[out]	handle	Pointer to receive the handle to the new NvMedia2D context.
[in]	attr	Pointer to NvMedia2DAttributes struct, or NULL for default attributes.

Returns: An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	Context created successfully.
NVMEDIA_STATUS_BAD_PARAMETER	handle is NULL, or attr has bad attribute values.
NVMEDIA_STATUS_INVALID_STATE	The function was called in incorrect system state.
NVMEDIA_STATUS_NOT_SUPPORTED	NvMedia 2D is not supported on this hardware platform.
NVMEDIA_STATUS_OUT_OF_MEMORY	Memory allocation failed for internal data structures or device memory buffers.
NVMEDIA_STATUS_ERROR	An internal failure occurred when trying to create the context.

Precondition: None.

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes, with the following conditions:
  - Each thread uses different NvMedia2D handle
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: Yes
- Runtime: No
- De-Init: No

See also: NvMedia2D; NvMedia2DDestroy()

◆ NvMedia2DCreateFilterBuffer()

NvMediaStatus NvMedia2DCreateFilterBuffer	(	NvMedia2D *const	handle,
		NvMedia2DFilterBuffer *const	filterBuffer
	)

Creates and returns an NvMedia2DFilterBuffer instance.

This functions returns a handle to an NvMedia2DFilterBuffer object. The filter buffer can be used to provide custom 5-tap and 10-tap filter coefficients for a compose operation.

The buffer instance must be destroyed with NvMedia2DDestroyFilterBuffer() during the De-Init stage.

Parameters

[in]	handle	Pointer to the NvMedia2D context.
[out]	filterBuffer	Pointer to an NvMedia2DFilterBuffer, which will be populated with the handle.

Returns: An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	Buffer created successfully.
NVMEDIA_STATUS_BAD_PARAMETER	One of the parameters has an invalid value, either: handle is NULL filterBuffer is NULL.
NVMEDIA_STATUS_INSUFFICIENT_BUFFERING	Maximum number of buffers has been created.
NVMEDIA_STATUS_INVALID_STATE	The function was called in incorrect system state.
NVMEDIA_STATUS_OUT_OF_MEMORY	Failed to allocate memory for the buffer.
NVMEDIA_STATUS_ERROR	An internal failure occurred when trying to create the buffer.

Precondition

handle must be valid NvMedia2D handle created with NvMedia2DCreate().

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes, with the following conditions:
  - Each thread uses different NvMedia2D handle
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: Yes
- Runtime: No
- De-Init: No

See also: NvMedia2DAttributes; NvMedia2DFilterBuffer; NvMedia2DDestroyFilterBuffer()

◆ NvMedia2DDestroy()

NvMediaStatus NvMedia2DDestroy ( NvMedia2D * handle )

Destroys the NvMedia2D context.

This function destroys the specified NvMedia2D context.

Before calling this function, the caller must ensure:

There are no NvSciSync or NvSyncBuf objects still registered against the NvMedia2D context.

All previous 2D operations submitted using NvMedia2DCompose() have

Parameters

[in] handle Pointer to the NvMedia2D context.

Returns: An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	Context destroyed successfully.
NVMEDIA_STATUS_BAD_PARAMETER	handle is NULL.
NVMEDIA_STATUS_INVALID_STATE	The function was called in incorrect system state.
NVMEDIA_STATUS_PENDING	There are still some NvSciSync or NvSciBuf objects registered against the NvMedia2D context.
NVMEDIA_STATUS_ERROR	An internal failure occurred when trying to destroy the context. The context is in state where the only valid operation is to attempt to destroy it again.

Precondition

handle must be valid NvMedia2D handle created with NvMedia2DCreate().

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes, with the following conditions:
  - Each thread uses different NvMedia2D handle
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: Yes
- Runtime: No
- De-Init: Yes

See also: NvMedia2D; NvMedia2DCreate()

◆ NvMedia2DDestroyFilterBuffer()

NvMediaStatus NvMedia2DDestroyFilterBuffer	(	NvMedia2D *const	handle,
		NvMedia2DFilterBuffer const	filterBuffer
	)

Destroys an NvMedia2DFilterBuffer instance.

This functions destroys an NvMedia2DFilterBuffer object.

Parameters

[in]	handle	Pointer to the NvMedia2D context.
[in]	filterBuffer	An NvMedia2DFilterBuffer handle.

Returns: An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	Buffer are destroyed successfully.
NVMEDIA_STATUS_BAD_PARAMETER	One of the parameters has an invalid value, either: handle is NULL. filterBuffer is invalid.
NVMEDIA_STATUS_INVALID_STATE	The function was called in incorrect system state.
NVMEDIA_STATUS_PENDING	The buffer is still being used by a pending operation.
NVMEDIA_STATUS_ERROR	An internal failure occurred when trying to destroy the buffer. The buffer is in state where the only valid operation is to attempt to destroy it again.

Precondition

handle must be valid NvMedia2D handle created with NvMedia2DCreate().
filterBuffer must be valid NvMedia2DFilterBuffer handle created with NvMedia2DCreateFilterBuffer().

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes, with the following conditions:
  - Each thread uses different NvMedia2D handle
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: Yes
- Runtime: No
- De-Init: Yes

See also: NvMedia2DFilterBuffer; NvMedia2DCreateFilterBuffer()

◆ NvMedia2DGetComposeParameters()

NvMediaStatus NvMedia2DGetComposeParameters	(	NvMedia2D *const	handle,
		NvMedia2DComposeParameters *	params
	)

Returns an NvMedia2DComposeParameters instance.

This functions returns a handle to an NvMedia2DComposeParameters object. The object will be initialised and ready to use. The caller takes ownership of this handle. Ownership will be passed back to the NvMedia2D context when it is subsequently used in the NvMedia2DCompose() operation.

The object will be initialised with these default values:

source rectangle: set to the dimensions of the source surface
destination rectangle: set to the dimensions of the destination surface
filter: NVMEDIA_2D_FILTER_OFF
transform: NVMEDIA_2D_TRANSFORM_NONE.

Parameters

[in]	handle	Pointer to the NvMedia2D context.
[out]	params	Pointer to an NvMedia2DComposeParameters, which will be populated with the handle.

Returns: An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	Parameters instance is initialized successfully.
NVMEDIA_STATUS_BAD_PARAMETER	One of the parameters has an invalid value, either: handle is NULL params is NULL.
NVMEDIA_STATUS_INSUFFICIENT_BUFFERING	There is no free instance available.

Precondition

handle must be valid NvMedia2D handle created with NvMedia2DCreate().

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes, with the following conditions:
  - Each thread uses different NvMedia2D handle
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: No
- Runtime: Yes
- De-Init: No

See also: NvMedia2DComposeParameters; NvMedia2DCompose()

◆ NvMedia2DGetVersion()

NvMediaStatus NvMedia2DGetVersion ( NvMediaVersion * version )

Returns the version number of the NvMedia 2D library.

This function returns the major and minor version number of the NvMedia 2D library. The client must pass an NvMediaVersion struct to this function, and the version information will be returned in this struct.

This allows the client to verify that the version of the library matches and is compatible with the the version number of the header file they are using.

Parameters

[out] version Pointer to an NvMediaVersion struct that will be populated with the version information.

Returns: An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	Version information returned successfully.
NVMEDIA_STATUS_BAD_PARAMETER	version is NULL.

Precondition: None.

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes, with the following conditions:
  - Each thread uses different NvMediaVersion object
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: Yes
- Runtime: Yes
- De-Init: Yes

See also: NVMEDIA_2D_VERSION_MAJOR; NVMEDIA_2D_VERSION_MINOR; NVMEDIA_2D_VERSION_PATCH; NvMediaVersion

◆ NvMedia2DSetFilterBuffer()

NvMediaStatus NvMedia2DSetFilterBuffer	(	NvMedia2D *const	handle,
		NvMedia2DComposeParameters const	params,
		NvMedia2DFilterBuffer const	filterBuffer
	)

Sets the filter buffer for an NvMedia2DComposeParameters instance.

This function updates the NvMedia2DComposeParameters instance to indicate that the specified filter buffer object shall be used to provide the custom filter coefficients for the compose operation.

After this function returns successfully, there are a few additional limitations on the compose operation:

Only the first 5 source layers can be used (indexes 0 to 4).
If a source layer's NvMedia2DFilter is set to NVMEDIA_2D_FILTER_MEDIUM or NVMEDIA_2D_FILTER_HIGH, the custom 5-tap or 10-tap coefficients, respectively, for such layer shall have been properly set in the NvMedia2DFilterBuffer.

Due to the filter buffer object being read-only from the compose operation perspective, there is no limitation for the same filter buffer object to be set for multiple NvMedia2DComposeParameters instances.

Parameters

[in]	handle	Pointer to the NvMedia2D context.
[in]	params	An NvMedia2DComposeParameters handle.
[in]	filterBuffer	An NvMedia2DFilterBuffer handle.

Returns: An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	Filter buffer was set successfully.
NVMEDIA_STATUS_BAD_PARAMETER	One of the parameters has an invalid value, either: handle is NULL. params is invalid. filterBuffer is invalid.

Precondition

handle must be valid NvMedia2D handle created with NvMedia2DCreate().
params must be valid NvMedia2DComposeParameters handle created with NvMedia2DGetComposeParameters().
filterBuffer must be valid NvMedia2DFilterBuffer handle created with NvMedia2DCreateFilterBuffer().

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes, with the following conditions:
  - Each thread uses different NvMedia2D handle
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: No
- Runtime: Yes
- De-Init: No

See also: NvMedia2DFilterBuffer; NvMedia2DCreateFilterBuffer(); NvMedia2DFilter; NvMedia2DSetSrcFilter(); NvMedia2DComputeFilterCoefficients5Tap(); NvMedia2DComputeFilterCoefficients10Tap()

◆ NvMedia2DSetSrcBlendMode()

NvMediaStatus NvMedia2DSetSrcBlendMode	(	NvMedia2D *const	handle,
		NvMedia2DComposeParameters const	params,
		uint32_t const	index,
		NvMedia2DBlendMode const	blendMode,
		float const	constantAlpha
	)

Sets the blend mode for a source layer.

Parameters

[in]	handle	Pointer to the NvMedia2D context.
[in]	params	An NvMedia2DComposeParameters handle.
[in]	index	Index of source layer to configure. Must be in range [0, 15].
[in]	blendMode	Blend mode to set.
[in]	constantAlpha	Constant alpha factor to use in blending. Must be in range [0, 1].

Returns: An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	Parameters set successfully.
NVMEDIA_STATUS_BAD_PARAMETER	One of the parameters has an invalid value. This could be: handle is NULL params is invalid index is out of range blendMode is invalid constantAlpha is out of range

Precondition

handle must be valid NvMedia2D handle created with NvMedia2DCreate().
params must be valid NvMedia2DComposeParameters handle created with NvMedia2DGetComposeParameters().

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes, with the following conditions:
  - Each thread uses different NvMedia2D handle
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: No
- Runtime: Yes
- De-Init: No

See also: NvMedia2DComposeParameters; NvMedia2DBlendMode; NvMedia2DCompose()

◆ NvMedia2DSetSrcFilter()

NvMediaStatus NvMedia2DSetSrcFilter	(	NvMedia2D *const	handle,
		NvMedia2DComposeParameters const	params,
		uint32_t const	index,
		NvMedia2DFilter const	filter
	)

Sets the filter mode for a source layer.

Parameters

[in]	handle	Pointer to the NvMedia2D context.
[in]	params	An NvMedia2DComposeParameters handle.
[in]	index	Index of source layer to configure. Must be in range [0, 15].
[in]	filter	An NvMedia2DFilter to use when reading the the layer's source surface.

Returns: An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	Parameters set successfully.
NVMEDIA_STATUS_BAD_PARAMETER	One of the parameters has an invalid value. This could be: handle is NULL params is invalid index is out of range filter is invalid.

Precondition

handle must be valid NvMedia2D handle created with NvMedia2DCreate().
params must be valid NvMedia2DComposeParameters handle created with NvMedia2DGetComposeParameters().

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes, with the following conditions:
  - Each thread uses different NvMedia2D handle
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: No
- Runtime: Yes
- De-Init: No

See also: NvMedia2DComposeParameters; NvMedia2DCompose()

◆ NvMedia2DSetSrcGeometry()

NvMediaStatus NvMedia2DSetSrcGeometry	(	NvMedia2D *const	handle,
		NvMedia2DComposeParameters const	params,
		uint32_t const	index,
		NvMediaRect const *const	srcRect,
		NvMediaRect const *const	dstRect,
		NvMedia2DTransform const	transform
	)

Sets the geometry for a source layer.

Parameters

[in]	handle	Pointer to the NvMedia2D context.
[in]	params	An NvMedia2DComposeParameters handle.
[in]	index	Index of source layer to configure. Must be in range [0, 15].
[in]	dstRect	Pointer to an NvMediaRect that contains the destination rectangle, or NULL for default rectangle.
[in]	srcRect	Pointer to an NvMediaRect that contains the source rectangle, or NULL for default rectangle.
[in]	transform	An NvMedia2DTransform to apply the content region.

Returns: An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	Parameters set successfully.
NVMEDIA_STATUS_BAD_PARAMETER	One of the parameters has an invalid value. This could be: handle is NULL params is invalid index is out of range srcRect is invalid dstRect is invalid transform is invalid.
NVMEDIA_STATUS_NOT_SUPPORTED	Requested operation is not supported by current platform.

Precondition

handle must be valid NvMedia2D handle created with NvMedia2DCreate().
params must be valid NvMedia2DComposeParameters handle created with NvMedia2DGetComposeParameters().

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes, with the following conditions:
  - Each thread uses different NvMedia2D handle
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: No
- Runtime: Yes
- De-Init: No

See also: NvMedia2DComposeParameters; NvMedia2DCompose()

NVIDIA DRIVE OS Linux SDK API Reference

6.0.9 Release

Detailed Description

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ NVMEDIA_2D_VERSION_MAJOR

◆ NVMEDIA_2D_VERSION_MINOR

◆ NVMEDIA_2D_VERSION_PATCH

Typedef Documentation

◆ NvMedia2D

◆ NvMedia2DComposeParameters

◆ NvMedia2DFilterBuffer

Enumeration Type Documentation

◆ NvMedia2DBlendMode

◆ NvMedia2DFilter

◆ NvMedia2DTransform

Function Documentation

◆ NvMedia2DCompose()

◆ NvMedia2DComputeFilterCoefficients10Tap()

◆ NvMedia2DComputeFilterCoefficients5Tap()

◆ NvMedia2DCreate()

◆ NvMedia2DCreateFilterBuffer()

◆ NvMedia2DDestroy()

◆ NvMedia2DDestroyFilterBuffer()

◆ NvMedia2DGetComposeParameters()

◆ NvMedia2DGetVersion()

◆ NvMedia2DSetFilterBuffer()

◆ NvMedia2DSetSrcBlendMode()

◆ NvMedia2DSetSrcFilter()

◆ NvMedia2DSetSrcGeometry()