1 //--------------------------------------------------------------------------------------------------- 2 //--------------------------------------------------------------------------------------------------- 3 4 /* 5 Steinberg Audio Stream I/O API 6 (c) 1997 - 2013, Steinberg Media Technologies GmbH 7 8 ASIO Interface Specification v 2.3 9 10 2005 - Added support for DSD sample data (in cooperation with Sony) 11 2012 - Added support for drop out detection 12 13 14 basic concept is an i/o synchronous double-buffer scheme: 15 16 on bufferSwitch(index == 0), host will read/write: 17 18 after ASIOStart(), the 19 read first input buffer A (index 0) 20 | will be invalid (empty) 21 * ------------------------ 22 |------------------------|-----------------------| 23 | | | 24 | Input Buffer A (0) | Input Buffer B (1) | 25 | | | 26 |------------------------|-----------------------| 27 | | | 28 | Output Buffer A (0) | Output Buffer B (1) | 29 | | | 30 |------------------------|-----------------------| 31 * ------------------------- 32 | before calling ASIOStart(), 33 write host will have filled output 34 buffer B (index 1) already 35 36 *please* take special care of proper statement of input 37 and output latencies (see ASIOGetLatencies()), these 38 control sequencer sync accuracy 39 40 */ 41 42 //--------------------------------------------------------------------------------------------------- 43 //--------------------------------------------------------------------------------------------------- 44 45 /* 46 47 prototypes summary: 48 49 ASIOError ASIOInit(ASIODriverInfo *info); 50 ASIOError ASIOExit(void); 51 ASIOError ASIOStart(void); 52 ASIOError ASIOStop(void); 53 ASIOError ASIOGetChannels(long *numInputChannels, long *numOutputChannels); 54 ASIOError ASIOGetLatencies(long *inputLatency, long *outputLatency); 55 ASIOError ASIOGetBufferSize(long *minSize, long *maxSize, long *preferredSize, long *granularity); 56 ASIOError ASIOCanSampleRate(ASIOSampleRate sampleRate); 57 ASIOError ASIOGetSampleRate(ASIOSampleRate *currentRate); 58 ASIOError ASIOSetSampleRate(ASIOSampleRate sampleRate); 59 ASIOError ASIOGetClockSources(ASIOClockSource *clocks, long *numSources); 60 ASIOError ASIOSetClockSource(long reference); 61 ASIOError ASIOGetSamplePosition (ASIOSamples *sPos, ASIOTimeStamp *tStamp); 62 ASIOError ASIOGetChannelInfo(ASIOChannelInfo *info); 63 ASIOError ASIOCreateBuffers(ASIOBufferInfo *bufferInfos, long numChannels, 64 long bufferSize, ASIOCallbacks *callbacks); 65 ASIOError ASIODisposeBuffers(void); 66 ASIOError ASIOControlPanel(void); 67 void *ASIOFuture(long selector, void *params); 68 ASIOError ASIOOutputReady(void); 69 70 */ 71 72 //--------------------------------------------------------------------------------------------------- 73 //--------------------------------------------------------------------------------------------------- 74 75 #ifndef __ASIO_H 76 #define __ASIO_H 77 78 // force 4 byte alignment 79 #if defined(_MSC_VER) && !defined(__MWERKS__) 80 #pragma pack(push,4) 81 #elif PRAGMA_ALIGN_SUPPORTED 82 #pragma options align = native 83 #endif 84 85 //- - - - - - - - - - - - - - - - - - - - - - - - - 86 // Type definitions 87 //- - - - - - - - - - - - - - - - - - - - - - - - - 88 89 // number of samples data type is 64 bit integer 90 #if NATIVE_INT64 91 typedef long long int ASIOSamples; 92 #else 93 typedef struct ASIOSamples { 94 unsigned long hi; 95 unsigned long lo; 96 } ASIOSamples; 97 #endif 98 99 // Timestamp data type is 64 bit integer, 100 // Time format is Nanoseconds. 101 #if NATIVE_INT64 102 typedef long long int ASIOTimeStamp ; 103 #else 104 typedef struct ASIOTimeStamp { 105 unsigned long hi; 106 unsigned long lo; 107 } ASIOTimeStamp; 108 #endif 109 110 // Samplerates are expressed in IEEE 754 64 bit double float, 111 // native format as host computer 112 #if IEEE754_64FLOAT 113 typedef double ASIOSampleRate; 114 #else 115 typedef struct ASIOSampleRate { 116 char ieee[8]; 117 } ASIOSampleRate; 118 #endif 119 120 // Boolean values are expressed as long 121 typedef long ASIOBool; 122 enum { 123 ASIOFalse = 0, 124 ASIOTrue = 1 125 }; 126 127 // Sample Types are expressed as long 128 typedef long ASIOSampleType; 129 enum { 130 ASIOSTInt16MSB = 0, 131 ASIOSTInt24MSB = 1, // used for 20 bits as well 132 ASIOSTInt32MSB = 2, 133 ASIOSTFloat32MSB = 3, // IEEE 754 32 bit float 134 ASIOSTFloat64MSB = 4, // IEEE 754 64 bit double float 135 136 // these are used for 32 bit data buffer, with different alignment of the data inside 137 // 32 bit PCI bus systems can be more easily used with these 138 ASIOSTInt32MSB16 = 8, // 32 bit data with 16 bit alignment 139 ASIOSTInt32MSB18 = 9, // 32 bit data with 18 bit alignment 140 ASIOSTInt32MSB20 = 10, // 32 bit data with 20 bit alignment 141 ASIOSTInt32MSB24 = 11, // 32 bit data with 24 bit alignment 142 143 ASIOSTInt16LSB = 16, 144 ASIOSTInt24LSB = 17, // used for 20 bits as well 145 ASIOSTInt32LSB = 18, 146 ASIOSTFloat32LSB = 19, // IEEE 754 32 bit float, as found on Intel x86 architecture 147 ASIOSTFloat64LSB = 20, // IEEE 754 64 bit double float, as found on Intel x86 architecture 148 149 // these are used for 32 bit data buffer, with different alignment of the data inside 150 // 32 bit PCI bus systems can more easily used with these 151 ASIOSTInt32LSB16 = 24, // 32 bit data with 18 bit alignment 152 ASIOSTInt32LSB18 = 25, // 32 bit data with 18 bit alignment 153 ASIOSTInt32LSB20 = 26, // 32 bit data with 20 bit alignment 154 ASIOSTInt32LSB24 = 27, // 32 bit data with 24 bit alignment 155 156 // ASIO DSD format. 157 ASIOSTDSDInt8LSB1 = 32, // DSD 1 bit data, 8 samples per byte. First sample in Least significant bit. 158 ASIOSTDSDInt8MSB1 = 33, // DSD 1 bit data, 8 samples per byte. First sample in Most significant bit. 159 ASIOSTDSDInt8NER8 = 40, // DSD 8 bit data, 1 sample per byte. No Endianness required. 160 161 ASIOSTLastEntry 162 }; 163 164 /*----------------------------------------------------------------------------- 165 // DSD operation and buffer layout 166 // Definition by Steinberg/Sony Oxford. 167 // 168 // We have tried to treat DSD as PCM and so keep a consistant structure across 169 // the ASIO interface. 170 // 171 // DSD's sample rate is normally referenced as a multiple of 44.1Khz, so 172 // the standard sample rate is refered to as 64Fs (or 2.8224Mhz). We looked 173 // at making a special case for DSD and adding a field to the ASIOFuture that 174 // would allow the user to select the Over Sampleing Rate (OSR) as a seperate 175 // entity but decided in the end just to treat it as a simple value of 176 // 2.8224Mhz and use the standard interface to set it. 177 // 178 // The second problem was the "word" size, in PCM the word size is always a 179 // greater than or equal to 8 bits (a byte). This makes life easy as we can 180 // then pack the samples into the "natural" size for the machine. 181 // In DSD the "word" size is 1 bit. This is not a major problem and can easily 182 // be dealt with if we ensure that we always deal with a multiple of 8 samples. 183 // 184 // DSD brings with it another twist to the Endianness religion. How are the 185 // samples packed into the byte. It would be nice to just say the most significant 186 // bit is always the first sample, however there would then be a performance hit 187 // on little endian machines. Looking at how some of the processing goes... 188 // Little endian machines like the first sample to be in the Least Significant Bit, 189 // this is because when you write it to memory the data is in the correct format 190 // to be shifted in and out of the words. 191 // Big endian machine prefer the first sample to be in the Most Significant Bit, 192 // again for the same reasion. 193 // 194 // And just when things were looking really muddy there is a proposed extension to 195 // DSD that uses 8 bit word sizes. It does not care what endianness you use. 196 // 197 // Switching the driver between DSD and PCM mode 198 // ASIOFuture allows for extending the ASIO API quite transparently. 199 // See kAsioSetIoFormat, kAsioGetIoFormat, kAsioCanDoIoFormat 200 // 201 //-----------------------------------------------------------------------------*/ 202 203 204 //- - - - - - - - - - - - - - - - - - - - - - - - - 205 // Error codes 206 //- - - - - - - - - - - - - - - - - - - - - - - - - 207 208 typedef long ASIOError; 209 enum { 210 ASE_OK = 0, // This value will be returned whenever the call succeeded 211 ASE_SUCCESS = 0x3f4847a0, // unique success return value for ASIOFuture calls 212 ASE_NotPresent = -1000, // hardware input or output is not present or available 213 ASE_HWMalfunction, // hardware is malfunctioning (can be returned by any ASIO function) 214 ASE_InvalidParameter, // input parameter invalid 215 ASE_InvalidMode, // hardware is in a bad mode or used in a bad mode 216 ASE_SPNotAdvancing, // hardware is not running when sample position is inquired 217 ASE_NoClock, // sample clock or rate cannot be determined or is not present 218 ASE_NoMemory // not enough memory for completing the request 219 }; 220 221 //--------------------------------------------------------------------------------------------------- 222 //--------------------------------------------------------------------------------------------------- 223 224 //- - - - - - - - - - - - - - - - - - - - - - - - - 225 // Time Info support 226 //- - - - - - - - - - - - - - - - - - - - - - - - - 227 228 typedef struct ASIOTimeCode 229 { 230 double speed; // speed relation (fraction of nominal speed) 231 // optional; set to 0. or 1. if not supported 232 ASIOSamples timeCodeSamples; // time in samples 233 unsigned long flags; // some information flags (see below) 234 char future[64]; 235 } ASIOTimeCode; 236 237 typedef enum ASIOTimeCodeFlags 238 { 239 kTcValid = 1, 240 kTcRunning = 1 << 1, 241 kTcReverse = 1 << 2, 242 kTcOnspeed = 1 << 3, 243 kTcStill = 1 << 4, 244 245 kTcSpeedValid = 1 << 8 246 } ASIOTimeCodeFlags; 247 248 typedef struct AsioTimeInfo 249 { 250 double speed; // absolute speed (1. = nominal) 251 ASIOTimeStamp systemTime; // system time related to samplePosition, in nanoseconds 252 // on mac, must be derived from Microseconds() (not UpTime()!) 253 // on windows, must be derived from timeGetTime() 254 ASIOSamples samplePosition; 255 ASIOSampleRate sampleRate; // current rate 256 unsigned long flags; // (see below) 257 char reserved[12]; 258 } AsioTimeInfo; 259 260 typedef enum AsioTimeInfoFlags 261 { 262 kSystemTimeValid = 1, // must always be valid 263 kSamplePositionValid = 1 << 1, // must always be valid 264 kSampleRateValid = 1 << 2, 265 kSpeedValid = 1 << 3, 266 267 kSampleRateChanged = 1 << 4, 268 kClockSourceChanged = 1 << 5 269 } AsioTimeInfoFlags; 270 271 typedef struct ASIOTime // both input/output 272 { 273 long reserved[4]; // must be 0 274 struct AsioTimeInfo timeInfo; // required 275 struct ASIOTimeCode timeCode; // optional, evaluated if (timeCode.flags & kTcValid) 276 } ASIOTime; 277 278 /* 279 280 using time info: 281 it is recommended to use the new method with time info even if the asio 282 device does not support timecode; continuous calls to ASIOGetSamplePosition 283 and ASIOGetSampleRate are avoided, and there is a more defined relationship 284 between callback time and the time info. 285 286 see the example below. 287 to initiate time info mode, after you have received the callbacks pointer in 288 ASIOCreateBuffers, you will call the asioMessage callback with kAsioSupportsTimeInfo 289 as the argument. if this returns 1, host has accepted time info mode. 290 now host expects the new callback bufferSwitchTimeInfo to be used instead 291 of the old bufferSwitch method. the ASIOTime structure is assumed to be valid 292 and accessible until the callback returns. 293 294 using time code: 295 if the device supports reading time code, it will call host's asioMessage callback 296 with kAsioSupportsTimeCode as the selector. it may then fill the according 297 fields and set the kTcValid flag. 298 host will call the future method with the kAsioEnableTimeCodeRead selector when 299 it wants to enable or disable tc reading by the device. you should also support 300 the kAsioCanTimeInfo and kAsioCanTimeCode selectors in ASIOFuture (see example). 301 302 note: 303 the AsioTimeInfo/ASIOTimeCode pair is supposed to work in both directions. 304 as a matter of convention, the relationship between the sample 305 position counter and the time code at buffer switch time is 306 (ignoring offset between tc and sample pos when tc is running): 307 308 on input: sample 0 -> input buffer sample 0 -> time code 0 309 on output: sample 0 -> output buffer sample 0 -> time code 0 310 311 this means that for 'real' calculations, one has to take into account 312 the according latencies. 313 314 example: 315 316 ASIOTime asioTime; 317 318 in createBuffers() 319 { 320 memset(&asioTime, 0, sizeof(ASIOTime)); 321 AsioTimeInfo* ti = &asioTime.timeInfo; 322 ti->sampleRate = theSampleRate; 323 ASIOTimeCode* tc = &asioTime.timeCode; 324 tc->speed = 1.; 325 timeInfoMode = false; 326 canTimeCode = false; 327 if(callbacks->asioMessage(kAsioSupportsTimeInfo, 0, 0, 0) == 1) 328 { 329 timeInfoMode = true; 330 #if kCanTimeCode 331 if(callbacks->asioMessage(kAsioSupportsTimeCode, 0, 0, 0) == 1) 332 canTimeCode = true; 333 #endif 334 } 335 } 336 337 void switchBuffers(long doubleBufferIndex, bool processNow) 338 { 339 if(timeInfoMode) 340 { 341 AsioTimeInfo* ti = &asioTime.timeInfo; 342 ti->flags = kSystemTimeValid | kSamplePositionValid | kSampleRateValid; 343 ti->systemTime = theNanoSeconds; 344 ti->samplePosition = theSamplePosition; 345 if(ti->sampleRate != theSampleRate) 346 ti->flags |= kSampleRateChanged; 347 ti->sampleRate = theSampleRate; 348 349 #if kCanTimeCode 350 if(canTimeCode && timeCodeEnabled) 351 { 352 ASIOTimeCode* tc = &asioTime.timeCode; 353 tc->timeCodeSamples = tcSamples; // tc in samples 354 tc->flags = kTcValid | kTcRunning | kTcOnspeed; // if so... 355 } 356 ASIOTime* bb = callbacks->bufferSwitchTimeInfo(&asioTime, doubleBufferIndex, processNow ? ASIOTrue : ASIOFalse); 357 #else 358 callbacks->bufferSwitchTimeInfo(&asioTime, doubleBufferIndex, processNow ? ASIOTrue : ASIOFalse); 359 #endif 360 } 361 else 362 callbacks->bufferSwitch(doubleBufferIndex, ASIOFalse); 363 } 364 365 ASIOError ASIOFuture(long selector, void *params) 366 { 367 switch(selector) 368 { 369 case kAsioEnableTimeCodeRead: 370 timeCodeEnabled = true; 371 return ASE_SUCCESS; 372 case kAsioDisableTimeCodeRead: 373 timeCodeEnabled = false; 374 return ASE_SUCCESS; 375 case kAsioCanTimeInfo: 376 return ASE_SUCCESS; 377 #if kCanTimeCode 378 case kAsioCanTimeCode: 379 return ASE_SUCCESS; 380 #endif 381 } 382 return ASE_NotPresent; 383 }; 384 385 */ 386 387 //- - - - - - - - - - - - - - - - - - - - - - - - - 388 // application's audio stream handler callbacks 389 //- - - - - - - - - - - - - - - - - - - - - - - - - 390 391 typedef struct ASIOCallbacks 392 { 393 void (*bufferSwitch) (long doubleBufferIndex, ASIOBool directProcess); 394 // bufferSwitch indicates that both input and output are to be processed. 395 // the current buffer half index (0 for A, 1 for B) determines 396 // - the output buffer that the host should start to fill. the other buffer 397 // will be passed to output hardware regardless of whether it got filled 398 // in time or not. 399 // - the input buffer that is now filled with incoming data. Note that 400 // because of the synchronicity of i/o, the input always has at 401 // least one buffer latency in relation to the output. 402 // directProcess suggests to the host whether it should immedeately 403 // start processing (directProcess == ASIOTrue), or whether its process 404 // should be deferred because the call comes from a very low level 405 // (for instance, a high level priority interrupt), and direct processing 406 // would cause timing instabilities for the rest of the system. If in doubt, 407 // directProcess should be set to ASIOFalse. 408 // Note: bufferSwitch may be called at interrupt time for highest efficiency. 409 410 void (*sampleRateDidChange) (ASIOSampleRate sRate); 411 // gets called when the AudioStreamIO detects a sample rate change 412 // If sample rate is unknown, 0 is passed (for instance, clock loss 413 // when externally synchronized). 414 415 long (*asioMessage) (long selector, long value, void* message, double* opt); 416 // generic callback for various purposes, see selectors below. 417 // note this is only present if the asio version is 2 or higher 418 419 ASIOTime* (*bufferSwitchTimeInfo) (ASIOTime* params, long doubleBufferIndex, ASIOBool directProcess); 420 // new callback with time info. makes ASIOGetSamplePosition() and various 421 // calls to ASIOGetSampleRate obsolete, 422 // and allows for timecode sync etc. to be preferred; will be used if 423 // the driver calls asioMessage with selector kAsioSupportsTimeInfo. 424 } ASIOCallbacks; 425 426 // asioMessage selectors 427 enum 428 { 429 kAsioSelectorSupported = 1, // selector in <value>, returns 1L if supported, 430 // 0 otherwise 431 kAsioEngineVersion, // returns engine (host) asio implementation version, 432 // 2 or higher 433 kAsioResetRequest, // request driver reset. if accepted, this 434 // will close the driver (ASIO_Exit() ) and 435 // re-open it again (ASIO_Init() etc). some 436 // drivers need to reconfigure for instance 437 // when the sample rate changes, or some basic 438 // changes have been made in ASIO_ControlPanel(). 439 // returns 1L; note the request is merely passed 440 // to the application, there is no way to determine 441 // if it gets accepted at this time (but it usually 442 // will be). 443 kAsioBufferSizeChange, // not yet supported, will currently always return 0L. 444 // for now, use kAsioResetRequest instead. 445 // once implemented, the new buffer size is expected 446 // in <value>, and on success returns 1L 447 kAsioResyncRequest, // the driver went out of sync, such that 448 // the timestamp is no longer valid. this 449 // is a request to re-start the engine and 450 // slave devices (sequencer). returns 1 for ok, 451 // 0 if not supported. 452 kAsioLatenciesChanged, // the drivers latencies have changed. The engine 453 // will refetch the latencies. 454 kAsioSupportsTimeInfo, // if host returns true here, it will expect the 455 // callback bufferSwitchTimeInfo to be called instead 456 // of bufferSwitch 457 kAsioSupportsTimeCode, // 458 kAsioMMCCommand, // unused - value: number of commands, message points to mmc commands 459 kAsioSupportsInputMonitor, // kAsioSupportsXXX return 1 if host supports this 460 kAsioSupportsInputGain, // unused and undefined 461 kAsioSupportsInputMeter, // unused and undefined 462 kAsioSupportsOutputGain, // unused and undefined 463 kAsioSupportsOutputMeter, // unused and undefined 464 kAsioOverload, // driver detected an overload 465 466 kAsioNumMessageSelectors 467 }; 468 469 //--------------------------------------------------------------------------------------------------- 470 //--------------------------------------------------------------------------------------------------- 471 472 //- - - - - - - - - - - - - - - - - - - - - - - - - 473 // (De-)Construction 474 //- - - - - - - - - - - - - - - - - - - - - - - - - 475 476 typedef struct ASIODriverInfo 477 { 478 long asioVersion; // currently, 2 479 long driverVersion; // driver specific 480 char name[32]; 481 char errorMessage[124]; 482 void *sysRef; // on input: system reference 483 // (Windows: application main window handle, Mac & SGI: 0) 484 } ASIODriverInfo; 485 486 ASIOError ASIOInit(ASIODriverInfo *info); 487 /* Purpose: 488 Initialize the AudioStreamIO. 489 Parameter: 490 info: pointer to an ASIODriver structure: 491 - asioVersion: 492 - on input, the host version. *** Note *** this is 0 for earlier asio 493 implementations, and the asioMessage callback is implemeted 494 only if asioVersion is 2 or greater. sorry but due to a design fault 495 the driver doesn't have access to the host version in ASIOInit :-( 496 added selector for host (engine) version in the asioMessage callback 497 so we're ok from now on. 498 - on return, asio implementation version. 499 older versions are 1 500 if you support this version (namely, ASIO_outputReady() ) 501 this should be 2 or higher. also see the note in 502 ASIO_getTimeStamp() ! 503 - version: on return, the driver version (format is driver specific) 504 - name: on return, a null-terminated string containing the driver's name 505 - error message: on return, should contain a user message describing 506 the type of error that occured during ASIOInit(), if any. 507 - sysRef: platform specific 508 Returns: 509 If neither input nor output is present ASE_NotPresent 510 will be returned. 511 ASE_NoMemory, ASE_HWMalfunction are other possible error conditions 512 */ 513 514 ASIOError ASIOExit(void); 515 /* Purpose: 516 Terminates the AudioStreamIO. 517 Parameter: 518 None. 519 Returns: 520 If neither input nor output is present ASE_NotPresent 521 will be returned. 522 Notes: this implies ASIOStop() and ASIODisposeBuffers(), 523 meaning that no host callbacks must be accessed after ASIOExit(). 524 */ 525 526 //- - - - - - - - - - - - - - - - - - - - - - - - - 527 // Start/Stop 528 //- - - - - - - - - - - - - - - - - - - - - - - - - 529 530 ASIOError ASIOStart(void); 531 /* Purpose: 532 Start input and output processing synchronously. 533 This will 534 - reset the sample counter to zero 535 - start the hardware (both input and output) 536 The first call to the hosts' bufferSwitch(index == 0) then tells 537 the host to read from input buffer A (index 0), and start 538 processing to output buffer A while output buffer B (which 539 has been filled by the host prior to calling ASIOStart()) 540 is possibly sounding (see also ASIOGetLatencies()) 541 Parameter: 542 None. 543 Returns: 544 If neither input nor output is present, ASE_NotPresent 545 will be returned. 546 If the hardware fails to start, ASE_HWMalfunction will be returned. 547 Notes: 548 There is no restriction on the time that ASIOStart() takes 549 to perform (that is, it is not considered a realtime trigger). 550 */ 551 552 ASIOError ASIOStop(void); 553 /* Purpose: 554 Stops input and output processing altogether. 555 Parameter: 556 None. 557 Returns: 558 If neither input nor output is present ASE_NotPresent 559 will be returned. 560 Notes: 561 On return from ASIOStop(), the driver must in no 562 case call the hosts' bufferSwitch() routine. 563 */ 564 565 //- - - - - - - - - - - - - - - - - - - - - - - - - 566 // Inquiry methods and sample rate 567 //- - - - - - - - - - - - - - - - - - - - - - - - - 568 569 ASIOError ASIOGetChannels(long *numInputChannels, long *numOutputChannels); 570 /* Purpose: 571 Returns number of individual input/output channels. 572 Parameter: 573 numInputChannels will hold the number of available input channels 574 numOutputChannels will hold the number of available output channels 575 Returns: 576 If no input/output is present ASE_NotPresent will be returned. 577 If only inputs, or only outputs are available, the according 578 other parameter will be zero, and ASE_OK is returned. 579 */ 580 581 ASIOError ASIOGetLatencies(long *inputLatency, long *outputLatency); 582 /* Purpose: 583 Returns the input and output latencies. This includes 584 device specific delays, like FIFOs etc. 585 Parameter: 586 inputLatency will hold the 'age' of the first sample frame 587 in the input buffer when the hosts reads it in bufferSwitch() 588 (this is theoretical, meaning it does not include the overhead 589 and delay between the actual physical switch, and the time 590 when bufferSitch() enters). 591 This will usually be the size of one block in sample frames, plus 592 device specific latencies. 593 594 outputLatency will specify the time between the buffer switch, 595 and the time when the next play buffer will start to sound. 596 The next play buffer is defined as the one the host starts 597 processing after (or at) bufferSwitch(), indicated by the 598 index parameter (0 for buffer A, 1 for buffer B). 599 It will usually be either one block, if the host writes directly 600 to a dma buffer, or two or more blocks if the buffer is 'latched' by 601 the driver. As an example, on ASIOStart(), the host will have filled 602 the play buffer at index 1 already; when it gets the callback (with 603 the parameter index == 0), this tells it to read from the input 604 buffer 0, and start to fill the play buffer 0 (assuming that now 605 play buffer 1 is already sounding). In this case, the output 606 latency is one block. If the driver decides to copy buffer 1 607 at that time, and pass it to the hardware at the next slot (which 608 is most commonly done, but should be avoided), the output latency 609 becomes two blocks instead, resulting in a total i/o latency of at least 610 3 blocks. As memory access is the main bottleneck in native dsp processing, 611 and to acheive less latency, it is highly recommended to try to avoid 612 copying (this is also why the driver is the owner of the buffers). To 613 summarize, the minimum i/o latency can be acheived if the input buffer 614 is processed by the host into the output buffer which will physically 615 start to sound on the next time slice. Also note that the host expects 616 the bufferSwitch() callback to be accessed for each time slice in order 617 to retain sync, possibly recursively; if it fails to process a block in 618 time, it will suspend its operation for some time in order to recover. 619 Returns: 620 If no input/output is present ASE_NotPresent will be returned. 621 */ 622 623 ASIOError ASIOGetBufferSize(long *minSize, long *maxSize, long *preferredSize, long *granularity); 624 /* Purpose: 625 Returns min, max, and preferred buffer sizes for input/output 626 Parameter: 627 minSize will hold the minimum buffer size 628 maxSize will hold the maxium possible buffer size 629 preferredSize will hold the preferred buffer size (a size which 630 best fits performance and hardware requirements) 631 granularity will hold the granularity at which buffer sizes 632 may differ. Usually, the buffer size will be a power of 2; 633 in this case, granularity will hold -1 on return, signalling 634 possible buffer sizes starting from minSize, increased in 635 powers of 2 up to maxSize. 636 Returns: 637 If no input/output is present ASE_NotPresent will be returned. 638 Notes: 639 When minimum and maximum buffer size are equal, 640 the preferred buffer size has to be the same value as well; granularity 641 should be 0 in this case. 642 */ 643 644 ASIOError ASIOCanSampleRate(ASIOSampleRate sampleRate); 645 /* Purpose: 646 Inquires the hardware for the available sample rates. 647 Parameter: 648 sampleRate is the rate in question. 649 Returns: 650 If the inquired sample rate is not supported, ASE_NoClock will be returned. 651 If no input/output is present ASE_NotPresent will be returned. 652 */ 653 ASIOError ASIOGetSampleRate(ASIOSampleRate *currentRate); 654 /* Purpose: 655 Get the current sample Rate. 656 Parameter: 657 currentRate will hold the current sample rate on return. 658 Returns: 659 If sample rate is unknown, sampleRate will be 0 and ASE_NoClock will be returned. 660 If no input/output is present ASE_NotPresent will be returned. 661 Notes: 662 */ 663 664 ASIOError ASIOSetSampleRate(ASIOSampleRate sampleRate); 665 /* Purpose: 666 Set the hardware to the requested sample Rate. If sampleRate == 0, 667 enable external sync. 668 Parameter: 669 sampleRate: on input, the requested rate 670 Returns: 671 If sampleRate is unknown ASE_NoClock will be returned. 672 If the current clock is external, and sampleRate is != 0, 673 ASE_InvalidMode will be returned 674 If no input/output is present ASE_NotPresent will be returned. 675 Notes: 676 */ 677 678 typedef struct ASIOClockSource 679 { 680 long index; // as used for ASIOSetClockSource() 681 long associatedChannel; // for instance, S/PDIF or AES/EBU 682 long associatedGroup; // see channel groups (ASIOGetChannelInfo()) 683 ASIOBool isCurrentSource; // ASIOTrue if this is the current clock source 684 char name[32]; // for user selection 685 } ASIOClockSource; 686 687 ASIOError ASIOGetClockSources(ASIOClockSource *clocks, long *numSources); 688 /* Purpose: 689 Get the available external audio clock sources 690 Parameter: 691 clocks points to an array of ASIOClockSource structures: 692 - index: this is used to identify the clock source 693 when ASIOSetClockSource() is accessed, should be 694 an index counting from zero 695 - associatedInputChannel: the first channel of an associated 696 input group, if any. 697 - associatedGroup: the group index of that channel. 698 groups of channels are defined to seperate for 699 instance analog, S/PDIF, AES/EBU, ADAT connectors etc, 700 when present simultaniously. Note that associated channel 701 is enumerated according to numInputs/numOutputs, means it 702 is independant from a group (see also ASIOGetChannelInfo()) 703 inputs are associated to a clock if the physical connection 704 transfers both data and clock (like S/PDIF, AES/EBU, or 705 ADAT inputs). if there is no input channel associated with 706 the clock source (like Word Clock, or internal oscillator), both 707 associatedChannel and associatedGroup should be set to -1. 708 - isCurrentSource: on exit, ASIOTrue if this is the current clock 709 source, ASIOFalse else 710 - name: a null-terminated string for user selection of the available sources. 711 numSources: 712 on input: the number of allocated array members 713 on output: the number of available clock sources, at least 714 1 (internal clock generator). 715 Returns: 716 If no input/output is present ASE_NotPresent will be returned. 717 Notes: 718 */ 719 720 ASIOError ASIOSetClockSource(long index); 721 /* Purpose: 722 Set the audio clock source 723 Parameter: 724 index as obtained from an inquiry to ASIOGetClockSources() 725 Returns: 726 If no input/output is present ASE_NotPresent will be returned. 727 If the clock can not be selected because an input channel which 728 carries the current clock source is active, ASE_InvalidMode 729 *may* be returned (this depends on the properties of the driver 730 and/or hardware). 731 Notes: 732 Should *not* return ASE_NoClock if there is no clock signal present 733 at the selected source; this will be inquired via ASIOGetSampleRate(). 734 It should call the host callback procedure sampleRateHasChanged(), 735 if the switch causes a sample rate change, or if no external clock 736 is present at the selected source. 737 */ 738 739 ASIOError ASIOGetSamplePosition (ASIOSamples *sPos, ASIOTimeStamp *tStamp); 740 /* Purpose: 741 Inquires the sample position/time stamp pair. 742 Parameter: 743 sPos will hold the sample position on return. The sample 744 position is reset to zero when ASIOStart() gets called. 745 tStamp will hold the system time when the sample position 746 was latched. 747 Returns: 748 If no input/output is present, ASE_NotPresent will be returned. 749 If there is no clock, ASE_SPNotAdvancing will be returned. 750 Notes: 751 752 in order to be able to synchronise properly, 753 the sample position / time stamp pair must refer to the current block, 754 that is, the engine will call ASIOGetSamplePosition() in its bufferSwitch() 755 callback and expect the time for the current block. thus, when requested 756 in the very first bufferSwitch after ASIO_Start(), the sample position 757 should be zero, and the time stamp should refer to the very time where 758 the stream was started. it also means that the sample position must be 759 block aligned. the driver must ensure proper interpolation if the system 760 time can not be determined for the block position. the driver is responsible 761 for precise time stamps as it usually has most direct access to lower 762 level resources. proper behaviour of ASIO_GetSamplePosition() and ASIO_GetLatencies() 763 are essential for precise media synchronization! 764 */ 765 766 typedef struct ASIOChannelInfo 767 { 768 long channel; // on input, channel index 769 ASIOBool isInput; // on input 770 ASIOBool isActive; // on exit 771 long channelGroup; // dto 772 ASIOSampleType type; // dto 773 char name[32]; // dto 774 } ASIOChannelInfo; 775 776 ASIOError ASIOGetChannelInfo(ASIOChannelInfo *info); 777 /* Purpose: 778 retreive information about the nature of a channel 779 Parameter: 780 info: pointer to a ASIOChannelInfo structure with 781 - channel: on input, the channel index of the channel in question. 782 - isInput: on input, ASIOTrue if info for an input channel is 783 requested, else output 784 - channelGroup: on return, the channel group that the channel 785 belongs to. For drivers which support different types of 786 channels, like analog, S/PDIF, AES/EBU, ADAT etc interfaces, 787 there should be a reasonable grouping of these types. Groups 788 are always independant form a channel index, that is, a channel 789 index always counts from 0 to numInputs/numOutputs regardless 790 of the group it may belong to. 791 There will always be at least one group (group 0). Please 792 also note that by default, the host may decide to activate 793 channels 0 and 1; thus, these should belong to the most 794 useful type (analog i/o, if present). 795 - type: on return, contains the sample type of the channel 796 - isActive: on return, ASIOTrue if channel is active as it was 797 installed by ASIOCreateBuffers(), ASIOFalse else 798 - name: describing the type of channel in question. Used to allow 799 for user selection, and enabling of specific channels. examples: 800 "Analog In", "SPDIF Out" etc 801 Returns: 802 If no input/output is present ASE_NotPresent will be returned. 803 Notes: 804 If possible, the string should be organised such that the first 805 characters are most significantly describing the nature of the 806 port, to allow for identification even if the view showing the 807 port name is too small to display more than 8 characters, for 808 instance. 809 */ 810 811 //- - - - - - - - - - - - - - - - - - - - - - - - - 812 // Buffer preparation 813 //- - - - - - - - - - - - - - - - - - - - - - - - - 814 815 typedef struct ASIOBufferInfo 816 { 817 ASIOBool isInput; // on input: ASIOTrue: input, else output 818 long channelNum; // on input: channel index 819 void *buffers[2]; // on output: double buffer addresses 820 } ASIOBufferInfo; 821 822 ASIOError ASIOCreateBuffers(ASIOBufferInfo *bufferInfos, long numChannels, 823 long bufferSize, ASIOCallbacks *callbacks); 824 825 /* Purpose: 826 Allocates input/output buffers for all input and output channels to be activated. 827 Parameter: 828 bufferInfos is a pointer to an array of ASIOBufferInfo structures: 829 - isInput: on input, ASIOTrue if the buffer is to be allocated 830 for an input, output buffer else 831 - channelNum: on input, the index of the channel in question 832 (counting from 0) 833 - buffers: on exit, 2 pointers to the halves of the channels' double-buffer. 834 the size of the buffer(s) of course depend on both the ASIOSampleType 835 as obtained from ASIOGetChannelInfo(), and bufferSize 836 numChannels is the sum of all input and output channels to be created; 837 thus bufferInfos is a pointer to an array of numChannels ASIOBufferInfo 838 structures. 839 bufferSize selects one of the possible buffer sizes as obtained from 840 ASIOGetBufferSizes(). 841 callbacks is a pointer to an ASIOCallbacks structure. 842 Returns: 843 If not enough memory is available ASE_NoMemory will be returned. 844 If no input/output is present ASE_NotPresent will be returned. 845 If bufferSize is not supported, or one or more of the bufferInfos elements 846 contain invalid settings, ASE_InvalidMode will be returned. 847 Notes: 848 If individual channel selection is not possible but requested, 849 the driver has to handle this. namely, bufferSwitch() will only 850 have filled buffers of enabled outputs. If possible, processing 851 and buss activities overhead should be avoided for channels which 852 were not enabled here. 853 */ 854 855 ASIOError ASIODisposeBuffers(void); 856 /* Purpose: 857 Releases all buffers for the device. 858 Parameter: 859 None. 860 Returns: 861 If no buffer were ever prepared, ASE_InvalidMode will be returned. 862 If no input/output is present ASE_NotPresent will be returned. 863 Notes: 864 This implies ASIOStop(). 865 */ 866 867 ASIOError ASIOControlPanel(void); 868 /* Purpose: 869 request the driver to start a control panel component 870 for device specific user settings. This will not be 871 accessed on some platforms (where the component is accessed 872 instead). 873 Parameter: 874 None. 875 Returns: 876 If no panel is available ASE_NotPresent will be returned. 877 Actually, the return code is ignored. 878 Notes: 879 if the user applied settings which require a re-configuration 880 of parts or all of the enigine and/or driver (such as a change of 881 the block size), the asioMessage callback can be used (see 882 ASIO_Callbacks). 883 */ 884 885 ASIOError ASIOFuture(long selector, void *params); 886 /* Purpose: 887 various 888 Parameter: 889 selector: operation Code as to be defined. zero is reserved for 890 testing purposes. 891 params: depends on the selector; usually pointer to a structure 892 for passing and retreiving any type and amount of parameters. 893 Returns: 894 the return value is also selector dependant. if the selector 895 is unknown, ASE_InvalidParameter should be returned to prevent 896 further calls with this selector. on success, ASE_SUCCESS 897 must be returned (note: ASE_OK is *not* sufficient!) 898 Notes: 899 see selectors defined below. 900 */ 901 902 enum 903 { 904 kAsioEnableTimeCodeRead = 1, // no arguments 905 kAsioDisableTimeCodeRead, // no arguments 906 kAsioSetInputMonitor, // ASIOInputMonitor* in params 907 kAsioTransport, // ASIOTransportParameters* in params 908 kAsioSetInputGain, // ASIOChannelControls* in params, apply gain 909 kAsioGetInputMeter, // ASIOChannelControls* in params, fill meter 910 kAsioSetOutputGain, // ASIOChannelControls* in params, apply gain 911 kAsioGetOutputMeter, // ASIOChannelControls* in params, fill meter 912 kAsioCanInputMonitor, // no arguments for kAsioCanXXX selectors 913 kAsioCanTimeInfo, 914 kAsioCanTimeCode, 915 kAsioCanTransport, 916 kAsioCanInputGain, 917 kAsioCanInputMeter, 918 kAsioCanOutputGain, 919 kAsioCanOutputMeter, 920 kAsioOptionalOne, 921 922 // DSD support 923 // The following extensions are required to allow switching 924 // and control of the DSD subsystem. 925 kAsioSetIoFormat = 0x23111961, /* ASIOIoFormat * in params. */ 926 kAsioGetIoFormat = 0x23111983, /* ASIOIoFormat * in params. */ 927 kAsioCanDoIoFormat = 0x23112004, /* ASIOIoFormat * in params. */ 928 // Extension for drop out detection 929 kAsioCanReportOverload = 0x24042012, /* return ASE_SUCCESS if driver can detect and report overloads */ 930 kAsioGetInternalBufferSamples = 0x25042012 /* ASIOInternalBufferInfo * in params. Deliver size of driver internal buffering, return ASE_SUCCESS if supported */ 931 }; 932 933 typedef struct ASIOInputMonitor 934 { 935 long input; // this input was set to monitor (or off), -1: all 936 long output; // suggested output for monitoring the input (if so) 937 long gain; // suggested gain, ranging 0 - 0x7fffffffL (-inf to +12 dB) 938 ASIOBool state; // ASIOTrue => on, ASIOFalse => off 939 long pan; // suggested pan, 0 => all left, 0x7fffffff => right 940 } ASIOInputMonitor; 941 942 typedef struct ASIOChannelControls 943 { 944 long channel; // on input, channel index 945 ASIOBool isInput; // on input 946 long gain; // on input, ranges 0 thru 0x7fffffff 947 long meter; // on return, ranges 0 thru 0x7fffffff 948 char future[32]; 949 } ASIOChannelControls; 950 951 typedef struct ASIOTransportParameters 952 { 953 long command; // see enum below 954 ASIOSamples samplePosition; 955 long track; 956 long trackSwitches[16]; // 512 tracks on/off 957 char future[64]; 958 } ASIOTransportParameters; 959 960 enum 961 { 962 kTransStart = 1, 963 kTransStop, 964 kTransLocate, // to samplePosition 965 kTransPunchIn, 966 kTransPunchOut, 967 kTransArmOn, // track 968 kTransArmOff, // track 969 kTransMonitorOn, // track 970 kTransMonitorOff, // track 971 kTransArm, // trackSwitches 972 kTransMonitor // trackSwitches 973 }; 974 975 /* 976 // DSD support 977 // Some notes on how to use ASIOIoFormatType. 978 // 979 // The caller will fill the format with the request types. 980 // If the board can do the request then it will leave the 981 // values unchanged. If the board does not support the 982 // request then it will change that entry to Invalid (-1) 983 // 984 // So to request DSD then 985 // 986 // ASIOIoFormat NeedThis={kASIODSDFormat}; 987 // 988 // if(ASE_SUCCESS != ASIOFuture(kAsioSetIoFormat,&NeedThis) ){ 989 // // If the board did not accept one of the parameters then the 990 // // whole call will fail and the failing parameter will 991 // // have had its value changes to -1. 992 // } 993 // 994 // Note: Switching between the formats need to be done before the "prepared" 995 // state (see ASIO 2 documentation) is entered. 996 */ 997 typedef long int ASIOIoFormatType; 998 enum ASIOIoFormatType_e 999 { 1000 kASIOFormatInvalid = -1, 1001 kASIOPCMFormat = 0, 1002 kASIODSDFormat = 1, 1003 }; 1004 1005 typedef struct ASIOIoFormat_s 1006 { 1007 ASIOIoFormatType FormatType; 1008 char future[512-sizeof(ASIOIoFormatType)]; 1009 } ASIOIoFormat; 1010 1011 // Extension for drop detection 1012 // Note: Refers to buffering that goes beyond the double buffer e.g. used by USB driver designs 1013 typedef struct ASIOInternalBufferInfo 1014 { 1015 long inputSamples; // size of driver's internal input buffering which is included in getLatencies 1016 long outputSamples; // size of driver's internal output buffering which is included in getLatencies 1017 } ASIOInternalBufferInfo; 1018 1019 1020 ASIOError ASIOOutputReady(void); 1021 /* Purpose: 1022 this tells the driver that the host has completed processing 1023 the output buffers. if the data format required by the hardware 1024 differs from the supported asio formats, but the hardware 1025 buffers are DMA buffers, the driver will have to convert 1026 the audio stream data; as the bufferSwitch callback is 1027 usually issued at dma block switch time, the driver will 1028 have to convert the *previous* host buffer, which increases 1029 the output latency by one block. 1030 when the host finds out that ASIOOutputReady() returns 1031 true, it will issue this call whenever it completed 1032 output processing. then the driver can convert the 1033 host data directly to the dma buffer to be played next, 1034 reducing output latency by one block. 1035 another way to look at it is, that the buffer switch is called 1036 in order to pass the *input* stream to the host, so that it can 1037 process the input into the output, and the output stream is passed 1038 to the driver when the host has completed its process. 1039 Parameter: 1040 None 1041 Returns: 1042 only if the above mentioned scenario is given, and a reduction 1043 of output latency can be acheived by this mechanism, should 1044 ASE_OK be returned. otherwise (and usually), ASE_NotPresent 1045 should be returned in order to prevent further calls to this 1046 function. note that the host may want to determine if it is 1047 to use this when the system is not yet fully initialized, so 1048 ASE_OK should always be returned if the mechanism makes sense. 1049 Notes: 1050 please remeber to adjust ASIOGetLatencies() according to 1051 whether ASIOOutputReady() was ever called or not, if your 1052 driver supports this scenario. 1053 also note that the engine may fail to call ASIO_OutputReady() 1054 in time in overload cases. as already mentioned, bufferSwitch 1055 should be called for every block regardless of whether a block 1056 could be processed in time. 1057 */ 1058 1059 // restore old alignment 1060 #if defined(_MSC_VER) && !defined(__MWERKS__) 1061 #pragma pack(pop) 1062 #elif PRAGMA_ALIGN_SUPPORTED 1063 #pragma options align = reset 1064 #endif 1065 1066 #endif 1067 1068