Documentation/userspace-api/media/v4l/selection-api-configuration.rst

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