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