libcamera: libcamera::V4L2VideoDevice Class Reference

libcamera v0.0.1 Supporting cameras in Linux since 2019

Public Types | Public Member Functions | Static Public Member Functions | Public Attributes | Protected Member Functions | List of all members
libcamera::V4L2VideoDevice Class Reference

V4L2VideoDevice object and API. More...

Inheritance diagram for libcamera::V4L2VideoDevice:
[legend]
Collaboration diagram for libcamera::V4L2VideoDevice:
[legend]

## Public Types
using | Formats = std::map< V4L2PixelFormat, std::vector< SizeRange > >
| A map of supported V4L2 pixel formats to frame sizes.

## Public Member Functions
| V4L2VideoDevice (const std::string &deviceNode)
| Construct a V4L2VideoDevice. More...
| V4L2VideoDevice (const MediaEntity *entity)
| Construct a V4L2VideoDevice from a MediaEntity. More...
int | open ()
| Open the V4L2 video device node and query its capabilities. More...
int | open (SharedFD handle, enum v4l2_buf_type type)
| Open a V4L2 video device from an opened file handle and query its capabilities. More...
void | close ()
| Close the video device, releasing any resources acquired by open()
const char * | driverName () const
| Retrieve the name of the V4L2 device driver. More...
const char * | deviceName () const
| Retrieve the name of the V4L2 video device. More...
const char * | busName () const
| Retrieve the location of the device in the system. More...
const V4L2Capability & | caps () const
| Retrieve the device V4L2 capabilities. More...
int | getFormat (V4L2DeviceFormat *format)
| Retrieve the image format set on the V4L2 video device. More...
int | tryFormat (V4L2DeviceFormat *format)
| Try an image format on the V4L2 video device. More...
int | setFormat (V4L2DeviceFormat *format)
| Configure an image format on the V4L2 video device. More...
Formats | formats (uint32_t code=0)
| Enumerate all pixel formats and frame sizes. More...
int | setSelection (unsigned int target, Rectangle *rect)
| Set a selection rectangle rect for target. More...
int | allocateBuffers (unsigned int count, std::vector< std::unique_ptr< FrameBuffer > > *buffers)
| Allocate and export buffers from the video device. More...
int | exportBuffers (unsigned int count, std::vector< std::unique_ptr< FrameBuffer > > *buffers)
| Export buffers from the video device. More...
int | importBuffers (unsigned int count)
| Prepare the device to import count buffers. More...
int | releaseBuffers ()
| Release resources allocated by allocateBuffers() or importBuffers() More...
int | queueBuffer (FrameBuffer *buffer)
| Queue a buffer to the video device. More...
int | streamOn ()
| Start the video stream. More...
int | streamOff ()
| Stop the video stream. More...
void | setDequeueTimeout (utils::Duration timeout)
| Set the dequeue timeout value. More...
V4L2PixelFormat | toV4L2PixelFormat (const PixelFormat &pixelFormat) const
| Convert PixelFormat to a V4L2PixelFormat supported by the device. More...
Public Member Functions inherited from libcamera::V4L2Device
void | close ()
| Close the device node. More...
bool | isOpen () const
| Check if the V4L2 device node is open. More...
const ControlInfoMap & | controls () const
| Retrieve the supported V4L2 controls and their information. More...
ControlList | getControls (const std::vector< uint32_t > &ids)
| Read controls from the device. More...
int | setControls (ControlList *ctrls)
| Write controls to the device. More...
const struct v4l2_query_ext_ctrl * | controlInfo (uint32_t id) const
| Retrieve the v4l2_query_ext_ctrl information for the given control. More...
const std::string & | deviceNode () const
| Retrieve the device node path. More...
std::string | devicePath () const
| Retrieve the device path in sysfs. More...
int | setFrameStartEnabled (bool enable)
| Enable or disable frame start event notification. More...
void | updateControlInfo ()
| Update the information for all device controls. More...

## Static Public Member Functions
static std::unique_ptr< V4L2VideoDevice > | fromEntityName (const MediaDevice *media, const std::string &entity)
| Create a new video device instance from entity in media device media. More...

## Public Attributes
Signal< FrameBuffer * > | bufferReady
| A Signal emitted when a framebuffer completes.
Signal | dequeueTimeout
| A Signal emitted when the dequeue watchdog timer expires.
Public Attributes inherited from libcamera::V4L2Device
Signal< uint32_t > | frameStart
| A Signal emitted when capture of a frame has started.

