105 lines
4.4 KiB
ReStructuredText
105 lines
4.4 KiB
ReStructuredText
.. SPDX-License-Identifier: GPL-2.0
|
|
|
|
.. _media_using_camera_sensor_drivers:
|
|
|
|
Using camera sensor drivers
|
|
===========================
|
|
|
|
This section describes common practices for how the V4L2 sub-device interface is
|
|
used to control the camera sensor drivers.
|
|
|
|
You may also find :ref:`media_writing_camera_sensor_drivers` useful.
|
|
|
|
Frame size
|
|
----------
|
|
|
|
There are two distinct ways to configure the frame size produced by camera
|
|
sensors.
|
|
|
|
Freely configurable camera sensor drivers
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Freely configurable camera sensor drivers expose the device's internal
|
|
processing pipeline as one or more sub-devices with different cropping and
|
|
scaling configurations. The output size of the device is the result of a series
|
|
of cropping and scaling operations from the device's pixel array's size.
|
|
|
|
An example of such a driver is the CCS driver.
|
|
|
|
Register list based drivers
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Register list based drivers generally, instead of able to configure the device
|
|
they control based on user requests, are limited to a number of preset
|
|
configurations that combine a number of different parameters that on hardware
|
|
level are independent. How a driver picks such configuration is based on the
|
|
format set on a source pad at the end of the device's internal pipeline.
|
|
|
|
Most sensor drivers are implemented this way.
|
|
|
|
Frame interval configuration
|
|
----------------------------
|
|
|
|
There are two different methods for obtaining possibilities for different frame
|
|
intervals as well as configuring the frame interval. Which one to implement
|
|
depends on the type of the device.
|
|
|
|
Raw camera sensors
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
Instead of a high level parameter such as frame interval, the frame interval is
|
|
a result of the configuration of a number of camera sensor implementation
|
|
specific parameters. Luckily, these parameters tend to be the same for more or
|
|
less all modern raw camera sensors.
|
|
|
|
The frame interval is calculated using the following equation::
|
|
|
|
frame interval = (analogue crop width + horizontal blanking) *
|
|
(analogue crop height + vertical blanking) / pixel rate
|
|
|
|
The formula is bus independent and is applicable for raw timing parameters on
|
|
large variety of devices beyond camera sensors. Devices that have no analogue
|
|
crop, use the full source image size, i.e. pixel array size.
|
|
|
|
Horizontal and vertical blanking are specified by ``V4L2_CID_HBLANK`` and
|
|
``V4L2_CID_VBLANK``, respectively. The unit of the ``V4L2_CID_HBLANK`` control
|
|
is pixels and the unit of the ``V4L2_CID_VBLANK`` is lines. The pixel rate in
|
|
the sensor's **pixel array** is specified by ``V4L2_CID_PIXEL_RATE`` in the same
|
|
sub-device. The unit of that control is pixels per second.
|
|
|
|
Register list based drivers need to implement read-only sub-device nodes for the
|
|
purpose. Devices that are not register list based need these to configure the
|
|
device's internal processing pipeline.
|
|
|
|
The first entity in the linear pipeline is the pixel array. The pixel array may
|
|
be followed by other entities that are there to allow configuring binning,
|
|
skipping, scaling or digital crop, see :ref:`VIDIOC_SUBDEV_G_SELECTION
|
|
<VIDIOC_SUBDEV_G_SELECTION>`.
|
|
|
|
USB cameras etc. devices
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
USB video class hardware, as well as many cameras offering a similar higher
|
|
level interface natively, generally use the concept of frame interval (or frame
|
|
rate) on device level in firmware or hardware. This means lower level controls
|
|
implemented by raw cameras may not be used on uAPI (or even kAPI) to control the
|
|
frame interval on these devices.
|
|
|
|
Rotation, orientation and flipping
|
|
----------------------------------
|
|
|
|
Some systems have the camera sensor mounted upside down compared to its natural
|
|
mounting rotation. In such cases, drivers shall expose the information to
|
|
userspace with the :ref:`V4L2_CID_CAMERA_SENSOR_ROTATION
|
|
<v4l2-camera-sensor-rotation>` control.
|
|
|
|
Sensor drivers shall also report the sensor's mounting orientation with the
|
|
:ref:`V4L2_CID_CAMERA_SENSOR_ORIENTATION <v4l2-camera-sensor-orientation>`.
|
|
|
|
Sensor drivers that have any vertical or horizontal flips embedded in the
|
|
register programming sequences shall initialize the :ref:`V4L2_CID_HFLIP
|
|
<v4l2-cid-hflip>` and :ref:`V4L2_CID_VFLIP <v4l2-cid-vflip>` controls with the
|
|
values programmed by the register sequences. The default values of these
|
|
controls shall be 0 (disabled). Especially these controls shall not be inverted,
|
|
independently of the sensor's mounting rotation.
|