libcamera  v0.0.0
Supporting cameras in Linux since 2019
Public Member Functions | Protected Member Functions | List of all members
libcamera::CameraSensor Class Reference

A camera sensor based on V4L2 subdevices. More...

Inheritance diagram for libcamera::CameraSensor:
libcamera::Loggable

Public Member Functions

 CameraSensor (const MediaEntity *entity)
 Construct a CameraSensor. More...
 
 ~CameraSensor ()
 Destroy a CameraSensor.
 
 CameraSensor (const CameraSensor &)=delete
 
CameraSensoroperator= (const CameraSensor &)=delete
 
int init ()
 Initialize the camera sensor instance. More...
 
const std::string & model () const
 Retrieve the sensor model name. More...
 
const MediaEntityentity () const
 Retrieve the sensor media entity. More...
 
const std::vector< unsigned int > & mbusCodes () const
 Retrieve the media bus codes supported by the camera sensor. More...
 
const std::vector< Size > & sizes () const
 Retrieve the frame sizes supported by the camera sensor. More...
 
const Sizeresolution () const
 Retrieve the camera sensor resolution. More...
 
V4L2SubdeviceFormat getFormat (const std::vector< unsigned int > &mbusCodes, const Size &size) const
 Retrieve the best sensor format for a desired output. More...
 
int setFormat (V4L2SubdeviceFormat *format)
 Set the sensor output format. 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 sensor. More...
 
int setControls (ControlList *ctrls)
 Write controls to the sensor. More...
 
const ControlListproperties () const
 Retrieve the camera sensor properties. More...
 
int sensorInfo (CameraSensorInfo *info) const
 Assemble and return the camera sensor info. 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::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

A camera sensor based on V4L2 subdevices.

The CameraSensor class eases handling of sensors for pipeline handlers by hiding the details of the V4L2 subdevice kernel API and caching sensor information.

The implementation is currently limited to sensors that expose a single V4L2 subdevice with a single pad. It will be extended to support more complex devices as the needs arise.

Constructor & Destructor Documentation

◆ CameraSensor()

libcamera::CameraSensor::CameraSensor ( const MediaEntity entity)
explicit

Construct a CameraSensor.

Parameters
[in]entityThe media entity backing the camera sensor

Once constructed the instance must be initialized with init().

Member Function Documentation

◆ controls()

const ControlInfoMap & libcamera::CameraSensor::controls ( ) const

Retrieve the supported V4L2 controls and their information.

Returns
A map of the V4L2 controls supported by the sensor

◆ entity()

libcamera::CameraSensor::entity ( ) const
inline

Retrieve the sensor media entity.

Returns
The sensor media entity

◆ getControls()

ControlList libcamera::CameraSensor::getControls ( const std::vector< uint32_t > &  ids)

Read controls from the sensor.

Parameters
[in]idsThe list of controls to read, specified by their ID

This method 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 method returns an empty control list.

See also
V4L2Device::getControls()
Returns
The control values in a ControlList on success, or an empty list on error

◆ getFormat()

V4L2SubdeviceFormat libcamera::CameraSensor::getFormat ( const std::vector< unsigned int > &  mbusCodes,
const Size size 
) const

Retrieve the best sensor format for a desired output.

Parameters
[in]mbusCodesThe list of acceptable media bus codes
[in]sizeThe desired size

Media bus codes are selected from mbusCodes, which lists all acceptable codes in decreasing order of preference. Media bus codes supported by the sensor but not listed in mbusCodes are ignored. If none of the desired codes is supported, it returns an error.

size indicates the desired size at the output of the sensor. This method selects the best media bus code and size supported by the sensor according to the following criteria.

  • The desired size shall fit in the sensor output size to avoid the need to up-scale.
  • The sensor output size shall match the desired aspect ratio to avoid the need to crop the field of view.
  • The sensor output size shall be as small as possible to lower the required bandwidth.
  • The desired size shall be supported by one of the media bus code listed in mbusCodes.

When multiple media bus codes can produce the same size, the code at the lowest position in mbusCodes is selected.

The use of this method is optional, as the above criteria may not match the needs of all pipeline handlers. Pipeline handlers may implement custom sensor format selection when needed.

The returned sensor output format is guaranteed to be acceptable by the setFormat() method without any modification.

Returns
The best sensor output format matching the desired media bus codes and size on success, or an empty format otherwise.

◆ init()

int libcamera::CameraSensor::init ( )

Initialize the camera sensor instance.

This method performs the initialisation steps of the CameraSensor that may fail. It shall be called once and only once after constructing the instance.

Returns
0 on success or a negative error code otherwise

◆ logPrefix()

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

◆ mbusCodes()

libcamera::CameraSensor::mbusCodes ( ) const
inline

Retrieve the media bus codes supported by the camera sensor.

Returns
The supported media bus codes sorted in increasing order

◆ model()

libcamera::CameraSensor::model ( ) const
inline

Retrieve the sensor model name.

The sensor model name is a free-formed string that uniquely identifies the sensor model.

Returns
The sensor model name

◆ properties()

libcamera::CameraSensor::properties ( ) const
inline

Retrieve the camera sensor properties.

Returns
The list of camera sensor properties

◆ resolution()

libcamera::CameraSensor::resolution ( ) const
inline

Retrieve the camera sensor resolution.

Returns
The camera sensor resolution in pixels

◆ sensorInfo()

int libcamera::CameraSensor::sensorInfo ( CameraSensorInfo info) const

Assemble and return the camera sensor info.

Parameters
[out]infoThe camera sensor info

The CameraSensorInfo content is assembled by inspecting the currently applied sensor configuration and the sensor static properties.

Returns
0 on success, a negative error code otherwise

◆ setControls()

int libcamera::CameraSensor::setControls ( ControlList ctrls)

Write controls to the sensor.

Parameters
[in]ctrlsThe list of controls to write

This method 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, or if any other error occurs during validation of the requested controls, no control is written and this method 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.

See also
V4L2Device::setControls()
Returns
0 on success or an error code otherwise
Return values
-EINVALOne of the control is not supported or not accessible
iThe index of the control that failed

◆ setFormat()

int libcamera::CameraSensor::setFormat ( V4L2SubdeviceFormat format)

Set the sensor output format.

Parameters
[in]formatThe desired sensor output format
Returns
0 on success or a negative error code otherwise

◆ sizes()

libcamera::CameraSensor::sizes ( ) const
inline

Retrieve the frame sizes supported by the camera sensor.

The reported sizes span all media bus codes supported by the camera sensor. Not all sizes may be supported by all media bus codes.

Returns
The supported frame sizes sorted in increasing order

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