Detailed Description

Defines a helper class for operations performed on a V4L2 Element plane.

This derived class is modeled on the planes of a V4L2 Element. It provides convenient wrapper methods around V4L2 IOCTLs associated with plane operations such as VIDIOC_G_FMT/VIDIOC_S_FMT, VIDIOC_REQBUFS, VIDIOC_STREAMON/VIDIOC_STREAMOFF, etc.

The plane buffer type can be either V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE (for the output plane) or V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE (for the capture plane).

The plane has an array of NvBuffer object pointers that is allocated and initialized during reqbuf call. These NvBuffer objects are similar to the v4l2_buffer structures that are queued/dequeued.

This class provides another feature useful for multi-threading. On calling startDQThread, it internally spawns a thread that runs infinitely until signaled to stop. This thread keeps trying to dequeue a buffer from the plane and calls a dqThreadCallback method specified by the user on successful dequeue.

Definition at line 104 of file NvV4l2ElementPlane.h.

Public Types
typedef bool(*	dqThreadCallback) (struct v4l2_buffer v4l2_buf, NvBuffer buffer, NvBuffer shared_buffer, void data)
	This is a callback function type method that is called by the DQ Thread when it successfully dequeues a buffer from the plane. More...

Public Member Functions
int	getFormat (struct v4l2_format &format)
	Gets the plane format. More...

int	setFormat (struct v4l2_format &format)
	Sets the plane format. More...

int	mapOutputBuffers (struct v4l2_buffer &v4l2_buf, int dmabuff_fd)
	Maps the NvMMBuffer to NvBuffer for V4L2_MEMORY_DMABUF. More...

int	unmapOutputBuffers (int index, int dmabuff_fd)
	Unmaps the NvMMBuffer for V4L2_MEMORY_DMABUF. More...

int	getCrop (struct v4l2_crop &crop)
	Gets the cropping rectangle for the plane. More...

int	setSelection (uint32_t target, uint32_t flags, struct v4l2_rect &rect)
	Sets the selection rectangle for the plane. More...

int	reqbufs (enum v4l2_memory mem_type, uint32_t num)
	Requests for buffers on the plane. More...

int	queryBuffer (uint32_t buf_index)
	Queries the status of the buffer at the index. More...

int	exportBuffer (uint32_t buf_index)
	Exports the buffer as DMABUF FD. More...

int	setStreamStatus (bool status)
	Starts or stops streaming on the plane. More...

bool	getStreamStatus ()
	Checks whether the plane is streaming. More...

int	setStreamParms (struct v4l2_streamparm &parm)
	Sets streaming parameters. More...

int	setupPlane (enum v4l2_memory mem_type, uint32_t num_buffers, bool map, bool allocate)
	Helper method that encapsulates all the method calls required to set up the plane for streaming. More...

void	deinitPlane ()
	Helper method that encapsulates all the method calls required to deinitialize the plane for streaming. More...

enum v4l2_buf_type	getBufType ()
	Gets the streaming/buffer type of this plane. More...

NvBuffer *	getNthBuffer (uint32_t n)
	Gets the `NvBuffer` object at index n. More...

int	dqBuffer (struct v4l2_buffer &v4l2_buf, NvBuffer buffer, NvBuffer shared_buffer, uint32_t num_retries)
	Dequeues a buffer from the plane. More...

int	qBuffer (struct v4l2_buffer &v4l2_buf, NvBuffer *shared_buffer)
	Queues a buffer on the plane. More...

uint32_t	getNumBuffers ()
	Gets the number of buffers allocated/requested on the plane. More...

uint32_t	getNumPlanes ()
	Gets the number of planes buffers on this plane for the currently set format. More...

void	setBufferPlaneFormat (int n_planes, NvBuffer::NvBufferPlaneFormat *planefmts)
	Sets the format of the planes of the buffer that is used with this plane. More...

uint32_t	getNumQueuedBuffers ()
	Gets the number of buffers currently queued on the plane. More...

uint32_t	getTotalDequeuedBuffers ()
	Gets the total number of buffers dequeued from the plane. More...

uint32_t	getTotalQueuedBuffers ()
	Gets the total number of buffers queued on the plane. More...

