Documentation/media/uapi/v4l/selection-api-configuration.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 Configuration
  12 *************
  13
  14 Applications can use the :ref:`selection API <VIDIOC_G_SELECTION>` to
  15 select an area in a video signal or a buffer, and to query for default
  16 settings and hardware limits.
  17
  18 Video hardware can have various cropping, composing and scaling
  19 limitations. It may only scale up or down, support only discrete scaling
  20 factors, or have different scaling abilities in the horizontal and
  21 vertical directions. Also it may not support scaling at all. At the same
  22 time the cropping/composing rectangles may have to be aligned, and both
  23 the source and the sink may have arbitrary upper and lower size limits.
  24 Therefore, as usual, drivers are expected to adjust the requested
  25 parameters and return the actual values selected. An application can
  26 control the rounding behaviour using
  27 :ref:`constraint flags <v4l2-selection-flags>`.
  28
  29
  30 Configuration of video capture
  31 ==============================
  32
  33 See figure :ref:`sel-targets-capture` for examples of the selection
  34 targets available for a video capture device. It is recommended to
  35 configure the cropping targets before to the composing targets.
  36
  37 The range of coordinates of the top left corner, width and height of
  38 areas that can be sampled is given by the ``V4L2_SEL_TGT_CROP_BOUNDS``
  39 target. It is recommended for the driver developers to put the top/left
  40 corner at position ``(0,0)``. The rectangle's coordinates are expressed
  41 in pixels.
  42
  43 The top left corner, width and height of the source rectangle, that is
  44 the area actually sampled, is given by the ``V4L2_SEL_TGT_CROP`` target.
  45 It uses the same coordinate system as ``V4L2_SEL_TGT_CROP_BOUNDS``. The
  46 active cropping area must lie completely inside the capture boundaries.
  47 The driver may further adjust the requested size and/or position
  48 according to hardware limitations.
  49
  50 Each capture device has a default source rectangle, given by the
  51 ``V4L2_SEL_TGT_CROP_DEFAULT`` target. This rectangle shall cover what the
  52 driver writer considers the complete picture. Drivers shall set the
  53 active crop rectangle to the default when the driver is first loaded,
  54 but not later.
  55
  56 The composing targets refer to a memory buffer. The limits of composing
  57 coordinates are obtained using ``V4L2_SEL_TGT_COMPOSE_BOUNDS``. All
  58 coordinates are expressed in pixels. The rectangle's top/left corner
  59 must be located at position ``(0,0)``. The width and height are equal to
  60 the image size set by :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`.
  61
  62 The part of a buffer into which the image is inserted by the hardware is
  63 controlled by the ``V4L2_SEL_TGT_COMPOSE`` target. The rectangle's
  64 coordinates are also expressed in the same coordinate system as the
  65 bounds rectangle. The composing rectangle must lie completely inside
  66 bounds rectangle. The driver must adjust the composing rectangle to fit
  67 to the bounding limits. Moreover, the driver can perform other
  68 adjustments according to hardware limitations. The application can
  69 control rounding behaviour using
  70 :ref:`constraint flags <v4l2-selection-flags>`.
  71
  72 For capture devices the default composing rectangle is queried using
  73 ``V4L2_SEL_TGT_COMPOSE_DEFAULT``. It is usually equal to the bounding
  74 rectangle.
  75
  76 The part of a buffer that is modified by the hardware is given by
  77 ``V4L2_SEL_TGT_COMPOSE_PADDED``. It contains all pixels defined using
  78 ``V4L2_SEL_TGT_COMPOSE`` plus all padding data modified by hardware
  79 during insertion process. All pixels outside this rectangle *must not*
  80 be changed by the hardware. The content of pixels that lie inside the
  81 padded area but outside active area is undefined. The application can
  82 use the padded and active rectangles to detect where the rubbish pixels
  83 are located and remove them if needed.
  84
  85
  86 Configuration of video output
  87 =============================
  88
  89 For output devices targets and ioctls are used similarly to the video
  90 capture case. The *composing* rectangle refers to the insertion of an
  91 image into a video signal. The cropping rectangles refer to a memory
  92 buffer. It is recommended to configure the composing targets before to
  93 the cropping targets.
  94
  95 The cropping targets refer to the memory buffer that contains an image
  96 to be inserted into a video signal or graphical screen. The limits of
  97 cropping coordinates are obtained using ``V4L2_SEL_TGT_CROP_BOUNDS``.
  98 All coordinates are expressed in pixels. The top/left corner is always
  99 point ``(0,0)``. The width and height is equal to the image size
 100 specified using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
 101
 102 The top left corner, width and height of the source rectangle, that is
 103 the area from which image date are processed by the hardware, is given
 104 by the ``V4L2_SEL_TGT_CROP``. Its coordinates are expressed in in the
 105 same coordinate system as the bounds rectangle. The active cropping area
 106 must lie completely inside the crop boundaries and the driver may
 107 further adjust the requested size and/or position according to hardware
 108 limitations.
 109
 110 For output devices the default cropping rectangle is queried using
 111 ``V4L2_SEL_TGT_CROP_DEFAULT``. It is usually equal to the bounding
 112 rectangle.
 113
 114 The part of a video signal or graphics display where the image is
 115 inserted by the hardware is controlled by ``V4L2_SEL_TGT_COMPOSE``
 116 target. The rectangle's coordinates are expressed in pixels. The
 117 composing rectangle must lie completely inside the bounds rectangle. The
 118 driver must adjust the area to fit to the bounding limits. Moreover, the
 119 driver can perform other adjustments according to hardware limitations.
 120
 121 The device has a default composing rectangle, given by the
 122 ``V4L2_SEL_TGT_COMPOSE_DEFAULT`` target. This rectangle shall cover what
 123 the driver writer considers the complete picture. It is recommended for
 124 the driver developers to put the top/left corner at position ``(0,0)``.
 125 Drivers shall set the active composing rectangle to the default one when
 126 the driver is first loaded.
 127
 128 The devices may introduce additional content to video signal other than
 129 an image from memory buffers. It includes borders around an image.
 130 However, such a padded area is driver-dependent feature not covered by
 131 this document. Driver developers are encouraged to keep padded rectangle
 132 equal to active one. The padded target is accessed by the
 133 ``V4L2_SEL_TGT_COMPOSE_PADDED`` identifier. It must contain all pixels
 134 from the ``V4L2_SEL_TGT_COMPOSE`` target.
 135
 136
 137 Scaling control
 138 ===============
 139
 140 An application can detect if scaling is performed by comparing the width
 141 and the height of rectangles obtained using ``V4L2_SEL_TGT_CROP`` and
 142 ``V4L2_SEL_TGT_COMPOSE`` targets. If these are not equal then the
 143 scaling is applied. The application can compute the scaling ratios using
 144 these values.