1 .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1. 1 .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
2 2
3 .. _encoder: 3 .. _encoder:
4 4
5 ********************************************** 5 *************************************************
6 Memory-to-Memory Stateful Video Encoder Interf 6 Memory-to-Memory Stateful Video Encoder Interface
7 ********************************************** 7 *************************************************
8 8
9 A stateful video encoder takes raw video frame 9 A stateful video encoder takes raw video frames in display order and encodes
10 them into a bytestream. It generates complete 10 them into a bytestream. It generates complete chunks of the bytestream, including
11 all metadata, headers, etc. The resulting byte 11 all metadata, headers, etc. The resulting bytestream does not require any
12 further post-processing by the client. 12 further post-processing by the client.
13 13
14 Performing software stream processing, header 14 Performing software stream processing, header generation etc. in the driver
15 in order to support this interface is strongly 15 in order to support this interface is strongly discouraged. In case such
16 operations are needed, use of the Stateless Vi 16 operations are needed, use of the Stateless Video Encoder Interface (in
17 development) is strongly advised. 17 development) is strongly advised.
18 18
19 Conventions and Notations Used in This Documen 19 Conventions and Notations Used in This Document
20 ============================================== 20 ===============================================
21 21
22 1. The general V4L2 API rules apply if not spe 22 1. The general V4L2 API rules apply if not specified in this document
23 otherwise. 23 otherwise.
24 24
25 2. The meaning of words "must", "may", "should 25 2. The meaning of words "must", "may", "should", etc. is as per `RFC
26 2119 <https://tools.ietf.org/html/rfc2119>` 26 2119 <https://tools.ietf.org/html/rfc2119>`_.
27 27
28 3. All steps not marked "optional" are require 28 3. All steps not marked "optional" are required.
29 29
30 4. :c:func:`VIDIOC_G_EXT_CTRLS` and :c:func:`V 30 4. :c:func:`VIDIOC_G_EXT_CTRLS` and :c:func:`VIDIOC_S_EXT_CTRLS` may be used
31 interchangeably with :c:func:`VIDIOC_G_CTRL 31 interchangeably with :c:func:`VIDIOC_G_CTRL` and :c:func:`VIDIOC_S_CTRL`,
32 unless specified otherwise. 32 unless specified otherwise.
33 33
34 5. Single-planar API (see :ref:`planar-apis`) 34 5. Single-planar API (see :ref:`planar-apis`) and applicable structures may be
35 used interchangeably with multi-planar API, 35 used interchangeably with multi-planar API, unless specified otherwise,
36 depending on encoder capabilities and follo 36 depending on encoder capabilities and following the general V4L2 guidelines.
37 37
38 6. i = [a..b]: sequence of integers from a to 38 6. i = [a..b]: sequence of integers from a to b, inclusive, i.e. i =
39 [0..2]: i = 0, 1, 2. 39 [0..2]: i = 0, 1, 2.
40 40
41 7. Given an ``OUTPUT`` buffer A, then A' repre 41 7. Given an ``OUTPUT`` buffer A, then A' represents a buffer on the ``CAPTURE``
42 queue containing data that resulted from pr 42 queue containing data that resulted from processing buffer A.
43 43
44 Glossary 44 Glossary
45 ======== 45 ========
46 46
47 Refer to :ref:`decoder-glossary`. 47 Refer to :ref:`decoder-glossary`.
48 48
49 State Machine 49 State Machine
50 ============= 50 =============
51 51
52 .. kernel-render:: DOT 52 .. kernel-render:: DOT
53 :alt: DOT digraph of encoder state machine 53 :alt: DOT digraph of encoder state machine
54 :caption: Encoder State Machine 54 :caption: Encoder State Machine
55 55
56 digraph encoder_state_machine { 56 digraph encoder_state_machine {
57 node [shape = doublecircle, label="Enco 57 node [shape = doublecircle, label="Encoding"] Encoding;
58 58
59 node [shape = circle, label="Initializa 59 node [shape = circle, label="Initialization"] Initialization;
60 node [shape = circle, label="Stopped"] 60 node [shape = circle, label="Stopped"] Stopped;
61 node [shape = circle, label="Drain"] Dr 61 node [shape = circle, label="Drain"] Drain;
62 node [shape = circle, label="Reset"] Re 62 node [shape = circle, label="Reset"] Reset;
63 63
64 node [shape = point]; qi 64 node [shape = point]; qi
65 qi -> Initialization [ label = "open()" 65 qi -> Initialization [ label = "open()" ];
66 66
67 Initialization -> Encoding [ label = "B 67 Initialization -> Encoding [ label = "Both queues streaming" ];
68 68
69 Encoding -> Drain [ label = "V4L2_ENC_C 69 Encoding -> Drain [ label = "V4L2_ENC_CMD_STOP" ];
70 Encoding -> Reset [ label = "VIDIOC_STR 70 Encoding -> Reset [ label = "VIDIOC_STREAMOFF(CAPTURE)" ];
71 Encoding -> Stopped [ label = "VIDIOC_S 71 Encoding -> Stopped [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
72 Encoding -> Encoding; 72 Encoding -> Encoding;
73 73
74 Drain -> Stopped [ label = "All CAPTURE 74 Drain -> Stopped [ label = "All CAPTURE\nbuffers dequeued\nor\nVIDIOC_STREAMOFF(OUTPUT)" ];
75 Drain -> Reset [ label = "VIDIOC_STREAM 75 Drain -> Reset [ label = "VIDIOC_STREAMOFF(CAPTURE)" ];
76 76
77 Reset -> Encoding [ label = "VIDIOC_STR 77 Reset -> Encoding [ label = "VIDIOC_STREAMON(CAPTURE)" ];
78 Reset -> Initialization [ label = "VIDI 78 Reset -> Initialization [ label = "VIDIOC_REQBUFS(OUTPUT, 0)" ];
79 79
80 Stopped -> Encoding [ label = "V4L2_ENC 80 Stopped -> Encoding [ label = "V4L2_ENC_CMD_START\nor\nVIDIOC_STREAMON(OUTPUT)" ];
81 Stopped -> Reset [ label = "VIDIOC_STRE 81 Stopped -> Reset [ label = "VIDIOC_STREAMOFF(CAPTURE)" ];
82 } 82 }
83 83
84 Querying Capabilities 84 Querying Capabilities
85 ===================== 85 =====================
86 86
87 1. To enumerate the set of coded formats suppo 87 1. To enumerate the set of coded formats supported by the encoder, the
88 client may call :c:func:`VIDIOC_ENUM_FMT` o 88 client may call :c:func:`VIDIOC_ENUM_FMT` on ``CAPTURE``.
89 89
90 * The full set of supported formats will be 90 * The full set of supported formats will be returned, regardless of the
91 format set on ``OUTPUT``. 91 format set on ``OUTPUT``.
92 92
93 2. To enumerate the set of supported raw forma 93 2. To enumerate the set of supported raw formats, the client may call
94 :c:func:`VIDIOC_ENUM_FMT` on ``OUTPUT``. 94 :c:func:`VIDIOC_ENUM_FMT` on ``OUTPUT``.
95 95
96 * Only the formats supported for the format 96 * Only the formats supported for the format currently active on ``CAPTURE``
97 will be returned. 97 will be returned.
98 98
99 * In order to enumerate raw formats support 99 * In order to enumerate raw formats supported by a given coded format,
100 the client must first set that coded form 100 the client must first set that coded format on ``CAPTURE`` and then
101 enumerate the formats on ``OUTPUT``. 101 enumerate the formats on ``OUTPUT``.
102 102
103 3. The client may use :c:func:`VIDIOC_ENUM_FRA 103 3. The client may use :c:func:`VIDIOC_ENUM_FRAMESIZES` to detect supported
104 resolutions for a given format, passing the 104 resolutions for a given format, passing the desired pixel format in
105 :c:type:`v4l2_frmsizeenum` ``pixel_format`` 105 :c:type:`v4l2_frmsizeenum` ``pixel_format``.
106 106
107 * Values returned by :c:func:`VIDIOC_ENUM_F 107 * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a coded pixel
108 format will include all possible coded re 108 format will include all possible coded resolutions supported by the
109 encoder for the given coded pixel format. 109 encoder for the given coded pixel format.
110 110
111 * Values returned by :c:func:`VIDIOC_ENUM_F 111 * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a raw pixel format
112 will include all possible frame buffer re 112 will include all possible frame buffer resolutions supported by the
113 encoder for the given raw pixel format an 113 encoder for the given raw pixel format and coded format currently set on
114 ``CAPTURE``. 114 ``CAPTURE``.
115 115
116 4. The client may use :c:func:`VIDIOC_ENUM_FRA 116 4. The client may use :c:func:`VIDIOC_ENUM_FRAMEINTERVALS` to detect supported
117 frame intervals for a given format and reso 117 frame intervals for a given format and resolution, passing the desired pixel
118 format in :c:type:`v4l2_frmivalenum` ``pixe 118 format in :c:type:`v4l2_frmivalenum` ``pixel_format`` and the resolution
119 in :c:type:`v4l2_frmivalenum` ``width`` and 119 in :c:type:`v4l2_frmivalenum` ``width`` and :c:type:`v4l2_frmivalenum`
120 ``height``. 120 ``height``.
121 121
122 * Values returned by :c:func:`VIDIOC_ENUM_F 122 * Values returned by :c:func:`VIDIOC_ENUM_FRAMEINTERVALS` for a coded pixel
123 format and coded resolution will include 123 format and coded resolution will include all possible frame intervals
124 supported by the encoder for the given co 124 supported by the encoder for the given coded pixel format and resolution.
125 125
126 * Values returned by :c:func:`VIDIOC_ENUM_F 126 * Values returned by :c:func:`VIDIOC_ENUM_FRAMEINTERVALS` for a raw pixel
127 format and resolution will include all po 127 format and resolution will include all possible frame intervals supported
128 by the encoder for the given raw pixel fo 128 by the encoder for the given raw pixel format and resolution and for the
129 coded format, coded resolution and coded 129 coded format, coded resolution and coded frame interval currently set on
130 ``CAPTURE``. 130 ``CAPTURE``.
131 131
132 * Support for :c:func:`VIDIOC_ENUM_FRAMEINT 132 * Support for :c:func:`VIDIOC_ENUM_FRAMEINTERVALS` is optional. If it is
133 not implemented, then there are no specia 133 not implemented, then there are no special restrictions other than the
134 limits of the codec itself. 134 limits of the codec itself.
135 135
136 5. Supported profiles and levels for the coded 136 5. Supported profiles and levels for the coded format currently set on
137 ``CAPTURE``, if applicable, may be queried 137 ``CAPTURE``, if applicable, may be queried using their respective controls
138 via :c:func:`VIDIOC_QUERYCTRL`. 138 via :c:func:`VIDIOC_QUERYCTRL`.
139 139
140 6. Any additional encoder capabilities may be 140 6. Any additional encoder capabilities may be discovered by querying
141 their respective controls. 141 their respective controls.
142 142
143 Initialization 143 Initialization
144 ============== 144 ==============
145 145
146 1. Set the coded format on the ``CAPTURE`` que 146 1. Set the coded format on the ``CAPTURE`` queue via :c:func:`VIDIOC_S_FMT`.
147 147
148 * **Required fields:** 148 * **Required fields:**
149 149
150 ``type`` 150 ``type``
151 a ``V4L2_BUF_TYPE_*`` enum appropriat 151 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
152 152
153 ``pixelformat`` 153 ``pixelformat``
154 the coded format to be produced. 154 the coded format to be produced.
155 155
156 ``sizeimage`` 156 ``sizeimage``
157 desired size of ``CAPTURE`` buffers; 157 desired size of ``CAPTURE`` buffers; the encoder may adjust it to
158 match hardware requirements. 158 match hardware requirements.
159 159
160 ``width``, ``height`` 160 ``width``, ``height``
161 ignored (read-only). 161 ignored (read-only).
162 162
163 other fields 163 other fields
164 follow standard semantics. 164 follow standard semantics.
165 165
166 * **Returned fields:** 166 * **Returned fields:**
167 167
168 ``sizeimage`` 168 ``sizeimage``
169 adjusted size of ``CAPTURE`` buffers. 169 adjusted size of ``CAPTURE`` buffers.
170 170
171 ``width``, ``height`` 171 ``width``, ``height``
172 the coded size selected by the encode 172 the coded size selected by the encoder based on current state, e.g.
173 ``OUTPUT`` format, selection rectangl 173 ``OUTPUT`` format, selection rectangles, etc. (read-only).
174 174
175 .. important:: 175 .. important::
176 176
177 Changing the ``CAPTURE`` format may chan 177 Changing the ``CAPTURE`` format may change the currently set ``OUTPUT``
178 format. How the new ``OUTPUT`` format is 178 format. How the new ``OUTPUT`` format is determined is up to the encoder
179 and the client must ensure it matches it 179 and the client must ensure it matches its needs afterwards.
180 180
181 2. **Optional.** Enumerate supported ``OUTPUT` 181 2. **Optional.** Enumerate supported ``OUTPUT`` formats (raw formats for
182 source) for the selected coded format via : 182 source) for the selected coded format via :c:func:`VIDIOC_ENUM_FMT`.
183 183
184 * **Required fields:** 184 * **Required fields:**
185 185
186 ``type`` 186 ``type``
187 a ``V4L2_BUF_TYPE_*`` enum appropriat 187 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
188 188
189 other fields 189 other fields
190 follow standard semantics. 190 follow standard semantics.
191 191
192 * **Returned fields:** 192 * **Returned fields:**
193 193
194 ``pixelformat`` 194 ``pixelformat``
195 raw format supported for the coded fo 195 raw format supported for the coded format currently selected on
196 the ``CAPTURE`` queue. 196 the ``CAPTURE`` queue.
197 197
198 other fields 198 other fields
199 follow standard semantics. 199 follow standard semantics.
200 200
201 3. Set the raw source format on the ``OUTPUT`` 201 3. Set the raw source format on the ``OUTPUT`` queue via
202 :c:func:`VIDIOC_S_FMT`. 202 :c:func:`VIDIOC_S_FMT`.
203 203
204 * **Required fields:** 204 * **Required fields:**
205 205
206 ``type`` 206 ``type``
207 a ``V4L2_BUF_TYPE_*`` enum appropriat 207 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
208 208
209 ``pixelformat`` 209 ``pixelformat``
210 raw format of the source. 210 raw format of the source.
211 211
212 ``width``, ``height`` 212 ``width``, ``height``
213 source resolution. 213 source resolution.
214 214
215 other fields 215 other fields
216 follow standard semantics. 216 follow standard semantics.
217 217
218 * **Returned fields:** 218 * **Returned fields:**
219 219
220 ``width``, ``height`` 220 ``width``, ``height``
221 may be adjusted to match encoder mini 221 may be adjusted to match encoder minimums, maximums and alignment
222 requirements, as required by the curr 222 requirements, as required by the currently selected formats, as
223 reported by :c:func:`VIDIOC_ENUM_FRAM 223 reported by :c:func:`VIDIOC_ENUM_FRAMESIZES`.
224 224
225 other fields 225 other fields
226 follow standard semantics. 226 follow standard semantics.
227 227
228 * Setting the ``OUTPUT`` format will reset 228 * Setting the ``OUTPUT`` format will reset the selection rectangles to their
229 default values, based on the new resoluti 229 default values, based on the new resolution, as described in the next
230 step. 230 step.
231 231
232 4. Set the raw frame interval on the ``OUTPUT` 232 4. Set the raw frame interval on the ``OUTPUT`` queue via
233 :c:func:`VIDIOC_S_PARM`. This also sets the 233 :c:func:`VIDIOC_S_PARM`. This also sets the coded frame interval on the
234 ``CAPTURE`` queue to the same value. 234 ``CAPTURE`` queue to the same value.
235 235
236 * **Required fields:** 236 * **Required fields:**
237 237
238 ``type`` 238 ``type``
239 a ``V4L2_BUF_TYPE_*`` enum appropriat 239 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
240 240
241 ``parm.output`` 241 ``parm.output``
242 set all fields except ``parm.output.t 242 set all fields except ``parm.output.timeperframe`` to 0.
243 243
244 ``parm.output.timeperframe`` 244 ``parm.output.timeperframe``
245 the desired frame interval; the encod 245 the desired frame interval; the encoder may adjust it to
246 match hardware requirements. 246 match hardware requirements.
247 247
248 * **Returned fields:** 248 * **Returned fields:**
249 249
250 ``parm.output.timeperframe`` 250 ``parm.output.timeperframe``
251 the adjusted frame interval. 251 the adjusted frame interval.
252 252
253 .. important:: 253 .. important::
254 254
255 Changing the ``OUTPUT`` frame interval * 255 Changing the ``OUTPUT`` frame interval *also* sets the framerate that
256 the encoder uses to encode the video. So 256 the encoder uses to encode the video. So setting the frame interval
257 to 1/24 (or 24 frames per second) will p 257 to 1/24 (or 24 frames per second) will produce a coded video stream
258 that can be played back at that speed. T 258 that can be played back at that speed. The frame interval for the
259 ``OUTPUT`` queue is just a hint, the app 259 ``OUTPUT`` queue is just a hint, the application may provide raw
260 frames at a different rate. It can be us 260 frames at a different rate. It can be used by the driver to help
261 schedule multiple encoders running in pa 261 schedule multiple encoders running in parallel.
262 262
263 In the next step the ``CAPTURE`` frame i 263 In the next step the ``CAPTURE`` frame interval can optionally be
264 changed to a different value. This is us 264 changed to a different value. This is useful for off-line encoding
265 were the coded frame interval can be dif 265 were the coded frame interval can be different from the rate at
266 which raw frames are supplied. 266 which raw frames are supplied.
267 267
268 .. important:: 268 .. important::
269 269
270 ``timeperframe`` deals with *frames*, no 270 ``timeperframe`` deals with *frames*, not fields. So for interlaced
271 formats this is the time per two fields, 271 formats this is the time per two fields, since a frame consists of
272 a top and a bottom field. 272 a top and a bottom field.
273 273
274 .. note:: 274 .. note::
275 275
276 It is due to historical reasons that cha 276 It is due to historical reasons that changing the ``OUTPUT`` frame
277 interval also changes the coded frame in 277 interval also changes the coded frame interval on the ``CAPTURE``
278 queue. Ideally these would be independen 278 queue. Ideally these would be independent settings, but that would
279 break the existing API. 279 break the existing API.
280 280
281 5. **Optional** Set the coded frame interval o 281 5. **Optional** Set the coded frame interval on the ``CAPTURE`` queue via
282 :c:func:`VIDIOC_S_PARM`. This is only neces 282 :c:func:`VIDIOC_S_PARM`. This is only necessary if the coded frame
283 interval is different from the raw frame in 283 interval is different from the raw frame interval, which is typically
284 the case for off-line encoding. Support for 284 the case for off-line encoding. Support for this feature is signalled
285 by the :ref:`V4L2_FMT_FLAG_ENC_CAP_FRAME_IN 285 by the :ref:`V4L2_FMT_FLAG_ENC_CAP_FRAME_INTERVAL <fmtdesc-flags>` format flag.
286 286
287 * **Required fields:** 287 * **Required fields:**
288 288
289 ``type`` 289 ``type``
290 a ``V4L2_BUF_TYPE_*`` enum appropriat 290 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
291 291
292 ``parm.capture`` 292 ``parm.capture``
293 set all fields except ``parm.capture. 293 set all fields except ``parm.capture.timeperframe`` to 0.
294 294
295 ``parm.capture.timeperframe`` 295 ``parm.capture.timeperframe``
296 the desired coded frame interval; the 296 the desired coded frame interval; the encoder may adjust it to
297 match hardware requirements. 297 match hardware requirements.
298 298
299 * **Returned fields:** 299 * **Returned fields:**
300 300
301 ``parm.capture.timeperframe`` 301 ``parm.capture.timeperframe``
302 the adjusted frame interval. 302 the adjusted frame interval.
303 303
304 .. important:: 304 .. important::
305 305
306 Changing the ``CAPTURE`` frame interval 306 Changing the ``CAPTURE`` frame interval sets the framerate for the
307 coded video. It does *not* set the rate 307 coded video. It does *not* set the rate at which buffers arrive on the
308 ``CAPTURE`` queue, that depends on how f 308 ``CAPTURE`` queue, that depends on how fast the encoder is and how
309 fast raw frames are queued on the ``OUTP 309 fast raw frames are queued on the ``OUTPUT`` queue.
310 310
311 .. important:: 311 .. important::
312 312
313 ``timeperframe`` deals with *frames*, no 313 ``timeperframe`` deals with *frames*, not fields. So for interlaced
314 formats this is the time per two fields, 314 formats this is the time per two fields, since a frame consists of
315 a top and a bottom field. 315 a top and a bottom field.
316 316
317 .. note:: 317 .. note::
318 318
319 Not all drivers support this functionali 319 Not all drivers support this functionality, in that case just set
320 the desired coded frame interval for the 320 the desired coded frame interval for the ``OUTPUT`` queue.
321 321
322 However, drivers that can schedule multi 322 However, drivers that can schedule multiple encoders based on the
323 ``OUTPUT`` frame interval must support t 323 ``OUTPUT`` frame interval must support this optional feature.
324 324
325 6. **Optional.** Set the visible resolution fo 325 6. **Optional.** Set the visible resolution for the stream metadata via
326 :c:func:`VIDIOC_S_SELECTION` on the ``OUTPU 326 :c:func:`VIDIOC_S_SELECTION` on the ``OUTPUT`` queue if it is desired
327 to be different than the full OUTPUT resolu 327 to be different than the full OUTPUT resolution.
328 328
329 * **Required fields:** 329 * **Required fields:**
330 330
331 ``type`` 331 ``type``
332 a ``V4L2_BUF_TYPE_*`` enum appropriat 332 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
333 333
334 ``target`` 334 ``target``
335 set to ``V4L2_SEL_TGT_CROP``. 335 set to ``V4L2_SEL_TGT_CROP``.
336 336
337 ``r.left``, ``r.top``, ``r.width``, ``r.h 337 ``r.left``, ``r.top``, ``r.width``, ``r.height``
338 visible rectangle; this must fit with 338 visible rectangle; this must fit within the `V4L2_SEL_TGT_CROP_BOUNDS`
339 rectangle and may be subject to adjus 339 rectangle and may be subject to adjustment to match codec and
340 hardware constraints. 340 hardware constraints.
341 341
342 * **Returned fields:** 342 * **Returned fields:**
343 343
344 ``r.left``, ``r.top``, ``r.width``, ``r.h 344 ``r.left``, ``r.top``, ``r.width``, ``r.height``
345 visible rectangle adjusted by the enc 345 visible rectangle adjusted by the encoder.
346 346
347 * The following selection targets are suppo 347 * The following selection targets are supported on ``OUTPUT``:
348 348
349 ``V4L2_SEL_TGT_CROP_BOUNDS`` 349 ``V4L2_SEL_TGT_CROP_BOUNDS``
350 equal to the full source frame, match 350 equal to the full source frame, matching the active ``OUTPUT``
351 format. 351 format.
352 352
353 ``V4L2_SEL_TGT_CROP_DEFAULT`` 353 ``V4L2_SEL_TGT_CROP_DEFAULT``
354 equal to ``V4L2_SEL_TGT_CROP_BOUNDS`` 354 equal to ``V4L2_SEL_TGT_CROP_BOUNDS``.
355 355
356 ``V4L2_SEL_TGT_CROP`` 356 ``V4L2_SEL_TGT_CROP``
357 rectangle within the source buffer to 357 rectangle within the source buffer to be encoded into the
358 ``CAPTURE`` stream; defaults to ``V4L 358 ``CAPTURE`` stream; defaults to ``V4L2_SEL_TGT_CROP_DEFAULT``.
359 359
360 .. note:: 360 .. note::
361 361
362 A common use case for this selecti 362 A common use case for this selection target is encoding a source
363 video with a resolution that is no 363 video with a resolution that is not a multiple of a macroblock,
364 e.g. the common 1920x1080 resolut 364 e.g. the common 1920x1080 resolution may require the source
365 buffers to be aligned to 1920x1088 365 buffers to be aligned to 1920x1088 for codecs with 16x16 macroblock
366 size. To avoid encoding the paddin 366 size. To avoid encoding the padding, the client needs to explicitly
367 configure this selection target to 367 configure this selection target to 1920x1080.
368 368
369 .. warning:: 369 .. warning::
370 370
371 The encoder may adjust the crop/compose 371 The encoder may adjust the crop/compose rectangles to the nearest
372 supported ones to meet codec and hardwar 372 supported ones to meet codec and hardware requirements. The client needs
373 to check the adjusted rectangle returned 373 to check the adjusted rectangle returned by :c:func:`VIDIOC_S_SELECTION`.
374 374
375 7. Allocate buffers for both ``OUTPUT`` and `` 375 7. Allocate buffers for both ``OUTPUT`` and ``CAPTURE`` via
376 :c:func:`VIDIOC_REQBUFS`. This may be perfo 376 :c:func:`VIDIOC_REQBUFS`. This may be performed in any order.
377 377
378 * **Required fields:** 378 * **Required fields:**
379 379
380 ``count`` 380 ``count``
381 requested number of buffers to alloca 381 requested number of buffers to allocate; greater than zero.
382 382
383 ``type`` 383 ``type``
384 a ``V4L2_BUF_TYPE_*`` enum appropriat 384 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT`` or
385 ``CAPTURE``. 385 ``CAPTURE``.
386 386
387 other fields 387 other fields
388 follow standard semantics. 388 follow standard semantics.
389 389
390 * **Returned fields:** 390 * **Returned fields:**
391 391
392 ``count`` 392 ``count``
393 actual number of buffers allocated. 393 actual number of buffers allocated.
394 394
395 .. warning:: 395 .. warning::
396 396
397 The actual number of allocated buffers m 397 The actual number of allocated buffers may differ from the ``count``
398 given. The client must check the updated 398 given. The client must check the updated value of ``count`` after the
399 call returns. 399 call returns.
400 400
401 .. note:: 401 .. note::
402 402
403 To allocate more than the minimum number 403 To allocate more than the minimum number of OUTPUT buffers (for pipeline
404 depth), the client may query the ``V4L2_ 404 depth), the client may query the ``V4L2_CID_MIN_BUFFERS_FOR_OUTPUT``
405 control to get the minimum number of buf 405 control to get the minimum number of buffers required, and pass the
406 obtained value plus the number of additi 406 obtained value plus the number of additional buffers needed in the
407 ``count`` field to :c:func:`VIDIOC_REQBU 407 ``count`` field to :c:func:`VIDIOC_REQBUFS`.
408 408
409 Alternatively, :c:func:`VIDIOC_CREATE_BUFS` 409 Alternatively, :c:func:`VIDIOC_CREATE_BUFS` can be used to have more
410 control over buffer allocation. 410 control over buffer allocation.
411 411
412 * **Required fields:** 412 * **Required fields:**
413 413
414 ``count`` 414 ``count``
415 requested number of buffers to alloca 415 requested number of buffers to allocate; greater than zero.
416 416
417 ``type`` 417 ``type``
418 a ``V4L2_BUF_TYPE_*`` enum appropriat 418 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
419 419
420 other fields 420 other fields
421 follow standard semantics. 421 follow standard semantics.
422 422
423 * **Returned fields:** 423 * **Returned fields:**
424 424
425 ``count`` 425 ``count``
426 adjusted to the number of allocated b 426 adjusted to the number of allocated buffers.
427 427
428 8. Begin streaming on both ``OUTPUT`` and ``CA 428 8. Begin streaming on both ``OUTPUT`` and ``CAPTURE`` queues via
429 :c:func:`VIDIOC_STREAMON`. This may be perf 429 :c:func:`VIDIOC_STREAMON`. This may be performed in any order. The actual
430 encoding process starts when both queues st 430 encoding process starts when both queues start streaming.
431 431
432 .. note:: 432 .. note::
433 433
434 If the client stops the ``CAPTURE`` queue d 434 If the client stops the ``CAPTURE`` queue during the encode process and then
435 restarts it again, the encoder will begin g 435 restarts it again, the encoder will begin generating a stream independent
436 from the stream generated before the stop. 436 from the stream generated before the stop. The exact constraints depend
437 on the coded format, but may include the fo 437 on the coded format, but may include the following implications:
438 438
439 * encoded frames produced after the restart 439 * encoded frames produced after the restart must not reference any
440 frames produced before the stop, e.g. no 440 frames produced before the stop, e.g. no long term references for
441 H.264/HEVC, 441 H.264/HEVC,
442 442
443 * any headers that must be included in a st 443 * any headers that must be included in a standalone stream must be
444 produced again, e.g. SPS and PPS for H.26 444 produced again, e.g. SPS and PPS for H.264/HEVC.
445 445
446 Encoding 446 Encoding
447 ======== 447 ========
448 448
449 This state is reached after the `Initializatio 449 This state is reached after the `Initialization` sequence finishes
450 successfully. In this state, the client queue 450 successfully. In this state, the client queues and dequeues buffers to both
451 queues via :c:func:`VIDIOC_QBUF` and :c:func:` 451 queues via :c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`, following the
452 standard semantics. 452 standard semantics.
453 453
454 The content of encoded ``CAPTURE`` buffers dep 454 The content of encoded ``CAPTURE`` buffers depends on the active coded pixel
455 format and may be affected by codec-specific e 455 format and may be affected by codec-specific extended controls, as stated
456 in the documentation of each format. 456 in the documentation of each format.
457 457
458 Both queues operate independently, following s 458 Both queues operate independently, following standard behavior of V4L2 buffer
459 queues and memory-to-memory devices. In additi 459 queues and memory-to-memory devices. In addition, the order of encoded frames
460 dequeued from the ``CAPTURE`` queue may differ 460 dequeued from the ``CAPTURE`` queue may differ from the order of queuing raw
461 frames to the ``OUTPUT`` queue, due to propert 461 frames to the ``OUTPUT`` queue, due to properties of the selected coded format,
462 e.g. frame reordering. 462 e.g. frame reordering.
463 463
464 The client must not assume any direct relation 464 The client must not assume any direct relationship between ``CAPTURE`` and
465 ``OUTPUT`` buffers and any specific timing of 465 ``OUTPUT`` buffers and any specific timing of buffers becoming
466 available to dequeue. Specifically: 466 available to dequeue. Specifically:
467 467
468 * a buffer queued to ``OUTPUT`` may result in 468 * a buffer queued to ``OUTPUT`` may result in more than one buffer produced on
469 ``CAPTURE`` (for example, if returning an en 469 ``CAPTURE`` (for example, if returning an encoded frame allowed the encoder
470 to return a frame that preceded it in displa 470 to return a frame that preceded it in display, but succeeded it in the decode
471 order; however, there may be other reasons f 471 order; however, there may be other reasons for this as well),
472 472
473 * a buffer queued to ``OUTPUT`` may result in 473 * a buffer queued to ``OUTPUT`` may result in a buffer being produced on
474 ``CAPTURE`` later into encode process, and/o 474 ``CAPTURE`` later into encode process, and/or after processing further
475 ``OUTPUT`` buffers, or be returned out of or 475 ``OUTPUT`` buffers, or be returned out of order, e.g. if display
476 reordering is used, 476 reordering is used,
477 477
478 * buffers may become available on the ``CAPTUR 478 * buffers may become available on the ``CAPTURE`` queue without additional
479 buffers queued to ``OUTPUT`` (e.g. during dr 479 buffers queued to ``OUTPUT`` (e.g. during drain or ``EOS``), because of the
480 ``OUTPUT`` buffers queued in the past whose 480 ``OUTPUT`` buffers queued in the past whose encoding results are only
481 available at later time, due to specifics of 481 available at later time, due to specifics of the encoding process,
482 482
483 * buffers queued to ``OUTPUT`` may not become 483 * buffers queued to ``OUTPUT`` may not become available to dequeue instantly
484 after being encoded into a corresponding ``C 484 after being encoded into a corresponding ``CAPTURE`` buffer, e.g. if the
485 encoder needs to use the frame as a referenc 485 encoder needs to use the frame as a reference for encoding further frames.
486 486
487 .. note:: 487 .. note::
488 488
489 To allow matching encoded ``CAPTURE`` buffe 489 To allow matching encoded ``CAPTURE`` buffers with ``OUTPUT`` buffers they
490 originated from, the client can set the ``t 490 originated from, the client can set the ``timestamp`` field of the
491 :c:type:`v4l2_buffer` struct when queuing a 491 :c:type:`v4l2_buffer` struct when queuing an ``OUTPUT`` buffer. The
492 ``CAPTURE`` buffer(s), which resulted from 492 ``CAPTURE`` buffer(s), which resulted from encoding that ``OUTPUT`` buffer
493 will have their ``timestamp`` field set to 493 will have their ``timestamp`` field set to the same value when dequeued.
494 494
495 In addition to the straightforward case of 495 In addition to the straightforward case of one ``OUTPUT`` buffer producing
496 one ``CAPTURE`` buffer, the following cases 496 one ``CAPTURE`` buffer, the following cases are defined:
497 497
498 * one ``OUTPUT`` buffer generates multiple 498 * one ``OUTPUT`` buffer generates multiple ``CAPTURE`` buffers: the same
499 ``OUTPUT`` timestamp will be copied to mu 499 ``OUTPUT`` timestamp will be copied to multiple ``CAPTURE`` buffers,
500 500
501 * the encoding order differs from the prese 501 * the encoding order differs from the presentation order (i.e. the
502 ``CAPTURE`` buffers are out-of-order comp 502 ``CAPTURE`` buffers are out-of-order compared to the ``OUTPUT`` buffers):
503 ``CAPTURE`` timestamps will not retain th 503 ``CAPTURE`` timestamps will not retain the order of ``OUTPUT`` timestamps.
504 504
505 .. note:: 505 .. note::
506 506
507 To let the client distinguish between frame 507 To let the client distinguish between frame types (keyframes, intermediate
508 frames; the exact list of types depends on 508 frames; the exact list of types depends on the coded format), the
509 ``CAPTURE`` buffers will have corresponding 509 ``CAPTURE`` buffers will have corresponding flag bits set in their
510 :c:type:`v4l2_buffer` struct when dequeued. 510 :c:type:`v4l2_buffer` struct when dequeued. See the documentation of
511 :c:type:`v4l2_buffer` and each coded pixel 511 :c:type:`v4l2_buffer` and each coded pixel format for exact list of flags
512 and their meanings. 512 and their meanings.
513 513
514 Should an encoding error occur, it will be rep 514 Should an encoding error occur, it will be reported to the client with the level
515 of details depending on the encoder capabiliti 515 of details depending on the encoder capabilities. Specifically:
516 516
517 * the ``CAPTURE`` buffer (if any) that contain 517 * the ``CAPTURE`` buffer (if any) that contains the results of the failed encode
518 operation will be returned with the ``V4L2_B 518 operation will be returned with the ``V4L2_BUF_FLAG_ERROR`` flag set,
519 519
520 * if the encoder is able to precisely report t 520 * if the encoder is able to precisely report the ``OUTPUT`` buffer(s) that triggered
521 the error, such buffer(s) will be returned w 521 the error, such buffer(s) will be returned with the ``V4L2_BUF_FLAG_ERROR`` flag
522 set. 522 set.
523 523
524 .. note:: 524 .. note::
525 525
526 If a ``CAPTURE`` buffer is too small then i 526 If a ``CAPTURE`` buffer is too small then it is just returned with the
527 ``V4L2_BUF_FLAG_ERROR`` flag set. More work 527 ``V4L2_BUF_FLAG_ERROR`` flag set. More work is needed to detect that this
528 error occurred because the buffer was too s 528 error occurred because the buffer was too small, and to provide support to
529 free existing buffers that were too small. 529 free existing buffers that were too small.
530 530
531 In case of a fatal failure that does not allow 531 In case of a fatal failure that does not allow the encoding to continue, any
532 further operations on corresponding encoder fi 532 further operations on corresponding encoder file handle will return the -EIO
533 error code. The client may close the file hand 533 error code. The client may close the file handle and open a new one, or
534 alternatively reinitialize the instance by sto 534 alternatively reinitialize the instance by stopping streaming on both queues,
535 releasing all buffers and performing the Initi 535 releasing all buffers and performing the Initialization sequence again.
536 536
537 Encoding Parameter Changes 537 Encoding Parameter Changes
538 ========================== 538 ==========================
539 539
540 The client is allowed to use :c:func:`VIDIOC_S 540 The client is allowed to use :c:func:`VIDIOC_S_CTRL` to change encoder
541 parameters at any time. The availability of pa 541 parameters at any time. The availability of parameters is encoder-specific
542 and the client must query the encoder to find 542 and the client must query the encoder to find the set of available controls.
543 543
544 The ability to change each parameter during en 544 The ability to change each parameter during encoding is encoder-specific, as
545 per the standard semantics of the V4L2 control 545 per the standard semantics of the V4L2 control interface. The client may
546 attempt to set a control during encoding and i 546 attempt to set a control during encoding and if the operation fails with the
547 -EBUSY error code, the ``CAPTURE`` queue needs 547 -EBUSY error code, the ``CAPTURE`` queue needs to be stopped for the
548 configuration change to be allowed. To do this 548 configuration change to be allowed. To do this, it may follow the `Drain`
549 sequence to avoid losing the already queued/en 549 sequence to avoid losing the already queued/encoded frames.
550 550
551 The timing of parameter updates is encoder-spe 551 The timing of parameter updates is encoder-specific, as per the standard
552 semantics of the V4L2 control interface. If th 552 semantics of the V4L2 control interface. If the client needs to apply the
553 parameters exactly at specific frame, using th 553 parameters exactly at specific frame, using the Request API
554 (:ref:`media-request-api`) should be considere 554 (:ref:`media-request-api`) should be considered, if supported by the encoder.
555 555
556 Drain 556 Drain
557 ===== 557 =====
558 558
559 To ensure that all the queued ``OUTPUT`` buffe 559 To ensure that all the queued ``OUTPUT`` buffers have been processed and the
560 related ``CAPTURE`` buffers are given to the c 560 related ``CAPTURE`` buffers are given to the client, the client must follow the
561 drain sequence described below. After the drai 561 drain sequence described below. After the drain sequence ends, the client has
562 received all encoded frames for all ``OUTPUT`` 562 received all encoded frames for all ``OUTPUT`` buffers queued before the
563 sequence was started. 563 sequence was started.
564 564
565 1. Begin the drain sequence by issuing :c:func 565 1. Begin the drain sequence by issuing :c:func:`VIDIOC_ENCODER_CMD`.
566 566
567 * **Required fields:** 567 * **Required fields:**
568 568
569 ``cmd`` 569 ``cmd``
570 set to ``V4L2_ENC_CMD_STOP``. 570 set to ``V4L2_ENC_CMD_STOP``.
571 571
572 ``flags`` 572 ``flags``
573 set to 0. 573 set to 0.
574 574
575 ``pts`` 575 ``pts``
576 set to 0. 576 set to 0.
577 577
578 .. warning:: 578 .. warning::
579 579
580 The sequence can be only initiated if bo 580 The sequence can be only initiated if both ``OUTPUT`` and ``CAPTURE``
581 queues are streaming. For compatibility 581 queues are streaming. For compatibility reasons, the call to
582 :c:func:`VIDIOC_ENCODER_CMD` will not fa 582 :c:func:`VIDIOC_ENCODER_CMD` will not fail even if any of the queues is
583 not streaming, but at the same time it w 583 not streaming, but at the same time it will not initiate the `Drain`
584 sequence and so the steps described belo 584 sequence and so the steps described below would not be applicable.
585 585
586 2. Any ``OUTPUT`` buffers queued by the client 586 2. Any ``OUTPUT`` buffers queued by the client before the
587 :c:func:`VIDIOC_ENCODER_CMD` was issued wil 587 :c:func:`VIDIOC_ENCODER_CMD` was issued will be processed and encoded as
588 normal. The client must continue to handle 588 normal. The client must continue to handle both queues independently,
589 similarly to normal encode operation. This 589 similarly to normal encode operation. This includes:
590 590
591 * queuing and dequeuing ``CAPTURE`` buffers 591 * queuing and dequeuing ``CAPTURE`` buffers, until a buffer marked with the
592 ``V4L2_BUF_FLAG_LAST`` flag is dequeued, 592 ``V4L2_BUF_FLAG_LAST`` flag is dequeued,
593 593
594 .. warning:: 594 .. warning::
595 595
596 The last buffer may be empty (with :c: 596 The last buffer may be empty (with :c:type:`v4l2_buffer`
597 ``bytesused`` = 0) and in that case it 597 ``bytesused`` = 0) and in that case it must be ignored by the client,
598 as it does not contain an encoded fram 598 as it does not contain an encoded frame.
599 599
600 .. note:: 600 .. note::
601 601
602 Any attempt to dequeue more ``CAPTURE` 602 Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer
603 marked with ``V4L2_BUF_FLAG_LAST`` wil 603 marked with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from
604 :c:func:`VIDIOC_DQBUF`. 604 :c:func:`VIDIOC_DQBUF`.
605 605
606 * dequeuing processed ``OUTPUT`` buffers, u 606 * dequeuing processed ``OUTPUT`` buffers, until all the buffers queued
607 before the ``V4L2_ENC_CMD_STOP`` command 607 before the ``V4L2_ENC_CMD_STOP`` command are dequeued,
608 608
609 * dequeuing the ``V4L2_EVENT_EOS`` event, i 609 * dequeuing the ``V4L2_EVENT_EOS`` event, if the client subscribes to it.
610 610
611 .. note:: 611 .. note::
612 612
613 For backwards compatibility, the encoder 613 For backwards compatibility, the encoder will signal a ``V4L2_EVENT_EOS``
614 event when the last frame has been encod 614 event when the last frame has been encoded and all frames are ready to be
615 dequeued. It is deprecated behavior and 615 dequeued. It is deprecated behavior and the client must not rely on it.
616 The ``V4L2_BUF_FLAG_LAST`` buffer flag s 616 The ``V4L2_BUF_FLAG_LAST`` buffer flag should be used instead.
617 617
618 3. Once all ``OUTPUT`` buffers queued before t 618 3. Once all ``OUTPUT`` buffers queued before the ``V4L2_ENC_CMD_STOP`` call are
619 dequeued and the last ``CAPTURE`` buffer is 619 dequeued and the last ``CAPTURE`` buffer is dequeued, the encoder is stopped
620 and it will accept, but not process any new 620 and it will accept, but not process any newly queued ``OUTPUT`` buffers
621 until the client issues any of the followin 621 until the client issues any of the following operations:
622 622
623 * ``V4L2_ENC_CMD_START`` - the encoder will 623 * ``V4L2_ENC_CMD_START`` - the encoder will not be reset and will resume
624 operation normally, with all the state fr 624 operation normally, with all the state from before the drain,
625 625
626 * a pair of :c:func:`VIDIOC_STREAMOFF` and 626 * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
627 ``CAPTURE`` queue - the encoder will be r 627 ``CAPTURE`` queue - the encoder will be reset (see the `Reset` sequence)
628 and then resume encoding, 628 and then resume encoding,
629 629
630 * a pair of :c:func:`VIDIOC_STREAMOFF` and 630 * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
631 ``OUTPUT`` queue - the encoder will resum 631 ``OUTPUT`` queue - the encoder will resume operation normally, however any
632 source frames queued to the ``OUTPUT`` qu 632 source frames queued to the ``OUTPUT`` queue between ``V4L2_ENC_CMD_STOP``
633 and :c:func:`VIDIOC_STREAMOFF` will be di 633 and :c:func:`VIDIOC_STREAMOFF` will be discarded.
634 634
635 .. note:: 635 .. note::
636 636
637 Once the drain sequence is initiated, the c 637 Once the drain sequence is initiated, the client needs to drive it to
638 completion, as described by the steps above 638 completion, as described by the steps above, unless it aborts the process by
639 issuing :c:func:`VIDIOC_STREAMOFF` on any o 639 issuing :c:func:`VIDIOC_STREAMOFF` on any of the ``OUTPUT`` or ``CAPTURE``
640 queues. The client is not allowed to issue 640 queues. The client is not allowed to issue ``V4L2_ENC_CMD_START`` or
641 ``V4L2_ENC_CMD_STOP`` again while the drain 641 ``V4L2_ENC_CMD_STOP`` again while the drain sequence is in progress and they
642 will fail with -EBUSY error code if attempt 642 will fail with -EBUSY error code if attempted.
643 643
644 For reference, handling of various corner c 644 For reference, handling of various corner cases is described below:
645 645
646 * In case of no buffer in the ``OUTPUT`` qu 646 * In case of no buffer in the ``OUTPUT`` queue at the time the
647 ``V4L2_ENC_CMD_STOP`` command was issued, 647 ``V4L2_ENC_CMD_STOP`` command was issued, the drain sequence completes
648 immediately and the encoder returns an em 648 immediately and the encoder returns an empty ``CAPTURE`` buffer with the
649 ``V4L2_BUF_FLAG_LAST`` flag set. 649 ``V4L2_BUF_FLAG_LAST`` flag set.
650 650
651 * In case of no buffer in the ``CAPTURE`` q 651 * In case of no buffer in the ``CAPTURE`` queue at the time the drain
652 sequence completes, the next time the cli 652 sequence completes, the next time the client queues a ``CAPTURE`` buffer
653 it is returned at once as an empty buffer 653 it is returned at once as an empty buffer with the ``V4L2_BUF_FLAG_LAST``
654 flag set. 654 flag set.
655 655
656 * If :c:func:`VIDIOC_STREAMOFF` is called o 656 * If :c:func:`VIDIOC_STREAMOFF` is called on the ``CAPTURE`` queue in the
657 middle of the drain sequence, the drain s 657 middle of the drain sequence, the drain sequence is canceled and all
658 ``CAPTURE`` buffers are implicitly return 658 ``CAPTURE`` buffers are implicitly returned to the client.
659 659
660 * If :c:func:`VIDIOC_STREAMOFF` is called o 660 * If :c:func:`VIDIOC_STREAMOFF` is called on the ``OUTPUT`` queue in the
661 middle of the drain sequence, the drain s 661 middle of the drain sequence, the drain sequence completes immediately and
662 next ``CAPTURE`` buffer will be returned 662 next ``CAPTURE`` buffer will be returned empty with the
663 ``V4L2_BUF_FLAG_LAST`` flag set. 663 ``V4L2_BUF_FLAG_LAST`` flag set.
664 664
665 Although not mandatory, the availability of 665 Although not mandatory, the availability of encoder commands may be queried
666 using :c:func:`VIDIOC_TRY_ENCODER_CMD`. 666 using :c:func:`VIDIOC_TRY_ENCODER_CMD`.
667 667
668 Reset 668 Reset
669 ===== 669 =====
670 670
671 The client may want to request the encoder to 671 The client may want to request the encoder to reinitialize the encoding, so
672 that the following stream data becomes indepen 672 that the following stream data becomes independent from the stream data
673 generated before. Depending on the coded forma 673 generated before. Depending on the coded format, that may imply that:
674 674
675 * encoded frames produced after the restart mu 675 * encoded frames produced after the restart must not reference any frames
676 produced before the stop, e.g. no long term 676 produced before the stop, e.g. no long term references for H.264/HEVC,
677 677
678 * any headers that must be included in a stand 678 * any headers that must be included in a standalone stream must be produced
679 again, e.g. SPS and PPS for H.264/HEVC. 679 again, e.g. SPS and PPS for H.264/HEVC.
680 680
681 This can be achieved by performing the reset s 681 This can be achieved by performing the reset sequence.
682 682
683 1. Perform the `Drain` sequence to ensure all 683 1. Perform the `Drain` sequence to ensure all the in-flight encoding finishes
684 and respective buffers are dequeued. 684 and respective buffers are dequeued.
685 685
686 2. Stop streaming on the ``CAPTURE`` queue via 686 2. Stop streaming on the ``CAPTURE`` queue via :c:func:`VIDIOC_STREAMOFF`. This
687 will return all currently queued ``CAPTURE` 687 will return all currently queued ``CAPTURE`` buffers to the client, without
688 valid frame data. 688 valid frame data.
689 689
690 3. Start streaming on the ``CAPTURE`` queue vi 690 3. Start streaming on the ``CAPTURE`` queue via :c:func:`VIDIOC_STREAMON` and
691 continue with regular encoding sequence. Th 691 continue with regular encoding sequence. The encoded frames produced into
692 ``CAPTURE`` buffers from now on will contai 692 ``CAPTURE`` buffers from now on will contain a standalone stream that can be
693 decoded without the need for frames encoded 693 decoded without the need for frames encoded before the reset sequence,
694 starting at the first ``OUTPUT`` buffer que 694 starting at the first ``OUTPUT`` buffer queued after issuing the
695 `V4L2_ENC_CMD_STOP` of the `Drain` sequence 695 `V4L2_ENC_CMD_STOP` of the `Drain` sequence.
696 696
697 This sequence may be also used to change encod 697 This sequence may be also used to change encoding parameters for encoders
698 without the ability to change the parameters o 698 without the ability to change the parameters on the fly.
699 699
700 Commit Points 700 Commit Points
701 ============= 701 =============
702 702
703 Setting formats and allocating buffers trigger 703 Setting formats and allocating buffers triggers changes in the behavior of the
704 encoder. 704 encoder.
705 705
706 1. Setting the format on the ``CAPTURE`` queue 706 1. Setting the format on the ``CAPTURE`` queue may change the set of formats
707 supported/advertised on the ``OUTPUT`` queu 707 supported/advertised on the ``OUTPUT`` queue. In particular, it also means
708 that the ``OUTPUT`` format may be reset and 708 that the ``OUTPUT`` format may be reset and the client must not rely on the
709 previously set format being preserved. 709 previously set format being preserved.
710 710
711 2. Enumerating formats on the ``OUTPUT`` queue 711 2. Enumerating formats on the ``OUTPUT`` queue always returns only formats
712 supported for the current ``CAPTURE`` forma 712 supported for the current ``CAPTURE`` format.
713 713
714 3. Setting the format on the ``OUTPUT`` queue 714 3. Setting the format on the ``OUTPUT`` queue does not change the list of
715 formats available on the ``CAPTURE`` queue. 715 formats available on the ``CAPTURE`` queue. An attempt to set the ``OUTPUT``
716 format that is not supported for the curren 716 format that is not supported for the currently selected ``CAPTURE`` format
717 will result in the encoder adjusting the re 717 will result in the encoder adjusting the requested ``OUTPUT`` format to a
718 supported one. 718 supported one.
719 719
720 4. Enumerating formats on the ``CAPTURE`` queu 720 4. Enumerating formats on the ``CAPTURE`` queue always returns the full set of
721 supported coded formats, irrespective of th 721 supported coded formats, irrespective of the current ``OUTPUT`` format.
722 722
723 5. While buffers are allocated on any of the ` 723 5. While buffers are allocated on any of the ``OUTPUT`` or ``CAPTURE`` queues,
724 the client must not change the format on th 724 the client must not change the format on the ``CAPTURE`` queue. Drivers will
725 return the -EBUSY error code for any such f 725 return the -EBUSY error code for any such format change attempt.
726 726
727 To summarize, setting formats and allocation m 727 To summarize, setting formats and allocation must always start with the
728 ``CAPTURE`` queue and the ``CAPTURE`` queue is 728 ``CAPTURE`` queue and the ``CAPTURE`` queue is the master that governs the
729 set of supported formats for the ``OUTPUT`` qu 729 set of supported formats for the ``OUTPUT`` queue.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.