0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002
0003 *************
0004 Configuration
0005 *************
0006
0007 Applications can use the :ref:`selection API <VIDIOC_G_SELECTION>` to
0008 select an area in a video signal or a buffer, and to query for default
0009 settings and hardware limits.
0010
0011 Video hardware can have various cropping, composing and scaling
0012 limitations. It may only scale up or down, support only discrete scaling
0013 factors, or have different scaling abilities in the horizontal and
0014 vertical directions. Also it may not support scaling at all. At the same
0015 time the cropping/composing rectangles may have to be aligned, and both
0016 the source and the sink may have arbitrary upper and lower size limits.
0017 Therefore, as usual, drivers are expected to adjust the requested
0018 parameters and return the actual values selected. An application can
0019 control the rounding behaviour using
0020 :ref:`constraint flags <v4l2-selection-flags>`.
0021
0022
0023 Configuration of video capture
0024 ==============================
0025
0026 See figure :ref:`sel-targets-capture` for examples of the selection
0027 targets available for a video capture device. It is recommended to
0028 configure the cropping targets before to the composing targets.
0029
0030 The range of coordinates of the top left corner, width and height of
0031 areas that can be sampled is given by the ``V4L2_SEL_TGT_CROP_BOUNDS``
0032 target. It is recommended for the driver developers to put the top/left
0033 corner at position ``(0,0)``. The rectangle's coordinates are expressed
0034 in pixels.
0035
0036 The top left corner, width and height of the source rectangle, that is
0037 the area actually sampled, is given by the ``V4L2_SEL_TGT_CROP`` target.
0038 It uses the same coordinate system as ``V4L2_SEL_TGT_CROP_BOUNDS``. The
0039 active cropping area must lie completely inside the capture boundaries.
0040 The driver may further adjust the requested size and/or position
0041 according to hardware limitations.
0042
0043 Each capture device has a default source rectangle, given by the
0044 ``V4L2_SEL_TGT_CROP_DEFAULT`` target. This rectangle shall cover what the
0045 driver writer considers the complete picture. Drivers shall set the
0046 active crop rectangle to the default when the driver is first loaded,
0047 but not later.
0048
0049 The composing targets refer to a memory buffer. The limits of composing
0050 coordinates are obtained using ``V4L2_SEL_TGT_COMPOSE_BOUNDS``. All
0051 coordinates are expressed in pixels. The rectangle's top/left corner
0052 must be located at position ``(0,0)``. The width and height are equal to
0053 the image size set by :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`.
0054
0055 The part of a buffer into which the image is inserted by the hardware is
0056 controlled by the ``V4L2_SEL_TGT_COMPOSE`` target. The rectangle's
0057 coordinates are also expressed in the same coordinate system as the
0058 bounds rectangle. The composing rectangle must lie completely inside
0059 bounds rectangle. The driver must adjust the composing rectangle to fit
0060 to the bounding limits. Moreover, the driver can perform other
0061 adjustments according to hardware limitations. The application can
0062 control rounding behaviour using
0063 :ref:`constraint flags <v4l2-selection-flags>`.
0064
0065 For capture devices the default composing rectangle is queried using
0066 ``V4L2_SEL_TGT_COMPOSE_DEFAULT``. It is usually equal to the bounding
0067 rectangle.
0068
0069 The part of a buffer that is modified by the hardware is given by
0070 ``V4L2_SEL_TGT_COMPOSE_PADDED``. It contains all pixels defined using
0071 ``V4L2_SEL_TGT_COMPOSE`` plus all padding data modified by hardware
0072 during insertion process. All pixels outside this rectangle *must not*
0073 be changed by the hardware. The content of pixels that lie inside the
0074 padded area but outside active area is undefined. The application can
0075 use the padded and active rectangles to detect where the rubbish pixels
0076 are located and remove them if needed.
0077
0078
0079 Configuration of video output
0080 =============================
0081
0082 For output devices targets and ioctls are used similarly to the video
0083 capture case. The *composing* rectangle refers to the insertion of an
0084 image into a video signal. The cropping rectangles refer to a memory
0085 buffer. It is recommended to configure the composing targets before to
0086 the cropping targets.
0087
0088 The cropping targets refer to the memory buffer that contains an image
0089 to be inserted into a video signal or graphical screen. The limits of
0090 cropping coordinates are obtained using ``V4L2_SEL_TGT_CROP_BOUNDS``.
0091 All coordinates are expressed in pixels. The top/left corner is always
0092 point ``(0,0)``. The width and height is equal to the image size
0093 specified using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
0094
0095 The top left corner, width and height of the source rectangle, that is
0096 the area from which image date are processed by the hardware, is given
0097 by the ``V4L2_SEL_TGT_CROP``. Its coordinates are expressed in the
0098 same coordinate system as the bounds rectangle. The active cropping area
0099 must lie completely inside the crop boundaries and the driver may
0100 further adjust the requested size and/or position according to hardware
0101 limitations.
0102
0103 For output devices the default cropping rectangle is queried using
0104 ``V4L2_SEL_TGT_CROP_DEFAULT``. It is usually equal to the bounding
0105 rectangle.
0106
0107 The part of a video signal or graphics display where the image is
0108 inserted by the hardware is controlled by ``V4L2_SEL_TGT_COMPOSE``
0109 target. The rectangle's coordinates are expressed in pixels. The
0110 composing rectangle must lie completely inside the bounds rectangle. The
0111 driver must adjust the area to fit to the bounding limits. Moreover, the
0112 driver can perform other adjustments according to hardware limitations.
0113
0114 The device has a default composing rectangle, given by the
0115 ``V4L2_SEL_TGT_COMPOSE_DEFAULT`` target. This rectangle shall cover what
0116 the driver writer considers the complete picture. It is recommended for
0117 the driver developers to put the top/left corner at position ``(0,0)``.
0118 Drivers shall set the active composing rectangle to the default one when
0119 the driver is first loaded.
0120
0121 The devices may introduce additional content to video signal other than
0122 an image from memory buffers. It includes borders around an image.
0123 However, such a padded area is driver-dependent feature not covered by
0124 this document. Driver developers are encouraged to keep padded rectangle
0125 equal to active one. The padded target is accessed by the
0126 ``V4L2_SEL_TGT_COMPOSE_PADDED`` identifier. It must contain all pixels
0127 from the ``V4L2_SEL_TGT_COMPOSE`` target.
0128
0129
0130 Scaling control
0131 ===============
0132
0133 An application can detect if scaling is performed by comparing the width
0134 and the height of rectangles obtained using ``V4L2_SEL_TGT_CROP`` and
0135 ``V4L2_SEL_TGT_COMPOSE`` targets. If these are not equal then the
0136 scaling is applied. The application can compute the scaling ratios using
0137 these values.
