libcamera  v0.3.0
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:
Inheritance graph
[legend]
Collaboration diagram for libcamera::V4L2VideoDevice:
Collaboration graph
[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 V4L2Capabilitycaps () 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 ControlInfoMapcontrols () 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< V4L2VideoDevicefromEntityName (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< ColorSpacetoColorSpace (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 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]deviceNodeThe 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]entityThe 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]countNumber of buffers to allocate
[out]buffersVector 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
-EBUSYbuffers 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]countNumber of buffers to allocate
[out]buffersVector 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
-EBUSYbuffers 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]codeRestrict 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]mediaThe media device where the entity is registered
[in]entityThe 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]formatThe 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]countNumber 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
-EBUSYbuffers 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]handleThe file descriptor to set
[in]typeThe 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]bufferThe 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]timeoutThe 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]formatThe 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]targetThe selection target defined by the V4L2_SEL_TGT_* flags
[in,out]rectThe 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]pixelFormatThe 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]formatThe 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: