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