Image Handling API

Detailed Description

The Image Processing API encompasses all NvMedia image-related functionality.

Note

Not all the functions are supported on safety build and refer to nvmedia safety manual for details of APIs available on safety build.

Data Structures
struct	NvMediaImageSurface
	Holds an image surface descriptor used by NvMediaImageLock(). More...
struct	NvMediaImageSurfaceMap
	Holds an image surface map descriptor used by NvMediaImageLock(). More...

Modules
	Image 2D Processing
	The Image 2D Processing API encompasses all NvMedia 2D image processing related functionality.
	Image 2D Processing Synchronization
	The NvMedia 2D NvSciSync API encompasses all NvMedia2D NvSciSync handling functions.
	Image Capture
	Captures uncompressed image data, writing the results to an NvMediaImage.
	Image Capture Synchronization
	The NvMedia ICP NvSciSync API encompasses all NvMediaICP NvSciSync handling functions.
	Image Creation
	Defines and manages image objects.
	Image Decoder
	Image Display Processing (IDP)
	Displays NvMediaImage type surfaces.
	Image Encoder
	The NvMediaIEP object takes uncompressed image data and turns it into a codec specific bitstream. Only H.264, H.265 and VP9 encoding is supported.
	Image Encoder Synchronization
	The NvMedia IEP NvSciSync API encompasses all NvMediaIEP NvSciSync handling functions.
	Image Handling with Buffer Allocation API
	The NvMedia Image NvSciBuf API encompasses all NvMediaImage NvSciBuf handling functions.
	Image JPEG Decoder
	The NvMediaIJPD object takes a JPEG bitstream and decompress it to image data.
	Image JPEG Encoder
	The NvMediaIJPE object takes uncompressed image data and turns it into a jpeg bitstream.
	Image Locking and Unlocking
	Locking and unlocking controls access to the image surfaces.
	Image OFST Synchronization
	The NvMedia IOFST NvSciSync API encompasses all NvMediaIOFST NvSciSync handling functions.
	Image OpticalFlow/StereoDisparity (OFST) Estimator
	The NvMediaIOFST object takes an uncompressed image frame pair and turns them into opticalflow/stereodisparity estimation data.
	Image Read and Write by Client
	Provides image surface read and write by the client application for diagnostic purposes.
	Image Sensor Control (ISC)
	Image Signal Processing (ISP) Statistics
	NvMedia ISP Defines NvMedia ISP Stat structures.
	SIPL
	SIPL provides abstract and simple API to capture the output of image sensors with optional image processing. SIPL is implemented on top of NvMedia API.

Macros
#define	NVMEDIA_IMAGE_VERSION_MAJOR   (1u)
	Major version number. More...
#define	NVMEDIA_IMAGE_VERSION_MINOR   (24u)
	Minor version number. More...

Functions
NvMediaStatus	NvMediaImageGetEmbeddedData (const NvMediaImage *image, uint32_t imageIndex, uint8_t *embeddedBufTop, uint32_t *embeddedBufTopSize, uint8_t *embeddedBufBottom, uint32_t *embeddedBufBottomSize)
	Returns embedded data stored in a captured image. More...
NvMediaStatus	NvMediaImageGetStatus (const NvMediaImage *image, uint32_t millisecondWait, NvMediaTaskStatus *taskStatus)
	Gets status of the current or most recent operation for an image; optionally waits for the current operation to complete or time out. More...
NvMediaStatus	NvMediaImageSetTag (NvMediaImage *image, void *tag)
	Sets a tag for an NvMediaImage. More...
NvMediaStatus	NvMediaImageGetTag (const NvMediaImage *image, void **tag)
	Gets the tag from an NvMediaImage. More...
NvMediaStatus	NvMediaImageGetTimeStamp (const NvMediaImage *image, NvMediaTime *timeStamp)
	Gets the capture timestamp of the image. More...
