SID.java

/**
 * This file is part of reSID, a MOS6581 SID emulator engine.
 * Copyright (C) 2004  Dag Lem <resid@nimrod.no>
 * <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.
 * <p>
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * <p>
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 *
 * @author Ken Händel
 *
 */
package builder.resid.resid;

import libsidplay.common.ChipModel;
import libsidplay.common.Potentiometer;
import libsidplay.common.SIDChip;
import libsidplay.config.IFilterSection;

import java.util.function.IntConsumer;

/**
 * MOS6581/MOS8580 emulation. Based on reSID 1.0beta by Dag Lem, ported to Java
 * by Antti S. Lankila. Slight changes by Ken händel.
 *
 * @author Ken Händel
 * @author Dag Lem
 * @author Antti Lankila
 */
public final class SID implements SIDChip {
    private static final int INPUTDIGIBOOST = 0x3FF;
    private static final int NO_INPUTDIGIBOOST = 0x07F;

    /**
     * Output scaler.
     */
    private static final int OUTPUT_LEVEL = 359;

    /**
     * SID voices
     */
    public final Voice[] voice = new Voice[]{new Voice(), new Voice(), new Voice()};

    /**
     * Currently active filter
     */
    private Filter filter;

    /**
     * Filter used if the model is set to 6581
     */
    private final Filter6581 filter6581 = new Filter6581();

    /**
     * Filter used if the model is set to 8580
     */
    private final Filter8580 filter8580 = new Filter8580();

    private double dacNonlinearity6581 = 2.2, dacNonlinearity8580 = 2.0;

    /**
     * External filter that provides high-pass and low-pass filtering to adjust
     * sound tone slightly.
     */
    private final ExternalFilter externalFilter = new ExternalFilter();

    /**
     * Paddle X register support
     */
    private final Potentiometer potX = new Potentiometer() {
    };

    /**
     * Paddle Y register support
     */
    private final Potentiometer potY = new Potentiometer() {
    };

    /**
     * Last written value
     */
    private byte busValue;

    /**
     * Time to live for the last written value
     */
    private int busValueTtl, databus_ttl, write_address;

    /**
     * Currently active chip model.
     */
    private ChipModel model;

    /**
     * Time until synchronize() must be run.
     */
    private int nextVoiceSync;

    private final boolean[] muted = new boolean[4];

    /**
     * Estimate DAC nonlinearity. The SID contains R-2R ladder, and some likely
     * errors in the resistor lengths that result in errors depending on the bits
     * chosen.
     * <p>
     * This model was derived by Dag Lem, and is port of the upcoming reSID version.
     * On average, it shows a value higher than the target by a value that depends
     * on the _2R_div_R parameter. It differs from the version written by Antti
     * Lankila chiefly in the emulation of the lacking termination of the 2R ladder,
     * which destroys the output with respect to the low bits of the DAC.
     * <p>
     * Returns the analog value as modeled from the R-2R network.
     *
     * @param dac       digital value to convert to analog
     * @param _2R_div_R resistor ratio, 2.0 for an ideal terminated R-2R DAC.
     * @param term      is the dac terminated by a 2R resistor? (6581 DACs are not)
     */
    static void kinkedDac(final double[] dac, final double _2R_div_R, final boolean term) {
        final double INFINITY = 1e6;

        // Calculate voltage contribution by each individual bit in the R-2R
        // ladder.
        for (int set_bit = 0; set_bit < dac.length; set_bit++) {
            int bit;

            double Vn = 1; // Normalized bit voltage.
            double R = 1; // Normalized R
            double _2R = _2R_div_R * R; // 2R
            double Rn = term ? // Rn = 2R for correct termination,
                    _2R : INFINITY; // INFINITY for missing termination.

            // Calculate DAC "tail" resistance by repeated parallel
            // substitution.
            for (bit = 0; bit < set_bit; bit++) {
                if (Rn == INFINITY) {
                    Rn = R + _2R;
                } else {
                    Rn = R + _2R * Rn / (_2R + Rn); // R + 2R || Rn
                }
            }

            // Source transformation for the bit voltage.
            if (Rn == INFINITY) {
                Rn = _2R;
            } else {
                Rn = _2R * Rn / (_2R + Rn); // 2R || Rn
                Vn = Vn * Rn / _2R;
            }

            // Calculate DAC output voltage by repeated source transformation
            // from
            // the "tail".

            for (++bit; bit < dac.length; bit++) {
                Rn += R;
                double I = Vn / Rn;
                Rn = _2R * Rn / (_2R + Rn); // 2R || Rn
                Vn = Rn * I;
            }

            dac[set_bit] = Vn;
        }

        /* Normalize to integerish behavior */
        double Vsum = 0;
        for (double element : dac) {
            Vsum += element;
        }
        Vsum /= 1 << dac.length;
        for (int i = 0; i < dac.length; i++) {
            dac[i] /= Vsum;
        }
    }

