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.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.