#ifndef NOVA64_CORE_H
#define NOVA64_CORE_H

#include <stdbool.h>
#include <stdint.h>

// Cross-platform DLL export/import visibility macros
#if defined(_WIN32) || defined(__CYGWIN__)
#ifdef NOVA64_EXPORTS
#define NOVA64_API __declspec(dllexport)
#else
#define NOVA64_API __declspec(dllimport)
#endif
#else
#if __GNUC__ >= 4
#define NOVA64_API __attribute__((visibility("default")))
#else
#define NOVA64_API
#endif
#endif

/* ========================================================================== */
/* I/O Callback Typedefs                                                      */
/* ========================================================================== */

/**
 * @brief Callback to flush a frame buffer to the display.
 * @param buffer Pointer to raw pixel data (e.g., RGB565 / RGBA8888).
 * @param width Frame width in pixels.
 * @param height Frame height in pixels.
 */
typedef void (*nova64_display_flush_cb_t)(const uint16_t *buffer,
                                          uint16_t width, uint16_t height);

/**
 * @brief Callback to output audio samples.
 * @param samples Pointer to PCM audio sample buffer.
 * @param count Number of samples in the buffer.
 */
typedef void (*nova64_audio_output_cb_t)(const int16_t *samples,
                                         uint32_t count);

/**
 * @brief Callback to read sectors from the SD card.
 * @param sector_idx The zero-based sector index to read.
 * @param destination_buffer Pointer to memory where sector data should be
 * copied.
 * @param sector_count Number of 512-byte sectors to read.
 * @return True on success, false on read error.
 */
typedef bool (*nova64_sd_read_sector_cb_t)(uint32_t sector_idx,
                                           uint8_t *destination_buffer,
                                           uint32_t sector_count);

/**
 * @brief Callback triggered when a cartridge state change occurs (e.g.
 * inserted/removed).
 * @param slot_idx Zero-based cartridge slot index.
 * @param is_inserted True if a cartridge is detected, false if ejected.
 */
typedef void (*nova64_cartridge_status_cb_t)(uint32_t slot_idx,
                                            bool is_inserted);

/* ========================================================================== */
/* I/O Interface Configuration Struct                                         */
/* ========================================================================== */

/**
 * @brief Struct containing all I/O hardware abstraction callbacks.
 *        Pass NULL for any unneeded callback.
 */
typedef struct {
  nova64_display_flush_cb_t display_flush;
  nova64_audio_output_cb_t audio_output;
  nova64_sd_read_sector_cb_t sd_read_sector;
  nova64_cartridge_status_cb_t cartridge_status;
} nova64_io_interface_t;

/* ========================================================================== */
/* Engine Core API                                                            */
/* ========================================================================== */

/**
 * @brief Initializes the core engine and registers host I/O interface
 * callbacks.
 * @param io_interface Pointer to filled struct containing I/O function
 * pointers.
 * @return True if initialized successfully, false if already initialized or
 * invalid.
 */
NOVA64_API bool nova64_init_io(const nova64_io_interface_t *io_interface);

/**
 * @brief Executes one engine processing tick.
 * @param delta_ms Elapsed time in milliseconds since the last tick.
 * @return 0 on success, negative error code on failure.
 */
NOVA64_API int32_t nova64_process_tick(uint32_t delta_ms);

/**
 * @brief Retrieves the engine version integer.
 * @return 24-bit packed version number (0xMMmmPP -> Major, Minor, Patch).
 */
NOVA64_API uint32_t nova64_get_version(void);

#endif // NOVA64_CORE_H