| 1 | |
| 2 |
|
| 3 | .. _media_using_camera_sensor_drivers:
|
| 4 |
|
| 5 | Using camera sensor drivers
|
| 6 | ===========================
|
| 7 |
|
| 8 | This section describes common practices for how the V4L2 sub-device interface is
|
| 9 | used to control the camera sensor drivers.
|
| 10 |
|
| 11 | You may also find :ref:`media_writing_camera_sensor_drivers` useful.
|
| 12 |
|
| 13 | Sensor internal pipeline configuration
|
| 14 | --------------------------------------
|
| 15 |
|
| 16 | Camera sensors have an internal processing pipeline including cropping and
|
| 17 | binning functionality. The sensor drivers belong to two distinct classes, freely
|
| 18 | configurable and register list-based drivers, depending on how the driver
|
| 19 | configures this functionality.
|
| 20 |
|
| 21 | Freely configurable camera sensor drivers
|
| 22 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| 23 |
|
| 24 | Freely configurable camera sensor drivers expose the device's internal
|
| 25 | processing pipeline as one or more sub-devices with different cropping and
|
| 26 | scaling configurations. The output size of the device is the result of a series
|
| 27 | of cropping and scaling operations from the device's pixel array's size.
|
| 28 |
|
| 29 | An example of such a driver is the CCS driver.
|
| 30 |
|
| 31 | Register list-based drivers
|
| 32 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| 33 |
|
| 34 | Register list-based drivers generally, instead of able to configure the device
|
| 35 | they control based on user requests, are limited to a number of preset
|
| 36 | configurations that combine a number of different parameters that on hardware
|
| 37 | level are independent. How a driver picks such configuration is based on the
|
| 38 | format set on a source pad at the end of the device's internal pipeline.
|
| 39 |
|
| 40 | Most sensor drivers are implemented this way.
|
| 41 |
|
| 42 | Frame interval configuration
|
| 43 | ----------------------------
|
| 44 |
|
| 45 | There are two different methods for obtaining possibilities for different frame
|
| 46 | intervals as well as configuring the frame interval. Which one to implement
|
| 47 | depends on the type of the device.
|
| 48 |
|
| 49 | Raw camera sensors
|
| 50 | ~~~~~~~~~~~~~~~~~~
|
| 51 |
|
| 52 | Instead of a high level parameter such as frame interval, the frame interval is
|
| 53 | a result of the configuration of a number of camera sensor implementation
|
| 54 | specific parameters. Luckily, these parameters tend to be the same for more or
|
| 55 | less all modern raw camera sensors.
|
| 56 |
|
| 57 | The frame interval is calculated using the following equation::
|
| 58 |
|
| 59 | frame interval = (analogue crop width + horizontal blanking) *
|
| 60 | (analogue crop height + vertical blanking) / pixel rate
|
| 61 |
|
| 62 | The formula is bus independent and is applicable for raw timing parameters on
|
| 63 | large variety of devices beyond camera sensors. Devices that have no analogue
|
| 64 | crop, use the full source image size, i.e. pixel array size.
|
| 65 |
|
| 66 | Horizontal and vertical blanking are specified by ``V4L2_CID_HBLANK`` and
|
| 67 | ``V4L2_CID_VBLANK``, respectively. The unit of the ``V4L2_CID_HBLANK`` control
|
| 68 | is pixels and the unit of the ``V4L2_CID_VBLANK`` is lines. The pixel rate in
|
| 69 | the sensor's **pixel array** is specified by ``V4L2_CID_PIXEL_RATE`` in the same
|
| 70 | sub-device. The unit of that control is pixels per second.
|
| 71 |
|
| 72 | Register list-based drivers need to implement read-only sub-device nodes for the
|
| 73 | purpose. Devices that are not register list based need these to configure the
|
| 74 | device's internal processing pipeline.
|
| 75 |
|
| 76 | The first entity in the linear pipeline is the pixel array. The pixel array may
|
| 77 | be followed by other entities that are there to allow configuring binning,
|
| 78 | skipping, scaling or digital crop, see :ref:`VIDIOC_SUBDEV_G_SELECTION
|
| 79 | <VIDIOC_SUBDEV_G_SELECTION>`.
|
| 80 |
|
| 81 | USB cameras etc. devices
|
| 82 | ~~~~~~~~~~~~~~~~~~~~~~~~
|
| 83 |
|
| 84 | USB video class hardware, as well as many cameras offering a similar higher
|
| 85 | level interface natively, generally use the concept of frame interval (or frame
|
| 86 | rate) on device level in firmware or hardware. This means lower level controls
|
| 87 | implemented by raw cameras may not be used on uAPI (or even kAPI) to control the
|
| 88 | frame interval on these devices.
|
| 89 |
|
| 90 | Rotation, orientation and flipping
|
| 91 | ----------------------------------
|
| 92 |
|
| 93 | Some systems have the camera sensor mounted upside down compared to its natural
|
| 94 | mounting rotation. In such cases, drivers shall expose the information to
|
| 95 | userspace with the :ref:`V4L2_CID_CAMERA_SENSOR_ROTATION
|
| 96 | <v4l2-camera-sensor-rotation>` control.
|
| 97 |
|
| 98 | Sensor drivers shall also report the sensor's mounting orientation with the
|
| 99 | :ref:`V4L2_CID_CAMERA_SENSOR_ORIENTATION <v4l2-camera-sensor-orientation>`.
|
| 100 |
|
| 101 | Sensor drivers that have any vertical or horizontal flips embedded in the
|
| 102 | register programming sequences shall initialize the :ref:`V4L2_CID_HFLIP
|
| 103 | <v4l2-cid-hflip>` and :ref:`V4L2_CID_VFLIP <v4l2-cid-vflip>` controls with the
|
| 104 | values programmed by the register sequences. The default values of these
|
| 105 | controls shall be 0 (disabled). Especially these controls shall not be inverted,
|
| 106 | independently of the sensor's mounting rotation.
|