lavu/threadmessage: add av_thread_message_queue_nb_elems()
[ffmpeg.git] / 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 AVFrame 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 of supported formats.
16
17   For video links, that means pixel format. For audio links, that means
18   channel layout, sample format (the sample packing is implied by the sample
19   format) and sample rate.
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 end of a link, all references to both lists are replaced
24   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 has to do is use a reference
30   to the same list of formats.
31
32   query_formats can leave some formats unset and return AVERROR(EAGAIN) to
33   cause the negotiation mechanism to try again later. That can be used by
34   filters with complex requirements to use the format negotiated on one link
35   to set the formats supported on another.
36
37
38 Frame references ownership and permissions
39 ==========================================
40
41   Principle
42   ---------
43
44     Audio and video data are voluminous; the frame and frame reference
45     mechanism is intended to avoid, as much as possible, expensive copies of
46     that data while still allowing the filters to produce correct results.
47
48     The data is stored in buffers represented by AVFrame structures.
49     Several references can point to the same frame buffer; the buffer is
50     automatically deallocated once all corresponding references have been
51     destroyed.
52
53     The characteristics of the data (resolution, sample rate, etc.) are
54     stored in the reference; different references for the same buffer can
55     show different characteristics. In particular, a video reference can
56     point to only a part of a video buffer.
57
58     A reference is usually obtained as input to the filter_frame method or
59     requested using the ff_get_video_buffer or ff_get_audio_buffer
60     functions. A new reference on an existing buffer can be created with
61     av_frame_ref(). A reference is destroyed using
62     the av_frame_free() function.
63
64   Reference ownership
65   -------------------
66
67     At any time, a reference “belongs” to a particular piece of code,
68     usually a filter. With a few caveats that will be explained below, only
69     that piece of code is allowed to access it. It is also responsible for
70     destroying it, although this is sometimes done automatically (see the
71     section on link reference fields).
72
73     Here are the (fairly obvious) rules for reference ownership:
74
75     * A reference received by the filter_frame method belongs to the
76       corresponding filter.
77
78     * A reference passed to ff_filter_frame is given away and must no longer
79       be used.
80
81     * A reference created with av_frame_ref() belongs to the code that
82       created it.
83
84     * A reference obtained with ff_get_video_buffer or ff_get_audio_buffer
85       belongs to the code that requested it.
86
87     * A reference given as return value by the get_video_buffer or
88       get_audio_buffer method is given away and must no longer be used.
89
90   Link reference fields
91   ---------------------
92
93     The AVFilterLink structure has a few AVFrame fields.
94
95     partial_buf is used by libavfilter internally and must not be accessed
96     by filters.
97
98     fifo contains frames queued in the filter's input. They belong to the
99     framework until they are taken by the filter.
100
101   Reference permissions
102   ---------------------
103
104     Since the same frame data can be shared by several frames, modifying may
105     have unintended consequences. A frame is considered writable if only one
106     reference to it exists. The code owning that reference it then allowed
107     to modify the data.
108
109     A filter can check if a frame is writable by using the
110     av_frame_is_writable() function.
111
112     A filter can ensure that a frame is writable at some point of the code
113     by using the ff_inlink_make_frame_writable() function. It will duplicate
114     the frame if needed.
115
116     A filter can ensure that the frame passed to the filter_frame() callback
117     is writable by setting the needs_writable flag on the corresponding
118     input pad. It does not apply to the activate() callback.
119
120
121 Frame scheduling
122 ================
123
124   The purpose of these rules is to ensure that frames flow in the filter
125   graph without getting stuck and accumulating somewhere.
126
127   Simple filters that output one frame for each input frame should not have
128   to worry about it.
129
130   There are two design for filters: one using the filter_frame() and
131   request_frame() callbacks and the other using the activate() callback.
132
133   The design using filter_frame() and request_frame() is legacy, but it is
134   suitable for filters that have a single input and process one frame at a
135   time. New filters with several inputs, that treat several frames at a time
136   or that require a special treatment at EOF should probably use the design
137   using activate().
138
139   activate
140   --------
141
142     This method is called when something must be done in a filter; the
143     definition of that "something" depends on the semantic of the filter.
144
145     The callback must examine the status of the filter's links and proceed
146     accordingly.
147
148     The status of output links is stored in the frame_wanted_out, status_in
149     and status_out fields and tested by the ff_outlink_frame_wanted()
150     function. If this function returns true, then the processing requires a
151     frame on this link and the filter is expected to make efforts in that
152     direction.
153
154     The status of input links is stored by the status_in, fifo and
155     status_out fields; they must not be accessed directly. The fifo field
156     contains the frames that are queued in the input for processing by the
157     filter. The status_in and status_out fields contains the queued status
158     (EOF or error) of the link; status_in is a status change that must be
159     taken into account after all frames in fifo have been processed;
160     status_out is the status that have been taken into account, it is final
161     when it is not 0.
162
163     The typical task of an activate callback is to first check the backward
164     status of output links, and if relevant forward it to the corresponding
165     input. Then, if relevant, for each input link: test the availability of
166     frames in fifo and process them;  if no frame is available, test and
167     acknowledge a change of status using ff_inlink_acknowledge_status(); and
168     forward the result (frame or status change) to the corresponding input.
169     If nothing is possible, test the status of outputs and forward it to the
170     corresponding input(s). If still not possible, return FFERROR_NOT_READY.
171
172     If the filters stores internally one or a few frame for some input, it
173     can consider them to be part of the FIFO and delay acknowledging a
174     status change accordingly.
175
176     Example code:
177
178     ret = ff_outlink_get_status(outlink);
179     if (ret) {
180         ff_inlink_set_status(inlink, ret);
181         return 0;
182     }
183     if (priv->next_frame) {
184         /* use it */
185         return 0;
186     }
187     ret = ff_inlink_consume_frame(inlink, &frame);
188     if (ret < 0)
189         return ret;
190     if (ret) {
191         /* use it */
192         return 0;
193     }
194     ret = ff_inlink_acknowledge_status(inlink, &status, &pts);
195     if (ret) {
196         /* flush */
197         ff_outlink_set_status(outlink, status, pts);
198         return 0;
199     }
200     if (ff_outlink_frame_wanted(outlink)) {
201         ff_inlink_request_frame(inlink);
202         return 0;
203     }
204     return FFERROR_NOT_READY;
205
206     The exact code depends on how similar the /* use it */ blocks are and
207     how related they are to the /* flush */ block, and needs to apply these
208     operations to the correct inlink or outlink if there are several.
209
210     Macros are available to factor that when no extra processing is needed:
211
212     FF_FILTER_FORWARD_STATUS_BACK(outlink, inlink);
213     FF_FILTER_FORWARD_STATUS_ALL(outlink, filter);
214     FF_FILTER_FORWARD_STATUS(inlink, outlink);
215     FF_FILTER_FORWARD_STATUS_ALL(inlink, filter);
216     FF_FILTER_FORWARD_WANTED(outlink, inlink);
217
218   filter_frame
219   ------------
220
221     For filters that do not use the activate() callback, this method is
222     called when a frame is pushed to the filter's input. It can be called at
223     any time except in a reentrant way.
224
225     If the input frame is enough to produce output, then the filter should
226     push the output frames on the output link immediately.
227
228     As an exception to the previous rule, if the input frame is enough to
229     produce several output frames, then the filter needs output only at
230     least one per link. The additional frames can be left buffered in the
231     filter; these buffered frames must be flushed immediately if a new input
232     produces new output.
233
234     (Example: frame rate-doubling filter: filter_frame must (1) flush the
235     second copy of the previous frame, if it is still there, (2) push the
236     first copy of the incoming frame, (3) keep the second copy for later.)
237
238     If the input frame is not enough to produce output, the filter must not
239     call request_frame to get more. It must just process the frame or queue
240     it. The task of requesting more frames is left to the filter's
241     request_frame method or the application.
242
243     If a filter has several inputs, the filter must be ready for frames
244     arriving randomly on any input. Therefore, any filter with several inputs
245     will most likely require some kind of queuing mechanism. It is perfectly
246     acceptable to have a limited queue and to drop frames when the inputs
247     are too unbalanced.
248
249   request_frame
250   -------------
251
252     For filters that do not use the activate() callback, this method is
253     called when a frame is wanted on an output.
254
255     For a source, it should directly call filter_frame on the corresponding
256     output.
257
258     For a filter, if there are queued frames already ready, one of these
259     frames should be pushed. If not, the filter should request a frame on
260     one of its inputs, repeatedly until at least one frame has been pushed.
261
262     Return values:
263     if request_frame could produce a frame, or at least make progress
264     towards producing a frame, it should return 0;
265     if it could not for temporary reasons, it should return AVERROR(EAGAIN);
266     if it could not because there are no more frames, it should return
267     AVERROR_EOF.
268
269     The typical implementation of request_frame for a filter with several
270     inputs will look like that:
271
272         if (frames_queued) {
273             push_one_frame();
274             return 0;
275         }
276         input = input_where_a_frame_is_most_needed();
277         ret = ff_request_frame(input);
278         if (ret == AVERROR_EOF) {
279             process_eof_on_input();
280         } else if (ret < 0) {
281             return ret;
282         }
283         return 0;
284
285     Note that, except for filters that can have queued frames and sources,
286     request_frame does not push frames: it requests them to its input, and
287     as a reaction, the filter_frame method possibly will be called and do
288     the work.