1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>Raw VBI Data Interface</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="devices.html" title="Chapter 4. Interfaces"><link rel="prev" href="effect.html" title="Effect Devices Interface"><link rel="next" href="sliced.html" title="Sliced VBI Data Interface"></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">Raw VBI Data Interface</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="effect.html">Prev</a> </td><th width="60%" align="center">Chapter 4. Interfaces</th><td width="20%" align="right"> <a accesskey="n" href="sliced.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="raw-vbi"></a>Raw VBI Data Interface</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="raw-vbi.html#idp1105460852">Querying Capabilities</a></span></dt><dt><span class="section"><a href="raw-vbi.html#idp1105463228">Supplemental Functions</a></span></dt><dt><span class="section"><a href="raw-vbi.html#idp1105465628">Raw VBI Format Negotiation</a></span></dt><dt><span class="section"><a href="raw-vbi.html#idp1105522708">Reading and writing VBI images</a></span></dt></dl></div><p>VBI is an abbreviation of Vertical Blanking Interval, a gap 2in the sequence of lines of an analog video signal. During VBI 3no picture information is transmitted, allowing some time while the 4electron beam of a cathode ray tube TV returns to the top of the 5screen. Using an oscilloscope you will find here the vertical 6synchronization pulses and short data packages ASK 7modulated<a href="#ftn.idp1105426812" class="footnote" name="idp1105426812"><sup class="footnote">[16]</sup></a> 8onto the video signal. These are transmissions of services such as 9Teletext or Closed Caption.</p><p>Subject of this interface type is raw VBI data, as sampled off 10a video signal, or to be added to a signal for output. 11The data format is similar to uncompressed video images, a number of 12lines times a number of samples per line, we call this a VBI image.</p><p>Conventionally V4L2 VBI devices are accessed through character 13device special files named <code class="filename">/dev/vbi</code> and 14<code class="filename">/dev/vbi0</code> to <code class="filename">/dev/vbi31</code> with 15major number 81 and minor numbers 224 to 255. 16<code class="filename">/dev/vbi</code> is typically a symbolic link to the 17preferred VBI device. This convention applies to both input and output 18devices.</p><p>To address the problems of finding related video and VBI 19devices VBI capturing and output is also available as device function 20under <code class="filename">/dev/video</code>. To capture or output raw VBI 21data with these devices applications must call the <a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_S_FMT</code></a> 22ioctl. Accessed as <code class="filename">/dev/vbi</code>, raw VBI capturing 23or output is the default device function.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1105460852"></a>Querying Capabilities</h3></div></div></div><p>Devices supporting the raw VBI capturing or output API set 24the <code class="constant">V4L2_CAP_VBI_CAPTURE</code> or 25<code class="constant">V4L2_CAP_VBI_OUTPUT</code> flags, respectively, in the 26<em class="structfield"><code>capabilities</code></em> field of struct <a class="link" href="vidioc-querycap.html#v4l2-capability" title="Table A.93. struct v4l2_capability">v4l2_capability</a> 27returned by the <a class="link" href="vidioc-querycap.html" title="ioctl VIDIOC_QUERYCAP"><code class="constant">VIDIOC_QUERYCAP</code></a> ioctl. At least one of the 28read/write, streaming or asynchronous I/O methods must be 29supported. VBI devices may or may not have a tuner or modulator.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1105463228"></a>Supplemental Functions</h3></div></div></div><p>VBI devices shall support <a class="link" href="video.html" title="Video Inputs and Outputs">video 30input or output</a>, <a class="link" href="tuner.html" title="Tuners and Modulators">tuner or 31modulator</a>, and <a class="link" href="control.html" title="User Controls">controls</a> ioctls 32as needed. The <a class="link" href="standard.html" title="Video Standards">video standard</a> ioctls provide 33information vital to program a VBI device, therefore must be 34supported.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1105465628"></a>Raw VBI Format Negotiation</h3></div></div></div><p>Raw VBI sampling abilities can vary, in particular the 35sampling frequency. To properly interpret the data V4L2 specifies an 36ioctl to query the sampling parameters. Moreover, to allow for some 37flexibility applications can also suggest different parameters.</p><p>As usual these parameters are <span class="emphasis"><em>not</em></span> 38reset at <a class="link" href="func-open.html" title="V4L2 open()"><code class="function">open()</code></a> time to permit Unix tool chains, programming a 39device and then reading from it as if it was a plain file. Well 40written V4L2 applications should always ensure they really get what 41they want, requesting reasonable parameters and then checking if the 42actual parameters are suitable.</p><p>To query the current raw VBI capture parameters 43applications set the <em class="structfield"><code>type</code></em> field of a 44struct <a class="link" href="vidioc-g-fmt.html#v4l2-format" title="Table A.72. struct v4l2_format">v4l2_format</a> to <code class="constant">V4L2_BUF_TYPE_VBI_CAPTURE</code> or 45<code class="constant">V4L2_BUF_TYPE_VBI_OUTPUT</code>, and call the 46<a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_G_FMT</code></a> ioctl with a pointer to this structure. Drivers fill 47the struct <a class="link" href="raw-vbi.html#v4l2-vbi-format" title="Table 4.4. struct v4l2_vbi_format">v4l2_vbi_format</a> <em class="structfield"><code>vbi</code></em> member of the 48<em class="structfield"><code>fmt</code></em> union.</p><p>To request different parameters applications set the 49<em class="structfield"><code>type</code></em> field of a struct <a class="link" href="vidioc-g-fmt.html#v4l2-format" title="Table A.72. struct v4l2_format">v4l2_format</a> as above and 50initialize all fields of the struct <a class="link" href="raw-vbi.html#v4l2-vbi-format" title="Table 4.4. struct v4l2_vbi_format">v4l2_vbi_format</a> 51<em class="structfield"><code>vbi</code></em> member of the 52<em class="structfield"><code>fmt</code></em> union, or better just modify the 53results of <code class="constant">VIDIOC_G_FMT</code>, and call the 54<a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_S_FMT</code></a> ioctl with a pointer to this structure. Drivers return 55an <span class="errorcode">EINVAL</span> error code only when the given parameters are ambiguous, otherwise 56they modify the parameters according to the hardware capabilites and 57return the actual parameters. When the driver allocates resources at 58this point, it may return an <span class="errorcode">EBUSY</span> error code to indicate the returned 59parameters are valid but the required resources are currently not 60available. That may happen for instance when the video and VBI areas 61to capture would overlap, or when the driver supports multiple opens 62and another process already requested VBI capturing or output. Anyway, 63applications must expect other resource allocation points which may 64return <span class="errorcode">EBUSY</span>, at the <a class="link" href="vidioc-streamon.html" title="ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF"><code class="constant">VIDIOC_STREAMON</code></a> ioctl 65and the first read(), write() and select() call.</p><p>VBI devices must implement both the 66<code class="constant">VIDIOC_G_FMT</code> and 67<code class="constant">VIDIOC_S_FMT</code> ioctl, even if 68<code class="constant">VIDIOC_S_FMT</code> ignores all requests and always 69returns default parameters as <code class="constant">VIDIOC_G_FMT</code> does. 70<code class="constant">VIDIOC_TRY_FMT</code> is optional.</p><div class="table"><a name="v4l2-vbi-format"></a><p class="title"><b>Table 4.4. struct <span class="structname">v4l2_vbi_format</span></b></p><div class="table-contents"><table summary="struct v4l2_vbi_format" width="100%" border="0"><colgroup><col class="c1"><col class="c2"><col class="c3"></colgroup><tbody valign="top"><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>sampling_rate</code></em></td><td valign="top">Samples per second, i. e. unit 1 Hz.</td></tr><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>offset</code></em></td><td valign="top"><p>Horizontal offset of the VBI image, 71relative to the leading edge of the line synchronization pulse and 72counted in samples: The first sample in the VBI image will be located 73<em class="structfield"><code>offset</code></em> / 74<em class="structfield"><code>sampling_rate</code></em> seconds following the leading 75edge. See also <a class="xref" href="raw-vbi.html#vbi-hsync" title="Figure 4.1. Line synchronization">Figure 4.1, “Line synchronization”</a>.</p></td></tr><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>samples_per_line</code></em></td><td valign="top"> </td></tr><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>sample_format</code></em></td><td valign="top"><p>Defines the sample format as in <a class="xref" href="pixfmt.html" title="Chapter 2. Image Formats">Chapter 2, <i>Image Formats</i></a>, a four-character-code.<a href="#ftn.idp1105484860" class="footnote" name="idp1105484860"><sup class="footnote">[a]</sup></a> Usually this is 76<code class="constant">V4L2_PIX_FMT_GREY</code>, i. e. each sample 77consists of 8 bits with lower values oriented towards the black level. 78Do not assume any other correlation of values with the signal level. 79For example, the MSB does not necessarily indicate if the signal is 80'high' or 'low' because 128 may not be the mean value of the 81signal. Drivers shall not convert the sample format by software.</p></td></tr><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>start</code></em>[2]</td><td valign="top">This is the scanning system line number 82associated with the first line of the VBI image, of the first and the 83second field respectively. See <a class="xref" href="raw-vbi.html#vbi-525" title="Figure 4.2. ITU-R 525 line numbering (M/NTSC and M/PAL)">Figure 4.2, “ITU-R 525 line numbering (M/NTSC and M/PAL)”</a> and 84<a class="xref" href="raw-vbi.html#vbi-625" title="Figure 4.3. ITU-R 625 line numbering">Figure 4.3, “ITU-R 625 line numbering”</a> for valid values. 85The <code class="constant">V4L2_VBI_ITU_525_F1_START</code>, 86<code class="constant">V4L2_VBI_ITU_525_F2_START</code>, 87<code class="constant">V4L2_VBI_ITU_625_F1_START</code> and 88<code class="constant">V4L2_VBI_ITU_625_F2_START</code> defines give the start line 89numbers for each field for each 525 or 625 line format as a convenience. 90Don't forget that ITU line numbering starts at 1, not 0. 91VBI input drivers can return start values 0 if the hardware cannot 92reliable identify scanning lines, VBI acquisition may not require this 93information.</td></tr><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>count</code></em>[2]</td><td valign="top">The number of lines in the first and second 94field image, respectively.</td></tr><tr><td colspan="3" valign="top"><p>Drivers should be as 95flexibility as possible. For example, it may be possible to extend or 96move the VBI capture window down to the picture area, implementing a 97'full field mode' to capture data service transmissions embedded in 98the picture.</p><p>An application can set the first or second 99<em class="structfield"><code>count</code></em> value to zero if no data is required 100from the respective field; <em class="structfield"><code>count</code></em>[1] if the 101scanning system is progressive, i. e. not interlaced. The 102corresponding start value shall be ignored by the application and 103driver. Anyway, drivers may not support single field capturing and 104return both count values non-zero.</p><p>Both 105<em class="structfield"><code>count</code></em> values set to zero, or line numbers 106outside the bounds depicted in <a class="xref" href="raw-vbi.html#vbi-525" title="Figure 4.2. ITU-R 525 line numbering (M/NTSC and M/PAL)">Figure 4.2, “ITU-R 525 line numbering (M/NTSC and M/PAL)”</a> and <a class="xref" href="raw-vbi.html#vbi-625" title="Figure 4.3. ITU-R 625 line numbering">Figure 4.3, “ITU-R 625 line numbering”</a>, or a field image covering 107lines of two fields, are invalid and shall not be returned by the 108driver.</p><p>To initialize the <em class="structfield"><code>start</code></em> 109and <em class="structfield"><code>count</code></em> fields, applications must first 110determine the current video standard selection. The <a class="link" href="vidioc-enumstd.html#v4l2-std-id" title="Table A.48. typedef v4l2_std_id">v4l2_std_id</a> or 111the <em class="structfield"><code>framelines</code></em> field of struct <a class="link" href="vidioc-enumstd.html#v4l2-standard" title="Table A.46. struct v4l2_standard">v4l2_standard</a> can 112be evaluated for this purpose.</p></td></tr><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>flags</code></em></td><td valign="top">See <a class="xref" href="raw-vbi.html#vbifmt-flags" title="Table 4.5. Raw VBI Format Flags">Table 4.5, “Raw VBI Format Flags”</a> below. Currently 113only drivers set flags, applications must set this field to 114zero.</td></tr><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>reserved</code></em>[2]</td><td valign="top">This array is reserved for future extensions. 115Drivers and applications must set it to zero.</td></tr></tbody><tbody class="footnotes"><tr><td colspan="3"><div id="ftn.idp1105484860" class="footnote"><p><a href="#idp1105484860" class="para"><sup class="para">[a] </sup></a>A few devices may be unable to 116sample VBI data at all but can extend the video capture window to the 117VBI region.</p></div></td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="vbifmt-flags"></a><p class="title"><b>Table 4.5. Raw VBI Format Flags</b></p><div class="table-contents"><table summary="Raw VBI Format Flags" width="100%" border="0"><colgroup><col class="c1"><col class="c2"><col class="c3"></colgroup><tbody valign="top"><tr><td valign="top"><code class="constant">V4L2_VBI_UNSYNC</code></td><td valign="top">0x0001</td><td valign="top"><p>This flag indicates hardware which does not 118properly distinguish between fields. Normally the VBI image stores the 119first field (lower scanning line numbers) first in memory. This may be 120a top or bottom field depending on the video standard. When this flag 121is set the first or second field may be stored first, however the 122fields are still in correct temporal order with the older field first 123in memory.<a href="#ftn.idp1105501324" class="footnote" name="idp1105501324"><sup class="footnote">[a]</sup></a></p></td></tr><tr><td valign="top"><code class="constant">V4L2_VBI_INTERLACED</code></td><td valign="top">0x0002</td><td valign="top">By default the two field images will be passed 124sequentially; all lines of the first field followed by all lines of 125the second field (compare <a class="xref" href="field-order.html" title="Field Order">the section called “Field Order”</a> 126<code class="constant">V4L2_FIELD_SEQ_TB</code> and 127<code class="constant">V4L2_FIELD_SEQ_BT</code>, whether the top or bottom 128field is first in memory depends on the video standard). When this 129flag is set, the two fields are interlaced (cf. 130<code class="constant">V4L2_FIELD_INTERLACED</code>). The first line of the 131first field followed by the first line of the second field, then the 132two second lines, and so on. Such a layout may be necessary when the 133hardware has been programmed to capture or output interlaced video 134images and is unable to separate the fields for VBI capturing at 135the same time. For simplicity setting this flag implies that both 136<em class="structfield"><code>count</code></em> values are equal and non-zero.</td></tr></tbody><tbody class="footnotes"><tr><td colspan="3"><div id="ftn.idp1105501324" class="footnote"><p><a href="#idp1105501324" class="para"><sup class="para">[a] </sup></a>Most VBI services transmit on both fields, but 137some have different semantics depending on the field number. These 138cannot be reliable decoded or encoded when 139<code class="constant">V4L2_VBI_UNSYNC</code> is set.</p></div></td></tr></tbody></table></div></div><br class="table-break"><div class="figure"><a name="vbi-hsync"></a><p class="title"><b>Figure 4.1. Line synchronization</b></p><div class="figure-contents"><div class="mediaobject"><img src="vbi_hsync.gif" alt="Line synchronization diagram"></div></div></div><br class="figure-break"><div class="figure"><a name="vbi-525"></a><p class="title"><b>Figure 4.2. ITU-R 525 line numbering (M/NTSC and M/PAL)</b></p><div class="figure-contents"><div class="mediaobject"><img src="vbi_525.gif" alt="NTSC field synchronization diagram"><div class="caption"><p>(1) For the purpose of this specification field 2 140starts in line 264 and not 263.5 because half line capturing is not 141supported.</p></div></div></div></div><br class="figure-break"><div class="figure"><a name="vbi-625"></a><p class="title"><b>Figure 4.3. ITU-R 625 line numbering</b></p><div class="figure-contents"><div class="mediaobject"><img src="vbi_625.gif" alt="PAL/SECAM field synchronization diagram"><div class="caption"><p>(1) For the purpose of this specification field 2 142starts in line 314 and not 313.5 because half line capturing is not 143supported.</p></div></div></div></div><br class="figure-break"><p>Remember the VBI image format depends on the selected 144video standard, therefore the application must choose a new standard or 145query the current standard first. Attempts to read or write data ahead 146of format negotiation, or after switching the video standard which may 147invalidate the negotiated VBI parameters, should be refused by the 148driver. A format change during active I/O is not permitted.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1105522708"></a>Reading and writing VBI images</h3></div></div></div><p>To assure synchronization with the field number and easier 149implementation, the smallest unit of data passed at a time is one 150frame, consisting of two fields of VBI images immediately following in 151memory.</p><p>The total size of a frame computes as follows:</p><pre class="programlisting"> 152(<em class="structfield"><code>count</code></em>[0] + <em class="structfield"><code>count</code></em>[1]) * 153<em class="structfield"><code>samples_per_line</code></em> * sample size in bytes</pre><p>The sample size is most likely always one byte, 154applications must check the <em class="structfield"><code>sample_format</code></em> 155field though, to function properly with other drivers.</p><p>A VBI device may support <a class="link" href="io.html#rw" title="Read/Write">read/write</a> and/or streaming (<a class="link" href="mmap.html" title="Streaming I/O (Memory Mapping)">memory mapping</a> or <a class="link" href="userp.html" title="Streaming I/O (User Pointers)">user pointer</a>) I/O. The latter bears the 156possibility of synchronizing video and 157VBI data by using buffer timestamps.</p><p>Remember the <a class="link" href="vidioc-streamon.html" title="ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF"><code class="constant">VIDIOC_STREAMON</code></a> ioctl and the first read(), 158write() and select() call can be resource allocation points returning 159an <span class="errorcode">EBUSY</span> error code if the required hardware resources are temporarily 160unavailable, for example the device is already in use by another 161process.</p></div><div class="footnotes"><br><hr style="width:100; text-align:left;margin-left: 0"><div id="ftn.idp1105426812" class="footnote"><p><a href="#idp1105426812" class="para"><sup class="para">[16] </sup></a>ASK: Amplitude-Shift Keying. A high signal 162level represents a '1' bit, a low level a '0' bit.</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="effect.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="devices.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sliced.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Effect Devices Interface </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Sliced VBI Data Interface</td></tr></table></div></body></html> 163
