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

Revision 435, 14.5 kB (checked in by pieterpalmers, 15 years ago)

src/devicemanager:
- start OSC server for the device manager

src/devicemanager,
src/iavdevice,
src/libieee1394/configrom:
- inherit from OscNode? to become Osc'able

src/bounce,
src/libstreaming/AmdtpStreamProcessor,
src/libstreaming/AmdtpSlaveStreamProcessor:
- fixed bounce device implementation, now working

src/bebob:
- fixed midi bug

General:
- removed 'intermediate XML'
- removed obsolete tests
- removed obsolete files
- removed obsolete API calls

  • 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         /* slave mode */
126         int slave_mode;
127        
128         /* snoop mode */
129         int snoop_mode;
130
131 } freebob_options_t;
132
133 /**
134  * The types of streams supported by the API
135  *
136  * A freebob_audio type stream is a stream that consists of successive samples.
137  * The format is a 24bit UINT in host byte order, aligned as the 24LSB's of the
138  * 32bit UINT of the read/write buffer.
139  * The wait operation looks at this type of streams only.
140  *
141  * A freebob_midi type stream is a stream of midi bytes. The bytes are 8bit UINT,
142  * aligned as the first 8LSB's of the 32bit UINT of the read/write buffer.
143  *
144  */
145 typedef enum {
146         freebob_stream_type_invalid                      =   -1,
147         freebob_stream_type_unknown                      =   0,
148         freebob_stream_type_audio                        =   1,
149         freebob_stream_type_midi                         =   2,
150         freebob_stream_type_control                      =   3,
151 } freebob_streaming_stream_type;
152
153 /**
154  *
155  * Buffer types known to the API
156  *
157  */
158 typedef enum {
159         freebob_buffer_type_per_stream          =   -1, // use this to use the per-stream read functions
160         freebob_buffer_type_int24           =   0,
161         freebob_buffer_type_float            =   1,
162         freebob_buffer_type_midi            =   2,
163 //      freebob_buffer_type_uint32           =   2,
164 //      freebob_buffer_type_double           =   3,
165 //      ...
166 } freebob_streaming_buffer_type;
167
168 /**
169  * Initializes the streaming from/to a FreeBoB device. A FreeBoB device
170  * is a virtual device composed of several BeBoB or compatible devices,
171  * linked together in one sync domain.
172  *
173  * This prepares all IEEE1394 related stuff and sets up all buffering.
174  * It elects a sync master if nescessary.
175  *
176  * @param device_info provides a way to specify the virtual device
177  * @param options options regarding buffers, ieee1394 setup, ...
178  *
179  * @return Opaque device handle if successful.  If this is NULL, the
180  * init operation failed.
181  *
182  */
183 freebob_device_t *freebob_streaming_init (freebob_device_info_t *device_info,
184                                         freebob_options_t options);
185
186 /**
187  * preparation should be done after setting all per-stream parameters
188  * the way you want them. being buffer data type etc...
189  *
190  * @param dev the freebob device
191  * @return
192  */
193 int freebob_streaming_prepare(freebob_device_t *dev);
194
195
196 /**
197  * Finishes the FreeBoB streaming. Cleans up all internal data structures
198  * and terminates connections.
199  *
200  * @param dev the freebob device to be closed.
201  */
202 void freebob_streaming_finish(freebob_device_t *dev);
203
204 /**
205  * Returns the amount of capture channels available
206  *
207  * @param dev the freebob device
208  *
209  * @return the number of capture streams present & active on the device.
210  *         can be 0. returns -1 upon error.
211  */
212 int freebob_streaming_get_nb_capture_streams(freebob_device_t *dev);
213
214 /**
215  * Returns the amount of playack channels available
216  *
217  * @param dev the freebob device
218  *
219  * @return the number of playback streams present & active on the device.
220  *         can be 0. returns -1 upon error.
221  */
222 int freebob_streaming_get_nb_playback_streams(freebob_device_t *dev);
223
224 /**
225  * Copies the capture channel name into the specified buffer
226  *
227  * @param dev the freebob device
228  * @param number the stream number
229  * @param buffer the buffer to copy the name into. has to be allocated.
230  * @param buffersize the size of the buffer
231  *
232  * @return the number of characters copied into the buffer
233  */
234 int freebob_streaming_get_capture_stream_name(freebob_device_t *dev, int number, char* buffer, size_t buffersize);
235
236 /**
237  * Copies the playback channel name into the specified buffer
238  *
239  * @param dev the freebob device
240  * @param number the stream number
241  * @param buffer the buffer to copy the name into. has to be allocated.
242  * @param buffersize the size of the buffer
243  *
244  * @return the number of characters copied into the buffer
245  */
246 int freebob_streaming_get_playback_stream_name(freebob_device_t *dev, int number, char* buffer, size_t buffersize);
247
248 /**
249  * Returns the type of a capture channel
250  *
251  * @param dev the freebob device
252  * @param number the stream number
253  *
254  * @return the channel type
255  */
256 freebob_streaming_stream_type freebob_streaming_get_capture_stream_type(freebob_device_t *dev, int number);
257
258 /**
259  * Returns the type of a playback channel
260  *
261  * @param dev the freebob device
262  * @param number the stream number
263  *
264  * @return the channel type
265  */
266 freebob_streaming_stream_type freebob_streaming_get_playback_stream_type(freebob_device_t *dev, int number);
267 /*
268  *
269  * Note: buffer handling will change in order to allow setting the sample type for *_read and *_write
270  * and separately indicate if you want to use a user buffer or a managed buffer.
271  *
272  */
273  
274  
275  
276 /**
277  * Sets the decode buffer for the stream. This allows for zero-copy decoding.
278  * The call to freebob_streaming_transfer_buffers will decode one period of the stream to
279  * this buffer. Make sure it is large enough.
280  *
281  * @param dev the freebob device
282  * @param number the stream number
283  * @param buff a pointer to the sample buffer, make sure it is large enough
284  *             i.e. sizeof(your_sample_type)*period_size
285  * @param t   the type of the buffer. this determines sample type and the decode function used.
286  *
287  * @return -1 on error, 0 on success
288  */
289
290 int freebob_streaming_set_capture_stream_buffer(freebob_device_t *dev, int number, char *buff);
291 int freebob_streaming_set_capture_buffer_type(freebob_device_t *dev, int i, freebob_streaming_buffer_type t);
292 int freebob_streaming_capture_stream_onoff(freebob_device_t *dev, int number, int on);
293
294 /**
295  * Sets the encode buffer for the stream. This allows for zero-copy encoding (directly to the events).
296  * The call to freebob_streaming_transfer_buffers will encode one period of the stream from
297  * this buffer to the event buffer.
298  *
299  * @param dev the freebob device
300  * @param number the stream number
301  * @param buff a pointer to the sample buffer
302  * @param t   the type of the buffer. this determines sample type and the decode function used.
303  *
304  * @return -1 on error, 0 on success
305  */
306 int freebob_streaming_set_playback_stream_buffer(freebob_device_t *dev, int number, char *buff);
307 int freebob_streaming_set_playback_buffer_type(freebob_device_t *dev, int i, freebob_streaming_buffer_type t);
308 int freebob_streaming_playback_stream_onoff(freebob_device_t *dev, int number, int on);
309
310
311 /**
312  * preparation should be done after setting all per-stream parameters
313  * the way you want them. being buffer data type etc...
314  *
315  * @param dev
316  * @return
317  */
318  
319 int freebob_streaming_prepare(freebob_device_t *dev);
320
321 /**
322  * Starts the streaming operation. This initiates the connections to the FreeBoB devices and
323  * starts the packet handling thread(s). This has to be called before any I/O can occur.
324  *
325  * @param dev the freebob device
326  *
327  * @return 0 on success, -1 on failure.
328  */
329 int freebob_streaming_start(freebob_device_t *dev);
330
331 /**
332  * Stops the streaming operation. This closes the connections to the FreeBoB devices and
333  * stops the packet handling thread(s).
334  *
335  * @param dev the freebob device
336  *
337  * @return 0 on success, -1 on failure.
338  */
339 int freebob_streaming_stop(freebob_device_t *dev);
340
341 /**
342  * Resets the streaming as if it was stopped and restarted. The difference is that the connections
343  * are not nescessarily broken and restored.
344  *
345  * All buffers are reset in the initial state and all data in them is lost.
346  *
347  * @param dev the freebob device
348  *
349  * @return 0 on success, -1 on failure.
350  */
351 int freebob_streaming_reset(freebob_device_t *dev);
352
353 /**
354  * Waits until there is at least one period of data available on all capture connections and
355  * room for one period of data on all playback connections
356  *
357  * @param dev the freebob device
358  *
359  * @return The number of frames ready. -1 when a problem occurred.
360  */
361 int freebob_streaming_wait(freebob_device_t *dev);
362
363 /**
364  * Reads from a specific channel to a supplied buffer.
365  *
366  * @param dev the freebob device
367  * @param number the stream number
368  * @param buffer the buffer to copy the samples into
369  * @param nsamples the number of samples to be read. the buffer has to be big enough for this amount of samples.
370  *
371  * @return the amount of samples actually read. -1 on error (xrun).
372  */
373 int freebob_streaming_read(freebob_device_t *dev, int number, freebob_sample_t *buffer, int nsamples);
374
375 /**
376  * Write to a specific channel from a supplied buffer.
377  *
378  * @param dev the freebob device
379  * @param number the stream number
380  * @param buffer the buffer to copy the samples from
381  * @param nsamples the number of samples to be written.
382  *
383  * @return the amount of samples actually written. -1 on error.
384  */
385 int freebob_streaming_write(freebob_device_t *dev, int number, freebob_sample_t *buffer, int nsamples);
386
387 /**
388  * Transfer & decode the events from the packet buffer to the sample buffers
389  *
390  * This should be called after the wait call returns, before reading/writing the sample buffers
391  * with freebob_streaming_[read|write].
392  *
393  * The purpose is to allow more precise timing information. freebob_streaming_wait returns as soon as the
394  * period boundary is crossed, and can therefore be used to determine the time instant of this crossing (e.g. jack DLL).
395  *
396  * The actual decoding work is done in this function and can therefore be omitted in this timing calculation.
397  * Note that you HAVE to call this function in order for the buffers not to overflow, and only call it when
398  * freebob_streaming_wait doesn't indicate a buffer xrun (xrun handler resets buffer).
399  *
400  * If user supplied playback buffers are specified with freebob_streaming_set_playback_buffers
401  * their contents should be valid before calling this function.
402  * If user supplied capture buffers are specified with freebob_streaming_set_capture_buffers
403  * their contents are updated in this function.
404  *
405  * Use either freebob_streaming_transfer_buffers to transfer all buffers at once, or use
406  * freebob_streaming_transfer_playback_buffers and freebob_streaming_transfer_capture_buffers
407  * to have more control. Don't use both.
408  *
409  * @param dev the freebob device
410  * @return  -1 on error.
411  */
412  
413 int freebob_streaming_transfer_buffers(freebob_device_t *dev);
414
415 /**
416  * Transfer & encode the events from the sample buffers to the packet buffer
417  *
418  * This should be called after the wait call returns, after writing the sample buffers
419  * with freebob_streaming_write.
420  *
421  * If user supplied playback buffers are specified with freebob_streaming_set_playback_buffers
422  * their contents should be valid before calling this function.
423  *
424  * Use either freebob_streaming_transfer_buffers to transfer all buffers at once, or use
425  * freebob_streaming_transfer_playback_buffers and freebob_streaming_transfer_capture_buffers
426  * to have more control. Don't use both.
427  *
428  * @param dev the freebob device
429  * @return  -1 on error.
430  */
431  
432 int freebob_streaming_transfer_playback_buffers(freebob_device_t *dev);
433
434 /**
435  * Transfer & decode the events from the packet buffer to the sample buffers
436  *
437  * This should be called after the wait call returns, before reading the sample buffers
438  * with freebob_streaming_read.
439  *
440  * If user supplied capture buffers are specified with freebob_streaming_set_capture_buffers
441  * their contents are updated in this function.
442  *
443  * Use either freebob_streaming_transfer_buffers to transfer all buffers at once, or use
444  * freebob_streaming_transfer_playback_buffers and freebob_streaming_transfer_capture_buffers
445  * to have more control. Don't use both.
446  *
447  * @param dev the freebob device
448  * @return  -1 on error.
449  */
450
451 int freebob_streaming_transfer_capture_buffers(freebob_device_t *dev);
452
453 #ifdef __cplusplus
454 }
455 #endif
456
457 #endif
Note: See TracBrowser for help on using the browser.