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

Revision 194, 13.7 kB (checked in by pieterpalmers, 17 years ago)

- code cleanup in the streaming part.
- calculate ISO connection parameters instead of user-supplying them
- SSE code improvement

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