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();
    }

}