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

   1 /*
   2  * Bitstream filters public API
   3  *
   4  * This file is part of FFmpeg.
   5  *
   6  * FFmpeg is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2.1 of the License, or (at your option) any later version.
  10  *
  11  * FFmpeg is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public
  17  * License along with FFmpeg; if not, write to the Free Software
  18  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  19  */
  20
  21 #ifndef AVCODEC_BSF_H
  22 #define AVCODEC_BSF_H
  23
  24 #include "libavutil/dict.h"
  25 #include "libavutil/log.h"
  26 #include "libavutil/rational.h"
  27
  28 #include "codec_id.h"
  29 #include "codec_par.h"
  30 #include "packet.h"
  31
  32 /**
  33  * @addtogroup lavc_core
  34  * @{
  35  */
  36
  37 typedef struct AVBSFInternal AVBSFInternal;
  38
  39 /**
  40  * The bitstream filter state.
  41  *
  42  * This struct must be allocated with av_bsf_alloc() and freed with
  43  * av_bsf_free().
  44  *
  45  * The fields in the struct will only be changed (by the caller or by the
  46  * filter) as described in their documentation, and are to be considered
  47  * immutable otherwise.
  48  */
  49 typedef struct AVBSFContext {
  50     /**
  51      * A class for logging and AVOptions
  52      */
  53     const AVClass *av_class;
  54
  55     /**
  56      * The bitstream filter this context is an instance of.
  57      */
  58     const struct AVBitStreamFilter *filter;
  59
  60     /**
  61      * Opaque libavcodec internal data. Must not be touched by the caller in any
  62      * way.
  63      */
  64     AVBSFInternal *internal;
  65
  66     /**
  67      * Opaque filter-specific private data. If filter->priv_class is non-NULL,
  68      * this is an AVOptions-enabled struct.
  69      */
  70     void *priv_data;
  71
  72     /**
  73      * Parameters of the input stream. This field is allocated in
  74      * av_bsf_alloc(), it needs to be filled by the caller before
  75      * av_bsf_init().
  76      */
  77     AVCodecParameters *par_in;
  78
  79     /**
  80      * Parameters of the output stream. This field is allocated in
  81      * av_bsf_alloc(), it is set by the filter in av_bsf_init().
  82      */
  83     AVCodecParameters *par_out;
  84
  85     /**
  86      * The timebase used for the timestamps of the input packets. Set by the
  87      * caller before av_bsf_init().
  88      */
  89     AVRational time_base_in;
  90
  91     /**
  92      * The timebase used for the timestamps of the output packets. Set by the
  93      * filter in av_bsf_init().
  94      */
  95     AVRational time_base_out;
  96 } AVBSFContext;
  97
  98 typedef struct AVBitStreamFilter {
  99     const char *name;
 100
 101     /**
 102      * A list of codec ids supported by the filter, terminated by
 103      * AV_CODEC_ID_NONE.
 104      * May be NULL, in that case the bitstream filter works with any codec id.
 105      */
 106     const enum AVCodecID *codec_ids;
 107
 108     /**
 109      * A class for the private data, used to declare bitstream filter private
 110      * AVOptions. This field is NULL for bitstream filters that do not declare
 111      * any options.
 112      *
 113      * If this field is non-NULL, the first member of the filter private data
 114      * must be a pointer to AVClass, which will be set by libavcodec generic
 115      * code to this class.
 116      */
 117     const AVClass *priv_class;
 118
 119     /*****************************************************************
 120      * No fields below this line are part of the public API. They
 121      * may not be used outside of libavcodec and can be changed and
 122      * removed at will.
 123      * New public fields should be added right above.
 124      *****************************************************************
 125      */
 126
 127     int priv_data_size;
 128     int (*init)(AVBSFContext *ctx);
 129     int (*filter)(AVBSFContext *ctx, AVPacket *pkt);
 130     void (*close)(AVBSFContext *ctx);
 131     void (*flush)(AVBSFContext *ctx);
 132 } AVBitStreamFilter;
 133
 134 /**
 135  * @return a bitstream filter with the specified name or NULL if no such
 136  *         bitstream filter exists.
 137  */
 138 const AVBitStreamFilter *av_bsf_get_by_name(const char *name);
 139
 140 /**
 141  * Iterate over all registered bitstream filters.
 142  *
 143  * @param opaque a pointer where libavcodec will store the iteration state. Must
 144  *               point to NULL to start the iteration.
 145  *
 146  * @return the next registered bitstream filter or NULL when the iteration is
 147  *         finished
 148  */
 149 const AVBitStreamFilter *av_bsf_iterate(void **opaque);
 150
 151 /**
 152  * Allocate a context for a given bitstream filter. The caller must fill in the
 153  * context parameters as described in the documentation and then call
 154  * av_bsf_init() before sending any data to the filter.
 155  *
 156  * @param filter the filter for which to allocate an instance.
 157  * @param ctx a pointer into which the pointer to the newly-allocated context
 158  *            will be written. It must be freed with av_bsf_free() after the
 159  *            filtering is done.
 160  *
 161  * @return 0 on success, a negative AVERROR code on failure
 162  */
 163 int av_bsf_alloc(const AVBitStreamFilter *filter, AVBSFContext **ctx);
 164
 165 /**
 166  * Prepare the filter for use, after all the parameters and options have been
 167  * set.
 168  */
 169 int av_bsf_init(AVBSFContext *ctx);
 170
 171 /**
 172  * Submit a packet for filtering.
 173  *
 174  * After sending each packet, the filter must be completely drained by calling
 175  * av_bsf_receive_packet() repeatedly until it returns AVERROR(EAGAIN) or
 176  * AVERROR_EOF.
 177  *
 178  * @param pkt the packet to filter. The bitstream filter will take ownership of
 179  * the packet and reset the contents of pkt. pkt is not touched if an error occurs.
 180  * If pkt is empty (i.e. NULL, or pkt->data is NULL and pkt->side_data_elems zero),
 181  * it signals the end of the stream (i.e. no more non-empty packets will be sent;
 182  * sending more empty packets does nothing) and will cause the filter to output
 183  * any packets it may have buffered internally.
 184  *
 185  * @return 0 on success. AVERROR(EAGAIN) if packets need to be retrieved from the
 186  * filter (using av_bsf_receive_packet()) before new input can be consumed. Another
 187  * negative AVERROR value if an error occurs.
 188  */
 189 int av_bsf_send_packet(AVBSFContext *ctx, AVPacket *pkt);
 190
 191 /**
 192  * Retrieve a filtered packet.
 193  *
 194  * @param[out] pkt this struct will be filled with the contents of the filtered
 195  *                 packet. It is owned by the caller and must be freed using
 196  *                 av_packet_unref() when it is no longer needed.
 197  *                 This parameter should be "clean" (i.e. freshly allocated
 198  *                 with av_packet_alloc() or unreffed with av_packet_unref())
 199  *                 when this function is called. If this function returns
 200  *                 successfully, the contents of pkt will be completely
 201  *                 overwritten by the returned data. On failure, pkt is not
 202  *                 touched.
 203  *
 204  * @return 0 on success. AVERROR(EAGAIN) if more packets need to be sent to the
 205  * filter (using av_bsf_send_packet()) to get more output. AVERROR_EOF if there
 206  * will be no further output from the filter. Another negative AVERROR value if
 207  * an error occurs.
 208  *
 209  * @note one input packet may result in several output packets, so after sending
 210  * a packet with av_bsf_send_packet(), this function needs to be called
 211  * repeatedly until it stops returning 0. It is also possible for a filter to
 212  * output fewer packets than were sent to it, so this function may return
 213  * AVERROR(EAGAIN) immediately after a successful av_bsf_send_packet() call.
 214  */
 215 int av_bsf_receive_packet(AVBSFContext *ctx, AVPacket *pkt);
 216
 217 /**
 218  * Reset the internal bitstream filter state. Should be called e.g. when seeking.
 219  */
 220 void av_bsf_flush(AVBSFContext *ctx);
 221
 222 /**
 223  * Free a bitstream filter context and everything associated with it; write NULL
 224  * into the supplied pointer.
 225  */
 226 void av_bsf_free(AVBSFContext **ctx);
 227
 228 /**
 229  * Get the AVClass for AVBSFContext. It can be used in combination with
 230  * AV_OPT_SEARCH_FAKE_OBJ for examining options.
 231  *
 232  * @see av_opt_find().
 233  */
 234 const AVClass *av_bsf_get_class(void);
 235
 236 /**
 237  * Structure for chain/list of bitstream filters.
 238  * Empty list can be allocated by av_bsf_list_alloc().
 239  */
 240 typedef struct AVBSFList AVBSFList;
 241
 242 /**
 243  * Allocate empty list of bitstream filters.
 244  * The list must be later freed by av_bsf_list_free()
 245  * or finalized by av_bsf_list_finalize().
 246  *
 247  * @return Pointer to @ref AVBSFList on success, NULL in case of failure
 248  */
 249 AVBSFList *av_bsf_list_alloc(void);
 250
 251 /**
 252  * Free list of bitstream filters.
 253  *
 254  * @param lst Pointer to pointer returned by av_bsf_list_alloc()
 255  */
 256 void av_bsf_list_free(AVBSFList **lst);
 257
 258 /**
 259  * Append bitstream filter to the list of bitstream filters.
 260  *
 261  * @param lst List to append to
 262  * @param bsf Filter context to be appended
 263  *
 264  * @return >=0 on success, negative AVERROR in case of failure
 265  */
 266 int av_bsf_list_append(AVBSFList *lst, AVBSFContext *bsf);
 267
 268 /**
 269  * Construct new bitstream filter context given it's name and options
 270  * and append it to the list of bitstream filters.
 271  *
 272  * @param lst      List to append to
 273  * @param bsf_name Name of the bitstream filter
 274  * @param options  Options for the bitstream filter, can be set to NULL
 275  *
 276  * @return >=0 on success, negative AVERROR in case of failure
 277  */
 278 int av_bsf_list_append2(AVBSFList *lst, const char * bsf_name, AVDictionary **options);
 279 /**
 280  * Finalize list of bitstream filters.
 281  *
 282  * This function will transform @ref AVBSFList to single @ref AVBSFContext,
 283  * so the whole chain of bitstream filters can be treated as single filter
 284  * freshly allocated by av_bsf_alloc().
 285  * If the call is successful, @ref AVBSFList structure is freed and lst
 286  * will be set to NULL. In case of failure, caller is responsible for
 287  * freeing the structure by av_bsf_list_free()
 288  *
 289  * @param      lst Filter list structure to be transformed
 290  * @param[out] bsf Pointer to be set to newly created @ref AVBSFContext structure
 291  *                 representing the chain of bitstream filters
 292  *
 293  * @return >=0 on success, negative AVERROR in case of failure
 294  */
 295 int av_bsf_list_finalize(AVBSFList **lst, AVBSFContext **bsf);
 296
 297 /**
 298  * Parse string describing list of bitstream filters and create single
 299  * @ref AVBSFContext describing the whole chain of bitstream filters.
 300  * Resulting @ref AVBSFContext can be treated as any other @ref AVBSFContext freshly
 301  * allocated by av_bsf_alloc().
 302  *
 303  * @param      str String describing chain of bitstream filters in format
 304  *                 `bsf1[=opt1=val1:opt2=val2][,bsf2]`
 305  * @param[out] bsf Pointer to be set to newly created @ref AVBSFContext structure
 306  *                 representing the chain of bitstream filters
 307  *
 308  * @return >=0 on success, negative AVERROR in case of failure
 309  */
 310 int av_bsf_list_parse_str(const char *str, AVBSFContext **bsf);
 311
 312 /**
 313  * Get null/pass-through bitstream filter.
 314  *
 315  * @param[out] bsf Pointer to be set to new instance of pass-through bitstream filter
 316  *
 317  * @return
 318  */
 319 int av_bsf_get_null_filter(AVBSFContext **bsf);
 320
 321 /**
 322  * @}
 323  */
 324
 325 #endif // AVCODEC_BSF_H