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