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