From mboxrd@z Thu Jan 1 00:00:00 1970 Return-path: Received: from mailout4.w1.samsung.com ([210.118.77.14]:9344 "EHLO mailout4.w1.samsung.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1754644Ab1JDIAg (ORCPT ); Tue, 4 Oct 2011 04:00:36 -0400 MIME-version: 1.0 Content-transfer-encoding: 7BIT Content-type: text/plain; charset=UTF-8; format=flowed Received: from euspt1 ([210.118.77.14]) by mailout4.w1.samsung.com (Sun Java(tm) System Messaging Server 6.3-8.04 (built Jul 29 2009; 32bit)) with ESMTP id <0LSJ00EBX7KXQK00@mailout4.w1.samsung.com> for linux-media@vger.kernel.org; Tue, 04 Oct 2011 09:00:33 +0100 (BST) Received: from [106.116.48.223] by spt1.w1.samsung.com (iPlanet Messaging Server 5.2 Patch 2 (built Jul 14 2004)) with ESMTPA id <0LSJ0074L7KWAU@spt1.w1.samsung.com> for linux-media@vger.kernel.org; Tue, 04 Oct 2011 09:00:33 +0100 (BST) Date: Tue, 04 Oct 2011 10:00:28 +0200 From: Tomasz Stanislawski Subject: Re: [PATCH 3/5] doc: v4l: add documentation for selection API In-reply-to: <4E85F3C1.4070509@redhat.com> To: Mauro Carvalho Chehab 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 Message-id: <4E8ABD1C.8040909@samsung.com> References: <1317306161-23696-1-git-send-email-t.stanislaws@samsung.com> <1317306161-23696-4-git-send-email-t.stanislaws@samsung.com> <4E85F3C1.4070509@redhat.com> Sender: linux-media-owner@vger.kernel.org List-ID: On 09/30/2011 06:52 PM, Mauro Carvalho Chehab wrote: > 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. Hi Mauro, The patchset works perfectly on my PC. I tested it after rebasing on the latest linuxtv/staging/for_v3.2 . Try to call 'git clean -dfx' before 'make htmldocs'. Maybe I made some mistake configuring dependencies in docbook. Could you help me find it? Regards, Tomasz Stanislawski > > 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 anexperimental >> +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 videocapture 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 videooutput 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 theselection >> +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 >> + >> + >> + >> + >> + >> + intioctl >> + intfd >> + intrequest >> + 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 toselection 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. >> + >> + >> + >> + >> + >> + > >