int	waitAllBuffersQueued (uint32_t max_wait_ms)
	Waits until all buffers of the plane are queued. More...

int	waitAllBuffersDequeued (uint32_t max_wait_ms)
	Waits until all buffers of the plane are dequeued. More...

bool	setDQThreadCallback (dqThreadCallback callback)
	Sets the DQ Thread callback method. More...

int	startDQThread (void *data)
	Starts DQ Thread. More...

int	stopDQThread ()
	Force stops the DQ Thread if it is running. More...

int	waitForDQThread (uint32_t max_wait_ms)
	Waits for the DQ Thread to stop. More...

Data Fields
pthread_mutex_t	plane_lock
	Mutex lock used along with plane_cond. More...

pthread_cond_t	plane_cond
	Plane condition that application can wait on to receive notifications from qBuffer/dqBuffer. More...

Friends
class	NvV4l2Element

Member Typedef Documentation

◆ dqThreadCallback

typedef bool(* NvV4l2ElementPlane::dqThreadCallback) (struct v4l2_buffer *v4l2_buf, NvBuffer *buffer, NvBuffer *shared_buffer, void *data)

This is a callback function type method that is called by the DQ Thread when it successfully dequeues a buffer from the plane.

Applications must implement this and set the callback using setDQThreadCallback.

Setting the stream to off automatically stops this thread.

See also: setDQThreadCallback, startDQThread

Parameters

v4l2_buf	A pointer to the `v4l2_buffer` structure that is used for dequeueing.
buffer	A pointer to the NvBuffer object at the `index` contained in `v4l2_buf`.
shared_buffer	A pointer to the NvBuffer object if the plane shares a buffer with other elements, else NULL.
data	A pointer to application specific data that is set with startDQThread.

Returns: If the application implementing this call returns FALSE, the DQThread is stopped; else, the DQ Thread continues running.

Definition at line 422 of file NvV4l2ElementPlane.h.

Member Function Documentation

◆ deinitPlane()

void NvV4l2ElementPlane::deinitPlane ( )

Helper method that encapsulates all the method calls required to deinitialize the plane for streaming.

For each of the buffers, unmaps/deallocates memory depending on the memory type. Then, calls reqbuf with count zero.

See also: setupPlane

◆ dqBuffer()

int NvV4l2ElementPlane::dqBuffer	(	struct v4l2_buffer &	v4l2_buf,
		NvBuffer **	buffer,
		NvBuffer **	shared_buffer,
		uint32_t	num_retries
	)

Dequeues a buffer from the plane.

This is a blocking call. This call returns when a buffer is successfully dequeued or timeout is reached. If buffer is not NULL, returns the NvBuffer object at the index returned by the VIDIOC_DQBUF IOCTL. If this plane shares a buffer with other elements and shared_buffer is not NULL, returns the shared NvBuffer object in shared_buffer.

Parameters

[in]	v4l2_buf	A reference to the `v4l2_buffer` structure to use for dequeueing.
[out]	buffer	Returns a pointer to a pointer to the `NvBuffer` object associated with the dequeued buffer. Can be NULL.
[out]	shared_buffer	Returns a pointer to a pointer to the shared `NvBuffer` object if the queued buffer is shared with other elements. Can be NULL.
[in]	num_retries	Number of times to try dequeuing a buffer before a failure is returned. In case of non-blocking mode, this is equivalent to the number of milliseconds to try to dequeue a buffer.

Returns: 0 for success, -1 otherwise.

◆ exportBuffer()

int NvV4l2ElementPlane::exportBuffer ( uint32_t buf_index )

Exports the buffer as DMABUF FD.

Warning: This method works only for V4L2_MEMORY_MMAP memory.

Calls VIDIOC_EXPBUF IOCTL internally. Populates the fd member of all the NvBuffer::NvBufferPlane members of NvBuffer object at index buf_in.

Parameters

[in] buf_index Specifies the index of the buffer to export.

Returns: 0 for success, -1 otherwise.

◆ getBufType()

enum v4l2_buf_type NvV4l2ElementPlane::getBufType ( )

inline

Gets the streaming/buffer type of this plane.

Returns: Type of the buffer belonging to enum v4l2_buf_type.

