From mboxrd@z Thu Jan 1 00:00:00 1970 Return-path: Received: from mx1.redhat.com ([209.132.183.28]:52082 "EHLO mx1.redhat.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753023Ab1I3Qwq (ORCPT ); Fri, 30 Sep 2011 12:52:46 -0400 Message-ID: <4E85F3C1.4070509@redhat.com> Date: Fri, 30 Sep 2011 13:52:17 -0300 From: Mauro Carvalho Chehab MIME-Version: 1.0 To: Tomasz Stanislawski CC: linux-media@vger.kernel.org, m.szyprowski@samsung.com, kyungmin.park@samsung.com, hverkuil@xs4all.nl, laurent.pinchart@ideasonboard.com, sakari.ailus@iki.fi Subject: Re: [PATCH 3/5] doc: v4l: add documentation for selection API References: <1317306161-23696-1-git-send-email-t.stanislaws@samsung.com> <1317306161-23696-4-git-send-email-t.stanislaws@samsung.com> In-Reply-To: <1317306161-23696-4-git-send-email-t.stanislaws@samsung.com> Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit Sender: linux-media-owner@vger.kernel.org List-ID: Em 29-09-2011 11:22, Tomasz Stanislawski escreveu: > This patch adds a documentation for VIDIOC_{G/S}_SELECTION ioctl. Moreover, the > patch adds the description of modeling of composing, cropping and scaling > features in V4L2. Finally, some examples are presented. Doesn't work: $ make htmldocs GEN /home/v4l/v4l/patchwork/Documentation/DocBook//v4l2.xml GEN /home/v4l/v4l/patchwork/Documentation/DocBook//media-entities.tmpl GEN /home/v4l/v4l/patchwork/Documentation/DocBook//media-indices.tmpl GEN /home/v4l/v4l/patchwork/Documentation/DocBook//videodev2.h.xml GEN /home/v4l/v4l/patchwork/Documentation/DocBook//audio.h.xml GEN /home/v4l/v4l/patchwork/Documentation/DocBook//ca.h.xml GEN /home/v4l/v4l/patchwork/Documentation/DocBook//frontend.h.xml GEN /home/v4l/v4l/patchwork/Documentation/DocBook//net.h.xml GEN /home/v4l/v4l/patchwork/Documentation/DocBook//dmx.h.xml GEN /home/v4l/v4l/patchwork/Documentation/DocBook//video.h.xml DOCPROC Documentation/DocBook/media_api.xml HTML Documentation/DocBook/media_api.html /home/v4l/v4l/patchwork/Documentation/DocBook/selection-api.xml:232: parser error : Entity 'v4l2-selection' not defined &v4l2-selection; provides a lot of place for future ^ /home/v4l/v4l/patchwork/Documentation/DocBook/selection-api.xml:250: parser error : Entity 'v4l2-selection' not defined &v4l2-selection; sel = { ^ /home/v4l/v4l/patchwork/Documentation/DocBook/selection-api.xml:254: parser error : Entity 'VIDIOC-G-SELECTION' not defined ret = ioctl(fd, &VIDIOC-G-SELECTION;, &sel); ^ /home/v4l/v4l/patchwork/Documentation/DocBook/selection-api.xml:258: parser error : Entity 'VIDIOC-S-SELECTION' not defined ret = ioctl(fd, &VIDIOC-S-SELECTION;, &sel); ^ /home/v4l/v4l/patchwork/Documentation/DocBook/selection-api.xml:271: parser error : Entity 'v4l2-selection' not defined &v4l2-selection; sel = { ^ /home/v4l/v4l/patchwork/Documentation/DocBook/selection-api.xml:277: parser error : Entity 'VIDIOC-G-SELECTION' not defined ret = ioctl(fd, &VIDIOC-G-SELECTION;, &sel); ^ /home/v4l/v4l/patchwork/Documentation/DocBook/selection-api.xml:288: parser error : Entity 'VIDIOC-S-SELECTION' not defined ret = ioctl(fd, &VIDIOC-S-SELECTION;, &sel); ^ /home/v4l/v4l/patchwork/Documentation/DocBook/selection-api.xml:301: parser error : Entity 'v4l2-selection' not defined &v4l2-selection; compose = { ^ /home/v4l/v4l/patchwork/Documentation/DocBook/selection-api.xml:305: parser error : Entity 'v4l2-selection' not defined &v4l2-selection; crop = { ^ /home/v4l/v4l/patchwork/Documentation/DocBook/selection-api.xml:311: parser error : Entity 'VIDIOC-G-SELECTION' not defined ret = ioctl(fd, &VIDIOC-G-SELECTION;, &compose); ^ /home/v4l/v4l/patchwork/Documentation/DocBook/selection-api.xml:314: parser error : Entity 'VIDIOC-G-SELECTION' not defined ret = ioctl(fd, &VIDIOC-G-SELECTION;, &crop); ^ /home/v4l/v4l/patchwork/Documentation/DocBook/selection-api.xml:328: parser error : chunk is not well balanced ^ /home/v4l/v4l/patchwork/Documentation/DocBook/common.xml:1171: parser error : Failure to process entity sub-selection-api &sub-selection-api; ^ /home/v4l/v4l/patchwork/Documentation/DocBook/common.xml:1171: parser error : Entity 'sub-selection-api' not defined &sub-selection-api; ^ /home/v4l/v4l/patchwork/Documentation/DocBook/v4l2.xml:423: parser error : Failure to process entity sub-common &sub-common; ^ /home/v4l/v4l/patchwork/Documentation/DocBook/v4l2.xml:423: parser error : Entity 'sub-common' not defined &sub-common; ^ > > Signed-off-by: Tomasz Stanislawski > Signed-off-by: Kyungmin Park > --- > Documentation/DocBook/media/v4l/common.xml | 2 + > Documentation/DocBook/media/v4l/compat.xml | 9 + > Documentation/DocBook/media/v4l/selection-api.xml | 327 ++++++++++++++++++++ > Documentation/DocBook/media/v4l/v4l2.xml | 1 + > .../DocBook/media/v4l/vidioc-g-selection.xml | 303 ++++++++++++++++++ > 5 files changed, 642 insertions(+), 0 deletions(-) > create mode 100644 Documentation/DocBook/media/v4l/selection-api.xml > create mode 100644 Documentation/DocBook/media/v4l/vidioc-g-selection.xml > > diff --git a/Documentation/DocBook/media/v4l/common.xml b/Documentation/DocBook/media/v4l/common.xml > index a86f7a0..9c8db86 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 91410b6..7c430ca 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. > + > >
> > @@ -2486,6 +2492,9 @@ ioctls. > > Flash API. > > + > + 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 0000000..3b6dfe0 > --- /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 +linkend="v4l2-sel-flags"> 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_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_CROP_ACTIVE > + target. It uses the same coordinate system as > +V4L2_SEL_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_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_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_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_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_COMPOSE_PADDED . It contains all pixels defined > +using V4L2_SEL_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_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_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_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_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_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_COMPOSE_PADDED > + identifier. It must contain all pixels from the > +V4L2_SEL_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_CROP_ACTIVE > + and V4L2_SEL_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_COMPOSE_* family to configure composing > +area) > + > + > + > + &v4l2-selection; sel = { > + .type = V4L2_BUF_TYPE_VIDEO_CAPTURE, > + .target = V4L2_SEL_CROP_DEFAULT, > + }; > + ret = ioctl(fd, &VIDIOC-G-SELECTION;, &sel); > + if (ret) > + exit(-1); > + sel.target = V4L2_SEL_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_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_COMPOSE_ACTIVE; > + sel.flags = V4L2_SEL_SIZE_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_COMPOSE_ACTIVE, > + }; > + &v4l2-selection; crop = { > + .type = V4L2_BUF_TYPE_VIDEO_OUTPUT, > + .target = V4L2_SEL_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 40132c2..7f1b710 100644 > --- a/Documentation/DocBook/media/v4l/v4l2.xml > +++ b/Documentation/DocBook/media/v4l/v4l2.xml > @@ -500,6 +500,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 0000000..e0ef3e7 > --- /dev/null > +++ b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml > @@ -0,0 +1,303 @@ > + > + > + > + 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_CROP_ACTIVE ( V4L2_SEL_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_CROP_ACTIVE ( V4L2_SEL_COMPOSE_ACTIVE > +). Please refer to table or +linkend="selection-api" /> 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_SIZE_GE - The driver is not allowed to > +shrink the rectangle. The original rectangle must lay inside the adjusted > +one. > + > + > +V4L2_SEL_SIZE_LE - The driver is not allowed to > +enlarge the rectangle. The adjusted rectangle must lay inside the original > +one. > + > + > +V4L2_SEL_SIZE_GE | V4L2_SEL_SIZE_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_CROP_ACTIVE > + 0 > + area that is currently cropped by hardware > + > + > + V4L2_SEL_CROP_DEFAULT > + 1 > + suggested cropping rectangle that covers the "whole picture" > + > + > + V4L2_SEL_CROP_BOUNDS > + 2 > + limits for the cropping rectangle > + > + > + V4L2_SEL_COMPOSE_ACTIVE > + 256 > + area to which data are composed by hardware > + > + > + V4L2_SEL_COMPOSE_DEFAULT > + 257 > + suggested composing rectangle that covers the "whole picture" > + > + > + V4L2_SEL_COMPOSE_BOUNDS > + 258 > + limits for the composing rectangle > + > + > + V4L2_SEL_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_SIZE_GE > + 0x00000001 > + indicate that adjusted rectangle must contain a rectangle from &v4l2-selection;::r > + > + > + V4L2_SEL_SIZE_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. > + > + > + > + > + > +