EGL Stream API

Detailed Description

The EGL Stream API encompasses all NvMedia EGL Stream related functionality.

EGL Stream support enables interaction with EGL based surfaces.

Data Structures
struct	NvMediaEGLStreamProducer
	A handle representing an EGL stream producer object. More...
struct	NvMediaEglStreamProducerAttributes
	Holds the attributes for an EGL stream producer. More...
struct	NvMediaEGLStreamConsumer
	A handle representing an EGL stream consumer object. More...

Macros
#define	NVMEDIA_EGLSTREAM_VERSION_MAJOR   1
	Major Version number. More...
#define	NVMEDIA_EGLSTREAM_VERSION_MINOR   3
	Minor Version number. More...
#define	NVMEDIA_EGL_STREAM_TIMEOUT_INFINITE
	Infinite time-out for NvMedia EGL functions. More...
#define	NVMEDIA_EGL_STREAM_PRODUCER_ATTRIBUTE_MULTISEND
	Defines the multiSend attribute. More...
#define	NvMediaVideoSurfaceStreamProducerCreate   NvMediaEglStreamProducerCreate
	Deprecated function for legacy applications. More...
#define	NvMediaVideoSurfaceStreamProducerDestroy   NvMediaEglStreamProducerDestroy
	Deprecated function for legacy applications. More...
#define	NvMediaPostSurface   NvMediaEglStreamProducerPostSurface
	Deprecated function for legacy applications. More...
#define	NvMediaGetSurface   NvMediaEglStreamProducerGetSurface
	Deprecated function for legacy applications. More...
#define	NvMediaEglConsumerCreate   NvMediaEglStreamConsumerCreate
	Deprecated function for legacy applications. More...
#define	NvMediaEglConsumerDestroy   NvMediaEglStreamConsumerDestroy
	Deprecated function for legacy applications. More...
#define	NvMediaEglConsumerSurfaceAcquire   NvMediaEglStreamConsumerAcquireSurface
	Deprecated function for legacy applications. More...
#define	NvMediaEglConsumerSurfaceRelease   NvMediaEglStreamConsumerReleaseSurface
	Deprecated function for legacy applications. More...

Typedefs
typedef struct NvMediaEGLStreamProducer	NvMediaEGLStreamProducer
	A handle representing an EGL stream producer object. More...
typedef struct NvMediaEGLStreamConsumer	NvMediaEGLStreamConsumer
	A handle representing an EGL stream consumer object. More...

Functions
NvMediaStatus	NvMediaEglStreamGetVersion (NvMediaVersion *version)
	Get the version compatibility for the NvMedia EGLStream library. More...
NvMediaEGLStreamProducer *	NvMediaEglStreamProducerCreate (NvMediaDevice *device, EGLDisplay eglDisplay, EGLStreamKHR eglStream, NvMediaSurfaceType type, EGLint width, EGLint height)
	Creates an EGL stream producer object. More...
void	NvMediaEglStreamProducerSetAttributes (NvMediaEGLStreamProducer *producer, uint32_t attributeMask, NvMediaEglStreamProducerAttributes *attributes)
	Changes attributes of an NvMediaEGLStreamProducer. More...
void	NvMediaEglStreamProducerDestroy (NvMediaEGLStreamProducer *producer)
	Destroys an EGL stream producer object. More...
NvMediaStatus	NvMediaEglStreamProducerPostSurface (NvMediaEGLStreamProducer *producer, NvMediaVideoSurface *surface, NvMediaTime *timeStamp)
	Posts a surface to be sent to an EGL stream connection. More...
NvMediaStatus	NvMediaEglStreamProducerGetSurface (NvMediaEGLStreamProducer *producer, NvMediaVideoSurface **surface, uint32_t millisecondTimeout)
	Retrieves a surface that was sent to an EGL stream using the NvMediaEglStreamProducerPostSurface function and the EGL stream has processed and released it. More...
NvMediaEGLStreamConsumer *	NvMediaEglStreamConsumerCreate (NvMediaDevice *device, EGLDisplay dpy, EGLStreamKHR stream, NvMediaSurfaceType type)
	Creates an EGL stream consumer object. More...
