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