doc/spec/x7013.htm

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Raw VBI Data Interface</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
TITLE="Video for Linux Two API Specification"
HREF="book1.htm"><LINK
REL="UP"
TITLE="Interfaces"
HREF="c6488.htm"><LINK
REL="PREVIOUS"
TITLE="Effect Devices Interface"
HREF="x7002.htm"><LINK
REL="NEXT"
TITLE="Sliced VBI Data Interface"
HREF="x7236.htm"></HEAD
><BODY
CLASS="SECTION"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>Video for Linux Two API Specification: Revision 0.24</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="x7002.htm"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>Chapter 4. Interfaces</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="x7236.htm"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECTION"
><H1
CLASS="SECTION"
><A
NAME="RAW-VBI"
>4.7. Raw VBI Data Interface</A
></H1
><P
>VBI is an abbreviation of Vertical Blanking Interval, a gap
in the sequence of lines of an analog video signal. During VBI
no picture information is transmitted, allowing some time while the
electron beam of a cathode ray tube TV returns to the top of the
screen. Using an oscilloscope you will find here the vertical
synchronization pulses and short data packages ASK
modulated<A
NAME="AEN7016"
HREF="x7013.htm#FTN.AEN7016"
><SPAN
CLASS="footnote"
>[1]</SPAN
></A
>
onto the video signal. These are transmissions of services such as
Teletext or Closed Caption.</P
><P
>Subject of this interface type is raw VBI data, as sampled off
a video signal, or to be added to a signal for output.
The data format is similar to uncompressed video images, a number of
lines times a number of samples per line, we call this a VBI image.</P
><P
>Conventionally V4L2 VBI devices are accessed through character
device special files named <TT
CLASS="FILENAME"
>/dev/vbi</TT
> and
<TT
CLASS="FILENAME"
>/dev/vbi0</TT
> to <TT
CLASS="FILENAME"
>/dev/vbi31</TT
> with
major number 81 and minor numbers 224 to 255.
<TT
CLASS="FILENAME"
>/dev/vbi</TT
> is typically a symbolic link to the
preferred VBI device. This convention applies to both input and output
devices.</P
><P
>To address the problems of finding related video and VBI
devices VBI capturing and output is also available as device function
under <TT
CLASS="FILENAME"
>/dev/video</TT
>. To capture or output raw VBI
data with these devices applications must call the <A
HREF="r10944.htm"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
></A
>
ioctl. Accessed as <TT
CLASS="FILENAME"
>/dev/vbi</TT
>, raw VBI capturing
or output is the default device function.</P
><DIV
CLASS="SECTION"
><H2
CLASS="SECTION"
><A
NAME="AEN7029"
>4.7.1. Querying Capabilities</A
></H2
><P
>Devices supporting the raw VBI capturing or output API set
the <CODE
CLASS="CONSTANT"
>V4L2_CAP_VBI_CAPTURE</CODE
> or
<CODE
CLASS="CONSTANT"
>V4L2_CAP_VBI_OUTPUT</CODE
> flags, respectively, in the
<CODE
CLASS="STRUCTFIELD"
>capabilities</CODE
> field of struct&nbsp;<A
HREF="r13105.htm#V4L2-CAPABILITY"
>v4l2_capability</A
>
returned by the <A
HREF="r13105.htm"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYCAP</CODE
></A
> ioctl. At least one of the
read/write, streaming or asynchronous I/O methods must be
supported. VBI devices may or may not have a tuner or modulator.</P
></DIV
><DIV
CLASS="SECTION"
><H2
CLASS="SECTION"
><A
NAME="AEN7038"
>4.7.2. Supplemental Functions</A
></H2
><P
>VBI devices shall support <A
HREF="x309.htm"
>video
input or output</A
>, <A
HREF="x394.htm"
>tuner or
modulator</A
>, and <A
HREF="x542.htm"
>controls</A
> ioctls
as needed. The <A
HREF="x448.htm"
>video standard</A
> ioctls provide
information vital to program a VBI device, therefore must be
supported.</P
></DIV
><DIV
CLASS="SECTION"
><H2
CLASS="SECTION"
><A
NAME="AEN7045"
>4.7.3. Raw VBI Format Negotiation</A
></H2
><P
>Raw VBI sampling abilities can vary, in particular the
sampling frequency. To properly interpret the data V4L2 specifies an
ioctl to query the sampling parameters. Moreover, to allow for some
flexibility applications can also suggest different parameters.</P
><P
>As usual these parameters are <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>not</I
></SPAN
>
reset at <A
HREF="r14090.htm"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
> time to permit Unix tool chains, programming a
device and then reading from it as if it was a plain file. Well
written V4L2 applications should always ensure they really get what
they want, requesting reasonable parameters and then checking if the
actual parameters are suitable.</P
><P
>To query the current raw VBI capture parameters
applications set the <CODE
CLASS="STRUCTFIELD"
>type</CODE
> field of a
struct&nbsp;<A
HREF="r10944.htm#V4L2-FORMAT"
>v4l2_format</A
> to <CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VBI_CAPTURE</CODE
> or
<CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VBI_OUTPUT</CODE
>, and call the
<A
HREF="r10944.htm"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_FMT</CODE
></A
> ioctl with a pointer to this structure. Drivers fill
the struct&nbsp;<A
HREF="x7013.htm#V4L2-VBI-FORMAT"
>v4l2_vbi_format</A
> <CODE
CLASS="STRUCTFIELD"
>vbi</CODE
> member of the
<CODE
CLASS="STRUCTFIELD"
>fmt</CODE
> union.</P
><P
>To request different parameters applications set the
<CODE
CLASS="STRUCTFIELD"
>type</CODE
> field of a struct&nbsp;<A
HREF="r10944.htm#V4L2-FORMAT"
>v4l2_format</A
> as above and
initialize all fields of the struct&nbsp;<A
HREF="x7013.htm#V4L2-VBI-FORMAT"
>v4l2_vbi_format</A
>
<CODE
CLASS="STRUCTFIELD"
>vbi</CODE
> member of the
<CODE
CLASS="STRUCTFIELD"
>fmt</CODE
> union, or better just modify the
results of <CODE
CLASS="CONSTANT"
>VIDIOC_G_FMT</CODE
>, and call the
<A
HREF="r10944.htm"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
></A
> ioctl with a pointer to this structure. Drivers return
an <SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code only when the given parameters are ambiguous, otherwise
they modify the parameters according to the hardware capabilites and
return the actual parameters. When the driver allocates resources at
this point, it may return an <SPAN
CLASS="ERRORCODE"
>EBUSY</SPAN
> error code to indicate the returned
parameters are valid but the required resources are currently not
available. That may happen for instance when the video and VBI areas
to capture would overlap, or when the driver supports multiple opens
and another process already requested VBI capturing or output. Anyway,
applications must expect other resource allocation points which may
return <SPAN
CLASS="ERRORCODE"
>EBUSY</SPAN
>, at the <A
HREF="r13817.htm"
><CODE
CLASS="CONSTANT"
>VIDIOC_STREAMON</CODE
></A
> ioctl
and the first read(), write() and select() call.</P
><P
>VBI devices must implement both the
<CODE
CLASS="CONSTANT"
>VIDIOC_G_FMT</CODE
> and
<CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
> ioctl, even if
<CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
> ignores all requests and always
returns default parameters as <CODE
CLASS="CONSTANT"
>VIDIOC_G_FMT</CODE
> does.
<CODE
CLASS="CONSTANT"
>VIDIOC_TRY_FMT</CODE
> is optional.</P
><DIV
CLASS="TABLE"
><A
NAME="V4L2-VBI-FORMAT"
></A
><P
><B
>Table 4-4. struct <CODE
CLASS="STRUCTNAME"
>v4l2_vbi_format</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
VALIGN="TOP"
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>sampling_rate</CODE
></TD
><TD
>Samples per second, i.&nbsp;e. unit 1 Hz.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>offset</CODE
></TD
><TD
><P
>Horizontal offset of the VBI image,
relative to the leading edge of the line synchronization pulse and
counted in samples: The first sample in the VBI image will be located
<CODE
CLASS="STRUCTFIELD"
>offset</CODE
> /
<CODE
CLASS="STRUCTFIELD"
>sampling_rate</CODE
> seconds following the leading
edge. See also <A
HREF="x7013.htm#VBI-HSYNC"
>Figure 4-1</A
>.</P
></TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>samples_per_line</CODE
></TD
><TD
>&nbsp;</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>sample_format</CODE
></TD
><TD
><P
>Defines the sample format as in <A
HREF="c2030.htm"
>Chapter 2</A
>, a four-character-code.<SUP
>a</SUP
> Usually this is
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_GREY</CODE
>, i.&nbsp;e. each sample
consists of 8 bits with lower values oriented towards the black level.
Do not assume any other correlation of values with the signal level.
For example, the MSB does not necessarily indicate if the signal is
'high' or 'low' because 128 may not be the mean value of the
signal. Drivers shall not convert the sample format by software.</P
></TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>start</CODE
>[2]</TD
><TD
>This is the scanning system line number
associated with the first line of the VBI image, of the first and the
second field respectively. See <A
HREF="x7013.htm#VBI-525"
>Figure 4-2</A
> and
<A
HREF="x7013.htm#VBI-625"
>Figure 4-3</A
> for valid values. VBI input drivers can
return start values 0 if the hardware cannot reliable identify
scanning lines, VBI acquisition may not require this
information.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>count</CODE
>[2]</TD
><TD
>The number of lines in the first and second
field image, respectively.</TD
></TR
><TR
><TD
COLSPAN="3"
><P
>Drivers should be as
flexibility as possible. For example, it may be possible to extend or
move the VBI capture window down to the picture area, implementing a
'full field mode' to capture data service transmissions embedded in
the picture.</P
><P
>An application can set the first or second
<CODE
CLASS="STRUCTFIELD"
>count</CODE
> value to zero if no data is required
from the respective field; <CODE
CLASS="STRUCTFIELD"
>count</CODE
>[1] if the
scanning system is progressive, i.&nbsp;e. not interlaced. The
corresponding start value shall be ignored by the application and
driver. Anyway, drivers may not support single field capturing and
return both count values non-zero.</P
><P
>Both
<CODE
CLASS="STRUCTFIELD"
>count</CODE
> values set to zero, or line numbers
outside the bounds depicted in <A
HREF="x7013.htm#VBI-525"
>Figure 4-2</A
> and <A
HREF="x7013.htm#VBI-625"
>Figure 4-3</A
>, or a field image covering
lines of two fields, are invalid and shall not be returned by the
driver.</P
><P
>To initialize the <CODE
CLASS="STRUCTFIELD"
>start</CODE
>
and <CODE
CLASS="STRUCTFIELD"
>count</CODE
> fields, applications must first
determine the current video standard selection. The <A
HREF="r9288.htm#V4L2-STD-ID"
>v4l2_std_id</A
> or
the <CODE
CLASS="STRUCTFIELD"
>framelines</CODE
> field of struct&nbsp;<A
HREF="r9288.htm#V4L2-STANDARD"
>v4l2_standard</A
> can
be evaluated for this purpose.</P
></TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>flags</CODE
></TD
><TD
>See <A
HREF="x7013.htm#VBIFMT-FLAGS"
>Table 4-5</A
> below. Currently
only drivers set flags, applications must set this field to
zero.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>reserved</CODE
>[2]</TD
><TD
>This array is reserved for future extensions.
Drivers and applications must set it to zero.</TD
></TR
></TBODY
><TR
><TD
COLSPAN="3"
>Notes:<BR><A
NAME="FTN.AEN7117"
>a. </A
>A few devices may be unable to
sample VBI data at all but can extend the video capture window to the
VBI region.<BR></TD
></TR
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="VBIFMT-FLAGS"
></A
><P
><B
>Table 4-5. Raw VBI Format Flags</B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="38%"
TITLE="C1"><COL
WIDTH="12%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
VALIGN="TOP"
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_VBI_UNSYNC</CODE
></TD
><TD
>0x0001</TD
><TD
><P
>This flag indicates hardware which does not
properly distinguish between fields. Normally the VBI image stores the
first field (lower scanning line numbers) first in memory. This may be
a top or bottom field depending on the video standard. When this flag
is set the first or second field may be stored first, however the
fields are still in correct temporal order with the older field first
in memory.<SUP
>a</SUP
></P
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_VBI_INTERLACED</CODE
></TD
><TD
>0x0002</TD
><TD
>By default the two field images will be passed
sequentially; all lines of the first field followed by all lines of
the second field (compare <A
HREF="x6386.htm"
>Section 3.6</A
>
<CODE
CLASS="CONSTANT"
>V4L2_FIELD_SEQ_TB</CODE
> and
<CODE
CLASS="CONSTANT"
>V4L2_FIELD_SEQ_BT</CODE
>, whether the top or bottom
field is first in memory depends on the video standard). When this
flag is set, the two fields are interlaced (cf.
<CODE
CLASS="CONSTANT"
>V4L2_FIELD_INTERLACED</CODE
>). The first line of the
first field followed by the first line of the second field, then the
two second lines, and so on. Such a layout may be necessary when the
hardware has been programmed to capture or output interlaced video
images and is unable to separate the fields for VBI capturing at
the same time. For simplicity setting this flag implies that both
<CODE
CLASS="STRUCTFIELD"
>count</CODE
> values are equal and non-zero.</TD
></TR
></TBODY
><TR
><TD
COLSPAN="3"
>Notes:<BR><A
NAME="FTN.AEN7173"
>a. </A
>Most VBI services transmit on both fields, but
some have different semantics depending on the field number. These
cannot be reliable decoded or encoded when
<CODE
CLASS="CONSTANT"
>V4L2_VBI_UNSYNC</CODE
> is set.<BR></TD
></TR
></TABLE
></DIV
><DIV
CLASS="FIGURE"
><A
NAME="VBI-HSYNC"
></A
><P
><B
>Figure 4-1. Line synchronization</B
></P
><DIV
CLASS="MEDIAOBJECT"
><P
><IMG
SRC="vbi_hsync.gif"></P
></DIV
></DIV
><DIV
CLASS="FIGURE"
><A
NAME="VBI-525"
></A
><P
><B
>Figure 4-2. ITU-R 525 line numbering (M/NTSC and M/PAL)</B
></P
><DIV
CLASS="MEDIAOBJECT"
><P
><IMG
SRC="vbi_525.gif"><DIV
CLASS="CAPTION"
><P
>(1) For the purpose of this specification field 2
starts in line 264 and not 263.5 because half line capturing is not
supported.</P
></DIV
></P
></DIV
></DIV
><DIV
CLASS="FIGURE"
><A
NAME="VBI-625"
></A
><P
><B
>Figure 4-3. ITU-R 625 line numbering</B
></P
><DIV
CLASS="MEDIAOBJECT"
><P
><IMG
SRC="vbi_625.gif"><DIV
CLASS="CAPTION"
><P
>(1) For the purpose of this specification field 2
starts in line 314 and not 313.5 because half line capturing is not
supported.</P
></DIV
></P
></DIV
></DIV
><P
>Remember the VBI image format depends on the selected
video standard, therefore the application must choose a new standard or
query the current standard first. Attempts to read or write data ahead
of format negotiation, or after switching the video standard which may
invalidate the negotiated VBI parameters, should be refused by the
driver. A format change during active I/O is not permitted.</P
></DIV
><DIV
CLASS="SECTION"
><H2
CLASS="SECTION"
><A
NAME="AEN7218"
>4.7.4. Reading and writing VBI images</A
></H2
><P
>To assure synchronization with the field number and easier
implementation, the smallest unit of data passed at a time is one
frame, consisting of two fields of VBI images immediately following in
memory.</P
><P
>The total size of a frame computes as follows:</P
><PRE
CLASS="PROGRAMLISTING"
>(<CODE
CLASS="STRUCTFIELD"
>count</CODE
>[0] + <CODE
CLASS="STRUCTFIELD"
>count</CODE
>[1]) *
<CODE
CLASS="STRUCTFIELD"
>samples_per_line</CODE
> * sample size in bytes</PRE
><P
>The sample size is most likely always one byte,
applications must check the <CODE
CLASS="STRUCTFIELD"
>sample_format</CODE
>
field though, to function properly with other drivers.</P
><P
>A VBI device may support <A
HREF="c5742.htm#RW"
>read/write</A
> and/or streaming (<A
HREF="x5791.htm"
>memory mapping</A
> or <A
HREF="x5884.htm"
>user pointer</A
>) I/O. The latter bears the
possibility of synchronizing video and
VBI data by using buffer timestamps.</P
><P
>Remember the <A
HREF="r13817.htm"
><CODE
CLASS="CONSTANT"
>VIDIOC_STREAMON</CODE
></A
> ioctl and the first read(),
write() and select() call can be resource allocation points returning
an <SPAN
CLASS="ERRORCODE"
>EBUSY</SPAN
> error code if the required hardware resources are temporarily
unavailable, for example the device is already in use by another
process.</P
></DIV
></DIV
><H3
CLASS="FOOTNOTES"
>Notes</H3
><TABLE
BORDER="0"
CLASS="FOOTNOTES"
WIDTH="100%"
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN7016"
HREF="x7013.htm#AEN7016"
><SPAN
CLASS="footnote"
>[1]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>ASK: Amplitude-Shift Keying. A high signal
level represents a '1' bit, a low level a '0' bit.</P
></TD
></TR
></TABLE
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="x7002.htm"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="book1.htm"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="x7236.htm"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Effect Devices Interface</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="c6488.htm"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Sliced VBI Data Interface</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>