NvMediaStatus	NvMediaImageGetGlobalTimeStamp (const NvMediaImage *image, NvMediaGlobalTime *globalTimeStamp)
	Gets the global capture timestamp of the image. More...

Macro Definition Documentation

NVMEDIA_IMAGE_VERSION_MAJOR

#define NVMEDIA_IMAGE_VERSION_MAJOR   (1u)

Major version number.

Definition at line 38 of file nvmedia_image.h.

NVMEDIA_IMAGE_VERSION_MINOR

#define NVMEDIA_IMAGE_VERSION_MINOR   (24u)

Minor version number.

Definition at line 40 of file nvmedia_image.h.

Function Documentation

NvMediaImageGetEmbeddedData()

NvMediaStatus NvMediaImageGetEmbeddedData	(	const NvMediaImage *	image,
		uint32_t	imageIndex,
		uint8_t *	embeddedBufTop,
		uint32_t *	embeddedBufTopSize,
		uint8_t *	embeddedBufBottom,
		uint32_t *	embeddedBufBottomSize
	)

Returns embedded data stored in a captured image.

Embedded data can be added to the following image types. This type must obtained by a call to NvMediaSurfaceFormatGetType() with:

• NVM_SURF_FMT_SET_ATTR_YUV(attr, YUYV, 422, PACKED, UINT, 8, PL)
• NVM_SURF_FMT_SET_ATTR_RGBA(attr, RGBA, UINT, 8, [PL])
• NVM_SURF_FMT_SET_ATTR_RAW(attr, [RGGB/BGGR/GRBG/GBRG], [UINT/INT], [8/10/12/16/20], PL)
• NVM_SURF_FMT_SET_ATTR_RAW(attr, [RCCB/BCCR/CRBC/CBRC], [UINT/INT], 12, PL)
• NVM_SURF_FMT_SET_ATTR_RAW(attr, [RCCC/CCCR/CRCC/CCRC], [UINT/INT], 12, PL)

To use use this API, while creating an NvMedia image, you must set NvMediaSurfAllocAttrType in NvMediaSurfAllocAttr to NVM_SURF_ATTR_CPU_ACCESS_UNCACHED or NVM_SURF_ATTR_CPU_ACCESS_CACHED.

Embedded data may contain 8-bit data or data encoded in the sensor pixel data type, depending on the camera sensor side specification.

In case of RAW12 DataType, the bit layout may change without warning, depending on the surface data type specified.

The VI hardware changes data layout to:

• For RAW12 UINT case: [11][10][9][8][7][6][5][4][3][2][1][0][P][P][P][P]
• For RAW12 INT case: [0][11][10][9][8][7][6][5][4][3][2][1][0][P][P][P]

Each embedded data pixel has 16 bits. [P] represents a padding bit. Padding bits duplicate the most significant bits: [11][10][9][8] for UINT, or [11][10][9] for INT.

Contact NVIDIA for more information on other DataTypes.

Parameters

[in]	image	A pointer to the image from which to get embedded data.
[in]	imageIndex	Index of the sub-image in the case of a multi-image handle, counting from 0. For a single image handle imageIndex is ignored. 0 must be passed as this parameter's value, else the API will fail.
[in]	embeddedBufTop	A pointer to a buffer allocated on the caller side to store top data.
[in,out]	embeddedBufTopSize	A pointer to top buffer size (in). Actual size of copied data is returned at this location (out). Top buffer size is calculated from values like frame resolution and NVM_SURF_ATTR_EMB_LINES_TOP.
[in]	embeddedBufBottom	A pointer to a buffer allocated at caller side to store bottom data.
[in,out]	embeddedBufBottomSize	A pointer to bottom buffer size (in). Actual size of copied data is returned at this location (out). Bottom buffer size is calculated from values like frame resolution and NVM_SURF_ATTR_EMB_LINES_BOTTOM.

Return values

NVMEDIA_STATUS_OK	indicates that that call was successful.
NVMEDIA_STATUS_BAD_PARAMETER	indicates that one or more pointer parameters were NULL.
NVMEDIA_STATUS_ERROR	indicates that the surface type is not supported.

