media/v4l/crop.rst

1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
6 Image Cropping, Insertion and Scaling -- the CROP API
12    <selection-api>`. The new API should be preferred in most cases,
15    equivalent in the SELECTION API. See :ref:`selection-vs-crop` for a
34 device the source is the video signal, and the cropping ioctls determine
40 On a video output device the source are the images passed in by the
47 Source and target rectangles are defined even if the device does not
62 .. _crop-scale:
64 .. kernel-figure:: crop.svg
74 For capture devices the coordinates of the top left corner, width and
81 :ref:`vbi-hsync`). Vertically ITU-R line numbers of the first field
82 (see ITU R-525 line numbering for :ref:`525 lines <vbi-525>` and for
83 :ref:`625 lines <vbi-625>`), multiplied by two if the driver
86 The top left corner, width and height of the source rectangle, that is
95 Each capture device has a default source rectangle, given by the
117 lower size limits. In particular the maximum ``width`` and ``height`` in
131 Suppose scaling on a video capture device is restricted to a factor 1:1
155 reopening a device, such that piping data into or out of a device will
161    On the next two examples, a video capture device is assumed;
162    change ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other types of device.
167 .. code-block:: c
175     if (-1 == ioctl (fd, VIDIOC_CROPCAP, &cropcap)) {
186     if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop)
196 .. code-block:: c
209     format.fmt.pix.width = cropcap.defrect.width >> 1;
213     if (-1 == ioctl (fd, VIDIOC_S_FMT, &format)) {
224 .. note:: This example assumes an output device.
226 .. code-block:: c
234     if (-1 == ioctl (fd, VIDIOC_CROPCAP;, &cropcap)) {
244     /* Scale the width and height to 50 % of their original size
247     crop.c.width /= 2;
249     crop.c.left += crop.c.width / 2;
254     if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop)
263 .. note:: This example assumes a video capture device.
265 .. code-block:: c
277     if (-1 == ioctl (fd, VIDIOC_CROPCAP, &cropcap)) {
285     if (-1 == ioctl (fd, VIDIOC_G_CROP, &crop)) {
298     if (-1 == ioctl (fd, VIDIOC_G_FMT, &format)) {
305     hscale = format.fmt.pix.width / (double) crop.c.width;
312     /* Devices following ITU-R BT.601 do not capture
316     dwidth = format.fmt.pix.width / aspect;