libcamera  v0.2.0+85-1c5830a9
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:
Inheritance graph
[legend]
Collaboration diagram for libcamera::V4L2Subdevice:
Collaboration graph
[legend]

Classes

class  Route
 V4L2 subdevice routing table entry. More...
 
class  Stream
 V4L2 subdevice stream. 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.
 
using Routing = std::vector< Route >
 V4L2 subdevice routing table. More...
 

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 MediaEntityentity () const
 Retrieve the media entity associated with the subdevice. More...
 
int getSelection (const Stream &stream, unsigned int target, Rectangle *rect)
 Get selection rectangle rect for target. More...
 
int getSelection (unsigned int pad, unsigned int target, Rectangle *rect)
 Get selection rectangle rect for target. More...
 
int setSelection (const Stream &stream, unsigned int target, Rectangle *rect)
 Set 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 (const Stream &stream)
 Enumerate all media bus codes and frame sizes on a stream. More...
 
Formats formats (unsigned int pad)
 Enumerate all media bus codes and frame sizes on a pad. More...
 
int getFormat (const Stream &stream, V4L2SubdeviceFormat *format, Whence whence=ActiveFormat)
 Retrieve the image format set on one of the V4L2 subdevice streams. 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 (const Stream &stream, V4L2SubdeviceFormat *format, Whence whence=ActiveFormat)
 Set an image format 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 V4L2SubdeviceCapabilitycaps () 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 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< V4L2SubdevicefromEntityName (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
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< 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

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

◆ Routing

V4L2 subdevice routing table.

This class stores a subdevice routing table as a vector of routes.

Member Enumeration Documentation

◆ 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() [1/2]

V4L2Subdevice::Formats libcamera::V4L2Subdevice::formats ( const Stream stream)

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

Parameters
[in]streamThe stream to enumerate formats for

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

Returns
A list of the supported device formats

◆ formats() [2/2]

libcamera::V4L2Subdevice::formats ( unsigned int  pad)
inline

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

Parameters
[in]padThe 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]mediaThe media device where the entity is registered
[in]entityThe media entity name
Returns
A newly created V4L2Subdevice on success, nullptr otherwise

◆ getFormat() [1/2]

int libcamera::V4L2Subdevice::getFormat ( const Stream stream,
V4L2SubdeviceFormat format,
Whence  whence = ActiveFormat 
)

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

Parameters
[in]streamThe stream the format is to be retrieved from
[out]formatThe image bus format
[in]whenceThe format to get, ActiveFormat or TryFormat
Returns
0 on success or a negative error code otherwise

◆ getFormat() [2/2]

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

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

Parameters
[in]padThe 0-indexed pad number the format is to be retrieved from
[out]formatThe image bus format
[in]whenceThe 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]routingThe routing table
[in]whenceThe routing table to get, ActiveFormat or TryFormat
Returns
0 on success or a negative error code otherwise

◆ getSelection() [1/2]

int libcamera::V4L2Subdevice::getSelection ( const Stream stream,
unsigned int  target,
Rectangle rect 
)

Get selection rectangle rect for target.

Parameters
[in]streamThe stream the rectangle is retrieved from
[in]targetThe selection target defined by the V4L2_SEL_TGT_* flags
[out]rectThe retrieved selection rectangle
Todo:
Define a V4L2SelectionTarget enum for the selection target
Returns
0 on success or a negative error code otherwise

◆ getSelection() [2/2]

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

Get selection rectangle rect for target.

Parameters
[in]padThe 0-indexed pad number the rectangle is retrieved from
[in]targetThe selection target defined by the V4L2_SEL_TGT_* flags
[out]rectThe retrieved selection rectangle
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() [1/2]

int libcamera::V4L2Subdevice::setFormat ( const Stream stream,
V4L2SubdeviceFormat format,
Whence  whence = ActiveFormat 
)

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

Parameters
[in]streamThe stream the format is to be applied to
[in,out]formatThe image bus format to apply to the stream
[in]whenceThe format to set, ActiveFormat or TryFormat

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

Returns
0 on success or a negative error code otherwise

◆ setFormat() [2/2]

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

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

Parameters
[in]padThe 0-indexed pad number the format is to be applied to
[in,out]formatThe image bus format to apply to the subdevice's pad
[in]whenceThe 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]routingThe routing table
[in]whenceThe 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() [1/2]

int libcamera::V4L2Subdevice::setSelection ( const Stream stream,
unsigned int  target,
Rectangle rect 
)

Set selection rectangle rect for target.

Parameters
[in]streamThe stream the rectangle is to be applied to
[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

◆ setSelection() [2/2]

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

Set selection rectangle rect for target.

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

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