0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _sliced:
0005
0006 *************************
0007 Sliced VBI Data Interface
0008 *************************
0009
0010 VBI stands for Vertical Blanking Interval, a gap in the sequence of
0011 lines of an analog video signal. During VBI no picture information is
0012 transmitted, allowing some time while the electron beam of a cathode ray
0013 tube TV returns to the top of the screen.
0014
0015 Sliced VBI devices use hardware to demodulate data transmitted in the
0016 VBI. V4L2 drivers shall *not* do this by software, see also the
0017 :ref:`raw VBI interface <raw-vbi>`. The data is passed as short
0018 packets of fixed size, covering one scan line each. The number of
0019 packets per video frame is variable.
0020
0021 Sliced VBI capture and output devices are accessed through the same
0022 character special files as raw VBI devices. When a driver supports both
0023 interfaces, the default function of a ``/dev/vbi`` device is *raw* VBI
0024 capturing or output, and the sliced VBI function is only available after
0025 calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl as defined
0026 below. Likewise a ``/dev/video`` device may support the sliced VBI API,
0027 however the default function here is video capturing or output.
0028 Different file descriptors must be used to pass raw and sliced VBI data
0029 simultaneously, if this is supported by the driver.
0030
0031 Querying Capabilities
0032 =====================
0033
0034 Devices supporting the sliced VBI capturing or output API set the
0035 ``V4L2_CAP_SLICED_VBI_CAPTURE`` or ``V4L2_CAP_SLICED_VBI_OUTPUT`` flag
0036 respectively, in the ``capabilities`` field of struct
0037 :c:type:`v4l2_capability` returned by the
0038 :ref:`VIDIOC_QUERYCAP` ioctl. At least one of the
0039 read/write, streaming or asynchronous :ref:`I/O methods <io>` must be
0040 supported. Sliced VBI devices may have a tuner or modulator.
0041
0042 Supplemental Functions
0043 ======================
0044
0045 Sliced VBI devices shall support :ref:`video input or output <video>`
0046 and :ref:`tuner or modulator <tuner>` ioctls if they have these
0047 capabilities, and they may support :ref:`control` ioctls.
0048 The :ref:`video standard <standard>` ioctls provide information vital
0049 to program a sliced VBI device, therefore must be supported.
0050
0051 .. _sliced-vbi-format-negotitation:
0052
0053 Sliced VBI Format Negotiation
0054 =============================
0055
0056 To find out which data services are supported by the hardware
0057 applications can call the
0058 :ref:`VIDIOC_G_SLICED_VBI_CAP <VIDIOC_G_SLICED_VBI_CAP>` ioctl.
0059 All drivers implementing the sliced VBI interface must support this
0060 ioctl. The results may differ from those of the
0061 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl when the number of VBI
0062 lines the hardware can capture or output per frame, or the number of
0063 services it can identify on a given line are limited. For example on PAL
0064 line 16 the hardware may be able to look for a VPS or Teletext signal,
0065 but not both at the same time.
0066
0067 To determine the currently selected services applications set the
0068 ``type`` field of struct :c:type:`v4l2_format` to
0069 ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` or
0070 ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``, and the
0071 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl fills the ``fmt.sliced``
0072 member, a struct
0073 :c:type:`v4l2_sliced_vbi_format`.
0074
0075 Applications can request different parameters by initializing or
0076 modifying the ``fmt.sliced`` member and calling the
0077 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with a pointer to the
0078 struct :c:type:`v4l2_format` structure.
0079
0080 The sliced VBI API is more complicated than the raw VBI API because the
0081 hardware must be told which VBI service to expect on each scan line. Not
0082 all services may be supported by the hardware on all lines (this is
0083 especially true for VBI output where Teletext is often unsupported and
0084 other services can only be inserted in one specific line). In many
0085 cases, however, it is sufficient to just set the ``service_set`` field
0086 to the required services and let the driver fill the ``service_lines``
0087 array according to hardware capabilities. Only if more precise control
0088 is needed should the programmer set the ``service_lines`` array
0089 explicitly.
0090
0091 The :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl modifies the parameters
0092 according to hardware capabilities. When the driver allocates resources
0093 at this point, it may return an ``EBUSY`` error code if the required
0094 resources are temporarily unavailable. Other resource allocation points
0095 which may return ``EBUSY`` can be the
0096 :ref:`VIDIOC_STREAMON` ioctl and the first
0097 :c:func:`read()`, :c:func:`write()` and
0098 :c:func:`select()` call.
0099
0100 .. c:type:: v4l2_sliced_vbi_format
0101
0102 struct v4l2_sliced_vbi_format
0103 -----------------------------
0104
0105 .. raw:: latex
0106
0107 \begingroup
0108 \scriptsize
0109 \setlength{\tabcolsep}{2pt}
0110
0111 .. tabularcolumns:: |p{.85cm}|p{3.3cm}|p{4.45cm}|p{4.45cm}|p{4.45cm}|
0112
0113 .. cssclass:: longtable
0114
0115 .. flat-table::
0116 :header-rows: 0
0117 :stub-columns: 0
0118 :widths: 3 3 2 2 2
0119
0120 * - __u16
0121 - ``service_set``
0122 - :cspan:`2`
0123
0124 If ``service_set`` is non-zero when passed with
0125 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or
0126 :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`, the ``service_lines``
0127 array will be filled by the driver according to the services
0128 specified in this field. For example, if ``service_set`` is
0129 initialized with ``V4L2_SLICED_TELETEXT_B | V4L2_SLICED_WSS_625``,
0130 a driver for the cx25840 video decoder sets lines 7-22 of both
0131 fields [#f1]_ to ``V4L2_SLICED_TELETEXT_B`` and line 23 of the first
0132 field to ``V4L2_SLICED_WSS_625``. If ``service_set`` is set to
0133 zero, then the values of ``service_lines`` will be used instead.
0134
0135 On return the driver sets this field to the union of all elements
0136 of the returned ``service_lines`` array. It may contain less
0137 services than requested, perhaps just one, if the hardware cannot
0138 handle more services simultaneously. It may be empty (zero) if
0139 none of the requested services are supported by the hardware.
0140 * - __u16
0141 - ``service_lines``\ [2][24]
0142 - :cspan:`2`
0143
0144 Applications initialize this array with sets of data services the
0145 driver shall look for or insert on the respective scan line.
0146 Subject to hardware capabilities drivers return the requested set,
0147 a subset, which may be just a single service, or an empty set.
0148 When the hardware cannot handle multiple services on the same line
0149 the driver shall choose one. No assumptions can be made on which
0150 service the driver chooses.
0151
0152 Data services are defined in :ref:`vbi-services2`. Array indices
0153 map to ITU-R line numbers\ [#f2]_ as follows:
0154 * -
0155 -
0156 - Element
0157 - 525 line systems
0158 - 625 line systems
0159 * -
0160 -
0161 - ``service_lines``\ [0][1]
0162 - 1
0163 - 1
0164 * -
0165 -
0166 - ``service_lines``\ [0][23]
0167 - 23
0168 - 23
0169 * -
0170 -
0171 - ``service_lines``\ [1][1]
0172 - 264
0173 - 314
0174 * -
0175 -
0176 - ``service_lines``\ [1][23]
0177 - 286
0178 - 336
0179 * -
0180 -
0181 - :cspan:`2` Drivers must set ``service_lines`` [0][0] and
0182 ``service_lines``\ [1][0] to zero. The
0183 ``V4L2_VBI_ITU_525_F1_START``, ``V4L2_VBI_ITU_525_F2_START``,
0184 ``V4L2_VBI_ITU_625_F1_START`` and ``V4L2_VBI_ITU_625_F2_START``
0185 defines give the start line numbers for each field for each 525 or
0186 625 line format as a convenience. Don't forget that ITU line
0187 numbering starts at 1, not 0.
0188 * - __u32
0189 - ``io_size``
0190 - :cspan:`2` Maximum number of bytes passed by one
0191 :c:func:`read()` or :c:func:`write()` call,
0192 and the buffer size in bytes for the
0193 :ref:`VIDIOC_QBUF` and
0194 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. Drivers set this field
0195 to the size of struct
0196 :c:type:`v4l2_sliced_vbi_data` times the
0197 number of non-zero elements in the returned ``service_lines``
0198 array (that is the number of lines potentially carrying data).
0199 * - __u32
0200 - ``reserved``\ [2]
0201 - :cspan:`2` This array is reserved for future extensions.
0202
0203 Applications and drivers must set it to zero.
0204
0205 .. raw:: latex
0206
0207 \endgroup
0208
0209 .. _vbi-services2:
0210
0211 Sliced VBI services
0212 -------------------
0213
0214 .. raw:: latex
0215
0216 \footnotesize
0217
0218 .. tabularcolumns:: |p{4.2cm}|p{1.1cm}|p{2.1cm}|p{2.0cm}|p{6.5cm}|
0219
0220 .. flat-table::
0221 :header-rows: 1
0222 :stub-columns: 0
0223 :widths: 2 1 1 2 2
0224
0225 * - Symbol
0226 - Value
0227 - Reference
0228 - Lines, usually
0229 - Payload
0230 * - ``V4L2_SLICED_TELETEXT_B`` (Teletext System B)
0231 - 0x0001
0232 - :ref:`ets300706`,
0233
0234 :ref:`itu653`
0235 - PAL/SECAM line 7-22, 320-335 (second field 7-22)
0236 - Last 42 of the 45 byte Teletext packet, that is without clock
0237 run-in and framing code, lsb first transmitted.
0238 * - ``V4L2_SLICED_VPS``
0239 - 0x0400
0240 - :ref:`ets300231`
0241 - PAL line 16
0242 - Byte number 3 to 15 according to Figure 9 of ETS 300 231, lsb
0243 first transmitted.
0244 * - ``V4L2_SLICED_CAPTION_525``
0245 - 0x1000
0246 - :ref:`cea608`
0247 - NTSC line 21, 284 (second field 21)
0248 - Two bytes in transmission order, including parity bit, lsb first
0249 transmitted.
0250 * - ``V4L2_SLICED_WSS_625``
0251 - 0x4000
0252 - :ref:`itu1119`,
0253
0254 :ref:`en300294`
0255 - PAL/SECAM line 23
0256 - See :ref:`v4l2-sliced-wss-625-payload` below.
0257 * - ``V4L2_SLICED_VBI_525``
0258 - 0x1000
0259 - :cspan:`2` Set of services applicable to 525 line systems.
0260 * - ``V4L2_SLICED_VBI_625``
0261 - 0x4401
0262 - :cspan:`2` Set of services applicable to 625 line systems.
0263
0264 .. raw:: latex
0265
0266 \normalsize
0267
0268 Drivers may return an ``EINVAL`` error code when applications attempt to
0269 read or write data without prior format negotiation, after switching the
0270 video standard (which may invalidate the negotiated VBI parameters) and
0271 after switching the video input (which may change the video standard as
0272 a side effect). The :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl may
0273 return an ``EBUSY`` error code when applications attempt to change the
0274 format while i/o is in progress (between a
0275 :ref:`VIDIOC_STREAMON` and
0276 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` call, and after the first
0277 :c:func:`read()` or :c:func:`write()` call).
0278
0279 .. _v4l2-sliced-wss-625-payload:
0280
0281 V4L2_SLICED_WSS_625 payload
0282 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
0283
0284 The payload for ``V4L2_SLICED_WSS_625`` is:
0285
0286 +-----+------------------+-----------------------+
0287 |Byte | 0 | 1 |
0288 +-----+--------+---------+-----------+-----------+
0289 | | msb | lsb | msb | lsb |
0290 | +-+-+-+--+--+-+-+--+--+-+--+---+---+--+-+--+
0291 | Bit |7|6|5|4 | 3|2|1|0 | x|x|13|12 | 11|10|9|8 |
0292 +-----+-+-+-+--+--+-+-+--+--+-+--+---+---+--+-+--+
0293
0294 Reading and writing sliced VBI data
0295 ===================================
0296
0297 A single :c:func:`read()` or :c:func:`write()`
0298 call must pass all data belonging to one video frame. That is an array
0299 of struct :c:type:`v4l2_sliced_vbi_data` structures with one or
0300 more elements and a total size not exceeding ``io_size`` bytes. Likewise
0301 in streaming I/O mode one buffer of ``io_size`` bytes must contain data
0302 of one video frame. The ``id`` of unused
0303 struct :c:type:`v4l2_sliced_vbi_data` elements must be zero.
0304
0305 .. c:type:: v4l2_sliced_vbi_data
0306
0307 struct v4l2_sliced_vbi_data
0308 ---------------------------
0309
0310 .. tabularcolumns:: |p{1.2cm}|p{2.2cm}|p{13.9cm}|
0311
0312 .. flat-table::
0313 :header-rows: 0
0314 :stub-columns: 0
0315 :widths: 3 1 4
0316
0317 * - __u32
0318 - ``id``
0319 - A flag from :ref:`vbi-services` identifying the type of data in
0320 this packet. Only a single bit must be set. When the ``id`` of a
0321 captured packet is zero, the packet is empty and the contents of
0322 other fields are undefined. Applications shall ignore empty
0323 packets. When the ``id`` of a packet for output is zero the
0324 contents of the ``data`` field are undefined and the driver must
0325 no longer insert data on the requested ``field`` and ``line``.
0326 * - __u32
0327 - ``field``
0328 - The video field number this data has been captured from, or shall
0329 be inserted at. ``0`` for the first field, ``1`` for the second
0330 field.
0331 * - __u32
0332 - ``line``
0333 - The field (as opposed to frame) line number this data has been
0334 captured from, or shall be inserted at. See :ref:`vbi-525` and
0335 :ref:`vbi-625` for valid values. Sliced VBI capture devices can
0336 set the line number of all packets to ``0`` if the hardware cannot
0337 reliably identify scan lines. The field number must always be
0338 valid.
0339 * - __u32
0340 - ``reserved``
0341 - This field is reserved for future extensions. Applications and
0342 drivers must set it to zero.
0343 * - __u8
0344 - ``data``\ [48]
0345 - The packet payload. See :ref:`vbi-services` for the contents and
0346 number of bytes passed for each data type. The contents of padding
0347 bytes at the end of this array are undefined, drivers and
0348 applications shall ignore them.
0349
0350 Packets are always passed in ascending line number order, without
0351 duplicate line numbers. The :c:func:`write()` function and
0352 the :ref:`VIDIOC_QBUF` ioctl must return an ``EINVAL``
0353 error code when applications violate this rule. They must also return an
0354 EINVAL error code when applications pass an incorrect field or line
0355 number, or a combination of ``field``, ``line`` and ``id`` which has not
0356 been negotiated with the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` or
0357 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. When the line numbers are
0358 unknown the driver must pass the packets in transmitted order. The
0359 driver can insert empty packets with ``id`` set to zero anywhere in the
0360 packet array.
0361
0362 To assure synchronization and to distinguish from frame dropping, when a
0363 captured frame does not carry any of the requested data services drivers
0364 must pass one or more empty packets. When an application fails to pass
0365 VBI data in time for output, the driver must output the last VPS and WSS
0366 packet again, and disable the output of Closed Caption and Teletext
0367 data, or output data which is ignored by Closed Caption and Teletext
0368 decoders.
0369
0370 A sliced VBI device may support :ref:`read/write <rw>` and/or
0371 streaming (:ref:`memory mapping <mmap>` and/or
0372 :ref:`user pointer <userp>`) I/O. The latter bears the possibility of
0373 synchronizing video and VBI data by using buffer timestamps.
0374
0375 Sliced VBI Data in MPEG Streams
0376 ===============================
0377
0378 If a device can produce an MPEG output stream, it may be capable of
0379 providing
0380 :ref:`negotiated sliced VBI services <sliced-vbi-format-negotitation>`
0381 as data embedded in the MPEG stream. Users or applications control this
0382 sliced VBI data insertion with the
0383 :ref:`V4L2_CID_MPEG_STREAM_VBI_FMT <v4l2-mpeg-stream-vbi-fmt>`
0384 control.
0385
0386 If the driver does not provide the
0387 :ref:`V4L2_CID_MPEG_STREAM_VBI_FMT <v4l2-mpeg-stream-vbi-fmt>`
0388 control, or only allows that control to be set to
0389 :ref:`V4L2_MPEG_STREAM_VBI_FMT_NONE <v4l2-mpeg-stream-vbi-fmt>`,
0390 then the device cannot embed sliced VBI data in the MPEG stream.
0391
0392 The
0393 :ref:`V4L2_CID_MPEG_STREAM_VBI_FMT <v4l2-mpeg-stream-vbi-fmt>`
0394 control does not implicitly set the device driver to capture nor cease
0395 capturing sliced VBI data. The control only indicates to embed sliced
0396 VBI data in the MPEG stream, if an application has negotiated sliced VBI
0397 service be captured.
0398
0399 It may also be the case that a device can embed sliced VBI data in only
0400 certain types of MPEG streams: for example in an MPEG-2 PS but not an
0401 MPEG-2 TS. In this situation, if sliced VBI data insertion is requested,
0402 the sliced VBI data will be embedded in MPEG stream types when
0403 supported, and silently omitted from MPEG stream types where sliced VBI
0404 data insertion is not supported by the device.
0405
0406 The following subsections specify the format of the embedded sliced VBI
0407 data.
0408
0409 MPEG Stream Embedded, Sliced VBI Data Format: NONE
0410 --------------------------------------------------
0411
0412 The
0413 :ref:`V4L2_MPEG_STREAM_VBI_FMT_NONE <v4l2-mpeg-stream-vbi-fmt>`
0414 embedded sliced VBI format shall be interpreted by drivers as a control
0415 to cease embedding sliced VBI data in MPEG streams. Neither the device
0416 nor driver shall insert "empty" embedded sliced VBI data packets in the
0417 MPEG stream when this format is set. No MPEG stream data structures are
0418 specified for this format.
0419
0420 MPEG Stream Embedded, Sliced VBI Data Format: IVTV
0421 --------------------------------------------------
0422
0423 The
0424 :ref:`V4L2_MPEG_STREAM_VBI_FMT_IVTV <v4l2-mpeg-stream-vbi-fmt>`
0425 embedded sliced VBI format, when supported, indicates to the driver to
0426 embed up to 36 lines of sliced VBI data per frame in an MPEG-2 *Private
0427 Stream 1 PES* packet encapsulated in an MPEG-2 *Program Pack* in the
0428 MPEG stream.
0429
0430 *Historical context*: This format specification originates from a
0431 custom, embedded, sliced VBI data format used by the ``ivtv`` driver.
0432 This format has already been informally specified in the kernel sources
0433 in the file ``Documentation/userspace-api/media/drivers/cx2341x-uapi.rst`` . The
0434 maximum size of the payload and other aspects of this format are driven
0435 by the CX23415 MPEG decoder's capabilities and limitations with respect
0436 to extracting, decoding, and displaying sliced VBI data embedded within
0437 an MPEG stream.
0438
0439 This format's use is *not* exclusive to the ``ivtv`` driver *nor*
0440 exclusive to CX2341x devices, as the sliced VBI data packet insertion
0441 into the MPEG stream is implemented in driver software. At least the
0442 ``cx18`` driver provides sliced VBI data insertion into an MPEG-2 PS in
0443 this format as well.
0444
0445 The following definitions specify the payload of the MPEG-2 *Private
0446 Stream 1 PES* packets that contain sliced VBI data when
0447 :ref:`V4L2_MPEG_STREAM_VBI_FMT_IVTV <v4l2-mpeg-stream-vbi-fmt>`
0448 is set. (The MPEG-2 *Private Stream 1 PES* packet header and
0449 encapsulating MPEG-2 *Program Pack* header are not detailed here. Please
0450 refer to the MPEG-2 specifications for details on those packet headers.)
0451
0452 The payload of the MPEG-2 *Private Stream 1 PES* packets that contain
0453 sliced VBI data is specified by struct
0454 :c:type:`v4l2_mpeg_vbi_fmt_ivtv`. The
0455 payload is variable length, depending on the actual number of lines of
0456 sliced VBI data present in a video frame. The payload may be padded at
0457 the end with unspecified fill bytes to align the end of the payload to a
0458 4-byte boundary. The payload shall never exceed 1552 bytes (2 fields
0459 with 18 lines/field with 43 bytes of data/line and a 4 byte magic
0460 number).
0461
0462 .. c:type:: v4l2_mpeg_vbi_fmt_ivtv
0463
0464 struct v4l2_mpeg_vbi_fmt_ivtv
0465 -----------------------------
0466
0467 .. tabularcolumns:: |p{4.2cm}|p{2.0cm}|p{11.1cm}|
0468
0469 .. flat-table::
0470 :header-rows: 0
0471 :stub-columns: 0
0472 :widths: 1 1 2
0473
0474 * - __u8
0475 - ``magic``\ [4]
0476 - A "magic" constant from :ref:`v4l2-mpeg-vbi-fmt-ivtv-magic` that
0477 indicates this is a valid sliced VBI data payload and also
0478 indicates which member of the anonymous union, ``itv0`` or
0479 ``ITV0``, to use for the payload data.
0480 * - union {
0481 - (anonymous)
0482 * - struct :c:type:`v4l2_mpeg_vbi_itv0`
0483 - ``itv0``
0484 - The primary form of the sliced VBI data payload that contains
0485 anywhere from 1 to 35 lines of sliced VBI data. Line masks are
0486 provided in this form of the payload indicating which VBI lines
0487 are provided.
0488 * - struct :ref:`v4l2_mpeg_vbi_ITV0 <v4l2-mpeg-vbi-itv0-1>`
0489 - ``ITV0``
0490 - An alternate form of the sliced VBI data payload used when 36
0491 lines of sliced VBI data are present. No line masks are provided
0492 in this form of the payload; all valid line mask bits are
0493 implcitly set.
0494 * - }
0495 -
0496
0497 .. _v4l2-mpeg-vbi-fmt-ivtv-magic:
0498
0499 Magic Constants for struct v4l2_mpeg_vbi_fmt_ivtv magic field
0500 -------------------------------------------------------------
0501
0502 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|
0503
0504 .. flat-table::
0505 :header-rows: 1
0506 :stub-columns: 0
0507 :widths: 3 1 4
0508
0509 * - Defined Symbol
0510 - Value
0511 - Description
0512 * - ``V4L2_MPEG_VBI_IVTV_MAGIC0``
0513 - "itv0"
0514 - Indicates the ``itv0`` member of the union in struct
0515 :c:type:`v4l2_mpeg_vbi_fmt_ivtv` is
0516 valid.
0517 * - ``V4L2_MPEG_VBI_IVTV_MAGIC1``
0518 - "ITV0"
0519 - Indicates the ``ITV0`` member of the union in struct
0520 :c:type:`v4l2_mpeg_vbi_fmt_ivtv` is
0521 valid and that 36 lines of sliced VBI data are present.
0522
0523
0524 .. c:type:: v4l2_mpeg_vbi_itv0
0525
0526 .. c:type:: v4l2_mpeg_vbi_ITV0
0527
0528 structs v4l2_mpeg_vbi_itv0 and v4l2_mpeg_vbi_ITV0
0529 -------------------------------------------------
0530
0531 .. raw:: latex
0532
0533 \footnotesize
0534
0535 .. tabularcolumns:: |p{4.6cm}|p{2.0cm}|p{10.7cm}|
0536
0537 .. flat-table::
0538 :header-rows: 0
0539 :stub-columns: 0
0540 :widths: 1 1 2
0541
0542 * - __le32
0543 - ``linemask``\ [2]
0544 - Bitmasks indicating the VBI service lines present. These
0545 ``linemask`` values are stored in little endian byte order in the
0546 MPEG stream. Some reference ``linemask`` bit positions with their
0547 corresponding VBI line number and video field are given below.
0548 b\ :sub:`0` indicates the least significant bit of a ``linemask``
0549 value:
0550
0551
0552 ::
0553
0554 linemask[0] b0: line 6 first field
0555 linemask[0] b17: line 23 first field
0556 linemask[0] b18: line 6 second field
0557 linemask[0] b31: line 19 second field
0558 linemask[1] b0: line 20 second field
0559 linemask[1] b3: line 23 second field
0560 linemask[1] b4-b31: unused and set to 0
0561 * - struct
0562 :c:type:`v4l2_mpeg_vbi_itv0_line`
0563 - ``line``\ [35]
0564 - This is a variable length array that holds from 1 to 35 lines of
0565 sliced VBI data. The sliced VBI data lines present correspond to
0566 the bits set in the ``linemask`` array, starting from b\ :sub:`0`
0567 of ``linemask``\ [0] up through b\ :sub:`31` of ``linemask``\ [0],
0568 and from b\ :sub:`0` of ``linemask``\ [1] up through b\ :sub:`3` of
0569 ``linemask``\ [1]. ``line``\ [0] corresponds to the first bit
0570 found set in the ``linemask`` array, ``line``\ [1] corresponds to
0571 the second bit found set in the ``linemask`` array, etc. If no
0572 ``linemask`` array bits are set, then ``line``\ [0] may contain
0573 one line of unspecified data that should be ignored by
0574 applications.
0575
0576 .. raw:: latex
0577
0578 \normalsize
0579
0580 .. _v4l2-mpeg-vbi-itv0-1:
0581
0582 struct v4l2_mpeg_vbi_ITV0
0583 -------------------------
0584
0585 .. tabularcolumns:: |p{5.2cm}|p{2.4cm}|p{9.7cm}|
0586
0587 .. flat-table::
0588 :header-rows: 0
0589 :stub-columns: 0
0590 :widths: 1 1 2
0591
0592 * - struct
0593 :c:type:`v4l2_mpeg_vbi_itv0_line`
0594 - ``line``\ [36]
0595 - A fixed length array of 36 lines of sliced VBI data. ``line``\ [0]
0596 through ``line``\ [17] correspond to lines 6 through 23 of the
0597 first field. ``line``\ [18] through ``line``\ [35] corresponds to
0598 lines 6 through 23 of the second field.
0599
0600
0601 .. c:type:: v4l2_mpeg_vbi_itv0_line
0602
0603 struct v4l2_mpeg_vbi_itv0_line
0604 ------------------------------
0605
0606 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
0607
0608 .. flat-table::
0609 :header-rows: 0
0610 :stub-columns: 0
0611 :widths: 1 1 2
0612
0613 * - __u8
0614 - ``id``
0615 - A line identifier value from
0616 :ref:`ITV0-Line-Identifier-Constants` that indicates the type of
0617 sliced VBI data stored on this line.
0618 * - __u8
0619 - ``data``\ [42]
0620 - The sliced VBI data for the line.
0621
0622
0623 .. _ITV0-Line-Identifier-Constants:
0624
0625 Line Identifiers for struct v4l2_mpeg_vbi_itv0_line id field
0626 ------------------------------------------------------------
0627
0628 .. tabularcolumns:: |p{7.0cm}|p{1.8cm}|p{8.5cm}|
0629
0630 .. flat-table::
0631 :header-rows: 1
0632 :stub-columns: 0
0633 :widths: 3 1 4
0634
0635 * - Defined Symbol
0636 - Value
0637 - Description
0638 * - ``V4L2_MPEG_VBI_IVTV_TELETEXT_B``
0639 - 1
0640 - Refer to :ref:`Sliced VBI services <vbi-services2>` for a
0641 description of the line payload.
0642 * - ``V4L2_MPEG_VBI_IVTV_CAPTION_525``
0643 - 4
0644 - Refer to :ref:`Sliced VBI services <vbi-services2>` for a
0645 description of the line payload.
0646 * - ``V4L2_MPEG_VBI_IVTV_WSS_625``
0647 - 5
0648 - Refer to :ref:`Sliced VBI services <vbi-services2>` for a
0649 description of the line payload.
0650 * - ``V4L2_MPEG_VBI_IVTV_VPS``
0651 - 7
0652 - Refer to :ref:`Sliced VBI services <vbi-services2>` for a
0653 description of the line payload.
0654
0655
0656 .. [#f1]
0657 According to :ref:`ETS 300 706 <ets300706>` lines 6-22 of the first
0658 field and lines 5-22 of the second field may carry Teletext data.
0659
0660 .. [#f2]
0661 See also :ref:`vbi-525` and :ref:`vbi-625`.
