avfilter.h (54769B)
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 /** 26 * @file 27 * @ingroup lavfi 28 * Main libavfilter public API header 29 */ 30 31 /** 32 * @defgroup lavfi libavfilter 33 * Graph-based frame editing library. 34 * 35 * @{ 36 */ 37 38 #include <stddef.h> 39 40 #include "libavutil/attributes.h" 41 #include "libavutil/avutil.h" 42 #include "libavutil/buffer.h" 43 #include "libavutil/dict.h" 44 #include "libavutil/frame.h" 45 #include "libavutil/log.h" 46 #include "libavutil/samplefmt.h" 47 #include "libavutil/pixfmt.h" 48 #include "libavutil/rational.h" 49 50 #include "libavfilter/version_major.h" 51 #ifndef HAVE_AV_CONFIG_H 52 /* When included as part of the ffmpeg build, only include the major version 53 * to avoid unnecessary rebuilds. When included externally, keep including 54 * the full version information. */ 55 #include "libavfilter/version.h" 56 #endif 57 58 /** 59 * Return the LIBAVFILTER_VERSION_INT constant. 60 */ 61 unsigned avfilter_version(void); 62 63 /** 64 * Return the libavfilter build-time configuration. 65 */ 66 const char *avfilter_configuration(void); 67 68 /** 69 * Return the libavfilter license. 70 */ 71 const char *avfilter_license(void); 72 73 typedef struct AVFilterContext AVFilterContext; 74 typedef struct AVFilterLink AVFilterLink; 75 typedef struct AVFilterPad AVFilterPad; 76 typedef struct AVFilterFormats AVFilterFormats; 77 typedef struct AVFilterChannelLayouts AVFilterChannelLayouts; 78 79 /** 80 * Get the name of an AVFilterPad. 81 * 82 * @param pads an array of AVFilterPads 83 * @param pad_idx index of the pad in the array; it is the caller's 84 * responsibility to ensure the index is valid 85 * 86 * @return name of the pad_idx'th pad in pads 87 */ 88 const char *avfilter_pad_get_name(const AVFilterPad *pads, int pad_idx); 89 90 /** 91 * Get the type of an AVFilterPad. 92 * 93 * @param pads an array of AVFilterPads 94 * @param pad_idx index of the pad in the array; it is the caller's 95 * responsibility to ensure the index is valid 96 * 97 * @return type of the pad_idx'th pad in pads 98 */ 99 enum AVMediaType avfilter_pad_get_type(const AVFilterPad *pads, int pad_idx); 100 101 /** 102 * The number of the filter inputs is not determined just by AVFilter.inputs. 103 * The filter might add additional inputs during initialization depending on the 104 * options supplied to it. 105 */ 106 #define AVFILTER_FLAG_DYNAMIC_INPUTS (1 << 0) 107 /** 108 * The number of the filter outputs is not determined just by AVFilter.outputs. 109 * The filter might add additional outputs during initialization depending on 110 * the options supplied to it. 111 */ 112 #define AVFILTER_FLAG_DYNAMIC_OUTPUTS (1 << 1) 113 /** 114 * The filter supports multithreading by splitting frames into multiple parts 115 * and processing them concurrently. 116 */ 117 #define AVFILTER_FLAG_SLICE_THREADS (1 << 2) 118 /** 119 * The filter is a "metadata" filter - it does not modify the frame data in any 120 * way. It may only affect the metadata (i.e. those fields copied by 121 * av_frame_copy_props()). 122 * 123 * More precisely, this means: 124 * - video: the data of any frame output by the filter must be exactly equal to 125 * some frame that is received on one of its inputs. Furthermore, all frames 126 * produced on a given output must correspond to frames received on the same 127 * input and their order must be unchanged. Note that the filter may still 128 * drop or duplicate the frames. 129 * - audio: the data produced by the filter on any of its outputs (viewed e.g. 130 * as an array of interleaved samples) must be exactly equal to the data 131 * received by the filter on one of its inputs. 132 */ 133 #define AVFILTER_FLAG_METADATA_ONLY (1 << 3) 134 135 /** 136 * The filter can create hardware frames using AVFilterContext.hw_device_ctx. 137 */ 138 #define AVFILTER_FLAG_HWDEVICE (1 << 4) 139 /** 140 * Some filters support a generic "enable" expression option that can be used 141 * to enable or disable a filter in the timeline. Filters supporting this 142 * option have this flag set. When the enable expression is false, the default 143 * no-op filter_frame() function is called in place of the filter_frame() 144 * callback defined on each input pad, thus the frame is passed unchanged to 145 * the next filters. 146 */ 147 #define AVFILTER_FLAG_SUPPORT_TIMELINE_GENERIC (1 << 16) 148 /** 149 * Same as AVFILTER_FLAG_SUPPORT_TIMELINE_GENERIC, except that the filter will 150 * have its filter_frame() callback(s) called as usual even when the enable 151 * expression is false. The filter will disable filtering within the 152 * filter_frame() callback(s) itself, for example executing code depending on 153 * the AVFilterContext->is_disabled value. 154 */ 155 #define AVFILTER_FLAG_SUPPORT_TIMELINE_INTERNAL (1 << 17) 156 /** 157 * Handy mask to test whether the filter supports or no the timeline feature 158 * (internally or generically). 159 */ 160 #define AVFILTER_FLAG_SUPPORT_TIMELINE (AVFILTER_FLAG_SUPPORT_TIMELINE_GENERIC | AVFILTER_FLAG_SUPPORT_TIMELINE_INTERNAL) 161 162 /** 163 * Filter definition. This defines the pads a filter contains, and all the 164 * callback functions used to interact with the filter. 165 */ 166 typedef struct AVFilter { 167 /** 168 * Filter name. Must be non-NULL and unique among filters. 169 */ 170 const char *name; 171 172 /** 173 * A description of the filter. May be NULL. 174 * 175 * You should use the NULL_IF_CONFIG_SMALL() macro to define it. 176 */ 177 const char *description; 178 179 /** 180 * List of static inputs. 181 * 182 * NULL if there are no (static) inputs. Instances of filters with 183 * AVFILTER_FLAG_DYNAMIC_INPUTS set may have more inputs than present in 184 * this list. 185 */ 186 const AVFilterPad *inputs; 187 188 /** 189 * List of static outputs. 190 * 191 * NULL if there are no (static) outputs. Instances of filters with 192 * AVFILTER_FLAG_DYNAMIC_OUTPUTS set may have more outputs than present in 193 * this list. 194 */ 195 const AVFilterPad *outputs; 196 197 /** 198 * A class for the private data, used to declare filter private AVOptions. 199 * This field is NULL for filters that do not declare any options. 200 * 201 * If this field is non-NULL, the first member of the filter private data 202 * must be a pointer to AVClass, which will be set by libavfilter generic 203 * code to this class. 204 */ 205 const AVClass *priv_class; 206 207 /** 208 * A combination of AVFILTER_FLAG_* 209 */ 210 int flags; 211 212 /***************************************************************** 213 * All fields below this line are not part of the public API. They 214 * may not be used outside of libavfilter and can be changed and 215 * removed at will. 216 * New public fields should be added right above. 217 ***************************************************************** 218 */ 219 220 /** 221 * The number of entries in the list of inputs. 222 */ 223 uint8_t nb_inputs; 224 225 /** 226 * The number of entries in the list of outputs. 227 */ 228 uint8_t nb_outputs; 229 230 /** 231 * This field determines the state of the formats union. 232 * It is an enum FilterFormatsState value. 233 */ 234 uint8_t formats_state; 235 236 /** 237 * Filter pre-initialization function 238 * 239 * This callback will be called immediately after the filter context is 240 * allocated, to allow allocating and initing sub-objects. 241 * 242 * If this callback is not NULL, the uninit callback will be called on 243 * allocation failure. 244 * 245 * @return 0 on success, 246 * AVERROR code on failure (but the code will be 247 * dropped and treated as ENOMEM by the calling code) 248 */ 249 int (*preinit)(AVFilterContext *ctx); 250 251 /** 252 * Filter initialization function. 253 * 254 * This callback will be called only once during the filter lifetime, after 255 * all the options have been set, but before links between filters are 256 * established and format negotiation is done. 257 * 258 * Basic filter initialization should be done here. Filters with dynamic 259 * inputs and/or outputs should create those inputs/outputs here based on 260 * provided options. No more changes to this filter's inputs/outputs can be 261 * done after this callback. 262 * 263 * This callback must not assume that the filter links exist or frame 264 * parameters are known. 265 * 266 * @ref AVFilter.uninit "uninit" is guaranteed to be called even if 267 * initialization fails, so this callback does not have to clean up on 268 * failure. 269 * 270 * @return 0 on success, a negative AVERROR on failure 271 */ 272 int (*init)(AVFilterContext *ctx); 273 274 /** 275 * Filter uninitialization function. 276 * 277 * Called only once right before the filter is freed. Should deallocate any 278 * memory held by the filter, release any buffer references, etc. It does 279 * not need to deallocate the AVFilterContext.priv memory itself. 280 * 281 * This callback may be called even if @ref AVFilter.init "init" was not 282 * called or failed, so it must be prepared to handle such a situation. 283 */ 284 void (*uninit)(AVFilterContext *ctx); 285 286 /** 287 * The state of the following union is determined by formats_state. 288 * See the documentation of enum FilterFormatsState in internal.h. 289 */ 290 union { 291 /** 292 * Query formats supported by the filter on its inputs and outputs. 293 * 294 * This callback is called after the filter is initialized (so the inputs 295 * and outputs are fixed), shortly before the format negotiation. This 296 * callback may be called more than once. 297 * 298 * This callback must set ::AVFilterLink's 299 * @ref AVFilterFormatsConfig.formats "outcfg.formats" 300 * on every input link and 301 * @ref AVFilterFormatsConfig.formats "incfg.formats" 302 * on every output link to a list of pixel/sample formats that the filter 303 * supports on that link. 304 * For video links, this filter may also set 305 * @ref AVFilterFormatsConfig.color_spaces "incfg.color_spaces" 306 * / 307 * @ref AVFilterFormatsConfig.color_spaces "outcfg.color_spaces" 308 * and @ref AVFilterFormatsConfig.color_ranges "incfg.color_ranges" 309 * / 310 * @ref AVFilterFormatsConfig.color_ranges "outcfg.color_ranges" 311 * analogously. 312 * For audio links, this filter must also set 313 * @ref AVFilterFormatsConfig.samplerates "incfg.samplerates" 314 * / 315 * @ref AVFilterFormatsConfig.samplerates "outcfg.samplerates" 316 * and @ref AVFilterFormatsConfig.channel_layouts "incfg.channel_layouts" 317 * / 318 * @ref AVFilterFormatsConfig.channel_layouts "outcfg.channel_layouts" 319 * analogously. 320 * 321 * This callback must never be NULL if the union is in this state. 322 * 323 * @return zero on success, a negative value corresponding to an 324 * AVERROR code otherwise 325 */ 326 int (*query_func)(AVFilterContext *); 327 /** 328 * A pointer to an array of admissible pixel formats delimited 329 * by AV_PIX_FMT_NONE. The generic code will use this list 330 * to indicate that this filter supports each of these pixel formats, 331 * provided that all inputs and outputs use the same pixel format. 332 * 333 * In addition to that the generic code will mark all inputs 334 * and all outputs as supporting all color spaces and ranges, as 335 * long as all inputs and outputs use the same color space/range. 336 * 337 * This list must never be NULL if the union is in this state. 338 * The type of all inputs and outputs of filters using this must 339 * be AVMEDIA_TYPE_VIDEO. 340 */ 341 const enum AVPixelFormat *pixels_list; 342 /** 343 * Analogous to pixels, but delimited by AV_SAMPLE_FMT_NONE 344 * and restricted to filters that only have AVMEDIA_TYPE_AUDIO 345 * inputs and outputs. 346 * 347 * In addition to that the generic code will mark all inputs 348 * and all outputs as supporting all sample rates and every 349 * channel count and channel layout, as long as all inputs 350 * and outputs use the same sample rate and channel count/layout. 351 */ 352 const enum AVSampleFormat *samples_list; 353 /** 354 * Equivalent to { pix_fmt, AV_PIX_FMT_NONE } as pixels_list. 355 */ 356 enum AVPixelFormat pix_fmt; 357 /** 358 * Equivalent to { sample_fmt, AV_SAMPLE_FMT_NONE } as samples_list. 359 */ 360 enum AVSampleFormat sample_fmt; 361 } formats; 362 363 int priv_size; ///< size of private data to allocate for the filter 364 365 int flags_internal; ///< Additional flags for avfilter internal use only. 366 367 /** 368 * Make the filter instance process a command. 369 * 370 * @param cmd the command to process, for handling simplicity all commands must be alphanumeric only 371 * @param arg the argument for the command 372 * @param res a buffer with size res_size where the filter(s) can return a response. This must not change when the command is not supported. 373 * @param flags if AVFILTER_CMD_FLAG_FAST is set and the command would be 374 * time consuming then a filter should treat it like an unsupported command 375 * 376 * @returns >=0 on success otherwise an error code. 377 * AVERROR(ENOSYS) on unsupported commands 378 */ 379 int (*process_command)(AVFilterContext *, const char *cmd, const char *arg, char *res, int res_len, int flags); 380 381 /** 382 * Filter activation function. 383 * 384 * Called when any processing is needed from the filter, instead of any 385 * filter_frame and request_frame on pads. 386 * 387 * The function must examine inlinks and outlinks and perform a single 388 * step of processing. If there is nothing to do, the function must do 389 * nothing and not return an error. If more steps are or may be 390 * possible, it must use ff_filter_set_ready() to schedule another 391 * activation. 392 */ 393 int (*activate)(AVFilterContext *ctx); 394 } AVFilter; 395 396 /** 397 * Get the number of elements in an AVFilter's inputs or outputs array. 398 */ 399 unsigned avfilter_filter_pad_count(const AVFilter *filter, int is_output); 400 401 /** 402 * Process multiple parts of the frame concurrently. 403 */ 404 #define AVFILTER_THREAD_SLICE (1 << 0) 405 406 /** An instance of a filter */ 407 struct AVFilterContext { 408 const AVClass *av_class; ///< needed for av_log() and filters common options 409 410 const AVFilter *filter; ///< the AVFilter of which this is an instance 411 412 char *name; ///< name of this filter instance 413 414 AVFilterPad *input_pads; ///< array of input pads 415 AVFilterLink **inputs; ///< array of pointers to input links 416 unsigned nb_inputs; ///< number of input pads 417 418 AVFilterPad *output_pads; ///< array of output pads 419 AVFilterLink **outputs; ///< array of pointers to output links 420 unsigned nb_outputs; ///< number of output pads 421 422 void *priv; ///< private data for use by the filter 423 424 struct AVFilterGraph *graph; ///< filtergraph this filter belongs to 425 426 /** 427 * Type of multithreading being allowed/used. A combination of 428 * AVFILTER_THREAD_* flags. 429 * 430 * May be set by the caller before initializing the filter to forbid some 431 * or all kinds of multithreading for this filter. The default is allowing 432 * everything. 433 * 434 * When the filter is initialized, this field is combined using bit AND with 435 * AVFilterGraph.thread_type to get the final mask used for determining 436 * allowed threading types. I.e. a threading type needs to be set in both 437 * to be allowed. 438 * 439 * After the filter is initialized, libavfilter sets this field to the 440 * threading type that is actually used (0 for no multithreading). 441 */ 442 int thread_type; 443 444 /** 445 * Max number of threads allowed in this filter instance. 446 * If <= 0, its value is ignored. 447 * Overrides global number of threads set per filter graph. 448 */ 449 int nb_threads; 450 451 struct AVFilterCommand *command_queue; 452 453 char *enable_str; ///< enable expression string 454 void *enable; ///< parsed expression (AVExpr*) 455 double *var_values; ///< variable values for the enable expression 456 int is_disabled; ///< the enabled state from the last expression evaluation 457 458 /** 459 * For filters which will create hardware frames, sets the device the 460 * filter should create them in. All other filters will ignore this field: 461 * in particular, a filter which consumes or processes hardware frames will 462 * instead use the hw_frames_ctx field in AVFilterLink to carry the 463 * hardware context information. 464 * 465 * May be set by the caller on filters flagged with AVFILTER_FLAG_HWDEVICE 466 * before initializing the filter with avfilter_init_str() or 467 * avfilter_init_dict(). 468 */ 469 AVBufferRef *hw_device_ctx; 470 471 /** 472 * Ready status of the filter. 473 * A non-0 value means that the filter needs activating; 474 * a higher value suggests a more urgent activation. 475 */ 476 unsigned ready; 477 478 /** 479 * Sets the number of extra hardware frames which the filter will 480 * allocate on its output links for use in following filters or by 481 * the caller. 482 * 483 * Some hardware filters require all frames that they will use for 484 * output to be defined in advance before filtering starts. For such 485 * filters, any hardware frame pools used for output must therefore be 486 * of fixed size. The extra frames set here are on top of any number 487 * that the filter needs internally in order to operate normally. 488 * 489 * This field must be set before the graph containing this filter is 490 * configured. 491 */ 492 int extra_hw_frames; 493 }; 494 495 /** 496 * Lists of formats / etc. supported by an end of a link. 497 * 498 * This structure is directly part of AVFilterLink, in two copies: 499 * one for the source filter, one for the destination filter. 500 501 * These lists are used for negotiating the format to actually be used, 502 * which will be loaded into the format and channel_layout members of 503 * AVFilterLink, when chosen. 504 */ 505 typedef struct AVFilterFormatsConfig { 506 507 /** 508 * List of supported formats (pixel or sample). 509 */ 510 AVFilterFormats *formats; 511 512 /** 513 * Lists of supported sample rates, only for audio. 514 */ 515 AVFilterFormats *samplerates; 516 517 /** 518 * Lists of supported channel layouts, only for audio. 519 */ 520 AVFilterChannelLayouts *channel_layouts; 521 522 /** 523 * Lists of supported YUV color metadata, only for YUV video. 524 */ 525 AVFilterFormats *color_spaces; ///< AVColorSpace 526 AVFilterFormats *color_ranges; ///< AVColorRange 527 528 } AVFilterFormatsConfig; 529 530 /** 531 * A link between two filters. This contains pointers to the source and 532 * destination filters between which this link exists, and the indexes of 533 * the pads involved. In addition, this link also contains the parameters 534 * which have been negotiated and agreed upon between the filter, such as 535 * image dimensions, format, etc. 536 * 537 * Applications must not normally access the link structure directly. 538 * Use the buffersrc and buffersink API instead. 539 * In the future, access to the header may be reserved for filters 540 * implementation. 541 */ 542 struct AVFilterLink { 543 AVFilterContext *src; ///< source filter 544 AVFilterPad *srcpad; ///< output pad on the source filter 545 546 AVFilterContext *dst; ///< dest filter 547 AVFilterPad *dstpad; ///< input pad on the dest filter 548 549 enum AVMediaType type; ///< filter media type 550 551 int format; ///< agreed upon media format 552 553 /* These parameters apply only to video */ 554 int w; ///< agreed upon image width 555 int h; ///< agreed upon image height 556 AVRational sample_aspect_ratio; ///< agreed upon sample aspect ratio 557 /** 558 * For non-YUV links, these are respectively set to fallback values (as 559 * appropriate for that colorspace). 560 * 561 * Note: This includes grayscale formats, as these are currently treated 562 * as forced full range always. 563 */ 564 enum AVColorSpace colorspace; ///< agreed upon YUV color space 565 enum AVColorRange color_range; ///< agreed upon YUV color range 566 567 /* These parameters apply only to audio */ 568 int sample_rate; ///< samples per second 569 AVChannelLayout ch_layout; ///< channel layout of current buffer (see libavutil/channel_layout.h) 570 571 /** 572 * Define the time base used by the PTS of the frames/samples 573 * which will pass through this link. 574 * During the configuration stage, each filter is supposed to 575 * change only the output timebase, while the timebase of the 576 * input link is assumed to be an unchangeable property. 577 */ 578 AVRational time_base; 579 580 /***************************************************************** 581 * All fields below this line are not part of the public API. They 582 * may not be used outside of libavfilter and can be changed and 583 * removed at will. 584 * New public fields should be added right above. 585 ***************************************************************** 586 */ 587 588 /** 589 * Lists of supported formats / etc. supported by the input filter. 590 */ 591 AVFilterFormatsConfig incfg; 592 593 /** 594 * Lists of supported formats / etc. supported by the output filter. 595 */ 596 AVFilterFormatsConfig outcfg; 597 598 /** 599 * Graph the filter belongs to. 600 */ 601 struct AVFilterGraph *graph; 602 603 /** 604 * Current timestamp of the link, as defined by the most recent 605 * frame(s), in link time_base units. 606 */ 607 int64_t current_pts; 608 609 /** 610 * Current timestamp of the link, as defined by the most recent 611 * frame(s), in AV_TIME_BASE units. 612 */ 613 int64_t current_pts_us; 614 615 /** 616 * Frame rate of the stream on the link, or 1/0 if unknown or variable; 617 * if left to 0/0, will be automatically copied from the first input 618 * of the source filter if it exists. 619 * 620 * Sources should set it to the best estimation of the real frame rate. 621 * If the source frame rate is unknown or variable, set this to 1/0. 622 * Filters should update it if necessary depending on their function. 623 * Sinks can use it to set a default output frame rate. 624 * It is similar to the r_frame_rate field in AVStream. 625 */ 626 AVRational frame_rate; 627 628 /** 629 * Minimum number of samples to filter at once. If filter_frame() is 630 * called with fewer samples, it will accumulate them in fifo. 631 * This field and the related ones must not be changed after filtering 632 * has started. 633 * If 0, all related fields are ignored. 634 */ 635 int min_samples; 636 637 /** 638 * Maximum number of samples to filter at once. If filter_frame() is 639 * called with more samples, it will split them. 640 */ 641 int max_samples; 642 643 /** 644 * Number of past frames sent through the link. 645 */ 646 int64_t frame_count_in, frame_count_out; 647 648 /** 649 * Number of past samples sent through the link. 650 */ 651 int64_t sample_count_in, sample_count_out; 652 653 /** 654 * True if a frame is currently wanted on the output of this filter. 655 * Set when ff_request_frame() is called by the output, 656 * cleared when a frame is filtered. 657 */ 658 int frame_wanted_out; 659 660 /** 661 * For hwaccel pixel formats, this should be a reference to the 662 * AVHWFramesContext describing the frames. 663 */ 664 AVBufferRef *hw_frames_ctx; 665 }; 666 667 /** 668 * Link two filters together. 669 * 670 * @param src the source filter 671 * @param srcpad index of the output pad on the source filter 672 * @param dst the destination filter 673 * @param dstpad index of the input pad on the destination filter 674 * @return zero on success 675 */ 676 int avfilter_link(AVFilterContext *src, unsigned srcpad, 677 AVFilterContext *dst, unsigned dstpad); 678 679 #if FF_API_LINK_PUBLIC 680 /** 681 * @deprecated this function should never be called by users 682 */ 683 attribute_deprecated 684 void avfilter_link_free(AVFilterLink **link); 685 686 /** 687 * @deprecated this function should never be called by users 688 */ 689 attribute_deprecated 690 int avfilter_config_links(AVFilterContext *filter); 691 #endif 692 693 #define AVFILTER_CMD_FLAG_ONE 1 ///< Stop once a filter understood the command (for target=all for example), fast filters are favored automatically 694 #define AVFILTER_CMD_FLAG_FAST 2 ///< Only execute command when its fast (like a video out that supports contrast adjustment in hw) 695 696 /** 697 * Make the filter instance process a command. 698 * It is recommended to use avfilter_graph_send_command(). 699 */ 700 int avfilter_process_command(AVFilterContext *filter, const char *cmd, const char *arg, char *res, int res_len, int flags); 701 702 /** 703 * Iterate over all registered filters. 704 * 705 * @param opaque a pointer where libavfilter will store the iteration state. Must 706 * point to NULL to start the iteration. 707 * 708 * @return the next registered filter or NULL when the iteration is 709 * finished 710 */ 711 const AVFilter *av_filter_iterate(void **opaque); 712 713 /** 714 * Get a filter definition matching the given name. 715 * 716 * @param name the filter name to find 717 * @return the filter definition, if any matching one is registered. 718 * NULL if none found. 719 */ 720 const AVFilter *avfilter_get_by_name(const char *name); 721 722 723 /** 724 * Initialize a filter with the supplied parameters. 725 * 726 * @param ctx uninitialized filter context to initialize 727 * @param args Options to initialize the filter with. This must be a 728 * ':'-separated list of options in the 'key=value' form. 729 * May be NULL if the options have been set directly using the 730 * AVOptions API or there are no options that need to be set. 731 * @return 0 on success, a negative AVERROR on failure 732 */ 733 int avfilter_init_str(AVFilterContext *ctx, const char *args); 734 735 /** 736 * Initialize a filter with the supplied dictionary of options. 737 * 738 * @param ctx uninitialized filter context to initialize 739 * @param options An AVDictionary filled with options for this filter. On 740 * return this parameter will be destroyed and replaced with 741 * a dict containing options that were not found. This dictionary 742 * must be freed by the caller. 743 * May be NULL, then this function is equivalent to 744 * avfilter_init_str() with the second parameter set to NULL. 745 * @return 0 on success, a negative AVERROR on failure 746 * 747 * @note This function and avfilter_init_str() do essentially the same thing, 748 * the difference is in manner in which the options are passed. It is up to the 749 * calling code to choose whichever is more preferable. The two functions also 750 * behave differently when some of the provided options are not declared as 751 * supported by the filter. In such a case, avfilter_init_str() will fail, but 752 * this function will leave those extra options in the options AVDictionary and 753 * continue as usual. 754 */ 755 int avfilter_init_dict(AVFilterContext *ctx, AVDictionary **options); 756 757 /** 758 * Free a filter context. This will also remove the filter from its 759 * filtergraph's list of filters. 760 * 761 * @param filter the filter to free 762 */ 763 void avfilter_free(AVFilterContext *filter); 764 765 /** 766 * Insert a filter in the middle of an existing link. 767 * 768 * @param link the link into which the filter should be inserted 769 * @param filt the filter to be inserted 770 * @param filt_srcpad_idx the input pad on the filter to connect 771 * @param filt_dstpad_idx the output pad on the filter to connect 772 * @return zero on success 773 */ 774 int avfilter_insert_filter(AVFilterLink *link, AVFilterContext *filt, 775 unsigned filt_srcpad_idx, unsigned filt_dstpad_idx); 776 777 /** 778 * @return AVClass for AVFilterContext. 779 * 780 * @see av_opt_find(). 781 */ 782 const AVClass *avfilter_get_class(void); 783 784 /** 785 * A function pointer passed to the @ref AVFilterGraph.execute callback to be 786 * executed multiple times, possibly in parallel. 787 * 788 * @param ctx the filter context the job belongs to 789 * @param arg an opaque parameter passed through from @ref 790 * AVFilterGraph.execute 791 * @param jobnr the index of the job being executed 792 * @param nb_jobs the total number of jobs 793 * 794 * @return 0 on success, a negative AVERROR on error 795 */ 796 typedef int (avfilter_action_func)(AVFilterContext *ctx, void *arg, int jobnr, int nb_jobs); 797 798 /** 799 * A function executing multiple jobs, possibly in parallel. 800 * 801 * @param ctx the filter context to which the jobs belong 802 * @param func the function to be called multiple times 803 * @param arg the argument to be passed to func 804 * @param ret a nb_jobs-sized array to be filled with return values from each 805 * invocation of func 806 * @param nb_jobs the number of jobs to execute 807 * 808 * @return 0 on success, a negative AVERROR on error 809 */ 810 typedef int (avfilter_execute_func)(AVFilterContext *ctx, avfilter_action_func *func, 811 void *arg, int *ret, int nb_jobs); 812 813 typedef struct AVFilterGraph { 814 const AVClass *av_class; 815 AVFilterContext **filters; 816 unsigned nb_filters; 817 818 char *scale_sws_opts; ///< sws options to use for the auto-inserted scale filters 819 820 /** 821 * Type of multithreading allowed for filters in this graph. A combination 822 * of AVFILTER_THREAD_* flags. 823 * 824 * May be set by the caller at any point, the setting will apply to all 825 * filters initialized after that. The default is allowing everything. 826 * 827 * When a filter in this graph is initialized, this field is combined using 828 * bit AND with AVFilterContext.thread_type to get the final mask used for 829 * determining allowed threading types. I.e. a threading type needs to be 830 * set in both to be allowed. 831 */ 832 int thread_type; 833 834 /** 835 * Maximum number of threads used by filters in this graph. May be set by 836 * the caller before adding any filters to the filtergraph. Zero (the 837 * default) means that the number of threads is determined automatically. 838 */ 839 int nb_threads; 840 841 /** 842 * Opaque user data. May be set by the caller to an arbitrary value, e.g. to 843 * be used from callbacks like @ref AVFilterGraph.execute. 844 * Libavfilter will not touch this field in any way. 845 */ 846 void *opaque; 847 848 /** 849 * This callback may be set by the caller immediately after allocating the 850 * graph and before adding any filters to it, to provide a custom 851 * multithreading implementation. 852 * 853 * If set, filters with slice threading capability will call this callback 854 * to execute multiple jobs in parallel. 855 * 856 * If this field is left unset, libavfilter will use its internal 857 * implementation, which may or may not be multithreaded depending on the 858 * platform and build options. 859 */ 860 avfilter_execute_func *execute; 861 862 char *aresample_swr_opts; ///< swr options to use for the auto-inserted aresample filters, Access ONLY through AVOptions 863 } AVFilterGraph; 864 865 /** 866 * Allocate a filter graph. 867 * 868 * @return the allocated filter graph on success or NULL. 869 */ 870 AVFilterGraph *avfilter_graph_alloc(void); 871 872 /** 873 * Create a new filter instance in a filter graph. 874 * 875 * @param graph graph in which the new filter will be used 876 * @param filter the filter to create an instance of 877 * @param name Name to give to the new instance (will be copied to 878 * AVFilterContext.name). This may be used by the caller to identify 879 * different filters, libavfilter itself assigns no semantics to 880 * this parameter. May be NULL. 881 * 882 * @return the context of the newly created filter instance (note that it is 883 * also retrievable directly through AVFilterGraph.filters or with 884 * avfilter_graph_get_filter()) on success or NULL on failure. 885 */ 886 AVFilterContext *avfilter_graph_alloc_filter(AVFilterGraph *graph, 887 const AVFilter *filter, 888 const char *name); 889 890 /** 891 * Get a filter instance identified by instance name from graph. 892 * 893 * @param graph filter graph to search through. 894 * @param name filter instance name (should be unique in the graph). 895 * @return the pointer to the found filter instance or NULL if it 896 * cannot be found. 897 */ 898 AVFilterContext *avfilter_graph_get_filter(AVFilterGraph *graph, const char *name); 899 900 /** 901 * Create and add a filter instance into an existing graph. 902 * The filter instance is created from the filter filt and inited 903 * with the parameter args. opaque is currently ignored. 904 * 905 * In case of success put in *filt_ctx the pointer to the created 906 * filter instance, otherwise set *filt_ctx to NULL. 907 * 908 * @param name the instance name to give to the created filter instance 909 * @param graph_ctx the filter graph 910 * @return a negative AVERROR error code in case of failure, a non 911 * negative value otherwise 912 */ 913 int avfilter_graph_create_filter(AVFilterContext **filt_ctx, const AVFilter *filt, 914 const char *name, const char *args, void *opaque, 915 AVFilterGraph *graph_ctx); 916 917 /** 918 * Enable or disable automatic format conversion inside the graph. 919 * 920 * Note that format conversion can still happen inside explicitly inserted 921 * scale and aresample filters. 922 * 923 * @param flags any of the AVFILTER_AUTO_CONVERT_* constants 924 */ 925 void avfilter_graph_set_auto_convert(AVFilterGraph *graph, unsigned flags); 926 927 enum { 928 AVFILTER_AUTO_CONVERT_ALL = 0, /**< all automatic conversions enabled */ 929 AVFILTER_AUTO_CONVERT_NONE = -1, /**< all automatic conversions disabled */ 930 }; 931 932 /** 933 * Check validity and configure all the links and formats in the graph. 934 * 935 * @param graphctx the filter graph 936 * @param log_ctx context used for logging 937 * @return >= 0 in case of success, a negative AVERROR code otherwise 938 */ 939 int avfilter_graph_config(AVFilterGraph *graphctx, void *log_ctx); 940 941 /** 942 * Free a graph, destroy its links, and set *graph to NULL. 943 * If *graph is NULL, do nothing. 944 */ 945 void avfilter_graph_free(AVFilterGraph **graph); 946 947 /** 948 * A linked-list of the inputs/outputs of the filter chain. 949 * 950 * This is mainly useful for avfilter_graph_parse() / avfilter_graph_parse2(), 951 * where it is used to communicate open (unlinked) inputs and outputs from and 952 * to the caller. 953 * This struct specifies, per each not connected pad contained in the graph, the 954 * filter context and the pad index required for establishing a link. 955 */ 956 typedef struct AVFilterInOut { 957 /** unique name for this input/output in the list */ 958 char *name; 959 960 /** filter context associated to this input/output */ 961 AVFilterContext *filter_ctx; 962 963 /** index of the filt_ctx pad to use for linking */ 964 int pad_idx; 965 966 /** next input/input in the list, NULL if this is the last */ 967 struct AVFilterInOut *next; 968 } AVFilterInOut; 969 970 /** 971 * Allocate a single AVFilterInOut entry. 972 * Must be freed with avfilter_inout_free(). 973 * @return allocated AVFilterInOut on success, NULL on failure. 974 */ 975 AVFilterInOut *avfilter_inout_alloc(void); 976 977 /** 978 * Free the supplied list of AVFilterInOut and set *inout to NULL. 979 * If *inout is NULL, do nothing. 980 */ 981 void avfilter_inout_free(AVFilterInOut **inout); 982 983 /** 984 * Add a graph described by a string to a graph. 985 * 986 * @note The caller must provide the lists of inputs and outputs, 987 * which therefore must be known before calling the function. 988 * 989 * @note The inputs parameter describes inputs of the already existing 990 * part of the graph; i.e. from the point of view of the newly created 991 * part, they are outputs. Similarly the outputs parameter describes 992 * outputs of the already existing filters, which are provided as 993 * inputs to the parsed filters. 994 * 995 * @param graph the filter graph where to link the parsed graph context 996 * @param filters string to be parsed 997 * @param inputs linked list to the inputs of the graph 998 * @param outputs linked list to the outputs of the graph 999 * @return zero on success, a negative AVERROR code on error 1000 */ 1001 int avfilter_graph_parse(AVFilterGraph *graph, const char *filters, 1002 AVFilterInOut *inputs, AVFilterInOut *outputs, 1003 void *log_ctx); 1004 1005 /** 1006 * Add a graph described by a string to a graph. 1007 * 1008 * In the graph filters description, if the input label of the first 1009 * filter is not specified, "in" is assumed; if the output label of 1010 * the last filter is not specified, "out" is assumed. 1011 * 1012 * @param graph the filter graph where to link the parsed graph context 1013 * @param filters string to be parsed 1014 * @param inputs pointer to a linked list to the inputs of the graph, may be NULL. 1015 * If non-NULL, *inputs is updated to contain the list of open inputs 1016 * after the parsing, should be freed with avfilter_inout_free(). 1017 * @param outputs pointer to a linked list to the outputs of the graph, may be NULL. 1018 * If non-NULL, *outputs is updated to contain the list of open outputs 1019 * after the parsing, should be freed with avfilter_inout_free(). 1020 * @return non negative on success, a negative AVERROR code on error 1021 */ 1022 int avfilter_graph_parse_ptr(AVFilterGraph *graph, const char *filters, 1023 AVFilterInOut **inputs, AVFilterInOut **outputs, 1024 void *log_ctx); 1025 1026 /** 1027 * Add a graph described by a string to a graph. 1028 * 1029 * @param[in] graph the filter graph where to link the parsed graph context 1030 * @param[in] filters string to be parsed 1031 * @param[out] inputs a linked list of all free (unlinked) inputs of the 1032 * parsed graph will be returned here. It is to be freed 1033 * by the caller using avfilter_inout_free(). 1034 * @param[out] outputs a linked list of all free (unlinked) outputs of the 1035 * parsed graph will be returned here. It is to be freed by the 1036 * caller using avfilter_inout_free(). 1037 * @return zero on success, a negative AVERROR code on error 1038 * 1039 * @note This function returns the inputs and outputs that are left 1040 * unlinked after parsing the graph and the caller then deals with 1041 * them. 1042 * @note This function makes no reference whatsoever to already 1043 * existing parts of the graph and the inputs parameter will on return 1044 * contain inputs of the newly parsed part of the graph. Analogously 1045 * the outputs parameter will contain outputs of the newly created 1046 * filters. 1047 */ 1048 int avfilter_graph_parse2(AVFilterGraph *graph, const char *filters, 1049 AVFilterInOut **inputs, 1050 AVFilterInOut **outputs); 1051 1052 /** 1053 * Parameters of a filter's input or output pad. 1054 * 1055 * Created as a child of AVFilterParams by avfilter_graph_segment_parse(). 1056 * Freed in avfilter_graph_segment_free(). 1057 */ 1058 typedef struct AVFilterPadParams { 1059 /** 1060 * An av_malloc()'ed string containing the pad label. 1061 * 1062 * May be av_free()'d and set to NULL by the caller, in which case this pad 1063 * will be treated as unlabeled for linking. 1064 * May also be replaced by another av_malloc()'ed string. 1065 */ 1066 char *label; 1067 } AVFilterPadParams; 1068 1069 /** 1070 * Parameters describing a filter to be created in a filtergraph. 1071 * 1072 * Created as a child of AVFilterGraphSegment by avfilter_graph_segment_parse(). 1073 * Freed in avfilter_graph_segment_free(). 1074 */ 1075 typedef struct AVFilterParams { 1076 /** 1077 * The filter context. 1078 * 1079 * Created by avfilter_graph_segment_create_filters() based on 1080 * AVFilterParams.filter_name and instance_name. 1081 * 1082 * Callers may also create the filter context manually, then they should 1083 * av_free() filter_name and set it to NULL. Such AVFilterParams instances 1084 * are then skipped by avfilter_graph_segment_create_filters(). 1085 */ 1086 AVFilterContext *filter; 1087 1088 /** 1089 * Name of the AVFilter to be used. 1090 * 1091 * An av_malloc()'ed string, set by avfilter_graph_segment_parse(). Will be 1092 * passed to avfilter_get_by_name() by 1093 * avfilter_graph_segment_create_filters(). 1094 * 1095 * Callers may av_free() this string and replace it with another one or 1096 * NULL. If the caller creates the filter instance manually, this string 1097 * MUST be set to NULL. 1098 * 1099 * When both AVFilterParams.filter an AVFilterParams.filter_name are NULL, 1100 * this AVFilterParams instance is skipped by avfilter_graph_segment_*() 1101 * functions. 1102 */ 1103 char *filter_name; 1104 /** 1105 * Name to be used for this filter instance. 1106 * 1107 * An av_malloc()'ed string, may be set by avfilter_graph_segment_parse() or 1108 * left NULL. The caller may av_free() this string and replace with another 1109 * one or NULL. 1110 * 1111 * Will be used by avfilter_graph_segment_create_filters() - passed as the 1112 * third argument to avfilter_graph_alloc_filter(), then freed and set to 1113 * NULL. 1114 */ 1115 char *instance_name; 1116 1117 /** 1118 * Options to be apllied to the filter. 1119 * 1120 * Filled by avfilter_graph_segment_parse(). Afterwards may be freely 1121 * modified by the caller. 1122 * 1123 * Will be applied to the filter by avfilter_graph_segment_apply_opts() 1124 * with an equivalent of av_opt_set_dict2(filter, &opts, AV_OPT_SEARCH_CHILDREN), 1125 * i.e. any unapplied options will be left in this dictionary. 1126 */ 1127 AVDictionary *opts; 1128 1129 AVFilterPadParams **inputs; 1130 unsigned nb_inputs; 1131 1132 AVFilterPadParams **outputs; 1133 unsigned nb_outputs; 1134 } AVFilterParams; 1135 1136 /** 1137 * A filterchain is a list of filter specifications. 1138 * 1139 * Created as a child of AVFilterGraphSegment by avfilter_graph_segment_parse(). 1140 * Freed in avfilter_graph_segment_free(). 1141 */ 1142 typedef struct AVFilterChain { 1143 AVFilterParams **filters; 1144 size_t nb_filters; 1145 } AVFilterChain; 1146 1147 /** 1148 * A parsed representation of a filtergraph segment. 1149 * 1150 * A filtergraph segment is conceptually a list of filterchains, with some 1151 * supplementary information (e.g. format conversion flags). 1152 * 1153 * Created by avfilter_graph_segment_parse(). Must be freed with 1154 * avfilter_graph_segment_free(). 1155 */ 1156 typedef struct AVFilterGraphSegment { 1157 /** 1158 * The filtergraph this segment is associated with. 1159 * Set by avfilter_graph_segment_parse(). 1160 */ 1161 AVFilterGraph *graph; 1162 1163 /** 1164 * A list of filter chain contained in this segment. 1165 * Set in avfilter_graph_segment_parse(). 1166 */ 1167 AVFilterChain **chains; 1168 size_t nb_chains; 1169 1170 /** 1171 * A string containing a colon-separated list of key=value options applied 1172 * to all scale filters in this segment. 1173 * 1174 * May be set by avfilter_graph_segment_parse(). 1175 * The caller may free this string with av_free() and replace it with a 1176 * different av_malloc()'ed string. 1177 */ 1178 char *scale_sws_opts; 1179 } AVFilterGraphSegment; 1180 1181 /** 1182 * Parse a textual filtergraph description into an intermediate form. 1183 * 1184 * This intermediate representation is intended to be modified by the caller as 1185 * described in the documentation of AVFilterGraphSegment and its children, and 1186 * then applied to the graph either manually or with other 1187 * avfilter_graph_segment_*() functions. See the documentation for 1188 * avfilter_graph_segment_apply() for the canonical way to apply 1189 * AVFilterGraphSegment. 1190 * 1191 * @param graph Filter graph the parsed segment is associated with. Will only be 1192 * used for logging and similar auxiliary purposes. The graph will 1193 * not be actually modified by this function - the parsing results 1194 * are instead stored in seg for further processing. 1195 * @param graph_str a string describing the filtergraph segment 1196 * @param flags reserved for future use, caller must set to 0 for now 1197 * @param seg A pointer to the newly-created AVFilterGraphSegment is written 1198 * here on success. The graph segment is owned by the caller and must 1199 * be freed with avfilter_graph_segment_free() before graph itself is 1200 * freed. 1201 * 1202 * @retval "non-negative number" success 1203 * @retval "negative error code" failure 1204 */ 1205 int avfilter_graph_segment_parse(AVFilterGraph *graph, const char *graph_str, 1206 int flags, AVFilterGraphSegment **seg); 1207 1208 /** 1209 * Create filters specified in a graph segment. 1210 * 1211 * Walk through the creation-pending AVFilterParams in the segment and create 1212 * new filter instances for them. 1213 * Creation-pending params are those where AVFilterParams.filter_name is 1214 * non-NULL (and hence AVFilterParams.filter is NULL). All other AVFilterParams 1215 * instances are ignored. 1216 * 1217 * For any filter created by this function, the corresponding 1218 * AVFilterParams.filter is set to the newly-created filter context, 1219 * AVFilterParams.filter_name and AVFilterParams.instance_name are freed and set 1220 * to NULL. 1221 * 1222 * @param seg the filtergraph segment to process 1223 * @param flags reserved for future use, caller must set to 0 for now 1224 * 1225 * @retval "non-negative number" Success, all creation-pending filters were 1226 * successfully created 1227 * @retval AVERROR_FILTER_NOT_FOUND some filter's name did not correspond to a 1228 * known filter 1229 * @retval "another negative error code" other failures 1230 * 1231 * @note Calling this function multiple times is safe, as it is idempotent. 1232 */ 1233 int avfilter_graph_segment_create_filters(AVFilterGraphSegment *seg, int flags); 1234 1235 /** 1236 * Apply parsed options to filter instances in a graph segment. 1237 * 1238 * Walk through all filter instances in the graph segment that have option 1239 * dictionaries associated with them and apply those options with 1240 * av_opt_set_dict2(..., AV_OPT_SEARCH_CHILDREN). AVFilterParams.opts is 1241 * replaced by the dictionary output by av_opt_set_dict2(), which should be 1242 * empty (NULL) if all options were successfully applied. 1243 * 1244 * If any options could not be found, this function will continue processing all 1245 * other filters and finally return AVERROR_OPTION_NOT_FOUND (unless another 1246 * error happens). The calling program may then deal with unapplied options as 1247 * it wishes. 1248 * 1249 * Any creation-pending filters (see avfilter_graph_segment_create_filters()) 1250 * present in the segment will cause this function to fail. AVFilterParams with 1251 * no associated filter context are simply skipped. 1252 * 1253 * @param seg the filtergraph segment to process 1254 * @param flags reserved for future use, caller must set to 0 for now 1255 * 1256 * @retval "non-negative number" Success, all options were successfully applied. 1257 * @retval AVERROR_OPTION_NOT_FOUND some options were not found in a filter 1258 * @retval "another negative error code" other failures 1259 * 1260 * @note Calling this function multiple times is safe, as it is idempotent. 1261 */ 1262 int avfilter_graph_segment_apply_opts(AVFilterGraphSegment *seg, int flags); 1263 1264 /** 1265 * Initialize all filter instances in a graph segment. 1266 * 1267 * Walk through all filter instances in the graph segment and call 1268 * avfilter_init_dict(..., NULL) on those that have not been initialized yet. 1269 * 1270 * Any creation-pending filters (see avfilter_graph_segment_create_filters()) 1271 * present in the segment will cause this function to fail. AVFilterParams with 1272 * no associated filter context or whose filter context is already initialized, 1273 * are simply skipped. 1274 * 1275 * @param seg the filtergraph segment to process 1276 * @param flags reserved for future use, caller must set to 0 for now 1277 * 1278 * @retval "non-negative number" Success, all filter instances were successfully 1279 * initialized 1280 * @retval "negative error code" failure 1281 * 1282 * @note Calling this function multiple times is safe, as it is idempotent. 1283 */ 1284 int avfilter_graph_segment_init(AVFilterGraphSegment *seg, int flags); 1285 1286 /** 1287 * Link filters in a graph segment. 1288 * 1289 * Walk through all filter instances in the graph segment and try to link all 1290 * unlinked input and output pads. Any creation-pending filters (see 1291 * avfilter_graph_segment_create_filters()) present in the segment will cause 1292 * this function to fail. Disabled filters and already linked pads are skipped. 1293 * 1294 * Every filter output pad that has a corresponding AVFilterPadParams with a 1295 * non-NULL label is 1296 * - linked to the input with the matching label, if one exists; 1297 * - exported in the outputs linked list otherwise, with the label preserved. 1298 * Unlabeled outputs are 1299 * - linked to the first unlinked unlabeled input in the next non-disabled 1300 * filter in the chain, if one exists 1301 * - exported in the ouputs linked list otherwise, with NULL label 1302 * 1303 * Similarly, unlinked input pads are exported in the inputs linked list. 1304 * 1305 * @param seg the filtergraph segment to process 1306 * @param flags reserved for future use, caller must set to 0 for now 1307 * @param[out] inputs a linked list of all free (unlinked) inputs of the 1308 * filters in this graph segment will be returned here. It 1309 * is to be freed by the caller using avfilter_inout_free(). 1310 * @param[out] outputs a linked list of all free (unlinked) outputs of the 1311 * filters in this graph segment will be returned here. It 1312 * is to be freed by the caller using avfilter_inout_free(). 1313 * 1314 * @retval "non-negative number" success 1315 * @retval "negative error code" failure 1316 * 1317 * @note Calling this function multiple times is safe, as it is idempotent. 1318 */ 1319 int avfilter_graph_segment_link(AVFilterGraphSegment *seg, int flags, 1320 AVFilterInOut **inputs, 1321 AVFilterInOut **outputs); 1322 1323 /** 1324 * Apply all filter/link descriptions from a graph segment to the associated filtergraph. 1325 * 1326 * This functions is currently equivalent to calling the following in sequence: 1327 * - avfilter_graph_segment_create_filters(); 1328 * - avfilter_graph_segment_apply_opts(); 1329 * - avfilter_graph_segment_init(); 1330 * - avfilter_graph_segment_link(); 1331 * failing if any of them fails. This list may be extended in the future. 1332 * 1333 * Since the above functions are idempotent, the caller may call some of them 1334 * manually, then do some custom processing on the filtergraph, then call this 1335 * function to do the rest. 1336 * 1337 * @param seg the filtergraph segment to process 1338 * @param flags reserved for future use, caller must set to 0 for now 1339 * @param[out] inputs passed to avfilter_graph_segment_link() 1340 * @param[out] outputs passed to avfilter_graph_segment_link() 1341 * 1342 * @retval "non-negative number" success 1343 * @retval "negative error code" failure 1344 * 1345 * @note Calling this function multiple times is safe, as it is idempotent. 1346 */ 1347 int avfilter_graph_segment_apply(AVFilterGraphSegment *seg, int flags, 1348 AVFilterInOut **inputs, 1349 AVFilterInOut **outputs); 1350 1351 /** 1352 * Free the provided AVFilterGraphSegment and everything associated with it. 1353 * 1354 * @param seg double pointer to the AVFilterGraphSegment to be freed. NULL will 1355 * be written to this pointer on exit from this function. 1356 * 1357 * @note 1358 * The filter contexts (AVFilterParams.filter) are owned by AVFilterGraph rather 1359 * than AVFilterGraphSegment, so they are not freed. 1360 */ 1361 void avfilter_graph_segment_free(AVFilterGraphSegment **seg); 1362 1363 /** 1364 * Send a command to one or more filter instances. 1365 * 1366 * @param graph the filter graph 1367 * @param target the filter(s) to which the command should be sent 1368 * "all" sends to all filters 1369 * otherwise it can be a filter or filter instance name 1370 * which will send the command to all matching filters. 1371 * @param cmd the command to send, for handling simplicity all commands must be alphanumeric only 1372 * @param arg the argument for the command 1373 * @param res a buffer with size res_size where the filter(s) can return a response. 1374 * 1375 * @returns >=0 on success otherwise an error code. 1376 * AVERROR(ENOSYS) on unsupported commands 1377 */ 1378 int avfilter_graph_send_command(AVFilterGraph *graph, const char *target, const char *cmd, const char *arg, char *res, int res_len, int flags); 1379 1380 /** 1381 * Queue a command for one or more filter instances. 1382 * 1383 * @param graph the filter graph 1384 * @param target the filter(s) to which the command should be sent 1385 * "all" sends to all filters 1386 * otherwise it can be a filter or filter instance name 1387 * which will send the command to all matching filters. 1388 * @param cmd the command to sent, for handling simplicity all commands must be alphanumeric only 1389 * @param arg the argument for the command 1390 * @param ts time at which the command should be sent to the filter 1391 * 1392 * @note As this executes commands after this function returns, no return code 1393 * from the filter is provided, also AVFILTER_CMD_FLAG_ONE is not supported. 1394 */ 1395 int avfilter_graph_queue_command(AVFilterGraph *graph, const char *target, const char *cmd, const char *arg, int flags, double ts); 1396 1397 1398 /** 1399 * Dump a graph into a human-readable string representation. 1400 * 1401 * @param graph the graph to dump 1402 * @param options formatting options; currently ignored 1403 * @return a string, or NULL in case of memory allocation failure; 1404 * the string must be freed using av_free 1405 */ 1406 char *avfilter_graph_dump(AVFilterGraph *graph, const char *options); 1407 1408 /** 1409 * Request a frame on the oldest sink link. 1410 * 1411 * If the request returns AVERROR_EOF, try the next. 1412 * 1413 * Note that this function is not meant to be the sole scheduling mechanism 1414 * of a filtergraph, only a convenience function to help drain a filtergraph 1415 * in a balanced way under normal circumstances. 1416 * 1417 * Also note that AVERROR_EOF does not mean that frames did not arrive on 1418 * some of the sinks during the process. 1419 * When there are multiple sink links, in case the requested link 1420 * returns an EOF, this may cause a filter to flush pending frames 1421 * which are sent to another sink link, although unrequested. 1422 * 1423 * @return the return value of ff_request_frame(), 1424 * or AVERROR_EOF if all links returned AVERROR_EOF 1425 */ 1426 int avfilter_graph_request_oldest(AVFilterGraph *graph); 1427 1428 /** 1429 * @} 1430 */ 1431 1432 #endif /* AVFILTER_AVFILTER_H */