VICExplorer.java
package ui.vic;
import javafx.animation.AnimationTimer;
import javafx.application.Platform;
import javafx.collections.FXCollections;
import javafx.fxml.FXML;
import javafx.geometry.Insets;
import javafx.scene.canvas.Canvas;
import javafx.scene.control.*;
import javafx.scene.image.PixelFormat;
import javafx.scene.image.WritableImage;
import javafx.scene.layout.*;
import javafx.stage.FileChooser;
import javafx.util.StringConverter;
import libsidutils.debug.*;
import libsidutils.debug.InspectionService.Breakpoint;
import libsidutils.debug.InspectionService.BreakpointType;
import sidplay.Player;
import sidplay.player.State;
import ui.common.C64VBox;
import ui.common.C64Window;
import java.beans.PropertyChangeListener;
import java.io.File;
import java.nio.file.Files;
import java.util.IdentityHashMap;
import java.util.Map;
import java.util.concurrent.atomic.AtomicReference;
import java.util.function.Consumer;
/**
* UI consumes detached packets; it never reads live chip fields or runs emulation.
*/
public final class VICExplorer extends C64VBox {
public static final String ID = "VICEXPLORER";
@FXML
private VBox content;
private AtomicReference<InspectionSnapshot> pending;
private AtomicReference<InspectionTimeline> pendingTimeline;
private RasterTimelineView timelineView;
private Map<Canvas, WritableImage> images;
private Canvas rendered, spriteOverlay, screen, characters, zoom;
private Canvas[] sprites;
private Label[] spriteLabels;
private VBox[] spriteBoxes;
private Label metadata, status, error, spriteInfo, characterInfo, registers, addresses, renderedInfo, renderedPosition;
private CheckBox live, oneShot, spritePositions;
private ComboBox<BreakpointType> condition;
private TextField target, value, mask;
private Button resume, save, freeze, arm;
private AnimationTimer timer;
private volatile InspectionService.Subscription subscription;
private volatile InspectionService.VideoSubscription videoSubscription;
private InspectionSnapshot shown;
private PropertyChangeListener stateListener, statusListener;
private volatile boolean inspectorVisible, collectionRequested, videoRequested, closed;
private volatile boolean timelineRequested;
private int selectedSprite, selectedCharacter;
public VICExplorer() {
super();
}
public VICExplorer(C64Window window, Player player) {
super(window, player);
}
private String text(String key) {
return util.getBundle().getString(key);
}
@Override
protected void initialize() {
// C64VBox loads FXML from its constructor, before subclass field initializers would run.
pending = new AtomicReference<>();
pendingTimeline = new AtomicReference<>();
images = new IdentityHashMap<>();
rendered = new Canvas(384, 272);
rendered.setId("renderedVIC");
spriteOverlay = new Canvas(384, 272);
spriteOverlay.setId("spritePositions");
screen = new Canvas(384, 240);
characters = new Canvas(256, 256);
zoom = new Canvas(96, 84);
sprites = new Canvas[8];
spriteLabels = new Label[8];
spriteBoxes = new VBox[8];
metadata = new Label();
status = new Label();
error = new Label();
spriteInfo = new Label();
characterInfo = new Label();
registers = new Label();
addresses = new Label();
renderedInfo = new Label(text("VIDEO_DEMAND"));
renderedInfo.setWrapText(true);
renderedPosition = new Label();
renderedPosition.setMouseTransparent(true);
renderedPosition.setStyle("-fx-font-family: monospace; -fx-font-size: 11px; -fx-text-fill: white; -fx-background-color: #101820dd; -fx-padding: 3 6;");
StackPane renderedPicture = new StackPane(rendered, spriteOverlay, renderedPosition);
renderedPicture.setMaxWidth(384);
StackPane.setAlignment(renderedPosition, javafx.geometry.Pos.TOP_LEFT);
live = new CheckBox();
oneShot = new CheckBox();
spritePositions = new CheckBox(text("SPRITE_POSITIONS"));
spritePositions.setSelected(true);
spritePositions.selectedProperty().addListener((observable, previous, selected) -> {
if (shown != null) render(shown);
});
condition = new ComboBox<>();
target = new TextField("147");
value = new TextField("32");
mask = new TextField("$FF");
resume = new Button();
save = new Button();
freeze = new Button();
arm = new Button();
selectedCharacter = 60;
live.setText(text("LIVE"));
live.setId("liveInspection");
live.setSelected(false);
live.selectedProperty().addListener((observable, oldValue, newValue) -> updateSubscription());
Button snapshot = button("SNAPSHOT", () -> {
live.setSelected(false);
inspect(service -> offer(service.snapshot(InspectionService.ALL)));
});
freeze.setText(text("FREEZE"));
freeze.setOnAction(event -> inspect(service -> offer(service.freeze(InspectionService.ALL))));
resume.setText(text("RESUME"));
resume.setOnAction(event -> util.getPlayer().pauseContinue());
save.setText(text("SAVE"));
save.setDisable(true);
save.setOnAction(event -> save());
FlowPane controls = flow(live, snapshot, freeze, resume, save, status);
metadata.setWrapText(true);
metadata.setStyle("-fx-font-family: monospace;");
error.setWrapText(true);
error.setStyle("-fx-text-fill: #b34758;");
content.getChildren().addAll(controls, help("DEMAND_HELP"), metadata, error);
VBox memory = new VBox(10, screen, addresses, help("MEMORY_HELP"));
addresses.setWrapText(true);
addresses.setStyle("-fx-font-family: monospace;");
TilePane spriteGrid = new TilePane(8, 8);
spriteGrid.setPrefColumns(4);
for (int index = 0; index < 8; index++) {
final int selected = index;
sprites[index] = new Canvas(48, 42);
spriteLabels[index] = new Label("#" + index);
spriteBoxes[index] = new VBox(4, spriteLabels[index], sprites[index]);
spriteBoxes[index].setPadding(new Insets(6));
spriteBoxes[index].setOnMouseClicked(event -> {
selectedSprite = selected;
if (shown != null) render(shown);
});
spriteGrid.getChildren().add(spriteBoxes[index]);
}
spriteInfo.setWrapText(true);
spriteInfo.setStyle("-fx-font-family: monospace;");
VBox spritePanel = new VBox(12, spriteGrid, new HBox(12, zoom, spriteInfo));
registers.setStyle("-fx-font-family: monospace;");
registers.setWrapText(true);
spriteOverlay.setOnMouseClicked(event -> {
if (shown == null || !spritePositions.isSelected()) return;
for (var box : InspectionImage.spriteBounds(shown)) {
if (event.getX() >= box.x() && event.getX() < box.x() + box.width()
&& event.getY() >= box.y() && event.getY() < box.y() + box.height()) {
selectedSprite = box.index();
render(shown);
break;
}
}
});
VBox renderedContent = new VBox(10, spritePositions, renderedPicture, renderedInfo, help("VIDEO_HELP"), help("SPRITE_POSITIONS_HELP"));
renderedContent.setPadding(new Insets(8));
memory.setPadding(new Insets(8));
Tab renderedTab = new Tab(text("RENDERED"), renderedContent);
Tab memoryTab = new Tab(text("SCREEN_MEMORY"), memory);
TabPane pictures = new TabPane(memoryTab, renderedTab);
pictures.setId("inspectionPictures");
pictures.setTabClosingPolicy(TabPane.TabClosingPolicy.UNAVAILABLE);
pictures.setPrefHeight(410);
pictures.getSelectionModel().selectedIndexProperty().addListener((observable, previous, selected) ->
pictures.setPrefHeight(selected.intValue() == 0 ? 410 : 520));
rendered.setVisible(false);
rendered.setManaged(false);
spriteOverlay.setVisible(false);
spriteOverlay.setManaged(false);
renderedPosition.setVisible(false);
renderedPosition.setManaged(false);
TitledPane memoryPane = panel("PICTURE", pictures);
memoryPane.setPrefWidth(420);
TitledPane spritesPane = panel("SPRITES", spritePanel);
spritesPane.setPrefWidth(380);
TitledPane statePane = panel("STATE", new VBox(10, registers, help("STORED_REGISTERS")));
statePane.setPrefWidth(300);
FlowPane top = flow(memoryPane, spritesPane, statePane);
top.setRowValignment(javafx.geometry.VPos.TOP);
top.setPrefWrapLength(1100);
content.getChildren().add(top);
characters.setOnMouseClicked(event -> {
selectedCharacter = Math.min(15, (int) event.getY() / 16) * 16 + Math.min(15, (int) event.getX() / 16);
if (shown != null) render(shown);
});
characterInfo.setWrapText(true);
VBox characterPanel = new VBox(10, characters, characterInfo, help("GLYPH_HELP"));
condition.setItems(FXCollections.observableArrayList(BreakpointType.values()));
condition.setConverter(new StringConverter<>() {
@Override
public String toString(BreakpointType type) {
return type == null ? "" : text("RULE_" + type.name());
}
@Override
public BreakpointType fromString(String value) {
throw new UnsupportedOperationException();
}
});
condition.setValue(BreakpointType.RASTER);
condition.valueProperty().addListener((observable, oldValue, type) -> {
boolean raster = type == BreakpointType.RASTER, register = type == BreakpointType.VIC_REGISTER;
target.setDisable(!raster && !register);
value.setDisable(!raster && !register);
mask.setDisable(raster || type == BreakpointType.VIC_BANK || type == BreakpointType.DISPLAY_MODE);
target.setText(register ? "$20" : "147");
value.setText(register ? "$07" : "32");
mask.setText(register ? "$0F" : "$FF");
});
target.setPrefColumnCount(5);
value.setPrefColumnCount(5);
mask.setPrefColumnCount(5);
mask.setDisable(true);
oneShot.setText(text("ONE_SHOT"));
oneShot.setSelected(true);
arm.setText(text("ARM"));
arm.setOnAction(event -> arm());
Button disarm = button("DISARM", () -> inspect(service -> {
service.disarm();
offerCurrent(service);
}));
VBox rules = new VBox(12, flow(new Label(text("CONDITION")), condition),
flow(new Label(text("TARGET")), target, new Label(text("VALUE")), value, new Label(text("MASK")), mask),
flow(oneShot, arm, disarm), help("BREAKPOINT_HELP"), help("CYCLE_HELP"), help("UNKNOWN_HELP"));
TitledPane rulePanel = panel("BREAKPOINTS", rules);
rulePanel.setPrefWidth(590);
TitledPane characterPane = panel("CHARACTERS", characterPanel);
characterPane.setPrefWidth(320);
FlowPane bottom = flow(characterPane, rulePanel);
bottom.setRowValignment(javafx.geometry.VPos.TOP);
content.getChildren().add(bottom);
timelineView = new RasterTimelineView(util.getBundle(), action -> inspect(service -> {
switch (action) {
case "RECORD_TIMELINE" -> {
if (closed) return;
timelineRequested = true;
service.recordTimeline(this::offerTimeline);
}
case "CANCEL_TIMELINE" -> service.cancelTimeline();
case "CLEAR_TIMELINE" -> {
service.clearTimeline();
timelineRequested = false;
pendingTimeline.set(null);
Platform.runLater(() -> timelineView.setTimeline(null));
}
default -> throw new IllegalArgumentException("Unknown timeline action");
}
}), sprite -> {
selectedSprite = sprite;
if (shown != null) render(shown);
});
TitledPane timelinePane = panel("TIMELINE", timelineView);
content.getChildren().add(timelinePane);
timer = new AnimationTimer() {
@Override
public void handle(long now) {
InspectionSnapshot packet = pending.getAndSet(null);
if (packet != null) render(packet);
InspectionTimeline timeline = pendingTimeline.getAndSet(null);
if (timeline != null) timelineView.setTimeline(timeline);
}
};
stateListener = event -> Platform.runLater(() -> {
updateButtons((State) event.getNewValue());
if (event.getNewValue() == State.START) {
timelineRequested = false;
pending.set(null);
pendingTimeline.set(null);
timelineView.setTimeline(null);
shown = null;
save.setDisable(true);
metadata.setText(text("WAITING"));
updateSubscription();
}
});
statusListener = event -> Platform.runLater(() -> status.setText(text("STATUS_" + event.getNewValue())));
util.getPlayer().stateProperty().addListener(stateListener);
util.getPlayer().inspectionStatusProperty().addListener(statusListener);
updateButtons(util.getPlayer().stateProperty().get());
status.setText(text("STATUS_" + util.getPlayer().inspectionStatusProperty().get()));
metadata.setText(text("WAITING"));
}
private Button button(String key, Runnable action) {
Button button = new Button(text(key));
button.setOnAction(event -> action.run());
return button;
}
private Label help(String key) {
Label label = new Label(text(key));
label.setWrapText(true);
label.setMaxWidth(560);
label.setStyle("-fx-font-size: 11px;");
return label;
}
private static FlowPane flow(javafx.scene.Node... nodes) {
return new FlowPane(10, 10, nodes);
}
private TitledPane panel(String key, javafx.scene.Node node) {
TitledPane panel = new TitledPane(text(key), node);
panel.setCollapsible(false);
return panel;
}
private void updateButtons(State state) {
boolean running = state == State.PLAY || state == State.PAUSE;
freeze.setDisable(!running || state == State.PAUSE);
resume.setDisable(state != State.PAUSE);
arm.setDisable(!running);
if (timelineView != null) timelineView.setPlayback(running, state == State.PAUSE);
}
public void setInspectorVisible(boolean visible) {
inspectorVisible = visible;
if (visible) timer.start();
else timer.stop();
updateSubscription();
}
private void updateSubscription() {
boolean viewed = inspectorVisible && !closed;
boolean requested = viewed && live.isSelected();
if (!viewed && !collectionRequested && !videoRequested && subscription == null && videoSubscription == null)
return;
collectionRequested = requested;
videoRequested = viewed;
inspect(service -> {
if (videoRequested && videoSubscription == null) videoSubscription = service.watchVideo();
else if (!videoRequested && videoSubscription != null) {
videoSubscription.close();
videoSubscription = null;
}
if (subscription != null) subscription.close();
// A queued request may reach the player after the view was hidden or closed.
subscription = collectionRequested ? service.subscribe(InspectionService.ALL, this::offer) : null;
if (inspectorVisible && service.isPaused() && service.latest() != null) offer(service.latest());
if (inspectorVisible && service.timeline() != null) offerTimeline(service.timeline());
});
}
private void inspect(Consumer<InspectionService> action) {
error.setText("");
util.getPlayer().inspect(service -> {
try {
action.accept(service);
} catch (RuntimeException failure) {
Platform.runLater(() -> error.setText(failure.getMessage()));
}
});
}
private void offer(InspectionSnapshot snapshot) {
pending.set(snapshot);
}
private void offerTimeline(InspectionTimeline timeline) {
timelineRequested = timeline.recording();
if (!closed) pendingTimeline.set(timeline);
}
private void offerCurrent(InspectionService service) {
offer(service.isPaused() && service.latest() != null ? service.latest()
: service.snapshot(InspectionService.ALL & ~InspectionService.VIDEO));
}
private void arm() {
try {
BreakpointType type = condition.getValue();
boolean hasTarget = type == BreakpointType.RASTER || type == BreakpointType.VIC_REGISTER;
boolean hasMask = type != BreakpointType.RASTER && type != BreakpointType.VIC_BANK && type != BreakpointType.DISPLAY_MODE;
Breakpoint rule = new Breakpoint(type, hasTarget ? number(target.getText()) : 0,
hasTarget ? number(value.getText()) : 0, hasMask ? number(mask.getText()) : 0, oneShot.isSelected());
inspect(service -> {
service.arm(rule);
offerCurrent(service);
});
} catch (RuntimeException failure) {
error.setText(text("INVALID_NUMBER"));
}
}
private static int number(String text) {
String value = text.trim();
if (!value.matches("(?i)(\\$[0-9a-f]+|0x[0-9a-f]+|[0-9]+)")) throw new NumberFormatException();
return value.startsWith("$") ? Integer.parseInt(value.substring(1), 16)
: value.startsWith("0x") || value.startsWith("0X") ? Integer.parseInt(value.substring(2), 16) : Integer.parseInt(value);
}
private static String hex(int value, int digits) {
return value < 0 ? "?" : "$" + String.format("%0" + digits + "X", value);
}
private void render(InspectionSnapshot snapshot) {
timelineView.setSelectedSprite(selectedSprite);
shown = snapshot;
save.setDisable(false);
String reason = snapshot.reason().equals("BREAKPOINT") ? text("HIT") + " #" + snapshot.breakpointId()
+ " · " + text("RULE_" + snapshot.breakpointType()) : snapshot.paused() ? text("FROZEN") : text("CURRENT");
metadata.setText(reason + "\n" + snapshot.model() + " · " + snapshot.chip() + " · " + snapshot.clock()
+ " · " + text("FRAME") + " " + snapshot.frame() + " · " + text("RASTER") + " " + snapshot.vic().raster()
+ " · " + text("CYCLE") + " " + snapshot.vic().cycle() + " · " + snapshot.phase() + " · t=" + snapshot.time()
+ " · " + text("STATUS_ARMED") + ": " + snapshot.armed());
InspectionFrame frame = snapshot.video();
rendered.setVisible(frame != null);
rendered.setManaged(frame != null);
spriteOverlay.setVisible(frame != null && spritePositions.isSelected());
spriteOverlay.setManaged(frame != null);
renderedPosition.setVisible(frame != null);
renderedPosition.setManaged(frame != null);
if (frame != null) {
renderedPosition.setText(text("RASTER") + " " + snapshot.vic().raster() + " · " + text("CYCLE")
+ " " + snapshot.vic().cycle() + " · " + snapshot.phase());
rendered.setWidth(frame.width());
rendered.setHeight(frame.height());
paint(rendered, InspectionImage.video(frame), frame.width(), frame.height());
spriteOverlay.setWidth(frame.width());
spriteOverlay.setHeight(frame.height());
var guides = spriteOverlay.getGraphicsContext2D();
guides.clearRect(0, 0, frame.width(), frame.height());
if (spritePositions.isSelected()) for (var box : InspectionImage.spriteBounds(snapshot)) {
var color = javafx.scene.paint.Color.web(box.index() == selectedSprite ? "#f4b37f" : "#75cec8");
guides.setStroke(color);
guides.setLineWidth(box.index() == selectedSprite ? 2 : 1);
guides.strokeRect(box.x() + 0.5, box.y() + 0.5, box.width() - 1, box.height() - 1);
guides.setFill(javafx.scene.paint.Color.web("#101820"));
guides.fillRect(Math.max(0, box.x()), Math.max(0, box.y()), 19, 12);
guides.setFill(color);
guides.setFont(javafx.scene.text.Font.font("Monospaced", javafx.scene.text.FontWeight.BOLD, 9));
guides.fillText("#" + box.index(), Math.max(0, box.x()) + 2, Math.max(0, box.y()) + 9);
}
renderedInfo.setText(text("VIDEO_" + frame.status()) + " · " + frame.pixels().length + " / "
+ frame.width() * frame.height() + " " + text("PIXELS"));
} else {
renderedInfo.setText(text("VIDEO_DEMAND"));
}
paint(screen, InspectionImage.screen(snapshot), 320, 200);
paint(characters, InspectionImage.characters(snapshot), 128, 128);
characters.getGraphicsContext2D().setStroke(javafx.scene.paint.Color.ORANGE);
characters.getGraphicsContext2D().strokeRect(selectedCharacter % 16 * 16, selectedCharacter / 16 * 16, 16, 16);
characterInfo.setText(text("CHARACTER") + " " + hex(selectedCharacter, 2) + " · "
+ hex(snapshot.bank() + snapshot.vic().characterAddress() + selectedCharacter * 8, 4));
for (int sprite = 0; sprite < 8; sprite++) {
paint(sprites[sprite], InspectionImage.sprite(snapshot, sprite), 24, 21);
int pointer = snapshot.pointers().length == 8 ? snapshot.pointers()[sprite] : -1;
spriteLabels[sprite].setText("#" + sprite + " " + hex(pointer < 0 ? -1 : snapshot.bank() + pointer * 64, 4));
spriteBoxes[sprite].setStyle("-fx-border-color: " + (sprite == selectedSprite ? "#d39963;" : "#71808c;"));
}
paint(zoom, InspectionImage.sprite(snapshot, selectedSprite), 24, 21);
byte[] r = snapshot.vic().registers();
int bit = 1 << selectedSprite;
int x = (r[selectedSprite * 2] & 255) + ((r[0x10] & bit) != 0 ? 256 : 0);
spriteInfo.setText(text("SPRITE") + " #" + selectedSprite + "\nX " + x + " / Y " + (r[selectedSprite * 2 + 1] & 255)
+ "\n" + text("MULTICOLOR") + " " + ((r[0x1c] & bit) != 0)
+ "\nDMA " + ((snapshot.vic().dmaMask() & bit) != 0));
StringBuilder values = new StringBuilder();
for (int register : new int[]{0x11, 0x16, 0x18, 0x15, 0x17, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f}) {
values.append(hex(0xd000 + register, 4)).append(" ").append(hex(r[register] & 255, 2)).append('\n');
}
values.append("BA ").append(snapshot.bus() & 1).append(" / AEC ").append(snapshot.bus() >> 1 & 1)
.append('\n').append(text("BADLINE")).append(' ').append(snapshot.vic().badLine())
.append("\nVC ").append(hex(snapshot.vic().videoCounter(), 3)).append(" / RC ").append(snapshot.vic().rowCounter());
registers.setText(values.toString());
addresses.setText(text("BANK") + " " + snapshot.bank() / 16384 + " " + hex(snapshot.bank(), 4)
+ "\n" + text("SCREEN") + " " + hex(snapshot.bank() + snapshot.vic().screenAddress(), 4)
+ "\n" + text("CHARACTERS") + " " + hex(snapshot.bank() + snapshot.vic().characterAddress(), 4));
}
private void paint(Canvas canvas, int[] pixels, int width, int height) {
WritableImage image = images.get(canvas);
if (image == null || image.getWidth() != width || image.getHeight() != height) {
image = new WritableImage(width, height);
images.put(canvas, image);
}
image.getPixelWriter().setPixels(0, 0, width, height, PixelFormat.getIntArgbInstance(), pixels, 0, width);
var graphics = canvas.getGraphicsContext2D();
graphics.setImageSmoothing(false);
graphics.clearRect(0, 0, canvas.getWidth(), canvas.getHeight());
graphics.drawImage(image, 0, 0, canvas.getWidth(), canvas.getHeight());
}
private void save() {
if (shown == null) return;
FileChooser chooser = new FileChooser();
chooser.setTitle(text("SAVE"));
chooser.setInitialFileName("vic-" + shown.chip() + "-f" + shown.frame() + "-r" + shown.vic().raster()
+ "-c" + shown.vic().cycle() + "-" + shown.phase() + ".json");
chooser.getExtensionFilters().add(new FileChooser.ExtensionFilter("JSON", "*.json"));
File file = chooser.showSaveDialog(getScene().getWindow());
if (file != null) {
try {
Files.writeString(file.toPath(), shown.toJson());
} catch (Exception failure) {
error.setText(failure.getMessage());
}
}
}
@Override
public void doClose() {
closed = true;
if (timelineRequested) inspect(InspectionService::cancelTimeline);
setInspectorVisible(false);
util.getPlayer().stateProperty().removeListener(stateListener);
util.getPlayer().inspectionStatusProperty().removeListener(statusListener);
pending.set(null);
pendingTimeline.set(null);
}
}