1059b1c5bSMauro Carvalho Chehab.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2407e84cdSMauro Carvalho Chehab.. c:namespace:: V4L 354f38fcaSMauro Carvalho Chehab 454f38fcaSMauro Carvalho Chehab.. _VIDIOC_G_ENC_INDEX: 554f38fcaSMauro Carvalho Chehab 654f38fcaSMauro Carvalho Chehab************************ 754f38fcaSMauro Carvalho Chehabioctl VIDIOC_G_ENC_INDEX 854f38fcaSMauro Carvalho Chehab************************ 954f38fcaSMauro Carvalho Chehab 1054f38fcaSMauro Carvalho ChehabName 1154f38fcaSMauro Carvalho Chehab==== 1254f38fcaSMauro Carvalho Chehab 1354f38fcaSMauro Carvalho ChehabVIDIOC_G_ENC_INDEX - Get meta data about a compressed video stream 1454f38fcaSMauro Carvalho Chehab 1554f38fcaSMauro Carvalho ChehabSynopsis 1654f38fcaSMauro Carvalho Chehab======== 1754f38fcaSMauro Carvalho Chehab 18407e84cdSMauro Carvalho Chehab.. c:macro:: VIDIOC_G_ENC_INDEX 1954f38fcaSMauro Carvalho Chehab 20407e84cdSMauro Carvalho Chehab``int ioctl(int fd, VIDIOC_G_ENC_INDEX, struct v4l2_enc_idx *argp)`` 2154f38fcaSMauro Carvalho Chehab 2254f38fcaSMauro Carvalho ChehabArguments 2354f38fcaSMauro Carvalho Chehab========= 2454f38fcaSMauro Carvalho Chehab 2554f38fcaSMauro Carvalho Chehab``fd`` 26407e84cdSMauro Carvalho Chehab File descriptor returned by :c:func:`open()`. 2754f38fcaSMauro Carvalho Chehab 2854f38fcaSMauro Carvalho Chehab``argp`` 2954f38fcaSMauro Carvalho Chehab Pointer to struct :c:type:`v4l2_enc_idx`. 3054f38fcaSMauro Carvalho Chehab 3154f38fcaSMauro Carvalho ChehabDescription 3254f38fcaSMauro Carvalho Chehab=========== 3354f38fcaSMauro Carvalho Chehab 3454f38fcaSMauro Carvalho ChehabThe :ref:`VIDIOC_G_ENC_INDEX <VIDIOC_G_ENC_INDEX>` ioctl provides meta data about a compressed 3554f38fcaSMauro Carvalho Chehabvideo stream the same or another application currently reads from the 3654f38fcaSMauro Carvalho Chehabdriver, which is useful for random access into the stream without 3754f38fcaSMauro Carvalho Chehabdecoding it. 3854f38fcaSMauro Carvalho Chehab 3954f38fcaSMauro Carvalho ChehabTo read the data applications must call :ref:`VIDIOC_G_ENC_INDEX <VIDIOC_G_ENC_INDEX>` with a 4054f38fcaSMauro Carvalho Chehabpointer to a struct :c:type:`v4l2_enc_idx`. On success 4154f38fcaSMauro Carvalho Chehabthe driver fills the ``entry`` array, stores the number of elements 4254f38fcaSMauro Carvalho Chehabwritten in the ``entries`` field, and initializes the ``entries_cap`` 4354f38fcaSMauro Carvalho Chehabfield. 4454f38fcaSMauro Carvalho Chehab 4554f38fcaSMauro Carvalho ChehabEach element of the ``entry`` array contains meta data about one 4654f38fcaSMauro Carvalho Chehabpicture. A :ref:`VIDIOC_G_ENC_INDEX <VIDIOC_G_ENC_INDEX>` call reads up to 4754f38fcaSMauro Carvalho Chehab``V4L2_ENC_IDX_ENTRIES`` entries from a driver buffer, which can hold up 4854f38fcaSMauro Carvalho Chehabto ``entries_cap`` entries. This number can be lower or higher than 4954f38fcaSMauro Carvalho Chehab``V4L2_ENC_IDX_ENTRIES``, but not zero. When the application fails to 5054f38fcaSMauro Carvalho Chehabread the meta data in time the oldest entries will be lost. When the 5154f38fcaSMauro Carvalho Chehabbuffer is empty or no capturing/encoding is in progress, ``entries`` 5254f38fcaSMauro Carvalho Chehabwill be zero. 5354f38fcaSMauro Carvalho Chehab 5454f38fcaSMauro Carvalho ChehabCurrently this ioctl is only defined for MPEG-2 program streams and 5554f38fcaSMauro Carvalho Chehabvideo elementary streams. 5654f38fcaSMauro Carvalho Chehab 57*fea13a69SMauro Carvalho Chehab.. tabularcolumns:: |p{4.2cm}|p{6.2cm}|p{6.9cm}| 5854f38fcaSMauro Carvalho Chehab 5954f38fcaSMauro Carvalho Chehab.. c:type:: v4l2_enc_idx 6054f38fcaSMauro Carvalho Chehab 6154f38fcaSMauro Carvalho Chehab.. flat-table:: struct v4l2_enc_idx 6254f38fcaSMauro Carvalho Chehab :header-rows: 0 6354f38fcaSMauro Carvalho Chehab :stub-columns: 0 6454f38fcaSMauro Carvalho Chehab :widths: 1 3 8 6554f38fcaSMauro Carvalho Chehab 6654f38fcaSMauro Carvalho Chehab * - __u32 6754f38fcaSMauro Carvalho Chehab - ``entries`` 6854f38fcaSMauro Carvalho Chehab - The number of entries the driver stored in the ``entry`` array. 6954f38fcaSMauro Carvalho Chehab * - __u32 7054f38fcaSMauro Carvalho Chehab - ``entries_cap`` 7154f38fcaSMauro Carvalho Chehab - The number of entries the driver can buffer. Must be greater than 7254f38fcaSMauro Carvalho Chehab zero. 7354f38fcaSMauro Carvalho Chehab * - __u32 7454f38fcaSMauro Carvalho Chehab - ``reserved``\ [4] 7554f38fcaSMauro Carvalho Chehab - Reserved for future extensions. Drivers must set the 7654f38fcaSMauro Carvalho Chehab array to zero. 7754f38fcaSMauro Carvalho Chehab * - struct :c:type:`v4l2_enc_idx_entry` 7854f38fcaSMauro Carvalho Chehab - ``entry``\ [``V4L2_ENC_IDX_ENTRIES``] 7954f38fcaSMauro Carvalho Chehab - Meta data about a compressed video stream. Each element of the 8054f38fcaSMauro Carvalho Chehab array corresponds to one picture, sorted in ascending order by 8154f38fcaSMauro Carvalho Chehab their ``offset``. 8254f38fcaSMauro Carvalho Chehab 8354f38fcaSMauro Carvalho Chehab 84*fea13a69SMauro Carvalho Chehab.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| 8554f38fcaSMauro Carvalho Chehab 8654f38fcaSMauro Carvalho Chehab.. c:type:: v4l2_enc_idx_entry 8754f38fcaSMauro Carvalho Chehab 8854f38fcaSMauro Carvalho Chehab.. flat-table:: struct v4l2_enc_idx_entry 8954f38fcaSMauro Carvalho Chehab :header-rows: 0 9054f38fcaSMauro Carvalho Chehab :stub-columns: 0 9154f38fcaSMauro Carvalho Chehab :widths: 1 1 2 9254f38fcaSMauro Carvalho Chehab 9354f38fcaSMauro Carvalho Chehab * - __u64 9454f38fcaSMauro Carvalho Chehab - ``offset`` 9554f38fcaSMauro Carvalho Chehab - The offset in bytes from the beginning of the compressed video 9654f38fcaSMauro Carvalho Chehab stream to the beginning of this picture, that is a *PES packet 9754f38fcaSMauro Carvalho Chehab header* as defined in :ref:`mpeg2part1` or a *picture header* as 9854f38fcaSMauro Carvalho Chehab defined in :ref:`mpeg2part2`. When the encoder is stopped, the 9954f38fcaSMauro Carvalho Chehab driver resets the offset to zero. 10054f38fcaSMauro Carvalho Chehab * - __u64 10154f38fcaSMauro Carvalho Chehab - ``pts`` 10254f38fcaSMauro Carvalho Chehab - The 33 bit *Presentation Time Stamp* of this picture as defined in 10354f38fcaSMauro Carvalho Chehab :ref:`mpeg2part1`. 10454f38fcaSMauro Carvalho Chehab * - __u32 10554f38fcaSMauro Carvalho Chehab - ``length`` 10654f38fcaSMauro Carvalho Chehab - The length of this picture in bytes. 10754f38fcaSMauro Carvalho Chehab * - __u32 10854f38fcaSMauro Carvalho Chehab - ``flags`` 10954f38fcaSMauro Carvalho Chehab - Flags containing the coding type of this picture, see 11054f38fcaSMauro Carvalho Chehab :ref:`enc-idx-flags`. 11154f38fcaSMauro Carvalho Chehab * - __u32 11254f38fcaSMauro Carvalho Chehab - ``reserved``\ [2] 11354f38fcaSMauro Carvalho Chehab - Reserved for future extensions. Drivers must set the array to 11454f38fcaSMauro Carvalho Chehab zero. 11554f38fcaSMauro Carvalho Chehab 116*fea13a69SMauro Carvalho Chehab.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| 11754f38fcaSMauro Carvalho Chehab 11854f38fcaSMauro Carvalho Chehab.. _enc-idx-flags: 11954f38fcaSMauro Carvalho Chehab 12054f38fcaSMauro Carvalho Chehab.. flat-table:: Index Entry Flags 12154f38fcaSMauro Carvalho Chehab :header-rows: 0 12254f38fcaSMauro Carvalho Chehab :stub-columns: 0 12354f38fcaSMauro Carvalho Chehab :widths: 3 1 4 12454f38fcaSMauro Carvalho Chehab 12554f38fcaSMauro Carvalho Chehab * - ``V4L2_ENC_IDX_FRAME_I`` 12654f38fcaSMauro Carvalho Chehab - 0x00 12754f38fcaSMauro Carvalho Chehab - This is an Intra-coded picture. 12854f38fcaSMauro Carvalho Chehab * - ``V4L2_ENC_IDX_FRAME_P`` 12954f38fcaSMauro Carvalho Chehab - 0x01 13054f38fcaSMauro Carvalho Chehab - This is a Predictive-coded picture. 13154f38fcaSMauro Carvalho Chehab * - ``V4L2_ENC_IDX_FRAME_B`` 13254f38fcaSMauro Carvalho Chehab - 0x02 13354f38fcaSMauro Carvalho Chehab - This is a Bidirectionally predictive-coded picture. 13454f38fcaSMauro Carvalho Chehab * - ``V4L2_ENC_IDX_FRAME_MASK`` 13554f38fcaSMauro Carvalho Chehab - 0x0F 13654f38fcaSMauro Carvalho Chehab - *AND* the flags field with this mask to obtain the picture coding 13754f38fcaSMauro Carvalho Chehab type. 13854f38fcaSMauro Carvalho Chehab 13954f38fcaSMauro Carvalho ChehabReturn Value 14054f38fcaSMauro Carvalho Chehab============ 14154f38fcaSMauro Carvalho Chehab 14254f38fcaSMauro Carvalho ChehabOn success 0 is returned, on error -1 and the ``errno`` variable is set 14354f38fcaSMauro Carvalho Chehabappropriately. The generic error codes are described at the 14454f38fcaSMauro Carvalho Chehab:ref:`Generic Error Codes <gen-errors>` chapter. 145