0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _VIDIOC_G_SELECTION:
0005
0006 ********************************************
0007 ioctl VIDIOC_G_SELECTION, VIDIOC_S_SELECTION
0008 ********************************************
0009
0010 Name
0011 ====
0012
0013 VIDIOC_G_SELECTION - VIDIOC_S_SELECTION - Get or set one of the selection rectangles
0014
0015 Synopsis
0016 ========
0017
0018 .. c:macro:: VIDIOC_G_SELECTION
0019
0020 ``int ioctl(int fd, VIDIOC_G_SELECTION, struct v4l2_selection *argp)``
0021
0022 .. c:macro:: VIDIOC_S_SELECTION
0023
0024 ``int ioctl(int fd, VIDIOC_S_SELECTION, struct v4l2_selection *argp)``
0025
0026 Arguments
0027 =========
0028
0029 ``fd``
0030 File descriptor returned by :c:func:`open()`.
0031
0032 ``argp``
0033 Pointer to struct :c:type:`v4l2_selection`.
0034
0035 Description
0036 ===========
0037
0038 The ioctls are used to query and configure selection rectangles.
0039
0040 To query the cropping (composing) rectangle set struct
0041 :c:type:`v4l2_selection` ``type`` field to the
0042 respective buffer type. The next step is setting the
0043 value of struct :c:type:`v4l2_selection` ``target``
0044 field to ``V4L2_SEL_TGT_CROP`` (``V4L2_SEL_TGT_COMPOSE``). Please refer
0045 to table :ref:`v4l2-selections-common` or :ref:`selection-api` for
0046 additional targets. The ``flags`` and ``reserved`` fields of struct
0047 :c:type:`v4l2_selection` are ignored and they must be
0048 filled with zeros. The driver fills the rest of the structure or returns
0049 EINVAL error code if incorrect buffer type or target was used. If
0050 cropping (composing) is not supported then the active rectangle is not
0051 mutable and it is always equal to the bounds rectangle. Finally, the
0052 struct :c:type:`v4l2_rect` ``r`` rectangle is filled with
0053 the current cropping (composing) coordinates. The coordinates are
0054 expressed in driver-dependent units. The only exception are rectangles
0055 for images in raw formats, whose coordinates are always expressed in
0056 pixels.
0057
0058 To change the cropping (composing) rectangle set the struct
0059 :c:type:`v4l2_selection` ``type`` field to the
0060 respective buffer type. The next step is setting the
0061 value of struct :c:type:`v4l2_selection` ``target`` to
0062 ``V4L2_SEL_TGT_CROP`` (``V4L2_SEL_TGT_COMPOSE``). Please refer to table
0063 :ref:`v4l2-selections-common` or :ref:`selection-api` for additional
0064 targets. The struct :c:type:`v4l2_rect` ``r`` rectangle need
0065 to be set to the desired active area. Field struct
0066 :c:type:`v4l2_selection` ``reserved`` is ignored and
0067 must be filled with zeros. The driver may adjust coordinates of the
0068 requested rectangle. An application may introduce constraints to control
0069 rounding behaviour. The struct :c:type:`v4l2_selection`
0070 ``flags`` field must be set to one of the following:
0071
0072 - ``0`` - The driver can adjust the rectangle size freely and shall
0073 choose a crop/compose rectangle as close as possible to the requested
0074 one.
0075
0076 - ``V4L2_SEL_FLAG_GE`` - The driver is not allowed to shrink the
0077 rectangle. The original rectangle must lay inside the adjusted one.
0078
0079 - ``V4L2_SEL_FLAG_LE`` - The driver is not allowed to enlarge the
0080 rectangle. The adjusted rectangle must lay inside the original one.
0081
0082 - ``V4L2_SEL_FLAG_GE | V4L2_SEL_FLAG_LE`` - The driver must choose the
0083 size exactly the same as in the requested rectangle.
0084
0085 Please refer to :ref:`sel-const-adjust`.
0086
0087 The driver may have to adjusts the requested dimensions against hardware
0088 limits and other parts as the pipeline, i.e. the bounds given by the
0089 capture/output window or TV display. The closest possible values of
0090 horizontal and vertical offset and sizes are chosen according to
0091 following priority:
0092
0093 1. Satisfy constraints from struct
0094 :c:type:`v4l2_selection` ``flags``.
0095
0096 2. Adjust width, height, left, and top to hardware limits and
0097 alignments.
0098
0099 3. Keep center of adjusted rectangle as close as possible to the
0100 original one.
0101
0102 4. Keep width and height as close as possible to original ones.
0103
0104 5. Keep horizontal and vertical offset as close as possible to original
0105 ones.
0106
0107 On success the struct :c:type:`v4l2_rect` ``r`` field
0108 contains the adjusted rectangle. When the parameters are unsuitable the
0109 application may modify the cropping (composing) or image parameters and
0110 repeat the cycle until satisfactory parameters have been negotiated. If
0111 constraints flags have to be violated at then ``ERANGE`` is returned. The
0112 error indicates that *there exist no rectangle* that satisfies the
0113 constraints.
0114
0115 Selection targets and flags are documented in
0116 :ref:`v4l2-selections-common`.
0117
0118 .. _sel-const-adjust:
0119
0120 .. kernel-figure:: constraints.svg
0121 :alt: constraints.svg
0122 :align: center
0123
0124 Size adjustments with constraint flags.
0125
0126 Behaviour of rectangle adjustment for different constraint flags.
0127
0128
0129
0130 .. c:type:: v4l2_selection
0131
0132 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
0133
0134 .. flat-table:: struct v4l2_selection
0135 :header-rows: 0
0136 :stub-columns: 0
0137 :widths: 1 1 2
0138
0139 * - __u32
0140 - ``type``
0141 - Type of the buffer (from enum
0142 :c:type:`v4l2_buf_type`).
0143 * - __u32
0144 - ``target``
0145 - Used to select between
0146 :ref:`cropping and composing rectangles <v4l2-selections-common>`.
0147 * - __u32
0148 - ``flags``
0149 - Flags controlling the selection rectangle adjustments, refer to
0150 :ref:`selection flags <v4l2-selection-flags>`.
0151 * - struct :c:type:`v4l2_rect`
0152 - ``r``
0153 - The selection rectangle.
0154 * - __u32
0155 - ``reserved[9]``
0156 - Reserved fields for future use. Drivers and applications must zero
0157 this array.
0158
0159 .. note::
0160 Unfortunately in the case of multiplanar buffer types
0161 (``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``)
0162 this API was messed up with regards to how the :c:type:`v4l2_selection` ``type`` field
0163 should be filled in. Some drivers only accepted the ``_MPLANE`` buffer type while
0164 other drivers only accepted a non-multiplanar buffer type (i.e. without the
0165 ``_MPLANE`` at the end).
0166
0167 Starting with kernel 4.13 both variations are allowed.
0168
0169 Return Value
0170 ============
0171
0172 On success 0 is returned, on error -1 and the ``errno`` variable is set
0173 appropriately. The generic error codes are described at the
0174 :ref:`Generic Error Codes <gen-errors>` chapter.
0175
0176 EINVAL
0177 Given buffer type ``type`` or the selection target ``target`` is not
0178 supported, or the ``flags`` argument is not valid.
0179
0180 ERANGE
0181 It is not possible to adjust struct :c:type:`v4l2_rect`
0182 ``r`` rectangle to satisfy all constraints given in the ``flags``
0183 argument.
0184
0185 ENODATA
0186 Selection is not supported for this input or output.
0187
0188 EBUSY
0189 It is not possible to apply change of the selection rectangle at the
0190 moment. Usually because streaming is in progress.