## Protected Member Functions
std::string | logPrefix () const override
| Retrieve a string to be prefixed to the log message. More...
Protected Member Functions inherited from libcamera::V4L2Device
| V4L2Device (const std::string &deviceNode)
| Construct a V4L2Device. More...
| ~V4L2Device ()
| Destroy a V4L2Device.
int | open (unsigned int flags)
| Open a V4L2 device node. More...
int | setFd (UniqueFD fd)
| Set the file descriptor of a V4L2 device. More...
int | ioctl (unsigned long request, void *argp)
| Perform an IOCTL system call on the device node. More...
int | fd () const
| Retrieve the V4L2 device file descriptor. More...
Protected Member Functions inherited from libcamera::Loggable
virtual std::string | logPrefix () const =0
| Retrieve a string to be prefixed to the log message. More...
LogMessage | _log (const LogCategory *category, LogSeverity severity, const char *fileName=__builtin_FILE(), unsigned int line=__builtin_LINE()) const
| Create a temporary LogMessage object to log a message. More...

## Additional Inherited Members
Static Protected Member Functions inherited from libcamera::V4L2Device
template<typename T >
static std::optional< ColorSpace > | toColorSpace (const T &v4l2Format, PixelFormatInfo::ColourEncoding colourEncoding)
| Convert the color space fields in a V4L2 format to a ColorSpace. More...
template<typename T >
static int | fromColorSpace (const std::optional< ColorSpace > &colorSpace, T &v4l2Format)
| Fill in the color space fields of a V4L2 format from a ColorSpace. More...

## Detailed Description

V4L2VideoDevice object and API.

The V4L2VideoDevice class models an instance of a V4L2 video device. It is constructed with the path to a V4L2 video device node. The device node is only opened upon a call to open() which must be checked for success.

The video device capabilities are validated when the device is opened and the device is rejected if it is not a suitable V4L2 capture or output video device, or if the video device does not support streaming I/O.

No API call other than open(), isOpen() and close() shall be called on an unopened device instance.

The V4L2VideoDevice class supports the V4L2 MMAP and DMABUF memory types:

- The allocateBuffers() function wraps buffer allocation with the V4L2 MMAP memory type. It requests buffers from the driver, allocating the corresponding memory, and exports them as a set of FrameBuffer objects. Upon successful return the driver's internal buffer management is initialized in MMAP mode, and the video device is ready to accept queueBuffer() calls.

  This is the most traditional V4L2 buffer management, and is mostly useful to support internal buffer pools in pipeline handlers, either for CPU consumption (such as statistics or parameters pools), or for internal image buffers shared between devices.

- The exportBuffers() function operates similarly to allocateBuffers(), but leaves the driver's internal buffer management uninitialized. It uses the V4L2 buffer orphaning support to allocate buffers with the MMAP method, export them as a set of FrameBuffer objects, and reset the driver's internal buffer management. The video device shall be initialized with importBuffers() or allocateBuffers() before it can accept queueBuffer() calls. The exported buffers are directly usable with any V4L2 video device in DMABUF mode, or with other dmabuf importers.

  This method is mostly useful to implement buffer allocation helpers or to allocate ancillary buffers, when a V4L2 video device is used in DMABUF mode but no other source of buffers is available. An example use case would be allocation of scratch buffers to be used in case of buffer underruns on a video device that is otherwise supplied with external buffers.

- The importBuffers() function initializes the driver's buffer management to import buffers in DMABUF mode. It requests buffers from the driver, but doesn't allocate memory. Upon successful return, the video device is ready to accept queueBuffer() calls. The buffers to be imported are provided to queueBuffer(), and may be supplied externally, or come from a previous exportBuffers() call.

  This is the usual buffers initialization method for video devices whose buffers are exposed outside of libcamera. It is also typically used on one of the two video device that participate in buffer sharing inside pipelines, the other video device typically using allocateBuffers().

- The releaseBuffers() function resets the driver's internal buffer management that was initialized by a previous call to allocateBuffers() or importBuffers(). Any memory allocated by allocateBuffers() is freed. Buffer exported by exportBuffers() are not affected by this function.

The V4L2VideoDevice class tracks queued buffers and handles buffer events. It automatically dequeues completed buffers and emits the bufferReady signal.

