// Sprite multiplexing, end to end through the real video.c.

//

// test_sprite_trace.c drives the recorder directly with synthetic scanlines.

// This one drives VERA: it writes sprite attributes into VRAM, steps the beam a

// cycle at a time, and rewrites a slot part-way down the frame the way a raster

// IRQ handler would. What it checks is that the trace's answer comes from what

// render_sprite_line() actually put on screen -- so a sprite whose bitmap is

// entirely transparent is *not* counted, even though its attributes are live

// and its Y span is on screen.

#include "support/video_fixture.h"

// SDL redefines main to SDL_main, which makes a plain int main(void) a C4026

// and, under /WX, fatal. Undoing the macro is what lets this test build on

// MSVC; several older test files in this tree still trip over it.

#ifdef main

#undef main

#endif

#include "support/harness.h"

#include "sprite_trace.h"

#include "video.h"

#include <stdint.h>

#include <string.h>

// video.c exports these; the test needs to know where the beam is.

extern uint16_t vga_scan_pos_y;

extern int      frame_count;

#define DC_VIDEO 0x09

#define ADDR_SPRDATA 0x1FC00u

#define SPRITE_GFX_OPAQUE 0x4000u

#define SPRITE_GFX_CLEAR 0x5000u

#define SPRITE_GFX_BIG 0x8000u

#define MHZ 8.0f

static void

step_one_cycle(void)

{

	video_step(MHZ, 1, false);

}

// Run until the beam reaches `target`, giving up rather than spinning forever

// if the video mode is not what the test thinks it is.

static bool

step_to_line(uint16_t target)

{

	for (long guard = 0; guard < 2000000; guard++) {

		if (vga_scan_pos_y == target) {

			return true;

		}

		step_one_cycle();

	}

	return false;

}

static bool

step_one_frame(void)

{

	const int start = frame_count;

	for (long guard = 0; guard < 2000000; guard++) {

		if (frame_count != start) {

			return true;

		}

		step_one_cycle();

	}

	return false;

}

// wcode/hcode are VERA's size codes: 0=8, 1=16, 2=32, 3=64 pixels.

static void

write_sprite_sized(int slot, uint32_t addr, int x, int y, int z, int wcode, int hcode, int mode)

{

	uint8_t a[8];

	memset(a, 0, sizeof(a));

	a[0] = (uint8_t)((addr >> 5) & 0xff);

	a[1] = (uint8_t)(((addr >> 13) & 0x0f) | (mode ? 0x80 : 0));

	a[2] = (uint8_t)(x & 0xff);

	a[3] = (uint8_t)((x >> 8) & 3);

	a[4] = (uint8_t)(y & 0xff);

	a[5] = (uint8_t)((y >> 8) & 3);

	a[6] = (uint8_t)((z & 3) << 2); // no flip

	a[7] = (uint8_t)(((hcode & 3) << 6) | ((wcode & 3) << 4));

	for (int b = 0; b < 8; b++) {

		video_space_write(ADDR_SPRDATA + (uint32_t)slot * 8 + b, a[b]);

	}

}

static void

write_sprite(int slot, uint32_t addr, int x, int y, int z)

{

	write_sprite_sized(slot, addr, x, y, z, 0, 0, 0); // 8x8, 4bpp

}

// An 8x8 4bpp sprite is eight rows of four bytes.

static void

fill_sprite_gfx(uint32_t addr, uint8_t value)

{

	for (uint32_t i = 0; i < 8 * 4; i++) {

		video_space_write(addr + i, value);

	}

}

static void

setup(void)

{

	video_reset();

	// VGA out, sprites enabled.

	video_write(DC_VIDEO, 0x41);

	fill_sprite_gfx(SPRITE_GFX_OPAQUE, 0x11); // both nibbles a visible colour

	fill_sprite_gfx(SPRITE_GFX_CLEAR, 0x00);  // wholly transparent

	for (uint32_t i = 0; i < 64 * 64; i++) {

		video_space_write(SPRITE_GFX_BIG + i, 0x22); // 64x64 8bpp, opaque

	}

	for (int slot = 0; slot < 128; slot++) {

		write_sprite(slot, SPRITE_GFX_OPAQUE, 0, 0, 0); // z=0: disabled

	}

}

