1 .. Permission is granted to copy, distribute and/or modify this
2 .. document under the terms of the GNU Free Documentation License,
3 .. Version 1.1 or any later version published by the Free Software
4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
5 .. and no Back-Cover Texts. A copy of the license is included at
6 .. Documentation/media/uapi/fdl-appendix.rst.
8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
10 .. _VIDIOC_SUBDEV_G_SELECTION:
12 **********************************************************
13 ioctl VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION
14 **********************************************************
19 VIDIOC_SUBDEV_G_SELECTION - VIDIOC_SUBDEV_S_SELECTION - Get or set selection rectangles on a subdev pad
25 .. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_SELECTION, struct v4l2_subdev_selection *argp )
26 :name: VIDIOC_SUBDEV_G_SELECTION
28 .. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_SELECTION, struct v4l2_subdev_selection *argp )
29 :name: VIDIOC_SUBDEV_S_SELECTION
36 File descriptor returned by :ref:`open() <func-open>`.
39 Pointer to struct :c:type:`v4l2_subdev_selection`.
45 The selections are used to configure various image processing
46 functionality performed by the subdevs which affect the image size. This
47 currently includes cropping, scaling and composition.
49 The selection API replaces
50 :ref:`the old subdev crop API <VIDIOC_SUBDEV_G_CROP>`. All the
51 function of the crop API, and more, are supported by the selections API.
53 See :ref:`subdev` for more information on how each selection target
54 affects the image processing pipeline inside the subdevice.
57 Types of selection targets
58 --------------------------
60 There are two types of selection targets: actual and bounds. The actual
61 targets are the targets which configure the hardware. The BOUNDS target
62 will return a rectangle that contain all possible actual rectangles.
65 Discovering supported features
66 ------------------------------
68 To discover which targets are supported, the user can perform
69 ``VIDIOC_SUBDEV_G_SELECTION`` on them. Any unsupported target will
72 Selection targets and flags are documented in
73 :ref:`v4l2-selections-common`.
76 .. c:type:: v4l2_subdev_selection
78 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
80 .. flat-table:: struct v4l2_subdev_selection
87 - Active or try selection, from enum
88 :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
91 - Pad number as reported by the media framework.
94 - Target selection rectangle. See :ref:`v4l2-selections-common`.
97 - Flags. See :ref:`v4l2-selection-flags`.
98 * - struct :c:type:`v4l2_rect`
100 - Selection rectangle, in pixels.
103 - Reserved for future extensions. Applications and drivers must set
110 On success 0 is returned, on error -1 and the ``errno`` variable is set
111 appropriately. The generic error codes are described at the
112 :ref:`Generic Error Codes <gen-errors>` chapter.
115 The selection rectangle can't be changed because the pad is
116 currently busy. This can be caused, for instance, by an active video
117 stream on the pad. The ioctl must not be retried without performing
118 another action to fix the problem first. Only returned by
119 ``VIDIOC_SUBDEV_S_SELECTION``
122 The struct :c:type:`v4l2_subdev_selection`
123 ``pad`` references a non-existing pad, the ``which`` field
124 references a non-existing format, or the selection target is not
125 supported on the given subdev pad.