root/branches/streaming-rework/libfreebob/freebob_streaming.h

Revision 336, 14.6 kB (checked in by pieterpalmers, 17 years ago)

- Merged the developments on trunk since branch-off:

branch occurred at rev 194
svn merge -r 194:HEAD https://svn.sourceforge.net/svnroot/freebob/trunk/libfreebob

- Modified libfreebobavc to use the messagebuffer for debug info.
- This should compile and run

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
Line 
1 /*
2  *   FreeBoB Streaming API
3  *   FreeBoB = Firewire (pro-)audio for linux
4  *
5  *   http://freebob.sf.net
6  *
7  *   Copyright (C) 2005 Pieter Palmers <pieterpalmers@users.sourceforge.net>
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 2 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, write to the Free Software
21  *   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
22  *
23  *
24  *
25  */
26
27 /* freebob_streaming.h
28  *
29  * Specification for the FreeBoB Streaming API
30  *
31  */
32 #ifndef __FREEBOB_STREAMING_H__
33 #define __FREEBOB_STREAMING_H__
34
35 #include <stdlib.h>
36
37 #ifdef __cplusplus
38 extern "C" {
39 #endif
40
41 #define FREEBOB_STREAMING_MAX_URL_LENGTH 2048
42
43 #define FREEBOB_IGNORE_CAPTURE          (1<<0)
44 #define FREEBOB_IGNORE_PLAYBACK         (1<<1)
45
46
47 /* The basic operation of the API is as follows:
48  *
49  * freebob_streaming_init()
50  * freebob_streaming_start()
51  * while(running) {
52  *   retval = freebob_streaming_wait();
53  *   if (retval == -1) {
54  *     freebob_streaming_reset();
55  *     continue;
56  *   }
57  *
58  *   freebob_streaming_transfer_buffers(dev);
59  *
60  *   for(all channels) {
61  *     switch (channel_type) {
62  *     case audio:
63  *       bytesread=freebob_streaming_read(audioinbuffer[channel]);
64  *       byteswritten=freebob_streaming_write(audiooutbuffer[channel]);
65  *     case midi:
66  *       bytesread=freebob_streaming_read(midiinbuffer[channel]);
67  *       byteswritten=freebob_streaming_write(midioutbuffer[channel]);
68  *     }
69  *   }
70  * }
71  * freebob_streaming_stop();
72  * freebob_streaming_finish();
73  *
74  */
75
76 typedef struct _freebob_device freebob_device_t;
77
78 /**
79  * The sample format used by the freebob streaming API
80  */
81
82 typedef unsigned int freebob_sample_t;
83
84
85 typedef unsigned int freebob_nframes_t;
86
87
88 typedef struct freebob_device_info {
89         /* TODO: How is the device specification done? */
90 //      char xml_location[FREEBOB_STREAMING_MAX_URL_LENGTH]; // can be an osc url or an XML filename
91 //      freebob_device_info_location_type location_type;
92 } freebob_device_info_t;
93
94 /**
95  * Structure to pass the options to the freebob streaming code.
96  */
97 typedef struct freebob_options {
98         /* driver related setup */
99         int sample_rate;                /* this is acutally dictated by the device
100                                                          * you can specify a value here or -1 to autodetect
101                                                          */
102
103         /* buffer setup */
104         int period_size;        /* one period is the amount of frames that
105                                  * has to be sent or received in order for
106                                  * a period boundary to be signalled.
107                                  * (unit: frames)
108                                  */
109         int nb_buffers; /* the size of the frame buffer (in periods) */
110
111         /* packetizer thread options */
112         int realtime;
113         int packetizer_priority;
114        
115         /* libfreebob related setup */
116         int node_id;
117         int port;
118        
119         /* direction map */
120         int directions;
121        
122         /* verbosity */
123         int verbose;
124
125 } freebob_options_t;
126
127 /**
128  * The types of streams supported by the API
129  *
130  * A freebob_audio type stream is a stream that consists of successive samples.
131  * The format is a 24bit UINT in host byte order, aligned as the 24LSB's of the
132  * 32bit UINT of the read/write buffer.
133  * The wait operation looks at this type of streams only.
134  *
135  * A freebob_midi type stream is a stream of midi bytes. The bytes are 8bit UINT,
136  * aligned as the first 8LSB's of the 32bit UINT of the read/write buffer.
137  *
138  */
139 typedef enum {
140         freebob_stream_type_invalid                      =   -1,
141         freebob_stream_type_unknown                      =   0,
142         freebob_stream_type_audio                        =   1,
143         freebob_stream_type_midi                         =   2,
144         freebob_stream_type_control                      =   3,
145 } freebob_streaming_stream_type;
146
147 /**
148  *
149  * Buffer types known to the API
150  *
151  */
152 typedef enum {
153         freebob_buffer_type_per_stream          =   -1, // use this to use the per-stream read functions
154         freebob_buffer_type_int24           =   0,
155         freebob_buffer_type_float            =   1,
156         freebob_buffer_type_midi            =   2,
157 //      freebob_buffer_type_uint32           =   2,
158 //      freebob_buffer_type_double           =   3,
159 //      ...
160 } freebob_streaming_buffer_type;
161
162 /**
163  * Initializes the streaming from/to a FreeBoB device. A FreeBoB device
164  * is a virtual device composed of several BeBoB or compatible devices,
165  * linked together in one sync domain.
166  *
167  * This prepares all IEEE1394 related stuff and sets up all buffering.
168  * It elects a sync master if nescessary.
169  *
170  * @param device_info provides a way to specify the virtual device
171  * @param options options regarding buffers, ieee1394 setup, ...
172  *
173  * @return Opaque device handle if successful.  If this is NULL, the
174  * init operation failed.
175  *
176  */
177 freebob_device_t *freebob_streaming_init (freebob_device_info_t *device_info,
178                                         freebob_options_t options);
179
180 /**
181  * preparation should be done after setting all per-stream parameters
182  * the way you want them. being buffer data type etc...
183  *
184  * @param dev the freebob device
185  * @return
186  */
187 int freebob_streaming_prepare(freebob_device_t *dev);
188
189
190 /**
191  * Finishes the FreeBoB streaming. Cleans up all internal data structures
192  * and terminates connections.
193  *
194  * @param dev the freebob device to be closed.
195  */
196 void freebob_streaming_finish(freebob_device_t *dev);
197
198 /**
199  * Returns the amount of capture channels available
200  *
201  * @param dev the freebob device
202  *
203  * @return the number of capture streams present & active on the device.
204  *         can be 0. returns -1 upon error.
205  */
206 int freebob_streaming_get_nb_capture_streams(freebob_device_t *dev);
207
208 /**
209  * Returns the amount of playack channels available
210  *
211  * @param dev the freebob device
212  *
213  * @return the number of playback streams present & active on the device.
214  *         can be 0. returns -1 upon error.
215  */
216 int freebob_streaming_get_nb_playback_streams(freebob_device_t *dev);
217
218 /**
219  * Copies the capture channel name into the specified buffer
220  *
221  * @param dev the freebob device
222  * @param number the stream number
223  * @param buffer the buffer to copy the name into. has to be allocated.
224  * @param buffersize the size of the buffer
225  *
226  * @return the number of characters copied into the buffer
227  */
228 int freebob_streaming_get_capture_stream_name(freebob_device_t *dev, int number, char* buffer, size_t buffersize);
229
230 /**
231  * Copies the playback channel name into the specified buffer
232  *
233  * @param dev the freebob device
234  * @param number the stream number
235  * @param buffer the buffer to copy the name into. has to be allocated.
236  * @param buffersize the size of the buffer
237  *
238  * @return the number of characters copied into the buffer
239  */
240 int freebob_streaming_get_playback_stream_name(freebob_device_t *dev, int number, char* buffer, size_t buffersize);
241
242 /**
243  * Returns the type of a capture channel
244  *
245  * @param dev the freebob device
246  * @param number the stream number
247  *
248  * @return the channel type
249  */
250 freebob_streaming_stream_type freebob_streaming_get_capture_stream_type(freebob_device_t *dev, int number);
251
252 /**
253  * Returns the type of a playback channel
254  *
255  * @param dev the freebob device
256  * @param number the stream number
257  *
258  * @return the channel type
259  */
260 freebob_streaming_stream_type freebob_streaming_get_playback_stream_type(freebob_device_t *dev, int number);
261 /*
262  *
263  * Note: buffer handling will change in order to allow setting the sample type for *_read and *_write
264  * and separately indicate if you want to use a user buffer or a managed buffer.
265  *
266  */
267  
268  
269  
270 /**
271  * Sets the decode buffer for the stream. This allows for zero-copy decoding.
272  * The call to freebob_streaming_transfer_buffers will decode one period of the stream to
273  * this buffer. Make sure it is large enough.
274  *
275  * @param dev the freebob device
276  * @param number the stream number
277  * @param buff a pointer to the sample buffer, make sure it is large enough
278  *             i.e. sizeof(your_sample_type)*period_size
279  * @param t   the type of the buffer. this determines sample type and the decode function used.
280  *
281  * @return -1 on error, 0 on success
282  */
283
284 int freebob_streaming_set_capture_stream_buffer(freebob_device_t *dev, int number, char *buff);
285 int freebob_streaming_set_capture_buffer_type(freebob_device_t *dev, int i, freebob_streaming_buffer_type t);
286 int freebob_streaming_capture_stream_onoff(freebob_device_t *dev, int number, int on);
287
288 /**
289  * Sets the encode buffer for the stream. This allows for zero-copy encoding (directly to the events).
290  * The call to freebob_streaming_transfer_buffers will encode one period of the stream from
291  * this buffer to the event buffer.
292  *
293  * @param dev the freebob device
294  * @param number the stream number
295  * @param buff a pointer to the sample buffer
296  * @param t   the type of the buffer. this determines sample type and the decode function used.
297  *
298  * @return -1 on error, 0 on success
299  */
300 int freebob_streaming_set_playback_stream_buffer(freebob_device_t *dev, int number, char *buff);
301 int freebob_streaming_set_playback_buffer_type(freebob_device_t *dev, int i, freebob_streaming_buffer_type t);
302 int freebob_streaming_playback_stream_onoff(freebob_device_t *dev, int number, int on);
303
304
305 /**
306  * preparation should be done after setting all per-stream parameters
307  * the way you want them. being buffer data type etc...
308  *
309  * @param dev
310  * @return
311  */
312  
313 int freebob_streaming_prepare(freebob_device_t *dev);
314
315 /**
316  * Starts the streaming operation. This initiates the connections to the FreeBoB devices and
317  * starts the packet handling thread(s). This has to be called before any I/O can occur.
318  *
319  * @param dev the freebob device
320  *
321  * @return 0 on success, -1 on failure.
322  */
323 int freebob_streaming_start(freebob_device_t *dev);
324
325 /**
326  * Stops the streaming operation. This closes the connections to the FreeBoB devices and
327  * stops the packet handling thread(s).
328  *
329  * @param dev the freebob device
330  *
331  * @return 0 on success, -1 on failure.
332  */
333 int freebob_streaming_stop(freebob_device_t *dev);
334
335 /**
336  * Resets the streaming as if it was stopped and restarted. The difference is that the connections
337  * are not nescessarily broken and restored.
338  *
339  * All buffers are reset in the initial state and all data in them is lost.
340  *
341  * @param dev the freebob device
342  *
343  * @return 0 on success, -1 on failure.
344  */
345 int freebob_streaming_reset(freebob_device_t *dev);
346
347 /**
348  * Waits until there is at least one period of data available on all capture connections and
349  * room for one period of data on all playback connections
350  *
351  * @param dev the freebob device
352  *
353  * @return The number of frames ready. -1 when a problem occurred.
354  */
355 int freebob_streaming_wait(freebob_device_t *dev);
356
357 /**
358  * Reads from a specific channel to a supplied buffer.
359  *
360  * @param dev the freebob device
361  * @param number the stream number
362  * @param buffer the buffer to copy the samples into
363  * @param nsamples the number of samples to be read. the buffer has to be big enough for this amount of samples.
364  *
365  * @return the amount of samples actually read. -1 on error (xrun).
366  */
367 int freebob_streaming_read(freebob_device_t *dev, int number, freebob_sample_t *buffer, int nsamples);
368
369 /**
370  * Write to a specific channel from a supplied buffer.
371  *
372  * @param dev the freebob device
373  * @param number the stream number
374  * @param buffer the buffer to copy the samples from
375  * @param nsamples the number of samples to be written.
376  *
377  * @return the amount of samples actually written. -1 on error.
378  */
379 int freebob_streaming_write(freebob_device_t *dev, int number, freebob_sample_t *buffer, int nsamples);
380
381 /**
382  * Transfer & decode the events from the packet buffer to the sample buffers
383  *
384  * This should be called after the wait call returns, before reading/writing the sample buffers
385  * with freebob_streaming_[read|write].
386  *
387  * The purpose is to allow more precise timing information. freebob_streaming_wait returns as soon as the
388  * period boundary is crossed, and can therefore be used to determine the time instant of this crossing (e.g. jack DLL).
389  *
390  * The actual decoding work is done in this function and can therefore be omitted in this timing calculation.
391  * Note that you HAVE to call this function in order for the buffers not to overflow, and only call it when
392  * freebob_streaming_wait doesn't indicate a buffer xrun (xrun handler resets buffer).
393  *
394  * If user supplied playback buffers are specified with freebob_streaming_set_playback_buffers
395  * their contents should be valid before calling this function.
396  * If user supplied capture buffers are specified with freebob_streaming_set_capture_buffers
397  * their contents are updated in this function.
398  *
399  * Use either freebob_streaming_transfer_buffers to transfer all buffers at once, or use
400  * freebob_streaming_transfer_playback_buffers and freebob_streaming_transfer_capture_buffers
401  * to have more control. Don't use both.
402  *
403  * @param dev the freebob device
404  * @return  -1 on error.
405  */
406  
407 int freebob_streaming_transfer_buffers(freebob_device_t *dev);
408
409 /**
410  * Transfer & encode the events from the sample buffers to the packet buffer
411  *
412  * This should be called after the wait call returns, after writing the sample buffers
413  * with freebob_streaming_write.
414  *
415  * If user supplied playback buffers are specified with freebob_streaming_set_playback_buffers
416  * their contents should be valid before calling this function.
417  *
418  * Use either freebob_streaming_transfer_buffers to transfer all buffers at once, or use
419  * freebob_streaming_transfer_playback_buffers and freebob_streaming_transfer_capture_buffers
420  * to have more control. Don't use both.
421  *
422  * @param dev the freebob device
423  * @return  -1 on error.
424  */
425  
426 int freebob_streaming_transfer_playback_buffers(freebob_device_t *dev);
427
428 /**
429  * Transfer & decode the events from the packet buffer to the sample buffers
430  *
431  * This should be called after the wait call returns, before reading the sample buffers
432  * with freebob_streaming_read.
433  *
434  * If user supplied capture buffers are specified with freebob_streaming_set_capture_buffers
435  * their contents are updated in this function.
436  *
437  * Use either freebob_streaming_transfer_buffers to transfer all buffers at once, or use
438  * freebob_streaming_transfer_playback_buffers and freebob_streaming_transfer_capture_buffers
439  * to have more control. Don't use both.
440  *
441  * @param dev the freebob device
442  * @return  -1 on error.
443  */
444
445 int freebob_streaming_transfer_capture_buffers(freebob_device_t *dev);
446
447 /**
448  * Returns the packetizer thread to allow RT enabling by the host.
449  *
450  * @param dev the freebob device
451  *
452  * @return the thread.
453  */
454 pthread_t freebob_streaming_get_packetizer_thread(freebob_device_t *dev);
455
456
457 #ifdef __cplusplus
458 }
459 #endif
460
461 #endif
Note: See TracBrowser for help on using the browser.