aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook/v4l/dev-sliced-vbi.xml
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/DocBook/v4l/dev-sliced-vbi.xml')
-rw-r--r--Documentation/DocBook/v4l/dev-sliced-vbi.xml708
1 files changed, 708 insertions, 0 deletions
diff --git a/Documentation/DocBook/v4l/dev-sliced-vbi.xml b/Documentation/DocBook/v4l/dev-sliced-vbi.xml
new file mode 100644
index 000000000000..69e789fa7f7b
--- /dev/null
+++ b/Documentation/DocBook/v4l/dev-sliced-vbi.xml
@@ -0,0 +1,708 @@
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&nbsp;300&nbsp;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.</entry>
189 </row>
190 <row>
191 <entry>__u32</entry>
192 <entry><structfield>io_size</structfield></entry>
193 <entry spanname="hspan">Maximum number of bytes passed by
194one &func-read; or &func-write; call, and the buffer size in bytes for
195the &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. Drivers set this field to
196the size of &v4l2-sliced-vbi-data; times the number of non-zero
197elements in the returned <structfield>service_lines</structfield>
198array (that is the number of lines potentially carrying data).</entry>
199 </row>
200 <row>
201 <entry>__u32</entry>
202 <entry><structfield>reserved</structfield>[2]</entry>
203 <entry spanname="hspan">This array is reserved for future
204extensions. Applications and drivers must set it to zero.</entry>
205 </row>
206 </tbody>
207 </tgroup>
208 </table>
209
210 <!-- See also vidioc-g-sliced-vbi-cap.sgml -->
211 <table frame="none" pgwide="1" id="vbi-services2">
212 <title>Sliced VBI services</title>
213 <tgroup cols="5">
214 <colspec colname="c1" colwidth="2*" />
215 <colspec colname="c2" colwidth="1*" />
216 <colspec colname="c3" colwidth="1*" />
217 <colspec colname="c4" colwidth="2*" />
218 <colspec colname="c5" colwidth="2*" />
219 <spanspec namest="c3" nameend="c5" spanname="rlp" />
220 <thead>
221 <row>
222 <entry>Symbol</entry>
223 <entry>Value</entry>
224 <entry>Reference</entry>
225 <entry>Lines, usually</entry>
226 <entry>Payload</entry>
227 </row>
228 </thead>
229 <tbody valign="top">
230 <row>
231 <entry><constant>V4L2_SLICED_TELETEXT_B</constant>
232(Teletext System B)</entry>
233 <entry>0x0001</entry>
234 <entry><xref linkend="ets300706" />, <xref linkend="itu653" /></entry>
235 <entry>PAL/SECAM line 7-22, 320-335 (second field 7-22)</entry>
236 <entry>Last 42 of the 45 byte Teletext packet, that is
237without clock run-in and framing code, lsb first transmitted.</entry>
238 </row>
239 <row>
240 <entry><constant>V4L2_SLICED_VPS</constant></entry>
241 <entry>0x0400</entry>
242 <entry><xref linkend="ets300231" /></entry>
243 <entry>PAL line 16</entry>
244 <entry>Byte number 3 to 15 according to Figure 9 of
245ETS&nbsp;300&nbsp;231, lsb first transmitted.</entry>
246 </row>
247 <row>
248 <entry><constant>V4L2_SLICED_CAPTION_525</constant></entry>
249 <entry>0x1000</entry>
250 <entry><xref linkend="eia608" /></entry>
251 <entry>NTSC line 21, 284 (second field 21)</entry>
252 <entry>Two bytes in transmission order, including parity
253bit, lsb first transmitted.</entry>
254 </row>
255 <row>
256 <entry><constant>V4L2_SLICED_WSS_625</constant></entry>
257 <entry>0x4000</entry>
258 <entry><xref linkend="itu1119" />, <xref linkend="en300294" /></entry>
259 <entry>PAL/SECAM line 23</entry>
260 <entry><screen>
261Byte 0 1
262 msb lsb msb lsb
263 Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9
264</screen></entry>
265 </row>
266 <row>
267 <entry><constant>V4L2_SLICED_VBI_525</constant></entry>
268 <entry>0x1000</entry>
269 <entry spanname="rlp">Set of services applicable to 525
270line systems.</entry>
271 </row>
272 <row>
273 <entry><constant>V4L2_SLICED_VBI_625</constant></entry>
274 <entry>0x4401</entry>
275 <entry spanname="rlp">Set of services applicable to 625
276line systems.</entry>
277 </row>
278 </tbody>
279 </tgroup>
280 </table>
281
282 <para>Drivers may return an &EINVAL; when applications attempt to
283read or write data without prior format negotiation, after switching
284the video standard (which may invalidate the negotiated VBI
285parameters) and after switching the video input (which may change the
286video standard as a side effect). The &VIDIOC-S-FMT; ioctl may return
287an &EBUSY; when applications attempt to change the format while i/o is
288in progress (between a &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; call,
289and after the first &func-read; or &func-write; call).</para>
290 </section>
291
292 <section>
293 <title>Reading and writing sliced VBI data</title>
294
295 <para>A single &func-read; or &func-write; call must pass all data
296belonging to one video frame. That is an array of
297<structname>v4l2_sliced_vbi_data</structname> structures with one or
298more elements and a total size not exceeding
299<structfield>io_size</structfield> bytes. Likewise in streaming I/O
300mode one buffer of <structfield>io_size</structfield> bytes must
301contain data of one video frame. The <structfield>id</structfield> of
302unused <structname>v4l2_sliced_vbi_data</structname> elements must be
303zero.</para>
304
305 <table frame="none" pgwide="1" id="v4l2-sliced-vbi-data">
306 <title>struct
307<structname>v4l2_sliced_vbi_data</structname></title>
308 <tgroup cols="3">
309 &cs-def;
310 <tbody valign="top">
311 <row>
312 <entry>__u32</entry>
313 <entry><structfield>id</structfield></entry>
314 <entry>A flag from <xref linkend="vbi-services" />
315identifying the type of data in this packet. Only a single bit must be
316set. When the <structfield>id</structfield> of a captured packet is
317zero, the packet is empty and the contents of other fields are
318undefined. Applications shall ignore empty packets. When the
319<structfield>id</structfield> of a packet for output is zero the
320contents of the <structfield>data</structfield> field are undefined
321and the driver must no longer insert data on the requested
322<structfield>field</structfield> and
323<structfield>line</structfield>.</entry>
324 </row>
325 <row>
326 <entry>__u32</entry>
327 <entry><structfield>field</structfield></entry>
328 <entry>The video field number this data has been captured
329from, or shall be inserted at. <constant>0</constant> for the first
330field, <constant>1</constant> for the second field.</entry>
331 </row>
332 <row>
333 <entry>__u32</entry>
334 <entry><structfield>line</structfield></entry>
335 <entry>The field (as opposed to frame) line number this
336data has been captured from, or shall be inserted at. See <xref
337 linkend="vbi-525" /> and <xref linkend="vbi-625" /> for valid
338values. Sliced VBI capture devices can set the line number of all
339packets to <constant>0</constant> if the hardware cannot reliably
340identify scan lines. The field number must always be valid.</entry>
341 </row>
342 <row>
343 <entry>__u32</entry>
344 <entry><structfield>reserved</structfield></entry>
345 <entry>This field is reserved for future extensions.
346Applications and drivers must set it to zero.</entry>
347 </row>
348 <row>
349 <entry>__u8</entry>
350 <entry><structfield>data</structfield>[48]</entry>
351 <entry>The packet payload. See <xref
352 linkend="vbi-services" /> for the contents and number of
353bytes passed for each data type. The contents of padding bytes at the
354end of this array are undefined, drivers and applications shall ignore
355them.</entry>
356 </row>
357 </tbody>
358 </tgroup>
359 </table>
360
361 <para>Packets are always passed in ascending line number order,
362without duplicate line numbers. The &func-write; function and the
363&VIDIOC-QBUF; ioctl must return an &EINVAL; when applications violate
364this rule. They must also return an &EINVAL; when applications pass an
365incorrect field or line number, or a combination of
366<structfield>field</structfield>, <structfield>line</structfield> and
367<structfield>id</structfield> which has not been negotiated with the
368&VIDIOC-G-FMT; or &VIDIOC-S-FMT; ioctl. When the line numbers are
369unknown the driver must pass the packets in transmitted order. The
370driver can insert empty packets with <structfield>id</structfield> set
371to zero anywhere in the packet array.</para>
372
373 <para>To assure synchronization and to distinguish from frame
374dropping, when a captured frame does not carry any of the requested
375data services drivers must pass one or more empty packets. When an
376application fails to pass VBI data in time for output, the driver
377must output the last VPS and WSS packet again, and disable the output
378of Closed Caption and Teletext data, or output data which is ignored
379by Closed Caption and Teletext decoders.</para>
380
381 <para>A sliced VBI device may support <link
382linkend="rw">read/write</link> and/or streaming (<link
383linkend="mmap">memory mapping</link> and/or <link linkend="userp">user
384pointer</link>) I/O. The latter bears the possibility of synchronizing
385video and VBI data by using buffer timestamps.</para>
386
387 </section>
388
389 <section>
390 <title>Sliced VBI Data in MPEG Streams</title>
391
392 <para>If a device can produce an MPEG output stream, it may be
393capable of providing <link
394linkend="sliced-vbi-format-negotitation">negotiated sliced VBI
395services</link> as data embedded in the MPEG stream. Users or
396applications control this sliced VBI data insertion with the <link
397linkend="v4l2-mpeg-stream-vbi-fmt">V4L2_CID_MPEG_STREAM_VBI_FMT</link>
398control.</para>
399
400 <para>If the driver does not provide the <link
401linkend="v4l2-mpeg-stream-vbi-fmt">V4L2_CID_MPEG_STREAM_VBI_FMT</link>
402control, or only allows that control to be set to <link
403linkend="v4l2-mpeg-stream-vbi-fmt"><constant>
404V4L2_MPEG_STREAM_VBI_FMT_NONE</constant></link>, then the device
405cannot embed sliced VBI data in the MPEG stream.</para>
406
407 <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt">
408V4L2_CID_MPEG_STREAM_VBI_FMT</link> control does not implicitly set
409the device driver to capture nor cease capturing sliced VBI data. The
410control only indicates to embed sliced VBI data in the MPEG stream, if
411an application has negotiated sliced VBI service be captured.</para>
412
413 <para>It may also be the case that a device can embed sliced VBI
414data in only certain types of MPEG streams: for example in an MPEG-2
415PS but not an MPEG-2 TS. In this situation, if sliced VBI data
416insertion is requested, the sliced VBI data will be embedded in MPEG
417stream types when supported, and silently omitted from MPEG stream
418types where sliced VBI data insertion is not supported by the device.
419</para>
420
421 <para>The following subsections specify the format of the
422embedded sliced VBI data.</para>
423
424 <section>
425 <title>MPEG Stream Embedded, Sliced VBI Data Format: NONE</title>
426 <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt"><constant>
427V4L2_MPEG_STREAM_VBI_FMT_NONE</constant></link> embedded sliced VBI
428format shall be interpreted by drivers as a control to cease
429embedding sliced VBI data in MPEG streams. Neither the device nor
430driver shall insert "empty" embedded sliced VBI data packets in the
431MPEG stream when this format is set. No MPEG stream data structures
432are specified for this format.</para>
433 </section>
434
435 <section>
436 <title>MPEG Stream Embedded, Sliced VBI Data Format: IVTV</title>
437 <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt"><constant>
438V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant></link> embedded sliced VBI
439format, when supported, indicates to the driver to embed up to 36
440lines of sliced VBI data per frame in an MPEG-2 <emphasis>Private
441Stream 1 PES</emphasis> packet encapsulated in an MPEG-2 <emphasis>
442Program Pack</emphasis> in the MPEG stream.</para>
443
444 <para><emphasis>Historical context</emphasis>: This format
445specification originates from a custom, embedded, sliced VBI data
446format used by the <filename>ivtv</filename> driver. This format
447has already been informally specified in the kernel sources in the
448file <filename>Documentation/video4linux/cx2341x/README.vbi</filename>
449. The maximum size of the payload and other aspects of this format
450are driven by the CX23415 MPEG decoder's capabilities and limitations
451with respect to extracting, decoding, and displaying sliced VBI data
452embedded within an MPEG stream.</para>
453
454 <para>This format's use is <emphasis>not</emphasis> exclusive to
455the <filename>ivtv</filename> driver <emphasis>nor</emphasis>
456exclusive to CX2341x devices, as the sliced VBI data packet insertion
457into the MPEG stream is implemented in driver software. At least the
458<filename>cx18</filename> driver provides sliced VBI data insertion
459into an MPEG-2 PS in this format as well.</para>
460
461 <para>The following definitions specify the payload of the
462MPEG-2 <emphasis>Private Stream 1 PES</emphasis> packets that contain
463sliced VBI data when <link linkend="v4l2-mpeg-stream-vbi-fmt">
464<constant>V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant></link> is set.
465(The MPEG-2 <emphasis>Private Stream 1 PES</emphasis> packet header
466and encapsulating MPEG-2 <emphasis>Program Pack</emphasis> header are
467not detailed here. Please refer to the MPEG-2 specifications for
468details on those packet headers.)</para>
469
470 <para>The payload of the MPEG-2 <emphasis>Private Stream 1 PES
471</emphasis> packets that contain sliced VBI data is specified by
472&v4l2-mpeg-vbi-fmt-ivtv;. The payload is variable
473length, depending on the actual number of lines of sliced VBI data
474present in a video frame. The payload may be padded at the end with
475unspecified fill bytes to align the end of the payload to a 4-byte
476boundary. The payload shall never exceed 1552 bytes (2 fields with
47718 lines/field with 43 bytes of data/line and a 4 byte magic number).
478</para>
479
480 <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-fmt-ivtv">
481 <title>struct <structname>v4l2_mpeg_vbi_fmt_ivtv</structname>
482 </title>
483 <tgroup cols="4">
484 &cs-ustr;
485 <tbody valign="top">
486 <row>
487 <entry>__u8</entry>
488 <entry><structfield>magic</structfield>[4]</entry>
489 <entry></entry>
490 <entry>A "magic" constant from <xref
491 linkend="v4l2-mpeg-vbi-fmt-ivtv-magic" /> that indicates
492this is a valid sliced VBI data payload and also indicates which
493member of the anonymous union, <structfield>itv0</structfield> or
494<structfield>ITV0</structfield>, to use for the payload data.</entry>
495 </row>
496 <row>
497 <entry>union</entry>
498 <entry>(anonymous)</entry>
499 </row>
500 <row>
501 <entry></entry>
502 <entry>struct <link linkend="v4l2-mpeg-vbi-itv0">
503 <structname>v4l2_mpeg_vbi_itv0</structname></link>
504 </entry>
505 <entry><structfield>itv0</structfield></entry>
506 <entry>The primary form of the sliced VBI data payload
507that contains anywhere from 1 to 35 lines of sliced VBI data.
508Line masks are provided in this form of the payload indicating
509which VBI lines are provided.</entry>
510 </row>
511 <row>
512 <entry></entry>
513 <entry>struct <link linkend="v4l2-mpeg-vbi-itv0-1">
514 <structname>v4l2_mpeg_vbi_ITV0</structname></link>
515 </entry>
516 <entry><structfield>ITV0</structfield></entry>
517 <entry>An alternate form of the sliced VBI data payload
518used when 36 lines of sliced VBI data are present. No line masks are
519provided in this form of the payload; all valid line mask bits are
520implcitly set.</entry>
521 </row>
522 </tbody>
523 </tgroup>
524 </table>
525
526 <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-fmt-ivtv-magic">
527 <title>Magic Constants for &v4l2-mpeg-vbi-fmt-ivtv;
528 <structfield>magic</structfield> field</title>
529 <tgroup cols="3">
530 &cs-def;
531 <thead>
532 <row>
533 <entry align="left">Defined Symbol</entry>
534 <entry align="left">Value</entry>
535 <entry align="left">Description</entry>
536 </row>
537 </thead>
538 <tbody valign="top">
539 <row>
540 <entry><constant>V4L2_MPEG_VBI_IVTV_MAGIC0</constant>
541 </entry>
542 <entry>"itv0"</entry>
543 <entry>Indicates the <structfield>itv0</structfield>
544member of the union in &v4l2-mpeg-vbi-fmt-ivtv; is valid.</entry>
545 </row>
546 <row>
547 <entry><constant>V4L2_MPEG_VBI_IVTV_MAGIC1</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 and
552that 36 lines of sliced VBI data are present.</entry>
553 </row>
554 </tbody>
555 </tgroup>
556 </table>
557
558 <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0">
559 <title>struct <structname>v4l2_mpeg_vbi_itv0</structname>
560 </title>
561 <tgroup cols="3">
562 &cs-str;
563 <tbody valign="top">
564 <row>
565 <entry>__le32</entry>
566 <entry><structfield>linemask</structfield>[2]</entry>
567 <entry><para>Bitmasks indicating the VBI service lines
568present. These <structfield>linemask</structfield> values are stored
569in little endian byte order in the MPEG stream. Some reference
570<structfield>linemask</structfield> bit positions with their
571corresponding VBI line number and video field are given below.
572b<subscript>0</subscript> indicates the least significant bit of a
573<structfield>linemask</structfield> value:<screen>
574<structfield>linemask</structfield>[0] b<subscript>0</subscript>: line 6 first field
575<structfield>linemask</structfield>[0] b<subscript>17</subscript>: line 23 first field
576<structfield>linemask</structfield>[0] b<subscript>18</subscript>: line 6 second field
577<structfield>linemask</structfield>[0] b<subscript>31</subscript>: line 19 second field
578<structfield>linemask</structfield>[1] b<subscript>0</subscript>: line 20 second field
579<structfield>linemask</structfield>[1] b<subscript>3</subscript>: line 23 second field
580<structfield>linemask</structfield>[1] b<subscript>4</subscript>-b<subscript>31</subscript>: unused and set to 0</screen></para></entry>
581 </row>
582 <row>
583 <entry>struct <link linkend="v4l2-mpeg-vbi-itv0-line">
584 <structname>v4l2_mpeg_vbi_itv0_line</structname></link>
585 </entry>
586 <entry><structfield>line</structfield>[35]</entry>
587 <entry>This is a variable length array that holds from 1
588to 35 lines of sliced VBI data. The sliced VBI data lines present
589correspond to the bits set in the <structfield>linemask</structfield>
590array, starting from b<subscript>0</subscript> of <structfield>
591linemask</structfield>[0] up through b<subscript>31</subscript> of
592<structfield>linemask</structfield>[0], and from b<subscript>0
593</subscript> of <structfield>linemask</structfield>[1] up through b
594<subscript>3</subscript> of <structfield>linemask</structfield>[1].
595<structfield>line</structfield>[0] corresponds to the first bit
596found set in the <structfield>linemask</structfield> array,
597<structfield>line</structfield>[1] corresponds to the second bit
598found set in the <structfield>linemask</structfield> array, etc.
599If no <structfield>linemask</structfield> array bits are set, then
600<structfield>line</structfield>[0] may contain one line of
601unspecified data that should be ignored by applications.</entry>
602 </row>
603 </tbody>
604 </tgroup>
605 </table>
606
607 <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0-1">
608 <title>struct <structname>v4l2_mpeg_vbi_ITV0</structname>
609 </title>
610 <tgroup cols="3">
611 &cs-str;
612 <tbody valign="top">
613 <row>
614 <entry>struct <link linkend="v4l2-mpeg-vbi-itv0-line">
615 <structname>v4l2_mpeg_vbi_itv0_line</structname></link>
616 </entry>
617 <entry><structfield>line</structfield>[36]</entry>
618 <entry>A fixed length array of 36 lines of sliced VBI
619data. <structfield>line</structfield>[0] through <structfield>line
620</structfield>[17] correspond to lines 6 through 23 of the
621first field. <structfield>line</structfield>[18] through
622<structfield>line</structfield>[35] corresponds to lines 6
623through 23 of the second field.</entry>
624 </row>
625 </tbody>
626 </tgroup>
627 </table>
628
629 <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0-line">
630 <title>struct <structname>v4l2_mpeg_vbi_itv0_line</structname>
631 </title>
632 <tgroup cols="3">
633 &cs-str;
634 <tbody valign="top">
635 <row>
636 <entry>__u8</entry>
637 <entry><structfield>id</structfield></entry>
638 <entry>A line identifier value from
639<xref linkend="ITV0-Line-Identifier-Constants" /> that indicates
640the type of sliced VBI data stored on this line.</entry>
641 </row>
642 <row>
643 <entry>__u8</entry>
644 <entry><structfield>data</structfield>[42]</entry>
645 <entry>The sliced VBI data for the line.</entry>
646 </row>
647 </tbody>
648 </tgroup>
649 </table>
650
651 <table frame="none" pgwide="1" id="ITV0-Line-Identifier-Constants">
652 <title>Line Identifiers for struct <link
653 linkend="v4l2-mpeg-vbi-itv0-line"><structname>
654v4l2_mpeg_vbi_itv0_line</structname></link> <structfield>id
655</structfield> field</title>
656 <tgroup cols="3">
657 &cs-def;
658 <thead>
659 <row>
660 <entry align="left">Defined Symbol</entry>
661 <entry align="left">Value</entry>
662 <entry align="left">Description</entry>
663 </row>
664 </thead>
665 <tbody valign="top">
666 <row>
667 <entry><constant>V4L2_MPEG_VBI_IVTV_TELETEXT_B</constant>
668 </entry>
669 <entry>1</entry>
670 <entry>Refer to <link linkend="vbi-services2">
671Sliced VBI services</link> for a description of the line payload.</entry>
672 </row>
673 <row>
674 <entry><constant>V4L2_MPEG_VBI_IVTV_CAPTION_525</constant>
675 </entry>
676 <entry>4</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_WSS_625</constant>
682 </entry>
683 <entry>5</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_VPS</constant>
689 </entry>
690 <entry>7</entry>
691 <entry>Refer to <link linkend="vbi-services2">
692Sliced VBI services</link> for a description of the line payload.</entry>
693 </row>
694 </tbody>
695 </tgroup>
696 </table>
697
698 </section>
699 </section>
700
701
702<!--
703Local Variables:
704mode: sgml
705sgml-parent-document: "v4l2.sgml"
706indent-tabs-mode: nil
707End:
708 -->
generated by cgit v1.2.2 (git 2.25.0) at 2024-11-29 12:36:23 -0500