libcamera: libcamera::CameraSensor Class Reference

libcamera v0.0.4 Supporting cameras in Linux since 2019

Loading...
Searching...
No Matches
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:
[legend]
Collaboration diagram for libcamera::CameraSensor:
[legend]

## Public Member Functions
| CameraSensor (const MediaEntity *entity)
| Construct a CameraSensor.
| ~CameraSensor ()
| Destroy a CameraSensor.
int | init ()
| Initialize the camera sensor instance.
const std::string & | model () const
| Retrieve the sensor model name.
const std::string & | id () const
| Retrieve the sensor ID.
const MediaEntity * | entity () const
| Retrieve the sensor media entity.
const std::vector< unsigned int > & | mbusCodes () const
| Retrieve the media bus codes supported by the camera sensor.
std::vector< Size > | sizes (unsigned int mbusCode) const
| Retrieve the supported frame sizes for a media bus code.
Size | resolution () const
| Retrieve the camera sensor resolution.
const std::vector< controls::draft::TestPatternModeEnum > & | testPatternModes () const
| Retrieve all the supported test pattern modes of the camera sensor The test pattern mode values correspond to the controls::TestPattern control.
int | setTestPatternMode (controls::draft::TestPatternModeEnum mode)
| Set the test pattern mode for the camera sensor.
V4L2SubdeviceFormat | getFormat (const std::vector< unsigned int > &mbusCodes, const Size &size) const
| Retrieve the best sensor format for a desired output.
int | setFormat (V4L2SubdeviceFormat *format)
| Set the sensor output format.
const ControlInfoMap & | controls () const
| Retrieve the supported V4L2 controls and their information.
ControlList | getControls (const std::vector< uint32_t > &ids)
| Read V4L2 controls from the sensor.
int | setControls (ControlList *ctrls)
| Write V4L2 controls to the sensor.
V4L2Subdevice * | device ()
| Retrieve the camera sensor device.
const ControlList & | properties () const
| Retrieve the camera sensor properties.
int | sensorInfo (IPACameraSensorInfo *info) const
| Assemble and return the camera sensor info.
void | updateControlInfo ()
| Update the sensor's ControlInfoMap in case they have changed.
CameraLens * | focusLens ()
| Retrieve the focus lens controller.
Transform | validateTransform (Transform *transform) const
| Validate a transform request against the sensor capabilities.

## Protected Member Functions
std::string | logPrefix () const override
| Retrieve a string to be prefixed to the log message.
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.

## 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] | entity | The 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.

Control information is updated automatically to reflect the current sensor configuration when the setFormat() function is called, without invalidating any iterator on the ControlInfoMap. A manual update can also be forced by calling the updateControlInfo() function for pipeline handlers that change the sensor configuration wihtout using setFormat().

Returns
  A map of the V4L2 controls supported by the sensor

## ◆ device()

libcamera::CameraSensor::device | ( |  | ) |
| inline

Retrieve the camera sensor device.

Todo:
  Remove this function by integrating DelayedControl with CameraSensor

Returns
  The camera sensor device

## ◆ entity()

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

Retrieve the sensor media entity.

Returns
  The sensor media entity

## ◆ focusLens()

libcamera::CameraSensor::focusLens | ( |  | ) |
| inline

Retrieve the focus lens controller.

Returns
  The focus lens controller. nullptr if no focus lens controller is connected to the sensor

## ◆ getControls()

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

Read V4L2 controls from the sensor.

Parameters

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

This function reads the value of all controls contained in ids, and returns their values as a ControlList. The control identifiers are defined by the V4L2 specification (V4L2_CID_*).

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.

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] | mbusCodes | The list of acceptable media bus codes
  [in] | size | The 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 function 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 function 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() function without any modification.

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

## ◆ id()

libcamera::CameraSensor::id | ( |  | ) | const
| inline

Retrieve the sensor ID.

The sensor ID is a free-form string that uniquely identifies the sensor in the system. The ID satisfies the requirements to be used as a camera ID.

Returns
  The sensor ID

## ◆ init()

int libcamera::CameraSensor::init | ( |  | ) |

Initialize the camera sensor instance.

This function 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 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.

## ◆ mbusCodes()

libcamera::CameraSensor::mbusCodes | ( |  | ) | const
| inline

