1 <title>Sliced VBI Data Interface</title> 2 3 <para>VBI stands for Vertical Blanking Interval, a gap in the 4sequence of lines of an analog video signal. During VBI no picture 5information is transmitted, allowing some time while the electron beam 6of a cathode ray tube TV returns to the top of the screen.</para> 7 8 <para>Sliced VBI devices use hardware to demodulate data transmitted 9in the VBI. V4L2 drivers shall <emphasis>not</emphasis> do this by 10software, see also the <link linkend="raw-vbi">raw VBI 11interface</link>. The data is passed as short packets of fixed size, 12covering one scan line each. The number of packets per video frame is 13variable.</para> 14 15 <para>Sliced VBI capture and output devices are accessed through the 16same character special files as raw VBI devices. When a driver 17supports both interfaces, the default function of a 18<filename>/dev/vbi</filename> device is <emphasis>raw</emphasis> VBI 19capturing or output, and the sliced VBI function is only available 20after calling the &VIDIOC-S-FMT; ioctl as defined below. Likewise a 21<filename>/dev/video</filename> device may support the sliced VBI API, 22however the default function here is video capturing or output. 23Different file descriptors must be used to pass raw and sliced VBI 24data simultaneously, if this is supported by the driver.</para> 25 26 <section> 27 <title>Querying Capabilities</title> 28 29 <para>Devices supporting the sliced VBI capturing or output API 30set the <constant>V4L2_CAP_SLICED_VBI_CAPTURE</constant> or 31<constant>V4L2_CAP_SLICED_VBI_OUTPUT</constant> flag respectively, in 32the <structfield>capabilities</structfield> field of &v4l2-capability; 33returned by the &VIDIOC-QUERYCAP; ioctl. At least one of the 34read/write, streaming or asynchronous <link linkend="io">I/O 35methods</link> must be supported. Sliced VBI devices may have a tuner 36or modulator.</para> 37 </section> 38 39 <section> 40 <title>Supplemental Functions</title> 41 42 <para>Sliced VBI devices shall support <link linkend="video">video 43input or output</link> and <link linkend="tuner">tuner or 44modulator</link> ioctls if they have these capabilities, and they may 45support <link linkend="control">control</link> ioctls. The <link 46linkend="standard">video standard</link> ioctls provide information 47vital to program a sliced VBI device, therefore must be 48supported.</para> 49 </section> 50 51 <section id="sliced-vbi-format-negotitation"> 52 <title>Sliced VBI Format Negotiation</title> 53 54 <para>To find out which data services are supported by the 55hardware applications can call the &VIDIOC-G-SLICED-VBI-CAP; ioctl. 56All drivers implementing the sliced VBI interface must support this 57ioctl. The results may differ from those of the &VIDIOC-S-FMT; ioctl 58when the number of VBI lines the hardware can capture or output per 59frame, or the number of services it can identify on a given line are 60limited. For example on PAL line 16 the hardware may be able to look 61for a VPS or Teletext signal, but not both at the same time.</para> 62 63 <para>To determine the currently selected services applications 64set the <structfield>type </structfield> field of &v4l2-format; to 65<constant> V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant> or <constant> 66V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant>, and the &VIDIOC-G-FMT; 67ioctl fills the <structfield>fmt.sliced</structfield> member, a 68&v4l2-sliced-vbi-format;.</para> 69 70 <para>Applications can request different parameters by 71initializing or modifying the <structfield>fmt.sliced</structfield> 72member and calling the &VIDIOC-S-FMT; ioctl with a pointer to the 73<structname>v4l2_format</structname> structure.</para> 74 75 <para>The sliced VBI API is more complicated than the raw VBI API 76because the hardware must be told which VBI service to expect on each 77scan line. Not all services may be supported by the hardware on all 78lines (this is especially true for VBI output where Teletext is often 79unsupported and other services can only be inserted in one specific 80line). In many cases, however, it is sufficient to just set the 81<structfield>service_set</structfield> field to the required services 82and let the driver fill the <structfield>service_lines</structfield> 83array according to hardware capabilities. Only if more precise control 84is needed should the programmer set the 85<structfield>service_lines</structfield> array explicitly.</para> 86 87 <para>The &VIDIOC-S-FMT; ioctl modifies the parameters 88according to hardware capabilities. When the driver allocates 89resources at this point, it may return an &EBUSY; if the required 90resources are temporarily unavailable. Other resource allocation 91points which may return <errorcode>EBUSY</errorcode> can be the 92&VIDIOC-STREAMON; ioctl and the first &func-read;, &func-write; and 93&func-select; call.</para> 94 95 <table frame="none" pgwide="1" id="v4l2-sliced-vbi-format"> 96 <title>struct 97<structname>v4l2_sliced_vbi_format</structname></title> 98 <tgroup cols="5"> 99 <colspec colname="c1" colwidth="3*" /> 100 <colspec colname="c2" colwidth="3*" /> 101 <colspec colname="c3" colwidth="2*" /> 102 <colspec colname="c4" colwidth="2*" /> 103 <colspec colname="c5" colwidth="2*" /> 104 <spanspec namest="c3" nameend="c5" spanname="hspan" /> 105 <tbody valign="top"> 106 <row> 107 <entry>__u32</entry> 108 <entry><structfield>service_set</structfield></entry> 109 <entry spanname="hspan"><para>If 110<structfield>service_set</structfield> is non-zero when passed with 111&VIDIOC-S-FMT; or &VIDIOC-TRY-FMT;, the 112<structfield>service_lines</structfield> array will be filled by the 113driver according to the services specified in this field. For example, 114if <structfield>service_set</structfield> is initialized with 115<constant>V4L2_SLICED_TELETEXT_B | V4L2_SLICED_WSS_625</constant>, a 116driver for the cx25840 video decoder sets lines 7-22 of both 117fields<footnote><para>According to <link 118linkend="ets300706">ETS 300 706</link> lines 6-22 of the 119first field and lines 5-22 of the second field may carry Teletext 120data.</para></footnote> to <constant>V4L2_SLICED_TELETEXT_B</constant> 121and line 23 of the first field to 122<constant>V4L2_SLICED_WSS_625</constant>. If 123<structfield>service_set</structfield> is set to zero, then the values 124of <structfield>service_lines</structfield> will be used instead. 125</para><para>On return the driver sets this field to the union of all 126elements of the returned <structfield>service_lines</structfield> 127array. It may contain less services than requested, perhaps just one, 128if the hardware cannot handle more services simultaneously. It may be 129empty (zero) if none of the requested services are supported by the 130hardware.</para></entry> 131 </row> 132 <row> 133 <entry>__u16</entry> 134 <entry><structfield>service_lines</structfield>[2][24]</entry> 135 <entry spanname="hspan"><para>Applications initialize this 136array with sets of data services the driver shall look for or insert 137on the respective scan line. Subject to hardware capabilities drivers 138return the requested set, a subset, which may be just a single 139service, or an empty set. When the hardware cannot handle multiple 140services on the same line the driver shall choose one. No assumptions 141can be made on which service the driver chooses.</para><para>Data 142services are defined in <xref linkend="vbi-services2" />. Array indices 143map to ITU-R line numbers (see also <xref linkend="vbi-525" /> and <xref 144 linkend="vbi-625" />) as follows: <!-- No nested 145tables, sigh. --></para></entry> 146 </row> 147 <row> 148 <entry></entry> 149 <entry></entry> 150 <entry>Element</entry> 151 <entry>525 line systems</entry> 152 <entry>625 line systems</entry> 153 </row> 154 <row> 155 <entry></entry> 156 <entry></entry> 157 <entry><structfield>service_lines</structfield>[0][1]</entry> 158 <entry align="center">1</entry> 159 <entry align="center">1</entry> 160 </row> 161 <row> 162 <entry></entry> 163 <entry></entry> 164 <entry><structfield>service_lines</structfield>[0][23]</entry> 165 <entry align="center">23</entry> 166 <entry align="center">23</entry> 167 </row> 168 <row> 169 <entry></entry> 170 <entry></entry> 171 <entry><structfield>service_lines</structfield>[1][1]</entry> 172 <entry align="center">264</entry> 173 <entry align="center">314</entry> 174 </row> 175 <row> 176 <entry></entry> 177 <entry></entry> 178 <entry><structfield>service_lines</structfield>[1][23]</entry> 179 <entry align="center">286</entry> 180 <entry align="center">336</entry> 181 </row> 182 <!-- End of line numbers table. --> 183 <row> 184 <entry></entry> 185 <entry></entry> 186 <entry spanname="hspan">Drivers must set 187<structfield>service_lines</structfield>[0][0] and 188<structfield>service_lines</structfield>[1][0] to zero. 189The <constant>V4L2_VBI_ITU_525_F1_START</constant>, 190<constant>V4L2_VBI_ITU_525_F2_START</constant>, 191<constant>V4L2_VBI_ITU_625_F1_START</constant> and 192<constant>V4L2_VBI_ITU_625_F2_START</constant> defines give the start 193line numbers for each field for each 525 or 625 line format as a 194convenience. Don't forget that ITU line numbering starts at 1, not 0. 195</entry> 196 </row> 197 <row> 198 <entry>__u32</entry> 199 <entry><structfield>io_size</structfield></entry> 200 <entry spanname="hspan">Maximum number of bytes passed by 201one &func-read; or &func-write; call, and the buffer size in bytes for 202the &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. Drivers set this field to 203the size of &v4l2-sliced-vbi-data; times the number of non-zero 204elements in the returned <structfield>service_lines</structfield> 205array (that is the number of lines potentially carrying data).</entry> 206 </row> 207 <row> 208 <entry>__u32</entry> 209 <entry><structfield>reserved</structfield>[2]</entry> 210 <entry spanname="hspan">This array is reserved for future 211extensions. Applications and drivers must set it to zero.</entry> 212 </row> 213 </tbody> 214 </tgroup> 215 </table> 216 217 <!-- See also vidioc-g-sliced-vbi-cap.sgml --> 218 <table frame="none" pgwide="1" id="vbi-services2"> 219 <title>Sliced VBI services</title> 220 <tgroup cols="5"> 221 <colspec colname="c1" colwidth="2*" /> 222 <colspec colname="c2" colwidth="1*" /> 223 <colspec colname="c3" colwidth="1*" /> 224 <colspec colname="c4" colwidth="2*" /> 225 <colspec colname="c5" colwidth="2*" /> 226 <spanspec namest="c3" nameend="c5" spanname="rlp" /> 227 <thead> 228 <row> 229 <entry>Symbol</entry> 230 <entry>Value</entry> 231 <entry>Reference</entry> 232 <entry>Lines, usually</entry> 233 <entry>Payload</entry> 234 </row> 235 </thead> 236 <tbody valign="top"> 237 <row> 238 <entry><constant>V4L2_SLICED_TELETEXT_B</constant> 239(Teletext System B)</entry> 240 <entry>0x0001</entry> 241 <entry><xref linkend="ets300706" />, <xref linkend="itu653" /></entry> 242 <entry>PAL/SECAM line 7-22, 320-335 (second field 7-22)</entry> 243 <entry>Last 42 of the 45 byte Teletext packet, that is 244without clock run-in and framing code, lsb first transmitted.</entry> 245 </row> 246 <row> 247 <entry><constant>V4L2_SLICED_VPS</constant></entry> 248 <entry>0x0400</entry> 249 <entry><xref linkend="ets300231" /></entry> 250 <entry>PAL line 16</entry> 251 <entry>Byte number 3 to 15 according to Figure 9 of 252ETS 300 231, lsb first transmitted.</entry> 253 </row> 254 <row> 255 <entry><constant>V4L2_SLICED_CAPTION_525</constant></entry> 256 <entry>0x1000</entry> 257 <entry><xref linkend="cea608" /></entry> 258 <entry>NTSC line 21, 284 (second field 21)</entry> 259 <entry>Two bytes in transmission order, including parity 260bit, lsb first transmitted.</entry> 261 </row> 262 <row> 263 <entry><constant>V4L2_SLICED_WSS_625</constant></entry> 264 <entry>0x4000</entry> 265 <entry><xref linkend="itu1119" />, <xref linkend="en300294" /></entry> 266 <entry>PAL/SECAM line 23</entry> 267 <entry><screen> 268Byte 0 1 269 msb lsb msb lsb 270 Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9 271</screen></entry> 272 </row> 273 <row> 274 <entry><constant>V4L2_SLICED_VBI_525</constant></entry> 275 <entry>0x1000</entry> 276 <entry spanname="rlp">Set of services applicable to 525 277line systems.</entry> 278 </row> 279 <row> 280 <entry><constant>V4L2_SLICED_VBI_625</constant></entry> 281 <entry>0x4401</entry> 282 <entry spanname="rlp">Set of services applicable to 625 283line systems.</entry> 284 </row> 285 </tbody> 286 </tgroup> 287 </table> 288 289 <para>Drivers may return an &EINVAL; when applications attempt to 290read or write data without prior format negotiation, after switching 291the video standard (which may invalidate the negotiated VBI 292parameters) and after switching the video input (which may change the 293video standard as a side effect). The &VIDIOC-S-FMT; ioctl may return 294an &EBUSY; when applications attempt to change the format while i/o is 295in progress (between a &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; call, 296and after the first &func-read; or &func-write; call).</para> 297 </section> 298 299 <section> 300 <title>Reading and writing sliced VBI data</title> 301 302 <para>A single &func-read; or &func-write; call must pass all data 303belonging to one video frame. That is an array of 304<structname>v4l2_sliced_vbi_data</structname> structures with one or 305more elements and a total size not exceeding 306<structfield>io_size</structfield> bytes. Likewise in streaming I/O 307mode one buffer of <structfield>io_size</structfield> bytes must 308contain data of one video frame. The <structfield>id</structfield> of 309unused <structname>v4l2_sliced_vbi_data</structname> elements must be 310zero.</para> 311 312 <table frame="none" pgwide="1" id="v4l2-sliced-vbi-data"> 313 <title>struct 314<structname>v4l2_sliced_vbi_data</structname></title> 315 <tgroup cols="3"> 316 &cs-def; 317 <tbody valign="top"> 318 <row> 319 <entry>__u32</entry> 320 <entry><structfield>id</structfield></entry> 321 <entry>A flag from <xref linkend="vbi-services" /> 322identifying the type of data in this packet. Only a single bit must be 323set. When the <structfield>id</structfield> of a captured packet is 324zero, the packet is empty and the contents of other fields are 325undefined. Applications shall ignore empty packets. When the 326<structfield>id</structfield> of a packet for output is zero the 327contents of the <structfield>data</structfield> field are undefined 328and the driver must no longer insert data on the requested 329<structfield>field</structfield> and 330<structfield>line</structfield>.</entry> 331 </row> 332 <row> 333 <entry>__u32</entry> 334 <entry><structfield>field</structfield></entry> 335 <entry>The video field number this data has been captured 336from, or shall be inserted at. <constant>0</constant> for the first 337field, <constant>1</constant> for the second field.</entry> 338 </row> 339 <row> 340 <entry>__u32</entry> 341 <entry><structfield>line</structfield></entry> 342 <entry>The field (as opposed to frame) line number this 343data has been captured from, or shall be inserted at. See <xref 344 linkend="vbi-525" /> and <xref linkend="vbi-625" /> for valid 345values. Sliced VBI capture devices can set the line number of all 346packets to <constant>0</constant> if the hardware cannot reliably 347identify scan lines. The field number must always be valid.</entry> 348 </row> 349 <row> 350 <entry>__u32</entry> 351 <entry><structfield>reserved</structfield></entry> 352 <entry>This field is reserved for future extensions. 353Applications and drivers must set it to zero.</entry> 354 </row> 355 <row> 356 <entry>__u8</entry> 357 <entry><structfield>data</structfield>[48]</entry> 358 <entry>The packet payload. See <xref 359 linkend="vbi-services" /> for the contents and number of 360bytes passed for each data type. The contents of padding bytes at the 361end of this array are undefined, drivers and applications shall ignore 362them.</entry> 363 </row> 364 </tbody> 365 </tgroup> 366 </table> 367 368 <para>Packets are always passed in ascending line number order, 369without duplicate line numbers. The &func-write; function and the 370&VIDIOC-QBUF; ioctl must return an &EINVAL; when applications violate 371this rule. They must also return an &EINVAL; when applications pass an 372incorrect field or line number, or a combination of 373<structfield>field</structfield>, <structfield>line</structfield> and 374<structfield>id</structfield> which has not been negotiated with the 375&VIDIOC-G-FMT; or &VIDIOC-S-FMT; ioctl. When the line numbers are 376unknown the driver must pass the packets in transmitted order. The 377driver can insert empty packets with <structfield>id</structfield> set 378to zero anywhere in the packet array.</para> 379 380 <para>To assure synchronization and to distinguish from frame 381dropping, when a captured frame does not carry any of the requested 382data services drivers must pass one or more empty packets. When an 383application fails to pass VBI data in time for output, the driver 384must output the last VPS and WSS packet again, and disable the output 385of Closed Caption and Teletext data, or output data which is ignored 386by Closed Caption and Teletext decoders.</para> 387 388 <para>A sliced VBI device may support <link 389linkend="rw">read/write</link> and/or streaming (<link 390linkend="mmap">memory mapping</link> and/or <link linkend="userp">user 391pointer</link>) I/O. The latter bears the possibility of synchronizing 392video and VBI data by using buffer timestamps.</para> 393 394 </section> 395 396 <section> 397 <title>Sliced VBI Data in MPEG Streams</title> 398 399 <para>If a device can produce an MPEG output stream, it may be 400capable of providing <link 401linkend="sliced-vbi-format-negotitation">negotiated sliced VBI 402services</link> as data embedded in the MPEG stream. Users or 403applications control this sliced VBI data insertion with the <link 404linkend="v4l2-mpeg-stream-vbi-fmt">V4L2_CID_MPEG_STREAM_VBI_FMT</link> 405control.</para> 406 407 <para>If the driver does not provide the <link 408linkend="v4l2-mpeg-stream-vbi-fmt">V4L2_CID_MPEG_STREAM_VBI_FMT</link> 409control, or only allows that control to be set to <link 410linkend="v4l2-mpeg-stream-vbi-fmt"><constant> 411V4L2_MPEG_STREAM_VBI_FMT_NONE</constant></link>, then the device 412cannot embed sliced VBI data in the MPEG stream.</para> 413 414 <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt"> 415V4L2_CID_MPEG_STREAM_VBI_FMT</link> control does not implicitly set 416the device driver to capture nor cease capturing sliced VBI data. The 417control only indicates to embed sliced VBI data in the MPEG stream, if 418an application has negotiated sliced VBI service be captured.</para> 419 420 <para>It may also be the case that a device can embed sliced VBI 421data in only certain types of MPEG streams: for example in an MPEG-2 422PS but not an MPEG-2 TS. In this situation, if sliced VBI data 423insertion is requested, the sliced VBI data will be embedded in MPEG 424stream types when supported, and silently omitted from MPEG stream 425types where sliced VBI data insertion is not supported by the device. 426</para> 427 428 <para>The following subsections specify the format of the 429embedded sliced VBI data.</para> 430 431 <section> 432 <title>MPEG Stream Embedded, Sliced VBI Data Format: NONE</title> 433 <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt"><constant> 434V4L2_MPEG_STREAM_VBI_FMT_NONE</constant></link> embedded sliced VBI 435format shall be interpreted by drivers as a control to cease 436embedding sliced VBI data in MPEG streams. Neither the device nor 437driver shall insert "empty" embedded sliced VBI data packets in the 438MPEG stream when this format is set. No MPEG stream data structures 439are specified for this format.</para> 440 </section> 441 442 <section> 443 <title>MPEG Stream Embedded, Sliced VBI Data Format: IVTV</title> 444 <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt"><constant> 445V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant></link> embedded sliced VBI 446format, when supported, indicates to the driver to embed up to 36 447lines of sliced VBI data per frame in an MPEG-2 <emphasis>Private 448Stream 1 PES</emphasis> packet encapsulated in an MPEG-2 <emphasis> 449Program Pack</emphasis> in the MPEG stream.</para> 450 451 <para><emphasis>Historical context</emphasis>: This format 452specification originates from a custom, embedded, sliced VBI data 453format used by the <filename>ivtv</filename> driver. This format 454has already been informally specified in the kernel sources in the 455file <filename>Documentation/video4linux/cx2341x/README.vbi</filename> 456. The maximum size of the payload and other aspects of this format 457are driven by the CX23415 MPEG decoder's capabilities and limitations 458with respect to extracting, decoding, and displaying sliced VBI data 459embedded within an MPEG stream.</para> 460 461 <para>This format's use is <emphasis>not</emphasis> exclusive to 462the <filename>ivtv</filename> driver <emphasis>nor</emphasis> 463exclusive to CX2341x devices, as the sliced VBI data packet insertion 464into the MPEG stream is implemented in driver software. At least the 465<filename>cx18</filename> driver provides sliced VBI data insertion 466into an MPEG-2 PS in this format as well.</para> 467 468 <para>The following definitions specify the payload of the 469MPEG-2 <emphasis>Private Stream 1 PES</emphasis> packets that contain 470sliced VBI data when <link linkend="v4l2-mpeg-stream-vbi-fmt"> 471<constant>V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant></link> is set. 472(The MPEG-2 <emphasis>Private Stream 1 PES</emphasis> packet header 473and encapsulating MPEG-2 <emphasis>Program Pack</emphasis> header are 474not detailed here. Please refer to the MPEG-2 specifications for 475details on those packet headers.)</para> 476 477 <para>The payload of the MPEG-2 <emphasis>Private Stream 1 PES 478</emphasis> packets that contain sliced VBI data is specified by 479&v4l2-mpeg-vbi-fmt-ivtv;. The payload is variable 480length, depending on the actual number of lines of sliced VBI data 481present in a video frame. The payload may be padded at the end with 482unspecified fill bytes to align the end of the payload to a 4-byte 483boundary. The payload shall never exceed 1552 bytes (2 fields with 48418 lines/field with 43 bytes of data/line and a 4 byte magic number). 485</para> 486 487 <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-fmt-ivtv"> 488 <title>struct <structname>v4l2_mpeg_vbi_fmt_ivtv</structname> 489 </title> 490 <tgroup cols="4"> 491 &cs-ustr; 492 <tbody valign="top"> 493 <row> 494 <entry>__u8</entry> 495 <entry><structfield>magic</structfield>[4]</entry> 496 <entry></entry> 497 <entry>A "magic" constant from <xref 498 linkend="v4l2-mpeg-vbi-fmt-ivtv-magic" /> that indicates 499this is a valid sliced VBI data payload and also indicates which 500member of the anonymous union, <structfield>itv0</structfield> or 501<structfield>ITV0</structfield>, to use for the payload data.</entry> 502 </row> 503 <row> 504 <entry>union</entry> 505 <entry>(anonymous)</entry> 506 </row> 507 <row> 508 <entry></entry> 509 <entry>struct <link linkend="v4l2-mpeg-vbi-itv0"> 510 <structname>v4l2_mpeg_vbi_itv0</structname></link> 511 </entry> 512 <entry><structfield>itv0</structfield></entry> 513 <entry>The primary form of the sliced VBI data payload 514that contains anywhere from 1 to 35 lines of sliced VBI data. 515Line masks are provided in this form of the payload indicating 516which VBI lines are provided.</entry> 517 </row> 518 <row> 519 <entry></entry> 520 <entry>struct <link linkend="v4l2-mpeg-vbi-itv0-1"> 521 <structname>v4l2_mpeg_vbi_ITV0</structname></link> 522 </entry> 523 <entry><structfield>ITV0</structfield></entry> 524 <entry>An alternate form of the sliced VBI data payload 525used when 36 lines of sliced VBI data are present. No line masks are 526provided in this form of the payload; all valid line mask bits are 527implcitly set.</entry> 528 </row> 529 </tbody> 530 </tgroup> 531 </table> 532 533 <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-fmt-ivtv-magic"> 534 <title>Magic Constants for &v4l2-mpeg-vbi-fmt-ivtv; 535 <structfield>magic</structfield> field</title> 536 <tgroup cols="3"> 537 &cs-def; 538 <thead> 539 <row> 540 <entry align="left">Defined Symbol</entry> 541 <entry align="left">Value</entry> 542 <entry align="left">Description</entry> 543 </row> 544 </thead> 545 <tbody valign="top"> 546 <row> 547 <entry><constant>V4L2_MPEG_VBI_IVTV_MAGIC0</constant> 548 </entry> 549 <entry>"itv0"</entry> 550 <entry>Indicates the <structfield>itv0</structfield> 551member of the union in &v4l2-mpeg-vbi-fmt-ivtv; is valid.</entry> 552 </row> 553 <row> 554 <entry><constant>V4L2_MPEG_VBI_IVTV_MAGIC1</constant> 555 </entry> 556 <entry>"ITV0"</entry> 557 <entry>Indicates the <structfield>ITV0</structfield> 558member of the union in &v4l2-mpeg-vbi-fmt-ivtv; is valid and 559that 36 lines of sliced VBI data are present.</entry> 560 </row> 561 </tbody> 562 </tgroup> 563 </table> 564 565 <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0"> 566 <title>struct <structname>v4l2_mpeg_vbi_itv0</structname> 567 </title> 568 <tgroup cols="3"> 569 &cs-str; 570 <tbody valign="top"> 571 <row> 572 <entry>__le32</entry> 573 <entry><structfield>linemask</structfield>[2]</entry> 574 <entry><para>Bitmasks indicating the VBI service lines 575present. These <structfield>linemask</structfield> values are stored 576in little endian byte order in the MPEG stream. Some reference 577<structfield>linemask</structfield> bit positions with their 578corresponding VBI line number and video field are given below. 579b<subscript>0</subscript> indicates the least significant bit of a 580<structfield>linemask</structfield> value:<screen> 581<structfield>linemask</structfield>[0] b<subscript>0</subscript>: line 6 first field 582<structfield>linemask</structfield>[0] b<subscript>17</subscript>: line 23 first field 583<structfield>linemask</structfield>[0] b<subscript>18</subscript>: line 6 second field 584<structfield>linemask</structfield>[0] b<subscript>31</subscript>: line 19 second field 585<structfield>linemask</structfield>[1] b<subscript>0</subscript>: line 20 second field 586<structfield>linemask</structfield>[1] b<subscript>3</subscript>: line 23 second field 587<structfield>linemask</structfield>[1] b<subscript>4</subscript>-b<subscript>31</subscript>: unused and set to 0</screen></para></entry> 588 </row> 589 <row> 590 <entry>struct <link linkend="v4l2-mpeg-vbi-itv0-line"> 591 <structname>v4l2_mpeg_vbi_itv0_line</structname></link> 592 </entry> 593 <entry><structfield>line</structfield>[35]</entry> 594 <entry>This is a variable length array that holds from 1 595to 35 lines of sliced VBI data. The sliced VBI data lines present 596correspond to the bits set in the <structfield>linemask</structfield> 597array, starting from b<subscript>0</subscript> of <structfield> 598linemask</structfield>[0] up through b<subscript>31</subscript> of 599<structfield>linemask</structfield>[0], and from b<subscript>0 600</subscript> of <structfield>linemask</structfield>[1] up through b 601<subscript>3</subscript> of <structfield>linemask</structfield>[1]. 602<structfield>line</structfield>[0] corresponds to the first bit 603found set in the <structfield>linemask</structfield> array, 604<structfield>line</structfield>[1] corresponds to the second bit 605found set in the <structfield>linemask</structfield> array, etc. 606If no <structfield>linemask</structfield> array bits are set, then 607<structfield>line</structfield>[0] may contain one line of 608unspecified data that should be ignored by applications.</entry> 609 </row> 610 </tbody> 611 </tgroup> 612 </table> 613 614 <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0-1"> 615 <title>struct <structname>v4l2_mpeg_vbi_ITV0</structname> 616 </title> 617 <tgroup cols="3"> 618 &cs-str; 619 <tbody valign="top"> 620 <row> 621 <entry>struct <link linkend="v4l2-mpeg-vbi-itv0-line"> 622 <structname>v4l2_mpeg_vbi_itv0_line</structname></link> 623 </entry> 624 <entry><structfield>line</structfield>[36]</entry> 625 <entry>A fixed length array of 36 lines of sliced VBI 626data. <structfield>line</structfield>[0] through <structfield>line 627</structfield>[17] correspond to lines 6 through 23 of the 628first field. <structfield>line</structfield>[18] through 629<structfield>line</structfield>[35] corresponds to lines 6 630through 23 of the second field.</entry> 631 </row> 632 </tbody> 633 </tgroup> 634 </table> 635 636 <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0-line"> 637 <title>struct <structname>v4l2_mpeg_vbi_itv0_line</structname> 638 </title> 639 <tgroup cols="3"> 640 &cs-str; 641 <tbody valign="top"> 642 <row> 643 <entry>__u8</entry> 644 <entry><structfield>id</structfield></entry> 645 <entry>A line identifier value from 646<xref linkend="ITV0-Line-Identifier-Constants" /> that indicates 647the type of sliced VBI data stored on this line.</entry> 648 </row> 649 <row> 650 <entry>__u8</entry> 651 <entry><structfield>data</structfield>[42]</entry> 652 <entry>The sliced VBI data for the line.</entry> 653 </row> 654 </tbody> 655 </tgroup> 656 </table> 657 658 <table frame="none" pgwide="1" id="ITV0-Line-Identifier-Constants"> 659 <title>Line Identifiers for struct <link 660 linkend="v4l2-mpeg-vbi-itv0-line"><structname> 661v4l2_mpeg_vbi_itv0_line</structname></link> <structfield>id 662</structfield> field</title> 663 <tgroup cols="3"> 664 &cs-def; 665 <thead> 666 <row> 667 <entry align="left">Defined Symbol</entry> 668 <entry align="left">Value</entry> 669 <entry align="left">Description</entry> 670 </row> 671 </thead> 672 <tbody valign="top"> 673 <row> 674 <entry><constant>V4L2_MPEG_VBI_IVTV_TELETEXT_B</constant> 675 </entry> 676 <entry>1</entry> 677 <entry>Refer to <link linkend="vbi-services2"> 678Sliced VBI services</link> for a description of the line payload.</entry> 679 </row> 680 <row> 681 <entry><constant>V4L2_MPEG_VBI_IVTV_CAPTION_525</constant> 682 </entry> 683 <entry>4</entry> 684 <entry>Refer to <link linkend="vbi-services2"> 685Sliced VBI services</link> for a description of the line payload.</entry> 686 </row> 687 <row> 688 <entry><constant>V4L2_MPEG_VBI_IVTV_WSS_625</constant> 689 </entry> 690 <entry>5</entry> 691 <entry>Refer to <link linkend="vbi-services2"> 692Sliced VBI services</link> for a description of the line payload.</entry> 693 </row> 694 <row> 695 <entry><constant>V4L2_MPEG_VBI_IVTV_VPS</constant> 696 </entry> 697 <entry>7</entry> 698 <entry>Refer to <link linkend="vbi-services2"> 699Sliced VBI services</link> for a description of the line payload.</entry> 700 </row> 701 </tbody> 702 </tgroup> 703 </table> 704 705 </section> 706 </section> 707