diff options
Diffstat (limited to 'Documentation/media/uapi/v4l/vidioc-encoder-cmd.rst')
| -rw-r--r-- | Documentation/media/uapi/v4l/vidioc-encoder-cmd.rst | 195 |
1 files changed, 195 insertions, 0 deletions
diff --git a/Documentation/media/uapi/v4l/vidioc-encoder-cmd.rst b/Documentation/media/uapi/v4l/vidioc-encoder-cmd.rst new file mode 100644 index 000000000000..69bd9b4e0e56 --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-encoder-cmd.rst @@ -0,0 +1,195 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_ENCODER_CMD: + +************************************************ +ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD +************************************************ + +Name +==== + +VIDIOC_ENCODER_CMD - VIDIOC_TRY_ENCODER_CMD - Execute an encoder command + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_encoder_cmd *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD + +``argp`` + + +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 +:ref:`v4l2_encoder_cmd <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. + + +.. _v4l2-encoder-cmd: + +.. flat-table:: struct v4l2_encoder_cmd + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``cmd`` + + - The encoder command, see :ref:`encoder-cmds`. + + - .. row 2 + + - __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. + + - .. row 3 + + - __u32 + + - ``data``\ [8] + + - Reserved for future extensions. Drivers and applications must set + the array to zero. + + + +.. _encoder-cmds: + +.. flat-table:: Encoder Commands + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``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. + + - .. row 2 + + - ``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. + + - .. row 3 + + - ``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. + + - .. row 4 + + - ``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. + + + +.. _encoder-flags: + +.. flat-table:: Encoder Command Flags + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``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. |