void	NvMediaEglStreamConsumerDestroy (NvMediaEGLStreamConsumer *consumer)
	Destroys an EGL stream consumer object. More...
NvMediaStatus	NvMediaEglStreamConsumerAcquireSurface (NvMediaEGLStreamConsumer *consumer, NvMediaVideoSurface **surface, uint32_t millisecondTimeout, NvMediaTime *timeStamp)
	Acquires a surface that was sent by an EGL stream producer. More...
NvMediaStatus	NvMediaEglStreamConsumerReleaseSurface (NvMediaEGLStreamConsumer *consumer, NvMediaVideoSurface *surface)
	Releases a surface that was received by the NvMediaEglStreamConsumerAcquireSurface function. More...
NvMediaStatus	NvMediaEglStreamProducerPostImage (NvMediaEGLStreamProducer *producer, NvMediaImage *image, NvMediaTime *timeStamp)
	Posts an image to be sent to an EGL stream connection. More...
NvMediaStatus	NvMediaEglStreamProducerGetImage (NvMediaEGLStreamProducer *producer, NvMediaImage **image, uint32_t millisecondTimeout)
	Retrieves an image that was sent to an EGL stream using the NvMediaEglStreamProducerPostImage function and the EGL stream has processed and released it. More...
NvMediaStatus	NvMediaEglStreamConsumerAcquireImage (NvMediaEGLStreamConsumer *consumer, NvMediaImage **image, uint32_t millisecondTimeout, NvMediaTime *timeStamp)
	Acquire an image that was sent by an EGL stream producer. More...
NvMediaStatus	NvMediaEglStreamConsumerReleaseImage (NvMediaEGLStreamConsumer *consumer, NvMediaImage *image)
	Releases an image that was received by the NvMediaEglStreamConsumerAcquireImage function. More...
NvMediaStatus	NvMediaEglStreamProducerPostMetaData (NvMediaEGLStreamProducer *producer, uint32_t blockIdx, const void *dataBuf, uint32_t offset, uint32_t size)
	Posts a block of metadata to be sent to an EGL stream connection. More...
NvMediaStatus	NvMediaEglStreamConsumerAcquireMetaData (NvMediaEGLStreamConsumer *consumer, uint32_t blockIdx, void *dataBuf, uint32_t offset, uint32_t size)
	Acquires specified metadata block that was sent by an EGL stream producer. More...

Macro Definition Documentation

#define NVMEDIA_EGL_STREAM_PRODUCER_ATTRIBUTE_MULTISEND

Defines the multiSend attribute.

Definition at line 120 of file nvmedia_eglstream.h.

#define NVMEDIA_EGL_STREAM_TIMEOUT_INFINITE

Infinite time-out for NvMedia EGL functions.

Definition at line 48 of file nvmedia_eglstream.h.

#define NVMEDIA_EGLSTREAM_VERSION_MAJOR   1

Major Version number.

Definition at line 40 of file nvmedia_eglstream.h.

#define NVMEDIA_EGLSTREAM_VERSION_MINOR   3

Minor Version number.

Definition at line 42 of file nvmedia_eglstream.h.

#define NvMediaEglConsumerCreate   NvMediaEglStreamConsumerCreate

Deprecated function for legacy applications.

Definition at line 313 of file nvmedia_eglstream.h.

#define NvMediaEglConsumerDestroy   NvMediaEglStreamConsumerDestroy

Deprecated function for legacy applications.

Definition at line 315 of file nvmedia_eglstream.h.

#define NvMediaEglConsumerSurfaceAcquire   NvMediaEglStreamConsumerAcquireSurface

Deprecated function for legacy applications.

Definition at line 317 of file nvmedia_eglstream.h.

#define NvMediaEglConsumerSurfaceRelease   NvMediaEglStreamConsumerReleaseSurface

Deprecated function for legacy applications.

Definition at line 319 of file nvmedia_eglstream.h.

#define NvMediaGetSurface   NvMediaEglStreamProducerGetSurface

Deprecated function for legacy applications.

