annotate timefilter.h @ 4657:6b24b7aa7351 libavformat

Add clock_period parameter, this should make the code easier to use.
author michael
date Fri, 06 Mar 2009 00:44:12 +0000
parents 34a843f958b7
children aed6cf383ca2
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
4650
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
1 /*
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
2 * Delay Locked Loop based time filter prototypes and declarations
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
3 * Copyright (c) 2009 Samalyse
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
4 * Author: Olivier Guilyardi <olivier samalyse com>
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
5 *
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
6 * This file is part of FFmpeg.
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
7 *
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
8 * FFmpeg is free software; you can redistribute it and/or
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
9 * modify it under the terms of the GNU Lesser General Public
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
10 * License as published by the Free Software Foundation; either
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
11 * version 2.1 of the License, or (at your option) any later version.
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
12 *
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
13 * FFmpeg is distributed in the hope that it will be useful,
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
16 * Lesser General Public License for more details.
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
17 *
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
18 * You should have received a copy of the GNU Lesser General Public
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
19 * License along with FFmpeg; if not, write to the Free Software
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
20 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
21 */
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
22
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
23 #ifndef AVFORMAT_TIMEFILTER_H
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
24 #define AVFORMAT_TIMEFILTER_H
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
25
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
26 /**
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
27 * Opaque type representing a time filter state
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
28 *
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
29 * The purpose of this filter is to provide a way to compute accurate time
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
30 * stamps that can be compared to wall clock time, especially when dealing
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
31 * with two clocks: the system clock and a hardware device clock, such as
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
32 * a soundcard.
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
33 */
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
34 typedef struct TimeFilter TimeFilter;
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
35
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
36
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
37 /**
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
38 * Create a new Delay Locked Loop time filter
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
39 *
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
40 * feedback2_factor and feedback3_factor are the factors used for the
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
41 * multiplications that are respectively performed in the second and third
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
42 * feedback paths of the loop.
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
43 *
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
44 * Unless you know what you are doing, you should set these as follow:
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
45 *
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
46 * o = 2 * M_PI * bandwidth * period
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
47 * feedback2_factor = sqrt(2 * o)
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
48 * feedback3_factor = o * o
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
49 *
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
50 * Where bandwidth is up to you to choose. Smaller values will filter out more
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
51 * of the jitter, but also take a longer time for the loop to settle. A good
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
52 * starting point is something between 0.3 and 3 Hz.
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
53 *
4657
6b24b7aa7351 Add clock_period parameter, this should make the code easier to use.
michael
parents: 4653
diff changeset
54 * @param clock_period period of the hardware clock in seconds
6b24b7aa7351 Add clock_period parameter, this should make the code easier to use.
michael
parents: 4653
diff changeset
55 * (for example 1.0/44100)
6b24b7aa7351 Add clock_period parameter, this should make the code easier to use.
michael
parents: 4653
diff changeset
56 *
4650
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
57 * For more details about these parameters and background concepts please see:
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
58 * http://www.kokkinizita.net/papers/usingdll.pdf
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
59 */
4657
6b24b7aa7351 Add clock_period parameter, this should make the code easier to use.
michael
parents: 4653
diff changeset
60 TimeFilter * ff_timefilter_new(double clock_period, double feedback2_factor, double feedback3_factor);
4650
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
61
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
62 /**
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
63 * Update the filter
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
64 *
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
65 * This function must be called in real time, at each process cycle.
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
66 *
4657
6b24b7aa7351 Add clock_period parameter, this should make the code easier to use.
michael
parents: 4653
diff changeset
67 * @param period the device cycle duration in clock_periods. For example, at
6b24b7aa7351 Add clock_period parameter, this should make the code easier to use.
michael
parents: 4653
diff changeset
68 * 44.1kHz and a buffer size of 512 frames, period = 512 when clock_period
6b24b7aa7351 Add clock_period parameter, this should make the code easier to use.
michael
parents: 4653
diff changeset
69 * was 1.0/44100, or 512/44100 if clock_period was 1.
4652
28b80bbf6288 Allow timespans to vary.
michael
parents: 4650
diff changeset
70 *
4650
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
71 * system_time, in seconds, should be the value of the system clock time,
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
72 * at (or as close as possible to) the moment the device hardware interrupt
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
73 * occured (or any other event the device clock raises at the beginning of a
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
74 * cycle).
4653
34a843f958b7 Merge ff_timefilter_read() and ff_timefilter_update(), this simplifies API and
michael
parents: 4652
diff changeset
75 *
34a843f958b7 Merge ff_timefilter_read() and ff_timefilter_update(), this simplifies API and
michael
parents: 4652
diff changeset
76 * @return the filtered time, in seconds
4650
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
77 */
4653
34a843f958b7 Merge ff_timefilter_read() and ff_timefilter_update(), this simplifies API and
michael
parents: 4652
diff changeset
78 double ff_timefilter_update(TimeFilter *self, double system_time, double period);
4650
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
79
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
80 /**
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
81 * Reset the filter
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
82 *
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
83 * This function should mainly be called in case of XRUN.
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
84 *
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
85 * Warning: after calling this, the filter is in an undetermined state until
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
86 * the next call to ff_timefilter_update()
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
87 */
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
88 void ff_timefilter_reset(TimeFilter *);
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
89
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
90 /**
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
91 * Free all resources associated with the filter
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
92 */
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
93 void ff_timefilter_destroy(TimeFilter *);
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
94
5090afc3cd19 Timefilter code by Olivier Guilyardi o list O samalyse o com
michael
parents:
diff changeset
95 #endif /* AVFORMAT_TIMEFILTER_H */