git.sesse.net Git - ffmpeg/blob - doc/filter_design.txt

   1 Filter design
   2 =============
   3
   4 This document explains guidelines that should be observed (or ignored with
   5 good reason) when writing filters for libavfilter.
   6
   7 In this document, the word “frame” indicates either a video frame or a group
   8 of audio samples, as stored in an AVFilterBuffer structure.
   9
  10
  11 Format negotiation
  12 ==================
  13
  14   The query_formats method should set, for each input and each output links,
  15   the list supported formats.
  16
  17   For video links, that means pixel format. For audio links, that means
  18   channel layout, and sample format (the sample packing is implied by the
  19   sample format).
  20
  21   The lists are not just lists, they are references to shared objects. When
  22   the negotiation mechanism computes the intersection of the formats
  23   supported at each ends of a link, all references to both lists are
  24   replaced with a reference to the intersection. And when a single format is
  25   eventually chosen for a link amongst the remaining list, again, all
  26   references to the list are updated.
  27
  28   That means that if a filter requires that its input and output have the
  29   same format amongst a supported list, all it have to do is use a reference
  30   to the same list of formats.
  31
  32
  33 Buffer references ownership and permissions
  34 ===========================================
  35
  36   TODO
  37
  38
  39 Frame scheduling
  40 ================
  41
  42   The purpose of these rules is to ensure that frames flow in the filter
  43   graph without getting stuck and accumulating somewhere.
  44
  45   Simple filters that output one frame for each input frame should not have
  46   to worry about it.
  47
  48   start_frame / filter_samples
  49   ----------------------------
  50
  51     These methods are called when a frame is pushed to the filter's input.
  52     They can be called at any time except in a reentrant way.
  53
  54     If the input frame is enough to produce output, then the filter should
  55     push the output frames on the output link immediately.
  56
  57     As an exception to the previous rule, if the input frame is enough to
  58     produce several output frames, then the filter needs output only at
  59     least one per link. The additional frames can be left buffered in the
  60     filter; these buffered frames must be flushed immediately if a new input
  61     produces new output.
  62
  63     (Example: framerate-doubling filter: start_frame must (1) flush the
  64     second copy of the previous frame, if it is still there, (2) push the
  65     first copy of the incoming frame, (3) keep the second copy for later.)
  66
  67     If the input frame is not enough to produce output, the filter must not
  68     call request_frame to get more. It must just process the frame or queue
  69     it. The task of requesting more frames is left to the filter's
  70     request_frame method or the application.
  71
  72     If a filter has several inputs, the filter must be ready for frames
  73     arriving randomly on any input. Therefore, any filter with several input
  74     will most likely require some kind of queuing mechanism. It is perfectly
  75     acceptable to have a limited queue and to drop frames when the inputs
  76     are too unbalanced.
  77
  78   request_frame
  79   -------------
  80
  81     This method is called when a frame is wanted on an output.
  82
  83     For an input, it should directly call start_frame or filter_samples on
  84     the corresponding output.
  85
  86     For a filter, if there are queued frames already ready, one of these
  87     frames should be pushed. If not, the filter should request a frame on
  88     one of its input, repeatedly until at least one frame has been pushed.
  89
  90     Return values:
  91     if request_frame could produce a frame, it should return 0;
  92     if it could not for temporary reasons, it should return AVERROR(EAGAIN);
  93     if it could not because there are no more frames, it should return
  94     AVERROR_EOF.
  95
  96     The typical implementation of request_frame for a filter with several
  97     inputs will look like that:
  98
  99         if (frames_queued) {
 100             push_one_frame();
 101             return 0;
 102         }
 103         while (!frame_pushed) {
 104             input = input_where_a_frame_is_most_needed();
 105             ret = avfilter_request_frame(input);
 106             if (ret == AVERROR_EOF) {
 107                 process_eof_on_input();
 108             } else if (ret < 0) {
 109                 return ret;
 110             }
 111         }
 112         return 0;
 113
 114     Note that, except for filters that can have queued frames, request_frame
 115     does not push frames: it requests them to its input, and as a reaction,
 116     the start_frame / filter_samples method will be called and do the work.