Definition at line 311 of file nvmedia_eglstream.h.

#define NvMediaPostSurface   NvMediaEglStreamProducerPostSurface

Deprecated function for legacy applications.

Definition at line 309 of file nvmedia_eglstream.h.

#define NvMediaVideoSurfaceStreamProducerCreate   NvMediaEglStreamProducerCreate

Deprecated function for legacy applications.

Definition at line 305 of file nvmedia_eglstream.h.

#define NvMediaVideoSurfaceStreamProducerDestroy   NvMediaEglStreamProducerDestroy

Deprecated function for legacy applications.

Definition at line 307 of file nvmedia_eglstream.h.

Typedef Documentation

typedef struct NvMediaEGLStreamConsumer NvMediaEGLStreamConsumer

A handle representing an EGL stream consumer object.

typedef struct NvMediaEGLStreamProducer NvMediaEGLStreamProducer

A handle representing an EGL stream producer object.

Function Documentation

NvMediaStatus NvMediaEglStreamConsumerAcquireImage	(	NvMediaEGLStreamConsumer *	consumer,
		NvMediaImage **	image,
		uint32_t	millisecondTimeout,
		NvMediaTime *	timeStamp
	)

Acquire an image that was sent by an EGL stream producer.

Parameters

[in]	consumer	The EGL stream consumer object to use
[in]	image	The image pointer to receive
[in]	millisecondTimeout	The desired time-out. For infinite time-out use NVMEDIA_EGL_STREAM_TIMEOUT_INFINITE.
[in]	timeStamp	The desired time to display the image or NULL if immediate displaying is required.

Returns

NvMediaStatus The completion status of the operation. Possible values are:
NVMEDIA_STATUS_OK
NVMEDIA_STATUS_BAD_PARAMETER
NVMEDIA_STATUS_TIMED_OUT
NVMEDIA_STATUS_ERROR

NvMediaStatus NvMediaEglStreamConsumerAcquireMetaData	(	NvMediaEGLStreamConsumer *	consumer,
		uint32_t	blockIdx,
		void *	dataBuf,
		uint32_t	offset,
		uint32_t	size
	)

Acquires specified metadata block that was sent by an EGL stream producer.

Parameters

[in]	consumer	A pointer to the EGL stream consumer object to use.
[in]	blockIdx	Block index for the desired EGLstream metadata block.
[in]	dataBuf	A pointer to the data buffer to receive the metadata.
[in]	offset	The desired offset of the data to be queried in EGL stream metadata blocks.
[in]	size	The size of the buffer to receive the metadata.

Returns

NvMediaStatus The completion status of the operation. Possible values are:
NVMEDIA_STATUS_OK
NVMEDIA_STATUS_BAD_PARAMETER
NVMEDIA_STATUS_TIMED_OUT
NVMEDIA_STATUS_ERROR

NvMediaStatus NvMediaEglStreamConsumerAcquireSurface	(	NvMediaEGLStreamConsumer *	consumer,
		NvMediaVideoSurface **	surface,
		uint32_t	millisecondTimeout,
		NvMediaTime *	timeStamp
	)

Acquires a surface that was sent by an EGL stream producer.

Parameters

[in]	consumer	The EGL stream consumer object to use
[in]	surface	The surface pointer to receive
[in]	millisecondTimeout	The desired time-out. For infinite time-out use NVMEDIA_EGL_STREAM_TIMEOUT_INFINITE.
[in]	timeStamp	The desired time to display the surface or NULL if immedate displaying is required.

Returns

NvMediaStatus The completion status of the operation. Possible values are:
NVMEDIA_STATUS_OK
NVMEDIA_STATUS_BAD_PARAMETER
NVMEDIA_STATUS_TIMED_OUT
NVMEDIA_STATUS_ERROR

NvMediaEGLStreamConsumer* NvMediaEglStreamConsumerCreate	(	NvMediaDevice *	device,
		EGLDisplay	dpy,
		EGLStreamKHR	stream,
		NvMediaSurfaceType	type
	)

Creates an EGL stream consumer object.

Parameters

