Documentation/userspace-api/media/v4l/selection-api-configuration.rst - linux - Git at Google

 .. Permission is granted to copy, distribute and/or modify this
 .. document under the terms of the GNU Free Documentation License,
 .. Version 1.1 or any later version published by the Free Software
 .. Foundation, with no Invariant Sections, no Front-Cover Texts
 .. and no Back-Cover Texts. A copy of the license is included at
 .. Documentation/userspace-api/media/fdl-appendix.rst.
 ..
 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections

 *************
 Configuration
 *************

 Applications can use the :ref:`selection API <VIDIOC_G_SELECTION>` to
 select an area in a video signal or a buffer, and to query for default
 settings and hardware limits.

 Video hardware can have various cropping, composing and scaling
 limitations. It may only scale up or down, support only discrete scaling
 factors, or have different scaling abilities in the horizontal and
 vertical directions. Also it may not support scaling at all. At the same
 time the cropping/composing rectangles may have to be aligned, and both
 the source and the sink may have arbitrary upper and lower size limits.
 Therefore, as usual, drivers are expected to adjust the requested
 parameters and return the actual values selected. An application can
 control the rounding behaviour using
 :ref:`constraint flags <v4l2-selection-flags>`.


 Configuration of video capture
 ==============================

 See figure :ref:`sel-targets-capture` for examples of the selection
 targets available for a video capture device. It is recommended to
 configure the cropping targets before to the composing targets.

 The range of coordinates of the top left corner, width and height of
 areas that can be sampled is given by the ``V4L2_SEL_TGT_CROP_BOUNDS``
 target. It is recommended for the driver developers to put the top/left
 corner at position ``(0,0)``. The rectangle's coordinates are expressed
 in pixels.

 The top left corner, width and height of the source rectangle, that is
 the area actually sampled, is given by the ``V4L2_SEL_TGT_CROP`` target.
 It uses the same coordinate system as ``V4L2_SEL_TGT_CROP_BOUNDS``. The
 active cropping area must lie completely inside the capture boundaries.
 The driver may further adjust the requested size and/or position
 according to hardware limitations.

 Each capture device has a default source rectangle, given by the
 ``V4L2_SEL_TGT_CROP_DEFAULT`` target. This rectangle shall cover what the
 driver writer considers the complete picture. Drivers shall set the
 active crop rectangle to the default when the driver is first loaded,
 but not later.

 The composing targets refer to a memory buffer. The limits of composing
 coordinates are obtained using ``V4L2_SEL_TGT_COMPOSE_BOUNDS``. All
 coordinates are expressed in pixels. The rectangle's top/left corner
 must be located at position ``(0,0)``. The width and height are equal to
 the image size set by :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`.

 The part of a buffer into which the image is inserted by the hardware is
 controlled by the ``V4L2_SEL_TGT_COMPOSE`` target. The rectangle's
 coordinates are also expressed in the same coordinate system as the
 bounds rectangle. The composing rectangle must lie completely inside
 bounds rectangle. The driver must adjust the composing rectangle to fit
 to the bounding limits. Moreover, the driver can perform other
 adjustments according to hardware limitations. The application can
 control rounding behaviour using
 :ref:`constraint flags <v4l2-selection-flags>`.

 For capture devices the default composing rectangle is queried using
 ``V4L2_SEL_TGT_COMPOSE_DEFAULT``. It is usually equal to the bounding
 rectangle.

 The part of a buffer that is modified by the hardware is given by
 ``V4L2_SEL_TGT_COMPOSE_PADDED``. It contains all pixels defined using
 ``V4L2_SEL_TGT_COMPOSE`` plus all padding data modified by hardware
 during insertion process. All pixels outside this rectangle *must not*
 be changed by the hardware. The content of pixels that lie inside the
 padded area but outside active area is undefined. The application can
 use the padded and active rectangles to detect where the rubbish pixels
 are located and remove them if needed.


 Configuration of video output
 =============================

 For output devices targets and ioctls are used similarly to the video
 capture case. The *composing* rectangle refers to the insertion of an
 image into a video signal. The cropping rectangles refer to a memory
 buffer. It is recommended to configure the composing targets before to
 the cropping targets.

 The cropping targets refer to the memory buffer that contains an image
 to be inserted into a video signal or graphical screen. The limits of
 cropping coordinates are obtained using ``V4L2_SEL_TGT_CROP_BOUNDS``.
 All coordinates are expressed in pixels. The top/left corner is always
 point ``(0,0)``. The width and height is equal to the image size
 specified using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.

 The top left corner, width and height of the source rectangle, that is
 the area from which image date are processed by the hardware, is given
 by the ``V4L2_SEL_TGT_CROP``. Its coordinates are expressed in in the
 same coordinate system as the bounds rectangle. The active cropping area
 must lie completely inside the crop boundaries and the driver may
 further adjust the requested size and/or position according to hardware
 limitations.

 For output devices the default cropping rectangle is queried using
 ``V4L2_SEL_TGT_CROP_DEFAULT``. It is usually equal to the bounding
 rectangle.

 The part of a video signal or graphics display where the image is
 inserted by the hardware is controlled by ``V4L2_SEL_TGT_COMPOSE``
 target. The rectangle's coordinates are expressed in pixels. The
 composing rectangle must lie completely inside the bounds rectangle. The
 driver must adjust the area to fit to the bounding limits. Moreover, the
 driver can perform other adjustments according to hardware limitations.

 The device has a default composing rectangle, given by the
 ``V4L2_SEL_TGT_COMPOSE_DEFAULT`` target. This rectangle shall cover what
 the driver writer considers the complete picture. It is recommended for
 the driver developers to put the top/left corner at position ``(0,0)``.
 Drivers shall set the active composing rectangle to the default one when
 the driver is first loaded.

 The devices may introduce additional content to video signal other than
 an image from memory buffers. It includes borders around an image.
 However, such a padded area is driver-dependent feature not covered by
 this document. Driver developers are encouraged to keep padded rectangle
 equal to active one. The padded target is accessed by the
 ``V4L2_SEL_TGT_COMPOSE_PADDED`` identifier. It must contain all pixels
 from the ``V4L2_SEL_TGT_COMPOSE`` target.


 Scaling control
 ===============

 An application can detect if scaling is performed by comparing the width
 and the height of rectangles obtained using ``V4L2_SEL_TGT_CROP`` and
 ``V4L2_SEL_TGT_COMPOSE`` targets. If these are not equal then the
 scaling is applied. The application can compute the scaling ratios using
 these values.
	.. Permission is granted to copy, distribute and/or modify this
	.. document under the terms of the GNU Free Documentation License,
	.. Version 1.1 or any later version published by the Free Software
	.. Foundation, with no Invariant Sections, no Front-Cover Texts
	.. and no Back-Cover Texts. A copy of the license is included at
	.. Documentation/userspace-api/media/fdl-appendix.rst.
	..
	.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections

	*************
	Configuration
	*************

	Applications can use the :ref:`selection API <VIDIOC_G_SELECTION>` to
	select an area in a video signal or a buffer, and to query for default
	settings and hardware limits.

	Video hardware can have various cropping, composing and scaling
	limitations. It may only scale up or down, support only discrete scaling
	factors, or have different scaling abilities in the horizontal and
	vertical directions. Also it may not support scaling at all. At the same
	time the cropping/composing rectangles may have to be aligned, and both
	the source and the sink may have arbitrary upper and lower size limits.
	Therefore, as usual, drivers are expected to adjust the requested
	parameters and return the actual values selected. An application can
	control the rounding behaviour using
	:ref:`constraint flags <v4l2-selection-flags>`.


	Configuration of video capture
	==============================

	See figure :ref:`sel-targets-capture` for examples of the selection
	targets available for a video capture device. It is recommended to
	configure the cropping targets before to the composing targets.

	The range of coordinates of the top left corner, width and height of
	areas that can be sampled is given by the ``V4L2_SEL_TGT_CROP_BOUNDS``
	target. It is recommended for the driver developers to put the top/left
	corner at position ``(0,0)``. The rectangle's coordinates are expressed
	in pixels.

	The top left corner, width and height of the source rectangle, that is
	the area actually sampled, is given by the ``V4L2_SEL_TGT_CROP`` target.
	It uses the same coordinate system as ``V4L2_SEL_TGT_CROP_BOUNDS``. The
	active cropping area must lie completely inside the capture boundaries.
	The driver may further adjust the requested size and/or position
	according to hardware limitations.

	Each capture device has a default source rectangle, given by the
	``V4L2_SEL_TGT_CROP_DEFAULT`` target. This rectangle shall cover what the
	driver writer considers the complete picture. Drivers shall set the
	active crop rectangle to the default when the driver is first loaded,
	but not later.

	The composing targets refer to a memory buffer. The limits of composing
	coordinates are obtained using ``V4L2_SEL_TGT_COMPOSE_BOUNDS``. All
	coordinates are expressed in pixels. The rectangle's top/left corner
	must be located at position ``(0,0)``. The width and height are equal to
	the image size set by :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`.

	The part of a buffer into which the image is inserted by the hardware is
	controlled by the ``V4L2_SEL_TGT_COMPOSE`` target. The rectangle's
	coordinates are also expressed in the same coordinate system as the
	bounds rectangle. The composing rectangle must lie completely inside
	bounds rectangle. The driver must adjust the composing rectangle to fit
	to the bounding limits. Moreover, the driver can perform other
	adjustments according to hardware limitations. The application can
	control rounding behaviour using
	:ref:`constraint flags <v4l2-selection-flags>`.

	For capture devices the default composing rectangle is queried using
	``V4L2_SEL_TGT_COMPOSE_DEFAULT``. It is usually equal to the bounding
	rectangle.

	The part of a buffer that is modified by the hardware is given by
	``V4L2_SEL_TGT_COMPOSE_PADDED``. It contains all pixels defined using
	``V4L2_SEL_TGT_COMPOSE`` plus all padding data modified by hardware
	during insertion process. All pixels outside this rectangle must not
	be changed by the hardware. The content of pixels that lie inside the
	padded area but outside active area is undefined. The application can
	use the padded and active rectangles to detect where the rubbish pixels
	are located and remove them if needed.


	Configuration of video output
	=============================

	For output devices targets and ioctls are used similarly to the video
	capture case. The composing rectangle refers to the insertion of an
	image into a video signal. The cropping rectangles refer to a memory
	buffer. It is recommended to configure the composing targets before to
	the cropping targets.

	The cropping targets refer to the memory buffer that contains an image
	to be inserted into a video signal or graphical screen. The limits of
	cropping coordinates are obtained using ``V4L2_SEL_TGT_CROP_BOUNDS``.
	All coordinates are expressed in pixels. The top/left corner is always
	point ``(0,0)``. The width and height is equal to the image size
	specified using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.

	The top left corner, width and height of the source rectangle, that is
	the area from which image date are processed by the hardware, is given
	by the ``V4L2_SEL_TGT_CROP``. Its coordinates are expressed in in the
	same coordinate system as the bounds rectangle. The active cropping area
	must lie completely inside the crop boundaries and the driver may
	further adjust the requested size and/or position according to hardware
	limitations.

	For output devices the default cropping rectangle is queried using
	``V4L2_SEL_TGT_CROP_DEFAULT``. It is usually equal to the bounding
	rectangle.

	The part of a video signal or graphics display where the image is
	inserted by the hardware is controlled by ``V4L2_SEL_TGT_COMPOSE``
	target. The rectangle's coordinates are expressed in pixels. The
	composing rectangle must lie completely inside the bounds rectangle. The
	driver must adjust the area to fit to the bounding limits. Moreover, the
	driver can perform other adjustments according to hardware limitations.

	The device has a default composing rectangle, given by the
	``V4L2_SEL_TGT_COMPOSE_DEFAULT`` target. This rectangle shall cover what
	the driver writer considers the complete picture. It is recommended for
	the driver developers to put the top/left corner at position ``(0,0)``.
	Drivers shall set the active composing rectangle to the default one when
	the driver is first loaded.

	The devices may introduce additional content to video signal other than
	an image from memory buffers. It includes borders around an image.
	However, such a padded area is driver-dependent feature not covered by
	this document. Driver developers are encouraged to keep padded rectangle
	equal to active one. The padded target is accessed by the
	``V4L2_SEL_TGT_COMPOSE_PADDED`` identifier. It must contain all pixels
	from the ``V4L2_SEL_TGT_COMPOSE`` target.


	Scaling control
	===============

	An application can detect if scaling is performed by comparing the width
	and the height of rectangles obtained using ``V4L2_SEL_TGT_CROP`` and
	``V4L2_SEL_TGT_COMPOSE`` targets. If these are not equal then the
	scaling is applied. The application can compute the scaling ratios using
	these values.