// JoeyLib lifecycle: configuration, initialization, shutdown.

#ifndef JOEYLIB_CORE_H
#define JOEYLIB_CORE_H

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

typedef struct {
    HostModeE hostMode;       // takeover or cooperate with host OS
    uint32_t  codegenBytes;   // runtime compiled-sprite cache size
    uint16_t  maxSurfaces;    // maximum concurrent surfaces
    uint32_t  audioBytes;     // audio sample and module RAM pool
    uint32_t  assetBytes;     // tileset / sprite / map RAM pool
} JoeyConfigT;

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

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

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

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

// Returns the library version string (e.g., "1.0.0").
const char *joeyVersionString(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 joeyWaitVBL(void);

#endif