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