1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>Experimental API for cropping, composing and scaling</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="LINUX MEDIA INFRASTRUCTURE API"><link rel="up" href="common.html" title="Chapter 1. Common API Elements"><link rel="prev" href="crop.html" title="Image Cropping, Insertion and Scaling"><link rel="next" href="streaming-par.html" title="Streaming Parameters"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Experimental API for cropping, composing and scaling</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="crop.html">Prev</a> </td><th width="60%" align="center">Chapter 1. Common API Elements</th><td width="20%" align="right"> <a accesskey="n" href="streaming-par.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="selection-api"></a>Experimental API for cropping, composing and scaling</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="selection-api.html#idp1099015196">Introduction</a></span></dt><dt><span class="section"><a href="selection-api.html#idp1099060620">Selection targets</a></span></dt><dt><span class="section"><a href="selection-api.html#idp1099063868">Configuration</a></span></dt><dt><span class="section"><a href="selection-api.html#idp1099082516">Comparison with old cropping API</a></span></dt><dt><span class="section"><a href="selection-api.html#idp1099087124">Examples</a></span></dt></dl></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Experimental</h3><p>This is an <a class="link" href="hist-v4l2.html#experimental" title="Experimental API Elements">experimental</a> 2interface and may change in the future.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1099015196"></a>Introduction</h3></div></div></div><p>Some video capture devices can sample a subsection of a picture and 3shrink or enlarge it to an image of arbitrary size. Next, the devices can 4insert the image into larger one. Some video output devices can crop part of an 5input image, scale it up or down and insert it at an arbitrary scan line and 6horizontal offset into a video signal. We call these abilities cropping, 7scaling and composing.</p><p>On a video <span class="emphasis"><em>capture</em></span> device the source is a video 8signal, and the cropping target determine the area actually sampled. The sink 9is an image stored in a memory buffer. The composing area specifies which part 10of the buffer is actually written to by the hardware. </p><p>On a video <span class="emphasis"><em>output</em></span> device the source is an image in a 11memory buffer, and the cropping target is a part of an image to be shown on a 12display. The sink is the display or the graphics screen. The application may 13select the part of display where the image should be displayed. The size and 14position of such a window is controlled by the compose target.</p><p>Rectangles for all cropping and composing targets are defined even if the 15device does supports neither cropping nor composing. Their size and position 16will be fixed in such a case. If the device does not support scaling then the 17cropping and composing rectangles have the same size.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1099060620"></a>Selection targets</h3></div></div></div><p> 18 </p><div class="figure"><a name="sel-targets-capture"></a><p class="title"><b>Figure 1.2. Cropping and composing targets</b></p><div class="figure-contents"><div class="mediaobject"><img src="selection.png" alt="Targets used by a cropping, composing and scaling process"></div></div></div><p><br class="figure-break"> 19 </p><p>See <a class="xref" href="apb.html#v4l2-selection-targets" title="Selection targets">the section called “Selection targets”</a> for more 20 information.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1099063868"></a>Configuration</h3></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="selection-api.html#idp1099066380">Configuration of video capture</a></span></dt><dt><span class="section"><a href="selection-api.html#idp1099074500">Configuration of video output</a></span></dt><dt><span class="section"><a href="selection-api.html#idp1099081108">Scaling control</a></span></dt></dl></div><p>Applications can use the <a class="link" href="vidioc-g-selection.html" title="ioctl VIDIOC_G_SELECTION, VIDIOC_S_SELECTION">selection 21API</a> to select an area in a video signal or a buffer, and to query for 22default settings and hardware limits.</p><p>Video hardware can have various cropping, composing and scaling 23limitations. It may only scale up or down, support only discrete scaling 24factors, or have different scaling abilities in the horizontal and vertical 25directions. Also it may not support scaling at all. At the same time the 26cropping/composing rectangles may have to be aligned, and both the source and 27the sink may have arbitrary upper and lower size limits. Therefore, as usual, 28drivers are expected to adjust the requested parameters and return the actual 29values selected. An application can control the rounding behaviour using <a class="link" href="apb.html#v4l2-selection-flags" title="Selection flags"> constraint flags </a>.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="idp1099066380"></a>Configuration of video capture</h4></div></div></div><p>See figure <a class="xref" href="selection-api.html#sel-targets-capture" title="Figure 1.2. Cropping and composing targets">Figure 1.2, “Cropping and composing targets”</a> for examples of the 30selection targets available for a video capture device. It is recommended to 31configure the cropping targets before to the composing targets.</p><p>The range of coordinates of the top left corner, width and height of 32areas that can be sampled is given by the <code class="constant">V4L2_SEL_TGT_CROP_BOUNDS</code> 33target. It is recommended for the driver developers to put the 34top/left corner at position <code class="constant">(0,0)</code>. The rectangle's 35coordinates are expressed in pixels.</p><p>The top left corner, width and height of the source rectangle, that is 36the area actually sampled, is given by the <code class="constant">V4L2_SEL_TGT_CROP</code> 37target. It uses the same coordinate system as <code class="constant">V4L2_SEL_TGT_CROP_BOUNDS</code>. 38The active cropping area must lie completely inside the capture boundaries. The 39driver may further adjust the requested size and/or position according to hardware 40limitations.</p><p>Each capture device has a default source rectangle, given by the 41<code class="constant">V4L2_SEL_TGT_CROP_DEFAULT</code> target. This rectangle shall 42over what the driver writer considers the complete picture. Drivers shall set 43the active crop rectangle to the default when the driver is first loaded, but 44not later.</p><p>The composing targets refer to a memory buffer. The limits of composing 45coordinates are obtained using <code class="constant">V4L2_SEL_TGT_COMPOSE_BOUNDS</code>. 46All coordinates are expressed in pixels. The rectangle's top/left 47corner must be located at position <code class="constant">(0,0)</code>. The width and 48height are equal to the image size set by <code class="constant">VIDIOC_S_FMT</code>. 49</p><p>The part of a buffer into which the image is inserted by the hardware is 50controlled by the <code class="constant">V4L2_SEL_TGT_COMPOSE</code> target. 51The rectangle's coordinates are also expressed in the same coordinate system as 52the bounds rectangle. The composing rectangle must lie completely inside bounds 53rectangle. The driver must adjust the composing rectangle to fit to the 54bounding limits. Moreover, the driver can perform other adjustments according 55to hardware limitations. The application can control rounding behaviour using 56<a class="link" href="apb.html#v4l2-selection-flags" title="Selection flags"> constraint flags</a>.</p><p>For capture devices the default composing rectangle is queried using 57<code class="constant">V4L2_SEL_TGT_COMPOSE_DEFAULT</code>. It is usually equal to the 58bounding rectangle.</p><p>The part of a buffer that is modified by the hardware is given by 59<code class="constant">V4L2_SEL_TGT_COMPOSE_PADDED</code>. It contains all pixels 60defined using <code class="constant">V4L2_SEL_TGT_COMPOSE</code> plus all 61padding data modified by hardware during insertion process. All pixels outside 62this rectangle <span class="emphasis"><em>must not</em></span> be changed by the hardware. The 63content of pixels that lie inside the padded area but outside active area is 64undefined. The application can use the padded and active rectangles to detect 65where the rubbish pixels are located and remove them if needed.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="idp1099074500"></a>Configuration of video output</h4></div></div></div><p>For output devices targets and ioctls are used similarly to the video 66capture case. The <span class="emphasis"><em>composing</em></span> rectangle refers to the 67insertion of an image into a video signal. The cropping rectangles refer to a 68memory buffer. It is recommended to configure the composing targets before to 69the cropping targets.</p><p>The cropping targets refer to the memory buffer that contains an image to 70be inserted into a video signal or graphical screen. The limits of cropping 71coordinates are obtained using <code class="constant">V4L2_SEL_TGT_CROP_BOUNDS</code>. 72All coordinates are expressed in pixels. The top/left corner is always point 73<code class="constant">(0,0)</code>. The width and height is equal to the image size 74specified using <code class="constant">VIDIOC_S_FMT</code> ioctl.</p><p>The top left corner, width and height of the source rectangle, that is 75the area from which image date are processed by the hardware, is given by the 76<code class="constant">V4L2_SEL_TGT_CROP</code>. Its coordinates are expressed 77in in the same coordinate system as the bounds rectangle. The active cropping 78area must lie completely inside the crop boundaries and the driver may further 79adjust the requested size and/or position according to hardware 80limitations.</p><p>For output devices the default cropping rectangle is queried using 81<code class="constant">V4L2_SEL_TGT_CROP_DEFAULT</code>. It is usually equal to the 82bounding rectangle.</p><p>The part of a video signal or graphics display where the image is 83inserted by the hardware is controlled by <code class="constant">V4L2_SEL_TGT_COMPOSE</code> 84target. The rectangle's coordinates are expressed in pixels. The composing 85rectangle must lie completely inside the bounds rectangle. The driver must 86adjust the area to fit to the bounding limits. Moreover, the driver can 87perform other adjustments according to hardware limitations.</p><p>The device has a default composing rectangle, given by the 88<code class="constant">V4L2_SEL_TGT_COMPOSE_DEFAULT</code> target. This rectangle shall cover what 89the driver writer considers the complete picture. It is recommended for the 90driver developers to put the top/left corner at position <code class="constant">(0,0)</code>. 91Drivers shall set the active composing rectangle to the default 92one when the driver is first loaded.</p><p>The devices may introduce additional content to video signal other than 93an image from memory buffers. It includes borders around an image. However, 94such a padded area is driver-dependent feature not covered by this document. 95Driver developers are encouraged to keep padded rectangle equal to active one. 96The padded target is accessed by the <code class="constant">V4L2_SEL_TGT_COMPOSE_PADDED</code> 97identifier. It must contain all pixels from the <code class="constant">V4L2_SEL_TGT_COMPOSE</code> 98target.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="idp1099081108"></a>Scaling control</h4></div></div></div><p>An application can detect if scaling is performed by comparing the width 99and the height of rectangles obtained using <code class="constant">V4L2_SEL_TGT_CROP</code> 100and <code class="constant">V4L2_SEL_TGT_COMPOSE</code> targets. If 101these are not equal then the scaling is applied. The application can compute 102the scaling ratios using these values.</p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1099082516"></a>Comparison with old cropping API</h3></div></div></div><p>The selection API was introduced to cope with deficiencies of previous 103<a class="link" href="crop.html" title="Image Cropping, Insertion and Scaling"> API</a>, that was designed to control simple capture 104devices. Later the cropping API was adopted by video output drivers. The ioctls 105are used to select a part of the display were the video signal is inserted. It 106should be considered as an API abuse because the described operation is 107actually the composing. The selection API makes a clear distinction between 108composing and cropping operations by setting the appropriate targets. The V4L2 109API lacks any support for composing to and cropping from an image inside a 110memory buffer. The application could configure a capture device to fill only a 111part of an image by abusing V4L2 API. Cropping a smaller image from a larger 112one is achieved by setting the field 113struct <a class="link" href="pixfmt.html#v4l2-pix-format" title="Table 2.1. struct v4l2_pix_format">v4l2_pix_format</a><em class="structfield"><code>::bytesperline</code></em>. Introducing an image offsets 114could be done by modifying field struct <a class="link" href="buffer.html#v4l2-buffer" title="Table 3.1. struct v4l2_buffer">v4l2_buffer</a><em class="structfield"><code>::m_userptr</code></em> 115before calling <code class="constant">VIDIOC_QBUF</code>. Those 116operations should be avoided because they are not portable (endianness), and do 117not work for macroblock and Bayer formats and mmap buffers. The selection API 118deals with configuration of buffer cropping/composing in a clear, intuitive and 119portable way. Next, with the selection API the concepts of the padded target 120and constraints flags are introduced. Finally, struct <a class="link" href="vidioc-g-crop.html#v4l2-crop" title="Table A.55. struct v4l2_crop">v4l2_crop</a> and struct <a class="link" href="vidioc-cropcap.html#v4l2-cropcap" title="Table A.2. struct v4l2_cropcap">v4l2_cropcap</a> 121have no reserved fields. Therefore there is no way to extend their functionality. 122The new struct <a class="link" href="vidioc-g-selection.html#v4l2-selection" title="Table A.84. struct v4l2_selection">v4l2_selection</a> provides a lot of place for future 123extensions. Driver developers are encouraged to implement only selection API. 124The former cropping API would be simulated using the new one.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1099087124"></a>Examples</h3></div></div></div><div class="example"><a name="idp1099088212"></a><p class="title"><b>Example 1.15. Resetting the cropping parameters</b></p><div class="example-contents"><p>(A video capture device is assumed; change 125<code class="constant">V4L2_BUF_TYPE_VIDEO_CAPTURE</code> for other devices; change target to 126<code class="constant">V4L2_SEL_TGT_COMPOSE_*</code> family to configure composing 127area)</p><pre class="programlisting"> 128 129 struct <a class="link" href="vidioc-g-selection.html#v4l2-selection" title="Table A.84. struct v4l2_selection">v4l2_selection</a> sel = { 130 .type = V4L2_BUF_TYPE_VIDEO_CAPTURE, 131 .target = V4L2_SEL_TGT_CROP_DEFAULT, 132 }; 133 ret = ioctl(fd, <a class="link" href="vidioc-g-selection.html" title="ioctl VIDIOC_G_SELECTION, VIDIOC_S_SELECTION"><code class="constant">VIDIOC_G_SELECTION</code></a>, &sel); 134 if (ret) 135 exit(-1); 136 sel.target = V4L2_SEL_TGT_CROP; 137 ret = ioctl(fd, <a class="link" href="vidioc-g-selection.html" title="ioctl VIDIOC_G_SELECTION, VIDIOC_S_SELECTION"><code class="constant">VIDIOC_S_SELECTION</code></a>, &sel); 138 if (ret) 139 exit(-1); 140 141 </pre></div></div><br class="example-break"><div class="example"><a name="idp1099091620"></a><p class="title"><b>Example 1.16. Simple downscaling</b></p><div class="example-contents"><p>Setting a composing area on output of size of <span class="emphasis"><em> at most 142</em></span> half of limit placed at a center of a display.</p><pre class="programlisting"> 143 144 struct <a class="link" href="vidioc-g-selection.html#v4l2-selection" title="Table A.84. struct v4l2_selection">v4l2_selection</a> sel = { 145 .type = V4L2_BUF_TYPE_VIDEO_OUTPUT, 146 .target = V4L2_SEL_TGT_COMPOSE_BOUNDS, 147 }; 148 struct v4l2_rect r; 149 150 ret = ioctl(fd, <a class="link" href="vidioc-g-selection.html" title="ioctl VIDIOC_G_SELECTION, VIDIOC_S_SELECTION"><code class="constant">VIDIOC_G_SELECTION</code></a>, &sel); 151 if (ret) 152 exit(-1); 153 /* setting smaller compose rectangle */ 154 r.width = sel.r.width / 2; 155 r.height = sel.r.height / 2; 156 r.left = sel.r.width / 4; 157 r.top = sel.r.height / 4; 158 sel.r = r; 159 sel.target = V4L2_SEL_TGT_COMPOSE; 160 sel.flags = V4L2_SEL_FLAG_LE; 161 ret = ioctl(fd, <a class="link" href="vidioc-g-selection.html" title="ioctl VIDIOC_G_SELECTION, VIDIOC_S_SELECTION"><code class="constant">VIDIOC_S_SELECTION</code></a>, &sel); 162 if (ret) 163 exit(-1); 164 165 </pre></div></div><br class="example-break"><div class="example"><a name="idp1099095340"></a><p class="title"><b>Example 1.17. Querying for scaling factors</b></p><div class="example-contents"><p>A video output device is assumed; change 166<code class="constant">V4L2_BUF_TYPE_VIDEO_OUTPUT</code> for other devices</p><pre class="programlisting"> 167 168 struct <a class="link" href="vidioc-g-selection.html#v4l2-selection" title="Table A.84. struct v4l2_selection">v4l2_selection</a> compose = { 169 .type = V4L2_BUF_TYPE_VIDEO_OUTPUT, 170 .target = V4L2_SEL_TGT_COMPOSE, 171 }; 172 struct <a class="link" href="vidioc-g-selection.html#v4l2-selection" title="Table A.84. struct v4l2_selection">v4l2_selection</a> crop = { 173 .type = V4L2_BUF_TYPE_VIDEO_OUTPUT, 174 .target = V4L2_SEL_TGT_CROP, 175 }; 176 double hscale, vscale; 177 178 ret = ioctl(fd, <a class="link" href="vidioc-g-selection.html" title="ioctl VIDIOC_G_SELECTION, VIDIOC_S_SELECTION"><code class="constant">VIDIOC_G_SELECTION</code></a>, &compose); 179 if (ret) 180 exit(-1); 181 ret = ioctl(fd, <a class="link" href="vidioc-g-selection.html" title="ioctl VIDIOC_G_SELECTION, VIDIOC_S_SELECTION"><code class="constant">VIDIOC_G_SELECTION</code></a>, &crop); 182 if (ret) 183 exit(-1); 184 185 /* computing scaling factors */ 186 hscale = (double)compose.r.width / crop.r.width; 187 vscale = (double)compose.r.height / crop.r.height; 188 189 </pre></div></div><br class="example-break"></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="crop.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="common.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="streaming-par.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Image Cropping, Insertion and Scaling </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Streaming Parameters</td></tr></table></div></body></html> 190
