root/trunk/libffado/src/libutil/TimestampedBuffer.h

Revision 742, 8.1 kB (checked in by ppalmers, 16 years ago)

- Remove some obsolete support files and dirs

- Clean up the license statements in the source files. Everything is

GPL version 3 now.

- Add license and copyright notices to scons scripts

- Clean up some other text files

Line 
1 /*
2  * Copyright (C) 2005-2007 by Pieter Palmers
3  *
4  * This file is part of FFADO
5  * FFADO = Free Firewire (pro-)audio drivers for linux
6  *
7  * FFADO is based upon FreeBoB.
8  *
9  * This program is free software: you can redistribute it and/or modify
10  * it under the terms of the GNU General Public License as published by
11  * the Free Software Foundation, either version 3 of the License, or
12  * (at your option) any later version.
13  *
14  * This program is distributed in the hope that it will be useful,
15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17  * GNU General Public License for more details.
18  *
19  * You should have received a copy of the GNU General Public License
20  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
21  *
22  */
23
24 #ifndef __FFADO_TIMESTAMPEDBUFFER__
25 #define __FFADO_TIMESTAMPEDBUFFER__
26
27 #include "../debugmodule/debugmodule.h"
28 #include "libutil/ringbuffer.h"
29
30 //typedef float ffado_timestamp_t;
31 //#define TIMESTAMP_FORMAT_SPEC "%14.3f"
32 typedef double ffado_timestamp_t;
33 #define TIMESTAMP_FORMAT_SPEC "%14.3f"
34 // typedef int64_t ffado_timestamp_t;
35 // #define TIMESTAMP_FORMAT_SPEC "%012lld"
36
37 namespace Util
38 {
39
40 class TimestampedBufferClient;
41
42 /**
43     * \brief Class implementing a frame buffer that is time-aware
44     *
45     * This class implements a buffer that is time-aware. Whenever new frames
46     * are written to the buffer, the timestamp corresponding to the last frame
47     * in the buffer is updated. This allows to calculate the timestamp of any
48     * other frame in the buffer.
49     *
50     * The buffer is a frame buffer, having the following parameters defining
51     * it's behaviour:
52     * - buff_size: buffer size in frames (setBufferSize())
53     * - events_per_frame: the number of events per frame (setEventsPerFrame())
54     * - event_size: the storage size of the events (in bytes) (setEventSize())
55     *
56     * The total size of the buffer (in bytes) is at least
57     * buff_size*events_per_frame*event_size.
58     *
59     * Timestamp tracking is done by requiring that a timestamp is specified every
60     * time frames are added to the buffer. In combination with the buffer fill and
61     * the frame rate (calculated internally), this allows to calculate the timestamp
62     * of any frame in the buffer. In order to initialize the internal data structures,
63     * the setNominalRate() and setUpdatePeriod() functions are provided.
64     *
65     * \note Currently the class only supports fixed size writes of size update_period.
66     *       This can change in the future, implementation ideas are already in place.
67     *
68     * The TimestampedBuffer class is time unit agnostic. It can handle any time unit
69     * as long as it fits in a 64 bit unsigned integer. The buffer supports wrapped
70     * timestamps using (...).
71     *
72     * There are two methods of reading and writing to the buffer.
73     *
74     * The first method uses conventional readFrames() and writeFrames() functions.
75     *
76     * The second method makes use of the TimestampedBufferClient interface. When a
77     * TimestampedBuffer is created, it is required that a TimestampedBufferClient is
78     * registered. This client implements the processReadBlock and processWriteBlock
79     * functions. These are block processing 'callbacks' that allow zero-copy processing
80     * of the buffer contents. In order to initiate block processing, the
81     * blockProcessWriteFrames and blockProcessReadFrames functions are provided by
82     * TimestampedBuffer.
83     *
84     */
85 class TimestampedBuffer
86 {
87     public:
88         TimestampedBuffer ( TimestampedBufferClient * );
89         virtual ~TimestampedBuffer();
90
91         bool writeDummyFrame();
92         bool dropFrames ( unsigned int nbframes );
93
94         bool writeFrames ( unsigned int nbframes, char *data, ffado_timestamp_t ts );
95         bool readFrames ( unsigned int nbframes, char *data );
96
97         bool preloadFrames ( unsigned int nbframes, char *data, bool keep_head_ts );
98
99         bool blockProcessWriteFrames ( unsigned int nbframes, ffado_timestamp_t ts );
100         bool blockProcessReadFrames ( unsigned int nbframes );
101
102         bool init();
103         bool prepare();
104         bool clearBuffer();
105
106         bool isEnabled() {return m_enabled;};
107         void enable() {m_enabled=true;};
108         void disable() {m_enabled=false;};
109
110         bool isTransparent() {return m_transparent;};
111         void setTransparent ( bool v ) {m_transparent=v;};
112
113         bool setEventSize ( unsigned int s );
114         bool setEventsPerFrame ( unsigned int s );
115         bool setBufferSize ( unsigned int s );
116         unsigned int getBufferSize() {return m_buffer_size;};
117
118         unsigned int getBytesPerFrame() {return m_bytes_per_frame;};
119
120         bool setWrapValue ( ffado_timestamp_t w );
121
122         unsigned int getBufferFill();
123
124         // timestamp stuff
125         int getFrameCounter() {return m_framecounter;};
126
127         void getBufferHeadTimestamp ( ffado_timestamp_t *ts, signed int *fc );
128         void getBufferTailTimestamp ( ffado_timestamp_t *ts, signed int *fc );
129
130         void setBufferTailTimestamp ( ffado_timestamp_t new_timestamp );
131         void setBufferHeadTimestamp ( ffado_timestamp_t new_timestamp );
132
133         // sync related, also drops or add frames when necessary
134         bool syncBufferHeadToTimestamp ( ffado_timestamp_t ts );
135         bool syncBufferTailToTimestamp ( ffado_timestamp_t ts );
136         bool syncCorrectLag ( int64_t ts );
137
138         ffado_timestamp_t getTimestampFromTail ( int nframes );
139         ffado_timestamp_t getTimestampFromHead ( int nframes );
140
141         // buffer offset stuff
142         /// return the tick offset value
143         ffado_timestamp_t getTickOffset() {return m_tick_offset;};
144
145         bool setFrameOffset ( int nframes );
146         bool setTickOffset ( ffado_timestamp_t );
147
148         // dll stuff
149         bool setNominalRate ( float r );
150         float getNominalRate() {return m_nominal_rate;};
151         float getRate();
152
153         bool setUpdatePeriod ( unsigned int t );
154
155         // misc stuff
156         void dumpInfo();
157         void setVerboseLevel ( int l ) {setDebugLevel ( l );};
158
159     private:
160         void decrementFrameCounter ( int nbframes );
161         void incrementFrameCounter ( int nbframes, ffado_timestamp_t new_timestamp );
162         void resetFrameCounter();
163
164     protected:
165
166         ffado_ringbuffer_t * m_event_buffer;
167         char* m_cluster_buffer;
168
169         unsigned int m_event_size; // the size of one event
170         unsigned int m_events_per_frame; // the number of events in a frame
171         unsigned int m_buffer_size; // the number of frames in the buffer
172         unsigned int m_bytes_per_frame;
173         unsigned int m_bytes_per_buffer;
174         bool m_enabled; // you can get frames FIXME: rename!!
175         bool m_transparent; // the buffer should hold the frames put in it. if true, discards all frames
176
177         ffado_timestamp_t m_wrap_at; // value to wrap at
178
179         TimestampedBufferClient *m_Client;
180
181         DECLARE_DEBUG_MODULE;
182
183     private:
184         // the framecounter gives the number of frames in the buffer
185         signed int m_framecounter;
186
187         // the offset that define the timing of the buffer
188         ffado_timestamp_t m_tick_offset;
189
190         // the buffer tail timestamp gives the timestamp of the last frame
191         // that was put into the buffer
192         ffado_timestamp_t   m_buffer_tail_timestamp;
193         ffado_timestamp_t   m_buffer_next_tail_timestamp;
194
195         // this mutex protects the access to the framecounter
196         // and the buffer head timestamp.
197         pthread_mutex_t m_framecounter_lock;
198
199         // tracking DLL variables
200 // JMW: try double for this too
201 //    float m_dll_e2;
202         double m_dll_e2;
203         float m_dll_b;
204         float m_dll_c;
205
206         float m_nominal_rate;
207         unsigned int m_update_period;
208 };
209
210 /**
211     * \brief Interface to be implemented by TimestampedBuffer clients
212     */
213 class TimestampedBufferClient
214 {
215     public:
216         TimestampedBufferClient() {};
217         virtual ~TimestampedBufferClient() {};
218
219         virtual bool processReadBlock ( char *data, unsigned int nevents, unsigned int offset ) =0;
220         virtual bool processWriteBlock ( char *data, unsigned int nevents, unsigned int offset ) =0;
221
222 };
223
224 } // end of namespace Util
225
226 #endif /* __FFADO_TIMESTAMPEDBUFFER__ */
227
228
Note: See TracBrowser for help on using the browser.