1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd"> 2 <HTML 3 ><HEAD 4 ><TITLE 5 >Data Formats</TITLE 6 ><META 7 NAME="GENERATOR" 8 CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK 9 REL="HOME" 10 TITLE="Video for Linux Two API Specification" 11 HREF="book1.htm"><LINK 12 REL="UP" 13 TITLE="Common API Elements" 14 HREF="c174.htm"><LINK 15 REL="PREVIOUS" 16 TITLE="Extended Controls" 17 HREF="x802.htm"><LINK 18 REL="NEXT" 19 TITLE="Image Cropping, Insertion and Scaling" 20 HREF="x1904.htm"></HEAD 21 ><BODY 22 CLASS="SECTION" 23 BGCOLOR="#FFFFFF" 24 TEXT="#000000" 25 LINK="#0000FF" 26 VLINK="#840084" 27 ALINK="#0000FF" 28 ><DIV 29 CLASS="NAVHEADER" 30 ><TABLE 31 SUMMARY="Header navigation table" 32 WIDTH="100%" 33 BORDER="0" 34 CELLPADDING="0" 35 CELLSPACING="0" 36 ><TR 37 ><TH 38 COLSPAN="3" 39 ALIGN="center" 40 >Video for Linux Two API Specification: Revision 0.24</TH 41 ></TR 42 ><TR 43 ><TD 44 WIDTH="10%" 45 ALIGN="left" 46 VALIGN="bottom" 47 ><A 48 HREF="x802.htm" 49 ACCESSKEY="P" 50 >Prev</A 51 ></TD 52 ><TD 53 WIDTH="80%" 54 ALIGN="center" 55 VALIGN="bottom" 56 >Chapter 1. Common API Elements</TD 57 ><TD 58 WIDTH="10%" 59 ALIGN="right" 60 VALIGN="bottom" 61 ><A 62 HREF="x1904.htm" 63 ACCESSKEY="N" 64 >Next</A 65 ></TD 66 ></TR 67 ></TABLE 68 ><HR 69 ALIGN="LEFT" 70 WIDTH="100%"></DIV 71 ><DIV 72 CLASS="SECTION" 73 ><H1 74 CLASS="SECTION" 75 ><A 76 NAME="FORMAT" 77 >1.10. Data Formats</A 78 ></H1 79 ><DIV 80 CLASS="SECTION" 81 ><H2 82 CLASS="SECTION" 83 ><A 84 NAME="AEN1861" 85 >1.10.1. Data Format Negotiation</A 86 ></H2 87 ><P 88 >Different devices exchange different kinds of data with 89 applications, for example video images, raw or sliced VBI data, RDS 90 datagrams. Even within one kind many different formats are possible, 91 in particular an abundance of image formats. Although drivers must 92 provide a default and the selection persists across closing and 93 reopening a device, applications should always negotiate a data format 94 before engaging in data exchange. Negotiation means the application 95 asks for a particular format and the driver selects and reports the 96 best the hardware can do to satisfy the request. Of course 97 applications can also just query the current selection.</P 98 ><P 99 >A single mechanism exists to negotiate all data formats 100 using the aggregate struct <A 101 HREF="r10944.htm#V4L2-FORMAT" 102 >v4l2_format</A 103 > and the <A 104 HREF="r10944.htm" 105 ><CODE 106 CLASS="CONSTANT" 107 >VIDIOC_G_FMT</CODE 108 ></A 109 > and 110 <A 111 HREF="r10944.htm" 112 ><CODE 113 CLASS="CONSTANT" 114 >VIDIOC_S_FMT</CODE 115 ></A 116 > ioctls. Additionally the <A 117 HREF="r10944.htm" 118 ><CODE 119 CLASS="CONSTANT" 120 >VIDIOC_TRY_FMT</CODE 121 ></A 122 > ioctl can be 123 used to examine what the hardware <SPAN 124 CLASS="emphasis" 125 ><I 126 CLASS="EMPHASIS" 127 >could</I 128 ></SPAN 129 > do, 130 without actually selecting a new data format. The data formats 131 supported by the V4L2 API are covered in the respective device section 132 in <A 133 HREF="c6488.htm" 134 >Chapter 4</A 135 >. For a closer look at image formats see 136 <A 137 HREF="c2030.htm" 138 >Chapter 2</A 139 >.</P 140 ><P 141 >The <CODE 142 CLASS="CONSTANT" 143 >VIDIOC_S_FMT</CODE 144 > ioctl is a major 145 turning-point in the initialization sequence. Prior to this point 146 multiple panel applications can access the same device concurrently to 147 select the current input, change controls or modify other properties. 148 The first <CODE 149 CLASS="CONSTANT" 150 >VIDIOC_S_FMT</CODE 151 > assigns a logical stream 152 (video data, VBI data etc.) exclusively to one file descriptor.</P 153 ><P 154 >Exclusive means no other application, more precisely no 155 other file descriptor, can grab this stream or change device 156 properties inconsistent with the negotiated parameters. A video 157 standard change for example, when the new standard uses a different 158 number of scan lines, can invalidate the selected image format. 159 Therefore only the file descriptor owning the stream can make 160 invalidating changes. Accordingly multiple file descriptors which 161 grabbed different logical streams prevent each other from interfering 162 with their settings. When for example video overlay is about to start 163 or already in progress, simultaneous video capturing may be restricted 164 to the same cropping and image size.</P 165 ><P 166 >When applications omit the 167 <CODE 168 CLASS="CONSTANT" 169 >VIDIOC_S_FMT</CODE 170 > ioctl its locking side effects are 171 implied by the next step, the selection of an I/O method with the 172 <A 173 HREF="r13696.htm" 174 ><CODE 175 CLASS="CONSTANT" 176 >VIDIOC_REQBUFS</CODE 177 ></A 178 > ioctl or implicit with the first <A 179 HREF="r14264.htm" 180 ><CODE 181 CLASS="FUNCTION" 182 >read()</CODE 183 ></A 184 > or 185 <A 186 HREF="r14496.htm" 187 ><CODE 188 CLASS="FUNCTION" 189 >write()</CODE 190 ></A 191 > call.</P 192 ><P 193 >Generally only one logical stream can be assigned to a 194 file descriptor, the exception being drivers permitting simultaneous 195 video capturing and overlay using the same file descriptor for 196 compatibility with V4L and earlier versions of V4L2. Switching the 197 logical stream or returning into "panel mode" is possible by closing 198 and reopening the device. Drivers <SPAN 199 CLASS="emphasis" 200 ><I 201 CLASS="EMPHASIS" 202 >may</I 203 ></SPAN 204 > support a 205 switch using <CODE 206 CLASS="CONSTANT" 207 >VIDIOC_S_FMT</CODE 208 >.</P 209 ><P 210 >All drivers exchanging data with 211 applications must support the <CODE 212 CLASS="CONSTANT" 213 >VIDIOC_G_FMT</CODE 214 > and 215 <CODE 216 CLASS="CONSTANT" 217 >VIDIOC_S_FMT</CODE 218 > ioctl. Implementation of the 219 <CODE 220 CLASS="CONSTANT" 221 >VIDIOC_TRY_FMT</CODE 222 > is highly recommended but 223 optional.</P 224 ></DIV 225 ><DIV 226 CLASS="SECTION" 227 ><H2 228 CLASS="SECTION" 229 ><A 230 NAME="AEN1894" 231 >1.10.2. Image Format Enumeration</A 232 ></H2 233 ><P 234 >Apart of the generic format negotiation functions 235 a special ioctl to enumerate all image formats supported by video 236 capture, overlay or output devices is available.<A 237 NAME="AEN1897" 238 HREF="x1859.htm#FTN.AEN1897" 239 ><SPAN 240 CLASS="footnote" 241 >[1]</SPAN 242 ></A 243 ></P 244 ><P 245 >The <A 246 HREF="r8367.htm" 247 ><CODE 248 CLASS="CONSTANT" 249 >VIDIOC_ENUM_FMT</CODE 250 ></A 251 > ioctl must be supported 252 by all drivers exchanging image data with applications.</P 253 ><DIV 254 CLASS="IMPORTANT" 255 ><BLOCKQUOTE 256 CLASS="IMPORTANT" 257 ><P 258 ><B 259 >Important: </B 260 >Drivers are not supposed to convert image formats in 261 kernel space. They must enumerate only formats directly supported by 262 the hardware. If necessary driver writers should publish an example 263 conversion routine or library for integration into applications.</P 264 ></BLOCKQUOTE 265 ></DIV 266 ></DIV 267 ></DIV 268 ><H3 269 CLASS="FOOTNOTES" 270 >Notes</H3 271 ><TABLE 272 BORDER="0" 273 CLASS="FOOTNOTES" 274 WIDTH="100%" 275 ><TR 276 ><TD 277 ALIGN="LEFT" 278 VALIGN="TOP" 279 WIDTH="5%" 280 ><A 281 NAME="FTN.AEN1897" 282 HREF="x1859.htm#AEN1897" 283 ><SPAN 284 CLASS="footnote" 285 >[1]</SPAN 286 ></A 287 ></TD 288 ><TD 289 ALIGN="LEFT" 290 VALIGN="TOP" 291 WIDTH="95%" 292 ><P 293 >Enumerating formats an application has no a-priori 294 knowledge of (otherwise it could explicitely ask for them and need not 295 enumerate) seems useless, but there are applications serving as proxy 296 between drivers and the actual video applications for which this is 297 useful.</P 298 ></TD 299 ></TR 300 ></TABLE 301 ><DIV 302 CLASS="NAVFOOTER" 303 ><HR 304 ALIGN="LEFT" 305 WIDTH="100%"><TABLE 306 SUMMARY="Footer navigation table" 307 WIDTH="100%" 308 BORDER="0" 309 CELLPADDING="0" 310 CELLSPACING="0" 311 ><TR 312 ><TD 313 WIDTH="33%" 314 ALIGN="left" 315 VALIGN="top" 316 ><A 317 HREF="x802.htm" 318 ACCESSKEY="P" 319 >Prev</A 320 ></TD 321 ><TD 322 WIDTH="34%" 323 ALIGN="center" 324 VALIGN="top" 325 ><A 326 HREF="book1.htm" 327 ACCESSKEY="H" 328 >Home</A 329 ></TD 330 ><TD 331 WIDTH="33%" 332 ALIGN="right" 333 VALIGN="top" 334 ><A 335 HREF="x1904.htm" 336 ACCESSKEY="N" 337 >Next</A 338 ></TD 339 ></TR 340 ><TR 341 ><TD 342 WIDTH="33%" 343 ALIGN="left" 344 VALIGN="top" 345 >Extended Controls</TD 346 ><TD 347 WIDTH="34%" 348 ALIGN="center" 349 VALIGN="top" 350 ><A 351 HREF="c174.htm" 352 ACCESSKEY="U" 353 >Up</A 354 ></TD 355 ><TD 356 WIDTH="33%" 357 ALIGN="right" 358 VALIGN="top" 359 >Image Cropping, Insertion and Scaling</TD 360 ></TR 361 ></TABLE 362 ></DIV 363 ></BODY 364 ></HTML 365 > 366
