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

Inheritance diagram for libcamera::V4L2Subdevice:

Collaboration diagram for libcamera::V4L2Subdevice:

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 MediaEntity *	entity () 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 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
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 Typedef Documentation

◆ Routing

libcamera::V4L2Subdevice::Routing

V4L2 subdevice routing table.

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

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

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

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

Parameters

[in] stream The 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] 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() [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]	stream	The stream 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

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

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

Get selection rectangle rect for target.

Parameters

[in]	stream	The stream 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

◆ getSelection() [2/2]

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

inline

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

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]	stream	The stream the format is to be applied to
[in,out]	format	The image bus format to apply to the stream
[in]	whence	The 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]	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() [1/2]

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

Set selection rectangle rect for target.

Parameters

[in]	stream	The stream 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

◆ setSelection() [2/2]

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

inline

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

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ Routing

Member Enumeration Documentation

◆ Whence

Member Function Documentation

◆ caps()

◆ entity()

◆ formats() [1/2]

◆ formats() [2/2]

◆ fromEntityName()

◆ getFormat() [1/2]

◆ getFormat() [2/2]

◆ getRouting()

◆ getSelection() [1/2]

◆ getSelection() [2/2]

◆ logPrefix()

◆ model()

◆ open()

◆ setFormat() [1/2]

◆ setFormat() [2/2]

◆ setRouting()

◆ setSelection() [1/2]

◆ setSelection() [2/2]