Documentation/media/uapi/v4l/vidioc-encoder-cmd.rst

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