libcamera: libcamera::CameraSensor Class Reference

libcamera v0.7.0 Supporting cameras in Linux since 2019

Loading...
Searching...
No Matches
libcamera::CameraSensor Class Referenceabstract

A abstract camera sensor. More...

## Public Member Functions
virtual | ~CameraSensor ()
| Destroy a CameraSensor.
virtual const std::string & | model () const =0
| Retrieve the sensor model name.
virtual const std::string & | id () const =0
| Retrieve the sensor ID.
virtual const MediaEntity * | entity () const =0
| Retrieve the sensor media entity.
virtual V4L2Subdevice * | device ()=0
| Retrieve the camera sensor device.
virtual CameraLens * | focusLens ()=0
| Retrieve the focus lens controller.
virtual const std::vector< unsigned int > & | mbusCodes () const =0
| Retrieve the media bus codes supported by the camera sensor.
virtual std::vector< Size > | sizes (unsigned int mbusCode) const =0
| Retrieve the supported frame sizes for a media bus code.
virtual Size | resolution () const =0
| Retrieve the camera sensor resolution.
virtual V4L2SubdeviceFormat | getFormat (Span< const unsigned int > mbusCodes, const Size &size, const Size maxSize=Size()) const =0
| Retrieve the best sensor format for a desired output.
virtual int | setFormat (V4L2SubdeviceFormat *format, Transform transform=Transform::Identity)=0
| Set the sensor output format.
virtual int | tryFormat (V4L2SubdeviceFormat *format) const =0
| Try the sensor output format.
virtual int | applyConfiguration (const SensorConfiguration &config, Transform transform=Transform::Identity, V4L2SubdeviceFormat *sensorFormat=nullptr)=0
| Apply a sensor configuration to the camera sensor.
virtual V4L2Subdevice::Stream | imageStream () const
| Retrieve the image source stream.
virtual std::optional< V4L2Subdevice::Stream > | embeddedDataStream () const
| Retrieve the embedded data source stream.
virtual V4L2SubdeviceFormat | embeddedDataFormat () const
| Retrieve the format on the embedded data stream.
virtual int | setEmbeddedDataEnabled (bool enable)
| Enable or disable the embedded data stream.
virtual const ControlList & | properties () const =0
| Retrieve the camera sensor properties.
virtual int | sensorInfo (IPACameraSensorInfo *info) const =0
| Assemble and return the camera sensor info.
virtual Transform | computeTransform (Orientation *orientation) const =0
| Compute the Transform that gives the requested orientation.
virtual BayerFormat::Order | bayerOrder (Transform t) const =0
| Compute the Bayer order that results from the given Transform.
virtual Orientation | mountingOrientation () const =0
| Fetch the mounting orientation of the sensor.
virtual const ControlInfoMap & | controls () const =0
| Retrieve the supported V4L2 controls and their information.
virtual ControlList | getControls (Span< const uint32_t > ids)=0
| Read V4L2 controls from the sensor.
virtual int | setControls (ControlList *ctrls)=0
| Write V4L2 controls to the sensor.
virtual const std::vector< controls::draft::TestPatternModeEnum > & | testPatternModes () const =0
| Retrieve all the supported test pattern modes of the camera sensor The test pattern mode values correspond to the controls::TestPattern control.
virtual int | setTestPatternMode (controls::draft::TestPatternModeEnum mode)=0
| Set the test pattern mode for the camera sensor.
virtual const CameraSensorProperties::SensorDelays & | sensorDelays ()=0
| Fetch the sensor delay values.

## Detailed Description

A abstract camera sensor.

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

## Member Function Documentation

## ◆ applyConfiguration()

virtual int libcamera::CameraSensor::applyConfiguration | ( | const SensorConfiguration & | config,
|  | Transform | transform = Transform::Identity,
|  | V4L2SubdeviceFormat * | sensorFormat = nullptr )
| pure virtual