    /**
     * Constructor.
     */
    public SID() {
        reset();
        setChipModel(ChipModel.MOS8580);
    }

    /**
     * Set a chip model.
     *
     * @param model chip model to use
     */
    @Override
    public void setChipModel(final ChipModel model) {
        this.model = model;

        /**
         * <pre>
         * results from real C64 (testprogs/SID/bitfade/delayfrq0.prg):
         *
         * (new SID) (250469/8580R5) (250469/8580R5)
         * delayfrq0    ~7a000        ~108000
         *
         * (old SID) (250407/6581)
         * delayfrq0    ~01d00
         *
         * </pre>
         **/
        databus_ttl = model == ChipModel.MOS8580 ? 0xa2000 : 0x1d00;

        if (model == ChipModel.MOS6581) {
            filter = filter6581;
        } else if (model == ChipModel.MOS8580) {
            filter = filter8580;
        } else {
            throw new RuntimeException("Don't know how to handle chip type " + model);
        }

        /* calculate waveform-related tables, feed them to the generator */
        final short[][] tables = WaveformCalculator.buildTable(model);

        /* update voice offsets */
        for (int i = 0; i < 3; i++) {
            voice[i].envelope.setChipModel(model);
            voice[i].wave.setChipModel(model);
            voice[i].wave.setWaveformModels(tables);
        }
        double ratio = model == ChipModel.MOS6581 ? dacNonlinearity6581 : dacNonlinearity8580;
        if (ratio != (model == ChipModel.MOS6581 ? 2.2 : 2.0)) updateVoiceDacs(ratio);
    }

    /** Preset calibration; the native defaults preserve the historical output. */
    public void configureFilter(IFilterSection settings) {
        checkedDacRatio(settings.getVoiceNonlinearity());
        filter.setResonanceFactor(settings.getResonanceFactor());
        setDacNonlinearity(settings.getVoiceNonlinearity());
        if (model == ChipModel.MOS6581) filter6581.setFilterCurve(settings.getFilter6581CurvePosition());
        else filter8580.setFilterCurve(settings.getFilter8580CurvePosition());
    }

    static double checkedDacRatio(float ratio) {
        // Use the nominal double upper bound for direct JavaScript calls at exactly 2.6.
        if (!Float.isFinite(ratio) || ratio < 1.8f || ratio > 2.6)
            throw new IllegalArgumentException("ReSID DAC resistor ratio must be 1.8..2.6");
        // Preserve the original double-precision default after INI/JSON float conversion.
        return ratio == 2.2f ? 2.2 : (double) ratio;
    }

    public float getDacNonlinearity() {
        return (float) (model == ChipModel.MOS6581 ? dacNonlinearity6581 : dacNonlinearity8580);
    }

    public void setDacNonlinearity(float ratio) {
        double calibrated = checkedDacRatio(ratio);
        if (calibrated == (model == ChipModel.MOS6581 ? dacNonlinearity6581 : dacNonlinearity8580)) return;
        if (model == ChipModel.MOS6581) {
            dacNonlinearity6581 = calibrated;
            filter6581.setDacNonlinearity(ratio);
        } else dacNonlinearity8580 = calibrated;
        updateVoiceDacs(calibrated);
    }

    private void updateVoiceDacs(double ratio) {
        for (Voice v : voice) {
            v.wave.setDacNonlinearity(ratio);
            v.envelope.setDacNonlinearity(model, ratio);
        }
    }

    ChipModel getChipModel() {
        return model;
    }

    /**
     * SID reset.
     */
    @Override
    public void reset() {
        for (int i = 0; i < 3; i++) {
            voice[i].reset();
        }
        filter6581.reset();
        filter8580.reset();
        externalFilter.reset();

        busValue = 0;
        busValueTtl = 0;
        write_address = 0;
        voiceSync(false);
    }

    /**
     * 16-bit input (EXT IN). Write a 16-bit sample to audio input. NB! The caller is
     * responsible for keeping the value within 16 bits. Note that to mix in an
     * external audio signal, the signal should be resampled to 1MHz first to avoid
     * sampling noise.
     *
     * @param value input level to set
     */
    @Override
    public void input(final int value) {
        filter6581.input(value);
        filter8580.input(value);
    }

