// Commander X16 Emulator

// Copyright (c) 2020 Frank van den Hoef

// All rights reserved. License: 2-clause BSD

#pragma once

#include <stdint.h>

#include <stdbool.h>

#ifdef __cplusplus

extern "C" {

#endif

void psg_reset(void);

void psg_writereg(uint8_t reg, uint8_t val);

void psg_render(int16_t *buf, unsigned num_samples);

// ─── Debugger accessors ─────────────────────────────────────────────────────

// Read-only views of the PSG for the ImGui debugger's PSG panel. All of these

// are side-effect free (apart from arming/clearing the debug-only capture state

// documented below) and are called from the emulator main thread — the same

// thread that runs psg_render() via audio_render() — so no locking is needed.

#define PSG_NUM_CHANNELS 16

#define PSG_NUM_REGS     (PSG_NUM_CHANNELS * 4)

// Waveform codes, register +3 bits 7-6.

enum psg_waveform {

	PSG_WF_PULSE = 0,

	PSG_WF_SAWTOOTH,

	PSG_WF_TRIANGLE,

	PSG_WF_NOISE,

};

struct psg_debug_channel {

	uint16_t freq;        // 16-bit frequency word

	uint8_t  vol_raw;     // volume as written (0-63)

	uint16_t vol_lut;     // volume after the 64-entry LUT (0-511)

	bool     left, right;

	uint8_t  pw;          // pulse width (Pulse) / wave-shaping mask (Saw, Tri)

	uint8_t  waveform;    // enum psg_waveform

	uint32_t phase;       // live 17-bit phase accumulator

	uint16_t noiseval;    // last latched noise sample (0-63)

	int16_t  last_sample; // last rendered sample, before L/R panning

	uint16_t peak;        // peak |sample| since the previous call (then reset)

};

// Snapshot one voice. `peak` reports the loudest sample since the previous call

// and is reset by it, which is exactly what a per-frame level meter wants.

// Returns false (and leaves *out untouched) for an out-of-range index.

bool psg_debug_get_channel(int ch, struct psg_debug_channel *out);

// Raw register byte as last written. VERA also mirrors these into video_ram at

// $1F9C0+reg, but that mirror survives psg_reset(), so prefer this shadow.

uint8_t psg_debug_get_reg(uint8_t reg);

// The shared 16-bit noise LFSR state.

uint16_t psg_debug_get_noise_state(void);

// ─── Scope capture ──────────────────────────────────────────────────────────

// Self-arming per-voice sample capture backing the debugger's oscilloscope.

// psg_debug_scope_read() (re)arms capture for roughly half a second; if nothing

// reads for that long, capture switches itself off again. psg_render() therefore

// costs nothing extra while the Scope tab is hidden, and the panels need no

// explicit enable/disable lifecycle.

#define PSG_SCOPE_SAMPLES  2048             // ring depth, ~42 ms at 48828 Hz

#define PSG_SCOPE_MIX_L    PSG_NUM_CHANNELS // summed PSG output, left

#define PSG_SCOPE_MIX_R    (PSG_NUM_CHANNELS + 1)

#define PSG_SCOPE_STREAMS  (PSG_NUM_CHANNELS + 2)

// Copy the most recent `max_samples` samples of stream `ch` (a voice index, or

// PSG_SCOPE_MIX_L/R) into `dest`, oldest first. All streams share one write

// index, so reads of different streams are time-aligned. Returns the sample

// count written; always (re)arms capture, even for an invalid stream.

unsigned psg_debug_scope_read(int ch, int16_t *dest, unsigned max_samples);

// Predict what the next `num_samples` would look like, from the current voice

// state, WITHOUT advancing the PSG. Fills every stream (indexed as above) of

// `dest` and returns the sample count written to each.

//

// This exists for the debugger: scope capture is self-arming and nothing renders

// audio while the machine is paused, so a scope opened at a breakpoint would

// otherwise have nothing to draw. The registers fully determine the waveform, so

// we can run the real renderer forward on the voice state and show what it is

// about to emit. It is a projection of the current registers, not captured

// output, so callers must label it as such.

//

// Uses the same render path as live audio, so the traces cannot drift from it.

//

// Implementation note for reviewers: this runs the live voice state forward and

// then rewinds it, rather than working on a copy. That is safe here because

//   * every field render() touches is saved and restored (the state is just

//     `channels` and the noise LFSR - there is no hidden or derived state), and

//   * psg_render() is only ever called from audio_render() on the main thread,

//     the same thread as the debugger, and not at all while paused.

// Nothing in the audio path observes the intermediate state.

unsigned psg_debug_scope_predict(int16_t (*dest)[PSG_SCOPE_SAMPLES], unsigned num_samples);

#ifdef __cplusplus

}

#endif