[in]	device	The device's resource manager connection is used for the allocation.
[in]	dpy	EGL display handle
[in]	stream	EGL stream handle
[in]	type	Type of the used surface. The supported types are obtained by /ref NvMediaSurfaceFormatGetType with: NVM_SURF_FMT_SET_ATTR_RGBA(attr, RGBA/BGRA/ARGB, UINT, 8, PL/BL) NVM_SURF_FMT_SET_ATTR_YUV(attr, YUV, 420, SEMI_PLANAR/PLANAR, UINT, 8, PL/BL) NVM_SURF_FMT_SET_ATTR_YUV(attr, YUV, 422, SEMI_PLANAR/PLANAR, UINT, 8, PL/BL) NVM_SURF_FMT_SET_ATTR_YUV(attr, LUMA, NONE, PACKED, UINT, 10/16, PL/BL) NVM_SURF_FMT_SET_ATTR_YUV(attr, XUYV, NONE, PACKED, UINT, 2_10_10_10, PL/BL) NVM_SURF_FMT_SET_ATTR_RAW (attr, RGGB/BGGR/GRBG/GBRG, INT, 12, PL/BL) NVM_SURF_FMT_SET_ATTR_RAW (attr, RCCB/BCCR/CRBC/CBRC, INT, 12, PL/BL) NVM_SURF_FMT_SET_ATTR_RAW (attr, RCCC/CCCR/CRCC/CCRC, INT, 12, PL/BL)

Returns

NvMediaEGLStreamConsumer The new EGL stream consumer's handle or NULL if unsuccessful.

void NvMediaEglStreamConsumerDestroy

(

NvMediaEGLStreamConsumer *

consumer

)

Destroys an EGL stream consumer object.

Parameters

[in]

consumer

The EGL stream consumer to destroy.

Returns

void

NvMediaStatus NvMediaEglStreamConsumerReleaseImage	(	NvMediaEGLStreamConsumer *	consumer,
		NvMediaImage *	image
	)

Releases an image that was received by the NvMediaEglStreamConsumerAcquireImage function.

Parameters

[in]	consumer	The EGL stream consumer object to use
[in]	image	The image to release

Returns

NvMediaStatus The completion status of the operation. Possible values are:
NVMEDIA_STATUS_OK
NVMEDIA_STATUS_BAD_PARAMETER
NVMEDIA_STATUS_TIMED_OUT
NVMEDIA_STATUS_ERROR

NvMediaStatus NvMediaEglStreamConsumerReleaseSurface	(	NvMediaEGLStreamConsumer *	consumer,
		NvMediaVideoSurface *	surface
	)

Releases a surface that was received by the NvMediaEglStreamConsumerAcquireSurface function.

Parameters

[in]	consumer	The EGL stream consumer object to use
[in]	surface	The surface to release

Returns

NvMediaStatus The completion status of the operation. Possible values are:
NVMEDIA_STATUS_OK
NVMEDIA_STATUS_BAD_PARAMETER
NVMEDIA_STATUS_TIMED_OUT
NVMEDIA_STATUS_ERROR

NvMediaStatus NvMediaEglStreamGetVersion

(

NvMediaVersion *

version

)

Get the version compatibility for the NvMedia EGLStream library.

Parameters

[in]

version

A pointer to a NvMediaVersion structure of the client.

Returns

NvMediaStatus The status of the operation. Possible values are:
NVMEDIA_STATUS_OK
NVMEDIA_STATUS_BAD_PARAMETER if the pointer is invalid.

NvMediaEGLStreamProducer* NvMediaEglStreamProducerCreate	(	NvMediaDevice *	device,
		EGLDisplay	eglDisplay,
		EGLStreamKHR	eglStream,
		NvMediaSurfaceType	type,
		EGLint	width,
		EGLint	height
	)

Creates an EGL stream producer object.

Parameters

