Documentation/media/uapi/v4l/vidioc-encoder-cmd.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_ENCODER_CMD:
  11
  12 ************************************************
  13 ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD
  14 ************************************************
  15
  16 Name
  17 ====
  18
  19 VIDIOC_ENCODER_CMD - VIDIOC_TRY_ENCODER_CMD - Execute an encoder command
  20
  21
  22 Synopsis
  23 ========
  24
  25 .. c:function:: int ioctl( int fd, VIDIOC_ENCODER_CMD, struct v4l2_encoder_cmd *argp )
  26     :name: VIDIOC_ENCODER_CMD
  27
  28 .. c:function:: int ioctl( int fd, VIDIOC_TRY_ENCODER_CMD, struct v4l2_encoder_cmd *argp )
  29     :name: VIDIOC_TRY_ENCODER_CMD
  30
  31
  32 Arguments
  33 =========
  34
  35 ``fd``
  36     File descriptor returned by :ref:`open() <func-open>`.
  37
  38 ``argp``
  39     Pointer to struct :c:type:`v4l2_encoder_cmd`.
  40
  41 Description
  42 ===========
  43
  44 These ioctls control an audio/video (usually MPEG-) encoder.
  45 ``VIDIOC_ENCODER_CMD`` sends a command to the encoder,
  46 ``VIDIOC_TRY_ENCODER_CMD`` can be used to try a command without actually
  47 executing it.
  48
  49 To send a command applications must initialize all fields of a struct
  50 :c:type:`v4l2_encoder_cmd` and call
  51 ``VIDIOC_ENCODER_CMD`` or ``VIDIOC_TRY_ENCODER_CMD`` with a pointer to
  52 this structure.
  53
  54 The ``cmd`` field must contain the command code. The ``flags`` field is
  55 currently only used by the STOP command and contains one bit: If the
  56 ``V4L2_ENC_CMD_STOP_AT_GOP_END`` flag is set, encoding will continue
  57 until the end of the current *Group Of Pictures*, otherwise it will stop
  58 immediately.
  59
  60 A :ref:`read() <func-read>` or :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
  61 call sends an implicit START command to the encoder if it has not been
  62 started yet. After a STOP command, :ref:`read() <func-read>` calls will read
  63 the remaining data buffered by the driver. When the buffer is empty,
  64 :ref:`read() <func-read>` will return zero and the next :ref:`read() <func-read>`
  65 call will restart the encoder.
  66
  67 A :ref:`close() <func-close>` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`
  68 call of a streaming file descriptor sends an implicit immediate STOP to
  69 the encoder, and all buffered data is discarded.
  70
  71 These ioctls are optional, not all drivers may support them. They were
  72 introduced in Linux 2.6.21.
  73
  74
  75 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  76
  77 .. c:type:: v4l2_encoder_cmd
  78
  79 .. flat-table:: struct v4l2_encoder_cmd
  80     :header-rows:  0
  81     :stub-columns: 0
  82     :widths:       1 1 2
  83
  84     * - __u32
  85       - ``cmd``
  86       - The encoder command, see :ref:`encoder-cmds`.
  87     * - __u32
  88       - ``flags``
  89       - Flags to go with the command, see :ref:`encoder-flags`. If no
  90         flags are defined for this command, drivers and applications must
  91         set this field to zero.
  92     * - __u32
  93       - ``data``\ [8]
  94       - Reserved for future extensions. Drivers and applications must set
  95         the array to zero.
  96
  97
  98
  99 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 100
 101 .. _encoder-cmds:
 102
 103 .. flat-table:: Encoder Commands
 104     :header-rows:  0
 105     :stub-columns: 0
 106     :widths:       3 1 4
 107
 108     * - ``V4L2_ENC_CMD_START``
 109       - 0
 110       - Start the encoder. When the encoder is already running or paused,
 111         this command does nothing. No flags are defined for this command.
 112     * - ``V4L2_ENC_CMD_STOP``
 113       - 1
 114       - Stop the encoder. When the ``V4L2_ENC_CMD_STOP_AT_GOP_END`` flag
 115         is set, encoding will continue until the end of the current *Group
 116         Of Pictures*, otherwise encoding will stop immediately. When the
 117         encoder is already stopped, this command does nothing. mem2mem
 118         encoders will send a ``V4L2_EVENT_EOS`` event when the last frame
 119         has been encoded and all frames are ready to be dequeued and will
 120         set the ``V4L2_BUF_FLAG_LAST`` buffer flag on the last buffer of
 121         the capture queue to indicate there will be no new buffers
 122         produced to dequeue. This buffer may be empty, indicated by the
 123         driver setting the ``bytesused`` field to 0. Once the
 124         ``V4L2_BUF_FLAG_LAST`` flag was set, the
 125         :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore,
 126         but return an ``EPIPE`` error code.
 127     * - ``V4L2_ENC_CMD_PAUSE``
 128       - 2
 129       - Pause the encoder. When the encoder has not been started yet, the
 130         driver will return an ``EPERM`` error code. When the encoder is
 131         already paused, this command does nothing. No flags are defined
 132         for this command.
 133     * - ``V4L2_ENC_CMD_RESUME``
 134       - 3
 135       - Resume encoding after a PAUSE command. When the encoder has not
 136         been started yet, the driver will return an ``EPERM`` error code. When
 137         the encoder is already running, this command does nothing. No
 138         flags are defined for this command.
 139
 140
 141 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 142
 143 .. _encoder-flags:
 144
 145 .. flat-table:: Encoder Command Flags
 146     :header-rows:  0
 147     :stub-columns: 0
 148     :widths:       3 1 4
 149
 150     * - ``V4L2_ENC_CMD_STOP_AT_GOP_END``
 151       - 0x0001
 152       - Stop encoding at the end of the current *Group Of Pictures*,
 153         rather than immediately.
 154
 155
 156 Return Value
 157 ============
 158
 159 On success 0 is returned, on error -1 and the ``errno`` variable is set
 160 appropriately. The generic error codes are described at the
 161 :ref:`Generic Error Codes <gen-errors>` chapter.
 162
 163 EINVAL
 164     The ``cmd`` field is invalid.
 165
 166 EPERM
 167     The application sent a PAUSE or RESUME command when the encoder was
 168     not running.