libcamera  v0.0.0
Supporting cameras in Linux since 2019
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:
libcamera::V4L2Device libcamera::Loggable

Public Member Functions

 V4L2VideoDevice (const std::string &deviceNode)
 Construct a V4L2VideoDevice. More...
 
 V4L2VideoDevice (const MediaEntity *entity)
 Construct a V4L2VideoDevice from a MediaEntity. More...
 
 V4L2VideoDevice (const V4L2VideoDevice &)=delete
 
V4L2VideoDeviceoperator= (const V4L2VideoDevice &)=delete
 
int open ()
 Open the V4L2 video device node and query its capabilities. More...
 
int open (int 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 setFormat (V4L2DeviceFormat *format)
 Configure an image format on the V4L2 video device. More...
 
std::map< V4L2PixelFormat, std::vector< SizeRange > > 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 setFrameStartEnabled (bool enable)
 Enable or disable frame start event notification. More...
 
int streamOn ()
 Start the video stream. More...
 
int streamOff ()
 Stop the video stream. More...
 
V4L2PixelFormat toV4L2PixelFormat (const PixelFormat &pixelFormat)
 Convert PixelFormat to its corresponding V4L2 FourCC. 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 std::string & deviceNode () const
 Retrieve the device node path. More...
 

Static Public Member Functions

static 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< 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 (int 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 ()
 Retrieve the V4L2 device file descriptor. More...
 
- Protected Member Functions inherited from libcamera::Loggable
LogMessage _log (const char *file, unsigned int line, LogSeverity severity) const
 Create a temporary LogMessage object to log a message. More...
 
LogMessage _log (const char *file, unsigned int line, const LogCategory &category, LogSeverity severity) const
 Create a temporary LogMessage object to log a message. 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 the plane sizes for the allocation are determined by the currently active format on the device as set by setFormat().

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 the plane sizes for the allocation are determined by the currently active format on the device as set by setFormat().

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

std::map< V4L2PixelFormat, std::vector< SizeRange > > 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()

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

Releasing memory of the newly created instance is responsibility of the caller of this function.

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 method 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 ( int  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 methods opens a video device from the existing file descriptor handle. Like open(), this method 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, and the caller is responsible for closing the handle when it has no further use for it. The close() method will close the duplicated file descriptor, leaving handle untouched.

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.

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.

◆ 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

◆ setFrameStartEnabled()

int libcamera::V4L2VideoDevice::setFrameStartEnabled ( bool  enable)

Enable or disable frame start event notification.

Parameters
[in]enableTrue to enable frame start events, false to disable them

This function enables or disables generation of frame start events. Once enabled, the events are signalled through the frameStart signal.

Returns
0 on success, 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.

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)

Convert PixelFormat to its corresponding V4L2 FourCC.

Parameters
[in]pixelFormatThe PixelFormat to convert

For multiplanar formats, the V4L2 format variant (contiguous or non-contiguous planes) is selected automatically based on the capabilities of the video device. If the video device supports the V4L2 multiplanar API, non-contiguous formats are preferred.

Returns
The V4L2_PIX_FMT_* pixel format code corresponding to pixelFormat

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