// One slot, two sprites, a raster rewrite between them: the whole point of the

// exercise, measured through the real renderer.

static void

test_a_slot_rewritten_mid_frame_yields_two_effective_sprites(void)

{

	setup();

	check(sprite_trace_set_enabled(true), "tracing enables");

	write_sprite(0, SPRITE_GFX_OPAQUE, 100, 10, 1);

	// Let a frame boundary pass so the trace is recording a clean frame.

	check(step_one_frame(), "the beam reaches a frame boundary");

	// Now the frame under test: the sprite shows at y=10..17, then the handler

	// hands the slot to a second sprite that shows at y=200..207.

	check(step_to_line(50), "the beam reaches the split");

	write_sprite(0, SPRITE_GFX_OPAQUE, 140, 200, 1);

	check(step_one_frame(), "the frame under test completes");

	const sprite_trace_frame_t *f = sprite_trace_last_frame();

	check(f != NULL, "the frame is published");

	if (!f) {

		return;

	}

	check_eq(f->summary.effective_sprites, 2u, "one slot showed two sprites");

	check_eq(f->summary.slots_used, 1u, "using one hardware slot");

	check_eq(f->summary.slots_multiplexed, 1u, "the slot is reported as multiplexed");

	check(f->summary.multiplexing, "multiplexing is detected");

	check_eq(f->summary.phantom_writes, 0u, "neither value was wasted");

	check_eq(f->summary.late_writes, 0u, "neither write was late");

	// The residency map has to show the handover at the right place.

	const uint16_t at12  = f->line_gen[(size_t)12 * SPRITE_TRACE_SLOTS + 0];

	const uint16_t at202 = f->line_gen[(size_t)202 * SPRITE_TRACE_SLOTS + 0];

	check(at12 != at202, "the slot holds different values above and below the split");

	check(f->line_flags[(size_t)12 * SPRITE_TRACE_SLOTS + 0] & SPRITE_TRACE_DREW,

	      "the first sprite drew on its own lines");

	check(f->line_flags[(size_t)202 * SPRITE_TRACE_SLOTS + 0] & SPRITE_TRACE_DREW,

	      "the second sprite drew on its own lines");

	check(!(f->line_flags[(size_t)100 * SPRITE_TRACE_SLOTS + 0] & SPRITE_TRACE_DREW),

	      "and neither drew on a line between them");

	if (at202 < f->gen_count) {

		check_eq(f->gens[at202].y, 200u, "the second generation carries its own Y");

		check_eq(f->gens[at202].lines_drawn, 8u, "it drew on all eight of its rows");

	}

}

// The trace reports what reached the screen, not what the attribute table says

// should have. A fully transparent sprite is live, enabled and on screen, and

// still contributes nothing.

static void

test_a_transparent_sprite_is_not_an_effective_sprite(void)

{

	setup();

	sprite_trace_set_enabled(false);

	check(sprite_trace_set_enabled(true), "tracing re-enables");

	write_sprite(1, SPRITE_GFX_OPAQUE, 50, 20, 1); // draws

	write_sprite(2, SPRITE_GFX_CLEAR, 60, 20, 1);  // enabled, on screen, invisible

	check(step_one_frame(), "the beam reaches a frame boundary");

	check(step_one_frame(), "a full frame is recorded");

	const sprite_trace_frame_t *f = sprite_trace_last_frame();

	check(f != NULL, "the frame is published");

	if (!f) {

		return;

	}

	check_eq(f->summary.effective_sprites, 1u, "only the sprite with visible pixels counts");

	check_eq(f->summary.slots_used, 1u, "one slot reached the screen");

	const size_t clear_at20 = (size_t)20 * SPRITE_TRACE_SLOTS + 2;

	check(f->line_flags[clear_at20] & SPRITE_TRACE_ONSCREEN,

	      "the transparent sprite is still recorded as on screen");

	check(!(f->line_flags[clear_at20] & SPRITE_TRACE_DREW),

	      "but it is not recorded as having drawn");

}

// The per-scanline VERA budget has to be charged from the renderer's own

// accounting, and only on the lines that actually did sprite work.

static void

test_the_budget_is_charged_on_the_lines_that_did_the_work(void)

