diff options
Diffstat (limited to 'v4l2-spec/dev-sliced-vbi.sgml')
| -rw-r--r-- | v4l2-spec/dev-sliced-vbi.sgml | 315 |
1 files changed, 314 insertions, 1 deletions
diff --git a/v4l2-spec/dev-sliced-vbi.sgml b/v4l2-spec/dev-sliced-vbi.sgml index 5560650a6..3c260e3e3 100644 --- a/v4l2-spec/dev-sliced-vbi.sgml +++ b/v4l2-spec/dev-sliced-vbi.sgml @@ -48,7 +48,7 @@ vital to program a sliced VBI device, therefore must be supported.</para> </section> - <section> + <section id="sliced-vbi-format-negotitation"> <title>Sliced VBI Format Negotiation</title> <para>To find out which data services are supported by the @@ -386,6 +386,319 @@ video and VBI data by using buffer timestamps.</para> </section> + <section> + <title>Sliced VBI Data in MPEG Streams</title> + + <para>If a device can produce an MPEG output stream, it may be +capable of providing <link +linkend="sliced-vbi-format-negotitation">negotiated sliced VBI +services</link> as data embedded in the MPEG stream. Users or +applications control this sliced VBI data insertion with the <link +linkend="v4l2-mpeg-stream-vbi-fmt">V4L2_CID_MPEG_STREAM_VBI_FMT</link> +control.</para> + + <para>If the driver does not provide the <link +linkend="v4l2-mpeg-stream-vbi-fmt">V4L2_CID_MPEG_STREAM_VBI_FMT</link> +control, or only allows that control to be set to <link +linkend="v4l2-mpeg-stream-vbi-fmt"><constant> +V4L2_MPEG_STREAM_VBI_FMT_NONE</constant></link>, then the device +cannot embed sliced VBI data in the MPEG stream.</para> + + <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt"> +V4L2_CID_MPEG_STREAM_VBI_FMT</link> control does not implicitly set +the device driver to capture nor cease capturing sliced VBI data. The +control only indicates to embed sliced VBI data in the MPEG stream, if +an application has negotiated sliced VBI service be captured.</para> + + <para>It may also be the case that a device can embed sliced VBI +data in only certain types of MPEG streams: for example in an MPEG-2 +PS but not an MPEG-2 TS. In this situation, if sliced VBI data +insertion is requested, the sliced VBI data will be embedded in MPEG +stream types when supported, and silently omitted from MPEG stream +types where sliced VBI data insertion is not supported by the device. +</para> + + <para>The following subsections specify the format of the +embedded sliced VBI data.</para> + + <section> + <title>MPEG Stream Embedded, Sliced VBI Data Format: NONE</title> + <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt"><constant> +V4L2_MPEG_STREAM_VBI_FMT_NONE</constant></link> embedded sliced VBI +format shall be interpreted by drivers as a control to cease +embedding sliced VBI data in MPEG streams. Neither the device nor +driver shall insert "empty" embedded sliced VBI data packets in the +MPEG stream when this format is set. No MPEG stream data structures +are specified for this format.</para> + </section> + + <section> + <title>MPEG Stream Embedded, Sliced VBI Data Format: IVTV</title> + <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt"><constant> +V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant></link> embedded sliced VBI +format, when supported, indicates to the driver to embed up to 36 +lines of sliced VBI data per frame in an MPEG-2 <emphasis>Private +Stream 1 PES</emphasis> packet encapsulated in an MPEG-2 <emphasis> +Program Pack</emphasis> in the MPEG stream.</para> + + <para><emphasis>Historical context</emphasis>: This format +specification originates from a custom, embedded, sliced VBI data +format used by the <filename>ivtv</filename> driver. This format +has already been informally specified in the kernel sources in the +file <filename>Documentation/video4linux/cx2341x/README.vbi</filename> +. The maximum size of the payload and other aspects of this format +are driven by the CX23415 MPEG decoder's capabilities and limitations +with respect to extracting, decoding, and displaying sliced VBI data +embedded within an MPEG stream.</para> + + <para>This format's use is <emphasis>not</emphasis> exclusive to +the <filename>ivtv</filename> driver <emphasis>nor</emphasis> +exclusive to CX2341x devices, as the sliced VBI data packet insertion +into the MPEG stream is implemented in driver software. At least the +<filename>cx18</filename> driver provides sliced VBI data insertion +into an MPEG-2 PS in this format as well.</para> + + <para>The following definitions specify the payload of the +MPEG-2 <emphasis>Private Stream 1 PES</emphasis> packets that contain +sliced VBI data when <link linkend="v4l2-mpeg-stream-vbi-fmt"> +<constant>V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant></link> is set. +(The MPEG-2 <emphasis>Private Stream 1 PES</emphasis> packet header +and encapsulating MPEG-2 <emphasis>Program Pack</emphasis> header are +not detailed here. Please refer to the MPEG-2 specifications for +details on those packet headers.)</para> + + <para>The payload of the MPEG-2 <emphasis>Private Stream 1 PES +</emphasis> packets that contain sliced VBI data is specified by +&v4l2-mpeg-vbi-fmt-ivtv;. The payload is variable +length, depending on the actual number of lines of sliced VBI data +present in a video frame. The payload may be padded at the end with +unspecified fill bytes to align the end of the payload to a 4-byte +boundary. The payload shall never exceed 1552 bytes (2 fields with +18 lines/field with 43 bytes of data/line and a 4 byte magic number). +</para> + + <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-fmt-ivtv"> + <title>struct <structname>v4l2_mpeg_vbi_fmt_ivtv</structname> + </title> + <tgroup cols="4"> + &cs-ustr; + <tbody valign="top"> + <row> + <entry>__u8</entry> + <entry><structfield>magic</structfield>[4]</entry> + <entry></entry> + <entry>A "magic" constant from <xref + linkend="v4l2-mpeg-vbi-fmt-ivtv-magic"> that indicates +this is a valid sliced VBI data payload and also indicates which +member of the anonymous union, <structfield>itv0</structfield> or +<structfield>ITV0</structfield>, to use for the payload data.</entry> + </row> + <row> + <entry>union</entry> + <entry>(anonymous)</entry> + </row> + <row> + <entry></entry> + <entry>struct <link linkend="v4l2-mpeg-vbi-itv0"> + <structname>v4l2_mpeg_vbi_itv0</structname></link> + </entry> + <entry><structfield>itv0</structfield></entry> + <entry>The primary form of the sliced VBI data payload +that contains anywhere from 1 to 35 lines of sliced VBI data. +Line masks are provided in this form of the payload indicating +which VBI lines are provided.</entry> + </row> + <row> + <entry></entry> + <entry>struct <link linkend="v4l2-mpeg-vbi-ITV0-1"> + <structname>v4l2_mpeg_vbi_ITV0</structname></link> + </entry> + <entry><structfield>ITV0</structfield></entry> + <entry>An alternate form of the sliced VBI data payload +used when 36 lines of sliced VBI data are present. No line masks are +provided in this form of the payload; all valid line mask bits are +implcitly set.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-fmt-ivtv-magic"> + <title>Magic Constants for &v4l2-mpeg-vbi-fmt-ivtv; + <structfield>magic</structfield> field</title> + <tgroup cols="3"> + &cs-def; + <thead> + <row> + <entry align="left">Defined Symbol</entry> + <entry align="left">Value</entry> + <entry align="left">Description</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry><constant>V4L2_MPEG_VBI_IVTV_MAGIC0</constant> + </entry> + <entry>"itv0"</entry> + <entry>Indicates the <structfield>itv0</structfield> +member of the union in &v4l2-mpeg-vbi-fmt-ivtv; is valid.</entry> + </row> + <row> + <entry><constant>V4L2_MPEG_VBI_IVTV_MAGIC1</constant> + </entry> + <entry>"ITV0"</entry> + <entry>Indicates the <structfield>ITV0</structfield> +member of the union in &v4l2-mpeg-vbi-fmt-ivtv; is valid and +that 36 lines of sliced VBI data are present.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0"> + <title>struct <structname>v4l2_mpeg_vbi_itv0</structname> + </title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__le32</entry> + <entry><structfield>linemask</structfield>[2]</entry> + <entry><para>Bitmasks indicating the VBI service lines +present. These <structfield>linemask</structfield> values are stored +in little endian byte order in the MPEG stream. Some reference +<structfield>linemask</structfield> bit positions with their +corresponding VBI line number and video field are given below. +b<subscript>0</subscript> indicates the least significant bit of a +<structfield>linemask</structfield> value:<screen> +<structfield>linemask</structfield>[0] b<subscript>0</subscript>: line 6 first field +<structfield>linemask</structfield>[0] b<subscript>17</subscript>: line 23 first field +<structfield>linemask</structfield>[0] b<subscript>18</subscript>: line 6 second field +<structfield>linemask</structfield>[0] b<subscript>31</subscript>: line 19 second field +<structfield>linemask</structfield>[1] b<subscript>0</subscript>: line 20 second field +<structfield>linemask</structfield>[1] b<subscript>3</subscript>: line 23 second field +<structfield>linemask</structfield>[1] b<subscript>4</subscript>-b<subscript>31</subscript>: unused and set to 0</screen></para></entry> + </row> + <row> + <entry>struct <link linkend="v4l2-mpeg-vbi-itv0-line"> + <structname>v4l2_mpeg_vbi_itv0_line</structname></link> + </entry> + <entry><structfield>line</structfield>[35]</entry> + <entry>This is a variable length array that holds from 1 +to 35 lines of sliced VBI data. The sliced VBI data lines present +correspond to the bits set in the <structfield>linemask</structfield> +array, starting from b<subscript>0</subscript> of <structfield> +linemask</structfield>[0] up through b<subscript>31</subscript> of +<structfield>linemask</structfield>[0], and from b<subscript>0 +</subscript> of <structfield>linemask</structfield>[1] up through b +<subscript>3</subscript> of <structfield>linemask</structfield>[1]. +<structfield>line</structfield>[0] corresponds to the first bit +found set in the <structfield>linemask</structfield> array, +<structfield>line</structfield>[1] corresponds to the second bit +found set in the <structfield>linemask</structfield> array, etc. +If no <structfield>linemask</structfield> array bits are set, then +<structfield>line</structfield>[0] may contain one line of +unspecified data that should be ignored by applications.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-ITV0-1"> + <title>struct <structname>v4l2_mpeg_vbi_ITV0</structname> + </title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>struct <link linkend="v4l2-mpeg-vbi-itv0-line"> + <structname>v4l2_mpeg_vbi_itv0_line</structname></link> + </entry> + <entry><structfield>line</structfield>[36]</entry> + <entry>A fixed length array of 36 lines of sliced VBI +data. <structfield>line</structfield>[0] through <structfield>line +</structfield>[17] correspond to lines 6 through 23 of the +first field. <structfield>line</structfield>[18] through +<structfield>line</structfield>[35] corresponds to lines 6 +through 23 of the second field.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0-line"> + <title>struct <structname>v4l2_mpeg_vbi_itv0_line</structname> + </title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u8</entry> + <entry><structfield>id</structfield></entry> + <entry>A line identifier value from +<xref linkend="ITV0-Line-Identifier-Constants"> that indicates +the type of sliced VBI data stored on this line.</entry> + </row> + <row> + <entry>__u8</entry> + <entry><structfield>data</structfield>[42]</entry> + <entry>The sliced VBI data for the line.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="none" pgwide="1" id="ITV0-Line-Identifier-Constants"> + <title>Line Identifiers for struct <link + linkend="v4l2-mpeg-vbi-itv0-line"><structname> +v4l2_mpeg_vbi_itv0_line</structname></link> <structfield>id +</structfield> field</title> + <tgroup cols="3"> + &cs-def; + <thead> + <row> + <entry align="left">Defined Symbol</entry> + <entry align="left">Value</entry> + <entry align="left">Description</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry><constant>V4L2_MPEG_VBI_IVTV_TELETEXT_B</constant> + </entry> + <entry>1</entry> + <entry>Refer to <link linkend="vbi-services2"> +Sliced VBI services</link> for a description of the line payload.</entry> + </row> + <row> + <entry><constant>V4L2_MPEG_VBI_IVTV_CAPTION_525</constant> + </entry> + <entry>4</entry> + <entry>Refer to <link linkend="vbi-services2"> +Sliced VBI services</link> for a description of the line payload.</entry> + </row> + <row> + <entry><constant>V4L2_MPEG_VBI_IVTV_WSS_625</constant> + </entry> + <entry>5</entry> + <entry>Refer to <link linkend="vbi-services2"> +Sliced VBI services</link> for a description of the line payload.</entry> + </row> + <row> + <entry><constant>V4L2_MPEG_VBI_IVTV_VPS</constant> + </entry> + <entry>7</entry> + <entry>Refer to <link linkend="vbi-services2"> +Sliced VBI services</link> for a description of the line payload.</entry> + </row> + </tbody> + </tgroup> + </table> + + </section> + </section> + + <!-- Local Variables: mode: sgml |