Documentation/media/uapi/v4l/vidioc-g-enc-index.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _VIDIOC_G_ENC_INDEX:
   4
   5 ************************
   6 ioctl VIDIOC_G_ENC_INDEX
   7 ************************
   8
   9 Name
  10 ====
  11
  12 VIDIOC_G_ENC_INDEX - Get meta data about a compressed video stream
  13
  14
  15 Synopsis
  16 ========
  17
  18 .. c:function:: int ioctl( int fd, VIDIOC_G_ENC_INDEX, struct v4l2_enc_idx *argp )
  19     :name: VIDIOC_G_ENC_INDEX
  20
  21
  22 Arguments
  23 =========
  24
  25 ``fd``
  26     File descriptor returned by :ref:`open() <func-open>`.
  27
  28 ``argp``
  29     Pointer to struct :c:type:`v4l2_enc_idx`.
  30
  31
  32 Description
  33 ===========
  34
  35 The :ref:`VIDIOC_G_ENC_INDEX <VIDIOC_G_ENC_INDEX>` ioctl provides meta data about a compressed
  36 video stream the same or another application currently reads from the
  37 driver, which is useful for random access into the stream without
  38 decoding it.
  39
  40 To read the data applications must call :ref:`VIDIOC_G_ENC_INDEX <VIDIOC_G_ENC_INDEX>` with a
  41 pointer to a struct :c:type:`v4l2_enc_idx`. On success
  42 the driver fills the ``entry`` array, stores the number of elements
  43 written in the ``entries`` field, and initializes the ``entries_cap``
  44 field.
  45
  46 Each element of the ``entry`` array contains meta data about one
  47 picture. A :ref:`VIDIOC_G_ENC_INDEX <VIDIOC_G_ENC_INDEX>` call reads up to
  48 ``V4L2_ENC_IDX_ENTRIES`` entries from a driver buffer, which can hold up
  49 to ``entries_cap`` entries. This number can be lower or higher than
  50 ``V4L2_ENC_IDX_ENTRIES``, but not zero. When the application fails to
  51 read the meta data in time the oldest entries will be lost. When the
  52 buffer is empty or no capturing/encoding is in progress, ``entries``
  53 will be zero.
  54
  55 Currently this ioctl is only defined for MPEG-2 program streams and
  56 video elementary streams.
  57
  58
  59 .. tabularcolumns:: |p{3.8cm}|p{5.6cm}|p{8.1cm}|
  60
  61 .. c:type:: v4l2_enc_idx
  62
  63 .. flat-table:: struct v4l2_enc_idx
  64     :header-rows:  0
  65     :stub-columns: 0
  66     :widths:       1 3 8
  67
  68     * - __u32
  69       - ``entries``
  70       - The number of entries the driver stored in the ``entry`` array.
  71     * - __u32
  72       - ``entries_cap``
  73       - The number of entries the driver can buffer. Must be greater than
  74         zero.
  75     * - __u32
  76       - ``reserved``\ [4]
  77       - Reserved for future extensions. Drivers must set the
  78         array to zero.
  79     * - struct :c:type:`v4l2_enc_idx_entry`
  80       - ``entry``\ [``V4L2_ENC_IDX_ENTRIES``]
  81       - Meta data about a compressed video stream. Each element of the
  82         array corresponds to one picture, sorted in ascending order by
  83         their ``offset``.
  84
  85
  86
  87 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  88
  89 .. c:type:: v4l2_enc_idx_entry
  90
  91 .. flat-table:: struct v4l2_enc_idx_entry
  92     :header-rows:  0
  93     :stub-columns: 0
  94     :widths:       1 1 2
  95
  96     * - __u64
  97       - ``offset``
  98       - The offset in bytes from the beginning of the compressed video
  99         stream to the beginning of this picture, that is a *PES packet
 100         header* as defined in :ref:`mpeg2part1` or a *picture header* as
 101         defined in :ref:`mpeg2part2`. When the encoder is stopped, the
 102         driver resets the offset to zero.
 103     * - __u64
 104       - ``pts``
 105       - The 33 bit *Presentation Time Stamp* of this picture as defined in
 106         :ref:`mpeg2part1`.
 107     * - __u32
 108       - ``length``
 109       - The length of this picture in bytes.
 110     * - __u32
 111       - ``flags``
 112       - Flags containing the coding type of this picture, see
 113         :ref:`enc-idx-flags`.
 114     * - __u32
 115       - ``reserved``\ [2]
 116       - Reserved for future extensions. Drivers must set the array to
 117         zero.
 118
 119
 120 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 121
 122 .. _enc-idx-flags:
 123
 124 .. flat-table:: Index Entry Flags
 125     :header-rows:  0
 126     :stub-columns: 0
 127     :widths:       3 1 4
 128
 129     * - ``V4L2_ENC_IDX_FRAME_I``
 130       - 0x00
 131       - This is an Intra-coded picture.
 132     * - ``V4L2_ENC_IDX_FRAME_P``
 133       - 0x01
 134       - This is a Predictive-coded picture.
 135     * - ``V4L2_ENC_IDX_FRAME_B``
 136       - 0x02
 137       - This is a Bidirectionally predictive-coded picture.
 138     * - ``V4L2_ENC_IDX_FRAME_MASK``
 139       - 0x0F
 140       - *AND* the flags field with this mask to obtain the picture coding
 141         type.
 142
 143
 144 Return Value
 145 ============
 146
 147 On success 0 is returned, on error -1 and the ``errno`` variable is set
 148 appropriately. The generic error codes are described at the
 149 :ref:`Generic Error Codes <gen-errors>` chapter.