[in]	device	A pointer to the device resource manager connection, which is used for the allocation.
[in]	eglDisplay	A pointer to the EGL display.
[in]	eglStream	EGL stream handle.
[in]	type	Type of the used surface. The supported types are: NVM_SURF_FMT_SET_ATTR_RGBA(attr, RGBA/BGRA/ARGB, UINT, 8, PL/BL) NVM_SURF_FMT_SET_ATTR_YUV(attr, YUV, 420, SEMI_PLANAR/PLANAR, UINT, 8, PL/BL) NVM_SURF_FMT_SET_ATTR_YUV(attr, YUV, 422, SEMI_PLANAR/PLANAR, UINT, 8, PL/BL) NVM_SURF_FMT_SET_ATTR_YUV(attr, LUMA, NONE, PACKED, UINT, 10/16, PL/BL) NVM_SURF_FMT_SET_ATTR_YUV(attr, XUYV, NONE, PACKED, UINT, 2_10_10_10, PL/BL) NVM_SURF_FMT_SET_ATTR_RAW (attr, RGGB/BGGR/GRBG/GBRG, INT, 12, PL/BL) NVM_SURF_FMT_SET_ATTR_RAW (attr, RCCB/BCCR/CRBC/CBRC, INT, 12, PL/BL) NVM_SURF_FMT_SET_ATTR_RAW (attr, RCCC/CCCR/CRCC/CCRC, INT, 12, PL/BL)
[in]	width	Width of the EGL stream producer.
[in]	height	Height of the EGL stream producer.

Return values

NvMediaEGLStreamProducer

The new EGL stream producer's handle or NULL if unsuccessful.

void NvMediaEglStreamProducerDestroy

(

NvMediaEGLStreamProducer *

producer

)

Destroys an EGL stream producer object.

Parameters

[in]

producer

The EGL stream producer to destroy.

NvMediaStatus NvMediaEglStreamProducerGetImage	(	NvMediaEGLStreamProducer *	producer,
		NvMediaImage **	image,
		uint32_t	millisecondTimeout
	)

Retrieves an image that was sent to an EGL stream using the NvMediaEglStreamProducerPostImage function and the EGL stream has processed and released it.

At any point in time after streaming starts, EGLStream is required to hold at least one buffer. This is to ensure the consumer has at least one buffer on which to work. As a result, applications must ensure that at least two images are posted to EGLStream before calling NvMediaEglStreamProducerGetImage() with the millisecondTimeout parameter set to NVMEDIA_EGL_STREAM_TIMEOUT_INFINITE.

Consider the following sequence:

1. The producer posts image1.
2. The consumer acquires, processes, and releases image1.

In the above sequence, the producer cannot get image1 by calling NvMediaEglStreamProducerGetImage(). Instead, it must post another image, say image2, before it can get image1.

For information on multiple consumer support, see the "EGLStream Support for Multiple Consumers/Producers" topic in the "Graphics Programming" chapter in the Development Guide.

Parameters

[in]	producer	The EGL stream producer object to use
[in]	image	The image pointer to receive
[in]	millisecondTimeout	The desired time-out. For infinite time-out use NVMEDIA_EGL_STREAM_TIMEOUT_INFINITE.

Returns

NvMediaStatus The completion status of the operation. Possible values are:
NVMEDIA_STATUS_OK
NVMEDIA_STATUS_BAD_PARAMETER
NVMEDIA_STATUS_TIMED_OUT
NVMEDIA_STATUS_ERROR

NvMediaStatus NvMediaEglStreamProducerGetSurface	(	NvMediaEGLStreamProducer *	producer,
		NvMediaVideoSurface **	surface,
		uint32_t	millisecondTimeout
	)

Retrieves a surface that was sent to an EGL stream using the NvMediaEglStreamProducerPostSurface function and the EGL stream has processed and released it.

At any point in time after streaming starts, EGLStream is required to hold at least one buffer. This is to ensure the consumer has at least one buffer on which to work. As a result, applications must ensure that at least two surfaces are posted to EGLStream before calling NvMediaEglStreamProducerGetSurface() with the millisecondTimeout parameter set to NVMEDIA_EGL_STREAM_TIMEOUT_INFINITE.

Consider the following sequence:

1. The producer posts surface1.
2. The consumer acquires, processes, and releases surface1.

In the above sequence, the producer cannot get surface1 by calling NvMediaEglStreamProducerGetSurface(). Instead, it must post another surface, say surface2, before it can get surface1.

