// Commander X16 Emulator — sprite multiplexing trace

//

// VERA has 128 hardware sprite slots. A program that needs more rewrites the

// sprite attribute table part-way down the frame from a raster IRQ, so one slot

// shows a different sprite in each horizontal band of the screen. The static

// sprite viewer in the VERA panel reads the attribute table as it stands when

// you happen to look at it, which for a multiplexed frame is whatever the last

// band left behind -- the other 900-odd sprites the player saw are simply not

// in the data any more. This module records them.

//

// ─── What is recorded, and from where ──────────────────────────────────────

//

// Two streams, deliberately separate, because they answer different questions.

//

//   The renderer stream is ground truth. render_sprite_line() already walks all

//   128 slots for every scanline and already enforces VERA's per-line sprite

//   fetch budget, so it knows exactly which slot held which value when the beam

//   passed, which of those actually put pixels on screen, and which were cut

//   off when the budget ran out. Every "what did the frame contain" number here

//   comes from there, and none of it is reconstructed.

//

//   The mutation stream is the cause: the CPU's writes into $1FC00-$1FFFF, with

//   the cycle and scanline each landed on. That is what makes the CPU cost of

//   the multiplexing measurable, and what makes a write that missed its own

//   raster window detectable.

//

// Crossing the two is where the useful diagnostics live: a slot value the CPU

// wrote but the beam never drew is a wasted write, and a slot value written

// after the beam had already passed its Y position is a late write -- the

// classic multiplexer bug, and invisible in any view that only reads the

// attribute table.

//

// ─── Generations ───────────────────────────────────────────────────────────

//

// A "generation" is one value a slot held for one span of the frame. A sprite

// that never moves is one generation covering the whole frame; a slot recycled

// eight times is eight. Generations are opened lazily, when the renderer next

// reads a slot the CPU has dirtied, rather than on the write itself. That is

// what makes a partial update honest: a multiplexer storing bytes 2..5 across a

// scanline boundary leaves the renderer looking at a half-updated sprite for

// one line, and recording at read time captures the half-updated value that was

// really displayed instead of a coherent one that never existed.

//

// Per-generation totals are derived in sprite_trace_frame_end() by scanning the

// residency map, not accumulated as the frame runs. render_line() can be called

// more than once for the same scanline (a mid-line register split re-renders

// the line, and the last call wins), so running totals would count those lines

// twice; a single pass over the finished map cannot.

#ifndef SPRITE_TRACE_H

#define SPRITE_TRACE_H

#include <stdbool.h>

#include <stddef.h>

#include <stdint.h>

#ifdef __cplusplus

