libcamera: libcamera::V4L2Device Class Reference

libcamera v0.7.0 Supporting cameras in Linux since 2019

Loading...
Searching...
No Matches
libcamera::V4L2Device Class Reference

Base class for V4L2VideoDevice and V4L2Subdevice. More...

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

## Public Member Functions
void | close ()
| Close the device node.
bool | isOpen () const
| Check if the V4L2 device node is open.
const ControlInfoMap & | controls () const
| Retrieve the supported V4L2 controls and their information.
ControlList | getControls (Span< const uint32_t > ids, const V4L2Request *request=nullptr)
| Read controls from the device.
int | setControls (ControlList *ctrls, const V4L2Request *request=nullptr)
| Write controls to the device.
const struct v4l2_query_ext_ctrl * | controlInfo (uint32_t id) const
| Retrieve the v4l2_query_ext_ctrl information for the given control.
const std::string & | deviceNode () const
| Retrieve the device node path.
std::string | devicePath () const
| Retrieve the device path in sysfs.
bool | supportsFrameStartEvent ()
| Check if frame start event is supported.
int | setFrameStartEnabled (bool enable)
| Enable or disable frame start event notification.
void | updateControlInfo ()
| Update the information for all device controls.

## Public Attributes
Signal< uint32_t > | frameStart
| A Signal emitted when capture of a frame has started.

## Protected Member Functions
| V4L2Device (const std::string &deviceNode)
| Construct a V4L2Device.
| ~V4L2Device ()
| Destroy a V4L2Device.
int | open (unsigned int flags)
| Open a V4L2 device node.
int | setFd (UniqueFD fd)
| Set the file descriptor of a V4L2 device.
int | ioctl (unsigned long request, void *argp)
| Perform an IOCTL system call on the device node.
int | fd () const
| Retrieve the V4L2 device file descriptor.
Protected Member Functions inherited from libcamera::Loggable
virtual std::string | logPrefix () const =0
| Retrieve a string to be prefixed to the log message.
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.

## Static Protected Member Functions
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.
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.

## Detailed Description

Base class for V4L2VideoDevice and V4L2Subdevice.

The V4L2Device class groups together the functions and fields common to both the V4L2VideoDevice and V4L2Subdevice classes, and provides a base class with functions to open and close the device node associated with the device and to perform IOCTL system calls on it.

The V4L2Device class cannot be instantiated directly, as its constructor is protected. Users should instead create instances of one the derived classes to model either a V4L2 video device or a V4L2 subdevice.

## Constructor & Destructor Documentation

## ◆ V4L2Device()

libcamera::V4L2Device::V4L2Device | ( | const std::string & | deviceNode | ) |
| protected

Construct a V4L2Device.

Parameters

  [in] | deviceNode | The device node filesystem path

Initialize the file descriptor to -1 and store the deviceNode to be used at open() time, and the logTag to prefix log messages with.

## Member Function Documentation

## ◆ close()

void libcamera::V4L2Device::close | ( |  | ) |

Close the device node.

Reset the file descriptor to -1

## ◆ controlInfo()

const struct v4l2_query_ext_ctrl * libcamera::V4L2Device::controlInfo | ( | uint32_t | id | ) | const

Retrieve the v4l2_query_ext_ctrl information for the given control.

Parameters

  [in] | id | The V4L2 control id

Returns
  A pointer to the v4l2_query_ext_ctrl structure for the given control, or a null pointer if not found

## ◆ controls()

const ControlInfoMap & libcamera::V4L2Device::controls | ( |  | ) | const
| inline

Retrieve the supported V4L2 controls and their information.

Returns
  A map of the V4L2 controls supported by the device

## ◆ deviceNode()

const std::string & libcamera::V4L2Device::deviceNode | ( |  | ) | const
| inline

Retrieve the device node path.

Returns
  The device node path

## ◆ devicePath()

std::string libcamera::V4L2Device::devicePath | ( |  | ) | const

Retrieve the device path in sysfs.

This function returns the sysfs path to the physical device backing the V4L2 device. The path is guaranteed to be an absolute path, without any symbolic link.

It includes the sysfs mount point prefix

Returns
  The device path in sysfs

## ◆ fd()

int libcamera::V4L2Device::fd | ( |  | ) | const
| inlineprotected

Retrieve the V4L2 device file descriptor.

Returns
  The V4L2 device file descriptor, -1 if the device node is not open

## ◆ fromColorSpace()

template<typename T>

template int libcamera::V4L2Device::fromColorSpace | ( | const std::optional< ColorSpace > & | colorSpace,
|  | T & | v4l2Format )
| staticprotected

Fill in the color space fields of a V4L2 format from a ColorSpace.

Parameters

  [in] | colorSpace | The ColorSpace to be converted
  [out] | v4l2Format | A V4L2 format containing color space information

The colorspace, ycbcr_enc, xfer_func and quantization fields within a V4L2 format structure are filled in from a corresponding ColorSpace.

An error is returned if any of the V4L2 fields do not support the value given in the ColorSpace. Such fields are set to the V4L2 "default" values, but all other fields are still filled in where possible.

If the color space is completely unset, "default" V4L2 values are used everywhere, so a driver would then choose its preferred color space.

Returns
  0 on success or a negative error code otherwise

Return values

  -EINVAL | The ColorSpace does not have a representation using V4L2 enums

