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. Some commands use the
55``flags`` field for additional information.
56
57After a STOP command, :ref:`read() <func-read>` calls will read
58the remaining data buffered by the driver. When the buffer is empty,
59:ref:`read() <func-read>` will return zero and the next :ref:`read() <func-read>`
60call will restart the encoder.
61
62A :ref:`read() <func-read>` or :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
63call sends an implicit START command to the encoder if it has not been
64started yet. Applies to both queues of mem2mem encoders.
65
66A :ref:`close() <func-close>` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`
67call of a streaming file descriptor sends an implicit immediate STOP to
68the encoder, and all buffered data is discarded. Applies to both queues of
69mem2mem encoders.
70
71These ioctls are optional, not all drivers may support them. They were
72introduced in Linux 2.6.21. They are, however, mandatory for stateful mem2mem
73encoders (as further documented in :ref:`encoder`).
74
75
76.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
77
78.. c:type:: v4l2_encoder_cmd
79
80.. flat-table:: struct v4l2_encoder_cmd
81    :header-rows:  0
82    :stub-columns: 0
83    :widths:       1 1 2
84
85    * - __u32
86      - ``cmd``
87      - The encoder command, see :ref:`encoder-cmds`.
88    * - __u32
89      - ``flags``
90      - Flags to go with the command, see :ref:`encoder-flags`. If no
91	flags are defined for this command, drivers and applications must
92	set this field to zero.
93    * - __u32
94      - ``data``\ [8]
95      - Reserved for future extensions. Drivers and applications must set
96	the array to zero.
97
98
99
100.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
101
102.. _encoder-cmds:
103
104.. flat-table:: Encoder Commands
105    :header-rows:  0
106    :stub-columns: 0
107    :widths:       3 1 4
108
109    * - ``V4L2_ENC_CMD_START``
110      - 0
111      - Start the encoder. When the encoder is already running or paused,
112	this command does nothing. No flags are defined for this command.
113
114	For a device implementing the :ref:`encoder`, once the drain sequence
115	is initiated with the ``V4L2_ENC_CMD_STOP`` command, it must be driven
116	to completion before this command can be invoked.  Any attempt to
117	invoke the command while the drain sequence is in progress will trigger
118	an ``EBUSY`` error code. See :ref:`encoder` for more details.
119    * - ``V4L2_ENC_CMD_STOP``
120      - 1
121      - Stop the encoder. When the ``V4L2_ENC_CMD_STOP_AT_GOP_END`` flag
122	is set, encoding will continue until the end of the current *Group
123	Of Pictures*, otherwise encoding will stop immediately. When the
124	encoder is already stopped, this command does nothing.
125
126	For a device implementing the :ref:`encoder`, the command will initiate
127	the drain sequence as documented in :ref:`encoder`. No flags or other
128	arguments are accepted in this case. Any attempt to invoke the command
129	again before the sequence completes will trigger an ``EBUSY`` error
130	code.
131    * - ``V4L2_ENC_CMD_PAUSE``
132      - 2
133      - Pause the encoder. When the encoder has not been started yet, the
134	driver will return an ``EPERM`` error code. When the encoder is
135	already paused, this command does nothing. No flags are defined
136	for this command.
137    * - ``V4L2_ENC_CMD_RESUME``
138      - 3
139      - Resume encoding after a PAUSE command. When the encoder has not
140	been started yet, the driver will return an ``EPERM`` error code. When
141	the encoder is already running, this command does nothing. No
142	flags are defined for this command.
143
144
145.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
146
147.. _encoder-flags:
148
149.. flat-table:: Encoder Command Flags
150    :header-rows:  0
151    :stub-columns: 0
152    :widths:       3 1 4
153
154    * - ``V4L2_ENC_CMD_STOP_AT_GOP_END``
155      - 0x0001
156      - Stop encoding at the end of the current *Group Of Pictures*,
157	rather than immediately.
158
159        Does not apply to :ref:`encoder`.
160
161
162Return Value
163============
164
165On success 0 is returned, on error -1 and the ``errno`` variable is set
166appropriately. The generic error codes are described at the
167:ref:`Generic Error Codes <gen-errors>` chapter.
168
169EBUSY
170    A drain sequence of a device implementing the :ref:`encoder` is still in
171    progress. It is not allowed to issue another encoder command until it
172    completes.
173
174EINVAL
175    The ``cmd`` field is invalid.
176
177EPERM
178    The application sent a PAUSE or RESUME command when the encoder was
179    not running.
180