79 | | #endif /* FREEBOB_H */ |
---|
| 82 | #endif /* FFADO_H */ |
---|
| 83 | |
---|
| 84 | /* ffado_streaming.h |
---|
| 85 | * |
---|
| 86 | * Specification for the FFADO Streaming API |
---|
| 87 | * |
---|
| 88 | */ |
---|
| 89 | #ifndef __FFADO_STREAMING_H__ |
---|
| 90 | #define __FFADO_STREAMING_H__ |
---|
| 91 | |
---|
| 92 | #include <stdlib.h> |
---|
| 93 | |
---|
| 94 | #ifdef __cplusplus |
---|
| 95 | extern "C" { |
---|
| 96 | #endif |
---|
| 97 | |
---|
| 98 | #define FFADO_STREAMING_MAX_URL_LENGTH 2048 |
---|
| 99 | |
---|
| 100 | #define FFADO_IGNORE_CAPTURE (1<<0) |
---|
| 101 | #define FFADO_IGNORE_PLAYBACK (1<<1) |
---|
| 102 | |
---|
| 103 | |
---|
| 104 | /* The basic operation of the API is as follows: |
---|
| 105 | * |
---|
| 106 | * ffado_streaming_init() |
---|
| 107 | * ffado_streaming_start() |
---|
| 108 | * while(running) { |
---|
| 109 | * retval = ffado_streaming_wait(); |
---|
| 110 | * if (retval == -1) { |
---|
| 111 | * ffado_streaming_reset(); |
---|
| 112 | * continue; |
---|
| 113 | * } |
---|
| 114 | * |
---|
| 115 | * ffado_streaming_transfer_buffers(dev); |
---|
| 116 | * |
---|
| 117 | * for(all channels) { |
---|
| 118 | * switch (channel_type) { |
---|
| 119 | * case audio: |
---|
| 120 | * bytesread=ffado_streaming_read(audioinbuffer[channel]); |
---|
| 121 | * byteswritten=ffado_streaming_write(audiooutbuffer[channel]); |
---|
| 122 | * case midi: |
---|
| 123 | * bytesread=ffado_streaming_read(midiinbuffer[channel]); |
---|
| 124 | * byteswritten=ffado_streaming_write(midioutbuffer[channel]); |
---|
| 125 | * } |
---|
| 126 | * } |
---|
| 127 | * } |
---|
| 128 | * ffado_streaming_stop(); |
---|
| 129 | * ffado_streaming_finish(); |
---|
| 130 | * |
---|
| 131 | */ |
---|
| 132 | |
---|
| 133 | typedef struct _ffado_device ffado_device_t; |
---|
| 134 | |
---|
| 135 | /** |
---|
| 136 | * The sample format used by the ffado streaming API |
---|
| 137 | */ |
---|
| 138 | |
---|
| 139 | typedef unsigned int ffado_sample_t; |
---|
| 140 | |
---|
| 141 | |
---|
| 142 | typedef unsigned int ffado_nframes_t; |
---|
| 143 | |
---|
| 144 | |
---|
| 145 | typedef struct ffado_device_info { |
---|
| 146 | /* TODO: How is the device specification done? */ |
---|
| 147 | // char xml_location[FFADO_STREAMING_MAX_URL_LENGTH]; // can be an osc url or an XML filename |
---|
| 148 | // ffado_device_info_location_type location_type; |
---|
| 149 | } ffado_device_info_t; |
---|
| 150 | |
---|
| 151 | /** |
---|
| 152 | * Structure to pass the options to the ffado streaming code. |
---|
| 153 | */ |
---|
| 154 | typedef struct ffado_options { |
---|
| 155 | /* driver related setup */ |
---|
| 156 | int sample_rate; /* this is acutally dictated by the device |
---|
| 157 | * you can specify a value here or -1 to autodetect |
---|
| 158 | */ |
---|
| 159 | |
---|
| 160 | /* buffer setup */ |
---|
| 161 | int period_size; /* one period is the amount of frames that |
---|
| 162 | * has to be sent or received in order for |
---|
| 163 | * a period boundary to be signalled. |
---|
| 164 | * (unit: frames) |
---|
| 165 | */ |
---|
| 166 | int nb_buffers; /* the size of the frame buffer (in periods) */ |
---|
| 167 | |
---|
| 168 | /* packetizer thread options */ |
---|
| 169 | int realtime; |
---|
| 170 | int packetizer_priority; |
---|
| 171 | |
---|
| 172 | /* libffado related setup */ |
---|
| 173 | int node_id; |
---|
| 174 | int port; |
---|
| 175 | |
---|
| 176 | /* direction map */ |
---|
| 177 | int directions; |
---|
| 178 | |
---|
| 179 | /* verbosity */ |
---|
| 180 | int verbose; |
---|
| 181 | |
---|
| 182 | /* slave mode */ |
---|
| 183 | int slave_mode; |
---|
| 184 | |
---|
| 185 | /* snoop mode */ |
---|
| 186 | int snoop_mode; |
---|
| 187 | |
---|
| 188 | } ffado_options_t; |
---|
| 189 | |
---|
| 190 | /** |
---|
| 191 | * The types of streams supported by the API |
---|
| 192 | * |
---|
| 193 | * A ffado_audio type stream is a stream that consists of successive samples. |
---|
| 194 | * The format is a 24bit UINT in host byte order, aligned as the 24LSB's of the |
---|
| 195 | * 32bit UINT of the read/write buffer. |
---|
| 196 | * The wait operation looks at this type of streams only. |
---|
| 197 | * |
---|
| 198 | * A ffado_midi type stream is a stream of midi bytes. The bytes are 8bit UINT, |
---|
| 199 | * aligned as the first 8LSB's of the 32bit UINT of the read/write buffer. |
---|
| 200 | * |
---|
| 201 | */ |
---|
| 202 | typedef enum { |
---|
| 203 | ffado_stream_type_invalid = -1, |
---|
| 204 | ffado_stream_type_unknown = 0, |
---|
| 205 | ffado_stream_type_audio = 1, |
---|
| 206 | ffado_stream_type_midi = 2, |
---|
| 207 | ffado_stream_type_control = 3, |
---|
| 208 | } ffado_streaming_stream_type; |
---|
| 209 | |
---|
| 210 | /** |
---|
| 211 | * |
---|
| 212 | * Buffer types known to the API |
---|
| 213 | * |
---|
| 214 | */ |
---|
| 215 | typedef enum { |
---|
| 216 | ffado_buffer_type_per_stream = -1, // use this to use the per-stream read functions |
---|
| 217 | ffado_buffer_type_int24 = 0, |
---|
| 218 | ffado_buffer_type_float = 1, |
---|
| 219 | ffado_buffer_type_midi = 2, |
---|
| 220 | // ffado_buffer_type_uint32 = 2, |
---|
| 221 | // ffado_buffer_type_double = 3, |
---|
| 222 | // ... |
---|
| 223 | } ffado_streaming_buffer_type; |
---|
| 224 | |
---|
| 225 | /** |
---|
| 226 | * Initializes the streaming from/to a FFADO device. A FFADO device |
---|
| 227 | * is a virtual device composed of several BeBoB or compatible devices, |
---|
| 228 | * linked together in one sync domain. |
---|
| 229 | * |
---|
| 230 | * This prepares all IEEE1394 related stuff and sets up all buffering. |
---|
| 231 | * It elects a sync master if nescessary. |
---|
| 232 | * |
---|
| 233 | * @param device_info provides a way to specify the virtual device |
---|
| 234 | * @param options options regarding buffers, ieee1394 setup, ... |
---|
| 235 | * |
---|
| 236 | * @return Opaque device handle if successful. If this is NULL, the |
---|
| 237 | * init operation failed. |
---|
| 238 | * |
---|
| 239 | */ |
---|
| 240 | ffado_device_t *ffado_streaming_init (ffado_device_info_t *device_info, |
---|
| 241 | ffado_options_t options); |
---|
| 242 | |
---|
| 243 | /** |
---|
| 244 | * preparation should be done after setting all per-stream parameters |
---|
| 245 | * the way you want them. being buffer data type etc... |
---|
| 246 | * |
---|
| 247 | * @param dev the ffado device |
---|
| 248 | * @return |
---|
| 249 | */ |
---|
| 250 | int ffado_streaming_prepare(ffado_device_t *dev); |
---|
| 251 | |
---|
| 252 | |
---|
| 253 | /** |
---|
| 254 | * Finishes the FFADO streaming. Cleans up all internal data structures |
---|
| 255 | * and terminates connections. |
---|
| 256 | * |
---|
| 257 | * @param dev the ffado device to be closed. |
---|
| 258 | */ |
---|
| 259 | void ffado_streaming_finish(ffado_device_t *dev); |
---|
| 260 | |
---|
| 261 | /** |
---|
| 262 | * Returns the amount of capture channels available |
---|
| 263 | * |
---|
| 264 | * @param dev the ffado device |
---|
| 265 | * |
---|
| 266 | * @return the number of capture streams present & active on the device. |
---|
| 267 | * can be 0. returns -1 upon error. |
---|
| 268 | */ |
---|
| 269 | int ffado_streaming_get_nb_capture_streams(ffado_device_t *dev); |
---|
| 270 | |
---|
| 271 | /** |
---|
| 272 | * Returns the amount of playack channels available |
---|
| 273 | * |
---|
| 274 | * @param dev the ffado device |
---|
| 275 | * |
---|
| 276 | * @return the number of playback streams present & active on the device. |
---|
| 277 | * can be 0. returns -1 upon error. |
---|
| 278 | */ |
---|
| 279 | int ffado_streaming_get_nb_playback_streams(ffado_device_t *dev); |
---|
| 280 | |
---|
| 281 | /** |
---|
| 282 | * Copies the capture channel name into the specified buffer |
---|
| 283 | * |
---|
| 284 | * @param dev the ffado device |
---|
| 285 | * @param number the stream number |
---|
| 286 | * @param buffer the buffer to copy the name into. has to be allocated. |
---|
| 287 | * @param buffersize the size of the buffer |
---|
| 288 | * |
---|
| 289 | * @return the number of characters copied into the buffer |
---|
| 290 | */ |
---|
| 291 | int ffado_streaming_get_capture_stream_name(ffado_device_t *dev, int number, char* buffer, size_t buffersize); |
---|
| 292 | |
---|
| 293 | /** |
---|
| 294 | * Copies the playback channel name into the specified buffer |
---|
| 295 | * |
---|
| 296 | * @param dev the ffado device |
---|
| 297 | * @param number the stream number |
---|
| 298 | * @param buffer the buffer to copy the name into. has to be allocated. |
---|
| 299 | * @param buffersize the size of the buffer |
---|
| 300 | * |
---|
| 301 | * @return the number of characters copied into the buffer |
---|
| 302 | */ |
---|
| 303 | int ffado_streaming_get_playback_stream_name(ffado_device_t *dev, int number, char* buffer, size_t buffersize); |
---|
| 304 | |
---|
| 305 | /** |
---|
| 306 | * Returns the type of a capture channel |
---|
| 307 | * |
---|
| 308 | * @param dev the ffado device |
---|
| 309 | * @param number the stream number |
---|
| 310 | * |
---|
| 311 | * @return the channel type |
---|
| 312 | */ |
---|
| 313 | ffado_streaming_stream_type ffado_streaming_get_capture_stream_type(ffado_device_t *dev, int number); |
---|
| 314 | |
---|
| 315 | /** |
---|
| 316 | * Returns the type of a playback channel |
---|
| 317 | * |
---|
| 318 | * @param dev the ffado device |
---|
| 319 | * @param number the stream number |
---|
| 320 | * |
---|
| 321 | * @return the channel type |
---|
| 322 | */ |
---|
| 323 | ffado_streaming_stream_type ffado_streaming_get_playback_stream_type(ffado_device_t *dev, int number); |
---|
| 324 | /* |
---|
| 325 | * |
---|
| 326 | * Note: buffer handling will change in order to allow setting the sample type for *_read and *_write |
---|
| 327 | * and separately indicate if you want to use a user buffer or a managed buffer. |
---|
| 328 | * |
---|
| 329 | */ |
---|
| 330 | |
---|
| 331 | |
---|
| 332 | |
---|
| 333 | /** |
---|
| 334 | * Sets the decode buffer for the stream. This allows for zero-copy decoding. |
---|
| 335 | * The call to ffado_streaming_transfer_buffers will decode one period of the stream to |
---|
| 336 | * this buffer. Make sure it is large enough. |
---|
| 337 | * |
---|
| 338 | * @param dev the ffado device |
---|
| 339 | * @param number the stream number |
---|
| 340 | * @param buff a pointer to the sample buffer, make sure it is large enough |
---|
| 341 | * i.e. sizeof(your_sample_type)*period_size |
---|
| 342 | * @param t the type of the buffer. this determines sample type and the decode function used. |
---|
| 343 | * |
---|
| 344 | * @return -1 on error, 0 on success |
---|
| 345 | */ |
---|
| 346 | |
---|
| 347 | int ffado_streaming_set_capture_stream_buffer(ffado_device_t *dev, int number, char *buff); |
---|
| 348 | int ffado_streaming_set_capture_buffer_type(ffado_device_t *dev, int i, ffado_streaming_buffer_type t); |
---|
| 349 | int ffado_streaming_capture_stream_onoff(ffado_device_t *dev, int number, int on); |
---|
| 350 | |
---|
| 351 | /** |
---|
| 352 | * Sets the encode buffer for the stream. This allows for zero-copy encoding (directly to the events). |
---|
| 353 | * The call to ffado_streaming_transfer_buffers will encode one period of the stream from |
---|
| 354 | * this buffer to the event buffer. |
---|
| 355 | * |
---|
| 356 | * @param dev the ffado device |
---|
| 357 | * @param number the stream number |
---|
| 358 | * @param buff a pointer to the sample buffer |
---|
| 359 | * @param t the type of the buffer. this determines sample type and the decode function used. |
---|
| 360 | * |
---|
| 361 | * @return -1 on error, 0 on success |
---|
| 362 | */ |
---|
| 363 | int ffado_streaming_set_playback_stream_buffer(ffado_device_t *dev, int number, char *buff); |
---|
| 364 | int ffado_streaming_set_playback_buffer_type(ffado_device_t *dev, int i, ffado_streaming_buffer_type t); |
---|
| 365 | int ffado_streaming_playback_stream_onoff(ffado_device_t *dev, int number, int on); |
---|
| 366 | |
---|
| 367 | |
---|
| 368 | /** |
---|
| 369 | * preparation should be done after setting all per-stream parameters |
---|
| 370 | * the way you want them. being buffer data type etc... |
---|
| 371 | * |
---|
| 372 | * @param dev |
---|
| 373 | * @return |
---|
| 374 | */ |
---|
| 375 | |
---|
| 376 | int ffado_streaming_prepare(ffado_device_t *dev); |
---|
| 377 | |
---|
| 378 | /** |
---|
| 379 | * Starts the streaming operation. This initiates the connections to the FFADO devices and |
---|
| 380 | * starts the packet handling thread(s). This has to be called before any I/O can occur. |
---|
| 381 | * |
---|
| 382 | * @param dev the ffado device |
---|
| 383 | * |
---|
| 384 | * @return 0 on success, -1 on failure. |
---|
| 385 | */ |
---|
| 386 | int ffado_streaming_start(ffado_device_t *dev); |
---|
| 387 | |
---|
| 388 | /** |
---|
| 389 | * Stops the streaming operation. This closes the connections to the FFADO devices and |
---|
| 390 | * stops the packet handling thread(s). |
---|
| 391 | * |
---|
| 392 | * @param dev the ffado device |
---|
| 393 | * |
---|
| 394 | * @return 0 on success, -1 on failure. |
---|
| 395 | */ |
---|
| 396 | int ffado_streaming_stop(ffado_device_t *dev); |
---|
| 397 | |
---|
| 398 | /** |
---|
| 399 | * Resets the streaming as if it was stopped and restarted. The difference is that the connections |
---|
| 400 | * are not nescessarily broken and restored. |
---|
| 401 | * |
---|
| 402 | * All buffers are reset in the initial state and all data in them is lost. |
---|
| 403 | * |
---|
| 404 | * @param dev the ffado device |
---|
| 405 | * |
---|
| 406 | * @return 0 on success, -1 on failure. |
---|
| 407 | */ |
---|
| 408 | int ffado_streaming_reset(ffado_device_t *dev); |
---|
| 409 | |
---|
| 410 | /** |
---|
| 411 | * Waits until there is at least one period of data available on all capture connections and |
---|
| 412 | * room for one period of data on all playback connections |
---|
| 413 | * |
---|
| 414 | * @param dev the ffado device |
---|
| 415 | * |
---|
| 416 | * @return The number of frames ready. -1 when a problem occurred. |
---|
| 417 | */ |
---|
| 418 | int ffado_streaming_wait(ffado_device_t *dev); |
---|
| 419 | |
---|
| 420 | /** |
---|
| 421 | * Reads from a specific channel to a supplied buffer. |
---|
| 422 | * |
---|
| 423 | * @param dev the ffado device |
---|
| 424 | * @param number the stream number |
---|
| 425 | * @param buffer the buffer to copy the samples into |
---|
| 426 | * @param nsamples the number of samples to be read. the buffer has to be big enough for this amount of samples. |
---|
| 427 | * |
---|
| 428 | * @return the amount of samples actually read. -1 on error (xrun). |
---|
| 429 | */ |
---|
| 430 | int ffado_streaming_read(ffado_device_t *dev, int number, ffado_sample_t *buffer, int nsamples); |
---|
| 431 | |
---|
| 432 | /** |
---|
| 433 | * Write to a specific channel from a supplied buffer. |
---|
| 434 | * |
---|
| 435 | * @param dev the ffado device |
---|
| 436 | * @param number the stream number |
---|
| 437 | * @param buffer the buffer to copy the samples from |
---|
| 438 | * @param nsamples the number of samples to be written. |
---|
| 439 | * |
---|
| 440 | * @return the amount of samples actually written. -1 on error. |
---|
| 441 | */ |
---|
| 442 | int ffado_streaming_write(ffado_device_t *dev, int number, ffado_sample_t *buffer, int nsamples); |
---|
| 443 | |
---|
| 444 | /** |
---|
| 445 | * Transfer & decode the events from the packet buffer to the sample buffers |
---|
| 446 | * |
---|
| 447 | * This should be called after the wait call returns, before reading/writing the sample buffers |
---|
| 448 | * with ffado_streaming_[read|write]. |
---|
| 449 | * |
---|
| 450 | * The purpose is to allow more precise timing information. ffado_streaming_wait returns as soon as the |
---|
| 451 | * period boundary is crossed, and can therefore be used to determine the time instant of this crossing (e.g. jack DLL). |
---|
| 452 | * |
---|
| 453 | * The actual decoding work is done in this function and can therefore be omitted in this timing calculation. |
---|
| 454 | * Note that you HAVE to call this function in order for the buffers not to overflow, and only call it when |
---|
| 455 | * ffado_streaming_wait doesn't indicate a buffer xrun (xrun handler resets buffer). |
---|
| 456 | * |
---|
| 457 | * If user supplied playback buffers are specified with ffado_streaming_set_playback_buffers |
---|
| 458 | * their contents should be valid before calling this function. |
---|
| 459 | * If user supplied capture buffers are specified with ffado_streaming_set_capture_buffers |
---|
| 460 | * their contents are updated in this function. |
---|
| 461 | * |
---|
| 462 | * Use either ffado_streaming_transfer_buffers to transfer all buffers at once, or use |
---|
| 463 | * ffado_streaming_transfer_playback_buffers and ffado_streaming_transfer_capture_buffers |
---|
| 464 | * to have more control. Don't use both. |
---|
| 465 | * |
---|
| 466 | * @param dev the ffado device |
---|
| 467 | * @return -1 on error. |
---|
| 468 | */ |
---|
| 469 | |
---|
| 470 | int ffado_streaming_transfer_buffers(ffado_device_t *dev); |
---|
| 471 | |
---|
| 472 | /** |
---|
| 473 | * Transfer & encode the events from the sample buffers to the packet buffer |
---|
| 474 | * |
---|
| 475 | * This should be called after the wait call returns, after writing the sample buffers |
---|
| 476 | * with ffado_streaming_write. |
---|
| 477 | * |
---|
| 478 | * If user supplied playback buffers are specified with ffado_streaming_set_playback_buffers |
---|
| 479 | * their contents should be valid before calling this function. |
---|
| 480 | * |
---|
| 481 | * Use either ffado_streaming_transfer_buffers to transfer all buffers at once, or use |
---|
| 482 | * ffado_streaming_transfer_playback_buffers and ffado_streaming_transfer_capture_buffers |
---|
| 483 | * to have more control. Don't use both. |
---|
| 484 | * |
---|
| 485 | * @param dev the ffado device |
---|
| 486 | * @return -1 on error. |
---|
| 487 | */ |
---|
| 488 | |
---|
| 489 | int ffado_streaming_transfer_playback_buffers(ffado_device_t *dev); |
---|
| 490 | |
---|
| 491 | /** |
---|
| 492 | * Transfer & decode the events from the packet buffer to the sample buffers |
---|
| 493 | * |
---|
| 494 | * This should be called after the wait call returns, before reading the sample buffers |
---|
| 495 | * with ffado_streaming_read. |
---|
| 496 | * |
---|
| 497 | * If user supplied capture buffers are specified with ffado_streaming_set_capture_buffers |
---|
| 498 | * their contents are updated in this function. |
---|
| 499 | * |
---|
| 500 | * Use either ffado_streaming_transfer_buffers to transfer all buffers at once, or use |
---|
| 501 | * ffado_streaming_transfer_playback_buffers and ffado_streaming_transfer_capture_buffers |
---|
| 502 | * to have more control. Don't use both. |
---|
| 503 | * |
---|
| 504 | * @param dev the ffado device |
---|
| 505 | * @return -1 on error. |
---|
| 506 | */ |
---|
| 507 | |
---|
| 508 | int ffado_streaming_transfer_capture_buffers(ffado_device_t *dev); |
---|
| 509 | |
---|
| 510 | #ifdef __cplusplus |
---|
| 511 | } |
---|
| 512 | #endif |
---|
| 513 | |
---|
| 514 | #endif /* FFADO_STREAMING */ |
---|