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. *Despite their
-name, the :ref:`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.*
+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
On a video output device the source are the images passed in by the
application, and their size is again negotiated with the
-``VIDIOC_G/S_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.
+: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 ``VIDIOC_G/S_CROP`` ioctls. Their size (and
-position where applicable) will be fixed in this case. *All capture and
-output device must support the ``VIDIOC_CROPCAP`` ioctl such that
-applications can determine if scaling takes place.*
+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 must support the
+:ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>` ioctl such that applications can
+determine if scaling takes place.
Cropping Structures
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 :ref:`v4l2_cropcap <v4l2-cropcap>`
-returned by the ``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
+substructure of the struct :ref:`v4l2_cropcap <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
-(:ref:`vbi-525`, :ref:`vbi-625`), multiplied by two if the driver
+(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
:ref:`v4l2_crop <v4l2-crop>` using the same coordinate system as
struct :ref:`v4l2_cropcap <v4l2-cropcap>`. Applications can use the
-``VIDIOC_G_CROP`` and ``VIDIOC_S_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.
+: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
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 ``VIDIOC_CROPCAP`` the application can easily propose
-another offset to center the 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
work without special preparations. More advanced applications should
ensure the parameters are suitable before starting I/O.
-(A video capture device is assumed; change
-``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other devices.)
-
+**NOTE:** on the next two examples, a video capture device is assumed;
+change ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other types of device.
.. code-block:: c
+ :caption: Example 11: Resetting the cropping parameters
struct v4l2_cropcap cropcap;
struct v4l2_crop crop;
cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
if (-1 == ioctl (fd, VIDIOC_CROPCAP, &cropcap)) {
- perror ("VIDIOC_CROPCAP");
- exit (EXIT_FAILURE);
+ perror ("VIDIOC_CROPCAP");
+ exit (EXIT_FAILURE);
}
memset (&crop, 0, sizeof (crop));
/* Ignore if cropping is not supported (EINVAL). */
if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop)
- && errno != EINVAL) {
- perror ("VIDIOC_S_CROP");
- exit (EXIT_FAILURE);
+ && errno != EINVAL) {
+ perror ("VIDIOC_S_CROP");
+ exit (EXIT_FAILURE);
}
-(A video capture device is assumed.)
-
-
.. code-block:: c
+ :caption: Example 12: Simple downscaling
struct v4l2_cropcap cropcap;
struct v4l2_format format;
format.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;
if (-1 == ioctl (fd, VIDIOC_S_FMT, &format)) {
- perror ("VIDIOC_S_FORMAT");
- exit (EXIT_FAILURE);
+ 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. */
+**NOTE:** This example assumes an output device.
.. code-block:: c
+ :caption: Example 13. Selecting an output area
struct v4l2_cropcap cropcap;
struct v4l2_crop crop;
cropcap.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
if (-1 == ioctl (fd, VIDIOC_CROPCAP;, &cropcap)) {
- perror ("VIDIOC_CROPCAP");
- exit (EXIT_FAILURE);
+ perror ("VIDIOC_CROPCAP");
+ exit (EXIT_FAILURE);
}
memset (&crop, 0, sizeof (crop));
/* Ignore if cropping is not supported (EINVAL). */
if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop)
- && errno != EINVAL) {
- perror ("VIDIOC_S_CROP");
- exit (EXIT_FAILURE);
+ && errno != EINVAL) {
+ perror ("VIDIOC_S_CROP");
+ exit (EXIT_FAILURE);
}
-(A video capture device is assumed.)
-
+**NOTE:** This example assumes a video capture device.
.. code-block:: c
+ :caption: Example 14: Current scaling factor and pixel aspect
struct v4l2_cropcap cropcap;
struct v4l2_crop crop;
cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
if (-1 == ioctl (fd, VIDIOC_CROPCAP, &cropcap)) {
- perror ("VIDIOC_CROPCAP");
- exit (EXIT_FAILURE);
+ 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);
- }
+ if (errno != EINVAL) {
+ perror ("VIDIOC_G_CROP");
+ exit (EXIT_FAILURE);
+ }
- /* Cropping not supported. */
- crop.c = cropcap.defrect;
+ /* 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);
+ perror ("VIDIOC_G_FMT");
+ exit (EXIT_FAILURE);
}
/* The scaling applied by the driver. */
vscale = format.fmt.pix.height / (double) crop.c.height;
aspect = cropcap.pixelaspect.numerator /
- (double) cropcap.pixelaspect.denominator;
+ (double) cropcap.pixelaspect.denominator;
aspect = aspect * hscale / vscale;
/* Devices following ITU-R BT.601 do not capture
dheight = format.fmt.pix.height;
-
-
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
projects / linux-beck.git / commitdiff