Showing the changes to libavfilter/avfilter.h (1 of 1 file). Show all
Unified · Split
| @@ -412,20 +412,42 @@ enum AVMediaType avfilter_pad_get_type(const AVFilterPad *pads, int pad_idx); · 411 unmodified lines | ||
| 412 | 412 | * callback functions used to interact with the filter. |
| 413 | 413 | */ |
| 414 | 414 | typedef struct AVFilter { |
| 415 | − const char *name; ///< filter name | |
| 415 | + /** | |
| 416 | + * Filter name. Must be non-NULL and unique among filters. | |
| 417 | + */ | |
| 418 | + const char *name; | |
| 416 | 419 | |
| 417 | 420 | /** |
| 418 | − * A description for the filter. You should use the | |
| 419 | − * NULL_IF_CONFIG_SMALL() macro to define it. | |
| 421 | + * A description of the filter. May be NULL. | |
| 422 | + * | |
| 423 | + * You should use the NULL_IF_CONFIG_SMALL() macro to define it. | |
| 420 | 424 | */ |
| 421 | 425 | const char *description; |
| 422 | 426 | |
| 423 | − const AVFilterPad *inputs; ///< NULL terminated list of inputs. NULL if none | |
| 424 | − const AVFilterPad *outputs; ///< NULL terminated list of outputs. NULL if none | |
| 427 | + /** | |
| 428 | + * List of inputs, terminated by a zeroed element. | |
| 429 | + * | |
| 430 | + * NULL if there are no (static) inputs. Instances of filters with | |
| 431 | + * AVFILTER_FLAG_DYNAMIC_INPUTS set may have more inputs than present in | |
| 432 | + * this list. | |
| 433 | + */ | |
| 434 | + const AVFilterPad *inputs; | |
| 435 | + /** | |
| 436 | + * List of outputs, terminated by a zeroed element. | |
| 437 | + * | |
| 438 | + * NULL if there are no (static) outputs. Instances of filters with | |
| 439 | + * AVFILTER_FLAG_DYNAMIC_OUTPUTS set may have more outputs than present in | |
| 440 | + * this list. | |
| 441 | + */ | |
| 442 | + const AVFilterPad *outputs; | |
| 425 | 443 | |
| 426 | 444 | /** |
| 427 | − * A class for the private data, used to access filter private | |
| 428 | − * AVOptions. | |
| 445 | + * A class for the private data, used to declare filter private AVOptions. | |
| 446 | + * This field is NULL for filters that do not declare any options. | |
| 447 | + * | |
| 448 | + * If this field is non-NULL, the first member of the filter private data | |
| 449 | + * must be a pointer to AVClass, which will be set by libavfilter generic | |
| 450 | + * code to this class. | |
| 429 | 451 | */ |
| 430 | 452 | const AVClass *priv_class; |
| 431 | 453 | |
| @@ -443,29 +465,71 @@ typedef struct AVFilter { · 11 unmodified lines | ||
| 443 | 465 | */ |
| 444 | 466 | |
| 445 | 467 | /** |
| 446 | − * Filter initialization function. Called when all the options have been | |
| 447 | − * set. | |
| 468 | + * Filter initialization function. | |
| 469 | + * | |
| 470 | + * This callback will be called only once during the filter lifetime, after | |
| 471 | + * all the options have been set, but before links between filters are | |
| 472 | + * established and format negotiation is done. | |
| 473 | + * | |
| 474 | + * Basic filter initialization should be done here. Filters with dynamic | |
| 475 | + * inputs and/or outputs should create those inputs/outputs here based on | |
| 476 | + * provided options. No more changes to this filter's inputs/outputs can be | |
| 477 | + * done after this callback. | |
| 478 | + * | |
| 479 | + * This callback must not assume that the filter links exist or frame | |
| 480 | + * parameters are known. | |
| 481 | + * | |
| 482 | + * @ref AVFilter.uninit "uninit" is guaranteed to be called even if | |
| 483 | + * initialization fails, so this callback does not have to clean up on | |
| 484 | + * failure. | |
| 485 | + * | |
| 486 | + * @return 0 on success, a negative AVERROR on failure | |
| 448 | 487 | */ |
| 449 | 488 | int (*init)(AVFilterContext *ctx); |
| 450 | 489 | |
| 451 | 490 | /** |
| 452 | − * Should be set instead of init by the filters that want to pass a | |
| 453 | − * dictionary of AVOptions to nested contexts that are allocated in | |
| 454 | − * init. | |
| 491 | + * Should be set instead of @ref AVFilter.init "init" by the filters that | |
| 492 | + * want to pass a dictionary of AVOptions to nested contexts that are | |
| 493 | + * allocated during init. | |
| 494 | + * | |
| 495 | + * On return, the options dict should be freed and replaced with one that | |
| 496 | + * contains all the options which could not be processed by this filter (or | |
| 497 | + * with NULL if all the options were processed). | |
| 498 | + * | |
| 499 | + * Otherwise the semantics is the same as for @ref AVFilter.init "init". | |
| 455 | 500 | */ |
| 456 | 501 | int (*init_dict)(AVFilterContext *ctx, AVDictionary **options); |
| 457 | 502 | |
| 458 | 503 | /** |
| 459 | − * Filter uninitialization function. Should deallocate any memory held | |
| 460 | − * by the filter, release any buffer references, etc. This does not need | |
| 461 | − * to deallocate the AVFilterContext->priv memory itself. | |
| 504 | + * Filter uninitialization function. | |
| 505 | + * | |
| 506 | + * Called only once right before the filter is freed. Should deallocate any | |
| 507 | + * memory held by the filter, release any buffer references, etc. It does | |
| 508 | + * not need to deallocate the AVFilterContext.priv memory itself. | |
| 509 | + * | |
| 510 | + * This callback may be called even if @ref AVFilter.init "init" was not | |
| 511 | + * called or failed, so it must be prepared to handle such a situation. | |
| 462 | 512 | */ |
| 463 | 513 | void (*uninit)(AVFilterContext *ctx); |
| 464 | 514 | |
| 465 | 515 | /** |
| 466 | − * Queries formats supported by the filter and its pads, and sets the | |
| 467 | − * in_formats for links connected to its output pads, and out_formats | |
| 468 | − * for links connected to its input pads. | |
| 516 | + * Query formats supported by the filter on its inputs and outputs. | |
| 517 | + * | |
| 518 | + * This callback is called after the filter is initialized (so the inputs | |
| 519 | + * and outputs are fixed), shortly before the format negotiation. This | |
| 520 | + * callback may be called more than once. | |
| 521 | + * | |
| 522 | + * This callback must set AVFilterLink.out_formats on every input link and | |
| 523 | + * AVFilterLink.in_formats on every output link to a list of pixel/sample | |
| 524 | + * formats that the filter supports on that link. For audio links, this | |
| 525 | + * filter must also set @ref AVFilterLink.in_samplerates "in_samplerates" / | |
| 526 | + * @ref AVFilterLink.out_samplerates "out_samplerates" and | |
| 527 | + * @ref AVFilterLink.in_channel_layouts "in_channel_layouts" / | |
| 528 | + * @ref AVFilterLink.out_channel_layouts "out_channel_layouts" analogously. | |
| 529 | + * | |
| 530 | + * This callback may be NULL for filters with one input, in which case | |
| 531 | + * libavfilter assumes that it supports all input formats and preserves | |
| 532 | + * them on output. | |
| 469 | 533 | * |
| 470 | 534 | * @return zero on success, a negative value corresponding to an |
| 471 | 535 | * AVERROR code otherwise |
| @@ -474,6 +538,10 @@ typedef struct AVFilter { · 2 unmodified lines | ||
| 474 | 538 | |
| 475 | 539 | int priv_size; ///< size of private data to allocate for the filter |
| 476 | 540 | |
| 541 | + /** | |
| 542 | + * Used by the filter registration system. Must not be touched by any other | |
| 543 | + * code. | |
| 544 | + */ | |
| 477 | 545 | struct AVFilter *next; |
| 478 | 546 | } AVFilter; |
| 479 | 547 | |