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>Raw VBI Data Interface</TITLE 6><META 7NAME="GENERATOR" 8CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK 9REL="HOME" 10TITLE="Video for Linux Two API Specification" 11HREF="book1.htm"><LINK 12REL="UP" 13TITLE="Interfaces" 14HREF="c6488.htm"><LINK 15REL="PREVIOUS" 16TITLE="Effect Devices Interface" 17HREF="x7002.htm"><LINK 18REL="NEXT" 19TITLE="Sliced VBI Data Interface" 20HREF="x7236.htm"></HEAD 21><BODY 22CLASS="SECTION" 23BGCOLOR="#FFFFFF" 24TEXT="#000000" 25LINK="#0000FF" 26VLINK="#840084" 27ALINK="#0000FF" 28><DIV 29CLASS="NAVHEADER" 30><TABLE 31SUMMARY="Header navigation table" 32WIDTH="100%" 33BORDER="0" 34CELLPADDING="0" 35CELLSPACING="0" 36><TR 37><TH 38COLSPAN="3" 39ALIGN="center" 40>Video for Linux Two API Specification: Revision 0.24</TH 41></TR 42><TR 43><TD 44WIDTH="10%" 45ALIGN="left" 46VALIGN="bottom" 47><A 48HREF="x7002.htm" 49ACCESSKEY="P" 50>Prev</A 51></TD 52><TD 53WIDTH="80%" 54ALIGN="center" 55VALIGN="bottom" 56>Chapter 4. Interfaces</TD 57><TD 58WIDTH="10%" 59ALIGN="right" 60VALIGN="bottom" 61><A 62HREF="x7236.htm" 63ACCESSKEY="N" 64>Next</A 65></TD 66></TR 67></TABLE 68><HR 69ALIGN="LEFT" 70WIDTH="100%"></DIV 71><DIV 72CLASS="SECTION" 73><H1 74CLASS="SECTION" 75><A 76NAME="RAW-VBI" 77>4.7. Raw VBI Data Interface</A 78></H1 79><P 80>VBI is an abbreviation of Vertical Blanking Interval, a gap 81in the sequence of lines of an analog video signal. During VBI 82no picture information is transmitted, allowing some time while the 83electron beam of a cathode ray tube TV returns to the top of the 84screen. Using an oscilloscope you will find here the vertical 85synchronization pulses and short data packages ASK 86modulated<A 87NAME="AEN7016" 88HREF="x7013.htm#FTN.AEN7016" 89><SPAN 90CLASS="footnote" 91>[1]</SPAN 92></A 93> 94onto the video signal. These are transmissions of services such as 95Teletext or Closed Caption.</P 96><P 97>Subject of this interface type is raw VBI data, as sampled off 98a video signal, or to be added to a signal for output. 99The data format is similar to uncompressed video images, a number of 100lines times a number of samples per line, we call this a VBI image.</P 101><P 102>Conventionally V4L2 VBI devices are accessed through character 103device special files named <TT 104CLASS="FILENAME" 105>/dev/vbi</TT 106> and 107<TT 108CLASS="FILENAME" 109>/dev/vbi0</TT 110> to <TT 111CLASS="FILENAME" 112>/dev/vbi31</TT 113> with 114major number 81 and minor numbers 224 to 255. 115<TT 116CLASS="FILENAME" 117>/dev/vbi</TT 118> is typically a symbolic link to the 119preferred VBI device. This convention applies to both input and output 120devices.</P 121><P 122>To address the problems of finding related video and VBI 123devices VBI capturing and output is also available as device function 124under <TT 125CLASS="FILENAME" 126>/dev/video</TT 127>. To capture or output raw VBI 128data with these devices applications must call the <A 129HREF="r10944.htm" 130><CODE 131CLASS="CONSTANT" 132>VIDIOC_S_FMT</CODE 133></A 134> 135ioctl. Accessed as <TT 136CLASS="FILENAME" 137>/dev/vbi</TT 138>, raw VBI capturing 139or output is the default device function.</P 140><DIV 141CLASS="SECTION" 142><H2 143CLASS="SECTION" 144><A 145NAME="AEN7029" 146>4.7.1. Querying Capabilities</A 147></H2 148><P 149>Devices supporting the raw VBI capturing or output API set 150the <CODE 151CLASS="CONSTANT" 152>V4L2_CAP_VBI_CAPTURE</CODE 153> or 154<CODE 155CLASS="CONSTANT" 156>V4L2_CAP_VBI_OUTPUT</CODE 157> flags, respectively, in the 158<CODE 159CLASS="STRUCTFIELD" 160>capabilities</CODE 161> field of struct <A 162HREF="r13105.htm#V4L2-CAPABILITY" 163>v4l2_capability</A 164> 165returned by the <A 166HREF="r13105.htm" 167><CODE 168CLASS="CONSTANT" 169>VIDIOC_QUERYCAP</CODE 170></A 171> ioctl. At least one of the 172read/write, streaming or asynchronous I/O methods must be 173supported. VBI devices may or may not have a tuner or modulator.</P 174></DIV 175><DIV 176CLASS="SECTION" 177><H2 178CLASS="SECTION" 179><A 180NAME="AEN7038" 181>4.7.2. Supplemental Functions</A 182></H2 183><P 184>VBI devices shall support <A 185HREF="x309.htm" 186>video 187input or output</A 188>, <A 189HREF="x394.htm" 190>tuner or 191modulator</A 192>, and <A 193HREF="x542.htm" 194>controls</A 195> ioctls 196as needed. The <A 197HREF="x448.htm" 198>video standard</A 199> ioctls provide 200information vital to program a VBI device, therefore must be 201supported.</P 202></DIV 203><DIV 204CLASS="SECTION" 205><H2 206CLASS="SECTION" 207><A 208NAME="AEN7045" 209>4.7.3. Raw VBI Format Negotiation</A 210></H2 211><P 212>Raw VBI sampling abilities can vary, in particular the 213sampling frequency. To properly interpret the data V4L2 specifies an 214ioctl to query the sampling parameters. Moreover, to allow for some 215flexibility applications can also suggest different parameters.</P 216><P 217>As usual these parameters are <SPAN 218CLASS="emphasis" 219><I 220CLASS="EMPHASIS" 221>not</I 222></SPAN 223> 224reset at <A 225HREF="r14090.htm" 226><CODE 227CLASS="FUNCTION" 228>open()</CODE 229></A 230> time to permit Unix tool chains, programming a 231device and then reading from it as if it was a plain file. Well 232written V4L2 applications should always ensure they really get what 233they want, requesting reasonable parameters and then checking if the 234actual parameters are suitable.</P 235><P 236>To query the current raw VBI capture parameters 237applications set the <CODE 238CLASS="STRUCTFIELD" 239>type</CODE 240> field of a 241struct <A 242HREF="r10944.htm#V4L2-FORMAT" 243>v4l2_format</A 244> to <CODE 245CLASS="CONSTANT" 246>V4L2_BUF_TYPE_VBI_CAPTURE</CODE 247> or 248<CODE 249CLASS="CONSTANT" 250>V4L2_BUF_TYPE_VBI_OUTPUT</CODE 251>, and call the 252<A 253HREF="r10944.htm" 254><CODE 255CLASS="CONSTANT" 256>VIDIOC_G_FMT</CODE 257></A 258> ioctl with a pointer to this structure. Drivers fill 259the struct <A 260HREF="x7013.htm#V4L2-VBI-FORMAT" 261>v4l2_vbi_format</A 262> <CODE 263CLASS="STRUCTFIELD" 264>vbi</CODE 265> member of the 266<CODE 267CLASS="STRUCTFIELD" 268>fmt</CODE 269> union.</P 270><P 271>To request different parameters applications set the 272<CODE 273CLASS="STRUCTFIELD" 274>type</CODE 275> field of a struct <A 276HREF="r10944.htm#V4L2-FORMAT" 277>v4l2_format</A 278> as above and 279initialize all fields of the struct <A 280HREF="x7013.htm#V4L2-VBI-FORMAT" 281>v4l2_vbi_format</A 282> 283<CODE 284CLASS="STRUCTFIELD" 285>vbi</CODE 286> member of the 287<CODE 288CLASS="STRUCTFIELD" 289>fmt</CODE 290> union, or better just modify the 291results of <CODE 292CLASS="CONSTANT" 293>VIDIOC_G_FMT</CODE 294>, and call the 295<A 296HREF="r10944.htm" 297><CODE 298CLASS="CONSTANT" 299>VIDIOC_S_FMT</CODE 300></A 301> ioctl with a pointer to this structure. Drivers return 302an <SPAN 303CLASS="ERRORCODE" 304>EINVAL</SPAN 305> error code only when the given parameters are ambiguous, otherwise 306they modify the parameters according to the hardware capabilites and 307return the actual parameters. When the driver allocates resources at 308this point, it may return an <SPAN 309CLASS="ERRORCODE" 310>EBUSY</SPAN 311> error code to indicate the returned 312parameters are valid but the required resources are currently not 313available. That may happen for instance when the video and VBI areas 314to capture would overlap, or when the driver supports multiple opens 315and another process already requested VBI capturing or output. Anyway, 316applications must expect other resource allocation points which may 317return <SPAN 318CLASS="ERRORCODE" 319>EBUSY</SPAN 320>, at the <A 321HREF="r13817.htm" 322><CODE 323CLASS="CONSTANT" 324>VIDIOC_STREAMON</CODE 325></A 326> ioctl 327and the first read(), write() and select() call.</P 328><P 329>VBI devices must implement both the 330<CODE 331CLASS="CONSTANT" 332>VIDIOC_G_FMT</CODE 333> and 334<CODE 335CLASS="CONSTANT" 336>VIDIOC_S_FMT</CODE 337> ioctl, even if 338<CODE 339CLASS="CONSTANT" 340>VIDIOC_S_FMT</CODE 341> ignores all requests and always 342returns default parameters as <CODE 343CLASS="CONSTANT" 344>VIDIOC_G_FMT</CODE 345> does. 346<CODE 347CLASS="CONSTANT" 348>VIDIOC_TRY_FMT</CODE 349> is optional.</P 350><DIV 351CLASS="TABLE" 352><A 353NAME="V4L2-VBI-FORMAT" 354></A 355><P 356><B 357>Table 4-4. struct <CODE 358CLASS="STRUCTNAME" 359>v4l2_vbi_format</CODE 360></B 361></P 362><TABLE 363BORDER="0" 364FRAME="void" 365WIDTH="100%" 366CLASS="CALSTABLE" 367><COL 368WIDTH="25%" 369TITLE="C1"><COL 370WIDTH="25%" 371TITLE="C2"><COL 372WIDTH="50%" 373TITLE="C3"><TBODY 374VALIGN="TOP" 375><TR 376><TD 377>__u32</TD 378><TD 379><CODE 380CLASS="STRUCTFIELD" 381>sampling_rate</CODE 382></TD 383><TD 384>Samples per second, i. e. unit 1 Hz.</TD 385></TR 386><TR 387><TD 388>__u32</TD 389><TD 390><CODE 391CLASS="STRUCTFIELD" 392>offset</CODE 393></TD 394><TD 395><P 396>Horizontal offset of the VBI image, 397relative to the leading edge of the line synchronization pulse and 398counted in samples: The first sample in the VBI image will be located 399<CODE 400CLASS="STRUCTFIELD" 401>offset</CODE 402> / 403<CODE 404CLASS="STRUCTFIELD" 405>sampling_rate</CODE 406> seconds following the leading 407edge. See also <A 408HREF="x7013.htm#VBI-HSYNC" 409>Figure 4-1</A 410>.</P 411></TD 412></TR 413><TR 414><TD 415>__u32</TD 416><TD 417><CODE 418CLASS="STRUCTFIELD" 419>samples_per_line</CODE 420></TD 421><TD 422> </TD 423></TR 424><TR 425><TD 426>__u32</TD 427><TD 428><CODE 429CLASS="STRUCTFIELD" 430>sample_format</CODE 431></TD 432><TD 433><P 434>Defines the sample format as in <A 435HREF="c2030.htm" 436>Chapter 2</A 437>, a four-character-code.<SUP 438>a</SUP 439> Usually this is 440<CODE 441CLASS="CONSTANT" 442>V4L2_PIX_FMT_GREY</CODE 443>, i. e. each sample 444consists of 8 bits with lower values oriented towards the black level. 445Do not assume any other correlation of values with the signal level. 446For example, the MSB does not necessarily indicate if the signal is 447'high' or 'low' because 128 may not be the mean value of the 448signal. Drivers shall not convert the sample format by software.</P 449></TD 450></TR 451><TR 452><TD 453>__u32</TD 454><TD 455><CODE 456CLASS="STRUCTFIELD" 457>start</CODE 458>[2]</TD 459><TD 460>This is the scanning system line number 461associated with the first line of the VBI image, of the first and the 462second field respectively. See <A 463HREF="x7013.htm#VBI-525" 464>Figure 4-2</A 465> and 466<A 467HREF="x7013.htm#VBI-625" 468>Figure 4-3</A 469> for valid values. VBI input drivers can 470return start values 0 if the hardware cannot reliable identify 471scanning lines, VBI acquisition may not require this 472information.</TD 473></TR 474><TR 475><TD 476>__u32</TD 477><TD 478><CODE 479CLASS="STRUCTFIELD" 480>count</CODE 481>[2]</TD 482><TD 483>The number of lines in the first and second 484field image, respectively.</TD 485></TR 486><TR 487><TD 488COLSPAN="3" 489><P 490>Drivers should be as 491flexibility as possible. For example, it may be possible to extend or 492move the VBI capture window down to the picture area, implementing a 493'full field mode' to capture data service transmissions embedded in 494the picture.</P 495><P 496>An application can set the first or second 497<CODE 498CLASS="STRUCTFIELD" 499>count</CODE 500> value to zero if no data is required 501from the respective field; <CODE 502CLASS="STRUCTFIELD" 503>count</CODE 504>[1] if the 505scanning system is progressive, i. e. not interlaced. The 506corresponding start value shall be ignored by the application and 507driver. Anyway, drivers may not support single field capturing and 508return both count values non-zero.</P 509><P 510>Both 511<CODE 512CLASS="STRUCTFIELD" 513>count</CODE 514> values set to zero, or line numbers 515outside the bounds depicted in <A 516HREF="x7013.htm#VBI-525" 517>Figure 4-2</A 518> and <A 519HREF="x7013.htm#VBI-625" 520>Figure 4-3</A 521>, or a field image covering 522lines of two fields, are invalid and shall not be returned by the 523driver.</P 524><P 525>To initialize the <CODE 526CLASS="STRUCTFIELD" 527>start</CODE 528> 529and <CODE 530CLASS="STRUCTFIELD" 531>count</CODE 532> fields, applications must first 533determine the current video standard selection. The <A 534HREF="r9288.htm#V4L2-STD-ID" 535>v4l2_std_id</A 536> or 537the <CODE 538CLASS="STRUCTFIELD" 539>framelines</CODE 540> field of struct <A 541HREF="r9288.htm#V4L2-STANDARD" 542>v4l2_standard</A 543> can 544be evaluated for this purpose.</P 545></TD 546></TR 547><TR 548><TD 549>__u32</TD 550><TD 551><CODE 552CLASS="STRUCTFIELD" 553>flags</CODE 554></TD 555><TD 556>See <A 557HREF="x7013.htm#VBIFMT-FLAGS" 558>Table 4-5</A 559> below. Currently 560only drivers set flags, applications must set this field to 561zero.</TD 562></TR 563><TR 564><TD 565>__u32</TD 566><TD 567><CODE 568CLASS="STRUCTFIELD" 569>reserved</CODE 570>[2]</TD 571><TD 572>This array is reserved for future extensions. 573Drivers and applications must set it to zero.</TD 574></TR 575></TBODY 576><TR 577><TD 578COLSPAN="3" 579>Notes:<BR><A 580NAME="FTN.AEN7117" 581>a. </A 582>A few devices may be unable to 583sample VBI data at all but can extend the video capture window to the 584VBI region.<BR></TD 585></TR 586></TABLE 587></DIV 588><DIV 589CLASS="TABLE" 590><A 591NAME="VBIFMT-FLAGS" 592></A 593><P 594><B 595>Table 4-5. Raw VBI Format Flags</B 596></P 597><TABLE 598BORDER="0" 599FRAME="void" 600WIDTH="100%" 601CLASS="CALSTABLE" 602><COL 603WIDTH="38%" 604TITLE="C1"><COL 605WIDTH="12%" 606TITLE="C2"><COL 607WIDTH="50%" 608TITLE="C3"><TBODY 609VALIGN="TOP" 610><TR 611><TD 612><CODE 613CLASS="CONSTANT" 614>V4L2_VBI_UNSYNC</CODE 615></TD 616><TD 617>0x0001</TD 618><TD 619><P 620>This flag indicates hardware which does not 621properly distinguish between fields. Normally the VBI image stores the 622first field (lower scanning line numbers) first in memory. This may be 623a top or bottom field depending on the video standard. When this flag 624is set the first or second field may be stored first, however the 625fields are still in correct temporal order with the older field first 626in memory.<SUP 627>a</SUP 628></P 629></TD 630></TR 631><TR 632><TD 633><CODE 634CLASS="CONSTANT" 635>V4L2_VBI_INTERLACED</CODE 636></TD 637><TD 638>0x0002</TD 639><TD 640>By default the two field images will be passed 641sequentially; all lines of the first field followed by all lines of 642the second field (compare <A 643HREF="x6386.htm" 644>Section 3.6</A 645> 646<CODE 647CLASS="CONSTANT" 648>V4L2_FIELD_SEQ_TB</CODE 649> and 650<CODE 651CLASS="CONSTANT" 652>V4L2_FIELD_SEQ_BT</CODE 653>, whether the top or bottom 654field is first in memory depends on the video standard). When this 655flag is set, the two fields are interlaced (cf. 656<CODE 657CLASS="CONSTANT" 658>V4L2_FIELD_INTERLACED</CODE 659>). The first line of the 660first field followed by the first line of the second field, then the 661two second lines, and so on. Such a layout may be necessary when the 662hardware has been programmed to capture or output interlaced video 663images and is unable to separate the fields for VBI capturing at 664the same time. For simplicity setting this flag implies that both 665<CODE 666CLASS="STRUCTFIELD" 667>count</CODE 668> values are equal and non-zero.</TD 669></TR 670></TBODY 671><TR 672><TD 673COLSPAN="3" 674>Notes:<BR><A 675NAME="FTN.AEN7173" 676>a. </A 677>Most VBI services transmit on both fields, but 678some have different semantics depending on the field number. These 679cannot be reliable decoded or encoded when 680<CODE 681CLASS="CONSTANT" 682>V4L2_VBI_UNSYNC</CODE 683> is set.<BR></TD 684></TR 685></TABLE 686></DIV 687><DIV 688CLASS="FIGURE" 689><A 690NAME="VBI-HSYNC" 691></A 692><P 693><B 694>Figure 4-1. Line synchronization</B 695></P 696><DIV 697CLASS="MEDIAOBJECT" 698><P 699><IMG 700SRC="vbi_hsync.gif"></P 701></DIV 702></DIV 703><DIV 704CLASS="FIGURE" 705><A 706NAME="VBI-525" 707></A 708><P 709><B 710>Figure 4-2. ITU-R 525 line numbering (M/NTSC and M/PAL)</B 711></P 712><DIV 713CLASS="MEDIAOBJECT" 714><P 715><IMG 716SRC="vbi_525.gif"><DIV 717CLASS="CAPTION" 718><P 719>(1) For the purpose of this specification field 2 720starts in line 264 and not 263.5 because half line capturing is not 721supported.</P 722></DIV 723></P 724></DIV 725></DIV 726><DIV 727CLASS="FIGURE" 728><A 729NAME="VBI-625" 730></A 731><P 732><B 733>Figure 4-3. ITU-R 625 line numbering</B 734></P 735><DIV 736CLASS="MEDIAOBJECT" 737><P 738><IMG 739SRC="vbi_625.gif"><DIV 740CLASS="CAPTION" 741><P 742>(1) For the purpose of this specification field 2 743starts in line 314 and not 313.5 because half line capturing is not 744supported.</P 745></DIV 746></P 747></DIV 748></DIV 749><P 750>Remember the VBI image format depends on the selected 751video standard, therefore the application must choose a new standard or 752query the current standard first. Attempts to read or write data ahead 753of format negotiation, or after switching the video standard which may 754invalidate the negotiated VBI parameters, should be refused by the 755driver. A format change during active I/O is not permitted.</P 756></DIV 757><DIV 758CLASS="SECTION" 759><H2 760CLASS="SECTION" 761><A 762NAME="AEN7218" 763>4.7.4. Reading and writing VBI images</A 764></H2 765><P 766>To assure synchronization with the field number and easier 767implementation, the smallest unit of data passed at a time is one 768frame, consisting of two fields of VBI images immediately following in 769memory.</P 770><P 771>The total size of a frame computes as follows:</P 772><PRE 773CLASS="PROGRAMLISTING" 774>(<CODE 775CLASS="STRUCTFIELD" 776>count</CODE 777>[0] + <CODE 778CLASS="STRUCTFIELD" 779>count</CODE 780>[1]) * 781<CODE 782CLASS="STRUCTFIELD" 783>samples_per_line</CODE 784> * sample size in bytes</PRE 785><P 786>The sample size is most likely always one byte, 787applications must check the <CODE 788CLASS="STRUCTFIELD" 789>sample_format</CODE 790> 791field though, to function properly with other drivers.</P 792><P 793>A VBI device may support <A 794HREF="c5742.htm#RW" 795>read/write</A 796> and/or streaming (<A 797HREF="x5791.htm" 798>memory mapping</A 799> or <A 800HREF="x5884.htm" 801>user pointer</A 802>) I/O. The latter bears the 803possibility of synchronizing video and 804VBI data by using buffer timestamps.</P 805><P 806>Remember the <A 807HREF="r13817.htm" 808><CODE 809CLASS="CONSTANT" 810>VIDIOC_STREAMON</CODE 811></A 812> ioctl and the first read(), 813write() and select() call can be resource allocation points returning 814an <SPAN 815CLASS="ERRORCODE" 816>EBUSY</SPAN 817> error code if the required hardware resources are temporarily 818unavailable, for example the device is already in use by another 819process.</P 820></DIV 821></DIV 822><H3 823CLASS="FOOTNOTES" 824>Notes</H3 825><TABLE 826BORDER="0" 827CLASS="FOOTNOTES" 828WIDTH="100%" 829><TR 830><TD 831ALIGN="LEFT" 832VALIGN="TOP" 833WIDTH="5%" 834><A 835NAME="FTN.AEN7016" 836HREF="x7013.htm#AEN7016" 837><SPAN 838CLASS="footnote" 839>[1]</SPAN 840></A 841></TD 842><TD 843ALIGN="LEFT" 844VALIGN="TOP" 845WIDTH="95%" 846><P 847>ASK: Amplitude-Shift Keying. A high signal 848level represents a '1' bit, a low level a '0' bit.</P 849></TD 850></TR 851></TABLE 852><DIV 853CLASS="NAVFOOTER" 854><HR 855ALIGN="LEFT" 856WIDTH="100%"><TABLE 857SUMMARY="Footer navigation table" 858WIDTH="100%" 859BORDER="0" 860CELLPADDING="0" 861CELLSPACING="0" 862><TR 863><TD 864WIDTH="33%" 865ALIGN="left" 866VALIGN="top" 867><A 868HREF="x7002.htm" 869ACCESSKEY="P" 870>Prev</A 871></TD 872><TD 873WIDTH="34%" 874ALIGN="center" 875VALIGN="top" 876><A 877HREF="book1.htm" 878ACCESSKEY="H" 879>Home</A 880></TD 881><TD 882WIDTH="33%" 883ALIGN="right" 884VALIGN="top" 885><A 886HREF="x7236.htm" 887ACCESSKEY="N" 888>Next</A 889></TD 890></TR 891><TR 892><TD 893WIDTH="33%" 894ALIGN="left" 895VALIGN="top" 896>Effect Devices Interface</TD 897><TD 898WIDTH="34%" 899ALIGN="center" 900VALIGN="top" 901><A 902HREF="c6488.htm" 903ACCESSKEY="U" 904>Up</A 905></TD 906><TD 907WIDTH="33%" 908ALIGN="right" 909VALIGN="top" 910>Sliced VBI Data Interface</TD 911></TR 912></TABLE 913></DIV 914></BODY 915></HTML 916> 917
