// 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    pcm_reset(void);
void    pcm_write_ctrl(uint8_t val);
uint8_t pcm_read_ctrl(void);
void    pcm_write_rate(uint8_t val);
uint8_t pcm_read_rate(void);
void    pcm_write_fifo(uint8_t val);
void    pcm_render(int16_t *buf, unsigned num_samples);
bool    pcm_is_fifo_almost_empty(void);

// ─── Debugger accessors ─────────────────────────────────────────────────────
// Read-only views of the VERA PCM channel for the ImGui debugger's PCM panel.
// Called from the emulator main thread — the same thread that runs pcm_render()
// via audio_render() — so no locking is needed.

#define PCM_FIFO_SIZE 4096

struct pcm_debug_state {
	uint8_t  ctrl;         // AUDIO_CTRL as stored (bits 5-0; format + volume)
	uint8_t  rate;         // effective rate divider after the >128 clamp
	bool     loop;
	unsigned fifo_cnt;     // bytes queued
	unsigned fifo_rdidx;
	unsigned fifo_wridx;
	unsigned fifo_size;    // PCM_FIFO_SIZE (usable fill is fifo_size - 1)
	int16_t  cur_l, cur_r; // last sample fetched from the FIFO
	uint8_t  phase;        // 8-bit playback phase accumulator
	bool     almost_empty; // the AFLOW IRQ condition (fifo_cnt < 1024)
};

void pcm_debug_get_state(struct pcm_debug_state *out);

// Copy up to `len` queued FIFO bytes into `dest`, starting `offset` bytes after
// the read pointer, without consuming anything. Handles the ring wrap and stops
// at the end of the queued data. Returns the number of bytes written.
unsigned pcm_debug_peek_fifo(uint8_t *dest, unsigned offset, unsigned len);

// ─── Scope capture ──────────────────────────────────────────────────────────
// Self-arming output capture, same contract as the PSG's (see vera_psg.h):
// reading (re)arms it for roughly half a second, so pcm_render() costs nothing
// extra while the debugger's Scope tab is hidden.

#define PCM_SCOPE_SAMPLES 2048
#define PCM_SCOPE_L       0
#define PCM_SCOPE_R       1
#define PCM_SCOPE_STREAMS 2

unsigned pcm_debug_scope_read(int side, int16_t *dest, unsigned max_samples);

// Predict the next `num_samples` of playback from the queued FIFO contents,
// WITHOUT consuming them. Returns the sample count written to each side.
//
// For the debugger: scope capture is self-arming and nothing renders audio while
// paused, so a scope opened at a breakpoint has an empty ring. The FIFO already
// holds the samples that are about to play, so we can show them. Runs the real
// pcm_render() over saved-and-restored state, so the rate stepping, FIFO drain
// order and loop restart all behave exactly as they will on resume.
//
// This is a projection of queued data, not captured output; label it as such.
//
// Implementation note for reviewers: this runs the live FIFO state forward and
// then rewinds it, rather than working on a copy. That is safe here because
//   * every field pcm_render() touches is saved and restored (the FIFO, its
//     three indices, the held sample pair and the rate phase - there is no
//     hidden or derived state), and
//   * pcm_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 pcm_debug_scope_predict(int16_t *dest_l, int16_t *dest_r, unsigned num_samples);

#ifdef __cplusplus
}
#endif