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