Retrieve the media bus codes supported by the camera sensor.

Any Bayer formats are listed using the sensor's native Bayer order, that is, with the effect of V4L2_CID_HFLIP and V4L2_CID_VFLIP undone (where these controls exist).

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()

Size libcamera::CameraSensor::resolution | ( |  | ) | const

Retrieve the camera sensor resolution.

The camera sensor resolution is the active pixel area size, clamped to the maximum frame size the sensor can produce if it is smaller than the active pixel area.

Todo:
  Consider if it desirable to distinguish between the maximum resolution the sensor can produce (also including upscaled ones) and the actual pixel array size by splitting this function in two.

Returns
  The camera sensor resolution in pixels

## ◆ sensorInfo()

int libcamera::CameraSensor::sensorInfo | ( | IPACameraSensorInfo * | info | ) | const

Assemble and return the camera sensor info.

Parameters

  [out] | info | The camera sensor info

This function fills info with information that describes the camera sensor and its current configuration. The information combines static data (such as the the sensor model or active pixel array size) and data specific to the current sensor configuration (such as the line length and pixel rate).

Sensor information is only available for raw sensors. When called for a YUV sensor, this function returns -EINVAL.

Pipeline handlers that do not change the sensor format using the setFormat() function may need to call updateControlInfo() beforehand, to ensure all the control ranges are up to date.

Returns
  0 on success, a negative error code otherwise

## ◆ setControls()

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

Write V4L2 controls to the sensor.

Parameters

  [in] | ctrls | The list of controls to write

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. The control identifiers are defined by the V4L2 specification (V4L2_CID_*).

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 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.

See also
  V4L2Device::setControls()

Returns
  0 on success or an error code otherwise

Return values

  -EINVAL | One of the control is not supported or not accessible
  i | The index of the control that failed

## ◆ setFormat()

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

Set the sensor output format.

Parameters

  [in] | format | The desired sensor output format

If flips are writable they are configured according to the desired Transform. Transform::Identity always corresponds to H/V flip being disabled if the controls are writable. Flips are set before the new format is applied as they can effectively change the Bayer pattern ordering.

The ranges of any controls associated with the sensor are also updated.

Returns
  0 on success or a negative error code otherwise

## ◆ setTestPatternMode()

int libcamera::CameraSensor::setTestPatternMode | ( | controls::draft::TestPatternModeEnum | mode | ) |

Set the test pattern mode for the camera sensor.

Parameters

  [in] | mode | The test pattern mode

The new mode is applied to the sensor if it differs from the active test pattern mode. Otherwise, this function is a no-op. Setting the same test pattern mode for every frame thus incurs no performance penalty.

## ◆ sizes()

std::vector< Size > libcamera::CameraSensor::sizes | ( | unsigned int | mbusCode | ) | const

Retrieve the supported frame sizes for a media bus code.

Parameters

  [in] | mbusCode | The media bus code for which sizes are requested

Returns
  The supported frame sizes for mbusCode sorted in increasing order

## ◆ testPatternModes()

libcamera::CameraSensor::testPatternModes | ( |  | ) | const
| inline

Retrieve all the supported test pattern modes of the camera sensor The test pattern mode values correspond to the controls::TestPattern control.

Returns
  The list of test pattern modes

## ◆ updateControlInfo()

void libcamera::CameraSensor::updateControlInfo | ( |  | ) |

Update the sensor's ControlInfoMap in case they have changed.

See also
  V4L2Device::updateControlInfo()

## ◆ validateTransform()

Transform libcamera::CameraSensor::validateTransform | ( | Transform * | transform | ) | const

Validate a transform request against the sensor capabilities.

Parameters

  [in,out] | transform | The requested transformation, updated to match the sensor capabilities

The input transform is the transform that the caller wants, and it is adjusted according to the capabilities of the sensor to represent the "nearest" transform that can actually be delivered.

The returned Transform is the transform applied to the sensor in order to produce the input transform, It is also validated against the sensor's ability to perform horizontal and vertical flips.

For example, if the requested transform is Transform::Identity and the sensor rotation is 180 degrees, the output transform will be Transform::Rot180 to correct the images so that they appear to have Transform::Identity, but only if the sensor can apply horizontal and vertical flips.

Returns
  A Transform instance that represents which transformation has been applied to the camera sensor

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

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