Definition at line 269 of file NvV4l2ElementPlane.h.

◆ getCrop()

int NvV4l2ElementPlane::getCrop ( struct v4l2_crop & crop )

Gets the cropping rectangle for the plane.

Calls VIDIOC_G_CROP IOCTL internally.

Parameters

[in] crop A reference to the v4l2_crop structure to be filled.

Returns: 0 for success, -1 otherwise.

◆ getFormat()

int NvV4l2ElementPlane::getFormat ( struct v4l2_format & format )

Gets the plane format.

Calls VIDIOC_G_FMT IOCTL internally.

Parameters

[in,out] format A reference to the v4l2_format structure to be filled.

Returns: 0 for success, -1 otherwise.

◆ getNthBuffer()

NvBuffer* NvV4l2ElementPlane::getNthBuffer ( uint32_t n )

Gets the NvBuffer object at index n.

Returns: NvBuffer object at index n, NULL if n >= number of buffers.

◆ getNumBuffers()

uint32_t NvV4l2ElementPlane::getNumBuffers ( )

inline

Gets the number of buffers allocated/requested on the plane.

Returns: Number of buffers.

Definition at line 321 of file NvV4l2ElementPlane.h.

◆ getNumPlanes()

uint32_t NvV4l2ElementPlane::getNumPlanes ( )

inline

Gets the number of planes buffers on this plane for the currently set format.

Returns: Number of planes.

Definition at line 332 of file NvV4l2ElementPlane.h.

◆ getNumQueuedBuffers()

uint32_t NvV4l2ElementPlane::getNumQueuedBuffers ( )

inline

Gets the number of buffers currently queued on the plane.

Returns: Number of buffers currently queued on the plane.

Definition at line 358 of file NvV4l2ElementPlane.h.

◆ getStreamStatus()

bool NvV4l2ElementPlane::getStreamStatus ( )

Checks whether the plane is streaming.

Returns: true if the plane is streaming, false otherwise.

◆ getTotalDequeuedBuffers()

uint32_t NvV4l2ElementPlane::getTotalDequeuedBuffers ( )

inline

Gets the total number of buffers dequeued from the plane.

Returns: Total number of buffers dequeued from the plane.

Definition at line 368 of file NvV4l2ElementPlane.h.

◆ getTotalQueuedBuffers()

uint32_t NvV4l2ElementPlane::getTotalQueuedBuffers ( )

inline

Gets the total number of buffers queued on the plane.

Returns: Total number of buffers queued on the plane.

Definition at line 378 of file NvV4l2ElementPlane.h.

◆ mapOutputBuffers()

int NvV4l2ElementPlane::mapOutputBuffers	(	struct v4l2_buffer &	v4l2_buf,
		int	dmabuff_fd
	)

Maps the NvMMBuffer to NvBuffer for V4L2_MEMORY_DMABUF.

Parameters

[in]	v4l2_buf	Address of the NvBuffer to which the NvMMBuffer is mapped.
[in]	dmabuff_fd	Index to the field that holds NvMMBuffer attributes.

Returns: 0 for success, -1 otherwise.

◆ qBuffer()

int NvV4l2ElementPlane::qBuffer	(	struct v4l2_buffer &	v4l2_buf,
		NvBuffer *	shared_buffer
	)

Queues a buffer on the plane.

This method calls VIDIOC_QBUF internally. If this plane is sharing a buffer with other elements, the application can pass the pointer to the shared NvBuffer object in shared_buffer.

Parameters

[in]	v4l2_buf	A reference to the `v4l2_buffer` structure to use for queueing.
[in]	shared_buffer	A pointer to the shared `NvBuffer` object.

Returns: 0 for success, -1 otherwise.

◆ queryBuffer()

int NvV4l2ElementPlane::queryBuffer ( uint32_t buf_index )

Queries the status of the buffer at the index.

Warning: This method works only for V4L2_MEMORY_MMAP memory.

Calls VIDIOC_QUERYBUF IOCTL internally. Populates the length and mem_offset members of all the NvBuffer::NvBufferPlane members of the NvBuffer object at index buf_index.

Parameters

[in] buf_index Specifies the index of the buffer to query.