Apply a sensor configuration to the camera sensor.

Parameters

  [in] | config | The sensor configuration
  [in] | transform | The transform to be applied on the sensor. Defaults to Identity
  [out] | sensorFormat | Format applied to the sensor (optional)

Apply to the camera sensor the configuration config.

Todo
  The configuration shall be fully populated and if any of the fields specified cannot be applied exactly, an error code is returned.

Returns
  0 if config is applied correctly to the camera sensor, a negative error code otherwise

## ◆ bayerOrder()

virtual BayerFormat::Order libcamera::CameraSensor::bayerOrder | ( | Transform | t | ) | const
| pure virtual

Compute the Bayer order that results from the given Transform.

Parameters

  [in] | t | The Transform to apply to the sensor

Some sensors change their Bayer order when they are h-flipped or v-flipped. This function computes and returns the Bayer order that would result from the given transform applied to the sensor.

This function is valid only when the sensor produces raw Bayer formats.

Returns
  The Bayer order produced by the sensor when the Transform is applied

## ◆ computeTransform()

virtual Transform libcamera::CameraSensor::computeTransform | ( | Orientation * | orientation | ) | const
| pure virtual

Compute the Transform that gives the requested orientation.

Parameters

  [in,out] | orientation | The desired image orientation

This function computes the Transform that the pipeline handler should apply to the CameraSensor to obtain the requested orientation.

The intended caller of this function is the validate() implementation of pipeline handlers, that pass in the application requested CameraConfiguration::orientation and obtain a Transform to apply to the camera sensor, likely at configure() time.

If the requested orientation cannot be obtained, the orientation parameter is adjusted to report the native image orientation (i.e. resulting from the physical mounting rotation of the camera sensor, without any transformation) and Transform::Identity is returned.

If the requested orientation can be obtained, the function computes a Transform and does not adjust orientation.

Pipeline handlers are expected to verify if orientation has been adjusted by this function and set the CameraConfiguration::status to Adjusted accordingly.

Returns
  A Transform instance that applied to the CameraSensor produces images with orientation

## ◆ controls()

virtual const ControlInfoMap & libcamera::CameraSensor::controls | ( |  | ) | const
| pure virtual

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.

Returns
  A map of the V4L2 controls supported by the sensor

## ◆ device()

virtual V4L2Subdevice * libcamera::CameraSensor::device | ( |  | ) |
| pure virtual

Retrieve the camera sensor device.

Todo
  Remove this function by integrating DelayedControl with CameraSensor

Returns
  The camera sensor device

## ◆ embeddedDataFormat()

V4L2SubdeviceFormat libcamera::CameraSensor::embeddedDataFormat | ( |  | ) | const
| virtual

Retrieve the format on the embedded data stream.

When an embedded data stream is available, this function returns the corresponding format on the sensor's source pad. The format may vary with the image stream format, and should therefore be retrieved after configuring the image stream.

If the sensor doesn't support embedded data, this function returns a default-constructed format.

Returns
  The format on the embedded data stream

## ◆ embeddedDataStream()

std::optional< V4L2Subdevice::Stream > libcamera::CameraSensor::embeddedDataStream | ( |  | ) | const
| virtual

Retrieve the embedded data source stream.

Some sensors produce embedded data in a stream separate from the image stream. This function indicates if the sensor supports this feature by returning the embedded data stream on the sensor's source pad if available, or an std::optional<> without a value otheriwse.

Returns
  The embedded data source stream

## ◆ entity()

virtual const MediaEntity * libcamera::CameraSensor::entity | ( |  | ) | const
| pure virtual

Retrieve the sensor media entity.

Returns
  The sensor media entity

## ◆ focusLens()

virtual CameraLens * libcamera::CameraSensor::focusLens | ( |  | ) |
| pure virtual

Retrieve the focus lens controller.

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

## ◆ getControls()

virtual ControlList libcamera::CameraSensor::getControls | ( | Span< const uint32_t > | ids | ) |
| pure virtual

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