NvMediaImageGetGlobalTimeStamp()

NvMediaStatus NvMediaImageGetGlobalTimeStamp	(	const NvMediaImage *	image,
		NvMediaGlobalTime *	globalTimeStamp
	)

Gets the global capture timestamp of the image.

The global timestamp is set by the NvMedia IPP Capture component.

Parameters

[in]	image	A pointer to the image for which to get the timestamp.
[out]	globalTimeStamp	A pointer to the global capture timestamp of the image.

Return values

NVMEDIA_STATUS_OK	indicates that the call was successful.
NVMEDIA_STATUS_BAD_PARAMETER	indicates that image or timeStamp was NULL.
NVMEDIA_STATUS_ERROR	indicates that another error occurred.

NvMediaImageGetStatus()

NvMediaStatus NvMediaImageGetStatus	(	const NvMediaImage *	image,
		uint32_t	millisecondWait,
		NvMediaTaskStatus *	taskStatus
	)

Gets status of the current or most recent operation for an image; optionally waits for the current operation to complete or time out.

It waits only on a write operation to be completed on the image.

Parameters

[in]	image	A pointer to the image. It should be non-null.
[in]	millisecondWait	Time in milliseconds to wait for the current operation to complete before getting status. Valid range of input is [0, UINT32_MAX] NVMEDIA_IMAGE_TIMEOUT_INFINITE means wait indefinitely.
[out]	taskStatus	A pointer to the status of the operation. It should be non-null.

Return values

NVMEDIA_STATUS_OK	indicates that the call was successful.
NVMEDIA_STATUS_BAD_PARAMETER	indicates that image or status was NULL.
NVMEDIA_STATUS_TIMED_OUT	indicates that wait for the current operation timed out.
NVMEDIA_STATUS_ERROR	indicates that another error occurred.

NvMediaImageGetTag()

NvMediaStatus NvMediaImageGetTag	(	const NvMediaImage *	image,
		void **	tag
	)

Gets the tag from an NvMediaImage.

Note

The NvMediaImage struct's tag member is deprecated, and will be retired in a future release. Use NvMediaImageSetTag() to set a tag and NvMediaImageGetTag() to get a tag instead.

Parameters

[in]	image	A pointer to image for which to get the tag. It should be a valid non-null pointer.
[out]	tag	A pointer to a location where the function is to put a pointer to the tag. It should be non-null.

Returns

A status code; NVMEDIA_STATUS_OK if the call was successful, or NVMEDIA_STATUS_BAD_PARAMETER if image or tag was NULL.

NvMediaImageGetTimeStamp()

NvMediaStatus NvMediaImageGetTimeStamp	(	const NvMediaImage *	image,
		NvMediaTime *	timeStamp
	)

Gets the capture timestamp of the image.

Parameters

[in]	image	A pointer to the image for which to get the timestamp.
[out]	timeStamp	A pointer the capture timestamp of the image.

Return values

NVMEDIA_STATUS_OK	indicates that the call was successful.
NVMEDIA_STATUS_BAD_PARAMETER	indicates that image or timeStamp was NULL.
NVMEDIA_STATUS_ERROR	indicates that another error occurred.

NvMediaImageSetTag()

NvMediaStatus NvMediaImageSetTag	(	NvMediaImage *	image,
		void *	tag
	)

Sets a tag for an NvMediaImage.

Associates a tag (an arbitrary pointer) with an NvMediaImage.

Note

The NvMediaImage struct's tag member is deprecated, and will be retired in a future release. Use NvMediaImageSetTag() to set a tag instead.

Parameters

[in]	image	A pointer to image for which a tag is to be set. It should be a valid non-null pointer
[in]	tag	A pointer to the tag.

Returns

A status code; NVMEDIA_STATUS_OK if the call was successful, or NVMEDIA_STATUS_BAD_PARAMETER if image was NULL.