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