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.residfp;

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

import java.util.function.IntConsumer;

public class SID implements SIDChip {
    private static final int INPUTDIGIBOOST = -0x9500;

    /**
     * Output scaler.
     */
    private static final float OUTPUT_LEVEL = 32768f / (2047.f * 255.f * 3.0f * 2.0f);

    /**
     * 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 Filter filter6581;

    /**
     * Filter used if the model is set to 8580
     */
    private final Filter filter8580;

    /**
     * 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;

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

    /**
     * External audio input.
     */
    private float ext_in;

    /**
     * 6581 nonlinearity terms used for all DACs
     */
    private float nonLinearity6581;

    private boolean samplesMuted;

    /**
     * Set DAC nonlinearity for 6581 emulation.
     *
     * @param nonLinearity non linearity
     * @see SID#kinkedDac(int, float, int)
     */
    public void set6581VoiceNonlinearity(final float nonLinearity) {
        if (nonLinearity == nonLinearity6581) {
            return;
        }
        nonLinearity6581 = nonLinearity;
        if (model == ChipModel.MOS6581) {
            setChipModel(model);
        }
    }

    /**
     * Estimate DAC nonlinearity. The SID contains R-2R ladder, but the second
     * resistor is not exactly double the first. The parameter nonLinearity models
     * the deviation from the resistor lengths. There appears to be about 4 % error
     * on the 6581, resulting in major kinks on the DAC. The value that the DAC
     * yields tends to be larger than expected. The output of this method is
     * normalized such that DAC errors occur both above and below the ideal value
     * equally.
     *
     * @param input        digital value to convert to analog
     * @param nonLinearity nonlinearity parameter, 1.0 for perfect linearity.
     * @param maxBit       the highest bit that may be set in input.
     * @return the analog value as modeled from the R-2R network.
     */
    static float kinkedDac(final int input, final float nonLinearity, final int maxBit) {
        float value = 0f;
        int currentBit = 1;
        float weight = 1f;
        final float dir = 2f * nonLinearity;
        for (int i = 0; i < maxBit; i++) {
            if ((input & currentBit) != 0) {
                value += weight;
            }
            currentBit <<= 1;
            weight *= dir;
        }

        return value / (weight / nonLinearity / nonLinearity) * (1 << maxBit);
    }

    /**
     * Constructor.
     */
    public SID() {
        this(new Filter6581(), new Filter8580());
    }

    protected SID(Filter filter6581, Filter filter8580) {
        this.filter6581 = filter6581;
        this.filter8580 = filter8580;
        set6581VoiceNonlinearity(0.96f);
        setChipModel(ChipModel.MOS8580);
        reset();
    }

    /**
     * Set a chip model.
     *
     * @param model chip model to use
     */
    @Override
    public void setChipModel(final ChipModel model) {
        if (this.model != model) {
            filter6581.resetState();
            filter8580.resetState();
        }
        this.model = model;
        /*
         * results from real C64 (testprogs/SID/bitfade/delayfrq0.prg):
         *
         * (new SID) (250469/8580R5) (250469/8580R5) delayfrq0 ~7a000 ~108000
         *
         * (old SID) (250407/6581) delayfrq0 ~01d00
         *
         */
        databus_ttl = model == ChipModel.MOS8580 ? 0xa2000 : 0x1d00;

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

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

        /* update voice offsets */
        for (int i = 0; i < 3; i++) {
            voice[i].setChipModel(model);
            voice[i].envelope.setNonLinearity(nonLinearity);
            // Waveform setters materialize old latches before replacing inputs;
            // renderer modes and DAC caches depend on the model as well as tables.
            voice[i].wave.setChipModel(model);
            voice[i].wave.setWftable((float[][]) tables[0], (float[]) tables[1], (byte[][]) tables[2]);
        }
    }

    protected 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;
        samplesMuted = 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) {
        // Voice outputs are 20 bits. Scale up to match three voices
        // to facilitate simulation of the MOS8580 "digi boost" hardware hack.
        ext_in = (value << 4) * 3;
    }

    /**
     * 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) {
        final byte value;
        switch (offset) {
            case 0x19:
                value = potX.readPOT();

                busValueTtl = databus_ttl;
                break;
            case 0x1a:
                value = 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.
                value = model == ChipModel.MOS6581 ? voice[2].wave.readOSC6581(voice[1].wave)
                        : voice[2].wave.readOSC8580(voice[1].wave);
                busValueTtl = databus_ttl;
                break;
            case 0x1c:
                value = voice[2].envelope.readENV();
                busValueTtl = databus_ttl;
                break;
            default:
                value = busValue;
                busValueTtl /= 2;
                break;
        }

        busValue = value;
        return value;
    }

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

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

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

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

    public boolean isDigiBoostEnabled() {
        return model == ChipModel.MOS8580 && ext_in == (INPUTDIGIBOOST << 4) * 3;
    }

    /**
     * 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 delta_t c64 clocks to clock
     * @param sample  sample consumer
     */
    @Override
    public final void clock(final int delta_t, IntConsumer sample) {
        ageBusValue(delta_t);

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

    /**
     * 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 float clock() {
        Voice first = voice[0], second = voice[1], third = voice[2];
        // Preserve the public voice array's behavior even when callers alias entries.
        if (first == second || second == third || third == first) return clockAliased(first, second, third);
        int firstRising = first.wave.clockClocked();
        int secondRising = second.wave.clockClocked();
        int thirdRising = third.wave.clockClocked();
        // All oscillators advance before any SYNC reset, avoiding voice-order
        // dependence. This backend applies SYNC before rendering the sample.
        // With no MSB rise, skipping the SYNC checks is only an optimization.
        if (((firstRising | secondRising | thirdRising) & 0x800000) != 0) {
            first.wave.synchronize(second.wave, third.wave);
            second.wave.synchronize(third.wave, first.wave);
            third.wave.synchronize(first.wave, second.wave);
        }
        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(filterClock(first.outputClocked(third.wave), second.outputClocked(first.wave),
                third.outputClocked(second.wave), ext_in));
    }

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

    protected float filterClock(float first, float second, float third, float external) {
        return filter.clock(first, second, third, external);
    }

    protected final Filter getActiveFilter() {
        return filter;
    }

    public Filter getFilter6581() {
        return filter6581;
    }

    public Filter getFilter8580() {
        return filter8580;
    }

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

}