    /**
     * Read a SID register or the retained internal bus value.
     * <p>
     * Inherited reSID bus model: readable registers drive the bus just as writes
     * do, so OSC3 refreshes the value later seen at a write-only address. The
     * chip-specific whole-byte lifetime and its halving on write-only reads
     * approximate leakage; they do not simulate the decay of individual bits.
     * SIDRegisterRegressionTest.oscReadRefreshesInternalBus checks this contract;
     * the bitfade measurements cited in setChipModel() motivate the model times.
     *
     * @param offset SID register to read
     * @return value read from chip
     */
    @Override
    public byte read(final int offset) {
        switch (offset) {
            case 0x19:
                busValue = potX.readPOT();
                busValueTtl = databus_ttl;
                break;
            case 0x1a:
                busValue = potY.readPOT();
                busValueTtl = databus_ttl;
                break;
            case 0x1b:
                // OSC3 observes voice 3's latch; its ring partner is voice 2.
                // Refreshing the internal bus must not advance oscillator time.
                busValue = model == ChipModel.MOS6581 ? voice[2].wave.readOSC6581(voice[1].wave)
                        : voice[2].wave.readOSC8580(voice[1].wave);
                busValueTtl = databus_ttl;
                break;
            case 0x1c:
                busValue = voice[2].envelope.readENV();
                busValueTtl = databus_ttl;
                break;
            default:
                busValueTtl /= 2;
                break;
        }
        return busValue;
    }

    /**
     * Write registers.
     *
     * @param offset chip register to write
     * @param value  value to write
     */
    @Override
    public void write(final int offset, final byte value) {
        write_address = offset;
        busValue = value;
        busValueTtl = databus_ttl;

        switch (write_address) {
            case 0x00:
                voice[0].wave.writeFREQ_LO(busValue);
                break;
            case 0x01:
                voice[0].wave.writeFREQ_HI(busValue);
                break;
            case 0x02:
                voice[0].wave.writePW_LO(busValue);
                break;
            case 0x03:
                voice[0].wave.writePW_HI(busValue);
                break;
            case 0x04:
                voice[0].writeCONTROL_REG(muted[0] ? 0 : busValue);
                break;
            case 0x05:
                voice[0].envelope.writeATTACK_DECAY(busValue);
                break;
            case 0x06:
                voice[0].envelope.writeSUSTAIN_RELEASE(busValue);
                break;
            case 0x07:
                voice[1].wave.writeFREQ_LO(busValue);
                break;
            case 0x08:
                voice[1].wave.writeFREQ_HI(busValue);
                break;
            case 0x09:
                voice[1].wave.writePW_LO(busValue);
                break;
            case 0x0a:
                voice[1].wave.writePW_HI(busValue);
                break;
            case 0x0b:
                voice[1].writeCONTROL_REG(muted[1] ? 0 : busValue);
                break;
            case 0x0c:
                voice[1].envelope.writeATTACK_DECAY(busValue);
                break;
            case 0x0d:
                voice[1].envelope.writeSUSTAIN_RELEASE(busValue);
                break;
            case 0x0e:
                voice[2].wave.writeFREQ_LO(busValue);
                break;
            case 0x0f:
                voice[2].wave.writeFREQ_HI(busValue);
                break;
            case 0x10:
                voice[2].wave.writePW_LO(busValue);
                break;
            case 0x11:
                voice[2].wave.writePW_HI(busValue);
                break;
            case 0x12:
                voice[2].writeCONTROL_REG(muted[2] ? 0 : busValue);
                break;
            case 0x13:
                voice[2].envelope.writeATTACK_DECAY(busValue);
                break;
            case 0x14:
                voice[2].envelope.writeSUSTAIN_RELEASE(busValue);
                break;
            case 0x15:
                filter6581.writeFC_LO(busValue);
                filter8580.writeFC_LO(busValue);
                break;
            case 0x16:
                filter6581.writeFC_HI(busValue);
                filter8580.writeFC_HI(busValue);
                break;
            case 0x17:
                filter6581.writeRES_FILT(busValue);
                filter8580.writeRES_FILT(busValue);
                break;
            case 0x18:
                // samples muted? Fade-in is allowed anyway
                if (!muted[3] || (value & 0xf) >= filter6581.vol) {
                    filter6581.writeMODE_VOL(busValue);
                    filter8580.writeMODE_VOL(busValue);
                }
                break;
            default:
                break;
        }

        /* Update voicesync just in case. */
        voiceSync(false);
    }

    /**
     * SID voice muting.
     *
     * @param channel channel to modify
     * @param mute    is muted?
     */
    @Override
    public void mute(final int channel, final boolean mute) {
        if (channel < 4) {
            muted[channel] = mute;
        }
    }

    /** Read-only presentation state; no clocking or register access. */
    public int getMuteMask() {
        return (muted[0] ? 1 : 0) | (muted[1] ? 2 : 0) | (muted[2] ? 4 : 0) | (muted[3] ? 8 : 0);
    }

