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 326