Returns: 0 for success, -1 otherwise.

◆ reqbufs()

int NvV4l2ElementPlane::reqbufs	(	enum v4l2_memory	mem_type,
		uint32_t	num
	)

Requests for buffers on the plane.

Calls VIDIOC_REQBUFS IOCTL internally. Creates an array of NvBuffer of length equal to the count returned by the IOCTL.

Parameters

[in]	mem_type	Specifies the type of V4L2 memory to be requested.
[in]	num	Specifies the number of buffers to request on the plane.

Returns: 0 for success, -1 otherwise.

◆ setBufferPlaneFormat()

void NvV4l2ElementPlane::setBufferPlaneFormat	(	int	n_planes,
		NvBuffer::NvBufferPlaneFormat *	planefmts
	)

Sets the format of the planes of the buffer that is used with this plane.

The buffer plane format must be set before calling reqbuf since these are needed by the NvBuffer constructor.

See also: reqbufs

Parameters

[in]	n_planes	Number of planes in the buffer.
[in]	planefmts	A pointer to the array of `NvBufferPlaneFormat` that describes the format of each of the plane. The array length must be at least n_planes.

◆ setDQThreadCallback()

bool NvV4l2ElementPlane::setDQThreadCallback ( dqThreadCallback callback )

Sets the DQ Thread callback method.

The callback method is called from the DQ Thread once a buffer is successfully dequeued.

Parameters

[in] callback Method to be called upon succesful dequeue.

Returns: TRUE for success, FALSE for failure.

◆ setFormat()

int NvV4l2ElementPlane::setFormat ( struct v4l2_format & format )

Sets the plane format.

Calls VIDIOC_S_FMT IOCTL internally.

Parameters

[in] format A reference to the v4l2_format structure to be set on the plane.

Returns: 0 for success, -1 otherwise.

◆ setSelection()

int NvV4l2ElementPlane::setSelection	(	uint32_t	target,
		uint32_t	flags,
		struct v4l2_rect &	rect
	)

Sets the selection rectangle for the plane.

Calls VIDIOC_S_SELECTION IOCTL internally.

Parameters

[in]	target	Specifies the rectangle selection type.
[in]	flags	Specifies the flags to control selection adjustments.
[in]	rect	A reference to the selection rectangle.

Returns: 0 for success, -1 otherwise.

◆ setStreamParms()

int NvV4l2ElementPlane::setStreamParms ( struct v4l2_streamparm & parm )

Sets streaming parameters.

Calls VIDIOC_S_PARM IOCTL internally.

Parameters

[in] parm A reference to the v4l2_streamparm structure to be set on the plane.

Returns: 0 for success, -1 otherwise.

◆ setStreamStatus()

int NvV4l2ElementPlane::setStreamStatus ( bool status )

Starts or stops streaming on the plane.

Calls VIDIOC_STREAMON/VIDIOC_STREAMOFF IOCTLs internally.

Parameters

[in] status Must be TRUE to start the stream, FALSE to stop the stream.

Returns: 0 for success, -1 otherwise.

◆ setupPlane()

int NvV4l2ElementPlane::setupPlane	(	enum v4l2_memory	mem_type,
		uint32_t	num_buffers,
		bool	map,
		bool	allocate
	)

Helper method that encapsulates all the method calls required to set up the plane for streaming.

Calls reqbuf internally. Then, for each of the buffers, calls queryBuffer, exportBuffer and maps the buffer/allocates the buffer memory depending on the memory type.

See also: deinitPlane

Parameters

[in]	mem_type	V4L2 Memory to use on the buffer.
[in]	num_buffers	Number of buffer to request on the plane.
[in]	map	boolean value indicating if the buffers should be mapped to memory (Only for V4L2_MEMORY_MMAP).
[in]	allocate	boolean valued indicating whether the buffers should be allocated memory (Only for V4L2_MEMORY_USERPTR).

Returns: 0 for success, -1 otherwise.

◆ startDQThread()

int NvV4l2ElementPlane::startDQThread ( void * data )

Starts DQ Thread.

This method starts a thread internally. On successful dequeue of a buffer from the plane, the dqThreadCallback method set using setDQThreadCallback is called.

