1/* 2 * filter layer 3 * copyright (c) 2007 Bobby Bingham 4 * 5 * This file is part of FFmpeg. 6 * 7 * FFmpeg is free software; you can redistribute it and/or 8 * modify it under the terms of the GNU Lesser General Public 9 * License as published by the Free Software Foundation; either 10 * version 2.1 of the License, or (at your option) any later version. 11 * 12 * FFmpeg is distributed in the hope that it will be useful, 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 15 * Lesser General Public License for more details. 16 * 17 * You should have received a copy of the GNU Lesser General Public 18 * License along with FFmpeg; if not, write to the Free Software 19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 20 */ 21 22#ifndef AVFILTER_AVFILTER_H 23#define AVFILTER_AVFILTER_H 24 25#define LIBAVFILTER_VERSION_MAJOR 0 26#define LIBAVFILTER_VERSION_MINOR 4 27#define LIBAVFILTER_VERSION_MICRO 0 28 29#define LIBAVFILTER_VERSION_INT AV_VERSION_INT(LIBAVFILTER_VERSION_MAJOR, \ 30 LIBAVFILTER_VERSION_MINOR, \ 31 LIBAVFILTER_VERSION_MICRO) 32#define LIBAVFILTER_VERSION AV_VERSION(LIBAVFILTER_VERSION_MAJOR, \ 33 LIBAVFILTER_VERSION_MINOR, \ 34 LIBAVFILTER_VERSION_MICRO) 35#define LIBAVFILTER_BUILD LIBAVFILTER_VERSION_INT 36 37#include <stddef.h> 38#include "libavcodec/avcodec.h" 39 40/** 41 * Returns the LIBAVFILTER_VERSION_INT constant. 42 */ 43unsigned avfilter_version(void); 44 45typedef struct AVFilterContext AVFilterContext; 46typedef struct AVFilterLink AVFilterLink; 47typedef struct AVFilterPad AVFilterPad; 48 49/* TODO: look for other flags which may be useful in this structure (interlace 50 * flags, etc) 51 */ 52/** 53 * A reference-counted picture data type used by the filter system. Filters 54 * should not store pointers to this structure directly, but instead use the 55 * AVFilterPicRef structure below. 56 */ 57typedef struct AVFilterPic 58{ 59 uint8_t *data[4]; ///< picture data for each plane 60 int linesize[4]; ///< number of bytes per line 61 enum PixelFormat format; ///< colorspace 62 63 unsigned refcount; ///< number of references to this image 64 65 /** private data to be used by a custom free function */ 66 void *priv; 67 /** 68 * A pointer to the function to deallocate this image if the default 69 * function is not sufficient. This could, for example, add the memory 70 * back into a memory pool to be reused later without the overhead of 71 * reallocating it from scratch. 72 */ 73 void (*free)(struct AVFilterPic *pic); 74} AVFilterPic; 75 76/** 77 * A reference to an AVFilterPic. Since filters can manipulate the origin of 78 * a picture to, for example, crop image without any memcpy, the picture origin 79 * and dimensions are per-reference properties. Linesize is also useful for 80 * image flipping, frame to field filters, etc, and so is also per-reference. 81 * 82 * TODO: add anything necessary for frame reordering 83 */ 84typedef struct AVFilterPicRef 85{ 86 AVFilterPic *pic; ///< the picture that this is a reference to 87 uint8_t *data[4]; ///< picture data for each plane 88 int linesize[4]; ///< number of bytes per line 89 int w; ///< image width 90 int h; ///< image height 91 92 int64_t pts; ///< presentation timestamp in units of 1/AV_TIME_BASE 93 94 AVRational pixel_aspect; ///< pixel aspect ratio 95 96 int perms; ///< permissions 97#define AV_PERM_READ 0x01 ///< can read from the buffer 98#define AV_PERM_WRITE 0x02 ///< can write to the buffer 99#define AV_PERM_PRESERVE 0x04 ///< nobody else can overwrite the buffer 100#define AV_PERM_REUSE 0x08 ///< can output the buffer multiple times, with the same contents each time 101#define AV_PERM_REUSE2 0x10 ///< can output the buffer multiple times, modified each time 102} AVFilterPicRef; 103 104/** 105 * Add a new reference to a picture. 106 * @param ref an existing reference to the picture 107 * @param pmask a bitmask containing the allowable permissions in the new 108 * reference 109 * @return a new reference to the picture with the same properties as the 110 * old, excluding any permissions denied by pmask 111 */ 112AVFilterPicRef *avfilter_ref_pic(AVFilterPicRef *ref, int pmask); 113 114/** 115 * Remove a reference to a picture. If this is the last reference to the 116 * picture, the picture itself is also automatically freed. 117 * @param ref reference to the picture 118 */ 119void avfilter_unref_pic(AVFilterPicRef *ref); 120 121/** 122 * A list of supported formats for one end of a filter link. This is used 123 * during the format negotiation process to try to pick the best format to 124 * use to minimize the number of necessary conversions. Each filter gives a 125 * list of the formats supported by each input and output pad. The list 126 * given for each pad need not be distinct - they may be references to the 127 * same list of formats, as is often the case when a filter supports multiple 128 * formats, but will always output the same format as it is given in input. 129 * 130 * In this way, a list of possible input formats and a list of possible 131 * output formats are associated with each link. When a set of formats is 132 * negotiated over a link, the input and output lists are merged to form a 133 * new list containing only the common elements of each list. In the case 134 * that there were no common elements, a format conversion is necessary. 135 * Otherwise, the lists are merged, and all other links which reference 136 * either of the format lists involved in the merge are also affected. 137 * 138 * For example, consider the filter chain: 139 * filter (a) --> (b) filter (b) --> (c) filter 140 * 141 * where the letters in parenthesis indicate a list of formats supported on 142 * the input or output of the link. Suppose the lists are as follows: 143 * (a) = {A, B} 144 * (b) = {A, B, C} 145 * (c) = {B, C} 146 * 147 * First, the first link's lists are merged, yielding: 148 * filter (a) --> (a) filter (a) --> (c) filter 149 * 150 * Notice that format list (b) now refers to the same list as filter list (a). 151 * Next, the lists for the second link are merged, yielding: 152 * filter (a) --> (a) filter (a) --> (a) filter 153 * 154 * where (a) = {B}. 155 * 156 * Unfortunately, when the format lists at the two ends of a link are merged, 157 * we must ensure that all links which reference either pre-merge format list 158 * get updated as well. Therefore, we have the format list structure store a 159 * pointer to each of the pointers to itself. 160 */ 161typedef struct AVFilterFormats AVFilterFormats; 162struct AVFilterFormats 163{ 164 unsigned format_count; ///< number of formats 165 int *formats; ///< list of formats 166 167 unsigned refcount; ///< number of references to this list 168 AVFilterFormats ***refs; ///< references to this list 169}; 170 171/** 172 * Helper function to create a list of supported formats. This is intended 173 * for use in AVFilter->query_formats(). 174 * @param len the number of formats supported 175 * @param ... a list of the supported formats 176 * @return the format list, with no existing references 177 */ 178AVFilterFormats *avfilter_make_format_list(int len, ...); 179 180/** 181 * Returns a list of all colorspaces supported by FFmpeg. 182 */ 183AVFilterFormats *avfilter_all_colorspaces(void); 184 185/** 186 * Returns a format list which contains the intersection of the formats of 187 * a and b. Also, all the references of a, all the references of b, and 188 * a and b themselves will be deallocated. 189 * 190 * If a and b do not share any common formats, neither is modified, and NULL 191 * is returned. 192 */ 193AVFilterFormats *avfilter_merge_formats(AVFilterFormats *a, AVFilterFormats *b); 194 195/** 196 * Adds *ref as a new reference to formats. 197 * That is the pointers will point like in the ascii art below: 198 * ________ 199 * |formats |<--------. 200 * | ____ | ____|___________________ 201 * | |refs| | | __|_ 202 * | |* * | | | | | | AVFilterLink 203 * | |* *--------->|*ref| 204 * | |____| | | |____| 205 * |________| |________________________ 206 */ 207void avfilter_formats_ref(AVFilterFormats *formats, AVFilterFormats **ref); 208 209/** 210 * Remove *ref as a reference to the format list it currently points to, 211 * deallocate that list if this was the last reference, and set *ref to NULL. 212 * 213 * Before After 214 * ________ ________ NULL 215 * |formats |<--------. |formats | ^ 216 * | ____ | ____|________________ | ____ | ____|________________ 217 * | |refs| | | __|_ | |refs| | | __|_ 218 * | |* * | | | | | | AVFilterLink | |* * | | | | | | AVFilterLink 219 * | |* *--------->|*ref| | |* | | | |*ref| 220 * | |____| | | |____| | |____| | | |____| 221 * |________| |_____________________ |________| |_____________________ 222 */ 223void avfilter_formats_unref(AVFilterFormats **ref); 224 225/** 226 * 227 * Before After 228 * ________ ________ 229 * |formats |<---------. |formats |<---------. 230 * | ____ | ___|___ | ____ | ___|___ 231 * | |refs| | | | | | |refs| | | | | NULL 232 * | |* *--------->|*oldref| | |* *--------->|*newref| ^ 233 * | |* * | | |_______| | |* * | | |_______| ___|___ 234 * | |____| | | |____| | | | | 235 * |________| |________| |*oldref| 236 * |_______| 237 */ 238void avfilter_formats_changeref(AVFilterFormats **oldref, 239 AVFilterFormats **newref); 240 241/** 242 * A filter pad used for either input or output. 243 */ 244struct AVFilterPad 245{ 246 /** 247 * Pad name. The name is unique among inputs and among outputs, but an 248 * input may have the same name as an output. This may be NULL if this 249 * pad has no need to ever be referenced by name. 250 */ 251 const char *name; 252 253 /** 254 * AVFilterPad type. Only video supported now, hopefully someone will 255 * add audio in the future. 256 */ 257 enum CodecType type; 258 259 /** 260 * Minimum required permissions on incoming buffers. Any buffer with 261 * insufficient permissions will be automatically copied by the filter 262 * system to a new buffer which provides the needed access permissions. 263 * 264 * Input pads only. 265 */ 266 int min_perms; 267 268 /** 269 * Permissions which are not accepted on incoming buffers. Any buffer 270 * which has any of these permissions set will be automatically copied 271 * by the filter system to a new buffer which does not have those 272 * permissions. This can be used to easily disallow buffers with 273 * AV_PERM_REUSE. 274 * 275 * Input pads only. 276 */ 277 int rej_perms; 278 279 /** 280 * Callback called before passing the first slice of a new frame. If 281 * NULL, the filter layer will default to storing a reference to the 282 * picture inside the link structure. 283 * 284 * Input video pads only. 285 */ 286 void (*start_frame)(AVFilterLink *link, AVFilterPicRef *picref); 287 288 /** 289 * Callback function to get a buffer. If NULL, the filter system will 290 * handle buffer requests. 291 * 292 * Input video pads only. 293 */ 294 AVFilterPicRef *(*get_video_buffer)(AVFilterLink *link, int perms); 295 296 /** 297 * Callback called after the slices of a frame are completely sent. If 298 * NULL, the filter layer will default to releasing the reference stored 299 * in the link structure during start_frame(). 300 * 301 * Input video pads only. 302 */ 303 void (*end_frame)(AVFilterLink *link); 304 305 /** 306 * Slice drawing callback. This is where a filter receives video data 307 * and should do its processing. 308 * 309 * Input video pads only. 310 */ 311 void (*draw_slice)(AVFilterLink *link, int y, int height); 312 313 /** 314 * Frame poll callback. This returns the number of immediately available 315 * frames. It should return a positive value if the next request_frame() 316 * is guaranteed to return one frame (with no delay). 317 * 318 * Defaults to just calling the source poll_frame() method. 319 * 320 * Output video pads only. 321 */ 322 int (*poll_frame)(AVFilterLink *link); 323 324 /** 325 * Frame request callback. A call to this should result in at least one 326 * frame being output over the given link. This should return zero on 327 * success, and another value on error. 328 * 329 * Output video pads only. 330 */ 331 int (*request_frame)(AVFilterLink *link); 332 333 /** 334 * Link configuration callback. 335 * 336 * For output pads, this should set the link properties such as 337 * width/height. This should NOT set the format property - that is 338 * negotiated between filters by the filter system using the 339 * query_formats() callback before this function is called. 340 * 341 * For input pads, this should check the properties of the link, and update 342 * the filter's internal state as necessary. 343 * 344 * For both input and output filters, this should return zero on success, 345 * and another value on error. 346 */ 347 int (*config_props)(AVFilterLink *link); 348}; 349 350/** default handler for start_frame() for video inputs */ 351void avfilter_default_start_frame(AVFilterLink *link, AVFilterPicRef *picref); 352/** default handler for draw_slice() for video inputs */ 353void avfilter_default_draw_slice(AVFilterLink *link, int y, int h); 354/** default handler for end_frame() for video inputs */ 355void avfilter_default_end_frame(AVFilterLink *link); 356/** default handler for config_props() for video outputs */ 357int avfilter_default_config_output_link(AVFilterLink *link); 358/** default handler for config_props() for video inputs */ 359int avfilter_default_config_input_link (AVFilterLink *link); 360/** default handler for get_video_buffer() for video inputs */ 361AVFilterPicRef *avfilter_default_get_video_buffer(AVFilterLink *link, 362 int perms); 363/** 364 * A helper for query_formats() which sets all links to the same list of 365 * formats. If there are no links hooked to this filter, the list of formats is 366 * freed. 367 */ 368void avfilter_set_common_formats(AVFilterContext *ctx, AVFilterFormats *formats); 369/** Default handler for query_formats() */ 370int avfilter_default_query_formats(AVFilterContext *ctx); 371 372/** 373 * Filter definition. This defines the pads a filter contains, and all the 374 * callback functions used to interact with the filter. 375 */ 376typedef struct 377{ 378 const char *name; ///< filter name 379 380 int priv_size; ///< size of private data to allocate for the filter 381 382 /** 383 * Filter initialization function. Args contains the user-supplied 384 * parameters. FIXME: maybe an AVOption-based system would be better? 385 * opaque is data provided by the code requesting creation of the filter, 386 * and is used to pass data to the filter. 387 */ 388 int (*init)(AVFilterContext *ctx, const char *args, void *opaque); 389 390 /** 391 * Filter uninitialization function. Should deallocate any memory held 392 * by the filter, release any picture references, etc. This does not need 393 * to deallocate the AVFilterContext->priv memory itself. 394 */ 395 void (*uninit)(AVFilterContext *ctx); 396 397 /** 398 * Query formats supported by the filter and its pads. Should set the 399 * in_formats for links connected to its output pads, and out_formats 400 * for links connected to its input pads. 401 * 402 * Should return zero on success. 403 */ 404 int (*query_formats)(AVFilterContext *); 405 406 const AVFilterPad *inputs; ///< NULL terminated list of inputs. NULL if none 407 const AVFilterPad *outputs; ///< NULL terminated list of outputs. NULL if none 408} AVFilter; 409 410/** An instance of a filter */ 411struct AVFilterContext 412{ 413 const AVClass *av_class; ///< needed for av_log() 414 415 AVFilter *filter; ///< the AVFilter of which this is an instance 416 417 char *name; ///< name of this filter instance 418 419 unsigned input_count; ///< number of input pads 420 AVFilterPad *input_pads; ///< array of input pads 421 AVFilterLink **inputs; ///< array of pointers to input links 422 423 unsigned output_count; ///< number of output pads 424 AVFilterPad *output_pads; ///< array of output pads 425 AVFilterLink **outputs; ///< array of pointers to output links 426 427 void *priv; ///< private data for use by the filter 428}; 429 430/** 431 * A link between two filters. This contains pointers to the source and 432 * destination filters between which this link exists, and the indexes of 433 * the pads involved. In addition, this link also contains the parameters 434 * which have been negotiated and agreed upon between the filter, such as 435 * image dimensions, format, etc. 436 */ 437struct AVFilterLink 438{ 439 AVFilterContext *src; ///< source filter 440 unsigned int srcpad; ///< index of the output pad on the source filter 441 442 AVFilterContext *dst; ///< dest filter 443 unsigned int dstpad; ///< index of the input pad on the dest filter 444 445 /** stage of the initialization of the link properties (dimensions, etc) */ 446 enum { 447 AVLINK_UNINIT = 0, ///< not started 448 AVLINK_STARTINIT, ///< started, but incomplete 449 AVLINK_INIT ///< complete 450 } init_state; 451 452 int w; ///< agreed upon image width 453 int h; ///< agreed upon image height 454 enum PixelFormat format; ///< agreed upon image colorspace 455 456 /** 457 * Lists of formats supported by the input and output filters respectively. 458 * These lists are used for negotiating the format to actually be used, 459 * which will be loaded into the format member, above, when chosen. 460 */ 461 AVFilterFormats *in_formats; 462 AVFilterFormats *out_formats; 463 464 /** 465 * The picture reference currently being sent across the link by the source 466 * filter. This is used internally by the filter system to allow 467 * automatic copying of pictures which do not have sufficient permissions 468 * for the destination. This should not be accessed directly by the 469 * filters. 470 */ 471 AVFilterPicRef *srcpic; 472 473 AVFilterPicRef *cur_pic; 474 AVFilterPicRef *outpic; 475}; 476 477/** 478 * Link two filters together. 479 * @param src the source filter 480 * @param srcpad index of the output pad on the source filter 481 * @param dst the destination filter 482 * @param dstpad index of the input pad on the destination filter 483 * @return zero on success 484 */ 485int avfilter_link(AVFilterContext *src, unsigned srcpad, 486 AVFilterContext *dst, unsigned dstpad); 487 488/** 489 * Negotiate the colorspace, dimensions, etc of all inputs to a filter. 490 * @param filter the filter to negotiate the properties for its inputs 491 * @return zero on successful negotiation 492 */ 493int avfilter_config_links(AVFilterContext *filter); 494 495/** 496 * Request a picture buffer with a specific set of permissions. 497 * @param link the output link to the filter from which the picture will 498 * be requested 499 * @param perms the required access permissions 500 * @return A reference to the picture. This must be unreferenced with 501 * avfilter_unref_pic when you are finished with it. 502 */ 503AVFilterPicRef *avfilter_get_video_buffer(AVFilterLink *link, int perms); 504 505/** 506 * Request an input frame from the filter at the other end of the link. 507 * @param link the input link 508 * @return zero on success 509 */ 510int avfilter_request_frame(AVFilterLink *link); 511 512/** 513 * Poll a frame from the filter chain. 514 * @param link the input link 515 * @return the number of immediately available frames, a negative 516 * number in case of error 517 */ 518int avfilter_poll_frame(AVFilterLink *link); 519 520/** 521 * Notify the next filter of the start of a frame. 522 * @param link the output link the frame will be sent over 523 * @param picref A reference to the frame about to be sent. The data for this 524 * frame need only be valid once draw_slice() is called for that 525 * portion. The receiving filter will free this reference when 526 * it no longer needs it. 527 */ 528void avfilter_start_frame(AVFilterLink *link, AVFilterPicRef *picref); 529 530/** 531 * Notify the next filter that the current frame has finished. 532 * @param link the output link the frame was sent over 533 */ 534void avfilter_end_frame(AVFilterLink *link); 535 536/** 537 * Send a slice to the next filter. 538 * @param link the output link over which the frame is being sent 539 * @param y offset in pixels from the top of the image for this slice 540 * @param h height of this slice in pixels 541 */ 542void avfilter_draw_slice(AVFilterLink *link, int y, int h); 543 544/** Initialize the filter system. Registers all builtin filters */ 545void avfilter_register_all(void); 546 547/** Uninitialize the filter system. Unregisters all filters */ 548void avfilter_uninit(void); 549 550/** 551 * Register a filter. This is only needed if you plan to use 552 * avfilter_get_by_name later to lookup the AVFilter structure by name. A 553 * filter can still by instantiated with avfilter_open even if it is not 554 * registered. 555 * @param filter the filter to register 556 */ 557void avfilter_register(AVFilter *filter); 558 559/** 560 * Gets a filter definition matching the given name. 561 * @param name the filter name to find 562 * @return the filter definition, if any matching one is registered. 563 * NULL if none found. 564 */ 565AVFilter *avfilter_get_by_name(const char *name); 566 567/** 568 * Create a filter instance. 569 * @param filter the filter to create an instance of 570 * @param inst_name Name to give to the new instance. Can be NULL for none. 571 * @return Pointer to the new instance on success. NULL on failure. 572 */ 573AVFilterContext *avfilter_open(AVFilter *filter, const char *inst_name); 574 575/** 576 * Initialize a filter. 577 * @param filter the filter to initialize 578 * @param args A string of parameters to use when initializing the filter. 579 * The format and meaning of this string varies by filter. 580 * @param opaque Any extra non-string data needed by the filter. The meaning 581 * of this parameter varies by filter. 582 * @return zero on success 583 */ 584int avfilter_init_filter(AVFilterContext *filter, const char *args, void *opaque); 585 586/** 587 * Destroy a filter. 588 * @param filter the filter to destroy 589 */ 590void avfilter_destroy(AVFilterContext *filter); 591 592/** 593 * Insert a filter in the middle of an existing link. 594 * @param link the link into which the filter should be inserted 595 * @param filt the filter to be inserted 596 * @param in the input pad on the filter to connect 597 * @param out the output pad on the filter to connect 598 * @return zero on success 599 */ 600int avfilter_insert_filter(AVFilterLink *link, AVFilterContext *filt, 601 unsigned in, unsigned out); 602 603/** 604 * Insert a new pad. 605 * @param idx Insertion point. Pad is inserted at the end if this point 606 * is beyond the end of the list of pads. 607 * @param count Pointer to the number of pads in the list 608 * @param padidx_off Offset within an AVFilterLink structure to the element 609 * to increment when inserting a new pad causes link 610 * numbering to change 611 * @param pads Pointer to the pointer to the beginning of the list of pads 612 * @param links Pointer to the pointer to the beginning of the list of links 613 * @param newpad The new pad to add. A copy is made when adding. 614 */ 615void avfilter_insert_pad(unsigned idx, unsigned *count, size_t padidx_off, 616 AVFilterPad **pads, AVFilterLink ***links, 617 AVFilterPad *newpad); 618 619/** Insert a new input pad for the filter. */ 620static inline void avfilter_insert_inpad(AVFilterContext *f, unsigned index, 621 AVFilterPad *p) 622{ 623 avfilter_insert_pad(index, &f->input_count, offsetof(AVFilterLink, dstpad), 624 &f->input_pads, &f->inputs, p); 625} 626 627/** Insert a new output pad for the filter. */ 628static inline void avfilter_insert_outpad(AVFilterContext *f, unsigned index, 629 AVFilterPad *p) 630{ 631 avfilter_insert_pad(index, &f->output_count, offsetof(AVFilterLink, srcpad), 632 &f->output_pads, &f->outputs, p); 633} 634 635#endif /* AVFILTER_AVFILTER_H */ 636