git.sesse.net Git - ffmpeg/blob - libavcodec/cbs.h

   1 /*
   2  * This file is part of Libav.
   3  *
   4  * Libav 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  * Libav 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 Libav; 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 "avcodec.h"
  26
  27
  28 struct CodedBitstreamType;
  29
  30 /**
  31  * Coded bitstream unit structure.
  32  *
  33  * A bitstream unit the the smallest element of a bitstream which
  34  * is meaningful on its own.  For example, an H.264 NAL unit.
  35  *
  36  * See the codec-specific header for the meaning of this for any
  37  * particular codec.
  38  */
  39 typedef struct CodedBitstreamUnit {
  40     /**
  41      * Codec-specific type of this unit.
  42      */
  43     uint32_t type;
  44
  45     /**
  46      * Pointer to the bitstream form of this unit.
  47      *
  48      * May be NULL if the unit currently only exists in decomposed form.
  49      */
  50     uint8_t *data;
  51     /**
  52      * The number of bytes in the bitstream (including any padding bits
  53      * in the final byte).
  54      */
  55     size_t   data_size;
  56     /**
  57      * The number of bits which should be ignored in the final byte.
  58      *
  59      * This supports non-byte-aligned bitstreams.
  60      */
  61     size_t   data_bit_padding;
  62
  63     /**
  64      * Pointer to the decomposed form of this unit.
  65      *
  66      * The type of this structure depends on both the codec and the
  67      * type of this unit.  May be NULL if the unit only exists in
  68      * bitstream form.
  69      */
  70     void *content;
  71     /**
  72      * Whether the content was supplied externally.
  73      *
  74      * If so, it should not be freed when freeing the unit.
  75      */
  76     int   content_external;
  77 } CodedBitstreamUnit;
  78
  79 /**
  80  * Coded bitstream fragment structure, combining one or more units.
  81  *
  82  * This is any sequence of units.  It need not form some greater whole,
  83  * though in many cases it will.  For example, an H.264 access unit,
  84  * which is composed of a sequence of H.264 NAL units.
  85  */
  86 typedef struct CodedBitstreamFragment {
  87     /**
  88      * Pointer to the bitstream form of this fragment.
  89      *
  90      * May be NULL if the fragment only exists as component units.
  91      */
  92     uint8_t *data;
  93     /**
  94      * The number of bytes in the bitstream.
  95      *
  96      * The number of bytes in the bitstream (including any padding bits
  97      * in the final byte).
  98      */
  99     size_t   data_size;
 100     /**
 101      * The number of bits which should be ignored in the final byte.
 102      */
 103     size_t data_bit_padding;
 104
 105     /**
 106      * Number of units in this fragment.
 107      *
 108      * This may be zero if the fragment only exists in bistream form
 109      * and has not been decomposed.
 110      */
 111     int              nb_units;
 112     /**
 113      * Pointer to an array of units of length nb_units.
 114      *
 115      * Must be NULL if nb_units is zero.
 116      */
 117     CodedBitstreamUnit *units;
 118 } CodedBitstreamFragment;
 119
 120 /**
 121  * Context structure for coded bitstream operations.
 122  */
 123 typedef struct CodedBitstreamContext {
 124     /**
 125      * Logging context to be passed to all av_log() calls associated
 126      * with this context.
 127      */
 128     void *log_ctx;
 129
 130     /**
 131      * Internal codec-specific hooks.
 132      */
 133     const struct CodedBitstreamType *codec;
 134
 135     /**
 136      * Internal codec-specific data.
 137      *
 138      * This contains any information needed when reading/writing
 139      * bitsteams which will not necessarily be present in a fragment.
 140      * For example, for H.264 it contains all currently visible
 141      * parameter sets - they are required to determine the bitstream
 142      * syntax but need not be present in every access unit.
 143      */
 144     void *priv_data;
 145
 146     /**
 147      * Array of unit types which should be decomposed when reading.
 148      *
 149      * Types not in this list will be available in bitstream form only.
 150      * If NULL, all supported types will be decomposed.
 151      */
 152     uint32_t *decompose_unit_types;
 153     /**
 154      * Length of the decompose_unit_types array.
 155      */
 156     int    nb_decompose_unit_types;
 157
 158     /**
 159      * Enable trace output during read/write operations.
 160      */
 161     int trace_enable;
 162     /**
 163      * Log level to use for trace output.
 164      *
 165      * From AV_LOG_*; defaults to AV_LOG_TRACE.
 166      */
 167     int trace_level;
 168 } CodedBitstreamContext;
 169
 170
 171 /**
 172  * Initialise a new context for the given codec.
 173  */
 174 int ff_cbs_init(CodedBitstreamContext *ctx,
 175                 enum AVCodecID codec_id, void *log_ctx);
 176
 177 /**
 178  * Close a context and free all internal state.
 179  */
 180 void ff_cbs_close(CodedBitstreamContext *ctx);
 181
 182
 183 /**
 184  * Read the extradata bitstream found in codec parameters into a
 185  * fragment, then split into units and decompose.
 186  *
 187  * This also updates the internal state, so will need to be called for
 188  * codecs with extradata to read parameter sets necessary for further
 189  * parsing even if the fragment itself is not desired.
 190  */
 191 int ff_cbs_read_extradata(CodedBitstreamContext *ctx,
 192                           CodedBitstreamFragment *frag,
 193                           const AVCodecParameters *par);
 194
 195 /**
 196  * Read the data bitstream from a packet into a fragment, then
 197  * split into units and decompose.
 198  */
 199 int ff_cbs_read_packet(CodedBitstreamContext *ctx,
 200                        CodedBitstreamFragment *frag,
 201                        const AVPacket *pkt);
 202
 203 /**
 204  * Read a bitstream from a memory region into a fragment, then
 205  * split into units and decompose.
 206  */
 207 int ff_cbs_read(CodedBitstreamContext *ctx,
 208                 CodedBitstreamFragment *frag,
 209                 const uint8_t *data, size_t size);
 210
 211
 212 /**
 213  * Write the content of the fragment to its own internal buffer.
 214  *
 215  * Writes the content of all units and then assembles them into a new
 216  * data buffer.  When modifying the content of decomposed units, this
 217  * can be used to regenerate the bitstream form of units or the whole
 218  * fragment so that it can be extracted for other use.
 219  */
 220 int ff_cbs_write_fragment_data(CodedBitstreamContext *ctx,
 221                                CodedBitstreamFragment *frag);
 222
 223 /**
 224  * Write the bitstream of a fragment to the extradata in codec parameters.
 225  */
 226 int ff_cbs_write_extradata(CodedBitstreamContext *ctx,
 227                            AVCodecParameters *par,
 228                            CodedBitstreamFragment *frag);
 229
 230 /**
 231  * Write the bitstream of a fragment to a packet.
 232  */
 233 int ff_cbs_write_packet(CodedBitstreamContext *ctx,
 234                         AVPacket *pkt,
 235                         CodedBitstreamFragment *frag);
 236
 237
 238 /**
 239  * Free all allocated memory in a fragment.
 240  */
 241 void ff_cbs_fragment_uninit(CodedBitstreamContext *ctx,
 242                             CodedBitstreamFragment *frag);
 243
 244
 245 /**
 246  * Insert a new unit into a fragment with the given content.
 247  *
 248  * The content structure continues to be owned by the caller, and
 249  * will not be freed when the unit is.
 250  */
 251 int ff_cbs_insert_unit_content(CodedBitstreamContext *ctx,
 252                                CodedBitstreamFragment *frag,
 253                                int position, uint32_t type,
 254                                void *content);
 255
 256 /**
 257  * Insert a new unit into a fragment with the given data bitstream.
 258  *
 259  * The data buffer will be owned by the unit after this operation.
 260  */
 261 int ff_cbs_insert_unit_data(CodedBitstreamContext *ctx,
 262                             CodedBitstreamFragment *frag,
 263                             int position, uint32_t type,
 264                             uint8_t *data, size_t data_size);
 265
 266 /**
 267  * Delete a unit from a fragment and free all memory it uses.
 268  */
 269 int ff_cbs_delete_unit(CodedBitstreamContext *ctx,
 270                        CodedBitstreamFragment *frag,
 271                        int position);
 272
 273
 274 #endif /* AVCODEC_CBS_H */