xref: /openbmc/linux/Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst (revision 54f38fcae536ea202ce7d6a359521492fba30c1f)
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
56
57Types of selection targets
58--------------------------
59
60There are two types of selection targets: actual and bounds. The actual
61targets are the targets which configure the hardware. The BOUNDS target
62will return a rectangle that contain all possible actual rectangles.
63
64
65Discovering supported features
66------------------------------
67
68To discover which targets are supported, the user can perform
69``VIDIOC_SUBDEV_G_SELECTION`` on them. Any unsupported target will
70return ``EINVAL``.
71
72Selection targets and flags are documented in
73:ref:`v4l2-selections-common`.
74
75
76.. c:type:: v4l2_subdev_selection
77
78.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
79
80.. flat-table:: struct v4l2_subdev_selection
81    :header-rows:  0
82    :stub-columns: 0
83    :widths:       1 1 2
84
85    * - __u32
86      - ``which``
87      - Active or try selection, from enum
88	:ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
89    * - __u32
90      - ``pad``
91      - Pad number as reported by the media framework.
92    * - __u32
93      - ``target``
94      - Target selection rectangle. See :ref:`v4l2-selections-common`.
95    * - __u32
96      - ``flags``
97      - Flags. See :ref:`v4l2-selection-flags`.
98    * - struct :c:type:`v4l2_rect`
99      - ``r``
100      - Selection rectangle, in pixels.
101    * - __u32
102      - ``reserved``\ [8]
103      - Reserved for future extensions. Applications and drivers must set
104	the array to zero.
105
106
107Return Value
108============
109
110On success 0 is returned, on error -1 and the ``errno`` variable is set
111appropriately. The generic error codes are described at the
112:ref:`Generic Error Codes <gen-errors>` chapter.
113
114EBUSY
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``
120
121EINVAL
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.
126