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