InspectionTimeline.java

package libsidutils.debug;

import java.util.ArrayList;
import java.util.List;

/**
 * Detached one-frame change log. Ticks are half cycles relative to the observed raster-zero transition.
 */
public record InspectionTimeline(int version, int generation, String status, String model, String chip, String clock,
                                 int cyclesPerLine, int rasterLines, long startTime, int startCycle, int durationTicks,
                                 int[] initial, List<Change> events) {
    public static final int DMA = 64, BANK = 65, POINTERS = 66, FIELD_COUNT = 74, MAX_EVENTS = 8192;

    public record Change(int tick, int raster, int cycle, String phase, int field, int previous, int value) {
    }

    public record Span(int start, int end) {
    }

    public static int spriteMask(Change change) {
        int field = change.field();
        if (field < 16) return 1 << (field / 2);
        if (field >= 0x27 && field <= 0x2e) return 1 << (field - 0x27);
        if (field >= POINTERS) return 1 << (field - POINTERS);
        if (field == 0x10 || field == 0x15 || field == 0x17 || field == 0x1b || field == 0x1c || field == 0x1d
                || field == 0x1e || field == 0x1f || field == DMA) return (change.previous() ^ change.value()) & 255;
        return field == BANK || field == 0x18 || field == 0x25 || field == 0x26 ? 255 : 0;
    }

    public boolean recording() {
        return status.equals("WAITING") || status.equals("RECORDING");
    }

    public int[] stateAt(int tick) {
        int[] state = initial.clone();
        for (Change change : events) {
            if (change.tick() > tick) break;
            state[change.field()] = change.value();
        }
        return state;
    }

    /**
     * Enabled and DMA intervals are distinct: DMA is not a promise that opaque pixels were visible.
     */
    public List<Span> spans(int sprite, boolean dma) {
        List<Span> spans = new ArrayList<>();
        if (initial.length == 0) return spans;
        int field = dma ? DMA : 0x15, bit = 1 << sprite;
        int start = (initial[field] & bit) != 0 ? 0 : -1;
        for (Change change : events) {
            if (change.field() != field || ((change.previous() ^ change.value()) & bit) == 0) continue;
            if ((change.value() & bit) != 0) start = change.tick();
            else {
                if (start >= 0 && change.tick() > start) spans.add(new Span(start, change.tick()));
                start = -1;
            }
        }
        if (start >= 0 && durationTicks > start) spans.add(new Span(start, durationTicks));
        return spans;
    }

    public String messageJson() {
        return "{\"version\":" + version + ",\"reason\":\"TIMELINE\",\"timeline\":" + toJson() + "}";
    }

    public static String clearedMessageJson() {
        return "{\"version\":1,\"reason\":\"TIMELINE\",\"timeline\":null}";
    }

    public String toJson() {
        StringBuilder json = new StringBuilder(1024 + events.size() * 96);
        json.append("{\"version\":").append(version).append(",\"generation\":").append(generation)
                .append(",\"status\":\"").append(status).append("\",\"model\":\"").append(model)
                .append("\",\"chip\":\"").append(chip).append("\",\"clock\":\"").append(clock)
                .append("\",\"cyclesPerLine\":").append(cyclesPerLine).append(",\"rasterLines\":").append(rasterLines)
                .append(",\"startTime\":").append(startTime).append(",\"startCycle\":").append(startCycle)
                .append(",\"durationTicks\":").append(durationTicks).append(",\"initial\":[");
        for (int i = 0; i < initial.length; i++) {
            if (i != 0) json.append(',');
            json.append(initial[i]);
        }
        json.append("],\"events\":[");
        for (int i = 0; i < events.size(); i++) {
            if (i != 0) json.append(',');
            Change e = events.get(i);
            json.append("{\"tick\":").append(e.tick()).append(",\"raster\":").append(e.raster())
                    .append(",\"cycle\":").append(e.cycle()).append(",\"phase\":\"").append(e.phase())
                    .append("\",\"field\":").append(e.field()).append(",\"previous\":").append(e.previous())
                    .append(",\"value\":").append(e.value()).append('}');
        }
        return json.append("]}").toString();
    }
}