Jetson Linux API Reference

35.2.1 Release

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...
 
NvBuffergetNthBuffer (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_bufA pointer to the v4l2_buffer structure that is used for dequeueing.
bufferA pointer to the NvBuffer object at the index contained in v4l2_buf.
shared_bufferA pointer to the NvBuffer object if the plane shares a buffer with other elements, else NULL.
dataA 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_bufA reference to the v4l2_buffer structure to use for dequeueing.
[out]bufferReturns a pointer to a pointer to the NvBuffer object associated with the dequeued buffer. Can be NULL.
[out]shared_bufferReturns a pointer to a pointer to the shared NvBuffer object if the queued buffer is shared with other elements. Can be NULL.
[in]num_retriesNumber 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_indexSpecifies 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]cropA 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]formatA 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_bufAddress of the NvBuffer to which the NvMMBuffer is mapped.
[in]dmabuff_fdIndex 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_bufA reference to the v4l2_buffer structure to use for queueing.
[in]shared_bufferA 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_indexSpecifies 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_typeSpecifies the type of V4L2 memory to be requested.
[in]numSpecifies 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_planesNumber of planes in the buffer.
[in]planefmtsA 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]callbackMethod 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]formatA 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]targetSpecifies the rectangle selection type.
[in]flagsSpecifies the flags to control selection adjustments.
[in]rectA 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]parmA 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]statusMust 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_typeV4L2 Memory to use on the buffer.
[in]num_buffersNumber of buffer to request on the plane.
[in]mapboolean value indicating if the buffers should be mapped to memory (Only for V4L2_MEMORY_MMAP).
[in]allocateboolean 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]dataA 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]indexfor the current buffer index.
[in]dmabuff_fdIndex 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_msMaximum 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_msMaximum 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_msMaximum 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: