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_CROPCAP:
11
12********************
13ioctl VIDIOC_CROPCAP
14********************
15
16Name
17====
18
19VIDIOC_CROPCAP - Information about the video cropping and scaling abilities
20
21
22Synopsis
23========
24
25.. c:function:: int ioctl( int fd, VIDIOC_CROPCAP, struct v4l2_cropcap *argp )
26    :name: VIDIOC_CROPCAP
27
28
29Arguments
30=========
31
32``fd``
33    File descriptor returned by :ref:`open() <func-open>`.
34
35``argp``
36    Pointer to struct :c:type:`v4l2_cropcap`.
37
38
39Description
40===========
41
42Applications use this function to query the cropping limits, the pixel
43aspect of images and to calculate scale factors. They set the ``type``
44field of a v4l2_cropcap structure to the respective buffer (stream)
45type and call the :ref:`VIDIOC_CROPCAP` ioctl with a pointer to this
46structure. Drivers fill the rest of the structure. The results are
47constant except when switching the video standard. Remember this switch
48can occur implicit when switching the video input or output.
49
50This ioctl must be implemented for video capture or output devices that
51support cropping and/or scaling and/or have non-square pixels, and for
52overlay devices.
53
54.. c:type:: v4l2_cropcap
55
56.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
57
58.. flat-table:: struct v4l2_cropcap
59    :header-rows:  0
60    :stub-columns: 0
61    :widths:       1 1 2
62
63    * - __u32
64      - ``type``
65      - Type of the data stream, set by the application. Only these types
66	are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``, ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``,
67	``V4L2_BUF_TYPE_VIDEO_OUTPUT``, ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` and
68	``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :c:type:`v4l2_buf_type` and the note below.
69    * - struct :ref:`v4l2_rect <v4l2-rect-crop>`
70      - ``bounds``
71      - Defines the window within capturing or output is possible, this
72	may exclude for example the horizontal and vertical blanking
73	areas. The cropping rectangle cannot exceed these limits. Width
74	and height are defined in pixels, the driver writer is free to
75	choose origin and units of the coordinate system in the analog
76	domain.
77    * - struct :ref:`v4l2_rect <v4l2-rect-crop>`
78      - ``defrect``
79      - Default cropping rectangle, it shall cover the "whole picture".
80	Assuming pixel aspect 1/1 this could be for example a 640 × 480
81	rectangle for NTSC, a 768 × 576 rectangle for PAL and SECAM
82	centered over the active picture area. The same co-ordinate system
83	as for ``bounds`` is used.
84    * - struct :c:type:`v4l2_fract`
85      - ``pixelaspect``
86      - This is the pixel aspect (y / x) when no scaling is applied, the
87	ratio of the actual sampling frequency and the frequency required
88	to get square pixels.
89
90	When cropping coordinates refer to square pixels, the driver sets
91	``pixelaspect`` to 1/1. Other common values are 54/59 for PAL and
92	SECAM, 11/10 for NTSC sampled according to [:ref:`itu601`].
93
94.. note::
95   Unfortunately in the case of multiplanar buffer types
96   (``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``)
97   this API was messed up with regards to how the :c:type:`v4l2_cropcap` ``type`` field
98   should be filled in. Some drivers only accepted the ``_MPLANE`` buffer type while
99   other drivers only accepted a non-multiplanar buffer type (i.e. without the
100   ``_MPLANE`` at the end).
101
102   Starting with kernel 4.13 both variations are allowed.
103
104
105
106.. _v4l2-rect-crop:
107
108.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
109
110.. flat-table:: struct v4l2_rect
111    :header-rows:  0
112    :stub-columns: 0
113    :widths:       1 1 2
114
115    * - __s32
116      - ``left``
117      - Horizontal offset of the top, left corner of the rectangle, in
118	pixels.
119    * - __s32
120      - ``top``
121      - Vertical offset of the top, left corner of the rectangle, in
122	pixels.
123    * - __u32
124      - ``width``
125      - Width of the rectangle, in pixels.
126    * - __u32
127      - ``height``
128      - Height of the rectangle, in pixels.
129
130
131Return Value
132============
133
134On success 0 is returned, on error -1 and the ``errno`` variable is set
135appropriately. The generic error codes are described at the
136:ref:`Generic Error Codes <gen-errors>` chapter.
137
138EINVAL
139    The struct :c:type:`v4l2_cropcap` ``type`` is
140    invalid.
141
142ENODATA
143    Cropping is not supported for this input or output.
144