| 1 |
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later |
| 2 |
.. c:namespace:: V4L |
| 3 |
|
| 4 |
************* |
| 5 |
Configuration |
| 6 |
************* |
| 7 |
|
| 8 |
Applications can use the :ref:`selection API <VIDIOC_G_SELECTION>` to |
| 9 |
select an area in a video signal or a buffer, and to query for default |
| 10 |
settings and hardware limits. |
| 11 |
|
| 12 |
Video hardware can have various cropping, composing and scaling |
| 13 |
limitations. It may only scale up or down, support only discrete scaling |
| 14 |
factors, or have different scaling abilities in the horizontal and |
| 15 |
vertical directions. Also it may not support scaling at all. At the same |
| 16 |
time the cropping/composing rectangles may have to be aligned, and both |
| 17 |
the source and the sink may have arbitrary upper and lower size limits. |
| 18 |
Therefore, as usual, drivers are expected to adjust the requested |
| 19 |
parameters and return the actual values selected. An application can |
| 20 |
control the rounding behaviour using |
| 21 |
:ref:`constraint flags <v4l2-selection-flags>`. |
| 22 |
|
| 23 |
|
| 24 |
Configuration of video capture |
| 25 |
============================== |
| 26 |
|
| 27 |
See figure :ref:`sel-targets-capture` for examples of the selection |
| 28 |
targets available for a video capture device. It is recommended to |
| 29 |
configure the cropping targets before to the composing targets. |
| 30 |
|
| 31 |
The range of coordinates of the top left corner, width and height of |
| 32 |
areas that can be sampled is given by the ``V4L2_SEL_TGT_CROP_BOUNDS`` |
| 33 |
target. It is recommended for the driver developers to put the top/left |
| 34 |
corner at position ``(0,0)``. The rectangle's coordinates are expressed |
| 35 |
in pixels. |
| 36 |
|
| 37 |
The top left corner, width and height of the source rectangle, that is |
| 38 |
the area actually sampled, is given by the ``V4L2_SEL_TGT_CROP`` target. |
| 39 |
It uses the same coordinate system as ``V4L2_SEL_TGT_CROP_BOUNDS``. The |
| 40 |
active cropping area must lie completely inside the capture boundaries. |
| 41 |
The driver may further adjust the requested size and/or position |
| 42 |
according to hardware limitations. |
| 43 |
|
| 44 |
Each capture device has a default source rectangle, given by the |
| 45 |
``V4L2_SEL_TGT_CROP_DEFAULT`` target. This rectangle shall cover what the |
| 46 |
driver writer considers the complete picture. Drivers shall set the |
| 47 |
active crop rectangle to the default when the driver is first loaded, |
| 48 |
but not later. |
| 49 |
|
| 50 |
The composing targets refer to a memory buffer. The limits of composing |
| 51 |
coordinates are obtained using ``V4L2_SEL_TGT_COMPOSE_BOUNDS``. All |
| 52 |
coordinates are expressed in pixels. The rectangle's top/left corner |
| 53 |
must be located at position ``(0,0)``. The width and height are equal to |
| 54 |
the image size set by :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. |
| 55 |
|
| 56 |
The part of a buffer into which the image is inserted by the hardware is |
| 57 |
controlled by the ``V4L2_SEL_TGT_COMPOSE`` target. The rectangle's |
| 58 |
coordinates are also expressed in the same coordinate system as the |
| 59 |
bounds rectangle. The composing rectangle must lie completely inside |
| 60 |
bounds rectangle. The driver must adjust the composing rectangle to fit |
| 61 |
to the bounding limits. Moreover, the driver can perform other |
| 62 |
adjustments according to hardware limitations. The application can |
| 63 |
control rounding behaviour using |
| 64 |
:ref:`constraint flags <v4l2-selection-flags>`. |
| 65 |
|
| 66 |
For capture devices the default composing rectangle is queried using |
| 67 |
``V4L2_SEL_TGT_COMPOSE_DEFAULT``. It is usually equal to the bounding |
| 68 |
rectangle. |
| 69 |
|
| 70 |
The part of a buffer that is modified by the hardware is given by |
| 71 |
``V4L2_SEL_TGT_COMPOSE_PADDED``. It contains all pixels defined using |
| 72 |
``V4L2_SEL_TGT_COMPOSE`` plus all padding data modified by hardware |
| 73 |
during insertion process. All pixels outside this rectangle *must not* |
| 74 |
be changed by the hardware. The content of pixels that lie inside the |
| 75 |
padded area but outside active area is undefined. The application can |
| 76 |
use the padded and active rectangles to detect where the rubbish pixels |
| 77 |
are located and remove them if needed. |
| 78 |
|
| 79 |
|
| 80 |
Configuration of video output |
| 81 |
============================= |
| 82 |
|
| 83 |
For output devices targets and ioctls are used similarly to the video |
| 84 |
capture case. The *composing* rectangle refers to the insertion of an |
| 85 |
image into a video signal. The cropping rectangles refer to a memory |
| 86 |
buffer. It is recommended to configure the composing targets before to |
| 87 |
the cropping targets. |
| 88 |
|
| 89 |
The cropping targets refer to the memory buffer that contains an image |
| 90 |
to be inserted into a video signal or graphical screen. The limits of |
| 91 |
cropping coordinates are obtained using ``V4L2_SEL_TGT_CROP_BOUNDS``. |
| 92 |
All coordinates are expressed in pixels. The top/left corner is always |
| 93 |
point ``(0,0)``. The width and height is equal to the image size |
| 94 |
specified using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. |
| 95 |
|
| 96 |
The top left corner, width and height of the source rectangle, that is |
| 97 |
the area from which image date are processed by the hardware, is given |
| 98 |
by the ``V4L2_SEL_TGT_CROP``. Its coordinates are expressed in the |
| 99 |
same coordinate system as the bounds rectangle. The active cropping area |
| 100 |
must lie completely inside the crop boundaries and the driver may |
| 101 |
further adjust the requested size and/or position according to hardware |
| 102 |
limitations. |
| 103 |
|
| 104 |
For output devices the default cropping rectangle is queried using |
| 105 |
``V4L2_SEL_TGT_CROP_DEFAULT``. It is usually equal to the bounding |
| 106 |
rectangle. |
| 107 |
|
| 108 |
The part of a video signal or graphics display where the image is |
| 109 |
inserted by the hardware is controlled by ``V4L2_SEL_TGT_COMPOSE`` |
| 110 |
target. The rectangle's coordinates are expressed in pixels. The |
| 111 |
composing rectangle must lie completely inside the bounds rectangle. The |
| 112 |
driver must adjust the area to fit to the bounding limits. Moreover, the |
| 113 |
driver can perform other adjustments according to hardware limitations. |
| 114 |
|
| 115 |
The device has a default composing rectangle, given by the |
| 116 |
``V4L2_SEL_TGT_COMPOSE_DEFAULT`` target. This rectangle shall cover what |
| 117 |
the driver writer considers the complete picture. It is recommended for |
| 118 |
the driver developers to put the top/left corner at position ``(0,0)``. |
| 119 |
Drivers shall set the active composing rectangle to the default one when |
| 120 |
the driver is first loaded. |
| 121 |
|
| 122 |
The devices may introduce additional content to video signal other than |
| 123 |
an image from memory buffers. It includes borders around an image. |
| 124 |
However, such a padded area is driver-dependent feature not covered by |
| 125 |
this document. Driver developers are encouraged to keep padded rectangle |
| 126 |
equal to active one. The padded target is accessed by the |
| 127 |
``V4L2_SEL_TGT_COMPOSE_PADDED`` identifier. It must contain all pixels |
| 128 |
from the ``V4L2_SEL_TGT_COMPOSE`` target. |
| 129 |
|
| 130 |
|
| 131 |
Scaling control |
| 132 |
=============== |
| 133 |
|
| 134 |
An application can detect if scaling is performed by comparing the width |
| 135 |
and the height of rectangles obtained using ``V4L2_SEL_TGT_CROP`` and |
| 136 |
``V4L2_SEL_TGT_COMPOSE`` targets. If these are not equal then the |
| 137 |
scaling is applied. The application can compute the scaling ratios using |
| 138 |
these values. |