root/trunk/libffado/libffado/ffado.h

Revision 1928, 16.2 kB (checked in by jwoithe, 13 years ago)

ffado.h: remove references to old ffado_streaming_{read,write}() functions as reported by Adrian Knoth. Partial fix to ticket:313. I'm not certain I've got all the details correct - others may wish to check.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
Line 
1 /* ffado.h
2  *
3  * Copyright (C) 2005-2008 by Pieter Palmers
4  * Copyright (C) 2005-2008 by Daniel Wagner
5  *
6  * This file is part of FFADO
7  * FFADO = Free Firewire (pro-)audio drivers for linux
8  *
9  * FFADO is based upon FreeBoB
10  *
11  * This program is free software: you can redistribute it and/or modify
12  * it under the terms of the GNU General Public License as published by
13  * the Free Software Foundation, either version 2 of the License, or
14  * (at your option) version 3 of the License.
15  *
16  * This program is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
19  * GNU General Public License for more details.
20  *
21  * You should have received a copy of the GNU General Public License
22  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
23  *
24  */
25
26 #ifndef FFADO_H
27 #define FFADO_H
28
29 #define FFADO_MAX_NAME_LEN 256
30
31 #include <stdlib.h>
32
33 #define FFADO_STREAMING_MAX_URL_LENGTH 2048
34
35 #define FFADO_IGNORE_CAPTURE         (1<<0)
36 #define FFADO_IGNORE_PLAYBACK     (1<<1)
37
38 enum ffado_direction {
39     FFADO_CAPTURE  = 0,
40     FFADO_PLAYBACK = 1,
41 };
42
43 typedef struct ffado_handle* ffado_handle_t;
44
45 #ifdef __cplusplus
46 extern "C" {
47 #endif
48
49 /* ABI stuff */
50 const char*
51 ffado_get_version();
52
53 int
54 ffado_get_api_version();
55
56 /* various function */
57
58 /* The basic operation of the API is as follows:
59  *
60  * ffado_streaming_init()
61  * ffado_streaming_start()
62  * while(running) {
63  *   retval = ffado_streaming_wait();
64  *   if (retval == -1) {
65  *     ffado_streaming_reset();
66  *     continue;
67  *   }
68  *
69  *   ffado_streaming_transfer_capture_buffers(dev);
70  *
71  *   for(all channels) {
72  *     // For both audio and MIDI channels, captured data is available
73  *     // in the buffer previously set with a call to
74  *     //   ffado_streaming_set_capture_stream_buffer(dev, channel, buffer)
75  *     switch (channel_type) {
76  *     case audio:
77  *       // Process incoming audio as needed
78  *     case midi:
79  *       // Process incoming MIDI data as needed
80  *     }
81  *   }
82  *
83  *   for(all channels) {
84  *     // For both audio and MIDI channels, data is written to buffers
85  *     // previously associated with the playback channel streams using
86  *     //   ffado_streaming_set_playback_stream_buffer(dev, channel, buffer)
87  *     switch (channel_type) {
88  *     case audio:
89  *       // Set audio playback buffer contents
90  *     case midi:
91  *       // Set MIDI playback buffer contents
92  *     }
93  *   }
94  *   ffado_streaming_transfer_playback_buffers(dev);
95  *
96  * }
97  * ffado_streaming_stop();
98  * ffado_streaming_finish();
99  *
100  */
101
102 typedef struct _ffado_device ffado_device_t;
103
104 /**
105  * The sample format used by the ffado streaming API
106  */
107
108 typedef unsigned int ffado_sample_t; // FIXME
109 typedef unsigned int ffado_nframes_t;
110
111 #define FFADO_MAX_SPECSTRING_LENGTH 256
112 #define FFADO_MAX_SPECSTRINGS       64
113 /**
114  * This struct serves to define the devices that should be used by the library
115  * device_spec_strings is an array of pointers that should contain nb_device_spec_strings
116  * valid pointers to strings.
117  *
118  * The spec strings should be null terminated and can be no longer
119  * than FFADO_MAX_SPECSTRINGS.
120  *
121  * nb_device_spec_strings < FFADO_MAX_SPECSTRING_LENGTH
122  * nb_device_spec_strings >= 0
123  *
124  * If nb_device_spec_strings == 0, all busses are scanned for attached devices, and
125  * all found devices that are supported are combined into one large pseudo-device. The
126  * device order is defined by the GUID of the device. Devices with lower GUID's will
127  * be the first ones.
128  *
129  * If multiple device specifications are present, the device order is defined as follows:
130  *  - device(s) that correspond to a spec string with a lower index will be added before
131  *    devices from higher indexes.
132  *  - if a spec string results in multiple devices, they are sorted by GUID unless the
133  *    spec format dictates otherwise.
134  *
135  * The actual meaning of the device specification should be one of the following:
136  * - Format 1: "hw:x[,y[,z]]"
137  *     x = the firewire bus to use ('port' in raw1394 terminology)
138  *         (mandatory)
139  *     y = the node id the device currently has (bus resets might change that, but FFADO
140  *         will track these changes and keep using the device specified on startup)
141  *         (optional)
142  *     z = the stream direction to use.
143  *           0 => capture (record) channels only
144  *           1 => playback channels only
145  *           other/unspecified => both playback and capture
146  *         (optional)
147  *
148  * - Format 2: the device alias as defined in the ffado config file (UNIMPLEMENTED)
149  */
150 typedef struct ffado_device_info {
151     unsigned int nb_device_spec_strings;
152     char **device_spec_strings;
153
154     /* add some extra space to allow for future API extention
155        w/o breaking binary compatibility */
156     int32_t reserved[32];
157 } ffado_device_info_t;
158
159 /**
160  * Structure to pass the options to the ffado streaming code.
161  */
162 typedef struct ffado_options {
163     /* driver related setup */
164     int32_t sample_rate;         /*
165                              * you can specify a value here or -1 to autodetect
166                               */
167
168     /* buffer setup */
169     int32_t period_size;     /* one period is the amount of frames that
170                  * has to be sent or received in order for
171                  * a period boundary to be signalled.
172                  * (unit: frames)
173                  */
174     int32_t nb_buffers;    /* the size of the frame buffer (in periods) */
175
176     /* packetizer thread options */
177     int32_t realtime;
178     int32_t packetizer_priority;
179
180     /* verbosity */
181     int32_t verbose;
182
183     /* slave mode */
184     int32_t slave_mode;
185     /* snoop mode */
186     int32_t snoop_mode;
187
188     /* add some extra space to allow for future API extention
189        w/o breaking binary compatibility */
190     int32_t reserved[24];
191
192 } ffado_options_t;
193
194 /**
195  * The types of streams supported by the API
196  *
197  * A ffado_audio type stream is a stream that consists of successive samples.
198  * The format is a 24bit UINT in host byte order, aligned as the 24LSB's of the
199  * 32bit UINT of the read/write buffer.
200  * The wait operation looks at this type of streams only.
201  *
202  * A ffado_midi type stream is a stream of midi bytes. The bytes are 8bit UINT,
203  * aligned as the first 8LSB's of the 32bit UINT of the read/write buffer.
204  *
205  * A ffado_control type stream is a stream that provides control information. The
206  * format of this control information is undefined, and the stream should be ignored.
207  *
208  */
209 typedef enum {
210       ffado_stream_type_invalid                      =   -1,
211       ffado_stream_type_unknown                      =   0,
212       ffado_stream_type_audio                        =   1,
213       ffado_stream_type_midi                         =   2,
214       ffado_stream_type_control                      =   3,
215 } ffado_streaming_stream_type;
216
217 /**
218  *
219  * Audio data types known to the API
220  *
221  */
222 typedef enum {
223     ffado_audio_datatype_error           = -1,
224     ffado_audio_datatype_int24           =  0,
225     ffado_audio_datatype_float           =  1,
226 } ffado_streaming_audio_datatype;
227
228 /**
229  *
230  * Wait responses
231  *
232  */
233 typedef enum {
234     ffado_wait_shutdown        = -3,
235     ffado_wait_error           = -2,
236     ffado_wait_xrun            = -1,
237     ffado_wait_ok              =  0,
238 } ffado_wait_response;
239
240 /**
241  * Initializes the streaming from/to a FFADO device. A FFADO device
242  * is a virtual device composed of several BeBoB or compatible devices,
243  * linked together in one sync domain.
244  *
245  * This prepares all IEEE1394 related stuff and sets up all buffering.
246  * It elects a sync master if nescessary.
247  *
248  * @param device_info provides a way to specify the virtual device
249  * @param options options regarding buffers, ieee1394 setup, ...
250  *
251  * @return Opaque device handle if successful.  If this is NULL, the
252  * init operation failed.
253  *
254  */
255 ffado_device_t *ffado_streaming_init(
256                      ffado_device_info_t device_info,
257                      ffado_options_t options);
258
259 /**
260  * preparation should be done after setting all per-stream parameters
261  * the way you want them. being buffer data type etc...
262  *
263  * @param dev the ffado device
264  * @return
265  */
266 int ffado_streaming_prepare(ffado_device_t *dev);
267
268
269 /**
270  * Finishes the FFADO streaming. Cleans up all internal data structures
271  * and terminates connections.
272  *
273  * @param dev the ffado device to be closed.
274  */
275 void ffado_streaming_finish(ffado_device_t *dev);
276
277 /**
278  * Returns the amount of capture channels available
279  *
280  * @param dev the ffado device
281  *
282  * @return the number of capture streams present & active on the device.
283  *         can be 0. returns -1 upon error.
284  */
285 int ffado_streaming_get_nb_capture_streams(ffado_device_t *dev);
286
287 /**
288  * Returns the amount of playack channels available
289  *
290  * @param dev the ffado device
291  *
292  * @return the number of playback streams present & active on the device.
293  *         can be 0. returns -1 upon error.
294  */
295 int ffado_streaming_get_nb_playback_streams(ffado_device_t *dev);
296
297 /**
298  * Copies the capture channel name into the specified buffer
299  *
300  * @param dev the ffado device
301  * @param number the stream number
302  * @param buffer the buffer to copy the name into. has to be allocated.
303  * @param buffersize the size of the buffer
304  *
305  * @return the number of characters copied into the buffer
306  */
307 int ffado_streaming_get_capture_stream_name(ffado_device_t *dev, int number, char* buffer, size_t buffersize);
308
309 /**
310  * Copies the playback channel name into the specified buffer
311  *
312  * @param dev the ffado device
313  * @param number the stream number
314  * @param buffer the buffer to copy the name into. has to be allocated.
315  * @param buffersize the size of the buffer
316  *
317  * @return the number of characters copied into the buffer
318  */
319 int ffado_streaming_get_playback_stream_name(ffado_device_t *dev, int number, char* buffer, size_t buffersize);
320
321 /**
322  * Returns the type of a capture channel
323  *
324  * @param dev the ffado device
325  * @param number the stream number
326  *
327  * @return the channel type
328  */
329 ffado_streaming_stream_type ffado_streaming_get_capture_stream_type(ffado_device_t *dev, int number);
330
331 /**
332  * Returns the type of a playback channel
333  *
334  * @param dev the ffado device
335  * @param number the stream number
336  *
337  * @return the channel type
338  */
339 ffado_streaming_stream_type ffado_streaming_get_playback_stream_type(ffado_device_t *dev, int number);
340 /*
341  *
342  * Note: buffer handling will change in order to allow setting the sample type for *_read and *_write
343  * and separately indicate if you want to use a user buffer or a managed buffer.
344  *
345  */
346
347 /**
348  * Sets the decode buffer for the stream. This allows for zero-copy decoding.
349  * The call to ffado_streaming_transfer_buffers will decode one period of the stream to
350  * this buffer. Make sure it is large enough.
351  *
352  * @param dev the ffado device
353  * @param number the stream number
354  * @param buff a pointer to the sample buffer, make sure it is large enough
355  *             i.e. sizeof(your_sample_type)*period_size
356  * @param t   the type of the buffer. this determines sample type and the decode function used.
357  *
358  * @return -1 on error, 0 on success
359  */
360
361 int ffado_streaming_set_capture_stream_buffer(ffado_device_t *dev, int number, char *buff);
362 int ffado_streaming_capture_stream_onoff(ffado_device_t *dev, int number, int on);
363
364 /**
365  * Sets the encode buffer for the stream. This allows for zero-copy encoding (directly to the events).
366  * The call to ffado_streaming_transfer_buffers will encode one period of the stream from
367  * this buffer to the event buffer.
368  *
369  * @param dev the ffado device
370  * @param number the stream number
371  * @param buff a pointer to the sample buffer
372  * @param t   the type of the buffer. this determines sample type and the decode function used.
373  *
374  * @return -1 on error, 0 on success
375  */
376 int ffado_streaming_set_playback_stream_buffer(ffado_device_t *dev, int number, char *buff);
377 int ffado_streaming_playback_stream_onoff(ffado_device_t *dev, int number, int on);
378
379 ffado_streaming_audio_datatype ffado_streaming_get_audio_datatype(ffado_device_t *dev);
380 int ffado_streaming_set_audio_datatype(ffado_device_t *dev, ffado_streaming_audio_datatype t);
381
382 /**
383  * preparation should be done after setting all per-stream parameters
384  * the way you want them. being buffer data type etc...
385  *
386  * @param dev
387  * @return
388  */
389  
390 int ffado_streaming_prepare(ffado_device_t *dev);
391
392 /**
393  * Starts the streaming operation. This initiates the connections to the FFADO devices and
394  * starts the packet handling thread(s). This has to be called before any I/O can occur.
395  *
396  * @param dev the ffado device
397  *
398  * @return 0 on success, -1 on failure.
399  */
400 int ffado_streaming_start(ffado_device_t *dev);
401
402 /**
403  * Stops the streaming operation. This closes the connections to the FFADO devices and
404  * stops the packet handling thread(s).
405  *
406  * @param dev the ffado device
407  *
408  * @return 0 on success, -1 on failure.
409  */
410 int ffado_streaming_stop(ffado_device_t *dev);
411
412 /**
413  * Resets the streaming as if it was stopped and restarted. The difference is that the connections
414  * are not nescessarily broken and restored.
415  *
416  * All buffers are reset in the initial state and all data in them is lost.
417  *
418  * @param dev the ffado device
419  *
420  * @return 0 on success, -1 on failure.
421  */
422 int ffado_streaming_reset(ffado_device_t *dev);
423
424 /**
425  * Waits until there is at least one period of data available on all capture connections and
426  * room for one period of data on all playback connections
427  *
428  * @param dev the ffado device
429  *
430  * @return The number of frames ready. -1 when a problem occurred.
431  */
432 ffado_wait_response ffado_streaming_wait(ffado_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/writing the sample buffers
438  * with ffado_streaming_[read|write].
439  *
440  * The purpose is to allow more precise timing information. ffado_streaming_wait returns as soon as the
441  * period boundary is crossed, and can therefore be used to determine the time instant of this crossing (e.g. jack DLL).
442  *
443  * The actual decoding work is done in this function and can therefore be omitted in this timing calculation.
444  * Note that you HAVE to call this function in order for the buffers not to overflow, and only call it when
445  * ffado_streaming_wait doesn't indicate a buffer xrun (xrun handler resets buffer).
446  *
447  * If user supplied playback buffers are specified with ffado_streaming_set_playback_buffers
448  * their contents should be valid before calling this function.
449  * If user supplied capture buffers are specified with ffado_streaming_set_capture_buffers
450  * their contents are updated in this function.
451  *
452  * Use either ffado_streaming_transfer_buffers to transfer all buffers at once, or use
453  * ffado_streaming_transfer_playback_buffers and ffado_streaming_transfer_capture_buffers
454  * to have more control. Don't use both.
455  *
456  * @param dev the ffado device
457  * @return  -1 on error.
458  */
459  
460 int ffado_streaming_transfer_buffers(ffado_device_t *dev);
461
462 /**
463  * Transfer & encode the events from the sample buffers to the packet buffer
464  *
465  * This should be called after the wait call returns, after writing the sample buffers
466  * with ffado_streaming_write.
467  *
468  * If user supplied playback buffers are specified with ffado_streaming_set_playback_buffers
469  * their contents should be valid before calling this function.
470  *
471  * Use either ffado_streaming_transfer_buffers to transfer all buffers at once, or use
472  * ffado_streaming_transfer_playback_buffers and ffado_streaming_transfer_capture_buffers
473  * to have more control. Don't use both.
474  *
475  * @param dev the ffado device
476  * @return  -1 on error.
477  */
478  
479 int ffado_streaming_transfer_playback_buffers(ffado_device_t *dev);
480
481 /**
482  * Transfer & decode the events from the packet buffer to the sample buffers
483  *
484  * This should be called after the wait call returns, before reading the sample buffers
485  * with ffado_streaming_read.
486  *
487  * If user supplied capture buffers are specified with ffado_streaming_set_capture_buffers
488  * their contents are updated in this function.
489  *
490  * Use either ffado_streaming_transfer_buffers to transfer all buffers at once, or use
491  * ffado_streaming_transfer_playback_buffers and ffado_streaming_transfer_capture_buffers
492  * to have more control. Don't use both.
493  *
494  * @param dev the ffado device
495  * @return  -1 on error.
496  */
497
498 int ffado_streaming_transfer_capture_buffers(ffado_device_t *dev);
499
500 #ifdef __cplusplus
501 }
502 #endif
503
504 #endif /* FFADO_STREAMING */
Note: See TracBrowser for help on using the browser.