| 1 |
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later |
| 2 |
.. c:namespace:: V4L |
| 3 |
|
| 4 |
.. _VIDIOC_G_SELECTION: |
| 5 |
|
| 6 |
******************************************** |
| 7 |
ioctl VIDIOC_G_SELECTION, VIDIOC_S_SELECTION |
| 8 |
******************************************** |
| 9 |
|
| 10 |
Name |
| 11 |
==== |
| 12 |
|
| 13 |
VIDIOC_G_SELECTION - VIDIOC_S_SELECTION - Get or set one of the selection rectangles |
| 14 |
|
| 15 |
Synopsis |
| 16 |
======== |
| 17 |
|
| 18 |
.. c:macro:: VIDIOC_G_SELECTION |
| 19 |
|
| 20 |
``int ioctl(int fd, VIDIOC_G_SELECTION, struct v4l2_selection *argp)`` |
| 21 |
|
| 22 |
.. c:macro:: VIDIOC_S_SELECTION |
| 23 |
|
| 24 |
``int ioctl(int fd, VIDIOC_S_SELECTION, struct v4l2_selection *argp)`` |
| 25 |
|
| 26 |
Arguments |
| 27 |
========= |
| 28 |
|
| 29 |
``fd`` |
| 30 |
File descriptor returned by :c:func:`open()`. |
| 31 |
|
| 32 |
``argp`` |
| 33 |
Pointer to struct :c:type:`v4l2_selection`. |
| 34 |
|
| 35 |
Description |
| 36 |
=========== |
| 37 |
|
| 38 |
The ioctls are used to query and configure selection rectangles. |
| 39 |
|
| 40 |
To query the cropping (composing) rectangle set struct |
| 41 |
:c:type:`v4l2_selection` ``type`` field to the |
| 42 |
respective buffer type. The next step is setting the |
| 43 |
value of struct :c:type:`v4l2_selection` ``target`` |
| 44 |
field to ``V4L2_SEL_TGT_CROP`` (``V4L2_SEL_TGT_COMPOSE``). Please refer |
| 45 |
to table :ref:`v4l2-selections-common` or :ref:`selection-api` for |
| 46 |
additional targets. The ``flags`` and ``reserved`` fields of struct |
| 47 |
:c:type:`v4l2_selection` are ignored and they must be |
| 48 |
filled with zeros. The driver fills the rest of the structure or returns |
| 49 |
EINVAL error code if incorrect buffer type or target was used. If |
| 50 |
cropping (composing) is not supported then the active rectangle is not |
| 51 |
mutable and it is always equal to the bounds rectangle. Finally, the |
| 52 |
struct :c:type:`v4l2_rect` ``r`` rectangle is filled with |
| 53 |
the current cropping (composing) coordinates. The coordinates are |
| 54 |
expressed in driver-dependent units. The only exception are rectangles |
| 55 |
for images in raw formats, whose coordinates are always expressed in |
| 56 |
pixels. |
| 57 |
|
| 58 |
To change the cropping (composing) rectangle set the struct |
| 59 |
:c:type:`v4l2_selection` ``type`` field to the |
| 60 |
respective buffer type. The next step is setting the |
| 61 |
value of struct :c:type:`v4l2_selection` ``target`` to |
| 62 |
``V4L2_SEL_TGT_CROP`` (``V4L2_SEL_TGT_COMPOSE``). Please refer to table |
| 63 |
:ref:`v4l2-selections-common` or :ref:`selection-api` for additional |
| 64 |
targets. The struct :c:type:`v4l2_rect` ``r`` rectangle need |
| 65 |
to be set to the desired active area. Field struct |
| 66 |
:c:type:`v4l2_selection` ``reserved`` is ignored and |
| 67 |
must be filled with zeros. The driver may adjust coordinates of the |
| 68 |
requested rectangle. An application may introduce constraints to control |
| 69 |
rounding behaviour. The struct :c:type:`v4l2_selection` |
| 70 |
``flags`` field must be set to one of the following: |
| 71 |
|
| 72 |
- ``0`` - The driver can adjust the rectangle size freely and shall |
| 73 |
choose a crop/compose rectangle as close as possible to the requested |
| 74 |
one. |
| 75 |
|
| 76 |
- ``V4L2_SEL_FLAG_GE`` - The driver is not allowed to shrink the |
| 77 |
rectangle. The original rectangle must lay inside the adjusted one. |
| 78 |
|
| 79 |
- ``V4L2_SEL_FLAG_LE`` - The driver is not allowed to enlarge the |
| 80 |
rectangle. The adjusted rectangle must lay inside the original one. |
| 81 |
|
| 82 |
- ``V4L2_SEL_FLAG_GE | V4L2_SEL_FLAG_LE`` - The driver must choose the |
| 83 |
size exactly the same as in the requested rectangle. |
| 84 |
|
| 85 |
Please refer to :ref:`sel-const-adjust`. |
| 86 |
|
| 87 |
The driver may have to adjusts the requested dimensions against hardware |
| 88 |
limits and other parts as the pipeline, i.e. the bounds given by the |
| 89 |
capture/output window or TV display. The closest possible values of |
| 90 |
horizontal and vertical offset and sizes are chosen according to |
| 91 |
following priority: |
| 92 |
|
| 93 |
1. Satisfy constraints from struct |
| 94 |
:c:type:`v4l2_selection` ``flags``. |
| 95 |
|
| 96 |
2. Adjust width, height, left, and top to hardware limits and |
| 97 |
alignments. |
| 98 |
|
| 99 |
3. Keep center of adjusted rectangle as close as possible to the |
| 100 |
original one. |
| 101 |
|
| 102 |
4. Keep width and height as close as possible to original ones. |
| 103 |
|
| 104 |
5. Keep horizontal and vertical offset as close as possible to original |
| 105 |
ones. |
| 106 |
|
| 107 |
On success the struct :c:type:`v4l2_rect` ``r`` field |
| 108 |
contains the adjusted rectangle. When the parameters are unsuitable the |
| 109 |
application may modify the cropping (composing) or image parameters and |
| 110 |
repeat the cycle until satisfactory parameters have been negotiated. If |
| 111 |
constraints flags have to be violated at then ``ERANGE`` is returned. The |
| 112 |
error indicates that *there exist no rectangle* that satisfies the |
| 113 |
constraints. |
| 114 |
|
| 115 |
Selection targets and flags are documented in |
| 116 |
:ref:`v4l2-selections-common`. |
| 117 |
|
| 118 |
.. _sel-const-adjust: |
| 119 |
|
| 120 |
.. kernel-figure:: constraints.svg |
| 121 |
:alt: constraints.svg |
| 122 |
:align: center |
| 123 |
|
| 124 |
Size adjustments with constraint flags. |
| 125 |
|
| 126 |
Behaviour of rectangle adjustment for different constraint flags. |
| 127 |
|
| 128 |
|
| 129 |
|
| 130 |
.. c:type:: v4l2_selection |
| 131 |
|
| 132 |
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| |
| 133 |
|
| 134 |
.. flat-table:: struct v4l2_selection |
| 135 |
:header-rows: 0 |
| 136 |
:stub-columns: 0 |
| 137 |
:widths: 1 1 2 |
| 138 |
|
| 139 |
* - __u32 |
| 140 |
- ``type`` |
| 141 |
- Type of the buffer (from enum |
| 142 |
:c:type:`v4l2_buf_type`). |
| 143 |
* - __u32 |
| 144 |
- ``target`` |
| 145 |
- Used to select between |
| 146 |
:ref:`cropping and composing rectangles <v4l2-selections-common>`. |
| 147 |
* - __u32 |
| 148 |
- ``flags`` |
| 149 |
- Flags controlling the selection rectangle adjustments, refer to |
| 150 |
:ref:`selection flags <v4l2-selection-flags>`. |
| 151 |
* - struct :c:type:`v4l2_rect` |
| 152 |
- ``r`` |
| 153 |
- The selection rectangle. |
| 154 |
* - __u32 |
| 155 |
- ``reserved[9]`` |
| 156 |
- Reserved fields for future use. Drivers and applications must zero |
| 157 |
this array. |
| 158 |
|
| 159 |
.. note:: |
| 160 |
Unfortunately in the case of multiplanar buffer types |
| 161 |
(``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``) |
| 162 |
this API was messed up with regards to how the :c:type:`v4l2_selection` ``type`` field |
| 163 |
should be filled in. Some drivers only accepted the ``_MPLANE`` buffer type while |
| 164 |
other drivers only accepted a non-multiplanar buffer type (i.e. without the |
| 165 |
``_MPLANE`` at the end). |
| 166 |
|
| 167 |
Starting with kernel 4.13 both variations are allowed. |
| 168 |
|
| 169 |
Return Value |
| 170 |
============ |
| 171 |
|
| 172 |
On success 0 is returned, on error -1 and the ``errno`` variable is set |
| 173 |
appropriately. The generic error codes are described at the |
| 174 |
:ref:`Generic Error Codes <gen-errors>` chapter. |
| 175 |
|
| 176 |
EINVAL |
| 177 |
Given buffer type ``type`` or the selection target ``target`` is not |
| 178 |
supported, or the ``flags`` argument is not valid. |
| 179 |
|
| 180 |
ERANGE |
| 181 |
It is not possible to adjust struct :c:type:`v4l2_rect` |
| 182 |
``r`` rectangle to satisfy all constraints given in the ``flags`` |
| 183 |
argument. |
| 184 |
|
| 185 |
ENODATA |
| 186 |
Selection is not supported for this input or output. |
| 187 |
|
| 188 |
EBUSY |
| 189 |
It is not possible to apply change of the selection rectangle at the |
| 190 |
moment. Usually because streaming is in progress. |