1 /*
2 * This file is part of FFmpeg.
3 *
4 * FFmpeg is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2.1 of the License, or (at your option) any later version.
8 *
9 * FFmpeg is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with FFmpeg; if not, write to the Free Software
16 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17 */
18
19 #ifndef AVCODEC_CBS_H
20 #define AVCODEC_CBS_H
21
22 #include <stddef.h>
23 #include <stdint.h>
24
26
31
32 #ifndef CBS_PREFIX
33 #define CBS_PREFIX cbs
34 #endif
35
36 #define CBS_FUNC_PREFIX_NAME(prefix, name) ff_ ## prefix ## _ ## name
37 #define CBS_FUNC_NAME(prefix, name) CBS_FUNC_PREFIX_NAME(prefix, name)
38 #define CBS_FUNC(name) CBS_FUNC_NAME(CBS_PREFIX, name)
39
40 /*
41 * This defines a framework for converting between a coded bitstream
42 * and structures defining all individual syntax elements found in
43 * such a stream.
44 *
45 * Conversion in both directions is possible. Given a coded bitstream
46 * (any meaningful fragment), it can be parsed and decomposed into
47 * syntax elements stored in a set of codec-specific structures.
48 * Similarly, given a set of those same codec-specific structures the
49 * syntax elements can be serialised and combined to create a coded
50 * bitstream.
51 */
52
55
56 /**
57 * The codec-specific type of a bitstream unit.
58 *
59 * AV1: obu_type
60 * H.264 / AVC: nal_unit_type
61 * H.265 / HEVC: nal_unit_type
62 * JPEG: marker value (without 0xff prefix)
63 * MPEG-2: start code value (without prefix)
64 * VP9: unused, set to zero (every unit is a frame)
65 */
67
68 /**
69 * Coded bitstream unit structure.
70 *
71 * A bitstream unit the smallest element of a bitstream which
72 * is meaningful on its own. For example, an H.264 NAL unit.
73 *
74 * See the codec-specific header for the meaning of this for any
75 * particular codec.
76 */
78 /**
79 * Codec-specific type of this unit.
80 */
82
83 /**
84 * Pointer to the directly-parsable bitstream form of this unit.
85 *
86 * May be NULL if the unit currently only exists in decomposed form.
87 */
89 /**
90 * The number of bytes in the bitstream (including any padding bits
91 * in the final byte).
92 */
94 /**
95 * The number of bits which should be ignored in the final byte.
96 *
97 * This supports non-byte-aligned bitstreams.
98 */
100 /**
101 * A reference to the buffer containing data.
102 *
103 * Must be set if data is not NULL.
104 */
106
107 /**
108 * Pointer to the decomposed form of this unit.
109 *
110 * The type of this structure depends on both the codec and the
111 * type of this unit. May be NULL if the unit only exists in
112 * bitstream form.
113 */
115 /**
116 * If content is reference counted, a RefStruct reference backing content.
117 * NULL if content is not reference counted.
118 */
121
122 /**
123 * Coded bitstream fragment structure, combining one or more units.
124 *
125 * This is any sequence of units. It need not form some greater whole,
126 * though in many cases it will. For example, an H.264 access unit,
127 * which is composed of a sequence of H.264 NAL units.
128 */
130 /**
131 * Pointer to the bitstream form of this fragment.
132 *
133 * May be NULL if the fragment only exists as component units.
134 */
136 /**
137 * The number of bytes in the bitstream.
138 *
139 * The number of bytes in the bitstream (including any padding bits
140 * in the final byte).
141 */
143 /**
144 * The number of bits which should be ignored in the final byte.
145 */
147 /**
148 * A reference to the buffer containing data.
149 *
150 * Must be set if data is not NULL.
151 */
153
154 /**
155 * Number of units in this fragment.
156 *
157 * This may be zero if the fragment only exists in bitstream form
158 * and has not been decomposed.
159 */
161
162 /**
163 * Number of allocated units.
164 *
165 * Must always be >= nb_units; designed for internal use by cbs.
166 */
168
169 /**
170 * Pointer to an array of units of length nb_units_allocated.
171 * Only the first nb_units are valid.
172 *
173 * Must be NULL if nb_units_allocated is zero.
174 */
177
178
182
183 /**
184 * Callback type for read tracing.
185 *
186 * @param ctx User-set trace context.
187 * @param gbc A GetBitContext set at the start of the syntax
188 * element. This is a copy, the callee does not
189 * need to preserve it.
190 * @param length Length in bits of the syntax element.
191 * @param name String name of the syntax elements.
192 * @param subscripts If the syntax element is an array, a pointer to
193 * an array of subscripts into the array.
194 * @param value Parsed value of the syntax element.
195 */
198 int start_position,
200 const int *subscripts,
202
203 /**
204 * Callback type for write tracing.
205 *
206 * @param ctx User-set trace context.
207 * @param pbc A PutBitContext set at the end of the syntax
208 * element. The user must not modify this, but may
209 * inspect it to determine state.
210 * @param length Length in bits of the syntax element.
211 * @param name String name of the syntax elements.
212 * @param subscripts If the syntax element is an array, a pointer to
213 * an array of subscripts into the array.
214 * @param value Written value of the syntax element.
215 */
218 int start_position,
220 const int *subscripts,
222
223 /**
224 * Context structure for coded bitstream operations.
225 */
227 /**
228 * Logging context to be passed to all av_log() calls associated
229 * with this context.
230 */
232
233 /**
234 * Internal codec-specific hooks.
235 */
237
238 /**
239 * Internal codec-specific data.
240 *
241 * This contains any information needed when reading/writing
242 * bitsteams which will not necessarily be present in a fragment.
243 * For example, for H.264 it contains all currently visible
244 * parameter sets - they are required to determine the bitstream
245 * syntax but need not be present in every access unit.
246 */
248
249 /**
250 * Array of unit types which should be decomposed when reading.
251 *
252 * Types not in this list will be available in bitstream form only.
253 * If NULL, all supported types will be decomposed.
254 */
256 /**
257 * Length of the decompose_unit_types array.
258 */
260
261 /**
262 * Enable trace output during read/write operations.
263 */
265 /**
266 * Log level to use for default trace output.
267 *
268 * From AV_LOG_*; defaults to AV_LOG_TRACE.
269 */
271 /**
272 * User context pointer to pass to trace callbacks.
273 */
275 /**
276 * Callback for read tracing.
277 *
278 * If tracing is enabled then this is called once for each syntax
279 * element parsed.
280 */
282 /**
283 * Callback for write tracing.
284 *
285 * If tracing is enabled then this is called once for each syntax
286 * element written.
287 */
289
290 /**
291 * Write buffer. Used as intermediate buffer when writing units.
292 * For internal use of cbs only.
293 */
297
298
299 /**
300 * Table of all supported codec IDs.
301 *
302 * Terminated by AV_CODEC_ID_NONE.
303 */
305
306
307 /**
308 * Create and initialise a new context for the given codec.
309 */
312
313 /**
314 * Reset all internal state in a context.
315 */
317
318 /**
319 * Close a context and free all internal state.
320 */
322
323
324 /**
325 * Read the extradata bitstream found in codec parameters into a
326 * fragment, then split into units and decompose.
327 *
328 * This also updates the internal state, so will need to be called for
329 * codecs with extradata to read parameter sets necessary for further
330 * parsing even if the fragment itself is not desired.
331 *
332 * The fragment must have been zeroed or reset via ff_cbs_fragment_reset
333 * before use.
334 */
338
339 /**
340 * Read the extradata bitstream found in a codec context into a
341 * fragment, then split into units and decompose.
342 *
343 * This acts identical to ff_cbs_read_extradata() for the case where
344 * you already have a codec context.
345 */
349
353
354 /**
355 * Read the data bitstream from a packet into a fragment, then
356 * split into units and decompose.
357 *
358 * This also updates the internal state of the coded bitstream context
359 * with any persistent data from the fragment which may be required to
360 * read following fragments (e.g. parameter sets).
361 *
362 * The fragment must have been zeroed or reset via ff_cbs_fragment_reset
363 * before use.
364 */
368
369 /**
370 * Read a bitstream from a memory region into a fragment, then
371 * split into units and decompose.
372 *
373 * This also updates the internal state of the coded bitstream context
374 * with any persistent data from the fragment which may be required to
375 * read following fragments (e.g. parameter sets).
376 *
377 * The fragment must have been zeroed or reset via ff_cbs_fragment_reset
378 * before use.
379 */
384
385
386 /**
387 * Write the content of the fragment to its own internal buffer.
388 *
389 * Writes the content of all units and then assembles them into a new
390 * data buffer. When modifying the content of decomposed units, this
391 * can be used to regenerate the bitstream form of units or the whole
392 * fragment so that it can be extracted for other use.
393 *
394 * This also updates the internal state of the coded bitstream context
395 * with any persistent data from the fragment which may be required to
396 * write following fragments (e.g. parameter sets).
397 */
400
401 /**
402 * Write the bitstream of a fragment to the extradata in codec parameters.
403 *
404 * Modifies context and fragment as ff_cbs_write_fragment_data does and
405 * replaces any existing extradata in the structure.
406 */
410
411 /**
412 * Write the bitstream of a fragment to a packet.
413 *
414 * Modifies context and fragment as ff_cbs_write_fragment_data does.
415 *
416 * On success, the packet's buf is unreferenced and its buf, data and
417 * size fields are set to the corresponding values from the newly updated
418 * fragment; other fields are not touched. On failure, the packet is not
419 * touched at all.
420 */
424
425
426 /**
427 * Free the units contained in a fragment as well as the fragment's
428 * own data buffer, but not the units array itself.
429 */
431
432 /**
433 * Free the units array of a fragment in addition to what
434 * ff_cbs_fragment_reset does.
435 */
437
438 /**
439 * Allocate a new internal content buffer matching the type of the unit.
440 *
441 * The content will be zeroed.
442 */
445
446 /**
447 * Insert a new unit into a fragment with the given content.
448 *
449 * If content_ref is supplied, it has to be a RefStruct reference
450 * backing content; the user keeps ownership of the supplied reference.
451 * The content structure continues to be owned by the caller if
452 * content_ref is not supplied.
453 */
455 int position,
457 void *content,
458 void *content_ref);
459
460 /**
461 * Add a new unit to a fragment with the given data bitstream.
462 *
463 * If data_buf is not supplied then data must have been allocated with
464 * av_malloc() and will on success become owned by the unit after this
465 * call or freed on error.
466 */
469 uint8_t *
data,
size_t data_size,
471
472 /**
473 * Delete a unit from a fragment and free all memory it uses.
474 *
475 * Requires position to be >= 0 and < frag->nb_units.
476 */
478 int position);
479
480
481 /**
482 * Make the content of a unit refcounted.
483 *
484 * If the unit is not refcounted, this will do a deep copy of the unit
485 * content to new refcounted buffers.
486 *
487 * It is not valid to call this function on a unit which does not have
488 * decomposed content.
489 */
492
493 /**
494 * Make the content of a unit writable so that internal fields can be
495 * modified.
496 *
497 * If it is known that there are no other references to the content of
498 * the unit, does nothing and returns success. Otherwise (including the
499 * case where the unit content is not refcounted), it does a full clone
500 * of the content (including any internal buffers) to make a new copy,
501 * and replaces the existing references inside the unit with that.
502 *
503 * It is not valid to call this function on a unit which does not have
504 * decomposed content.
505 */
508
511
512 /**
513 * keep non-vcl units even if the picture has been dropped.
514 */
516 };
517
518 /**
519 * Discard units according to 'skip'.
520 */
525
526
527 /**
528 * Helper function for read tracing which formats the syntax element
529 * and logs the result.
530 *
531 * Trace context should be set to the CodedBitstreamContext.
532 */
535 const char *str, const int *subscripts,
537
538 /**
539 * Helper function for write tracing which formats the syntax element
540 * and logs the result.
541 *
542 * Trace context should be set to the CodedBitstreamContext.
543 */
546 const char *str, const int *subscripts,
548
549 #endif /* AVCODEC_CBS_H */