Setting the stream to off automatically stops the thread.

See also: stopDQThread, waitForDQThread

Parameters

[in] data A pointer to the application data. This is provided as an argument in the dqThreadCallback method.

Returns: 0 for success, -1 otherwise.

◆ stopDQThread()

int NvV4l2ElementPlane::stopDQThread ( )

Force stops the DQ Thread if it is running.

Does not work when the device is opened in blocking mode.

See also: startDQThread, waitForDQThread

Returns: 0 for success, -1 otherwise.

◆ unmapOutputBuffers()

int NvV4l2ElementPlane::unmapOutputBuffers	(	int	index,
		int	dmabuff_fd
	)

Unmaps the NvMMBuffer for V4L2_MEMORY_DMABUF.

Parameters

[in]	index	for the current buffer index.
[in]	dmabuff_fd	Index to the field that holds NvMMBuffer attributes.

Returns: 0 for success, -1 otherwise.

◆ waitAllBuffersDequeued()

int NvV4l2ElementPlane::waitAllBuffersDequeued ( uint32_t max_wait_ms )

Waits until all buffers of the plane are dequeued.

This is a blocking call that returns when all the buffers are dequeued or timeout is reached.

Parameters

[in] max_wait_ms Maximum time to wait, in milliseconds

Returns: 0 for success, -1 otherwise.

◆ waitAllBuffersQueued()

int NvV4l2ElementPlane::waitAllBuffersQueued ( uint32_t max_wait_ms )

Waits until all buffers of the plane are queued.

This is a blocking call that returns when all the buffers are queued or timeout is reached.

Parameters

[in] max_wait_ms Maximum time to wait, in milliseconds.

Returns: 0 for success, -1 otherwise.

◆ waitForDQThread()

int NvV4l2ElementPlane::waitForDQThread ( uint32_t max_wait_ms )

Waits for the DQ Thread to stop.

This method waits until the DQ Thread stops or timeout is reached.

See also: startDQThread, stopDQThread

Parameters

[in] max_wait_ms Maximum wait time, in milliseconds.

Returns: 0 for success, -1 otherwise.

Friends And Related Function Documentation

◆ NvV4l2Element

friend class NvV4l2Element

friend

Definition at line 583 of file NvV4l2ElementPlane.h.

Field Documentation

◆ plane_cond

pthread_cond_t NvV4l2ElementPlane::plane_cond

Plane condition that application can wait on to receive notifications from qBuffer/dqBuffer.

Definition at line 475 of file NvV4l2ElementPlane.h.

◆ plane_lock

pthread_mutex_t NvV4l2ElementPlane::plane_lock

Mutex lock used along with plane_cond.

Definition at line 474 of file NvV4l2ElementPlane.h.

The documentation for this class was generated from the following file:

multimedia_api/ll_samples/include/NvV4l2ElementPlane.h


Jetson Linux API Reference	32.7.5 Release

Jetson Linux API Reference

32.7.5 Release

Detailed Description

Public Types

Public Member Functions

Data Fields

Friends

Member Typedef Documentation

◆ dqThreadCallback

Member Function Documentation

◆ deinitPlane()

◆ dqBuffer()

◆ exportBuffer()

◆ getBufType()

◆ getCrop()

◆ getFormat()

◆ getNthBuffer()

◆ getNumBuffers()

◆ getNumPlanes()

◆ getNumQueuedBuffers()

◆ getStreamStatus()

◆ getTotalDequeuedBuffers()

◆ getTotalQueuedBuffers()

◆ mapOutputBuffers()

◆ qBuffer()

◆ queryBuffer()

◆ reqbufs()

◆ setBufferPlaneFormat()

◆ setDQThreadCallback()

◆ setFormat()

◆ setSelection()

◆ setStreamParms()

◆ setStreamStatus()

◆ setupPlane()

◆ startDQThread()

◆ stopDQThread()

◆ unmapOutputBuffers()

◆ waitAllBuffersDequeued()

◆ waitAllBuffersQueued()

◆ waitForDQThread()

Friends And Related Function Documentation

◆ NvV4l2Element

Field Documentation

◆ plane_cond

◆ plane_lock