Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
af4a4d0d | 3 | .. _VIDIOC_G_CROP: |
5377d91f MH |
4 | |
5 | ********************************** | |
6 | ioctl VIDIOC_G_CROP, VIDIOC_S_CROP | |
7 | ********************************** | |
8 | ||
9 | *man VIDIOC_G_CROP(2)* | |
10 | ||
11 | VIDIOC_S_CROP | |
12 | Get or set the current cropping rectangle | |
13 | ||
14 | ||
15 | Synopsis | |
16 | ======== | |
17 | ||
18 | .. c:function:: int ioctl( int fd, int request, struct v4l2_crop *argp ) | |
19 | ||
20 | .. c:function:: int ioctl( int fd, int request, const struct v4l2_crop *argp ) | |
21 | ||
22 | Arguments | |
23 | ========= | |
24 | ||
25 | ``fd`` | |
26 | File descriptor returned by :ref:`open() <func-open>`. | |
27 | ||
28 | ``request`` | |
29 | VIDIOC_G_CROP, VIDIOC_S_CROP | |
30 | ||
31 | ``argp`` | |
32 | ||
33 | ||
34 | Description | |
35 | =========== | |
36 | ||
37 | To query the cropping rectangle size and position applications set the | |
38 | ``type`` field of a :c:type:`struct v4l2_crop` structure to the | |
39 | respective buffer (stream) type and call the ``VIDIOC_G_CROP`` ioctl | |
40 | with a pointer to this structure. The driver fills the rest of the | |
41 | structure or returns the EINVAL error code if cropping is not supported. | |
42 | ||
43 | To change the cropping rectangle applications initialize the ``type`` | |
44 | and struct :ref:`v4l2_rect <v4l2-rect>` substructure named ``c`` of a | |
45 | v4l2_crop structure and call the ``VIDIOC_S_CROP`` ioctl with a pointer | |
46 | to this structure. | |
47 | ||
48 | Do not use the multiplanar buffer types. Use | |
49 | ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` instead of | |
50 | ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and use | |
51 | ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` instead of | |
52 | ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``. | |
53 | ||
54 | The driver first adjusts the requested dimensions against hardware | |
55 | limits, i. e. the bounds given by the capture/output window, and it | |
56 | rounds to the closest possible values of horizontal and vertical offset, | |
57 | width and height. In particular the driver must round the vertical | |
58 | offset of the cropping rectangle to frame lines modulo two, such that | |
59 | the field order cannot be confused. | |
60 | ||
61 | Second the driver adjusts the image size (the opposite rectangle of the | |
62 | scaling process, source or target depending on the data direction) to | |
63 | the closest size possible while maintaining the current horizontal and | |
64 | vertical scaling factor. | |
65 | ||
66 | Finally the driver programs the hardware with the actual cropping and | |
67 | image parameters. ``VIDIOC_S_CROP`` is a write-only ioctl, it does not | |
68 | return the actual parameters. To query them applications must call | |
af4a4d0d | 69 | ``VIDIOC_G_CROP`` and :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`. When the |
5377d91f MH |
70 | parameters are unsuitable the application may modify the cropping or |
71 | image parameters and repeat the cycle until satisfactory parameters have | |
72 | been negotiated. | |
73 | ||
74 | When cropping is not supported then no parameters are changed and | |
75 | ``VIDIOC_S_CROP`` returns the EINVAL error code. | |
76 | ||
77 | ||
78 | .. _v4l2-crop: | |
79 | ||
80 | .. flat-table:: struct v4l2_crop | |
81 | :header-rows: 0 | |
82 | :stub-columns: 0 | |
83 | :widths: 1 1 2 | |
84 | ||
85 | ||
86 | - .. row 1 | |
87 | ||
88 | - __u32 | |
89 | ||
90 | - ``type`` | |
91 | ||
92 | - Type of the data stream, set by the application. Only these types | |
93 | are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``, | |
94 | ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` and | |
95 | ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :ref:`v4l2-buf-type`. | |
96 | ||
97 | - .. row 2 | |
98 | ||
99 | - struct :ref:`v4l2_rect <v4l2-rect>` | |
100 | ||
101 | - ``c`` | |
102 | ||
103 | - Cropping rectangle. The same co-ordinate system as for struct | |
104 | :ref:`v4l2_cropcap <v4l2-cropcap>` ``bounds`` is used. | |
105 | ||
106 | ||
107 | ||
108 | Return Value | |
109 | ============ | |
110 | ||
111 | On success 0 is returned, on error -1 and the ``errno`` variable is set | |
112 | appropriately. The generic error codes are described at the | |
113 | :ref:`Generic Error Codes <gen-errors>` chapter. | |
114 | ||
115 | ||
116 | .. ------------------------------------------------------------------------------ | |
117 | .. This file was automatically converted from DocBook-XML with the dbxml | |
118 | .. library (https://github.com/return42/sphkerneldoc). The origin XML comes | |
119 | .. from the linux kernel, refer to: | |
120 | .. | |
121 | .. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook | |
122 | .. ------------------------------------------------------------------------------ |