libcamera: libcamera::V4L2Subdevice Class Reference

libcamera v0.0.1 Supporting cameras in Linux since 2019

Classes | Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
libcamera::V4L2Subdevice Class Reference

A V4L2 subdevice as exposed by the Linux kernel. More...

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

## Classes
class | Routing
| V4L2 subdevice routing table. More...

## Public Types
enum | Whence { TryFormat = V4L2_SUBDEV_FORMAT_TRY , ActiveFormat = V4L2_SUBDEV_FORMAT_ACTIVE }
| Specify the type of format for getFormat() and setFormat() operations. More...
using | Formats = std::map< unsigned int, std::vector< SizeRange > >
| A map of supported media bus formats to frame sizes.

## Public Member Functions
| V4L2Subdevice (const MediaEntity *entity)
| Create a V4L2 subdevice from a MediaEntity using its device node path.
int | open ()
| Open a V4L2 subdevice. More...
const MediaEntity * | entity () const
| Retrieve the media entity associated with the subdevice. More...
int | getSelection (unsigned int pad, unsigned int target, Rectangle *rect)
| Get selection rectangle rect for target. More...
int | setSelection (unsigned int pad, unsigned int target, Rectangle *rect)
| Set selection rectangle rect for target. More...
Formats | formats (unsigned int pad)
| Enumerate all media bus codes and frame sizes on a pad. More...
int | getFormat (unsigned int pad, V4L2SubdeviceFormat *format, Whence whence=ActiveFormat)
| Retrieve the image format set on one of the V4L2 subdevice pads. More...
int | setFormat (unsigned int pad, V4L2SubdeviceFormat *format, Whence whence=ActiveFormat)
| Set an image format on one of the V4L2 subdevice pads. More...
int | getRouting (Routing *routing, Whence whence=ActiveFormat)
| Retrieve the subdevice's internal routing table. More...
int | setRouting (Routing *routing, Whence whence=ActiveFormat)
| Set a routing table on the V4L2 subdevice. More...
const std::string & | model ()
| Retrieve the model name of the device. More...
const V4L2SubdeviceCapability & | caps () const
| Retrieve the subdevice V4L2 capabilities. 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< V4L2Subdevice > | fromEntityName (const MediaDevice *media, const std::string &entity)
| Create a new video subdevice instance from entity in media device media. More...

## 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
Public Attributes inherited from libcamera::V4L2Device
Signal< uint32_t > | frameStart
| A Signal emitted when capture of a frame has started.
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

A V4L2 subdevice as exposed by the Linux kernel.

The V4L2Subdevice class provides an API to the "Sub-device interface" as described in section 4.15 of the "Linux Media Infrastructure userspace API" chapter of the Linux Kernel documentation.

A V4L2Subdevice is constructed from a MediaEntity instance, using the system path of the entity's device node. No API call other than open(), isOpen() and close() shall be called on an unopened device instance. Upon destruction any device left open will be closed, and any resources released.

## Member Enumeration Documentation

## ◆ Whence

enum libcamera::V4L2Subdevice::Whence

Specify the type of format for getFormat() and setFormat() operations.

Enumerator
TryFormat | The format operation applies to TRY formats.
ActiveFormat | The format operation applies to ACTIVE formats.

## Member Function Documentation

## ◆ caps()

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

Retrieve the subdevice V4L2 capabilities.

Returns
  The subdevice V4L2 capabilities

## ◆ entity()

libcamera::V4L2Subdevice::entity | ( |  | ) | const
| inline

Retrieve the media entity associated with the subdevice.

Returns
  The subdevice's associated media entity.

## ◆ formats()

V4L2Subdevice::Formats libcamera::V4L2Subdevice::formats | ( | unsigned int | pad | ) |

Enumerate all media bus codes and frame sizes on a pad.

Parameters

  [in] | pad | The 0-indexed pad number to enumerate formats on