extern "C" {

#endif

#define SPRITE_TRACE_SLOTS 128

#define SPRITE_TRACE_LINES 480

// Clocks the sprite renderer gets per scanline, matching render_time_done in

// sprite_renderer.v:43 and SPRITE_RENDER_TIME in video.c. Kept here so the

// panel can draw the ceiling without reaching into video.c.

//

// It is WALL CLOCK, not bus accesses: render_time_r increments every clock

// (sprite_renderer.v:46-56), including the STATE_RENDER clocks when the

// renderer is painting the line buffer and holding no bus strobe at all. So

// this is the outer envelope a line's sprite work must finish inside, not a

// share of VRAM bandwidth -- see src/vera_bandwidth.h, which charges the same

// 800-clock line window that this 798 is measured against.

#define SPRITE_TRACE_LINE_BUDGET 798

// Marks a generation that was already in the attribute table when the frame

// started, rather than written during it.

#define SPRITE_TRACE_NO_LINE 0xFFFFu

// Per (line, slot) residency flags.

enum {

	SPRITE_TRACE_EVALUATED = 1u << 0, // the renderer reached this slot on this line

	SPRITE_TRACE_ONSCREEN  = 1u << 1, // enabled (z != 0) and the line fell inside its Y span

	SPRITE_TRACE_DREW      = 1u << 2, // put at least one non-transparent pixel on the line

	SPRITE_TRACE_CUT       = 1u << 3, // the line's budget ran out part-way through this sprite

};

// Per-generation flags.

enum {

	SPRITE_GEN_CARRIED = 1u << 0, // held over from before the frame, never written during it

	SPRITE_GEN_DREW    = 1u << 1, // drew on at least one line

	SPRITE_GEN_CUT     = 1u << 2, // was cut short by the budget on at least one line

	SPRITE_GEN_LATE    = 1u << 3, // written after the beam had passed its own Y span

};

// One value one slot held for one span of the frame.

typedef struct {

	uint8_t  attr[8];        // the attribute bytes as the renderer first read them

	uint8_t  slot;           // 0..127

	uint8_t  flags;          // SPRITE_GEN_*

	uint16_t index_in_slot;  // 0 for the slot's first value this frame, then 1, 2, ...

	uint16_t write_line;     // scanline the CPU dirtied it on, or SPRITE_TRACE_NO_LINE

	uint32_t write_cycle;    // clockticks6502 at that write

	// Attribute bytes whose value actually changed to produce this generation.

	// Not the number of stores the CPU made: a handler that rewrites all eight

	// bytes when only three differ shows 3 here and 8 in summary.mutations. The

	// gap between those two is redundant work the guest paid for.

	uint16_t writes;

	uint16_t first_line;     // first scanline it drew on (SPRITE_TRACE_NO_LINE if never)

	uint16_t last_line;      // last scanline it drew on

	uint16_t lines_resident; // scanlines it was the slot's value, drawn or not

	uint16_t lines_drawn;    // scanlines it actually put pixels on

	uint32_t budget_cycles;  // VERA sprite-fetch cycles it consumed over the frame

	// Decoded once at open, so consumers do not each re-derive it.

	int16_t  x, y;

	uint16_t width, height;

	uint32_t address;

	uint8_t  zdepth, palette_offset, color_mode, collision_mask;

	bool     hflip, vflip;

} sprite_gen_t;

// One CPU write into the sprite attribute table.

typedef struct {

	uint32_t cycle;   // clockticks6502 when it landed

	uint16_t line;    // display scanline the beam was on, or SPRITE_TRACE_NO_LINE off-screen

	uint8_t  slot;

	uint8_t  offset;  // 0..7, byte within the sprite's attributes

	uint8_t  old_val;

	uint8_t  new_val;

} sprite_mutation_t;

// What one scanline's sprite rendering cost and whether it fit.

typedef struct {

	uint16_t budget_used;   // clocks actually used, never above the ceiling

	uint32_t demand;        // clocks the line wanted, which may exceed it

	uint16_t evaluated;     // slots the renderer got to before time ran out

	uint16_t drawn;         // slots that put pixels on this line

	uint16_t dropped;       // slots on this line that time ran out before drawing

	uint16_t cut_slot;      // first slot time ran out in, or SPRITE_TRACE_NO_LINE

	uint32_t cpu_cycles;    // CPU cycles the guest spent while the beam was on this line

	bool     exhausted;     // the line ran out of time, so later slots were dropped

	bool     rendered;      // render_sprite_line() ran for this line at all

} sprite_line_stat_t;

// Frame-level totals, all derived in sprite_trace_frame_end().

typedef struct {

	uint32_t frame;              // frame_count this describes

	uint32_t cpu_cycles;         // CPU cycles spanned by the frame

	uint16_t gen_count;          // generations recorded (>= number of slots used)

	uint16_t effective_sprites;  // generations that actually drew: the real answer to

	                             // "how many sprites did the player see this frame"

	uint16_t phantom_writes;     // generations written during the frame that never drew

	uint16_t late_writes;        // generations written after their own Y span had passed

	uint16_t slots_used;         // slots that drew at least once

	uint16_t slots_multiplexed;  // slots that held more than one drawn value

	uint16_t max_gens_in_slot;   // deepest multiplexing on any one slot

	uint32_t mutations;          // attribute-byte writes seen

	uint32_t mutations_onscreen; // ...of which landed while the beam was in the display

	uint32_t mutation_bursts;    // runs of writes separated by <= burst_gap cycles

	uint32_t mutation_cycles;    // CPU cycles spanned by those runs

	uint32_t burst_gap;          // the gap threshold those two were computed with

	uint16_t lines_exhausted;    // scanlines that ran out of sprite render time

	uint32_t sprites_dropped;    // slot/line pairs that time ran out before drawing

	uint32_t budget_used_total;  // summed sprite render clocks over the frame

	uint16_t peak_line;          // scanline that wanted the most render time

	uint16_t peak_budget;        // that line's clocks actually used

	uint32_t peak_demand;        // that line's clocks wanted, ceiling or not

	bool     multiplexing;       // any slot held more than one drawn value

} sprite_frame_summary_t;

// A complete recording of one frame. Returned by sprite_trace_last_frame() and

// stable until the next frame is finished.

typedef struct {

	sprite_frame_summary_t summary;

	const sprite_gen_t    *gens;

	uint16_t               gen_count;

	const sprite_mutation_t *mutations;

	uint32_t                 mutation_count;

	uint32_t                 mutations_dropped; // lost to the ring buffer's capacity

	const sprite_line_stat_t *lines;            // [SPRITE_TRACE_LINES]

	// Residency map. line_gen[line * SPRITE_TRACE_SLOTS + slot] indexes gens[],

	// or is SPRITE_TRACE_NO_GEN when the renderer never reached that slot.

	const uint16_t *line_gen;

	const uint8_t  *line_flags;   // SPRITE_TRACE_* per (line, slot)

	const uint16_t *line_budget;  // per (line, slot) sprite-fetch cycles

} sprite_trace_frame_t;

#define SPRITE_TRACE_NO_GEN 0xFFFFu

// Set by sprite_trace_set_enabled(). Exposed directly so the renderer's inner

// loop can branch on a load instead of a call: render_sprite_line() consults it

// 128 times per scanline, 480 scanlines per frame.

extern bool sprite_trace_active;

// Turning tracing on allocates the maps (about 300 KB per buffer, two buffers);

// turning it off frees them. A build that never opens the panel therefore pays

// nothing. Returns false if the allocation failed, leaving tracing off.

bool sprite_trace_set_enabled(bool on);

void sprite_trace_reset(void);

// Bytes currently held by the trace, for the panel to report.

size_t sprite_trace_memory_usage(void);

// The gap, in CPU cycles, below which two consecutive attribute writes are

// treated as part of the same burst. Changing it re-derives mutation_bursts and

// mutation_cycles on the next frame.

void     sprite_trace_set_burst_gap(uint32_t cycles);

uint32_t sprite_trace_get_burst_gap(void);

// ─── Recording hooks, called from video.c ──────────────────────────────────

// Finish the frame in progress and start a new one. attrs is the live attribute

// table, used to seed each slot's carried-over generation.

void sprite_trace_frame_advance(uint32_t frame, uint32_t cpu_cycle,

                                const uint8_t attrs[SPRITE_TRACE_SLOTS][8]);

// A CPU write into the attribute table. Call after the byte has been stored.

void sprite_trace_note_write(uint8_t slot, uint8_t offset, uint8_t old_val,

                             uint8_t new_val, uint16_t line, uint32_t cpu_cycle);

// render_sprite_line() is starting on this line. Clears the line, so that a

// line rendered more than once records only its final pass -- matching the

// display, where the last pass is what remains on screen.

void sprite_trace_line_begin(uint16_t line, uint32_t cpu_cycle);

// The renderer read this slot on this line. attr is the live attribute table

// row, budget_used is what this sprite consumed, flags is SPRITE_TRACE_*.

void sprite_trace_note_slot(uint16_t line, uint8_t slot, const uint8_t attr[8],

                            uint16_t budget_used, uint8_t flags);

// render_sprite_line() has finished this line. `result` carries the whole line

// tally; the caller fills in what it measured and leaves cpu_cycles and

// rendered to the trace.

void sprite_trace_line_end(uint16_t line, const sprite_line_stat_t *result);

// ─── Reading ───────────────────────────────────────────────────────────────

// The most recently completed frame, or NULL if none has finished since tracing

// was enabled. Stable until the next frame boundary.

const sprite_trace_frame_t *sprite_trace_last_frame(void);

#ifdef __cplusplus

}

#endif

#endif // SPRITE_TRACE_H