{

	setup();

	sprite_trace_set_enabled(false);

	check(sprite_trace_set_enabled(true), "tracing re-enables");

	write_sprite(0, SPRITE_GFX_OPAQUE, 100, 30, 1);

	check(step_one_frame(), "the beam reaches a frame boundary");

	check(step_one_frame(), "a full frame is recorded");

	const sprite_trace_frame_t *f = sprite_trace_last_frame();

	check(f != NULL, "the frame is published");

	if (!f) {

		return;

	}

	// Every line pays one cycle per slot looked at; a line carrying the sprite

	// pays for its fetches and pixels on top.

	const uint16_t idle = f->lines[10].budget_used;

	const uint16_t busy = f->lines[32].budget_used;

	check(busy > idle, "a line with a sprite on it costs more than one without");

	check(idle >= 128, "every line still pays to look at all 128 slots");

	check_eq(f->lines[32].drawn, 1u, "one sprite drew on that line");

	check_eq(f->summary.lines_exhausted, 0u, "a single small sprite is nowhere near the budget");

	check(f->summary.peak_budget < SPRITE_TRACE_LINE_BUDGET,

	      "peak demand stays under the hardware ceiling");

}

// Sprites are never free. Once a scanline runs out of render time, VERA stops

// both its sprite search and its line renderer until the next line

// (sprite_renderer.v:171,349), so everything after the cut is off screen. This

// is the check that the emulator drops them instead of drawing them for

// nothing.

static void

test_a_line_out_of_render_time_drops_the_rest(void)

{

	setup();

	sprite_trace_set_enabled(false);

	check(sprite_trace_set_enabled(true), "tracing re-enables");

	// 64x64 8bpp sprites cost roughly 64 pixels + 16 fetches + 3 dispatch per

	// line each, so a dozen of them on one line cannot fit in 798 clocks.

	const int overload = 24;

	for (int slot = 0; slot < overload; slot++) {

		write_sprite_sized(slot, SPRITE_GFX_BIG, slot * 8, 100, 1, 3, 3, 1);

	}

	check(step_one_frame(), "the beam reaches a frame boundary");

	check(step_one_frame(), "a full frame is recorded");

	const sprite_trace_frame_t *f = sprite_trace_last_frame();

	check(f != NULL, "the frame is published");

	if (!f) {

		return;

	}

	const sprite_line_stat_t *line = &f->lines[120]; // inside the 100..163 band

	check(line->exhausted, "the overloaded line runs out of render time");

	check(line->demand > SPRITE_TRACE_LINE_BUDGET,

	      "and it wanted more than the line has to give");

	check_eq(line->budget_used, (uint32_t)SPRITE_TRACE_LINE_BUDGET,

	         "it spends exactly the ceiling, never more");

	check(line->dropped > 0, "sprites were dropped");

	check(line->drawn < overload, "not every sprite reached the screen");

	check(f->summary.sprites_dropped > 0, "the frame reports the drops");

	// The cut is ordered: low slots win, high slots lose. That is the whole

	// reason a multiplexer cares which slot a sprite goes in.

	check(line->cut_slot != SPRITE_TRACE_NO_LINE, "the cut point is recorded");

	check(f->line_flags[(size_t)120 * SPRITE_TRACE_SLOTS + 0] & SPRITE_TRACE_DREW,

	      "slot 0 drew: the search reaches it first");

	check(!(f->line_flags[(size_t)120 * SPRITE_TRACE_SLOTS + (overload - 1)] & SPRITE_TRACE_DREW),

	      "the last slot did not: time had run out before the search got there");

	// A line the sprites do not cover must be untouched by all of this.

	check(!f->lines[300].exhausted, "a line without sprites has time to spare");

}

// The counterpart to the test above: stepping over empty slots must not starve

// the line. VERA's search FSM advances one slot per clock whether or not the

// line renderer is busy (sprite_renderer.v:146-160), so scanning empties

// overlaps with drawing. Charging them serially would drop sprites real

// hardware draws -- a false dropout, which is worse than none at all.

//

// Measured as a difference rather than an absolute: the same eight sprites are

// placed low in the slot table, where the 120 empty slots are scanned after

// them and overlap with drawing, and then high, where the empties are scanned

// first and cannot overlap. If the search overlapped, the first costs less.

