138 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2 3*************4Configuration5*************6 7Applications can use the :ref:`selection API <VIDIOC_G_SELECTION>` to8select an area in a video signal or a buffer, and to query for default9settings and hardware limits.10 11Video hardware can have various cropping, composing and scaling12limitations. It may only scale up or down, support only discrete scaling13factors, or have different scaling abilities in the horizontal and14vertical directions. Also it may not support scaling at all. At the same15time the cropping/composing rectangles may have to be aligned, and both16the source and the sink may have arbitrary upper and lower size limits.17Therefore, as usual, drivers are expected to adjust the requested18parameters and return the actual values selected. An application can19control the rounding behaviour using20:ref:`constraint flags <v4l2-selection-flags>`.21 22 23Configuration of video capture24==============================25 26See figure :ref:`sel-targets-capture` for examples of the selection27targets available for a video capture device. It is recommended to28configure the cropping targets before to the composing targets.29 30The range of coordinates of the top left corner, width and height of31areas 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/left33corner at position ``(0,0)``. The rectangle's coordinates are expressed34in pixels.35 36The top left corner, width and height of the source rectangle, that is37the area actually sampled, is given by the ``V4L2_SEL_TGT_CROP`` target.38It uses the same coordinate system as ``V4L2_SEL_TGT_CROP_BOUNDS``. The39active cropping area must lie completely inside the capture boundaries.40The driver may further adjust the requested size and/or position41according to hardware limitations.42 43Each capture device has a default source rectangle, given by the44``V4L2_SEL_TGT_CROP_DEFAULT`` target. This rectangle shall cover what the45driver writer considers the complete picture. Drivers shall set the46active 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 composing50coordinates are obtained using ``V4L2_SEL_TGT_COMPOSE_BOUNDS``. All51coordinates are expressed in pixels. The rectangle's top/left corner52must be located at position ``(0,0)``. The width and height are equal to53the 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 is56controlled by the ``V4L2_SEL_TGT_COMPOSE`` target. The rectangle's57coordinates are also expressed in the same coordinate system as the58bounds rectangle. The composing rectangle must lie completely inside59bounds rectangle. The driver must adjust the composing rectangle to fit60to the bounding limits. Moreover, the driver can perform other61adjustments according to hardware limitations. The application can62control rounding behaviour using63:ref:`constraint flags <v4l2-selection-flags>`.64 65For capture devices the default composing rectangle is queried using66``V4L2_SEL_TGT_COMPOSE_DEFAULT``. It is usually equal to the bounding67rectangle.68 69The part of a buffer that is modified by the hardware is given by70``V4L2_SEL_TGT_COMPOSE_PADDED``. It contains all pixels defined using71``V4L2_SEL_TGT_COMPOSE`` plus all padding data modified by hardware72during insertion process. All pixels outside this rectangle *must not*73be changed by the hardware. The content of pixels that lie inside the74padded area but outside active area is undefined. The application can75use the padded and active rectangles to detect where the rubbish pixels76are located and remove them if needed.77 78 79Configuration of video output80=============================81 82For output devices targets and ioctls are used similarly to the video83capture case. The *composing* rectangle refers to the insertion of an84image into a video signal. The cropping rectangles refer to a memory85buffer. It is recommended to configure the composing targets before to86the cropping targets.87 88The cropping targets refer to the memory buffer that contains an image89to be inserted into a video signal or graphical screen. The limits of90cropping coordinates are obtained using ``V4L2_SEL_TGT_CROP_BOUNDS``.91All coordinates are expressed in pixels. The top/left corner is always92point ``(0,0)``. The width and height is equal to the image size93specified using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.94 95The top left corner, width and height of the source rectangle, that is96the area from which image date are processed by the hardware, is given97by the ``V4L2_SEL_TGT_CROP``. Its coordinates are expressed in the98same coordinate system as the bounds rectangle. The active cropping area99must lie completely inside the crop boundaries and the driver may100further adjust the requested size and/or position according to hardware101limitations.102 103For output devices the default cropping rectangle is queried using104``V4L2_SEL_TGT_CROP_DEFAULT``. It is usually equal to the bounding105rectangle.106 107The part of a video signal or graphics display where the image is108inserted by the hardware is controlled by ``V4L2_SEL_TGT_COMPOSE``109target. The rectangle's coordinates are expressed in pixels. The110composing rectangle must lie completely inside the bounds rectangle. The111driver must adjust the area to fit to the bounding limits. Moreover, the112driver can perform other adjustments according to hardware limitations.113 114The device has a default composing rectangle, given by the115``V4L2_SEL_TGT_COMPOSE_DEFAULT`` target. This rectangle shall cover what116the driver writer considers the complete picture. It is recommended for117the driver developers to put the top/left corner at position ``(0,0)``.118Drivers shall set the active composing rectangle to the default one when119the driver is first loaded.120 121The devices may introduce additional content to video signal other than122an image from memory buffers. It includes borders around an image.123However, such a padded area is driver-dependent feature not covered by124this document. Driver developers are encouraged to keep padded rectangle125equal to active one. The padded target is accessed by the126``V4L2_SEL_TGT_COMPOSE_PADDED`` identifier. It must contain all pixels127from the ``V4L2_SEL_TGT_COMPOSE`` target.128 129 130Scaling control131===============132 133An application can detect if scaling is performed by comparing the width134and the height of rectangles obtained using ``V4L2_SEL_TGT_CROP`` and135``V4L2_SEL_TGT_COMPOSE`` targets. If these are not equal then the136scaling is applied. The application can compute the scaling ratios using137these values.138