1<section id="v4l2-selections-common"> 2 3 <title>Common selection definitions</title> 4 5 <para>While the <link linkend="selection-api">V4L2 selection 6 API</link> and <link linkend="v4l2-subdev-selections">V4L2 subdev 7 selection APIs</link> are very similar, there's one fundamental 8 difference between the two. On sub-device API, the selection 9 rectangle refers to the media bus format, and is bound to a 10 sub-device's pad. On the V4L2 interface the selection rectangles 11 refer to the in-memory pixel format.</para> 12 13 <para>This section defines the common definitions of the 14 selection interfaces on the two APIs.</para> 15 16 <section id="v4l2-selection-targets"> 17 18 <title>Selection targets</title> 19 20 <para>The precise meaning of the selection targets may be 21 dependent on which of the two interfaces they are used.</para> 22 23 <table pgwide="1" frame="none" id="v4l2-selection-targets-table"> 24 <title>Selection target definitions</title> 25 <tgroup cols="5"> 26 <colspec colname="c1" /> 27 <colspec colname="c2" /> 28 <colspec colname="c3" /> 29 <colspec colname="c4" /> 30 <colspec colname="c5" /> 31 &cs-def; 32 <thead> 33 <row rowsep="1"> 34 <entry align="left">Target name</entry> 35 <entry align="left">id</entry> 36 <entry align="left">Definition</entry> 37 <entry align="left">Valid for V4L2</entry> 38 <entry align="left">Valid for V4L2 subdev</entry> 39 </row> 40 </thead> 41 <tbody valign="top"> 42 <row> 43 <entry><constant>V4L2_SEL_TGT_CROP</constant></entry> 44 <entry>0x0000</entry> 45 <entry>Crop rectangle. Defines the cropped area.</entry> 46 <entry>Yes</entry> 47 <entry>Yes</entry> 48 </row> 49 <row> 50 <entry><constant>V4L2_SEL_TGT_CROP_DEFAULT</constant></entry> 51 <entry>0x0001</entry> 52 <entry>Suggested cropping rectangle that covers the "whole picture".</entry> 53 <entry>Yes</entry> 54 <entry>No</entry> 55 </row> 56 <row> 57 <entry><constant>V4L2_SEL_TGT_CROP_BOUNDS</constant></entry> 58 <entry>0x0002</entry> 59 <entry>Bounds of the crop rectangle. All valid crop 60 rectangles fit inside the crop bounds rectangle. 61 </entry> 62 <entry>Yes</entry> 63 <entry>Yes</entry> 64 </row> 65 <row> 66 <entry><constant>V4L2_SEL_TGT_NATIVE_SIZE</constant></entry> 67 <entry>0x0003</entry> 68 <entry>The native size of the device, e.g. a sensor's 69 pixel array. <structfield>left</structfield> and 70 <structfield>top</structfield> fields are zero for this 71 target. Setting the native size will generally only make 72 sense for memory to memory devices where the software can 73 create a canvas of a given size in which for example a 74 video frame can be composed. In that case 75 V4L2_SEL_TGT_NATIVE_SIZE can be used to configure the size 76 of that canvas. 77 </entry> 78 <entry>Yes</entry> 79 <entry>Yes</entry> 80 </row> 81 <row> 82 <entry><constant>V4L2_SEL_TGT_COMPOSE</constant></entry> 83 <entry>0x0100</entry> 84 <entry>Compose rectangle. Used to configure scaling 85 and composition.</entry> 86 <entry>Yes</entry> 87 <entry>Yes</entry> 88 </row> 89 <row> 90 <entry><constant>V4L2_SEL_TGT_COMPOSE_DEFAULT</constant></entry> 91 <entry>0x0101</entry> 92 <entry>Suggested composition rectangle that covers the "whole picture".</entry> 93 <entry>Yes</entry> 94 <entry>No</entry> 95 </row> 96 <row> 97 <entry><constant>V4L2_SEL_TGT_COMPOSE_BOUNDS</constant></entry> 98 <entry>0x0102</entry> 99 <entry>Bounds of the compose rectangle. All valid compose 100 rectangles fit inside the compose bounds rectangle.</entry> 101 <entry>Yes</entry> 102 <entry>Yes</entry> 103 </row> 104 <row> 105 <entry><constant>V4L2_SEL_TGT_COMPOSE_PADDED</constant></entry> 106 <entry>0x0103</entry> 107 <entry>The active area and all padding pixels that are inserted or 108 modified by hardware.</entry> 109 <entry>Yes</entry> 110 <entry>No</entry> 111 </row> 112 </tbody> 113 </tgroup> 114 </table> 115 116 </section> 117 118 <section id="v4l2-selection-flags"> 119 120 <title>Selection flags</title> 121 122 <table pgwide="1" frame="none" id="v4l2-selection-flags-table"> 123 <title>Selection flag definitions</title> 124 <tgroup cols="5"> 125 <colspec colname="c1" /> 126 <colspec colname="c2" /> 127 <colspec colname="c3" /> 128 <colspec colname="c4" /> 129 <colspec colname="c5" /> 130 &cs-def; 131 <thead> 132 <row rowsep="1"> 133 <entry align="left">Flag name</entry> 134 <entry align="left">id</entry> 135 <entry align="left">Definition</entry> 136 <entry align="left">Valid for V4L2</entry> 137 <entry align="left">Valid for V4L2 subdev</entry> 138 </row> 139 </thead> 140 <tbody valign="top"> 141 <row> 142 <entry><constant>V4L2_SEL_FLAG_GE</constant></entry> 143 <entry>(1 << 0)</entry> 144 <entry>Suggest the driver it should choose greater or 145 equal rectangle (in size) than was requested. Albeit the 146 driver may choose a lesser size, it will only do so due to 147 hardware limitations. Without this flag (and 148 <constant>V4L2_SEL_FLAG_LE</constant>) the 149 behaviour is to choose the closest possible 150 rectangle.</entry> 151 <entry>Yes</entry> 152 <entry>Yes</entry> 153 </row> 154 <row> 155 <entry><constant>V4L2_SEL_FLAG_LE</constant></entry> 156 <entry>(1 << 1)</entry> 157 <entry>Suggest the driver it 158 should choose lesser or equal rectangle (in size) than was 159 requested. Albeit the driver may choose a greater size, it 160 will only do so due to hardware limitations.</entry> 161 <entry>Yes</entry> 162 <entry>Yes</entry> 163 </row> 164 <row> 165 <entry><constant>V4L2_SEL_FLAG_KEEP_CONFIG</constant></entry> 166 <entry>(1 << 2)</entry> 167 <entry>The configuration must not be propagated to any 168 further processing steps. If this flag is not given, the 169 configuration is propagated inside the subdevice to all 170 further processing steps.</entry> 171 <entry>No</entry> 172 <entry>Yes</entry> 173 </row> 174 </tbody> 175 </tgroup> 176 </table> 177 178 </section> 179 180</section> 181