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. 139