root/branches/libfreebob-1.4/libfreebob/freebob_streaming.h

Revision 241, 13.7 kB (checked in by pieterpalmers, 18 years ago)

* configure.ac: Version bump to 1.0.0

* Changed all FreeBob? to FreeBoB
* Removed all .cvsignore
* Added Pieter to AUTHORS
* Updated NEWS and README (release canditate date added)

by Daniel Wagner

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