diff options
Diffstat (limited to 'Documentation/media/uapi/v4l/vidioc-encoder-cmd.rst')
| -rw-r--r-- | Documentation/media/uapi/v4l/vidioc-encoder-cmd.rst | 168 |
1 files changed, 0 insertions, 168 deletions
diff --git a/Documentation/media/uapi/v4l/vidioc-encoder-cmd.rst b/Documentation/media/uapi/v4l/vidioc-encoder-cmd.rst deleted file mode 100644 index c313ca8b8cb5..000000000000 --- a/Documentation/media/uapi/v4l/vidioc-encoder-cmd.rst +++ /dev/null @@ -1,168 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDIOC_ENCODER_CMD: - -************************************************ -ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD -************************************************ - -Name -==== - -VIDIOC_ENCODER_CMD - VIDIOC_TRY_ENCODER_CMD - Execute an encoder command - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, VIDIOC_ENCODER_CMD, struct v4l2_encoder_cmd *argp ) - :name: VIDIOC_ENCODER_CMD - -.. c:function:: int ioctl( int fd, VIDIOC_TRY_ENCODER_CMD, struct v4l2_encoder_cmd *argp ) - :name: VIDIOC_TRY_ENCODER_CMD - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() <func-open>`. - -``argp`` - Pointer to struct :c:type:`v4l2_encoder_cmd`. - -Description -=========== - -These ioctls control an audio/video (usually MPEG-) encoder. -``VIDIOC_ENCODER_CMD`` sends a command to the encoder, -``VIDIOC_TRY_ENCODER_CMD`` can be used to try a command without actually -executing it. - -To send a command applications must initialize all fields of a struct -:c:type:`v4l2_encoder_cmd` and call -``VIDIOC_ENCODER_CMD`` or ``VIDIOC_TRY_ENCODER_CMD`` with a pointer to -this structure. - -The ``cmd`` field must contain the command code. The ``flags`` field is -currently only used by the STOP command and contains one bit: If the -``V4L2_ENC_CMD_STOP_AT_GOP_END`` flag is set, encoding will continue -until the end of the current *Group Of Pictures*, otherwise it will stop -immediately. - -A :ref:`read() <func-read>` or :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` -call sends an implicit START command to the encoder if it has not been -started yet. After a STOP command, :ref:`read() <func-read>` calls will read -the remaining data buffered by the driver. When the buffer is empty, -:ref:`read() <func-read>` will return zero and the next :ref:`read() <func-read>` -call will restart the encoder. - -A :ref:`close() <func-close>` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` -call of a streaming file descriptor sends an implicit immediate STOP to -the encoder, and all buffered data is discarded. - -These ioctls are optional, not all drivers may support them. They were -introduced in Linux 2.6.21. - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - -.. c:type:: v4l2_encoder_cmd - -.. flat-table:: struct v4l2_encoder_cmd - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u32 - - ``cmd`` - - The encoder command, see :ref:`encoder-cmds`. - * - __u32 - - ``flags`` - - Flags to go with the command, see :ref:`encoder-flags`. If no - flags are defined for this command, drivers and applications must - set this field to zero. - * - __u32 - - ``data``\ [8] - - Reserved for future extensions. Drivers and applications must set - the array to zero. - - - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| - -.. _encoder-cmds: - -.. flat-table:: Encoder Commands - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 4 - - * - ``V4L2_ENC_CMD_START`` - - 0 - - Start the encoder. When the encoder is already running or paused, - this command does nothing. No flags are defined for this command. - * - ``V4L2_ENC_CMD_STOP`` - - 1 - - Stop the encoder. When the ``V4L2_ENC_CMD_STOP_AT_GOP_END`` flag - is set, encoding will continue until the end of the current *Group - Of Pictures*, otherwise encoding will stop immediately. When the - encoder is already stopped, this command does nothing. mem2mem - encoders will send a ``V4L2_EVENT_EOS`` event when the last frame - has been encoded and all frames are ready to be dequeued and will - set the ``V4L2_BUF_FLAG_LAST`` buffer flag on the last buffer of - the capture queue to indicate there will be no new buffers - produced to dequeue. This buffer may be empty, indicated by the - driver setting the ``bytesused`` field to 0. Once the - ``V4L2_BUF_FLAG_LAST`` flag was set, the - :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore, - but return an ``EPIPE`` error code. - * - ``V4L2_ENC_CMD_PAUSE`` - - 2 - - Pause the encoder. When the encoder has not been started yet, the - driver will return an ``EPERM`` error code. When the encoder is - already paused, this command does nothing. No flags are defined - for this command. - * - ``V4L2_ENC_CMD_RESUME`` - - 3 - - Resume encoding after a PAUSE command. When the encoder has not - been started yet, the driver will return an ``EPERM`` error code. When - the encoder is already running, this command does nothing. No - flags are defined for this command. - - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| - -.. _encoder-flags: - -.. flat-table:: Encoder Command Flags - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 4 - - * - ``V4L2_ENC_CMD_STOP_AT_GOP_END`` - - 0x0001 - - Stop encoding at the end of the current *Group Of Pictures*, - rather than immediately. - - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. - -EINVAL - The ``cmd`` field is invalid. - -EPERM - The application sent a PAUSE or RESUME command when the encoder was - not running. |