diff --git a/Documentation/DocBook/media/v4l/common.xml b/Documentation/DocBook/media/v4l/common.xml
index 9d3919831ebac06fa806d350b64e13bc395456fc..c79278acfb0ec6c1942808b788b1fe25b65fa726 100644
--- a/Documentation/DocBook/media/v4l/common.xml
+++ b/Documentation/DocBook/media/v4l/common.xml
@@ -1168,6 +1168,8 @@ dheight = format.fmt.pix.height;
+ &sub-selection-api;
+
Streaming Parameters
diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml
index 12ba26262d32d5779c332ae6c23f1a172c7a7c4d..c736380b4647acc649f2203b09c394802cd6180e 100644
--- a/Documentation/DocBook/media/v4l/compat.xml
+++ b/Documentation/DocBook/media/v4l/compat.xml
@@ -2376,6 +2376,12 @@ that used it. It was originally scheduled for removal in 2.6.35.
V4L2_CTRL_FLAG_VOLATILE was added to signal volatile controls to userspace.
+
+ Add selection API for extended control over cropping and
+composing. Does not affect the compatibility of current drivers and
+applications. See selection API for
+details.
+
@@ -2500,6 +2506,9 @@ ioctls.
&VIDIOC-CREATE-BUFS; and &VIDIOC-PREPARE-BUF; ioctls.
+
+ Selection API.
+
diff --git a/Documentation/DocBook/media/v4l/selection-api.xml b/Documentation/DocBook/media/v4l/selection-api.xml
new file mode 100644
index 0000000000000000000000000000000000000000..46cb47ab8e3b231624324fa625eb77ac85f9ea4b
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/selection-api.xml
@@ -0,0 +1,327 @@
+
+
+ Experimental API for cropping, composing and scaling
+
+
+ Experimental
+
+ This is an experimental
+interface and may change in the future.
+
+
+
+ Introduction
+
+Some video capture devices can sample a subsection of a picture and
+shrink or enlarge it to an image of arbitrary size. Next, the devices can
+insert the image into larger one. Some video output devices can crop part of an
+input image, scale it up or down and insert it at an arbitrary scan line and
+horizontal offset into a video signal. We call these abilities cropping,
+scaling and composing.
+
+On a video capture device the source is a video
+signal, and the cropping target determine the area actually sampled. The sink
+is an image stored in a memory buffer. The composing area specifies which part
+of the buffer is actually written to by the hardware.
+
+On a video output device the source is an image in a
+memory buffer, and the cropping target is a part of an image to be shown on a
+display. The sink is the display or the graphics screen. The application may
+select the part of display where the image should be displayed. The size and
+position of such a window is controlled by the compose target.
+
+Rectangles for all cropping and composing targets are defined even if the
+device does supports neither cropping nor composing. Their size and position
+will be fixed in such a case. If the device does not support scaling then the
+cropping and composing rectangles have the same size.
+
+
+
+
+ Selection targets
+
+
+ Cropping and composing targets
+
+
+
+
+
+ Targets used by a cropping, composing and scaling
+ process
+
+
+
+
+
+
+
+ Configuration
+
+Applications can use the selection
+API 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 constraint flags .
+
+
+
+ Configuration of video capture
+
+See figure 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 driver dependant units, although the coordinate
+system guarantees that if sizes of the active cropping and the active composing
+rectangles are equal then no scaling is performed.
+
+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_ACTIVE
+ 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
+over 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 natural unit for given formats.
+Pixels are highly recommended. 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 VIDIOC_S_FMT .
+
+The part of a buffer into which the image is inserted by the hardware is
+controlled by the V4L2_SEL_TGT_COMPOSE_ACTIVE 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
+ constraint 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_ACTIVE 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 natural units for a given format. Pixels are
+highly recommended. The top/left corner is always point (0,0)
+. The width and height is equal to the image size specified using
+ VIDIOC_S_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_ACTIVE . 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_ACTIVE
+ target. The rectangle's coordinates are expressed in driver
+dependant units. The only exception are digital outputs where the units are
+pixels. For other types of devices, the coordinate system guarantees that if
+sizes of the active cropping and the active composing rectangles are equal then
+no scaling is performed. 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_ACTIVE 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_ACTIVE
+ and V4L2_SEL_TGT_COMPOSE_ACTIVE targets. If
+these are not equal then the scaling is applied. The application can compute
+the scaling ratios using these values.
+
+
+
+
+
+
+
+ Comparison with old cropping API.
+
+The selection API was introduced to cope with deficiencies of previous
+ API , that was designed to control simple capture
+devices. Later the cropping API was adopted by video output drivers. The ioctls
+are used to select a part of the display were the video signal is inserted. It
+should be considered as an API abuse because the described operation is
+actually the composing. The selection API makes a clear distinction between
+composing and cropping operations by setting the appropriate targets. The V4L2
+API lacks any support for composing to and cropping from an image inside a
+memory buffer. The application could configure a capture device to fill only a
+part of an image by abusing V4L2 API. Cropping a smaller image from a larger
+one is achieved by setting the field
+&v4l2-pix-format;::bytesperline . Introducing an image offsets
+could be done by modifying field &v4l2-buffer;::m:userptr
+ before calling VIDIOC_QBUF . Those
+operations should be avoided because they are not portable (endianness), and do
+not work for macroblock and Bayer formats and mmap buffers. The selection API
+deals with configuration of buffer cropping/composing in a clear, intuitive and
+portable way. Next, with the selection API the concepts of the padded target
+and constraints flags are introduced. Finally, &v4l2-crop;
+ and &v4l2-cropcap; have no reserved
+fields. Therefore there is no way to extend their functionality. The new
+ &v4l2-selection; provides a lot of place for future
+extensions. Driver developers are encouraged to implement only selection API.
+The former cropping API would be simulated using the new one.
+
+
+
+
+ Examples
+
+ Resetting the cropping parameters
+
+ (A video capture device is assumed; change
+V4L2_BUF_TYPE_VIDEO_CAPTURE for other devices; change target to
+ V4L2_SEL_TGT_COMPOSE_* family to configure composing
+area)
+
+
+
+ &v4l2-selection; sel = {
+ .type = V4L2_BUF_TYPE_VIDEO_CAPTURE,
+ .target = V4L2_SEL_TGT_CROP_DEFAULT,
+ };
+ ret = ioctl(fd, &VIDIOC-G-SELECTION;, &sel);
+ if (ret)
+ exit(-1);
+ sel.target = V4L2_SEL_TGT_CROP_ACTIVE;
+ ret = ioctl(fd, &VIDIOC-S-SELECTION;, &sel);
+ if (ret)
+ exit(-1);
+
+
+
+
+
+ Simple downscaling
+ Setting a composing area on output of size of at most
+ half of limit placed at a center of a display.
+
+
+ &v4l2-selection; sel = {
+ .type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
+ .target = V4L2_SEL_TGT_COMPOSE_BOUNDS,
+ };
+ struct v4l2_rect r;
+
+ ret = ioctl(fd, &VIDIOC-G-SELECTION;, &sel);
+ if (ret)
+ exit(-1);
+ /* setting smaller compose rectangle */
+ r.width = sel.r.width / 2;
+ r.height = sel.r.height / 2;
+ r.left = sel.r.width / 4;
+ r.top = sel.r.height / 4;
+ sel.r = r;
+ sel.target = V4L2_SEL_TGT_COMPOSE_ACTIVE;
+ sel.flags = V4L2_SEL_FLAG_LE;
+ ret = ioctl(fd, &VIDIOC-S-SELECTION;, &sel);
+ if (ret)
+ exit(-1);
+
+
+
+
+
+ Querying for scaling factors
+ A video output device is assumed; change
+V4L2_BUF_TYPE_VIDEO_OUTPUT for other devices
+
+
+ &v4l2-selection; compose = {
+ .type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
+ .target = V4L2_SEL_TGT_COMPOSE_ACTIVE,
+ };
+ &v4l2-selection; crop = {
+ .type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
+ .target = V4L2_SEL_TGT_CROP_ACTIVE,
+ };
+ double hscale, vscale;
+
+ ret = ioctl(fd, &VIDIOC-G-SELECTION;, &compose);
+ if (ret)
+ exit(-1);
+ ret = ioctl(fd, &VIDIOC-G-SELECTION;, &crop);
+ if (ret)
+ exit(-1);
+
+ /* computing scaling factors */
+ hscale = (double)compose.r.width / crop.r.width;
+ vscale = (double)compose.r.height / crop.r.height;
+
+
+
+
+
+
+
diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml
index 2ab365c10fb91083b9defe3e57d215cae8688450..e97c512861bb352320d8be206945a2bb5c82d8b7 100644
--- a/Documentation/DocBook/media/v4l/v4l2.xml
+++ b/Documentation/DocBook/media/v4l/v4l2.xml
@@ -501,6 +501,7 @@ and discussions on the V4L mailing list.
&sub-g-output;
&sub-g-parm;
&sub-g-priority;
+ &sub-g-selection;
&sub-g-sliced-vbi-cap;
&sub-g-std;
&sub-g-tuner;
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml
new file mode 100644
index 0000000000000000000000000000000000000000..a9d36e0c090e4a74b89ffde495eb82fb5cc5e92f
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml
@@ -0,0 +1,304 @@
+
+
+
+ ioctl VIDIOC_G_SELECTION, VIDIOC_S_SELECTION
+ &manvol;
+
+
+
+ VIDIOC_G_SELECTION
+ VIDIOC_S_SELECTION
+ Get or set one of the selection rectangles
+
+
+
+
+
+ int ioctl
+ int fd
+ int request
+ struct v4l2_selection *argp
+
+
+
+
+
+ Arguments
+
+
+
+ fd
+
+ &fd;
+
+
+
+ request
+
+ VIDIOC_G_SELECTION, VIDIOC_S_SELECTION
+
+
+
+ argp
+
+
+
+
+
+
+
+
+ Description
+
+
+ Experimental
+ This is an experimental
+ interface and may change in the future.
+
+
+ The ioctls are used to query and configure selection rectangles.
+
+ To query the cropping (composing) rectangle set
+&v4l2-selection;::type to the respective buffer type. Do not
+use multiplanar buffers. Use V4L2_BUF_TYPE_VIDEO_CAPTURE
+ instead of V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE
+. Use V4L2_BUF_TYPE_VIDEO_OUTPUT instead of
+ V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE . The next step is
+setting &v4l2-selection;::target to value
+ V4L2_SEL_TGT_CROP_ACTIVE (
+V4L2_SEL_TGT_COMPOSE_ACTIVE ). Please refer to table or for additional
+targets. Fields &v4l2-selection;::flags and
+ &v4l2-selection;::reserved are ignored and they
+must be filled with zeros. The driver fills the rest of the structure or
+returns &EINVAL; if incorrect buffer type or target was used. If cropping
+(composing) is not supported then the active rectangle is not mutable and it is
+always equal to the bounds rectangle. Finally, structure
+&v4l2-selection;::r is filled with the current cropping
+(composing) coordinates. The coordinates are expressed in driver-dependent
+units. The only exception are rectangles for images in raw formats, whose
+coordinates are always expressed in pixels.
+
+ To change the cropping (composing) rectangle set
+&v4l2-selection;::type to the respective buffer type. Do not
+use multiplanar buffers. Use V4L2_BUF_TYPE_VIDEO_CAPTURE
+ instead of V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE
+. Use V4L2_BUF_TYPE_VIDEO_OUTPUT instead of
+ V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE . The next step is
+setting &v4l2-selection;::target to value
+ V4L2_SEL_TGT_CROP_ACTIVE (
+V4L2_SEL_TGT_COMPOSE_ACTIVE ). Please refer to table or for additional
+targets. Set desired active area into the field
+&v4l2-selection;::r . Field
+&v4l2-selection;::reserved is ignored and must be filled with
+zeros. The driver may adjust the rectangle coordinates. An application may
+introduce constraints to control rounding behaviour. Set the field
+ &v4l2-selection;::flags to one of values:
+
+
+
+0 - The driver can adjust the rectangle size freely
+and shall choose a crop/compose rectangle as close as possible to the requested
+one.
+
+
+V4L2_SEL_FLAG_GE - The driver is not allowed to
+shrink the rectangle. The original rectangle must lay inside the adjusted
+one.
+
+
+V4L2_SEL_FLAG_LE - The driver is not allowed to
+enlarge the rectangle. The adjusted rectangle must lay inside the original
+one.
+
+
+V4L2_SEL_FLAG_GE | V4L2_SEL_FLAG_LE - The driver
+must choose the size exactly the same as in the requested rectangle.
+
+
+
+Please refer to .
+
+
+
+ The driver may have to adjusts the requested dimensions against hardware
+limits and other parts as the pipeline, i.e. the bounds given by the
+capture/output window or TV display. The closest possible values of horizontal
+and vertical offset and sizes are chosen according to following priority:
+
+
+
+ Satisfy constraints from &v4l2-selection;::flags.
+
+
+ Adjust width, height, left, and top to hardware limits and alignments.
+
+
+ Keep center of adjusted rectangle as close as possible to the original one.
+
+
+ Keep width and height as close as possible to original ones.
+
+
+ Keep horizontal and vertical offset as close as possible to original ones.
+
+
+
+On success the field &v4l2-selection;::r contains
+the adjusted rectangle. When the parameters are unsuitable the application may
+modify the cropping (composing) or image parameters and repeat the cycle until
+satisfactory parameters have been negotiated. If constraints flags have to be
+violated at then ERANGE is returned. The error indicates that there
+exist no rectangle that satisfies the constraints.
+
+
+
+
+
+ Selection targets.
+
+ &cs-def;
+
+
+ V4L2_SEL_TGT_CROP_ACTIVE
+ 0
+ area that is currently cropped by hardware
+
+
+ V4L2_SEL_TGT_CROP_DEFAULT
+ 1
+ suggested cropping rectangle that covers the "whole picture"
+
+
+ V4L2_SEL_TGT_CROP_BOUNDS
+ 2
+ limits for the cropping rectangle
+
+
+ V4L2_SEL_TGT_COMPOSE_ACTIVE
+ 256
+ area to which data are composed by hardware
+
+
+ V4L2_SEL_TGT_COMPOSE_DEFAULT
+ 257
+ suggested composing rectangle that covers the "whole picture"
+
+
+ V4L2_SEL_TGT_COMPOSE_BOUNDS
+ 258
+ limits for the composing rectangle
+
+
+ V4L2_SEL_TGT_COMPOSE_PADDED
+ 259
+ the active area and all padding pixels that are inserted or modified by the hardware
+
+
+
+
+
+
+
+
+ Selection constraint flags
+
+ &cs-def;
+
+
+ V4L2_SEL_FLAG_GE
+ 0x00000001
+ indicate that adjusted rectangle must contain a rectangle from &v4l2-selection;::r
+
+
+ V4L2_SEL_FLAG_LE
+ 0x00000002
+ indicate that adjusted rectangle must be inside a rectangle from &v4l2-selection;::r
+
+
+
+
+
+
+
+
+ Size adjustments with constraint flags.
+
+
+
+
+
+ Behaviour of rectangle adjustment for different constraint
+ flags.
+
+
+
+
+
+
+
+ struct <structname>v4l2_selection</structname>
+
+ &cs-str;
+
+
+ __u32
+ type
+ Type of the buffer (from &v4l2-buf-type;)
+
+
+ __u32
+ target
+ used to select between cropping and composing rectangles
+
+
+ __u32
+ flags
+ control over coordinates adjustments, refer to selection flags
+
+
+ &v4l2-rect;
+ r
+ selection rectangle
+
+
+ __u32
+ reserved[9]
+ Reserved fields for future use
+
+
+
+
+
+
+
+ &return-value;
+
+
+ EINVAL
+
+ The buffer &v4l2-selection;::type
+or &v4l2-selection;::target is not supported, or
+the &v4l2-selection;::flags are invalid.
+
+
+
+ ERANGE
+
+ it is not possible to adjust a rectangle
+&v4l2-selection;::r that satisfies all contraints from
+ &v4l2-selection;::flags .
+
+
+
+ EBUSY
+
+ it is not possible to apply change of selection rectangle at the moment.
+Usually because streaming is in progress.
+
+
+
+
+
+