Upon destruction any device left open will be closed, and any resources released.

Thread Safety:
  This class is thread-bound.

## Constructor & Destructor Documentation

## ◆ V4L2VideoDevice() [1/2]

libcamera::V4L2VideoDevice::V4L2VideoDevice | ( | const std::string & | deviceNode | ) |
| explicit

Construct a V4L2VideoDevice.

Parameters

  [in] | deviceNode | The file-system path to the video device node

## ◆ V4L2VideoDevice() [2/2]

libcamera::V4L2VideoDevice::V4L2VideoDevice | ( | const MediaEntity * | entity | ) |
| explicit

Construct a V4L2VideoDevice from a MediaEntity.

Parameters

  [in] | entity | The MediaEntity to build the video device from

Construct a V4L2VideoDevice from a MediaEntity's device node path.

## Member Function Documentation

## ◆ allocateBuffers()

int libcamera::V4L2VideoDevice::allocateBuffers | ( | unsigned int | count,
|  | std::vector< std::unique_ptr< FrameBuffer > > * | buffers
| ) |  |

Allocate and export buffers from the video device.

Parameters

  [in] | count | Number of buffers to allocate
  [out] | buffers | Vector to store allocated buffers

This function wraps buffer allocation with the V4L2 MMAP memory type. It requests count buffers from the driver, allocating the corresponding memory, and exports them as a set of FrameBuffer objects in buffers. Upon successful return the driver's internal buffer management is initialized in MMAP mode, and the video device is ready to accept queueBuffer() calls.

The number of planes and their offsets and sizes are determined by the currently active format on the device as set by setFormat(). They do not map to the V4L2 buffer planes, but to colour planes of the pixel format. For instance, if the active format is formats::NV12, the allocated FrameBuffer instances will have two planes, for the luma and chroma components, regardless of whether the device uses V4L2_PIX_FMT_NV12 or V4L2_PIX_FMT_NV12M.

Buffers allocated with this function shall later be free with releaseBuffers(). If buffers have already been allocated with allocateBuffers() or imported with importBuffers(), this function returns -EBUSY.

Returns
  The number of allocated buffers on success or a negative error code otherwise

Return values

  -EBUSY | buffers have already been allocated or imported

## ◆ busName()

libcamera::V4L2VideoDevice::busName | ( |  | ) | const
| inline

Retrieve the location of the device in the system.

Returns
  The string containing the device location

## ◆ caps()

libcamera::V4L2VideoDevice::caps | ( |  | ) | const
| inline

Retrieve the device V4L2 capabilities.

Returns
  The device V4L2 capabilities

## ◆ deviceName()

libcamera::V4L2VideoDevice::deviceName | ( |  | ) | const
| inline

Retrieve the name of the V4L2 video device.

Returns
  The string containing the device name

## ◆ driverName()

libcamera::V4L2VideoDevice::driverName | ( |  | ) | const
| inline

Retrieve the name of the V4L2 device driver.

Returns
  The string containing the driver name

## ◆ exportBuffers()

int libcamera::V4L2VideoDevice::exportBuffers | ( | unsigned int | count,
|  | std::vector< std::unique_ptr< FrameBuffer > > * | buffers
| ) |  |

Export buffers from the video device.

Parameters

  [in] | count | Number of buffers to allocate
  [out] | buffers | Vector to store allocated buffers

This function allocates count buffer from the video device and exports them as dmabuf objects, stored in buffers. Unlike allocateBuffers(), this function leaves the driver's internal buffer management uninitialized. The video device shall be initialized with importBuffers() or allocateBuffers() before it can accept queueBuffer() calls. The exported buffers are directly usable with any V4L2 video device in DMABUF mode, or with other dmabuf importers.

The number of planes and their offsets and sizes are determined by the currently active format on the device as set by setFormat(). They do not map to the V4L2 buffer planes, but to colour planes of the pixel format. For instance, if the active format is formats::NV12, the allocated FrameBuffer instances will have two planes, for the luma and chroma components, regardless of whether the device uses V4L2_PIX_FMT_NV12 or V4L2_PIX_FMT_NV12M.

Multiple independent sets of buffers can be allocated with multiple calls to this function. Device-specific limitations may apply regarding the minimum and maximum number of buffers per set, or to total amount of allocated memory. The exported dmabuf lifetime is tied to the returned buffers. To free a buffer, the caller shall delete the corresponding FrameBuffer instance. No bookkeeping and automatic free is performed by the V4L2VideoDevice class.

