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