diff options
Diffstat (limited to 'Documentation/media/uapi/v4l/crop.rst')
| -rw-r--r-- | Documentation/media/uapi/v4l/crop.rst | 324 |
1 files changed, 0 insertions, 324 deletions
diff --git a/Documentation/media/uapi/v4l/crop.rst b/Documentation/media/uapi/v4l/crop.rst deleted file mode 100644 index ada7c22e6291..000000000000 --- a/Documentation/media/uapi/v4l/crop.rst +++ /dev/null @@ -1,324 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _crop: - -***************************************************** -Image Cropping, Insertion and Scaling -- the CROP API -***************************************************** - -.. note:: - - The CROP API is mostly superseded by the newer :ref:`SELECTION API - <selection-api>`. The new API should be preferred in most cases, - with the exception of pixel aspect ratio detection, which is - implemented by :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>` and has no - equivalent in the SELECTION API. See :ref:`selection-vs-crop` for a - comparison of the two APIs. - -Some video capture devices can sample a subsection of the picture and -shrink or enlarge it to an image of arbitrary size. We call these -abilities cropping and scaling. Some video output devices can scale an -image up or down and insert it at an arbitrary scan line and horizontal -offset into a video signal. - -Applications can use the following API to select an area in the video -signal, query the default area and the hardware limits. - -.. note:: - - Despite their name, the :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>`, - :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and :ref:`VIDIOC_S_CROP - <VIDIOC_G_CROP>` ioctls apply to input as well as output devices. - -Scaling requires a source and a target. On a video capture or overlay -device the source is the video signal, and the cropping ioctls determine -the area actually sampled. The target are images read by the application -or overlaid onto the graphics screen. Their size (and position for an -overlay) is negotiated with the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` -and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls. - -On a video output device the source are the images passed in by the -application, and their size is again negotiated with the -:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` -ioctls, or may be encoded in a compressed video stream. The target is -the video signal, and the cropping ioctls determine the area where the -images are inserted. - -Source and target rectangles are defined even if the device does not -support scaling or the :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and -:ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` ioctls. Their size (and position -where applicable) will be fixed in this case. - -.. note:: - - All capture and output devices that support the CROP or SELECTION - API will also support the :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>` - ioctl. - -Cropping Structures -=================== - - -.. _crop-scale: - -.. kernel-figure:: crop.svg - :alt: crop.svg - :align: center - - Image Cropping, Insertion and Scaling - - The cropping, insertion and scaling process - - - -For capture devices the coordinates of the top left corner, width and -height of the area which can be sampled is given by the ``bounds`` -substructure of the struct :c:type:`v4l2_cropcap` returned -by the :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>` ioctl. To support a wide -range of hardware this specification does not define an origin or units. -However by convention drivers should horizontally count unscaled samples -relative to 0H (the leading edge of the horizontal sync pulse, see -:ref:`vbi-hsync`). Vertically ITU-R line numbers of the first field -(see ITU R-525 line numbering for :ref:`525 lines <vbi-525>` and for -:ref:`625 lines <vbi-625>`), multiplied by two if the driver -can capture both fields. - -The top left corner, width and height of the source rectangle, that is -the area actually sampled, is given by struct -:c:type:`v4l2_crop` using the same coordinate system as -struct :c:type:`v4l2_cropcap`. Applications can use the -:ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` -ioctls to get and set this rectangle. It must lie completely within the -capture boundaries and the driver may further adjust the requested size -and/or position according to hardware limitations. - -Each capture device has a default source rectangle, given by the -``defrect`` substructure of struct -:c:type:`v4l2_cropcap`. The center of this rectangle -shall align with the center of the active picture area of the video -signal, and cover what the driver writer considers the complete picture. -Drivers shall reset the source rectangle to the default when the driver -is first loaded, but not later. - -For output devices these structures and ioctls are used accordingly, -defining the *target* rectangle where the images will be inserted into -the video signal. - - -Scaling Adjustments -=================== - -Video hardware can have various cropping, insertion and scaling -limitations. It may only scale up or down, support only discrete scaling -factors, or have different scaling abilities in horizontal and vertical -direction. Also it may not support scaling at all. At the same time the -struct :c:type:`v4l2_crop` rectangle may have to be aligned, -and both the source and target rectangles may have arbitrary upper and -lower size limits. In particular the maximum ``width`` and ``height`` in -struct :c:type:`v4l2_crop` may be smaller than the struct -:c:type:`v4l2_cropcap`. ``bounds`` area. Therefore, as -usual, drivers are expected to adjust the requested parameters and -return the actual values selected. - -Applications can change the source or the target rectangle first, as -they may prefer a particular image size or a certain area in the video -signal. If the driver has to adjust both to satisfy hardware -limitations, the last requested rectangle shall take priority, and the -driver should preferably adjust the opposite one. The -:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl however shall not change -the driver state and therefore only adjust the requested rectangle. - -Suppose scaling on a video capture device is restricted to a factor 1:1 -or 2:1 in either direction and the target image size must be a multiple -of 16 × 16 pixels. The source cropping rectangle is set to defaults, -which are also the upper limit in this example, of 640 × 400 pixels at -offset 0, 0. An application requests an image size of 300 × 225 pixels, -assuming video will be scaled down from the "full picture" accordingly. -The driver sets the image size to the closest possible values 304 × 224, -then chooses the cropping rectangle closest to the requested size, that -is 608 × 224 (224 × 2:1 would exceed the limit 400). The offset 0, 0 is -still valid, thus unmodified. Given the default cropping rectangle -reported by :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>` the application can -easily propose another offset to center the cropping rectangle. - -Now the application may insist on covering an area using a picture -aspect ratio closer to the original request, so it asks for a cropping -rectangle of 608 × 456 pixels. The present scaling factors limit -cropping to 640 × 384, so the driver returns the cropping size 608 × 384 -and adjusts the image size to closest possible 304 × 192. - - -Examples -======== - -Source and target rectangles shall remain unchanged across closing and -reopening a device, such that piping data into or out of a device will -work without special preparations. More advanced applications should -ensure the parameters are suitable before starting I/O. - -.. note:: - - On the next two examples, a video capture device is assumed; - change ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other types of device. - -Example: Resetting the cropping parameters -========================================== - -.. code-block:: c - - struct v4l2_cropcap cropcap; - struct v4l2_crop crop; - - memset (&cropcap, 0, sizeof (cropcap)); - cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - - if (-1 == ioctl (fd, VIDIOC_CROPCAP, &cropcap)) { - perror ("VIDIOC_CROPCAP"); - exit (EXIT_FAILURE); - } - - memset (&crop, 0, sizeof (crop)); - crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - crop.c = cropcap.defrect; - - /* Ignore if cropping is not supported (EINVAL). */ - - if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop) - && errno != EINVAL) { - perror ("VIDIOC_S_CROP"); - exit (EXIT_FAILURE); - } - - -Example: Simple downscaling -=========================== - -.. code-block:: c - - struct v4l2_cropcap cropcap; - struct v4l2_format format; - - reset_cropping_parameters (); - - /* Scale down to 1/4 size of full picture. */ - - memset (&format, 0, sizeof (format)); /* defaults */ - - format.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - - format.fmt.pix.width = cropcap.defrect.width >> 1; - format.fmt.pix.height = cropcap.defrect.height >> 1; - format.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV; - - if (-1 == ioctl (fd, VIDIOC_S_FMT, &format)) { - perror ("VIDIOC_S_FORMAT"); - exit (EXIT_FAILURE); - } - - /* We could check the actual image size now, the actual scaling factor - or if the driver can scale at all. */ - -Example: Selecting an output area -================================= - -.. note:: This example assumes an output device. - -.. code-block:: c - - struct v4l2_cropcap cropcap; - struct v4l2_crop crop; - - memset (&cropcap, 0, sizeof (cropcap)); - cropcap.type = V4L2_BUF_TYPE_VIDEO_OUTPUT; - - if (-1 == ioctl (fd, VIDIOC_CROPCAP;, &cropcap)) { - perror ("VIDIOC_CROPCAP"); - exit (EXIT_FAILURE); - } - - memset (&crop, 0, sizeof (crop)); - - crop.type = V4L2_BUF_TYPE_VIDEO_OUTPUT; - crop.c = cropcap.defrect; - - /* Scale the width and height to 50 % of their original size - and center the output. */ - - crop.c.width /= 2; - crop.c.height /= 2; - crop.c.left += crop.c.width / 2; - crop.c.top += crop.c.height / 2; - - /* Ignore if cropping is not supported (EINVAL). */ - - if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop) - && errno != EINVAL) { - perror ("VIDIOC_S_CROP"); - exit (EXIT_FAILURE); - } - -Example: Current scaling factor and pixel aspect -================================================ - -.. note:: This example assumes a video capture device. - -.. code-block:: c - - struct v4l2_cropcap cropcap; - struct v4l2_crop crop; - struct v4l2_format format; - double hscale, vscale; - double aspect; - int dwidth, dheight; - - memset (&cropcap, 0, sizeof (cropcap)); - cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - - if (-1 == ioctl (fd, VIDIOC_CROPCAP, &cropcap)) { - perror ("VIDIOC_CROPCAP"); - exit (EXIT_FAILURE); - } - - memset (&crop, 0, sizeof (crop)); - crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - - if (-1 == ioctl (fd, VIDIOC_G_CROP, &crop)) { - if (errno != EINVAL) { - perror ("VIDIOC_G_CROP"); - exit (EXIT_FAILURE); - } - - /* Cropping not supported. */ - crop.c = cropcap.defrect; - } - - memset (&format, 0, sizeof (format)); - format.fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - - if (-1 == ioctl (fd, VIDIOC_G_FMT, &format)) { - perror ("VIDIOC_G_FMT"); - exit (EXIT_FAILURE); - } - - /* The scaling applied by the driver. */ - - hscale = format.fmt.pix.width / (double) crop.c.width; - vscale = format.fmt.pix.height / (double) crop.c.height; - - aspect = cropcap.pixelaspect.numerator / - (double) cropcap.pixelaspect.denominator; - aspect = aspect * hscale / vscale; - - /* Devices following ITU-R BT.601 do not capture - square pixels. For playback on a computer monitor - we should scale the images to this size. */ - - dwidth = format.fmt.pix.width / aspect; - dheight = format.fmt.pix.height; |