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 25 #include "libavutil/buffer.h" 26 27 #include "avcodec.h" 28 29 30 /* 31 * This defines a framework for converting between a coded bitstream 32 * and structures defining all individual syntax elements found in 33 * such a stream. 34 * 35 * Conversion in both directions is possible. Given a coded bitstream 36 * (any meaningful fragment), it can be parsed and decomposed into 37 * syntax elements stored in a set of codec-specific structures. 38 * Similarly, given a set of those same codec-specific structures the 39 * syntax elements can be serialised and combined to create a coded 40 * bitstream. 41 */ 42 43 struct CodedBitstreamType; 44 45 /** 46 * The codec-specific type of a bitstream unit. 47 * 48 * H.264 / AVC: nal_unit_type 49 * H.265 / HEVC: nal_unit_type 50 * MPEG-2: start code value (without prefix) 51 * VP9: unused, set to zero (every unit is a frame) 52 */ 53 typedef uint32_t CodedBitstreamUnitType; 54 55 /** 56 * Coded bitstream unit structure. 57 * 58 * A bitstream unit the smallest element of a bitstream which 59 * is meaningful on its own. For example, an H.264 NAL unit. 60 * 61 * See the codec-specific header for the meaning of this for any 62 * particular codec. 63 */ 64 typedef struct CodedBitstreamUnit { 65 /** 66 * Codec-specific type of this unit. 67 */ 68 CodedBitstreamUnitType type; 69 70 /** 71 * Pointer to the directly-parsable bitstream form of this unit. 72 * 73 * May be NULL if the unit currently only exists in decomposed form. 74 */ 75 uint8_t *data; 76 /** 77 * The number of bytes in the bitstream (including any padding bits 78 * in the final byte). 79 */ 80 size_t data_size; 81 /** 82 * The number of bits which should be ignored in the final byte. 83 * 84 * This supports non-byte-aligned bitstreams. 85 */ 86 size_t data_bit_padding; 87 /** 88 * A reference to the buffer containing data. 89 * 90 * Must be set if data is not NULL. 91 */ 92 AVBufferRef *data_ref; 93 94 /** 95 * Pointer to the decomposed form of this unit. 96 * 97 * The type of this structure depends on both the codec and the 98 * type of this unit. May be NULL if the unit only exists in 99 * bitstream form. 100 */ 101 void *content; 102 /** 103 * If content is reference counted, a reference to the buffer containing 104 * content. Null if content is not reference counted. 105 */ 106 AVBufferRef *content_ref; 107 } CodedBitstreamUnit; 108 109 /** 110 * Coded bitstream fragment structure, combining one or more units. 111 * 112 * This is any sequence of units. It need not form some greater whole, 113 * though in many cases it will. For example, an H.264 access unit, 114 * which is composed of a sequence of H.264 NAL units. 115 */ 116 typedef struct CodedBitstreamFragment { 117 /** 118 * Pointer to the bitstream form of this fragment. 119 * 120 * May be NULL if the fragment only exists as component units. 121 */ 122 uint8_t *data; 123 /** 124 * The number of bytes in the bitstream. 125 * 126 * The number of bytes in the bitstream (including any padding bits 127 * in the final byte). 128 */ 129 size_t data_size; 130 /** 131 * The number of bits which should be ignored in the final byte. 132 */ 133 size_t data_bit_padding; 134 /** 135 * A reference to the buffer containing data. 136 * 137 * Must be set if data is not NULL. 138 */ 139 AVBufferRef *data_ref; 140 141 /** 142 * Number of units in this fragment. 143 * 144 * This may be zero if the fragment only exists in bitstream form 145 * and has not been decomposed. 146 */ 147 int nb_units; 148 149 /** 150 * Number of allocated units. 151 * 152 * Must always be >= nb_units; designed for internal use by cbs. 153 */ 154 int nb_units_allocated; 155 156 /** 157 * Pointer to an array of units of length nb_units_allocated. 158 * Only the first nb_units are valid. 159 * 160 * Must be NULL if nb_units_allocated is zero. 161 */ 162 CodedBitstreamUnit *units; 163 } CodedBitstreamFragment; 164 165 /** 166 * Context structure for coded bitstream operations. 167 */ 168 typedef struct CodedBitstreamContext { 169 /** 170 * Logging context to be passed to all av_log() calls associated 171 * with this context. 172 */ 173 void *log_ctx; 174 175 /** 176 * Internal codec-specific hooks. 177 */ 178 const struct CodedBitstreamType *codec; 179 180 /** 181 * Internal codec-specific data. 182 * 183 * This contains any information needed when reading/writing 184 * bitsteams which will not necessarily be present in a fragment. 185 * For example, for H.264 it contains all currently visible 186 * parameter sets - they are required to determine the bitstream 187 * syntax but need not be present in every access unit. 188 */ 189 void *priv_data; 190 191 /** 192 * Array of unit types which should be decomposed when reading. 193 * 194 * Types not in this list will be available in bitstream form only. 195 * If NULL, all supported types will be decomposed. 196 */ 197 CodedBitstreamUnitType *decompose_unit_types; 198 /** 199 * Length of the decompose_unit_types array. 200 */ 201 int nb_decompose_unit_types; 202 203 /** 204 * Enable trace output during read/write operations. 205 */ 206 int trace_enable; 207 /** 208 * Log level to use for trace output. 209 * 210 * From AV_LOG_*; defaults to AV_LOG_TRACE. 211 */ 212 int trace_level; 213 214 /** 215 * Write buffer. Used as intermediate buffer when writing units. 216 * For internal use of cbs only. 217 */ 218 uint8_t *write_buffer; 219 size_t write_buffer_size; 220 } CodedBitstreamContext; 221 222 223 /** 224 * Table of all supported codec IDs. 225 * 226 * Terminated by AV_CODEC_ID_NONE. 227 */ 228 extern const enum AVCodecID ff_cbs_all_codec_ids[]; 229 230 231 /** 232 * Create and initialise a new context for the given codec. 233 */ 234 int ff_cbs_init(CodedBitstreamContext **ctx, 235 enum AVCodecID codec_id, void *log_ctx); 236 237 /** 238 * Close a context and free all internal state. 239 */ 240 void ff_cbs_close(CodedBitstreamContext **ctx); 241 242 243 /** 244 * Read the extradata bitstream found in codec parameters into a 245 * fragment, then split into units and decompose. 246 * 247 * This also updates the internal state, so will need to be called for 248 * codecs with extradata to read parameter sets necessary for further 249 * parsing even if the fragment itself is not desired. 250 * 251 * The fragment must have been zeroed or reset via ff_cbs_fragment_reset 252 * before use. 253 */ 254 int ff_cbs_read_extradata(CodedBitstreamContext *ctx, 255 CodedBitstreamFragment *frag, 256 const AVCodecParameters *par); 257 258 /** 259 * Read the data bitstream from a packet into a fragment, then 260 * split into units and decompose. 261 * 262 * This also updates the internal state of the coded bitstream context 263 * with any persistent data from the fragment which may be required to 264 * read following fragments (e.g. parameter sets). 265 * 266 * The fragment must have been zeroed or reset via ff_cbs_fragment_reset 267 * before use. 268 */ 269 int ff_cbs_read_packet(CodedBitstreamContext *ctx, 270 CodedBitstreamFragment *frag, 271 const AVPacket *pkt); 272 273 /** 274 * Read a bitstream from a memory region into a fragment, then 275 * split into units and decompose. 276 * 277 * This also updates the internal state of the coded bitstream context 278 * with any persistent data from the fragment which may be required to 279 * read following fragments (e.g. parameter sets). 280 * 281 * The fragment must have been zeroed or reset via ff_cbs_fragment_reset 282 * before use. 283 */ 284 int ff_cbs_read(CodedBitstreamContext *ctx, 285 CodedBitstreamFragment *frag, 286 const uint8_t *data, size_t size); 287 288 289 /** 290 * Write the content of the fragment to its own internal buffer. 291 * 292 * Writes the content of all units and then assembles them into a new 293 * data buffer. When modifying the content of decomposed units, this 294 * can be used to regenerate the bitstream form of units or the whole 295 * fragment so that it can be extracted for other use. 296 * 297 * This also updates the internal state of the coded bitstream context 298 * with any persistent data from the fragment which may be required to 299 * write following fragments (e.g. parameter sets). 300 */ 301 int ff_cbs_write_fragment_data(CodedBitstreamContext *ctx, 302 CodedBitstreamFragment *frag); 303 304 /** 305 * Write the bitstream of a fragment to the extradata in codec parameters. 306 * 307 * Modifies context and fragment as ff_cbs_write_fragment_data does and 308 * replaces any existing extradata in the structure. 309 */ 310 int ff_cbs_write_extradata(CodedBitstreamContext *ctx, 311 AVCodecParameters *par, 312 CodedBitstreamFragment *frag); 313 314 /** 315 * Write the bitstream of a fragment to a packet. 316 * 317 * Modifies context and fragment as ff_cbs_write_fragment_data does. 318 * 319 * On success, the packet's buf is unreferenced and its buf, data and 320 * size fields are set to the corresponding values from the newly updated 321 * fragment; other fields are not touched. On failure, the packet is not 322 * touched at all. 323 */ 324 int ff_cbs_write_packet(CodedBitstreamContext *ctx, 325 AVPacket *pkt, 326 CodedBitstreamFragment *frag); 327 328 329 /** 330 * Free the units contained in a fragment as well as the fragment's 331 * own data buffer, but not the units array itself. 332 */ 333 void ff_cbs_fragment_reset(CodedBitstreamContext *ctx, 334 CodedBitstreamFragment *frag); 335 336 /** 337 * Free the units array of a fragment in addition to what 338 * ff_cbs_fragment_reset does. 339 */ 340 void ff_cbs_fragment_free(CodedBitstreamContext *ctx, 341 CodedBitstreamFragment *frag); 342 343 /** 344 * Allocate a new internal content buffer of the given size in the unit. 345 * 346 * The content will be zeroed. 347 */ 348 int ff_cbs_alloc_unit_content(CodedBitstreamContext *ctx, 349 CodedBitstreamUnit *unit, 350 size_t size, 351 void (*free)(void *opaque, uint8_t *content)); 352 353 /** 354 * Allocate a new internal data buffer of the given size in the unit. 355 * 356 * The data buffer will have input padding. 357 */ 358 int ff_cbs_alloc_unit_data(CodedBitstreamContext *ctx, 359 CodedBitstreamUnit *unit, 360 size_t size); 361 362 /** 363 * Insert a new unit into a fragment with the given content. 364 * 365 * The content structure continues to be owned by the caller if 366 * content_buf is not supplied. 367 */ 368 int ff_cbs_insert_unit_content(CodedBitstreamContext *ctx, 369 CodedBitstreamFragment *frag, 370 int position, 371 CodedBitstreamUnitType type, 372 void *content, 373 AVBufferRef *content_buf); 374 375 /** 376 * Insert a new unit into a fragment with the given data bitstream. 377 * 378 * If data_buf is not supplied then data must have been allocated with 379 * av_malloc() and will on success become owned by the unit after this 380 * call or freed on error. 381 */ 382 int ff_cbs_insert_unit_data(CodedBitstreamContext *ctx, 383 CodedBitstreamFragment *frag, 384 int position, 385 CodedBitstreamUnitType type, 386 uint8_t *data, size_t data_size, 387 AVBufferRef *data_buf); 388 389 /** 390 * Delete a unit from a fragment and free all memory it uses. 391 * 392 * Requires position to be >= 0 and < frag->nb_units. 393 */ 394 void ff_cbs_delete_unit(CodedBitstreamContext *ctx, 395 CodedBitstreamFragment *frag, 396 int position); 397 398 399 #endif /* AVCODEC_CBS_H */ 400