com.synthbot.jasiohost
Class AsioDriver

java.lang.Object
  com.synthbot.jasiohost.AsioDriver

public class AsioDriver
extends java.lang.Object

The AsioDriver class represents an ASIO driver. Only one may be loaded at any time. A new driver is instantiated with getDriver(), supplied with the name of the driver to load, as derived from getDriverNames().

All methods may throw an AsioException, which is a RuntimeException (i.e., it is not required to be caught). The error message will have some information about what has gone wrong. Generally, it is not possible to recover from such errors, except for shutting down the driver.

Note that most methods also throw an IllegalStateException if the driver is not in the appropriate state for that method to be called. For instance, if start() is called before createBuffers(), an IllegalStateException will be thrown.

After the driver has been instantiated with getDriver(), the sequence of setup calls are: createBuffers() and then start(). Once the driver has been started, bufferSwitch() will be called on any AsioDriverListeners and audio can be sent or received from the driver. In order to shut down the driver from the RUNNING state, call: stop(), disposeBuffers(), exit(), and finally unloadDriver() (if the driver should be fully unloaded from memory). Alternatively returnToState() can also be used in order to return the AsioDriver to a particular AsioDriverState.

Method Summary

void	addAsioDriverListener(AsioDriverListener listener) Add a new AsioDriverListener.
boolean	canSampleRate(double sampleRate) Inquires of the hardware if a specific available sample rate is available.
void	createBuffers(java.util.Set<AsioChannel> channelsToInit) Creates audio buffers for the set of designated channels.
void	disposeBuffers() Remove the previously created audio buffers (with createBuffers()).
void	exit() Closes all data structures relating to the operation of the ASIO driver, though the driver remains loaded in memory.
protected void	finalize()
int	getAsioVersion() Returns the version of ASIO which this driver uses (currently 1 or 2).
int	getBufferGranularity()
int	getBufferMaxSize() Returns the maximum supported buffer size.
int	getBufferMinSize() Returns the minimum supported buffer size.
int	getBufferPreferredSize() Returns the preferred buffer size.
AsioChannel	getChannelInput(int index) Get information about an input channel.
AsioChannel	getChannelOutput(int index) Get information about an output channel.
static AsioDriver	getCurrentDriver() Returns the currently loaded AsioDriver.
AsioDriverState	getCurrentState() Returns the current state of the ASIO driver.
static AsioDriver	getDriver(java.lang.String driverName) The designated ASIO driver is loaded and returned in the INITIALIZED state.
static java.util.List<java.lang.String>	getDriverNames() A list of all (maximum 32) ASIO drivers registered with the system is returned.
int	getLatencyInput() Note: As getLatencyInput() will also have to include the audio buffer size of the createBuffers() call, the application should call this function after the buffer creation.
int	getLatencyOutput() Note: As getLatencyOutput() will also have to include the audio buffer size of the createBuffers() call, the application should call this function after the buffer creation.
java.lang.String	getName() Returns the name of the driver.
int	getNumChannelsInput() Returns the number of available input channels.
int	getNumChannelsOutput() Returns the number of available output channels.
double	getSampleRate() Returns the current sample rate to which the host is set.
int	getVersion() Returns the version of the driver.
static boolean	isDriverLoaded() Returns true if a driver is currently loaded, false otherwise.
void	openControlPanel() Open the native control panel, allowing the user to adjust the ASIO settings.
void	removeAsioDriverListener(AsioDriverListener listener) Unregister an AsioDriverListener.
void	returnToState(AsioDriverState targetState) Return the driver to a given state.
void	shutdownAndUnloadDriver() Shutdown the ASIO driver, regardless of what state it is in.
void	start() Start the driver.
void	stop() Stop the driver.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getDriver

public static AsioDriver getDriver(java.lang.String driverName)

The designated ASIO driver is loaded and returned in the INITIALIZED state. If a driver is already loaded and it is the named driver, then that driver object is returned. If the named driver is different from the one currently loaded, then the currently loaded driver is shut down and a new one is instantiated. There is only ever one loaded driver.

Parameters:

driverName - The name of the driver to load, as returned by getDriverNames().

Returns:

The named AsioDriver object.

Throws:

AsioException - Thrown if the driver could not be loaded into memory.

java.lang.NullPointerException - Thrown if the input is null.

getCurrentDriver

public static AsioDriver getCurrentDriver()

Returns the currently loaded AsioDriver. If no driver is loaded, null is returned. Check to see if a driver is currently loaded with isDriverLoaded().

isDriverLoaded

public static boolean isDriverLoaded()

Returns true if a driver is currently loaded, false otherwise.

getDriverNames

public static java.util.List<java.lang.String> getDriverNames()

A list of all (maximum 32) ASIO drivers registered with the system is returned.

finalize

protected void finalize()
                 throws java.lang.Throwable

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable

