Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst

Source file repositories/reference/linux-study-clean/Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst

File Facts

System
Linux kernel
Corpus path
Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst
Extension
.rst
Size
5438 bytes
Lines
170
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _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:macro:: VIDIOC_ENCODER_CMD

``int ioctl(int fd, VIDIOC_ENCODER_CMD, struct v4l2_encoder_cmd *argp)``

.. c:macro:: VIDIOC_TRY_ENCODER_CMD

``int ioctl(int fd, VIDIOC_TRY_ENCODER_CMD, struct v4l2_encoder_cmd *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c: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. Some commands use the
``flags`` field for additional information.

After a STOP command, :c:func:`read()` calls will read
the remaining data buffered by the driver. When the buffer is empty,
:c:func:`read()` will return zero and the next :c:func:`read()`
call will restart the encoder.

A :c:func:`read()` or :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
call sends an implicit START command to the encoder if it has not been
started yet. Applies to both queues of mem2mem encoders.

A :c: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. Applies to both queues of
mem2mem encoders.

These ioctls are optional, not all drivers may support them. They were
introduced in Linux 2.6.21. They are, however, mandatory for stateful mem2mem
encoders (as further documented in :ref:`encoder`).

.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|

Annotation

Implementation Notes