coreif

type AspectProvider interface {
	// PixelAspectRatio returns the current pixel aspect ratio.
	PixelAspectRatio() float64
}

type BIOSOption struct {
	Key      string        // Unique key, e.g. "main_bios"
	Label    string        // Display label, e.g. "System BIOS"
	Required bool          // true = core cannot run without it
	Variants []BIOSVariant // Known BIOS dumps
}

type BIOSVariant struct {
	Label    string // Display name, e.g. "US v1.0"
	SHA256   string // Expected SHA256 hex
	Filename string // Default filename for system directory lookup
}

type BatterySaver interface {
	// HasSRAM reports whether the loaded ROM uses battery-backed save.
	HasSRAM() bool

	// GetSRAM returns a copy of the current SRAM contents.
	GetSRAM() []byte

	// SetSRAM loads SRAM contents into the emulator.
	SetSRAM(data []byte)
}

type BusRegion struct {
	Name  string
	Start uint32 // native bus address of the region's first byte
	Size  uint32 // region size in bytes
}

type Button struct {
	Name       string
	ID         int    // Bit position in the uint32 bitmask (4+)
	DefaultKey string // Default keyboard key for desktop UI (e.g., "J", "Enter")
	DefaultPad string // Default gamepad button for desktop UI (e.g., "A", "Start")
}

type CoreFactory interface {
	// SystemInfo returns system metadata for UI configuration.
	SystemInfo() SystemInfo

	// CreateEmulator creates a new emulator instance. Content is provided
	// afterwards via Emulator.SetRom (cartridge) or Emulator.SetDisc (disc).
	CreateEmulator() Emulator
}

type CoreOption struct {
	Key         string
	Label       string
	Description string
	Type        CoreOptionType
	Default     string
	Values      []string           // Options for Select type
	Min         int                // Minimum for Range type
	Max         int                // Maximum for Range type
	Step        int                // Step size for Range type
	Category    CoreOptionCategory // Settings section routing
	PerGame     bool               // Whether this can be overridden per game
}

type CoreOptionCategory int

type CoreOptionType int

type DiscIdentifier interface {
	// DiscInfo returns the disc's derived information and true when it
	// can be read.
	DiscInfo(disc DiscReader) (info DiscInfo, ok bool)
}

type DiscInfo struct {
	// ProductNumber is the disc's product number. It is the same for
	// every disc of a multi-disc game, so the UI also uses it as the
	// library/grouping key.
	ProductNumber string

	// DiscNumber is the 1-based position of this disc within the game.
	DiscNumber int

	// DiscTotal is the total number of discs the game spans.
	DiscTotal int

	// Title is the on-disc game title, used as a display-name fallback.
	Title string
}

type DiscReader interface {
	// ReadSector returns the raw 2352-byte sector at the given LBA.
	ReadSector(lba int) ([]byte, error)

	// NumTracks returns the number of tracks on the disc.
	NumTracks() int

	// Track returns the TOC fields for track index i in [0, NumTracks).
	Track(i int) (number int, typ string, frames int, pregap int, startLBA int, control uint8)

	// NumTrackIndexes returns the count of index entries (index numbers >= 1)
	// for track index i in [0, NumTracks). Index 0 (the pregap) is not reported
	// here; it is implied for any FAD below the first entry.
	NumTrackIndexes(i int) int

	// TrackIndex returns the nth index entry of track index i. n is a 0-based
	// ordinal into the exposed list in [0, NumTrackIndexes(i)), not the index
	// number; entry 0 is the lowest-numbered exposed index (normally INDEX 01).
	// The returned lba is the absolute disc LBA of the index.
	TrackIndex(i, n int) (indexNumber int, lba int)

	// Close releases the underlying resources.
	Close() error
}

type Emulator interface {
	// RunFrame executes one frame of emulation.
	RunFrame()

	// GetFramebuffer returns the current frame as RGBA pixel data.
	GetFramebuffer() []byte

	// GetFramebufferStride returns bytes per row in the framebuffer.
	GetFramebufferStride() int

	// GetActiveHeight returns the current active display height in pixels.
	GetActiveHeight() int

	// GetAudioSamples returns stereo 16-bit PCM audio samples for the frame.
	GetAudioSamples() []int16

	// SetInput sets controller state as a button bitmask for the given player.
	SetInput(player int, buttons uint32)

	// GetTiming returns FPS and scanline count for the current region.
	GetTiming() Timing

	// SetOption applies a core option change identified by key.
	SetOption(key string, value string)

	// SetRom provides cartridge ROM data. Called after CreateEmulator and
	// before Start(). Disc-based cores ignore this and receive content via
	// SetDisc instead.
	SetRom(data []byte)

	// SetDisc provides a streaming disc reader for disc-based cores. Called
	// after CreateEmulator and before Start(). Cartridge cores ignore this.
	SetDisc(disc DiscReader)

	// SetBIOS provides BIOS data for the given key. Called after
	// CreateEmulator and before Start(). Cores without BIOS ignore this.
	// Returns an error if the data is invalid for the given key.
	SetBIOS(key string, data []byte) error

	// Start finalizes emulator state after all options are applied.
	// Must be called after SetOption and before the first RunFrame.
	Start()

	// Close releases any resources held by the emulator.
	Close()
}

type Memory interface {
	// ReadMemory reads from a native bus address into buf and returns
	// the number of bytes read.
	ReadMemory(addr uint32, buf []byte) uint32

	// WriteMemory writes data to a native bus address and returns the
	// number of bytes written.
	WriteMemory(addr uint32, data []byte) uint32

	// Regions describes the accessible bus regions in canonical
	// addresses. The table is static per machine.
	Regions() []BusRegion

	// ReadMemoryFlat reads from the console's flat memory convention
	// (the RetroAchievements layout) into buf and returns the number
	// of bytes read. Reads are contiguous across region boundaries
	// within the flat space.
	ReadMemoryFlat(off uint32, buf []byte) uint32

	// WriteMemoryFlat writes data to the console's flat memory
	// convention and returns the number of bytes written, matching
	// ReadMemoryFlat's layout and boundary behavior.
	WriteMemoryFlat(off uint32, data []byte) uint32
}

type MetadataVariant struct {
	Name          string // Display name, e.g. "Neo Geo Pocket"
	RDBName       string // e.g. "SNK - Neo Geo Pocket"
	ThumbnailRepo string // e.g. "SNK_-_Neo_Geo_Pocket"
	RumbleRepoDir string // e.g. "ngp"
	ConsoleID     int    // RetroAchievements console ID override; 0 = use SystemInfo.ConsoleID
}

type SaveStater interface {
	// Serialize captures the complete emulator state.
	Serialize() ([]byte, error)

	// Deserialize restores emulator state from previously serialized data.
	Deserialize(data []byte) error
}

type SystemInfo struct {
	Name             string
	ConsoleName      string
	Extensions       []string
	ScreenWidth      int
	MaxScreenHeight  int
	PixelAspectRatio float64
	SampleRate       int
	Buttons          []Button
	Players          int
	CoreOptions      []CoreOption
	MetadataVariants []MetadataVariant
	DataDirName      string
	ConsoleID        int
	CoreName         string
	CoreVersion      string
	SerializeSize    int
	BigEndianMemory  bool // true for big-endian CPUs (e.g. 68K)
	Disc             bool // true if content is a disc image (use SetDisc)
	BIOSOptions      []BIOSOption
}

type Timing struct {
	FPS       int
	Scanlines int
}