Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
3 | ************* | |
4 | Configuration | |
5 | ************* | |
6 | ||
af4a4d0d | 7 | Applications can use the :ref:`selection API <VIDIOC_G_SELECTION>` to |
5377d91f MH |
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 | |
2212ff25 | 53 | the image size set by :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. |
5377d91f MH |
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 | |
2212ff25 | 93 | specified using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. |
5377d91f MH |
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. |