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

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