media/v4l/dev-raw-vbi.rst

1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
4 .. _raw-vbi:
7 Raw VBI Data Interface
11 sequence of lines of an analog video signal. During VBI no picture
15 short data packages ASK modulated [#f1]_ onto the video signal. These are
18 Subject of this interface type is raw VBI data, as sampled off a video
19 signal, or to be added to a signal for output. The data format is
20 similar to uncompressed video images, a number of lines times a number
31 ``/dev/video``. To capture or output raw VBI data with these devices
59 frequency. To properly interpret the data V4L2 specifies an ioctl to
106 .. flat-table:: struct v4l2_vbi_format
107     :header-rows:  0
108     :stub-columns: 0
111     * - __u32
112       - ``sampling_rate``
113       - Samples per second, i. e. unit 1 Hz.
114     * - __u32
115       - ``offset``
116       - Horizontal offset of the VBI image, relative to the leading edge
120 	:ref:`vbi-hsync`.
121     * - __u32
122       - ``samples_per_line``
123       -
124     * - __u32
125       - ``sample_format``
126       - Defines the sample format as in :ref:`pixfmt`, a
127 	four-character-code. [#f2]_ Usually this is ``V4L2_PIX_FMT_GREY``,
134     * - __u32
135       - ``start``\ [#f2]_
136       - This is the scanning system line number associated with the first
138 	respectively. See :ref:`vbi-525` and :ref:`vbi-625` for valid
145 	identify scanning lines, VBI acquisition may not require this
147     * - __u32
148       - ``count``\ [#f2]_
149       - The number of lines in the first and second field image,
151     * - :cspan:`2`
155 	picture area, implementing a 'full field mode' to capture data
159 	if no data is required from the respective field; ``count``\ [1]
163 	return both count values non-zero.
166 	bounds depicted\ [#f4]_, or a field image covering lines of two
171 	:ref:`v4l2_std_id <v4l2-std-id>` or the ``framelines`` field
174     * - __u32
175       - ``flags``
176       - See :ref:`vbifmt-flags` below. Currently only drivers set flags,
178     * - __u32
179       - ``reserved``\ [#f2]_
180       - This array is reserved for future extensions. Drivers and
185 .. _vbifmt-flags:
187 .. flat-table:: Raw VBI Format Flags
188     :header-rows:  0
189     :stub-columns: 0
192     * - ``V4L2_VBI_UNSYNC``
193       - 0x0001
194       - This flag indicates hardware which does not properly distinguish
201     * - ``V4L2_VBI_INTERLACED``
202       - 0x0002
203       - By default the two field images will be passed sequentially; all
204 	lines of the first field followed by all lines of the second field
205 	(compare :ref:`field-order` ``V4L2_FIELD_SEQ_TB`` and
210 	second field, then the two second lines, and so on. Such a layout
215 	non-zero.
218 .. _vbi-hsync:
220 .. kernel-figure:: vbi_hsync.svg
226 .. _vbi-525:
228 .. kernel-figure:: vbi_525.svg
232     **Figure 4.2. ITU-R 525 line numbering (M/NTSC and M/PAL)**
234 .. _vbi-625:
236 .. kernel-figure:: vbi_625.svg
240     **Figure 4.3. ITU-R 625 line numbering**
244 current standard first. Attempts to read or write data ahead of format
253 implementation, the smallest unit of data passed at a time is one frame,
258 .. code-block:: c
268 The latter bears the possibility of synchronizing video and VBI data by
279    ASK: Amplitude-Shift Keying. A high signal level represents a '1'
283    A few devices may be unable to sample VBI data at all but can extend
292    The valid values ar shown at :ref:`vbi-525` and :ref:`vbi-625`.