static void

test_stepping_over_empty_slots_overlaps_with_drawing(void)

{

	setup();

	sprite_trace_set_enabled(false);

	check(sprite_trace_set_enabled(true), "tracing re-enables");

	for (int n = 0; n < 8; n++) {

		write_sprite_sized(n, SPRITE_GFX_BIG, n * 70, 100, 1, 3, 3, 1);

	}

	check(step_one_frame(), "the beam reaches a frame boundary");

	check(step_one_frame(), "a full frame is recorded");

	const sprite_trace_frame_t *f = sprite_trace_last_frame();

	check(f != NULL, "the low-slot frame is published");

	if (!f) {

		return;

	}

	const uint32_t low_demand = f->lines[120].demand;

	const uint16_t low_drawn  = f->lines[120].drawn;

	check(!f->lines[120].exhausted, "eight big sprites fit on a line");

	check_eq(low_drawn, 8u, "all eight drew");

	// Same eight sprites, now at the top of the slot table.

	setup();

	sprite_trace_set_enabled(false);

	check(sprite_trace_set_enabled(true), "tracing re-enables");

	for (int n = 0; n < 8; n++) {

		write_sprite_sized(120 + n, SPRITE_GFX_BIG, n * 70, 100, 1, 3, 3, 1);

	}

	check(step_one_frame(), "the beam reaches a frame boundary");

	check(step_one_frame(), "a full frame is recorded");

	f = sprite_trace_last_frame();

	check(f != NULL, "the high-slot frame is published");

	if (!f) {

		return;

	}

	const uint32_t high_demand = f->lines[120].demand;

	check_eq(f->lines[120].drawn, 8u, "all eight still drew");

	check(high_demand > low_demand,

	      "the same sprites cost more when no drawing overlaps the search");

}

// How many sprites actually fit on a line, which is the number a multiplexer

// budgets against. Pinned as a test because it falls out of the timing model:

// if the per-sprite cost drifts, this moves and someone should know why.

//

// Cost per sprite is 2 clocks to dispatch (SF_FIND_SPRITE, SF_START_RENDER),

// 1 for STATE_IDLE, then 1 per pixel and 1 per 32-bit fetch -- 8 pixels per

// fetch at 4bpp, 4 at 8bpp. An 8x8 4bpp sprite is therefore 3 + 8 + 1 = 12

// clocks, and 798 / 12 is 66.

static void

test_how_many_sprites_fit_on_one_line(void)

{

	setup();

	sprite_trace_set_enabled(false);

	check(sprite_trace_set_enabled(true), "tracing re-enables");

	// Every slot enabled and on the same line, spread across the screen.

	for (int slot = 0; slot < 128; slot++) {

		write_sprite_sized(slot, SPRITE_GFX_OPAQUE, (slot * 5) % 632, 100, 1, 0, 0, 0);

	}

	check(step_one_frame(), "the beam reaches a frame boundary");

	check(step_one_frame(), "a full frame is recorded");

	const sprite_trace_frame_t *f = sprite_trace_last_frame();

	check(f != NULL, "the frame is published");

	if (!f) {

		return;

	}

	const sprite_line_stat_t *line = &f->lines[100];

	printf("      8x8 4bpp sprites drawn on one line: %u of 128 (wanted %u of %d clocks)\n",

	       line->drawn, line->demand, SPRITE_TRACE_LINE_BUDGET);

	check(line->exhausted, "128 sprites on one line does not fit");

	check(line->drawn >= 60 && line->drawn <= 70,

	      "about 66 of them fit, at 12 clocks each");

	check_eq((uint32_t)(line->drawn + line->dropped), 128u,

	         "every slot is accounted for as drawn or dropped");

}

int

main(void)

{

	test_a_slot_rewritten_mid_frame_yields_two_effective_sprites();

	test_a_transparent_sprite_is_not_an_effective_sprite();

	test_the_budget_is_charged_on_the_lines_that_did_the_work();

	test_a_line_out_of_render_time_drops_the_rest();

	test_stepping_over_empty_slots_overlaps_with_drawing();

	test_how_many_sprites_fit_on_one_line();

	sprite_trace_set_enabled(false);

	return x16_test_summary("sprite_multiplex");

}