| .. -*- coding: utf-8; mode: rst -*- |
| |
| .. _raw-vbi: |
| |
| ********************** |
| Raw VBI Data Interface |
| ********************** |
| |
| VBI is an abbreviation of Vertical Blanking Interval, a gap in the |
| sequence of lines of an analog video signal. During VBI no picture |
| information is transmitted, allowing some time while the electron beam |
| of a cathode ray tube TV returns to the top of the screen. Using an |
| oscilloscope you will find here the vertical synchronization pulses and |
| short data packages ASK modulated [#f1]_ onto the video signal. These are |
| transmissions of services such as Teletext or Closed Caption. |
| |
| Subject of this interface type is raw VBI data, as sampled off a video |
| signal, or to be added to a signal for output. The data format is |
| similar to uncompressed video images, a number of lines times a number |
| of samples per line, we call this a VBI image. |
| |
| Conventionally V4L2 VBI devices are accessed through character device |
| special files named ``/dev/vbi`` and ``/dev/vbi0`` to ``/dev/vbi31`` |
| with major number 81 and minor numbers 224 to 255. ``/dev/vbi`` is |
| typically a symbolic link to the preferred VBI device. This convention |
| applies to both input and output devices. |
| |
| To address the problems of finding related video and VBI devices VBI |
| capturing and output is also available as device function under |
| ``/dev/video``. To capture or output raw VBI data with these devices |
| applications must call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. |
| Accessed as ``/dev/vbi``, raw VBI capturing or output is the default |
| device function. |
| |
| |
| Querying Capabilities |
| ===================== |
| |
| Devices supporting the raw VBI capturing or output API set the |
| ``V4L2_CAP_VBI_CAPTURE`` or ``V4L2_CAP_VBI_OUTPUT`` flags, respectively, |
| in the ``capabilities`` field of struct |
| :ref:`v4l2_capability <v4l2-capability>` returned by the |
| :ref:`VIDIOC_QUERYCAP` ioctl. At least one of the |
| read/write, streaming or asynchronous I/O methods must be supported. VBI |
| devices may or may not have a tuner or modulator. |
| |
| |
| Supplemental Functions |
| ====================== |
| |
| VBI devices shall support :ref:`video input or output <video>`, |
| :ref:`tuner or modulator <tuner>`, and :ref:`controls <control>` |
| ioctls as needed. The :ref:`video standard <standard>` ioctls provide |
| information vital to program a VBI device, therefore must be supported. |
| |
| |
| Raw VBI Format Negotiation |
| ========================== |
| |
| Raw VBI sampling abilities can vary, in particular the sampling |
| frequency. To properly interpret the data V4L2 specifies an ioctl to |
| query the sampling parameters. Moreover, to allow for some flexibility |
| applications can also suggest different parameters. |
| |
| As usual these parameters are *not* reset at :ref:`open() <func-open>` |
| time to permit Unix tool chains, programming a device and then reading |
| from it as if it was a plain file. Well written V4L2 applications should |
| always ensure they really get what they want, requesting reasonable |
| parameters and then checking if the actual parameters are suitable. |
| |
| To query the current raw VBI capture parameters applications set the |
| ``type`` field of a struct :ref:`v4l2_format <v4l2-format>` to |
| ``V4L2_BUF_TYPE_VBI_CAPTURE`` or ``V4L2_BUF_TYPE_VBI_OUTPUT``, and call |
| the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer to this |
| structure. Drivers fill the struct |
| :ref:`v4l2_vbi_format <v4l2-vbi-format>` ``vbi`` member of the |
| ``fmt`` union. |
| |
| To request different parameters applications set the ``type`` field of a |
| struct :ref:`v4l2_format <v4l2-format>` as above and initialize all |
| fields of the struct :ref:`v4l2_vbi_format <v4l2-vbi-format>` |
| ``vbi`` member of the ``fmt`` union, or better just modify the results |
| of :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, and call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` |
| ioctl with a pointer to this structure. Drivers return an ``EINVAL`` error |
| code only when the given parameters are ambiguous, otherwise they modify |
| the parameters according to the hardware capabilities and return the |
| actual parameters. When the driver allocates resources at this point, it |
| may return an ``EBUSY`` error code to indicate the returned parameters are |
| valid but the required resources are currently not available. That may |
| happen for instance when the video and VBI areas to capture would |
| overlap, or when the driver supports multiple opens and another process |
| already requested VBI capturing or output. Anyway, applications must |
| expect other resource allocation points which may return ``EBUSY``, at the |
| :ref:`VIDIOC_STREAMON` ioctl and the first :ref:`read() <func-read>` |
| , :ref:`write() <func-write>` and :ref:`select() <func-select>` calls. |
| |
| VBI devices must implement both the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and |
| :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ignores all requests |
| and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. |
| :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional. |
| |
| .. tabularcolumns:: |p{2.4cm}|p{4.4cm}|p{10.7cm}| |
| |
| .. _v4l2-vbi-format: |
| |
| .. cssclass:: longtable |
| |
| .. flat-table:: struct v4l2_vbi_format |
| :header-rows: 0 |
| :stub-columns: 0 |
| :widths: 1 1 2 |
| |
| |
| - .. row 1 |
| |
| - __u32 |
| |
| - ``sampling_rate`` |
| |
| - Samples per second, i. e. unit 1 Hz. |
| |
| - .. row 2 |
| |
| - __u32 |
| |
| - ``offset`` |
| |
| - Horizontal offset of the VBI image, relative to the leading edge |
| of the line synchronization pulse and counted in samples: The |
| first sample in the VBI image will be located ``offset`` / |
| ``sampling_rate`` seconds following the leading edge. See also |
| :ref:`vbi-hsync`. |
| |
| - .. row 3 |
| |
| - __u32 |
| |
| - ``samples_per_line`` |
| |
| - |
| |
| - .. row 4 |
| |
| - __u32 |
| |
| - ``sample_format`` |
| |
| - Defines the sample format as in :ref:`pixfmt`, a |
| four-character-code. [#f2]_ Usually this is ``V4L2_PIX_FMT_GREY``, |
| i. e. each sample consists of 8 bits with lower values oriented |
| towards the black level. Do not assume any other correlation of |
| values with the signal level. For example, the MSB does not |
| necessarily indicate if the signal is 'high' or 'low' because 128 |
| may not be the mean value of the signal. Drivers shall not convert |
| the sample format by software. |
| |
| - .. row 5 |
| |
| - __u32 |
| |
| - ``start``\ [#f2]_ |
| |
| - This is the scanning system line number associated with the first |
| line of the VBI image, of the first and the second field |
| respectively. See :ref:`vbi-525` and :ref:`vbi-625` for valid |
| values. The ``V4L2_VBI_ITU_525_F1_START``, |
| ``V4L2_VBI_ITU_525_F2_START``, ``V4L2_VBI_ITU_625_F1_START`` and |
| ``V4L2_VBI_ITU_625_F2_START`` defines give the start line numbers |
| for each field for each 525 or 625 line format as a convenience. |
| Don't forget that ITU line numbering starts at 1, not 0. VBI input |
| drivers can return start values 0 if the hardware cannot reliable |
| identify scanning lines, VBI acquisition may not require this |
| information. |
| |
| - .. row 6 |
| |
| - __u32 |
| |
| - ``count``\ [#f2]_ |
| |
| - The number of lines in the first and second field image, |
| respectively. |
| |
| - .. row 7 |
| |
| - :cspan:`2` |
| |
| Drivers should be as flexibility as possible. For example, it may |
| be possible to extend or move the VBI capture window down to the |
| picture area, implementing a 'full field mode' to capture data |
| service transmissions embedded in the picture. |
| |
| An application can set the first or second ``count`` value to zero |
| if no data is required from the respective field; ``count``\ [1] |
| if the scanning system is progressive, i. e. not interlaced. The |
| corresponding start value shall be ignored by the application and |
| driver. Anyway, drivers may not support single field capturing and |
| return both count values non-zero. |
| |
| Both ``count`` values set to zero, or line numbers are outside the |
| bounds depicted\ [#f4]_, or a field image covering lines of two |
| fields, are invalid and shall not be returned by the driver. |
| |
| To initialize the ``start`` and ``count`` fields, applications |
| must first determine the current video standard selection. The |
| :ref:`v4l2_std_id <v4l2-std-id>` or the ``framelines`` field |
| of struct :ref:`v4l2_standard <v4l2-standard>` can be evaluated |
| for this purpose. |
| |
| - .. row 8 |
| |
| - __u32 |
| |
| - ``flags`` |
| |
| - See :ref:`vbifmt-flags` below. Currently only drivers set flags, |
| applications must set this field to zero. |
| |
| - .. row 9 |
| |
| - __u32 |
| |
| - ``reserved``\ [#f2]_ |
| |
| - This array is reserved for future extensions. Drivers and |
| applications must set it to zero. |
| |
| |
| .. tabularcolumns:: |p{4.0cm}|p{1.5cm}|p{12.0cm}| |
| |
| .. _vbifmt-flags: |
| |
| .. flat-table:: Raw VBI Format Flags |
| :header-rows: 0 |
| :stub-columns: 0 |
| :widths: 3 1 4 |
| |
| |
| - .. row 1 |
| |
| - ``V4L2_VBI_UNSYNC`` |
| |
| - 0x0001 |
| |
| - This flag indicates hardware which does not properly distinguish |
| between fields. Normally the VBI image stores the first field |
| (lower scanning line numbers) first in memory. This may be a top |
| or bottom field depending on the video standard. When this flag is |
| set the first or second field may be stored first, however the |
| fields are still in correct temporal order with the older field |
| first in memory. [#f3]_ |
| |
| - .. row 2 |
| |
| - ``V4L2_VBI_INTERLACED`` |
| |
| - 0x0002 |
| |
| - By default the two field images will be passed sequentially; all |
| lines of the first field followed by all lines of the second field |
| (compare :ref:`field-order` ``V4L2_FIELD_SEQ_TB`` and |
| ``V4L2_FIELD_SEQ_BT``, whether the top or bottom field is first in |
| memory depends on the video standard). When this flag is set, the |
| two fields are interlaced (cf. ``V4L2_FIELD_INTERLACED``). The |
| first line of the first field followed by the first line of the |
| second field, then the two second lines, and so on. Such a layout |
| may be necessary when the hardware has been programmed to capture |
| or output interlaced video images and is unable to separate the |
| fields for VBI capturing at the same time. For simplicity setting |
| this flag implies that both ``count`` values are equal and |
| non-zero. |
| |
| |
| |
| .. _vbi-hsync: |
| |
| .. figure:: dev-raw-vbi_files/vbi_hsync.* |
| :alt: vbi_hsync.pdf / vbi_hsync.gif |
| :align: center |
| |
| **Figure 4.1. Line synchronization** |
| |
| |
| .. _vbi-525: |
| |
| .. figure:: dev-raw-vbi_files/vbi_525.* |
| :alt: vbi_525.pdf / vbi_525.gif |
| :align: center |
| |
| **Figure 4.2. ITU-R 525 line numbering (M/NTSC and M/PAL)** |
| |
| |
| |
| .. _vbi-625: |
| |
| .. figure:: dev-raw-vbi_files/vbi_625.* |
| :alt: vbi_625.pdf / vbi_625.gif |
| :align: center |
| |
| **Figure 4.3. ITU-R 625 line numbering** |
| |
| |
| |
| Remember the VBI image format depends on the selected video standard, |
| therefore the application must choose a new standard or query the |
| current standard first. Attempts to read or write data ahead of format |
| negotiation, or after switching the video standard which may invalidate |
| the negotiated VBI parameters, should be refused by the driver. A format |
| change during active I/O is not permitted. |
| |
| |
| Reading and writing VBI images |
| ============================== |
| |
| To assure synchronization with the field number and easier |
| implementation, the smallest unit of data passed at a time is one frame, |
| consisting of two fields of VBI images immediately following in memory. |
| |
| The total size of a frame computes as follows: |
| |
| |
| .. code-block:: c |
| |
| (count[0] + count[1]) * samples_per_line * sample size in bytes |
| |
| The sample size is most likely always one byte, applications must check |
| the ``sample_format`` field though, to function properly with other |
| drivers. |
| |
| A VBI device may support :ref:`read/write <rw>` and/or streaming |
| (:ref:`memory mapping <mmap>` or :ref:`user pointer <userp>`) I/O. |
| The latter bears the possibility of synchronizing video and VBI data by |
| using buffer timestamps. |
| |
| Remember the :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` ioctl and the |
| first :ref:`read() <func-read>`, :ref:`write() <func-write>` and |
| :ref:`select() <func-select>` call can be resource allocation |
| points returning an ``EBUSY`` error code if the required hardware resources |
| are temporarily unavailable, for example the device is already in use by |
| another process. |
| |
| .. [#f1] |
| ASK: Amplitude-Shift Keying. A high signal level represents a '1' |
| bit, a low level a '0' bit. |
| |
| .. [#f2] |
| A few devices may be unable to sample VBI data at all but can extend |
| the video capture window to the VBI region. |
| |
| .. [#f3] |
| Most VBI services transmit on both fields, but some have different |
| semantics depending on the field number. These cannot be reliable |
| decoded or encoded when ``V4L2_VBI_UNSYNC`` is set. |
| |
| .. [#f4] |
| The valid values ar shown at :ref:`vbi-525` and :ref:`vbi-625`. |