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/userspace-api/media/fdl-appendix.rst.
7..
8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
9
10.. _VIDIOC_SUBDEV_G_SELECTION:
11
12**********************************************************
13ioctl VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION
14**********************************************************
15
16Name
17====
18
19VIDIOC_SUBDEV_G_SELECTION - VIDIOC_SUBDEV_S_SELECTION - Get or set selection rectangles on a subdev pad
20
21
22Synopsis
23========
24
25.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_SELECTION, struct v4l2_subdev_selection *argp )
26    :name: VIDIOC_SUBDEV_G_SELECTION
27
28.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_SELECTION, struct v4l2_subdev_selection *argp )
29    :name: VIDIOC_SUBDEV_S_SELECTION
30
31
32Arguments
33=========
34
35``fd``
36    File descriptor returned by :ref:`open() <func-open>`.
37
38``argp``
39    Pointer to struct :c:type:`v4l2_subdev_selection`.
40
41
42Description
43===========
44
45The selections are used to configure various image processing
46functionality performed by the subdevs which affect the image size. This
47currently includes cropping, scaling and composition.
48
49The selection API replaces
50:ref:`the old subdev crop API <VIDIOC_SUBDEV_G_CROP>`. All the
51function of the crop API, and more, are supported by the selections API.
52
53See :ref:`subdev` for more information on how each selection target
54affects the image processing pipeline inside the subdevice.
55
56If the subdev device node has been registered in read-only mode, calls to
57``VIDIOC_SUBDEV_S_SELECTION`` are only valid if the ``which`` field is set to
58``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
59variable is set to ``-EPERM``.
60
61Types of selection targets
62--------------------------
63
64There are two types of selection targets: actual and bounds. The actual
65targets are the targets which configure the hardware. The BOUNDS target
66will return a rectangle that contain all possible actual rectangles.
67
68
69Discovering supported features
70------------------------------
71
72To discover which targets are supported, the user can perform
73``VIDIOC_SUBDEV_G_SELECTION`` on them. Any unsupported target will
74return ``EINVAL``.
75
76Selection targets and flags are documented in
77:ref:`v4l2-selections-common`.
78
79
80.. c:type:: v4l2_subdev_selection
81
82.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
83
84.. flat-table:: struct v4l2_subdev_selection
85    :header-rows:  0
86    :stub-columns: 0
87    :widths:       1 1 2
88
89    * - __u32
90      - ``which``
91      - Active or try selection, from enum
92	:ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
93    * - __u32
94      - ``pad``
95      - Pad number as reported by the media framework.
96    * - __u32
97      - ``target``
98      - Target selection rectangle. See :ref:`v4l2-selections-common`.
99    * - __u32
100      - ``flags``
101      - Flags. See :ref:`v4l2-selection-flags`.
102    * - struct :c:type:`v4l2_rect`
103      - ``r``
104      - Selection rectangle, in pixels.
105    * - __u32
106      - ``reserved``\ [8]
107      - Reserved for future extensions. Applications and drivers must set
108	the array to zero.
109
110
111Return Value
112============
113
114On success 0 is returned, on error -1 and the ``errno`` variable is set
115appropriately. The generic error codes are described at the
116:ref:`Generic Error Codes <gen-errors>` chapter.
117
118EBUSY
119    The selection rectangle can't be changed because the pad is
120    currently busy. This can be caused, for instance, by an active video
121    stream on the pad. The ioctl must not be retried without performing
122    another action to fix the problem first. Only returned by
123    ``VIDIOC_SUBDEV_S_SELECTION``
124
125EINVAL
126    The struct :c:type:`v4l2_subdev_selection`
127    ``pad`` references a non-existing pad, the ``which`` field
128    references a non-existing format, or the selection target is not
129    supported on the given subdev pad.
130
131EPERM
132    The ``VIDIOC_SUBDEV_S_SELECTION`` ioctl has been called on a read-only
133    subdevice and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
134