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_G_CROP:
11
12**********************************
13ioctl VIDIOC_G_CROP, VIDIOC_S_CROP
14**********************************
15
16Name
17====
18
19VIDIOC_G_CROP - VIDIOC_S_CROP - Get or set the current cropping rectangle
20
21
22Synopsis
23========
24
25.. c:function:: int ioctl( int fd, VIDIOC_G_CROP, struct v4l2_crop *argp )
26    :name: VIDIOC_G_CROP
27
28.. c:function:: int ioctl( int fd, VIDIOC_S_CROP, const struct v4l2_crop *argp )
29    :name: VIDIOC_S_CROP
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_crop`.
40
41
42Description
43===========
44
45To query the cropping rectangle size and position applications set the
46``type`` field of a struct :c:type:`v4l2_crop` structure to the
47respective buffer (stream) type and call the :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` ioctl
48with a pointer to this structure. The driver fills the rest of the
49structure or returns the ``EINVAL`` error code if cropping is not supported.
50
51To change the cropping rectangle applications initialize the ``type``
52and struct :c:type:`v4l2_rect` substructure named ``c`` of a
53v4l2_crop structure and call the :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` ioctl with a pointer
54to this structure.
55
56The driver first adjusts the requested dimensions against hardware
57limits, i. e. the bounds given by the capture/output window, and it
58rounds to the closest possible values of horizontal and vertical offset,
59width and height. In particular the driver must round the vertical
60offset of the cropping rectangle to frame lines modulo two, such that
61the field order cannot be confused.
62
63Second the driver adjusts the image size (the opposite rectangle of the
64scaling process, source or target depending on the data direction) to
65the closest size possible while maintaining the current horizontal and
66vertical scaling factor.
67
68Finally the driver programs the hardware with the actual cropping and
69image parameters. :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` is a write-only ioctl, it does not
70return the actual parameters. To query them applications must call
71:ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and :ref:`VIDIOC_G_FMT`. When the
72parameters are unsuitable the application may modify the cropping or
73image parameters and repeat the cycle until satisfactory parameters have
74been negotiated.
75
76When cropping is not supported then no parameters are changed and
77:ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` returns the ``EINVAL`` error code.
78
79
80.. c:type:: v4l2_crop
81
82.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
83
84.. flat-table:: struct v4l2_crop
85    :header-rows:  0
86    :stub-columns: 0
87    :widths:       1 1 2
88
89    * - __u32
90      - ``type``
91      - Type of the data stream, set by the application. Only these types
92	are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``, ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``,
93	``V4L2_BUF_TYPE_VIDEO_OUTPUT``, ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` and
94	``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :c:type:`v4l2_buf_type` and the note below.
95    * - struct :c:type:`v4l2_rect`
96      - ``c``
97      - Cropping rectangle. The same co-ordinate system as for struct
98	:c:type:`v4l2_cropcap` ``bounds`` is used.
99
100.. note::
101   Unfortunately in the case of multiplanar buffer types
102   (``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``)
103   this API was messed up with regards to how the :c:type:`v4l2_crop` ``type`` field
104   should be filled in. Some drivers only accepted the ``_MPLANE`` buffer type while
105   other drivers only accepted a non-multiplanar buffer type (i.e. without the
106   ``_MPLANE`` at the end).
107
108   Starting with kernel 4.13 both variations are allowed.
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
118ENODATA
119    Cropping is not supported for this input or output.
120