selection-api-configuration.rst

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