Enumerate all media bus codes and frame sizes supported by the subdevice on a pad.

Returns
  A list of the supported device formats

## ◆ fromEntityName()

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

Create a new video subdevice 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 V4L2Subdevice on success, nullptr otherwise

## ◆ getFormat()

int libcamera::V4L2Subdevice::getFormat | ( | unsigned int | pad,
|  | V4L2SubdeviceFormat * | format,
|  | Whence | whence = `ActiveFormat`
| ) |  |

Retrieve the image format set on one of the V4L2 subdevice pads.

Parameters

  [in] | pad | The 0-indexed pad number the format is to be retrieved from
  [out] | format | The image bus format
  [in] | whence | The format to get, ActiveFormat or TryFormat

Returns
  0 on success or a negative error code otherwise

## ◆ getRouting()

int libcamera::V4L2Subdevice::getRouting | ( | Routing * | routing,
|  | Whence | whence = `ActiveFormat`
| ) |  |

Retrieve the subdevice's internal routing table.

Parameters

  [out] | routing | The routing table
  [in] | whence | The routing table to get, ActiveFormat or TryFormat

Returns
  0 on success or a negative error code otherwise

## ◆ getSelection()

int libcamera::V4L2Subdevice::getSelection | ( | unsigned int | pad,
|  | unsigned int | target,
|  | Rectangle * | rect
| ) |  |

Get selection rectangle rect for target.

Parameters

  [in] | pad | The 0-indexed pad number the rectangle is retrieved from
  [in] | target | The selection target defined by the V4L2_SEL_TGT_* flags
  [out] | rect | The retrieved selection rectangle

Todo:
  Define a V4L2SelectionTarget enum for the selection target

Returns
  0 on success or a negative error code otherwise

## ◆ logPrefix()

std::string libcamera::V4L2Subdevice::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.

## ◆ model()

const std::string & libcamera::V4L2Subdevice::model | ( |  | ) |

Retrieve the model name of the device.

The model name allows identification of the specific device model. This can be used to infer device characteristics, for instance to determine the analogue gain model of a camera sensor based on the sensor model name.

Neither the V4L2 API nor the Media Controller API expose an explicit model name. This function implements a heuristics to extract the model name from the subdevice's entity name. This should produce accurate results for I2C-based devices. If the heuristics can't match a known naming pattern, the function returns the full entity name.

Returns
  The model name of the device

## ◆ open()

int libcamera::V4L2Subdevice::open | ( |  | ) |

Open a V4L2 subdevice.

Returns
  0 on success or a negative error code otherwise

## ◆ setFormat()

int libcamera::V4L2Subdevice::setFormat | ( | unsigned int | pad,
|  | V4L2SubdeviceFormat * | format,
|  | Whence | whence = `ActiveFormat`
| ) |  |

Set an image format on one of the V4L2 subdevice pads.

Parameters

  [in] | pad | The 0-indexed pad number the format is to be applied to
  [in,out] | format | The image bus format to apply to the subdevice's pad
  [in] | whence | The format to set, ActiveFormat or TryFormat

Apply the requested image format to the desired media pad and return the actually applied format parameters, as getFormat() would do.

Returns
  0 on success or a negative error code otherwise

## ◆ setRouting()

int libcamera::V4L2Subdevice::setRouting | ( | Routing * | routing,
|  | Whence | whence = `ActiveFormat`
| ) |  |

Set a routing table on the V4L2 subdevice.

Parameters

  [in,out] | routing | The routing table
  [in] | whence | The routing table to set, ActiveFormat or TryFormat

Apply to the V4L2 subdevice the routing table routing and update its content to reflect the actually applied routing table as getRouting() would do.

Returns
  0 on success or a negative error code otherwise

## ◆ setSelection()

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

Set selection rectangle rect for target.

Parameters

  [in] | pad | The 0-indexed pad number the rectangle is to be applied to
  [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

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

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