    public boolean isDigiBoostEnabled() {
        return model == ChipModel.MOS8580 && filter8580.getExternalInput() == (INPUTDIGIBOOST << 4);
    }

    /**
     * Setting of clock frequency.
     *
     * @param clockFrequency System clock frequency at Hz
     */
    @Override
    public void setClockFrequency(final double clockFrequency) {
        filter6581.setClockFrequency(clockFrequency);
        filter8580.setClockFrequency(clockFrequency);
        externalFilter.setClockFrequency(clockFrequency);
    }

    private void ageBusValue(final int n) {
        if (busValueTtl != 0) {
            busValueTtl -= n;
            if (busValueTtl <= 0) {
                busValue = 0;
                busValueTtl = 0;
            }
        }
    }

    /**
     * Clock SID forward using the chosen output sampling algorithm.
     *
     * @param cycles c64 clocks to clock
     * @param sample sample consumer
     */
    @Override
    public void clock(int cycles, IntConsumer sample) {
        ageBusValue(cycles);

        while (cycles != 0) {
            int delta_t = Math.min(nextVoiceSync, cycles);
            if (delta_t > 0) {

                for (int i = 0; i < delta_t; i++) {
                    sample.accept(clock() * OUTPUT_LEVEL >> 8);
                }
                filter.zeroDenormals();
                externalFilter.zeroDenormals();

                cycles -= delta_t;
                nextVoiceSync -= delta_t;
            }

            if (nextVoiceSync == 0) {
                voiceSync(true);
            }
        }
    }

    /**
     * Advance one sample with independent voice slots. The optimized waveform
     * path assumes exactly one clock and output per slot; manual/aliased calls
     * must retain the literal latch and feedback behavior.
     */
    private int clock() {
        Voice first = voice[0], second = voice[1], third = voice[2];
        if (first == second || second == third || third == first) return clockAliased(first, second, third);
        first.wave.clockClocked();
        second.wave.clockClocked();
        third.wave.clockClocked();
        first.envelope.clock();
        second.envelope.clock();
        third.envelope.clock();
        // Ring inputs follow 1<-3, 2<-1, 3<-2, using the already-clocked phases.
        // SIDWaveformTimingTest.ringModulationUsesVoiceTwoAndTheCorrectPolarity.
        return externalFilter.clock(filter.clock(first.outputClocked(third.wave), second.outputClocked(first.wave),
                third.outputClocked(second.wave)));
    }

    /**
     * API compatibility for reused Voice objects, not a physical SID configuration.
     * Each slot retains its historical clock/output side effects; see
     * SIDWaveformAPITrace.traceAliasedNoiseBoundary.
     */
    private int clockAliased(Voice first, Voice second, Voice third) {
        first.wave.clock();
        second.wave.clock();
        third.wave.clock();
        first.envelope.clock();
        second.envelope.clock();
        third.envelope.clock();
        return externalFilter.clock(filter.clock(first.output(third.wave), second.output(first.wave),
                third.output(second.wave)));
    }

    /**
     * Apply due hard sync and schedule the next source MSB rise. This backend
     * emits the boundary sample first; synchronizeAfterOutput() preserves its
     * pulse/tri-saw latches before resetting phase. Register writes reschedule
     * with sync=false, so a changed frequency does not itself trigger a reset.
     */
    private void voiceSync(boolean sync) {
        if (sync) {
            /* Synchronize the 3 waveform generators. */
            for (int i = 0; i < 3; i++) {
                voice[i].wave.synchronizeAfterOutput(voice[(i + 1) % 3].wave, voice[(i + 2) % 3].wave);
            }
        }

        /* Calculate the time to the next voice sync */
        nextVoiceSync = Integer.MAX_VALUE;
        for (int i = 0; i < 3; i++) {
            int accumulator = voice[i].wave.accumulator;
            int freq = voice[i].wave.freq;

            if (voice[i].wave.test || freq == 0 || !voice[(i + 1) % 3].wave.sync) {
                continue;
            }

            int thisVoiceSync = (0x7fffff - accumulator & 0xffffff) / freq + 1;
            if (thisVoiceSync < nextVoiceSync) {
                nextVoiceSync = thisVoiceSync;
            }
        }
    }

    /**
     * Get chip's 6581 filter.
     *
     * @return filter
     */
    public Filter6581 getFilter6581() {
        return filter6581;
    }

    /**
     * Get chip's 8580 filter.
     *
     * @return filter
     */
    public Filter8580 getFilter8580() {
        return filter8580;
    }

    @Override
    public void setDigiBoost(boolean digiBoost) {
        if (digiBoost && model.equals(ChipModel.MOS8580)) {
            input(INPUTDIGIBOOST);
        } else {
            input(NO_INPUTDIGIBOOST);
        }
    }
}