virtual V4L2SubdeviceFormat libcamera::CameraSensor::getFormat | ( | Span< const unsigned int > | mbusCodes,
|  | const Size & | size,
|  | const Size | maxSize = Size() ) const
| pure virtual

Retrieve the best sensor format for a desired output.

Parameters

  [in] | mbusCodes | The list of acceptable media bus codes
  [in] | size | The desired size
  [in] | maxSize | The maximum 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.
- The desired size shall fit into the maximum size maxSize if it is not null.

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

virtual const std::string & libcamera::CameraSensor::id | ( |  | ) | const
| pure virtual

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

## ◆ imageStream()

V4L2Subdevice::Stream libcamera::CameraSensor::imageStream | ( |  | ) | const
| virtual

Retrieve the image source stream.

Sensors that produce multiple streams do not guarantee that the image stream is always assigned number 0. This function allows callers to retrieve the image stream on the sensor's source pad, in order to configure the receiving side accordingly.

Returns
  The image source stream

## ◆ mbusCodes()

virtual const std::vector< unsigned int > & libcamera::CameraSensor::mbusCodes | ( |  | ) | const
| pure virtual

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

virtual const std::string & libcamera::CameraSensor::model | ( |  | ) | const
| pure virtual

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

## ◆ mountingOrientation()

virtual Orientation libcamera::CameraSensor::mountingOrientation | ( |  | ) | const
| pure virtual

Fetch the mounting orientation of the sensor.

Returns
  The mounting orientation of the sensor

## ◆ properties()

virtual const ControlList & libcamera::CameraSensor::properties | ( |  | ) | const
| pure virtual

Retrieve the camera sensor properties.

Returns
  The list of camera sensor properties

## ◆ resolution()

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

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

## ◆ sensorDelays()

virtual const CameraSensorProperties::SensorDelays & libcamera::CameraSensor::sensorDelays | ( |  | ) |
| pure virtual

Fetch the sensor delay values.

This function retrieves the delays that the sensor applies to controls. If the static properties database doesn't specifiy control delay values for the sensor, default delays that may be suitable are returned and a warning is logged.

Returns
  The sensor delay values

## ◆ sensorInfo()

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

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.

Returns
  0 on success, a negative error code otherwise

## ◆ setControls()

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

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

## ◆ setEmbeddedDataEnabled()

int libcamera::CameraSensor::setEmbeddedDataEnabled | ( | bool | enable | ) |
| virtual

Enable or disable the embedded data stream.

Parameters

  [in] | enable | True to enable the embedded data stream, false to disable it

For sensors that support embedded data, this function enables or disables generation of embedded data. Some of such sensors always produce embedded data, in which case this function return -EISCONN if the caller attempts to disable embedded data.

If the sensor doesn't support embedded data, this function returns 0 when enable is false, and -ENOSTR otherwise.

Returns
  0 on success, or a negative error code otherwise

## ◆ setFormat()

virtual int libcamera::CameraSensor::setFormat | ( | V4L2SubdeviceFormat * | format,
|  | Transform | transform = Transform::Identity )
| pure virtual

Set the sensor output format.

Parameters

  [in] | format | The desired sensor output format
  [in] | transform | The transform to be applied on the sensor. Defaults to Identity.

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

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

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

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

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

virtual const std::vector< controls::draft::TestPatternModeEnum > & libcamera::CameraSensor::testPatternModes | ( |  | ) | const
| pure virtual

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

## ◆ tryFormat()

virtual int libcamera::CameraSensor::tryFormat | ( | V4L2SubdeviceFormat * | format | ) | const
| pure virtual

Try the sensor output format.

Parameters

  [in] | format | The desired sensor output format

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

Todo
  Add support for Transform by changing the format's Bayer ordering before calling subdev_->setFormat().

Returns
  0 on success or a negative error code otherwise

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

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