Documentation/media/uapi/v4l/selection-api-examples.rst

   1 .. Permission is granted to copy, distribute and/or modify this
   2 .. document under the terms of the GNU Free Documentation License,
   3 .. Version 1.1 or any later version published by the Free Software
   4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
   5 .. and no Back-Cover Texts. A copy of the license is included at
   6 .. Documentation/media/uapi/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 ********
  11 Examples
  12 ********
  13
  14 (A video capture device is assumed; change
  15 ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other devices; change target to
  16 ``V4L2_SEL_TGT_COMPOSE_*`` family to configure composing area)
  17
  18 Example: Resetting the cropping parameters
  19 ==========================================
  20
  21 .. code-block:: c
  22
  23         struct v4l2_selection sel = {
  24             .type = V4L2_BUF_TYPE_VIDEO_CAPTURE,
  25             .target = V4L2_SEL_TGT_CROP_DEFAULT,
  26         };
  27         ret = ioctl(fd, VIDIOC_G_SELECTION, &sel);
  28         if (ret)
  29             exit(-1);
  30         sel.target = V4L2_SEL_TGT_CROP;
  31         ret = ioctl(fd, VIDIOC_S_SELECTION, &sel);
  32         if (ret)
  33             exit(-1);
  34
  35 Setting a composing area on output of size of *at most* half of limit
  36 placed at a center of a display.
  37
  38 Example: Simple downscaling
  39 ===========================
  40
  41 .. code-block:: c
  42
  43         struct v4l2_selection sel = {
  44             .type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
  45             .target = V4L2_SEL_TGT_COMPOSE_BOUNDS,
  46         };
  47         struct v4l2_rect r;
  48
  49         ret = ioctl(fd, VIDIOC_G_SELECTION, &sel);
  50         if (ret)
  51             exit(-1);
  52         /* setting smaller compose rectangle */
  53         r.width = sel.r.width / 2;
  54         r.height = sel.r.height / 2;
  55         r.left = sel.r.width / 4;
  56         r.top = sel.r.height / 4;
  57         sel.r = r;
  58         sel.target = V4L2_SEL_TGT_COMPOSE;
  59         sel.flags = V4L2_SEL_FLAG_LE;
  60         ret = ioctl(fd, VIDIOC_S_SELECTION, &sel);
  61         if (ret)
  62             exit(-1);
  63
  64 A video output device is assumed; change ``V4L2_BUF_TYPE_VIDEO_OUTPUT``
  65 for other devices
  66
  67 Example: Querying for scaling factors
  68 =====================================
  69
  70 .. code-block:: c
  71
  72         struct v4l2_selection compose = {
  73             .type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
  74             .target = V4L2_SEL_TGT_COMPOSE,
  75         };
  76         struct v4l2_selection crop = {
  77             .type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
  78             .target = V4L2_SEL_TGT_CROP,
  79         };
  80         double hscale, vscale;
  81
  82         ret = ioctl(fd, VIDIOC_G_SELECTION, &compose);
  83         if (ret)
  84             exit(-1);
  85         ret = ioctl(fd, VIDIOC_G_SELECTION, &crop);
  86         if (ret)
  87             exit(-1);
  88
  89         /* computing scaling factors */
  90         hscale = (double)compose.r.width / crop.r.width;
  91         vscale = (double)compose.r.height / crop.r.height;