For information on multiple consumer support, see the "EGLStream Support for Multiple Consumers/Producers" topic in the "Graphics Programming" chapter in the Development Guide.

Parameters

[in]	producer	The EGL stream producer object to use
[in]	surface	The surface pointer to receive
[in]	millisecondTimeout	The desired time-out. For infinite time-out use NVMEDIA_EGL_STREAM_TIMEOUT_INFINITE.

Returns

NvMediaStatus The completion status of the operation. Possible values are:
NVMEDIA_STATUS_OK
NVMEDIA_STATUS_BAD_PARAMETER
NVMEDIA_STATUS_TIMED_OUT
NVMEDIA_STATUS_ERROR

NvMediaStatus NvMediaEglStreamProducerPostImage	(	NvMediaEGLStreamProducer *	producer,
		NvMediaImage *	image,
		NvMediaTime *	timeStamp
	)

Posts an image to be sent to an EGL stream connection.

For information on multiple consumer support, see the "Using NvMedia EGLStream to Send to Multiple Consumers" topic in the "Graphics Guide" chapter in the Development Guide.

Parameters

[in]	producer	The EGL stream producer object to use.
[in]	image	The image to send.
[in]	timeStamp	The desired time to display the image or NULL if immediate displaying is required.

Returns

NvMediaStatus The completion status of the operation. Possible values are:
NVMEDIA_STATUS_OK
NVMEDIA_STATUS_BAD_PARAMETER
NVMEDIA_STATUS_ERROR

NvMediaStatus NvMediaEglStreamProducerPostMetaData	(	NvMediaEGLStreamProducer *	producer,
		uint32_t	blockIdx,
		const void *	dataBuf,
		uint32_t	offset,
		uint32_t	size
	)

Posts a block of metadata to be sent to an EGL stream connection.

Parameters

[in]	producer	A pointer to the EGL stream producer object to use.
[in]	blockIdx	Block index for the desired EGLstream metadata block.
[in]	dataBuf	A pointer to the data buffer to be sent.
[in]	offset	The desired offset of the data to be stored in EGL stream metadata blocks.
[in]	size	The size of the data buffer to send.

Returns

NvMediaStatus The completion status of the operation. Possible values are:
NVMEDIA_STATUS_OK
NVMEDIA_STATUS_BAD_PARAMETER
NVMEDIA_STATUS_ERROR

NvMediaStatus NvMediaEglStreamProducerPostSurface	(	NvMediaEGLStreamProducer *	producer,
		NvMediaVideoSurface *	surface,
		NvMediaTime *	timeStamp
	)

Posts a surface to be sent to an EGL stream connection.

Parameters

[in]	producer	The EGL stream producer object to use
[in]	surface	The surface to send
[in]	timeStamp	The desired time to display the surface or NULL if immedate displaying is required.

Returns

NvMediaStatus The completion status of the operation. Possible values are:
NVMEDIA_STATUS_OK
NVMEDIA_STATUS_BAD_PARAMETER
NVMEDIA_STATUS_ERROR

void NvMediaEglStreamProducerSetAttributes	(	NvMediaEGLStreamProducer *	producer,
		uint32_t	attributeMask,
		NvMediaEglStreamProducerAttributes *	attributes
	)

Changes attributes of an NvMediaEGLStreamProducer.

Parameters

[in]	producer	A pointer to the target producer.
[in]	attributeMask	Specifies which attributes are set. The value can be any combination of the binary OR of the following attributes: NVMEDIA_EGL_STREAM_PRODUCER_ATTRIBUTE_MULTISEND
[in]	attributes	A pointer to a structure that holds all the attributes, but only those are used which are indicated in the attributeMask.

Example: Enabling Multiple Sending On A Producer

NvMediaEglStreamProducerAttributes producerAttributes = { .multiSend = NVMEDIA_TRUE };
NvMediaEglStreamProducerSetAttributes(
  producerHandle,
  NVMEDIA_EGL_STREAM_PRODUCER_ATTRIBUTE_MULTISEND,
  & producerAttributes);