If buffers have already been allocated with allocateBuffers() or imported with importBuffers(), this function returns -EBUSY.

Returns
  The number of allocated buffers on success or a negative error code otherwise

Return values

  -EBUSY | buffers have already been allocated or imported

## ◆ formats()

V4L2VideoDevice::Formats libcamera::V4L2VideoDevice::formats | ( | uint32_t | code = `0` | ) |

Enumerate all pixel formats and frame sizes.

Parameters

  [in] | code | Restrict formats to this media bus code.

Enumerate all pixel formats and frame sizes supported by the video device. If the code argument is not zero, only formats compatible with that media bus code will be enumerated.

Returns
  A list of the supported video device formats

## ◆ fromEntityName()

std::unique_ptr< V4L2VideoDevice > libcamera::V4L2VideoDevice::fromEntityName | ( | const MediaDevice * | media,
|  | const std::string & | entity
| ) |  |
| static

Create a new video device instance from entity in media device media.

Parameters

  [in] | media | The media device where the entity is registered
  [in] | entity | The media entity name

Returns
  A newly created V4L2VideoDevice on success, nullptr otherwise

## ◆ getFormat()

int libcamera::V4L2VideoDevice::getFormat | ( | V4L2DeviceFormat * | format | ) |

Retrieve the image format set on the V4L2 video device.

Parameters

  [out] | format | The image format applied on the video device

Returns
  0 on success or a negative error code otherwise

## ◆ importBuffers()

int libcamera::V4L2VideoDevice::importBuffers | ( | unsigned int | count | ) |

Prepare the device to import count buffers.

Parameters

  [in] | count | Number of buffers to prepare to import

This function initializes the driver's buffer management to import buffers in DMABUF mode. It requests buffers from the driver, but doesn't allocate memory.

Upon successful return, the video device is ready to accept queueBuffer() calls. The buffers to be imported are provided to queueBuffer(), and may be supplied externally, or come from a previous exportBuffers() call.

Device initialization performed by this function shall later be cleaned up with releaseBuffers(). If buffers have already been allocated with allocateBuffers() or imported with importBuffers(), this function returns -EBUSY.

Returns
  0 on success or a negative error code otherwise

Return values

  -EBUSY | buffers have already been allocated or imported

## ◆ logPrefix()

std::string libcamera::V4L2VideoDevice::logPrefix | ( |  | ) | const
| overrideprotectedvirtual

Retrieve a string to be prefixed to the log message.

This function allows classes inheriting from the Loggable class to extend the logger with an object-specific prefix output right before the log message contents.

Returns
  A string to be prefixed to the log message

Implements libcamera::Loggable.

## ◆ open() [1/2]

int libcamera::V4L2VideoDevice::open | ( |  | ) |

Open the V4L2 video device node and query its capabilities.

Returns
  0 on success or a negative error code otherwise

## ◆ open() [2/2]

int libcamera::V4L2VideoDevice::open | ( | SharedFD | handle,
|  | enum v4l2_buf_type | type
| ) |  |

Open a V4L2 video device from an opened file handle and query its capabilities.

Parameters

  [in] | handle | The file descriptor to set
  [in] | type | The device type to operate on

This function opens a video device from the existing file descriptor handle. Like open(), this function queries the capabilities of the device, but handles it according to the given device type instead of determining its type from the capabilities. This can be used to force a given device type for memory-to-memory devices.

The file descriptor handle is duplicated, no reference to the original handle is kept.

Returns
  0 on success or a negative error code otherwise

## ◆ queueBuffer()

int libcamera::V4L2VideoDevice::queueBuffer | ( | FrameBuffer * | buffer | ) |

Queue a buffer to the video device.

Parameters

  [in] | buffer | The buffer to be queued

For capture video devices the buffer will be filled with data by the device. For output video devices the buffer shall contain valid data and will be processed by the device. Once the device has finished processing the buffer, it will be available for dequeue.

The best available V4L2 buffer is picked for buffer using the V4L2 buffer cache.

Note that queueBuffer() will fail if the device is in the process of being stopped from a streaming state through streamOff().

Returns
  0 on success or a negative error code otherwise

