Sliced VBI Format Negotiation

Sliced VBI Format Negotiation To find out which data services are supported by the @@ -386,6 +386,319 @@ video and VBI data by using buffer timestamps.

+ Sliced VBI Data in MPEG Streams + + If a device can produce an MPEG output stream, it may be +capable of providing negotiated sliced VBI +services as data embedded in the MPEG stream. Users or +applications control this sliced VBI data insertion with the V4L2_CID_MPEG_STREAM_VBI_FMT +control. + + If the driver does not provide the V4L2_CID_MPEG_STREAM_VBI_FMT +control, or only allows that control to be set to +V4L2_MPEG_STREAM_VBI_FMT_NONE, then the device +cannot embed sliced VBI data in the MPEG stream. + + The +V4L2_CID_MPEG_STREAM_VBI_FMT 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. + + 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. + + + The following subsections specify the format of the +embedded sliced VBI data. + +

+ MPEG Stream Embedded, Sliced VBI Data Format: NONE + The +V4L2_MPEG_STREAM_VBI_FMT_NONE 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. +

+ +

+ MPEG Stream Embedded, Sliced VBI Data Format: IVTV + The +V4L2_MPEG_STREAM_VBI_FMT_IVTV 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 Private +Stream 1 PES packet encapsulated in an MPEG-2 +Program Pack in the MPEG stream. + + Historical context: This format +specification originates from a custom, embedded, sliced VBI data +format used by the ivtv driver. This format +has already been informally specified in the kernel sources in the +file Documentation/video4linux/cx2341x/README.vbi +. 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. + + This format's use is not exclusive to +the ivtv driver nor +exclusive to CX2341x devices, as the sliced VBI data packet insertion +into the MPEG stream is implemented in driver software. At least the +cx18 driver provides sliced VBI data insertion +into an MPEG-2 PS in this format as well. + + The following definitions specify the payload of the +MPEG-2 Private Stream 1 PES packets that contain +sliced VBI data when +V4L2_MPEG_STREAM_VBI_FMT_IVTV is set. +(The MPEG-2 Private Stream 1 PES packet header +and encapsulating MPEG-2 Program Pack header are +not detailed here. Please refer to the MPEG-2 specifications for +details on those packet headers.) + + The payload of the MPEG-2 Private Stream 1 PES + 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). + + + + struct <structname>v4l2_mpeg_vbi_fmt_ivtv</structname> + + + &cs-ustr; + + + __u8 + magic[4] + + A "magic" constant from that indicates +this is a valid sliced VBI data payload and also indicates which +member of the anonymous union, itv0 or +ITV0, to use for the payload data. + + + union + (anonymous) + + + + struct + v4l2_mpeg_vbi_itv0 + + itv0 + 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. + + + + struct + v4l2_mpeg_vbi_ITV0 + + ITV0 + 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. + + + +

+ + + Magic Constants for &v4l2-mpeg-vbi-fmt-ivtv; + <structfield>magic</structfield> field + + &cs-def; + + + Defined Symbol + Value + Description + + + + + V4L2_MPEG_VBI_IVTV_MAGIC0 + + "itv0" + Indicates the itv0 +member of the union in &v4l2-mpeg-vbi-fmt-ivtv; is valid. + + + V4L2_MPEG_VBI_IVTV_MAGIC1 + + "ITV0" + Indicates the ITV0 +member of the union in &v4l2-mpeg-vbi-fmt-ivtv; is valid and +that 36 lines of sliced VBI data are present. + + + +

+ + + struct <structname>v4l2_mpeg_vbi_itv0</structname> + + + &cs-str; + + + __le32 + linemask[2] + Bitmasks indicating the VBI service lines +present. These linemask values are stored +in little endian byte order in the MPEG stream. Some reference +linemask bit positions with their +corresponding VBI line number and video field are given below. +b0 indicates the least significant bit of a +linemask value: +linemask[0] b0: line 6 first field +linemask[0] b17: line 23 first field +linemask[0] b18: line 6 second field +linemask[0] b31: line 19 second field +linemask[1] b0: line 20 second field +linemask[1] b3: line 23 second field +linemask[1] b4-b31: unused and set to 0 + + + struct + v4l2_mpeg_vbi_itv0_line + + line[35] + 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 linemask +array, starting from b0 of +linemask[0] up through b31 of +linemask[0], and from b0 + of linemask[1] up through b +3 of linemask[1]. +line[0] corresponds to the first bit +found set in the linemask array, +line[1] corresponds to the second bit +found set in the linemask array, etc. +If no linemask array bits are set, then +line[0] may contain one line of +unspecified data that should be ignored by applications. + + + +

+ + + struct <structname>v4l2_mpeg_vbi_ITV0</structname> + + + &cs-str; + + + struct + v4l2_mpeg_vbi_itv0_line + + line[36] + A fixed length array of 36 lines of sliced VBI +data. line[0] through line +[17] correspond to lines 6 through 23 of the +first field. line[18] through +line[35] corresponds to lines 6 +through 23 of the second field. + + + +

+ + + struct <structname>v4l2_mpeg_vbi_itv0_line</structname> + + + &cs-str; + + + __u8 + id + A line identifier value from + that indicates +the type of sliced VBI data stored on this line. + + + __u8 + data[42] + The sliced VBI data for the line. + + + +

+ + + Line Identifiers for struct <link + linkend="v4l2-mpeg-vbi-itv0-line"><structname> +v4l2_mpeg_vbi_itv0_line</structname></link> <structfield>id +</structfield> field + + &cs-def; + + + Defined Symbol + Value + Description + + + + + V4L2_MPEG_VBI_IVTV_TELETEXT_B + + 1 + Refer to +Sliced VBI services for a description of the line payload. + + + V4L2_MPEG_VBI_IVTV_CAPTION_525 + + 4 + Refer to +Sliced VBI services for a description of the line payload. + + + V4L2_MPEG_VBI_IVTV_WSS_625 + + 5 + Refer to +Sliced VBI services for a description of the line payload. + + + V4L2_MPEG_VBI_IVTV_VPS + + 7 + Refer to +Sliced VBI services for a description of the line payload. + + + +

+ +