## ◆ getControls()

ControlList libcamera::V4L2Device::getControls | ( | Span< const uint32_t > | ids,
|  | const V4L2Request * | request = nullptr )

Read controls from the device.

Parameters

  [in] | ids | The list of controls to read, specified by their ID
  [in] | request | An optional request

This function reads the value of all controls contained in ids, and returns their values as a ControlList.

If any control in ids is not supported by the device, is disabled (i.e. has the V4L2_CTRL_FLAG_DISABLED flag set), or if any other error occurs during validation of the requested controls, no control is read and this function returns an empty control list.

If request is specified the controls tied to that request are read.

Returns
  The control values in a ControlList on success, or an empty list on error

## ◆ ioctl()

int libcamera::V4L2Device::ioctl | ( | unsigned long | request,
|  | void * | argp )
| protected

Perform an IOCTL system call on the device node.

Parameters

  [in] | request | The IOCTL request code
  [in] | argp | A pointer to the IOCTL argument

Returns
  0 on success or a negative error code otherwise

## ◆ isOpen()

bool libcamera::V4L2Device::isOpen | ( |  | ) | const
| inline

Check if the V4L2 device node is open.

Returns
  True if the V4L2 device node is open, false otherwise

## ◆ open()

int libcamera::V4L2Device::open | ( | unsigned int | flags | ) |
| protected

Open a V4L2 device node.

Parameters

  [in] | flags | Access mode flags

Open the device node path with the provided access mode flags and initialize the file descriptor, which was initially set to -1.

Returns
  0 on success or a negative error code otherwise

## ◆ setControls()

int libcamera::V4L2Device::setControls | ( | ControlList * | ctrls,
|  | const V4L2Request * | request = nullptr )

Write controls to the device.

Parameters

  [in] | ctrls | The list of controls to write
  [in] | request | An optional request

This function writes the value of all controls contained in ctrls, and stores the values actually applied to the device in the corresponding ctrls entry.

If any control in ctrls is not supported by the device, is disabled (i.e. has the V4L2_CTRL_FLAG_DISABLED flag set), is read-only, if any other error occurs during validation of the requested controls, no control is written and this function returns -EINVAL.

If an error occurs while writing the controls, the index of the first control that couldn't be written is returned. All controls below that index are written and their values are updated in ctrls, while all other controls are not written and their values are not changed.

If request is set, the controls will be applied to that request. If the device doesn't support requests, -EACCESS will be returned. If request is invalid, -EINVAL will be returned.

Returns
  0 on success or an error code otherwise

Return values

  -EINVAL | One of the controls is not supported or not accessible
  -EACCESS | The device does not support requests
  i | The index of the control that failed

## ◆ setFd()

int libcamera::V4L2Device::setFd | ( | UniqueFD | fd | ) |
| protected

Set the file descriptor of a V4L2 device.

Parameters

  [in] | fd | The file descriptor handle

This function allows a device to provide an already opened file descriptor referring to the V4L2 device node, instead of opening it with open(). This can be used for V4L2 M2M devices where a single video device node is used for both the output and capture devices, or when receiving an open file descriptor in a context that doesn't have permission to open the device node itself.

This function and the open() function are mutually exclusive, only one of the two shall be used for a V4L2Device instance.

Returns
  0 on success or a negative error code otherwise

## ◆ setFrameStartEnabled()

int libcamera::V4L2Device::setFrameStartEnabled | ( | bool | enable | ) |

Enable or disable frame start event notification.

Parameters

  [in] | enable | True 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

## ◆ supportsFrameStartEvent()

bool libcamera::V4L2Device::supportsFrameStartEvent | ( |  | ) |

Check if frame start event is supported.

Due to limitations in the kernel API, this function may disable the frame start event as a side effect. It should only be called during initialization, before enabling the frame start event with setFrameStartEnabled().

Returns
  True if frame start event is supported, false otherwise

## ◆ toColorSpace()

template<typename T>

template std::optional< ColorSpace > libcamera::V4L2Device::toColorSpace | ( | const T & | v4l2Format,
|  | PixelFormatInfo::ColourEncoding | colourEncoding )
| staticprotected

Convert the color space fields in a V4L2 format to a ColorSpace.

Parameters

  [in] | v4l2Format | A V4L2 format containing color space information
  [in] | colourEncoding | Type of colour encoding

The colorspace, ycbcr_enc, xfer_func and quantization fields within a V4L2 format structure are converted to a corresponding ColorSpace.

If any V4L2 fields are not recognised then we return an "unset" color space.

Returns
  The ColorSpace corresponding to the input V4L2 format

Return values

  std::nullopt | One or more V4L2 color space fields were not recognised

## ◆ updateControlInfo()

void libcamera::V4L2Device::updateControlInfo | ( |  | ) |

Update the information for all device controls.

The V4L2Device class caches information about all controls supported by the device and exposes it through the controls() and controlInfo() functions. Control information may change at runtime, for instance when formats on a subdev are modified. When this occurs, this function can be used to refresh control information. The information is refreshed in-place, all pointers to v4l2_query_ext_ctrl instances previously returned by controlInfo() and iterators to the ControlInfoMap returned by controls() remain valid.

Note that control information isn't refreshed automatically is it may be an expensive operation. The V4L2Device users are responsible for calling this function when required, based on their usage pattern of the class.

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

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