InspectionSnapshot.java

package libsidutils.debug;

import libsidplay.components.mos656x.VICInspection.State;

/**
 * Detached, read-only-by-contract inspection packet. Missing memory channels are empty arrays; video is null unless
 * captured explicitly. Unavailable mapped bytes are -1. Memory describes the capture instant, not earlier fetches.
 * Version 1 is additive:
 * consumers ignore unknown fields and inspect the channels mask before reading optional data.
 */
public record InspectionSnapshot(int version, int generation, long time, long frame, String phase,
                                 String model, String chip, String clock, int cyclesPerLine, int rasterLines,
                                 int channels, boolean paused, int armed, String reason, int breakpointId,
                                 String breakpointType, int target, int value, int mask, int previousValue,
                                 int observedValue, int bank, int bus,
                                 State vic, int[] pointers, int[] sprites, int[] characters, int[] screen,
                                 int[] colors, int[] bitmap, InspectionFrame video) {
    /**
     * Preserve the original hit and data when a host merely changes subscriptions or armed rules while paused.
     */
    public InspectionSnapshot withArmed(int armed) {
        return new InspectionSnapshot(version, generation, time, frame, phase, model, chip, clock, cyclesPerLine,
                rasterLines, channels, paused, armed, reason, breakpointId, breakpointType, target, value, mask,
                previousValue, observedValue, bank, bus, vic, pointers, sprites, characters, screen, colors, bitmap, video);
    }

    public String toJson() {
        StringBuilder json = new StringBuilder(1024 + (sprites.length + characters.length + screen.length
                + colors.length + bitmap.length) * 4);
        json.append('{');
        number(json, "version", version);
        number(json, "generation", generation);
        number(json, "time", time);
        number(json, "frame", frame);
        string(json, "phase", phase);
        string(json, "model", model);
        string(json, "chip", chip);
        string(json, "clock", clock);
        number(json, "cyclesPerLine", cyclesPerLine);
        number(json, "rasterLines", rasterLines);
        number(json, "channels", channels);
        json.append("\"paused\":").append(paused).append(',');
        number(json, "armed", armed);
        string(json, "reason", reason);
        number(json, "breakpointId", breakpointId);
        string(json, "breakpointType", breakpointType);
        number(json, "target", target);
        number(json, "value", value);
        number(json, "mask", mask);
        number(json, "previousValue", previousValue);
        number(json, "observedValue", observedValue);
        number(json, "bank", bank);
        number(json, "bus", bus);
        number(json, "raster", vic.raster());
        number(json, "cycle", vic.cycle());
        number(json, "videoCounter", vic.videoCounter());
        number(json, "videoCounterBase", vic.videoCounterBase());
        number(json, "rowCounter", vic.rowCounter());
        number(json, "screenAddress", bank + vic.screenAddress());
        number(json, "characterAddress", bank + vic.characterAddress());
        number(json, "bitmapAddress", bank + vic.bitmapAddress());
        number(json, "dmaMask", vic.dmaMask());
        json.append("\"badLine\":").append(vic.badLine()).append(',');
        json.append("\"displayActive\":").append(vic.displayActive()).append(',');
        json.append("\"verticalBorder\":").append(vic.verticalBorder()).append(',');
        json.append("\"registers\":[");
        for (int i = 0; i < vic.registers().length; i++) {
            if (i != 0) json.append(',');
            json.append(vic.registers()[i] & 255);
        }
        json.append("],");
        array(json, "pointers", pointers);
        array(json, "sprites", sprites);
        array(json, "characters", characters);
        array(json, "screen", screen);
        array(json, "colors", colors);
        array(json, "bitmap", bitmap);
        json.append("\"video\":").append(video == null ? "null" : video.toJson()).append(',');
        json.setLength(json.length() - 1);
        return json.append('}').toString();
    }

    private static void number(StringBuilder json, String name, long value) {
        json.append('"').append(name).append("\":").append(value).append(',');
    }

    private static void string(StringBuilder json, String name, String value) {
        // These fields are internal enum names and fixed reason codes, never guest or user text.
        json.append('"').append(name).append("\":\"").append(value).append("\",");
    }

    private static void array(StringBuilder json, String name, int[] values) {
        json.append('"').append(name).append("\":[");
        for (int i = 0; i < values.length; i++) {
            if (i != 0) json.append(',');
            json.append(values[i]);
        }
        json.append("],");
    }
}