// dvxPlatform.h — Platform abstraction layer for DVX GUI
//
// All OS-specific and CPU-specific code is isolated behind this
// interface.  To port DVX to a new platform, implement a new
// dvxPlatformXxx.c against this header.
#ifndef DVX_PLATFORM_H
#define DVX_PLATFORM_H

#include "../dvxTypes.h"

// ============================================================
// Keyboard event
// ============================================================

typedef struct {
    int32_t ascii;      // ASCII value, 0 for extended/function keys
    int32_t scancode;   // PC scan code (0x48=Up, 0x50=Down, etc.)
} PlatformKeyEventT;

// ============================================================
// System lifecycle
// ============================================================

// One-time platform initialisation (signal handling, etc.)
void platformInit(void);

// Cooperative multitasking yield (give up CPU when idle)
void platformYield(void);

// ============================================================
// Video
// ============================================================

// Initialise video mode, map framebuffer, allocate backbuffer.
// Fills in all DisplayT fields on success.  Returns 0/-1.
int32_t platformVideoInit(DisplayT *d, int32_t requestedW, int32_t requestedH, int32_t preferredBpp);

// Shut down video — restore text mode, unmap framebuffer, free backbuffer.
void platformVideoShutdown(DisplayT *d);

// Set palette entries (8-bit mode).  pal is R,G,B triplets.
void platformVideoSetPalette(const uint8_t *pal, int32_t firstEntry, int32_t count);

// ============================================================
// Framebuffer flush
// ============================================================

// Copy a rectangle from d->backBuf to the display surface (d->lfb).
void platformFlushRect(const DisplayT *d, const RectT *r);

// ============================================================
// Optimised memory operations (span fill / copy)
// ============================================================

void platformSpanFill8(uint8_t *dst, uint32_t color, int32_t count);
void platformSpanFill16(uint8_t *dst, uint32_t color, int32_t count);
void platformSpanFill32(uint8_t *dst, uint32_t color, int32_t count);
void platformSpanCopy8(uint8_t *dst, const uint8_t *src, int32_t count);
void platformSpanCopy16(uint8_t *dst, const uint8_t *src, int32_t count);
void platformSpanCopy32(uint8_t *dst, const uint8_t *src, int32_t count);

// ============================================================
// Input — Mouse
// ============================================================

// Initialise mouse driver, set movement range, centre cursor.
void platformMouseInit(int32_t screenW, int32_t screenH);

// Read current mouse position and button state.
void platformMousePoll(int32_t *mx, int32_t *my, int32_t *buttons);

// ============================================================
// Input — Keyboard
// ============================================================

// Return current modifier flags (BIOS shift-state format:
// bits 0-1 = shift, bit 2 = ctrl, bit 3 = alt).
int32_t platformKeyboardGetModifiers(void);

// Read the next key from the keyboard buffer.
// Returns true if a key was available, false if the buffer was empty.
// Normalises extended-key markers (e.g. 0xE0 → 0).
bool platformKeyboardRead(PlatformKeyEventT *evt);

// Map a scan code to its Alt+letter ASCII character.
// Returns the lowercase letter if the scan code corresponds to an
// Alt+letter/digit combo, or 0 if it does not.
char platformAltScanToChar(int32_t scancode);

// ============================================================
// File system
// ============================================================

// Validate a filename for the current platform.
// Returns NULL if valid, or a human-readable error string if invalid.
const char *platformValidateFilename(const char *name);

#endif // DVX_PLATFORM_H