// JoeyLib lifecycle: configuration, initialization, shutdown.

#ifndef JOEYLIB_CORE_H
#define JOEYLIB_CORE_H

#include "platform.h"
#include "types.h"

typedef struct {
    uint32_t  codegenBytes;   // runtime compiled-sprite cache size
    uint16_t  maxSurfaces;    // maximum concurrent surfaces
    uint32_t  audioBytes;     // audio sample and module RAM pool
} jlConfigT;

// Initialize the library. Returns true on success.
// On failure, jlLastError() returns a human-readable description.
bool jlInit(const jlConfigT *config);

// Shut down the library, releasing all resources.
void jlShutdown(void);

// Returns the most recent error message, or NULL if none.
const char *jlLastError(void);

// Returns the platform identifier string (e.g., "Apple IIgs", "MS-DOS").
const char *jlPlatformName(void);

// Returns the library version string (e.g., "1.0.0").
const char *jlVersionString(void);

// Block the calling thread until the next display vertical blank.
// Used to pace game loops to the display's native refresh rate
// (~70 Hz on VGA mode 13h, ~50 or ~60 Hz on Amiga/ST PAL/NTSC, ~60 Hz
// on IIgs SHR). Cheap on every port since the underlying mechanism is
// always a hardware-level wait, not a software timer.
void jlWaitVBL(void);

// Monotonic 16-bit frame counter. Polled by callers; ports detect
// the rising edge inside this call (IIgs $C019, DOS $3DA, Amiga
// VPOSR) or expose a counter maintained by a VBL ISR (Atari ST).
// Caller must poll faster than 2 * jlFrameHz() so no edge is
// missed. Used by benchmarks and frame-rate-independent animation.
uint16_t jlFrameCount(void);

// Nominal display frame rate in Hz: 50 (Amiga PAL), 60 (IIgs / ST
// NTSC default), 70 (VGA mode 13h). The actual VBL cadence may
// drift slightly; the value reported here is what benchmarks divide
// by to convert iters-per-N-frames to ops/sec.
uint16_t jlFrameHz(void);

// Monotonic wall-clock millisecond counter since jlInit. Decoupled
// from frame rate -- two consecutive calls separated by a long
// render will report the true elapsed time, not the number of VBLs
// that fired. Per-port implementation: DOS uses uclock() (PIT
// counter 0, ~1 us resolution); ST reads the 200 Hz Timer C
// counter at _hz_200; Amiga uses ReadEClock (~1.4 us PAL); IIgs
// falls back to frame_count * 1000 / 60 since ORCA-C time() bursts
// the stdio cluster bank.
uint32_t jlMillisElapsed(void);

// Deterministic, seedable pseudo-random generator. Bit-identical
// output across every JoeyLib port for a given seed, since stdlib
// rand() varies wildly between DJGPP, ORCA-C, libnix, and mintlib.
// The underlying algorithm is xorshift32 (Marsaglia): period 2^32-1,
// no multiply, suitable for games but not for cryptography.
uint32_t jlRandom(void);

// Return a value in [0, bound). bound == 0 returns 0.
uint16_t jlRandomRange(uint16_t bound);

// Seed the generator. Any 32-bit value is accepted; a seed of 0 is
// remapped to 1 since xorshift cannot escape the all-zero state.
void jlRandomSeed(uint32_t seed);

#endif