NetworkSIDProtocol.java

package server.netsiddev;

/** Shared wire-format limits and units of the Network SID Device protocol. */
public final class NetworkSIDProtocol {
    /** ASCII UDP discovery query; replies start with this ID followed by a comma. */
    public static final String DISCOVERY_ID = "SidDevice";
    /** Discovery receive buffer size in bytes; reply metadata may contain UTF-8 text. */
    public static final int DISCOVERY_PACKET_SIZE = 512;

    /** First version, with model, clock and sampling encoded in the header's SID byte. */
    public static final int LEGACY_VERSION = 1;
    /** Introduces separate configuration discovery and per-SID mixer controls. */
    public static final int CONFIGURATION_VERSION = 2;
    /** Introduces muting voice index 3, the digi channel. */
    public static final int DIGI_MUTE_VERSION = 3;
    /** Introduces output delay, fades and tune-header metadata. */
    public static final int METADATA_VERSION = 4;
    /** Introduces 16-bit addresses and FM OPL control. */
    public static final int EXTENDED_ADDRESS_VERSION = 5;

    /** Request header: command byte, SID byte and big-endian uint16 payload length. */
    public static final int HEADER_SIZE = 4;
    /** Largest payload representable by the header's unsigned 16-bit length. */
    public static final int MAX_PAYLOAD_LENGTH = 0xffff;
    /** Largest delay of one timed event, in C64 cycles (unsigned 16-bit). */
    public static final int MAX_CYCLE_DELAY = 0xffff;
    /** Largest fade duration, in milliseconds (unsigned 32-bit). */
    public static final long MAX_FADE_MILLISECONDS = 0xffff_ffffL;
    /** Conversion between the player API's seconds and protocol milliseconds. */
    public static final int MILLIS_PER_SECOND = 1000;
    /** Maximum ISO-8859-1 bytes in INFO, excluding its mandatory NUL terminator. */
    public static final int MAX_INFO_NAME_LENGTH = 255;
    /** Largest number of configurations representable by the COUNT response byte. */
    public static final int MAX_CONFIGURATION_COUNT = 255;

    /** Bits occupied by a SID register within a packed SID/register address. */
    public static final int SID_REGISTER_BITS = 5;
    /** Mask selecting the register in a packed SID/register address. */
    public static final int SID_REGISTER_MASK = (1 << SID_REGISTER_BITS) - 1;
    /** Number of SID slots addressable by the legacy one-byte address format. */
    public static final int LEGACY_SID_CAPACITY = 8;
    /** Number of SID slots addressable by the extended address format. */
    public static final int EXTENDED_SID_CAPACITY = 16;
    /** Highest legacy SID/register address, including all eight SID slots. */
    public static final int MAX_LEGACY_SID_ADDRESS = (LEGACY_SID_CAPACITY << SID_REGISTER_BITS) - 1;
    /** Highest extended SID/register address, including all sixteen SID slots. */
    public static final int MAX_EXTENDED_SID_ADDRESS = (EXTENDED_SID_CAPACITY << SID_REGISTER_BITS) - 1;
    /** First C64 I/O address available to extended FM OPL writes. */
    public static final int FM_ADDRESS_START = 0xdf00;
    /** Last C64 I/O address available to extended FM OPL writes, inclusive. */
    public static final int FM_ADDRESS_END = 0xdfff;
    /** Legacy write event: uint16 cycles, uint8 address, uint8 data. */
    public static final int LEGACY_WRITE_SIZE = 4;
    /** Extended write event: uint16 cycles, uint16 address, uint8 data. */
    public static final int EXTENDED_WRITE_SIZE = 5;
    /** Legacy read tail: uint16 cycles and uint8 address. */
    public static final int LEGACY_READ_SIZE = 3;
    /** Extended read tail: uint16 cycles and uint16 SID address. */
    public static final int EXTENDED_READ_SIZE = 4;

    /** Fully left position in the signed one-byte panning scale. */
    public static final int POSITION_LEFT = -100;
    /** Center position; a single configured SID is always centered. */
    public static final int POSITION_CENTER = 0;
    /** Fully right position in the signed one-byte panning scale. */
    public static final int POSITION_RIGHT = 100;
    /** Number of protocol level units per dB; one unit is 0.2 dB. */
    public static final int LEVEL_STEPS_PER_DB = 5;
    /** Largest per-SID output delay, in unsigned one-byte milliseconds. */
    public static final int MAX_OUTPUT_DELAY_MILLIS = 255;
    /** Voice index reserved for digi muting; earlier indices address the three SID voices. */
    public static final int DIGI_VOICE = 3;
    /** Default SID volume register value when starting/restoring a tune. */
    public static final byte RESET_VOLUME = 0x0f;
    /** Version-1 header bit selecting MOS8580 instead of MOS6581. */
    public static final int LEGACY_MODEL_8580 = 1;
    /** Version-1 header bit selecting NTSC instead of PAL. */
    public static final int LEGACY_CLOCK_NTSC = 2;
    /** Version-1 header bit selecting DECIMATE instead of RESAMPLE. */
    public static final int LEGACY_SAMPLING_DECIMATE = 4;

    private NetworkSIDProtocol() {
    }

    /** Whether an extended write address belongs to the FM OPL I/O window. */
    public static boolean isFmAddress(int address) {
        return address >= FM_ADDRESS_START && address <= FM_ADDRESS_END;
    }

    /** Number of SID slots addressable by the client's supported commands. */
    public static int sidCapacity(int version) {
        return version >= EXTENDED_ADDRESS_VERSION ? EXTENDED_SID_CAPACITY
                : version >= CONFIGURATION_VERSION ? LEGACY_SID_CAPACITY : 1;
    }
}