## ◆ releaseBuffers()

int libcamera::V4L2VideoDevice::releaseBuffers | ( |  | ) |

Release resources allocated by allocateBuffers() or importBuffers()

This function resets the driver's internal buffer management that was initialized by a previous call to allocateBuffers() or importBuffers(). Any memory allocated by allocateBuffers() is freed. Buffer exported by exportBuffers(), if any, are not affected.

## ◆ setDequeueTimeout()

void libcamera::V4L2VideoDevice::setDequeueTimeout | ( | utils::Duration | timeout | ) |

Set the dequeue timeout value.

Parameters

  [in] | timeout | The timeout value to be used

Sets a timeout value, given by timeout, that will be used by a watchdog timer to ensure buffer dequeue events are periodically occurring when the device is streaming. The watchdog timer is only active when the device is streaming, so it is not necessary to disable it when the device stops streaming. The timeout value can be safely updated at any time.

If the timer expires, the V4L2VideoDevice::dequeueTimeout signal is emitted. This can typically be used by pipeline handlers to be notified of stalled devices.

Set timeout to 0 to disable the watchdog timer.

## ◆ setFormat()

int libcamera::V4L2VideoDevice::setFormat | ( | V4L2DeviceFormat * | format | ) |

Configure an image format on the V4L2 video device.

Parameters

  [in,out] | format | The image format to apply to the video device

Apply the supplied format to the video device, and return the actually applied format parameters, as V4L2VideoDevice::getFormat would do.

Returns
  0 on success or a negative error code otherwise

## ◆ setSelection()

int libcamera::V4L2VideoDevice::setSelection | ( | unsigned int | target,
|  | Rectangle * | rect
| ) |  |

Set a selection rectangle rect for target.

Parameters

  [in] | target | The selection target defined by the V4L2_SEL_TGT_* flags
  [in,out] | rect | The selection rectangle to be applied

Todo:
  Define a V4L2SelectionTarget enum for the selection target

Returns
  0 on success or a negative error code otherwise

## ◆ streamOff()

int libcamera::V4L2VideoDevice::streamOff | ( |  | ) |

Stop the video stream.

Buffers that are still queued when the video stream is stopped are immediately dequeued with their status set to FrameMetadata::FrameCancelled, and the bufferReady signal is emitted for them. The order in which those buffers are dequeued is not specified.

This will be a no-op if the stream is not started in the first place and has no queued buffers.

Returns
  0 on success or a negative error code otherwise

## ◆ streamOn()

int libcamera::V4L2VideoDevice::streamOn | ( |  | ) |

Start the video stream.

Returns
  0 on success or a negative error code otherwise

## ◆ toV4L2PixelFormat()

V4L2PixelFormat libcamera::V4L2VideoDevice::toV4L2PixelFormat | ( | const PixelFormat & | pixelFormat | ) | const

Convert PixelFormat to a V4L2PixelFormat supported by the device.

Parameters

  [in] | pixelFormat | The PixelFormat to convert

Convert pixelformat to a V4L2 FourCC that is known to be supported by the video device.

A V4L2VideoDevice may support different V4L2 pixel formats that map the same PixelFormat. This is the case of the contiguous and non-contiguous variants of multiplanar formats, and with the V4L2 MJPEG and JPEG pixel formats. Converting a PixelFormat to a V4L2PixelFormat may thus have multiple answers.

This function converts the pixelFormat using the list of V4L2 pixel formats that the V4L2VideoDevice supports. This guarantees that the returned V4L2PixelFormat will be valid for the device. If multiple matches are still possible, contiguous variants are preferred. If the pixelFormat is not supported by the device, the function returns an invalid V4L2PixelFormat.

Returns
  The V4L2PixelFormat corresponding to pixelFormat if supported by the device, or an invalid V4L2PixelFormat otherwise

## ◆ tryFormat()

int libcamera::V4L2VideoDevice::tryFormat | ( | V4L2DeviceFormat * | format | ) |

Try an image format on the V4L2 video device.

Parameters

  [in,out] | format | The image format to test applicability to the video device

Try the supplied format on the video device without applying it, returning the format that would be applied. This is equivalent to setFormat(), except that the device configuration is not changed.

Returns
  0 on success or a negative error code otherwise

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

- include/libcamera/internal/v4l2_videodevice.h
- src/libcamera/v4l2_videodevice.cpp