Inheritance diagram for libcamera::V4L2VideoDevice:

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
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

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ V4L2VideoDevice() [1/2]

◆ V4L2VideoDevice() [2/2]

Member Function Documentation

◆ allocateBuffers()

◆ busName()

◆ caps()

◆ deviceName()

◆ driverName()

◆ exportBuffers()

◆ formats()

◆ fromEntityName()

◆ getFormat()

◆ importBuffers()

◆ logPrefix()

◆ open() [1/2]

◆ open() [2/2]

◆ queueBuffer()

◆ releaseBuffers()

◆ setDequeueTimeout()

◆ setFormat()

◆ setSelection()

◆ streamOff()

◆ streamOn()

◆ toV4L2PixelFormat()

◆ tryFormat()