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     Pointer to struct :c:type:`v4l2_encoder_cmd`.
  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     * - __u32
  78       - ``cmd``
  79       - The encoder command, see :ref:`encoder-cmds`.
  80     * - __u32
  81       - ``flags``
  82       - Flags to go with the command, see :ref:`encoder-flags`. If no
  83         flags are defined for this command, drivers and applications must
  84         set this field to zero.
  85     * - __u32
  86       - ``data``\ [8]
  87       - Reserved for future extensions. Drivers and applications must set
  88         the array to zero.
  89
  90
  91
  92 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
  93
  94 .. _encoder-cmds:
  95
  96 .. flat-table:: Encoder Commands
  97     :header-rows:  0
  98     :stub-columns: 0
  99     :widths:       3 1 4
 100
 101     * - ``V4L2_ENC_CMD_START``
 102       - 0
 103       - Start the encoder. When the encoder is already running or paused,
 104         this command does nothing. No flags are defined for this command.
 105     * - ``V4L2_ENC_CMD_STOP``
 106       - 1
 107       - Stop the encoder. When the ``V4L2_ENC_CMD_STOP_AT_GOP_END`` flag
 108         is set, encoding will continue until the end of the current *Group
 109         Of Pictures*, otherwise encoding will stop immediately. When the
 110         encoder is already stopped, this command does nothing. mem2mem
 111         encoders will send a ``V4L2_EVENT_EOS`` event when the last frame
 112         has been encoded and all frames are ready to be dequeued and will
 113         set the ``V4L2_BUF_FLAG_LAST`` buffer flag on the last buffer of
 114         the capture queue to indicate there will be no new buffers
 115         produced to dequeue. This buffer may be empty, indicated by the
 116         driver setting the ``bytesused`` field to 0. Once the
 117         ``V4L2_BUF_FLAG_LAST`` flag was set, the
 118         :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore,
 119         but return an ``EPIPE`` error code.
 120     * - ``V4L2_ENC_CMD_PAUSE``
 121       - 2
 122       - Pause the encoder. When the encoder has not been started yet, the
 123         driver will return an ``EPERM`` error code. When the encoder is
 124         already paused, this command does nothing. No flags are defined
 125         for this command.
 126     * - ``V4L2_ENC_CMD_RESUME``
 127       - 3
 128       - Resume encoding after a PAUSE command. When the encoder has not
 129         been started yet, the driver will return an ``EPERM`` error code. When
 130         the encoder is already running, this command does nothing. No
 131         flags are defined for this command.
 132
 133
 134 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 135
 136 .. _encoder-flags:
 137
 138 .. flat-table:: Encoder Command Flags
 139     :header-rows:  0
 140     :stub-columns: 0
 141     :widths:       3 1 4
 142
 143     * - ``V4L2_ENC_CMD_STOP_AT_GOP_END``
 144       - 0x0001
 145       - Stop encoding at the end of the current *Group Of Pictures*,
 146         rather than immediately.
 147
 148
 149 Return Value
 150 ============
 151
 152 On success 0 is returned, on error -1 and the ``errno`` variable is set
 153 appropriately. The generic error codes are described at the
 154 :ref:`Generic Error Codes <gen-errors>` chapter.
 155
 156 EINVAL
 157     The ``cmd`` field is invalid.
 158
 159 EPERM
 160     The application sent a PAUSE or RESUME command when the encoder was
 161     not running.