From 871480933a1c28f8a9fed4c4d34d06c439a7a422 Mon Sep 17 00:00:00 2001 From: Srikant Patnaik Date: Sun, 11 Jan 2015 12:28:04 +0530 Subject: Moved, renamed, and deleted files The original directory structure was scattered and unorganized. Changes are basically to make it look like kernel structure. --- .../DocBook/media/v4l/vidioc-g-selection.xml | 308 +++++++++++++++++++++ 1 file changed, 308 insertions(+) create mode 100644 Documentation/DocBook/media/v4l/vidioc-g-selection.xml (limited to 'Documentation/DocBook/media/v4l/vidioc-g-selection.xml') 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 00000000..bb04eff7 --- /dev/null +++ b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml @@ -0,0 +1,308 @@ + + + + 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 field 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 the value of &v4l2-selection; target field +to V4L2_SEL_TGT_CROP_ACTIVE ( +V4L2_SEL_TGT_COMPOSE_ACTIVE ). Please refer to table or for additional +targets. The flags and reserved + fields of &v4l2-selection; 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, the &v4l2-rect; +r rectangle 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 the &v4l2-selection; +type field 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 the value of &v4l2-selection; target to +V4L2_SEL_TGT_CROP_ACTIVE ( +V4L2_SEL_TGT_COMPOSE_ACTIVE ). Please refer to table or for additional +targets. The &v4l2-rect; r rectangle need to be +set to the desired active area. Field &v4l2-selection; reserved + is ignored and must be filled with zeros. The driver may adjust +coordinates of the requested rectangle. An application may +introduce constraints to control rounding behaviour. The &v4l2-selection; +flags field must be set to one of the following: + + + +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 &v4l2-rect; r field 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 + 0x0000 + The area that is currently cropped by hardware. + + + V4L2_SEL_TGT_CROP_DEFAULT + 0x0001 + Suggested cropping rectangle that covers the "whole picture". + + + V4L2_SEL_TGT_CROP_BOUNDS + 0x0002 + Limits for the cropping rectangle. + + + V4L2_SEL_TGT_COMPOSE_ACTIVE + 0x0100 + The area to which data is composed by hardware. + + + V4L2_SEL_TGT_COMPOSE_DEFAULT + 0x0101 + Suggested composing rectangle that covers the "whole picture". + + + V4L2_SEL_TGT_COMPOSE_BOUNDS + 0x0102 + Limits for the composing rectangle. + + + V4L2_SEL_TGT_COMPOSE_PADDED + 0x0103 + The active area and all padding pixels that are inserted or modified by hardware. + + + +
+ + + + + Selection constraint flags + + &cs-def; + + + V4L2_SEL_FLAG_GE + 0x00000001 + Indicates that the adjusted rectangle must contain the original + &v4l2-selection; r rectangle. + + + V4L2_SEL_FLAG_LE + 0x00000002 + Indicates that the adjusted rectangle must be inside the original + &v4l2-rect; r rectangle. + + + +
+ + +
+
+ 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 + Flags controlling the selection rectangle adjustments, refer to + selection flags. + + + &v4l2-rect; + r + The selection rectangle. + + + __u32 + reserved[9] + Reserved fields for future use. + + + +
+ + + + &return-value; + + + EINVAL + + Given buffer type type or +the selection target target is not supported, +or the flags argument is not valid. + + + + ERANGE + + It is not possible to adjust &v4l2-rect; +r rectangle to satisfy all contraints given in the +flags argument. + + + + EBUSY + + It is not possible to apply change of the selection rectangle +at the moment. Usually because streaming is in progress. + + + + + + -- cgit