AudioDriver.java
/**
* description
* -----------
* begin : Sat Jul 8 2000
* copyright : (C) 2000 by Simon White
* email : s_a_white@email.com
* <p>
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License or
* (at your option) any later version.
*
* @author Ken Händel
*
*/
package sidplay.audio;
import libsidplay.common.CPUClock;
import libsidplay.common.EventScheduler;
import libsidplay.config.IAudioSection;
import javax.sound.sampled.LineUnavailableException;
import java.io.IOException;
import java.nio.ByteBuffer;
import java.util.Optional;
public interface AudioDriver {
/** Explicit opt-in: this live sink can discard output without pacing or recording it. */
default boolean supportsWarp() {
return false;
}
/** Called on the producer thread between mixing events; discard queued live audio on each transition. */
default void setWarp(boolean enabled) {
if (enabled) {
throw new UnsupportedOperationException("This audio driver does not support WARP");
}
}
/** Active VIC timing, supplied before open; standalone callers retain clock defaults. */
default void setVideoTiming(double screenRefresh, int borderHeight) {
}
/**
* Open audio interface.
*
* @param audioSection audio configuration
* @param recordingFilename name for a recording
* @param cpuClock CPU clock
* @param context event context
* @throws IOException error open audio device
* @throws LineUnavailableException audio device not available
*/
void open(IAudioSection audioSection, String recordingFilename, CPUClock cpuClock, EventScheduler context)
throws IOException, LineUnavailableException, InterruptedException;
/**
* Write the complete contents of ByteBuffer to an audio device.
*
* @throws InterruptedException if interrupted
*/
void write() throws InterruptedException;
/** Exact mixer sample boundaries; old drivers retain their existing write contract. */
default void write(long firstCycle, long lastCycle, long sampleOffset, int frames) throws InterruptedException {
write();
}
/** Absolute PCM frames played since open(), or -1 if unavailable. */
default long getPlayedFrames() {
return -1;
}
/** Device queue capacity in PCM frames; zero means the driver cannot report it. */
default int getPlaybackBufferFrames() {
return 0;
}
/**
* Temporarily cease audio production, for instance if user paused the
* application. Some backends such as DirectSound end up looping the audio
* unless explicitly told to pause.
* <p>
* Audio will be resumed automatically on the next writing ().
*/
default void pause() {
}
/**
* Free the audio device. (Counterpart of open().)
*/
void close();
/**
* Return the bytebuffer intended to hold the audio data.
* <p>
* The audio data is in interleaved format and has as many channels as given by
* the result of open(). Use putShort() to write 16-bit values. Don't call
* write() until you have filled the entire buffer with audio.
*
* @return The buffer to write audio to.
*/
ByteBuffer buffer();
/**
* @return is this audio driver recording tunes?
*/
boolean isRecording();
/** Whether this driver needs a tune with a known play routine address. */
default boolean requiresPlayAddress() {
return false;
}
/**
* @return file extension for recordings
*/
default String getExtension() {
return null;
}
/**
* @return concrete audio driver, if proxied
*/
default <T extends AudioDriver> Optional<T> lookup(Class<T> clz) {
if (clz.isInstance(this)) {
return Optional.of(clz.cast(this));
}
return Optional.empty();
}
}