getName

public java.lang.String getName()

Returns the name of the driver.

getVersion

public int getVersion()

Returns the version of the driver.

getAsioVersion

public int getAsioVersion()

Returns the version of ASIO which this driver uses (currently 1 or 2).

getCurrentState

public AsioDriverState getCurrentState()

Returns the current state of the ASIO driver.

exit

public void exit()

Closes all data structures relating to the operation of the ASIO driver, though the driver remains loaded in memory. Returns the driver from the INITIALIZED state to the LOADED state.

openControlPanel

public void openControlPanel()

Open the native control panel, allowing the user to adjust the ASIO settings. A control panel may not be provided by all drivers on all platforms.

getNumChannelsInput

public int getNumChannelsInput()

Returns the number of available input channels. -1 is returned if there is an error.

Returns:

The number of available input channels.

getNumChannelsOutput

public int getNumChannelsOutput()

Returns the number of available output channels. -1 is return if there is an error.

Returns:

The number of available output channels.

getSampleRate

public double getSampleRate()

Returns the current sample rate to which the host is set.

Returns:

The current sample rate.

canSampleRate

public boolean canSampleRate(double sampleRate)

Inquires of the hardware if a specific available sample rate is available.

Parameters:

sampleRate - The sample rate in question.

Returns:

True if the sample rate is supported. False otherwise.

getBufferMinSize

public int getBufferMinSize()

Returns the minimum supported buffer size.

getBufferMaxSize

public int getBufferMaxSize()

Returns the maximum supported buffer size.

getBufferPreferredSize

public int getBufferPreferredSize()

Returns the preferred buffer size. The host should attempt to use this buffer size.

getBufferGranularity

public int getBufferGranularity()

getLatencyInput

public int getLatencyInput()

Note: As getLatencyInput() will also have to include the audio buffer size of the createBuffers() call, the application should call this function after the buffer creation. In the case that the call occurs beforehand the driver should assume preferred buffer size.

Returns:

The input latency in samples.

getLatencyOutput

public int getLatencyOutput()

Note: As getLatencyOutput() will also have to include the audio buffer size of the createBuffers() call, the application should call this function after the buffer creation. In the case that the call occurs beforehand the driver should assume preferred buffer size.

Returns:

The output latency in samples.

getChannelInput

public AsioChannel getChannelInput(int index)

Get information about an input channel. The returned AsioChannel object is persistent for as long as the driver is INITIALIZED, and can be retrieved in any context.

Parameters:

index - The input channel index to get information about.

Returns:

An AsioChannel object representing the requested input channel.

Throws:

java.lang.IndexOutOfBoundsException - Thrown if the requested channel index is out of bounds. The channel does not exist.

getChannelOutput

public AsioChannel getChannelOutput(int index)

Get information about an output channel. The returned AsioChannel object is persistent for as long as the driver is INITIALIZED, and can be retrieved in any context.

Parameters:

index - The output channel index to get information about.

Returns:

An AsioChannel object representing the requested output channel.

Throws:

java.lang.IndexOutOfBoundsException - Thrown if the requested channel index is out of bounds. The channel does not exist.

createBuffers

public void createBuffers(java.util.Set<AsioChannel> channelsToInit)

Creates audio buffers for the set of designated channels. The buffer size is that as returned by getBufferPreferredSize().

Parameters:

channelsToInit - A Set of AsioChannelInfo objects designating the input and output channels to initialise and create audio buffers for.

disposeBuffers

public void disposeBuffers()

Remove the previously created audio buffers (with createBuffers()). The active channels are reset; all channels become inactive.

start

public void start()

Start the driver. Input buffers are presented and output buffers consumed via calls to bufferSwitch(). Puts the AsioDriver into the RUNNING state.

stop

public void stop()

Stop the driver. Calls to bufferSwitch() will cease. The AsioDriver returns to the PREPARED state.

shutdownAndUnloadDriver

public void shutdownAndUnloadDriver()

Shutdown the ASIO driver, regardless of what state it is in. Unload it from memory. This is a convenience method for returnToState(AsioDriverState.UNLOADED).

returnToState

public void returnToState(AsioDriverState targetState)

Return the driver to a given state. If the target state is ahead or equal to the current state then this method has no effect.

Parameters:

targetState - The state to which the driver should return.

addAsioDriverListener

public void addAsioDriverListener(AsioDriverListener listener)

Add a new AsioDriverListener. Listeners can only be updated while the driver is in the LOADED or INITIALIZED state.

Parameters:

listener - A new AsioDriverListener which should be sent callbacks.

removeAsioDriverListener

public void removeAsioDriverListener(AsioDriverListener listener)

Unregister an AsioDriverListener. Listeners can only be updated while the driver is in the LOADED or INITIALIZED state.

Parameters:

listener - A previously registered AsioDriverListener.