VAmiga

cpp

#include <VAmiga.h>

cpp

class VAmiga

Defined in VAmiga.h:2466

The emulator. Entry point of the API.

Public Attributes

Return	Name	Description
`AmigaAPI`	`amiga`	The Amiga (state, snapshots, media, execution control).
`AgnusAPI`	`agnus`	Agnus (DMA, beam position, sub-components).
`CIAAPI`	`ciaA`	CIA A.
`CIAAPI`	`ciaB`	CIA B.
`CPUAPI`	`cpu`	The Motorola 68000 CPU.
`DeniseAPI`	`denise`	Denise (video output).
`MemoryAPI`	`mem`	Memory (ROMs, RAM, access).
`PaulaAPI`	`paula`	Paula (audio, disk controller, UART, interrupts).
`RTCAPI`	`rtc`	The real-time clock.
`AudioPortAPI`	`audioPort`	Audio port.
`ControlPortAPI`	`controlPort1`	Control port 1.
`ControlPortAPI`	`controlPort2`	Control port 2.
`SerialPortAPI`	`serialPort`	Serial port.
`VideoPortAPI`	`videoPort`	Video port.
`FloppyDriveAPI`	`df0`	Floppy drive 0 (DF0).
`FloppyDriveAPI`	`df1`	Floppy drive 1 (DF1).
`FloppyDriveAPI`	`df2`	Floppy drive 2 (DF2).
`FloppyDriveAPI`	`df3`	Floppy drive 3 (DF3).
`HardDriveAPI`	`hd0`	Hard drive 0 (DH0).
`HardDriveAPI`	`hd1`	Hard drive 1 (DH1).
`HardDriveAPI`	`hd2`	Hard drive 2 (DH2).
`HardDriveAPI`	`hd3`	Hard drive 3 (DH3).
`KeyboardAPI`	`keyboard`	Keyboard.
`MsgQueueAPI`	`msgQueue`	Message queue.
`RemoteManagerAPI`	`remoteManager`	Remote servers.
`RetroShellAPI`	`retroShell`	RetroShell command interpreter.
`FloppyDriveAPI` *	`df`	Array view of the floppy drives, indexed by drive number.
`HardDriveAPI` *	`hd`	Array view of the hard drives, indexed by drive number.

amiga

cpp

AmigaAPI amiga

Type: AmigaAPI

Defined in VAmiga.h:2475

The Amiga (state, snapshots, media, execution control).

agnus

cpp

AgnusAPI agnus

Type: AgnusAPI

Defined in VAmiga.h:2477

Agnus (DMA, beam position, sub-components).

ciaA

cpp

CIAAPI ciaA

Type: CIAAPI

Defined in VAmiga.h:2479

CIA A.

ciaB

cpp

CIAAPI ciaB

Type: CIAAPI

Defined in VAmiga.h:2481

CIA B.

cpu

cpp

CPUAPI cpu

Type: CPUAPI

Defined in VAmiga.h:2483

The Motorola 68000 CPU.

denise

cpp

DeniseAPI denise

Type: DeniseAPI

Defined in VAmiga.h:2485

Denise (video output).

mem

cpp

MemoryAPI mem

Type: MemoryAPI

Defined in VAmiga.h:2487

Memory (ROMs, RAM, access).

paula

cpp

PaulaAPI paula

Type: PaulaAPI

Defined in VAmiga.h:2489

Paula (audio, disk controller, UART, interrupts).

rtc

cpp

RTCAPI rtc

Type: RTCAPI

Defined in VAmiga.h:2491

The real-time clock.

audioPort

cpp

AudioPortAPI audioPort

Type: AudioPortAPI

Defined in VAmiga.h:2495

Audio port.

controlPort1

cpp

ControlPortAPI controlPort1

Type: ControlPortAPI

Defined in VAmiga.h:2497

Control port 1.

controlPort2

cpp

ControlPortAPI controlPort2

Type: ControlPortAPI

Defined in VAmiga.h:2499

Control port 2.

serialPort

cpp

SerialPortAPI serialPort

Type: SerialPortAPI

Defined in VAmiga.h:2501

Serial port.

videoPort

cpp

VideoPortAPI videoPort

Type: VideoPortAPI

Defined in VAmiga.h:2503

Video port.

df0

cpp

FloppyDriveAPI df0

Type: FloppyDriveAPI

Defined in VAmiga.h:2507

Floppy drive 0 (DF0).

df1

cpp

FloppyDriveAPI df1

Type: FloppyDriveAPI

Defined in VAmiga.h:2509

Floppy drive 1 (DF1).

df2

cpp

FloppyDriveAPI df2

Type: FloppyDriveAPI

Defined in VAmiga.h:2511

Floppy drive 2 (DF2).

df3

cpp

FloppyDriveAPI df3

Type: FloppyDriveAPI

Defined in VAmiga.h:2513

Floppy drive 3 (DF3).

hd0

cpp

HardDriveAPI hd0

Type: HardDriveAPI

Defined in VAmiga.h:2515

Hard drive 0 (DH0).

hd1

cpp

HardDriveAPI hd1

Type: HardDriveAPI

Defined in VAmiga.h:2517

Hard drive 1 (DH1).

hd2

cpp

HardDriveAPI hd2

Type: HardDriveAPI

Defined in VAmiga.h:2519

Hard drive 2 (DH2).

hd3

cpp

HardDriveAPI hd3

Type: HardDriveAPI

Defined in VAmiga.h:2521

Hard drive 3 (DH3).

keyboard

cpp

KeyboardAPI keyboard

Type: KeyboardAPI

Defined in VAmiga.h:2523

Keyboard.

msgQueue

cpp

MsgQueueAPI msgQueue

Type: MsgQueueAPI

Defined in VAmiga.h:2527

Message queue.

remoteManager

cpp

RemoteManagerAPI remoteManager

Type: RemoteManagerAPI

Defined in VAmiga.h:2529

Remote servers.

retroShell

cpp

RetroShellAPI retroShell

Type: RetroShellAPI

Defined in VAmiga.h:2531

RetroShell command interpreter.

df

cpp

FloppyDriveAPI * df[4]

Defined in VAmiga.h:2535

Array view of the floppy drives, indexed by drive number.

hd

cpp

HardDriveAPI * hd[4]

Defined in VAmiga.h:2537

Array view of the hard drives, indexed by drive number.

Public Methods

Return	Name	Description
const `EmulatorInfo` &	`getInfo` `const`	Returns the component's current state.
const `EmulatorInfo` &	`getCachedInfo` `const`	Returns the most recent state snapshot recorded by the emulator thread (see getInfo()).
const `EmulatorMetrics` &	`getMetrics` `const`	Returns statistical information about the components.
const `EmulatorMetrics` &	`getCachedMetrics` `const`	Returns the most recent metrics snapshot recorded by the emulator thread (see getMetrics()).
`bool`	`isPoweredOn` `const`	Returns true iff the emulator if the emulator is powered on.
`bool`	`isPoweredOff` `const`	Returns true iff the emulator if the emulator is powered off.
`bool`	`isPaused` `const`	Returns true iff the emulator is in paused state.
`bool`	`isRunning` `const`	Returns true iff the emulator is running.
`bool`	`isSuspended` `const`	Returns true iff the emulator has been suspended.
`bool`	`isHalted` `const`	Returns true iff the emulator has shut down.
`bool`	`isWarping` `const`	Returns true iff warp mode is active.
`bool`	`isTracking` `const`	Returns true iff the emulator runs in track mode.
`void`	`checkReady` `const`	Checks if the emulator is runnable. The function checks if the necessary ROMs are installed to launch the emulator. On success, the functions returns. Otherwise, an exception is thrown.
`void`	`powerOn`	Switches the emulator on.
`void`	`powerOnAsync`	Switches the emulator on without waiting for the result.
`void`	`powerOff`	Switches the emulator off.
`void`	`powerOffAsync`	Switches the emulator off without waiting for the result.
`void`	`run`	Starts emulation.
`void`	`runAsync`	Starts emulation without waiting for the result.
`void`	`pause`	Pauses emulation.
`void`	`pauseAsync`	Pauses emulation without waiting for the result.
`void`	`hardReset`	Performs a hard reset.
`void`	`hardResetAsync`	Performs a hard reset without waiting for the result.
`void`	`softReset`	Performs a soft reset.
`void`	`softResetAsync`	Performs a soft reset without waiting for the result.
`void`	`halt`	Terminates the emulator thread.
`void`	`warpOn`	Enables warp mode.
`void`	`warpOnAsync`	Enables warp mode without waiting for the result.
`void`	`warpOff`	Disables warp mode.
`void`	`warpOffAsync`	Disables warp mode without waiting for the result.
`void`	`trackOn`	Enables track mode.
`void`	`trackOnAsync`	Enables track mode without waiting for the result.
`void`	`trackOff`	Disables track mode.
`void`	`trackOffAsync`	Disables track mode without waiting for the result.
`void`	`stepInto`	Steps a single instruction.
`void`	`stepOver`	Steps over the current instruction.
`void`	`finishLine`	Finishes the current rasterline.
`void`	`finishFrame`	Finishes the current frame.
`void`	`wakeUp`	Sends a wakeup signal to the emulator thread.
`void`	`sync`	Waits until every command sent so far has been carried out.
`void`	`launch`	Launches the emulator thread.
`void`	`removeListener`	Stops delivering messages to the listener registered by launch().
`bool`	`isLaunched` `const`	Returns true if the emulator has been launched.
`i64`	`get` `const`	Queries a configuration option.
`i64`	`get` `const`	Queries a configuration option.
`void`	`set`	Configures a component.
`void`	`set`	Configures a component.
`void`	`set`	Configures the emulator to match a specific Amiga model
`void`	`setAsync`	Configures a component without waiting for the result.
`void`	`setAsync`	Configures a component without waiting for the result.
`void`	`setAsync`	Asynchronous version of set(ConfigScheme): queues the request and returns at once.
`void`	`check`	Checks if a configuration option would be accepted.
`void`	`check`	Checks if a configuration option would be accepted.
`void`	`exportConfig` `const`	Exports the current configuration.
`void`	`exportConfig` `const`	Writes the configuration into a stream (see exportConfig()).
`void`	`call`	Runs a function on the emulator thread and waits until it is done.
`void`	`callAsync`	Queues a function for the emulator thread without waiting for it.
`void`	`put`	Feeds a command into the command queue and waits for the result.
`void`	`put` `inline`	Shorthand for put(Command(type, payload)).
`void`	`put` `inline`	Shorthand for put(Command(type, payload)).
`void`	`put` `inline`	Shorthand for put(Command(type, payload)).
`void`	`put` `inline`	Shorthand for put(Command(type, payload)).
`void`	`put` `inline`	Shorthand for put(Command(type, payload)).
`void`	`put` `inline`	Shorthand for put(Command(type, payload)).
`void`	`put` `inline`	Shorthand for put(Command(type, payload)).
`void`	`putAsync`	Feeds a command into the command queue without waiting for the result.
`void`	`putAsync` `inline`	Shorthand for putAsync(Command(type, payload)).
`void`	`putAsync` `inline`	Shorthand for putAsync(Command(type, payload)).
`void`	`putAsync` `inline`	Shorthand for putAsync(Command(type, payload)).
`void`	`putAsync` `inline`	Shorthand for putAsync(Command(type, payload)).
`void`	`putAsync` `inline`	Shorthand for putAsync(Command(type, payload)).
`void`	`putAsync` `inline`	Shorthand for putAsync(Command(type, payload)).
`void`	`putAsync` `inline`	Shorthand for putAsync(Command(type, payload)).
`class Emulator &`	`getEmulator`	Gives access to the internal components.
`class Amiga &`	`getAmiga`	Returns the Amiga.
`class Agnus &`	`getAgnus`	Returns Agnus.
`class LogicAnalyzer &`	`getLogicAnalyzer`	Returns the logic analyzer.
`class XRay &`	`getXRay`	Returns the X-Ray visualizer.
`class Copper &`	`getCopper`	Returns the Copper.
`class Blitter &`	`getBlitter`	Returns the Blitter.
`class CIA &`	`getCIA`	Returns a CIA chip (nr = 0 for CIA A, 1 for CIA B).
`class CPU &`	`getCPU`	Returns the CPU.
`class Denise &`	`getDenise`	Returns Denise.
`class Memory &`	`getMemory`	Returns the memory.
`class Paula &`	`getPaula`	Returns Paula.
`class DiskController &`	`getDiskController`	Returns the disk controller.
`class UART &`	`getUART`	Returns the UART.
`class RTC &`	`getRTC`	Returns the real-time clock.
`class AudioPort &`	`getAudioPort`	Returns the audio port.
`class ControlPort &`	`getControlPort`	Returns a control port (nr = 0 or 1).
`class Joystick &`	`getJoystick`	Returns the joystick of a control port (port = 0 or 1).
`class Mouse &`	`getMouse`	Returns the mouse of a control port (port = 0 or 1).
`class SerialPort &`	`getSerialPort`	Returns the serial port.
`class VideoPort &`	`getVideoPort`	Returns the video port.
`class FloppyDrive &`	`getFloppyDrive`	Returns a floppy drive (nr = 0 ... 3).
`class HardDrive &`	`getHardDrive`	Returns a hard drive (nr = 0 ... 3).
`class HdController &`	`getHdController`	Returns the controller of a hard drive (nr = 0 ... 3).
`class Keyboard &`	`getKeyboard`	Returns the keyboard.
`class MsgQueue &`	`getMsgQueue`	Returns the message queue.
`class RemoteManager &`	`getRemoteManager`	Returns the remote server manager.
`class RetroShell &`	`getRetroShell`	Returns RetroShell.
`class Defaults &`	`getDefaults`	Returns the user defaults storage.
	`~VAmiga`	Halts the emulator thread and destroys the emulator.

getInfo

const

cpp

const EmulatorInfo & getInfo() const

Defined in VAmiga.h:2584

Returns the component's current state.

getInfo() reads the live state on the calling thread. The result is only consistent if the emulator is paused or suspended. getCachedInfo() returns the snapshot the emulator thread has recorded most recently, which is the one to use while the emulator runs. Both return references that can be overwritten by a later call or by the emulator thread, so copy the data if you need to keep it.

getCachedInfo

const

cpp

const EmulatorInfo & getCachedInfo() const

Defined in VAmiga.h:2586

Returns the most recent state snapshot recorded by the emulator thread (see getInfo()).

getMetrics

const

cpp

const EmulatorMetrics & getMetrics() const

Defined in VAmiga.h:2597

Returns statistical information about the components.

getMetrics() reads the live state on the calling thread. The result is only consistent if the emulator is paused or suspended. getCachedMetrics() returns the snapshot the emulator thread has recorded most recently, which is the one to use while the emulator runs. Both return references that can be overwritten by a later call or by the emulator thread, so copy the data if you need to keep it.

getCachedMetrics

const

cpp

const EmulatorMetrics & getCachedMetrics() const

Defined in VAmiga.h:2599

Returns the most recent metrics snapshot recorded by the emulator thread (see getMetrics()).

isPoweredOn

const

cpp

bool isPoweredOn() const

Defined in VAmiga.h:2612

Returns true iff the emulator if the emulator is powered on.

isPoweredOff

const

cpp

bool isPoweredOff() const

Defined in VAmiga.h:2616

Returns true iff the emulator if the emulator is powered off.

isPaused

const

cpp

bool isPaused() const

Defined in VAmiga.h:2620

Returns true iff the emulator is in paused state.

isRunning

const

cpp

bool isRunning() const

Defined in VAmiga.h:2624

Returns true iff the emulator is running.

isSuspended

const

cpp

bool isSuspended() const

Defined in VAmiga.h:2628

Returns true iff the emulator has been suspended.

isHalted

const

cpp

bool isHalted() const

Defined in VAmiga.h:2632

Returns true iff the emulator has shut down.

isWarping

const

cpp

bool isWarping() const

Defined in VAmiga.h:2636

Returns true iff warp mode is active.

isTracking

const

cpp

bool isTracking() const

Defined in VAmiga.h:2640

Returns true iff the emulator runs in track mode.

checkReady

const

cpp

void checkReady() const

Defined in VAmiga.h:2647

Checks if the emulator is runnable. The function checks if the necessary ROMs are installed to launch the emulator. On success, the functions returns. Otherwise, an exception is thrown.

powerOn

cpp

void powerOn()

Defined in VAmiga.h:2668

Switches the emulator on.

Powering on the emulator changes the internal state to ExecState::PAUSED, the same state that is entered when the user hits the pause button. Calling this function on an already powered-on emulator has no effect.

The function returns when the emulator thread has carried out the request. A failure throws the corresponding exception.

Exceptions

Exception	Description
`CoreError`	(CoreError::NOT_LAUNCHED) if the emulator thread cannot carry out the request, because it has not been launched yet, is halted or suspended. The same applies if the function is called from the emulator thread. Use powerOnAsync() in these situations.

powerOnAsync

cpp

void powerOnAsync()

Defined in VAmiga.h:2675

Switches the emulator on without waiting for the result.

This is the asynchronous counterpart of powerOn(). The request is queued and carried out by the emulator thread at some later time (see sync()).

powerOff

cpp

void powerOff()

Defined in VAmiga.h:2690

Switches the emulator off.

Powering off the emulator changes the internal state to ExecState::OFF. Calling this function on an already powered-off emulator has no effect.

The function returns when the emulator thread has carried out the request. A failure throws the corresponding exception.

Exceptions

Exception	Description
`CoreError`	(CoreError::NOT_LAUNCHED) if the emulator thread cannot carry out the request, because it has not been launched yet, is halted or suspended. The same applies if the function is called from the emulator thread. Use powerOffAsync() in these situations.

powerOffAsync

cpp

void powerOffAsync()

Defined in VAmiga.h:2697

Switches the emulator off without waiting for the result.

This is the asynchronous counterpart of powerOff(). The request is queued and carried out by the emulator thread at some later time (see sync()).

run

cpp

void run()

Defined in VAmiga.h:2716

Starts emulation.

Running the emulator changes the internal state to ExecState::RUNNING, which is the normal operation state. Frames are computed at normal pace, if warp mode is switched off, or as fast as possible, if warp mode is switched on. If this function is called for a powered-off emulator, an implicit call to powerOn() will be performed.

The function returns when the emulator has been started.

Exceptions

Exception	Description
`CoreError`	if the emulator is not ready to run (see checkReady()).
`CoreError`	(CoreError::NOT_LAUNCHED) if the emulator thread cannot carry out the request, because it has not been launched yet, is halted or suspended. The same applies if the function is called from the emulator thread. Use runAsync() in these situations.

runAsync

cpp

void runAsync()

Defined in VAmiga.h:2725

Starts emulation without waiting for the result.

This is the asynchronous counterpart of run(). The request is queued and carried out by the emulator thread at some later time (see sync()).

Exceptions

Exception	Description
`CoreError`	if the emulator is not ready to run (see checkReady()).

pause

cpp

void pause()

Defined in VAmiga.h:2741

Pauses emulation.

Pausing the emulator changes the internal state from ExecState::RUNNING to ExecState::PAUSED after completing the current frame. The emulator enters a frozen state where no more frames are computed.

The function returns when the emulator thread has carried out the request. A failure throws the corresponding exception.

Exceptions

Exception	Description
`CoreError`	(CoreError::NOT_LAUNCHED) if the emulator thread cannot carry out the request, because it has not been launched yet, is halted or suspended. The same applies if the function is called from the emulator thread. Use pauseAsync() in these situations.

pauseAsync

cpp

void pauseAsync()

Defined in VAmiga.h:2748

Pauses emulation without waiting for the result.

This is the asynchronous counterpart of pause(). The request is queued and carried out by the emulator thread at some later time (see sync()).

hardReset

cpp

void hardReset()

Defined in VAmiga.h:2763

Performs a hard reset.

A hard reset affects all components. The effect is similar to switching power off and on.

The function returns when the emulator thread has carried out the request. A failure throws the corresponding exception.

Exceptions

Exception	Description
`CoreError`	(CoreError::NOT_LAUNCHED) if the emulator thread cannot carry out the request, because it has not been launched yet, is halted or suspended. The same applies if the function is called from the emulator thread. Use hardResetAsync() in these situations.

hardResetAsync

cpp

void hardResetAsync()

Defined in VAmiga.h:2770

Performs a hard reset without waiting for the result.

This is the asynchronous counterpart of hardReset(). The request is queued and carried out by the emulator thread at some later time (see sync()).

softReset

cpp

void softReset()

Defined in VAmiga.h:2784

Performs a soft reset.

A soft reset is similar to executing the CPU's reset instruction.

The function returns when the emulator thread has carried out the request. A failure throws the corresponding exception.

Exceptions

Exception	Description
`CoreError`	(CoreError::NOT_LAUNCHED) if the emulator thread cannot carry out the request, because it has not been launched yet, is halted or suspended. The same applies if the function is called from the emulator thread. Use softResetAsync() in these situations.

softResetAsync

cpp

void softResetAsync()

Defined in VAmiga.h:2791

Performs a soft reset without waiting for the result.

This is the asynchronous counterpart of softReset(). The request is queued and carried out by the emulator thread at some later time (see sync()).

halt

cpp

void halt()

Defined in VAmiga.h:2805

Terminates the emulator thread.

Halting the emulator changes the internal state to ExecState::HALTED. This state is part of the shutdown procedure and never entered during normal operation.

NOTE

The function blocks until the emulator thread has terminated. It does nothing if there is no running emulator thread (e.g., if the thread has already been halted), so it is safe to call it more than once. It throws a CoreError if the calling thread has suspended the emulator thread, because a suspended thread cannot terminate.

warpOn

cpp

void warpOn(isize source)

Defined in VAmiga.h:2824

Enables warp mode.

Several clients can request the mode independently. Each client uses its own source, and the mode stays on as long as at least one source has requested it. Valid sources are 0 to 6.

The function returns when the emulator thread has carried out the request. A failure throws the corresponding exception.

Parameters

Parameter	Type	Description
`source`	`isize`	The client requesting the change.

Exceptions

Exception	Description
`CoreError`	(CoreError::OPT_INV_ARG) if the source is out of range.
`CoreError`	(CoreError::NOT_LAUNCHED) if the emulator thread cannot carry out the request, because it has not been launched yet, is halted or suspended. The same applies if the function is called from the emulator thread. Use warpOnAsync() in these situations.

warpOnAsync

cpp

void warpOnAsync(isize source)

Defined in VAmiga.h:2833

Enables warp mode without waiting for the result.

This is the asynchronous counterpart of warpOn(). The request is queued and carried out by the emulator thread at some later time (see sync()).

Exceptions

Exception	Description
`CoreError`	(CoreError::OPT_INV_ARG) if the source is out of range.

warpOff

cpp

void warpOff(isize source)

Defined in VAmiga.h:2852

Disables warp mode.

Withdraws the request made by the given source. The mode is switched off when no other source requests it (the emulator itself may keep warp mode on to implement the warp mode option). Valid sources are 0 to 6.

The function returns when the emulator thread has carried out the request. A failure throws the corresponding exception.

Parameters

Parameter	Type	Description
`source`	`isize`	The client requesting the change.

Exceptions

Exception	Description
`CoreError`	(CoreError::OPT_INV_ARG) if the source is out of range.
`CoreError`	(CoreError::NOT_LAUNCHED) if the emulator thread cannot carry out the request, because it has not been launched yet, is halted or suspended. The same applies if the function is called from the emulator thread. Use warpOffAsync() in these situations.

warpOffAsync

cpp

void warpOffAsync(isize source)

Defined in VAmiga.h:2861

Disables warp mode without waiting for the result.

This is the asynchronous counterpart of warpOff(). The request is queued and carried out by the emulator thread at some later time (see sync()).

Exceptions

Exception	Description
`CoreError`	(CoreError::OPT_INV_ARG) if the source is out of range.

trackOn

cpp

void trackOn(isize source)

Defined in VAmiga.h:2880

Enables track mode.

Several clients can request the mode independently. Each client uses its own source, and the mode stays on as long as at least one source has requested it. Valid sources are 0 to 6.

The function returns when the emulator thread has carried out the request. A failure throws the corresponding exception.

Parameters

Parameter	Type	Description
`source`	`isize`	The client requesting the change.

Exceptions

Exception	Description
`CoreError`	(CoreError::OPT_INV_ARG) if the source is out of range.
`CoreError`	(CoreError::NOT_LAUNCHED) if the emulator thread cannot carry out the request, because it has not been launched yet, is halted or suspended. The same applies if the function is called from the emulator thread. Use trackOnAsync() in these situations.

trackOnAsync

cpp

void trackOnAsync(isize source)

Defined in VAmiga.h:2889

Enables track mode without waiting for the result.

This is the asynchronous counterpart of trackOn(). The request is queued and carried out by the emulator thread at some later time (see sync()).

Exceptions

Exception	Description
`CoreError`	(CoreError::OPT_INV_ARG) if the source is out of range.

trackOff

cpp

void trackOff(isize source)

Defined in VAmiga.h:2907

Disables track mode.

Withdraws the request made by the given source. The mode is switched off when no other source requests it. Valid sources are 0 to 6.

The function returns when the emulator thread has carried out the request. A failure throws the corresponding exception.

Parameters

Parameter	Type	Description
`source`	`isize`	The client requesting the change.

Exceptions

Exception	Description
`CoreError`	(CoreError::OPT_INV_ARG) if the source is out of range.
`CoreError`	(CoreError::NOT_LAUNCHED) if the emulator thread cannot carry out the request, because it has not been launched yet, is halted or suspended. The same applies if the function is called from the emulator thread. Use trackOffAsync() in these situations.

trackOffAsync

cpp

void trackOffAsync(isize source)

Defined in VAmiga.h:2916

Disables track mode without waiting for the result.

This is the asynchronous counterpart of trackOff(). The request is queued and carried out by the emulator thread at some later time (see sync()).

Exceptions

Exception	Description
`CoreError`	(CoreError::OPT_INV_ARG) if the source is out of range.

stepInto

cpp

void stepInto()

Defined in VAmiga.h:2937

Steps a single instruction.

Steps the CPU for a single instruction. The emulator must not be running. The CPU debugger utilizes this function to implement single stepping.

The function returns when the emulator has been started for the step. It is paused again when the step is done.

Exceptions

Exception	Description
`CoreError`	(CoreError::RUNNING) if the emulator is already running.
`CoreError`	if the emulator is not ready to run (see checkReady()).
`CoreError`	(CoreError::NOT_LAUNCHED) if the emulator thread cannot carry out the request (see put()).

stepOver

cpp

void stepOver()

Defined in VAmiga.h:2964

Steps over the current instruction.

Runs the emulator until the instruction following the current instruction has been reached. The emulator must not be running. The CPU debugger utilizes this function to implement single stepping.

stepOver() acts like stepInto() except for branching instructions. For instance, if the current instruction is a JSR instruction, the subroutine will be executed in a single chunk.

NOTE

If the current instruction is a branch instruction which never returns, the emulator will remain in running state. Calling this function will then be equivalent to a calling run(), with the exception of a small runtime overhead since the emulator will check after the each instruction if the program counter has reached its target location.

The function returns when the emulator has been started for the step. It is paused again when the step is done.

Exceptions

Exception	Description
`CoreError`	(CoreError::RUNNING) if the emulator is already running.
`CoreError`	if the emulator is not ready to run (see checkReady()).
`CoreError`	(CoreError::NOT_LAUNCHED) if the emulator thread cannot carry out the request (see put()).

finishLine

cpp

void finishLine()

Defined in VAmiga.h:2978

Finishes the current rasterline.

Calling this function runs the CPU until the end of the current rasterline.

The function returns when the emulator has been started for the step. It is paused again when the step is done.

Exceptions

Exception	Description
`CoreError`	(CoreError::RUNNING) if the emulator is already running.
`CoreError`	if the emulator is not ready to run (see checkReady()).
`CoreError`	(CoreError::NOT_LAUNCHED) if the emulator thread cannot carry out the request (see put()).

finishFrame

cpp

void finishFrame()

Defined in VAmiga.h:2992

Finishes the current frame.

Calling this function runs the CPU until the end of the current frame.

The function returns when the emulator has been started for the step. It is paused again when the step is done.

Exceptions

Exception	Description
`CoreError`	(CoreError::RUNNING) if the emulator is already running.
`CoreError`	if the emulator is not ready to run (see checkReady()).
`CoreError`	(CoreError::NOT_LAUNCHED) if the emulator thread cannot carry out the request (see put()).

wakeUp

cpp

void wakeUp()

Defined in VAmiga.h:3007

Sends a wakeup signal to the emulator thread.

To compute frames at the proper pace, the emulator core expects the GUI to send a wakeup signal on each VSYNC pulse. Once this signal is received, the emulator thread starts computing all missing frames. To minimize jitter, the wakeup signal should be sent right after the current texture has been handed over to the GPU.

sync

cpp

void sync()

Defined in VAmiga.h:3021

Waits until every command sent so far has been carried out.

Most calls on this API hand the emulator thread a command and return at once, so a caller that reads back what it just changed, or exports the configuration, can still see the old state. Calling this afterwards closes that gap.

Exceptions

Exception	Description
`CoreError`	(CoreError::NOT_LAUNCHED) if the emulator thread cannot carry out commands, because it has not been launched yet, is halted or suspended. The same applies if the function is called from the emulator thread.

launch

cpp

void launch(const void * listener = nullptr, Callback * func = nullptr)

Defined in VAmiga.h:3052

Launches the emulator thread.

This function must be called in the initialization procedure of the emulator. It launches the emulator thread and registers a callback function to the message queue. The callback function is a message receiver processing all incoming messages from the emulator.

NOTE

All functions of this API must be called from a user thread, i.e., from any thread except the emulator thread. In particular, the callback registered here is invoked on the emulator thread and must not call into the API. Forward the message to a user thread instead.

Parameters

Parameter	Type	Description
`listener`	`const void *`	An arbitrary pointer which will be passed to the registered callback function as first argument. You can use the argument to pass the address of an object into the callback function. Inside the callback you can utilize the pointer to invoke a message processing function on that object.
`func`	`Callback` *	The callback function.

Exceptions

Exception	Description
`CoreError`	(CoreError::ALREADY_LAUNCHED) if the emulator thread has already been launched.
`CoreError`	(CoreError::LAUNCH_FAILED) if the emulator thread could not be launched.

removeListener

cpp

void removeListener()

Defined in VAmiga.h:3062

Stops delivering messages to the listener registered by launch().

The emulator outlives its client whenever the client is a stack or static object torn down at exit: the core keeps running, keeps posting, and calls into whatever the listener pointer used to be. Call this before the client becomes unusable. It is synchronised against message delivery, so it is safe while the emulator runs.

isLaunched

const

cpp

bool isLaunched() const

Defined in VAmiga.h:3066

Returns true if the emulator has been launched.

get

const

cpp

i64 get(Opt opt) const

Defined in VAmiga.h:3082

Queries a configuration option.

This is the main function to query a configuration option.

NOTE

Some options require an additional parameter to uniquely determine the configured component. For those options, this function must not be called.

NOTE

The value is read without synchronizing with the emulator thread. A change requested by setAsync() shows up once the emulator thread has carried it out (see sync()).

Parameters

Parameter	Type	Description
`opt`	`Opt`	The option to query

get

const

cpp

i64 get(Opt opt, isize id) const

Defined in VAmiga.h:3098

Queries a configuration option.

This is the main function to query a configuration option.

NOTE

This function must only be called for those options that require an additional parameter to uniquely determine the configured component.

NOTE

The value is read without synchronizing with the emulator thread. A change requested by setAsync() shows up once the emulator thread has carried it out (see sync()).

Parameters

Parameter	Type	Description
`opt`	`Opt`	The option to query
`id`	`isize`	The component to query

set

cpp

void set(Opt opt, i64 value)

Defined in VAmiga.h:3120

Configures a component.

This is the main function to set a configuration option. It returns when the change has been made, so the new value is visible to get() right away. Because the command queue is processed in order, all requests issued earlier (e.g., via setAsync()) have been carried out as well. A rejected value throws the corresponding exception.

NOTE

If this function is called for an options that applies to multiple components, all components are configured with the specified value.

Parameters

Parameter	Type	Description
`opt`	`Opt`	The option to set
`value`	`i64`	The option's value

Exceptions

Exception	Description
`CoreError`	(CoreError::NOT_LAUNCHED) if the emulator thread cannot carry out the request, because it has not been launched yet, is halted or suspended. The same applies if the function is called from the emulator thread. Use setAsync() in these situations (it can also be called before the emulator thread is launched, in which case the request is carried out at launch).

set

cpp

void set(Opt opt, i64 value, isize id)

Defined in VAmiga.h:3132

Configures a component.

NOTE

This function must only be called for those options that require an additional parameter to uniquely determine the configured component.

See also: set(Opt, i64)

Parameters

Parameter	Type	Description
`opt`	`Opt`	The option to set
`value`	`i64`	The option's value
`id`	`isize`	The component to configure

set

cpp

void set(ConfigScheme model)

Defined in VAmiga.h:3139

Configures the emulator to match a specific Amiga model

See also: set(Opt, i64)

Parameters

Parameter	Type	Description
`model`	`ConfigScheme`	The Amiga model to emulate

setAsync

cpp

void setAsync(Opt opt, i64 value)

Defined in VAmiga.h:3157

Configures a component without waiting for the result.

These functions hand the request to the emulator thread and return at once. They are the asynchronous counterparts of set(). Use them if waiting is impossible or undesirable, e.g., when many options are changed in a row (follow up with sync() if needed), before the emulator thread has been launched (the request is carried out at launch), or while the emulator thread is suspended (it is carried out when the thread resumes).

The value is validated when the emulator thread carries out the command. A rejected value is reported by Msg::CONFIG, which then carries the exception.

Parameters

Parameter	Type	Description
`opt`	`Opt`	The option to set
`value`	`i64`	The option's value

setAsync

cpp

void setAsync(Opt opt, i64 value, isize id)

Defined in VAmiga.h:3168

Configures a component without waiting for the result.

Same as above, for options that require an additional parameter to determine the component.

Parameters

Parameter	Type	Description
`opt`	`Opt`	The option to set
`value`	`i64`	The option's value
`id`	`isize`	The component to configure

setAsync

cpp

void setAsync(ConfigScheme model)

Defined in VAmiga.h:3170

Asynchronous version of set(ConfigScheme): queues the request and returns at once.

check

cpp

void check(Opt opt, i64 value)

Defined in VAmiga.h:3182

Checks if a configuration option would be accepted.

The check is performed in the calling thread and does not change the configuration. It is not needed before set(), which validates the value itself, but it lets a caller skip a request that is known to fail.

Parameters

Parameter	Type	Description
`opt`	`Opt`	The option to check
`value`	`i64`	The option's value

Exceptions

Exception	Description
`CoreError`	if the value would be rejected

check

cpp

void check(Opt opt, i64 value, isize id)

Defined in VAmiga.h:3190

Checks if a configuration option would be accepted.

Parameters

Parameter	Type	Description
`opt`	`Opt`	The option to check
`value`	`i64`	The option's value
`id`	`isize`	The component to configure

Exceptions

Exception	Description
`CoreError`	if the value would be rejected

exportConfig

const

cpp

void exportConfig(const std::filesystem::path & path, bool diff = false) const

Defined in VAmiga.h:3203

Exports the current configuration.

The current configuration is exported in form of a RetroShell script. Reading in the script at a later point will restore the configuration.

Parameters

Parameter	Type	Description
`path`	`const std::filesystem::path &`	The path of the script file.
`diff`	`bool`	When set to true, the script will only contains settings for items that differ from the default configuration. This feature is useful for debugging to compare two virtual machine configurations.

exportConfig

const

cpp

void exportConfig(std::ostream & stream, bool diff = false) const

Defined in VAmiga.h:3205

Writes the configuration into a stream (see exportConfig()).

call

cpp

void call(const std::function< void()> & fn)

Defined in VAmiga.h:3243

Runs a function on the emulator thread and waits until it is done.

WARNING

This is an advanced interface, see above.

The function is carried out in the order of the commands that have been queued before, and never while a frame is computed or while another thread has suspended the emulator. An exception thrown by the function is passed on to the caller.

Exceptions

Exception	Description
`CoreError`	(CoreError::NOT_LAUNCHED) if the emulator thread cannot carry out the request (see put()).

callAsync

cpp

void callAsync(std::function< void()> fn, std::function< void(std::exception_ptr)> done = nullptr)

Defined in VAmiga.h:3258

Queues a function for the emulator thread without waiting for it.

WARNING

This is an advanced interface, see above.

This is the asynchronous counterpart of call(). The function is carried out by the emulator thread at some later time, so everything it refers to must stay valid until then. A failure of the function cannot be passed on to the caller. If 'done' is given, it is called on the emulator thread when the function has been carried out, with the exception it threw (or null). It is also called, on the calling thread, if the command queue is full and the request is dropped. Nothing is carried out as long as the emulator thread has not been launched.

put

cpp

void put(const Command & cmd, const std::string & str = "")

Defined in VAmiga.h:3281

Feeds a command into the command queue and waits for the result.

WARNING

This is an advanced interface, see above.

The function returns when the emulator thread has carried out the command. A command that fails throws the corresponding exception.

Because the queue is processed in order, all commands issued earlier (e.g., via putAsync()) have been carried out when the call returns. Commands that carry a pointer to an object of the caller can rely on that object being alive for the whole duration of the command.

Exceptions

Exception Description

CoreError (CoreError::NOT_LAUNCHED) if the emulator thread cannot carry out the command, because it has not been launched yet, is halted or suspended. The same applies if the function is called from the emulator thread. Use putAsync() in these situations (it can also be called before the emulator thread is launched, in which case the command is carried out at launch), and for events that occur at a high rate (e.g., key presses or mouse movements).

Exception	Description
`CoreError`	(CoreError::NOT_LAUNCHED) if the emulator thread cannot carry out the command, because it has not been launched yet, is halted or suspended. The same applies if the function is called from the emulator thread. Use putAsync() in these situations (it can also be called before the emulator thread is launched, in which case the command is carried out at launch), and for events that occur at a high rate (e.g., key presses or mouse movements).

put

inline

cpp

inline void put(Cmd type, const std::string & str)

Defined in VAmiga.h:3283

Shorthand for put(Command(type, payload)).

put

inline

cpp

inline void put(Cmd type, i64 payload = 0, i64 payload2 = 0)

Defined in VAmiga.h:3285

Shorthand for put(Command(type, payload)).

put

inline

cpp

inline void put(Cmd type, ConfigCmd payload)

Defined in VAmiga.h:3287

Shorthand for put(Command(type, payload)).

put

inline

cpp

inline void put(Cmd type, KeyCmd payload)

Defined in VAmiga.h:3289

Shorthand for put(Command(type, payload)).

put

inline

cpp

inline void put(Cmd type, GamePadCmd payload)

Defined in VAmiga.h:3291

Shorthand for put(Command(type, payload)).

put

inline

cpp

inline void put(Cmd type, CoordCmd payload)

Defined in VAmiga.h:3293

Shorthand for put(Command(type, payload)).

put

inline

cpp

inline void put(Cmd type, AlarmCmd payload)

Defined in VAmiga.h:3295

Shorthand for put(Command(type, payload)).

putAsync

cpp

void putAsync(const Command & cmd, const std::string & str = "")

Defined in VAmiga.h:3305

Feeds a command into the command queue without waiting for the result.

WARNING

This is an advanced interface, see put().

This is the asynchronous counterpart of put(). The command is carried out by the emulator thread at some later time. The caller must keep objects referenced by the command alive until it has been carried out (see sync()).

putAsync

inline

cpp

inline void putAsync(Cmd type, const std::string & str)

Defined in VAmiga.h:3307

Shorthand for putAsync(Command(type, payload)).

putAsync

inline

cpp

inline void putAsync(Cmd type, i64 payload = 0, i64 payload2 = 0)

Defined in VAmiga.h:3309

Shorthand for putAsync(Command(type, payload)).

putAsync

inline

cpp

inline void putAsync(Cmd type, ConfigCmd payload)

Defined in VAmiga.h:3311

Shorthand for putAsync(Command(type, payload)).

putAsync

inline

cpp

inline void putAsync(Cmd type, KeyCmd payload)

Defined in VAmiga.h:3313

Shorthand for putAsync(Command(type, payload)).

putAsync

inline

cpp

inline void putAsync(Cmd type, GamePadCmd payload)

Defined in VAmiga.h:3315

Shorthand for putAsync(Command(type, payload)).

putAsync

inline

cpp

inline void putAsync(Cmd type, CoordCmd payload)

Defined in VAmiga.h:3317

Shorthand for putAsync(Command(type, payload)).

putAsync

inline

cpp

inline void putAsync(Cmd type, AlarmCmd payload)

Defined in VAmiga.h:3319

Shorthand for putAsync(Command(type, payload)).

getEmulator

cpp

class Emulator & getEmulator()

Defined in VAmiga.h:3333

Gives access to the internal components.

WARNING

These are advanced interfaces. They return the internal objects the APIs operate on, bypassing all synchronization the dedicated API functions provide. Use them only while the emulator is suspended or from within a function passed to call(). To make use of the objects, include the corresponding internal headers. What they offer is not covered by any compatibility promise.

The getters that take a number throw a CoreError (CoreError::OPT_INV_ARG) if the number is out of range.

getAmiga

cpp

class Amiga & getAmiga()

Defined in VAmiga.h:3335

Returns the Amiga.

getAgnus

cpp

class Agnus & getAgnus()

Defined in VAmiga.h:3337

Returns Agnus.

getLogicAnalyzer

cpp

class LogicAnalyzer & getLogicAnalyzer()

Defined in VAmiga.h:3339

Returns the logic analyzer.

getXRay

cpp

class XRay & getXRay()

Defined in VAmiga.h:3341

Returns the X-Ray visualizer.

getCopper

cpp

class Copper & getCopper()

Defined in VAmiga.h:3343

Returns the Copper.

getBlitter

cpp

class Blitter & getBlitter()

Defined in VAmiga.h:3345

Returns the Blitter.

getCIA

cpp

class CIA & getCIA(isize nr)

Defined in VAmiga.h:3347

Returns a CIA chip (nr = 0 for CIA A, 1 for CIA B).

getCPU

cpp

class CPU & getCPU()

Defined in VAmiga.h:3349

Returns the CPU.

getDenise

cpp

class Denise & getDenise()

Defined in VAmiga.h:3351

Returns Denise.

getMemory

cpp

class Memory & getMemory()

Defined in VAmiga.h:3353

Returns the memory.

getPaula

cpp

class Paula & getPaula()

Defined in VAmiga.h:3355

Returns Paula.

getDiskController

cpp

class DiskController & getDiskController()

Defined in VAmiga.h:3357

Returns the disk controller.

getUART

cpp

class UART & getUART()

Defined in VAmiga.h:3359

Returns the UART.

getRTC

cpp

class RTC & getRTC()

Defined in VAmiga.h:3361

Returns the real-time clock.

getAudioPort

cpp

class AudioPort & getAudioPort()

Defined in VAmiga.h:3363

Returns the audio port.

getControlPort

cpp

class ControlPort & getControlPort(isize nr)

Defined in VAmiga.h:3365

Returns a control port (nr = 0 or 1).

getJoystick

cpp

class Joystick & getJoystick(isize port)

Defined in VAmiga.h:3367

Returns the joystick of a control port (port = 0 or 1).

getMouse

cpp

class Mouse & getMouse(isize port)

Defined in VAmiga.h:3369

Returns the mouse of a control port (port = 0 or 1).

getSerialPort

cpp

class SerialPort & getSerialPort()

Defined in VAmiga.h:3371

Returns the serial port.

getVideoPort

cpp

class VideoPort & getVideoPort()

Defined in VAmiga.h:3373

Returns the video port.

getFloppyDrive

cpp

class FloppyDrive & getFloppyDrive(isize nr)

Defined in VAmiga.h:3375

Returns a floppy drive (nr = 0 ... 3).

getHardDrive

cpp

class HardDrive & getHardDrive(isize nr)

Defined in VAmiga.h:3377

Returns a hard drive (nr = 0 ... 3).

getHdController

cpp

class HdController & getHdController(isize nr)

Defined in VAmiga.h:3379

Returns the controller of a hard drive (nr = 0 ... 3).

getKeyboard

cpp

class Keyboard & getKeyboard()

Defined in VAmiga.h:3381

Returns the keyboard.

getMsgQueue

cpp

class MsgQueue & getMsgQueue()

Defined in VAmiga.h:3383

Returns the message queue.

getRemoteManager

cpp

class RemoteManager & getRemoteManager()

Defined in VAmiga.h:3385

Returns the remote server manager.

getRetroShell

cpp

class RetroShell & getRetroShell()

Defined in VAmiga.h:3387

Returns RetroShell.

getDefaults

cpp

class Defaults & getDefaults()

Defined in VAmiga.h:3389

Returns the user defaults storage.

~VAmiga

cpp

~VAmiga()

Defined in VAmiga.h:2567

Halts the emulator thread and destroys the emulator.

A suspension that the calling thread still holds is released first, because a suspended emulator thread cannot be halted.

Public Static Attributes

Return	Name	Description
`DefaultsAPI`	`defaults` `static`	The user defaults storage, shared by all emulator instances.

defaults

static

cpp

DefaultsAPI defaults

Type: DefaultsAPI

Defined in VAmiga.h:2471

The user defaults storage, shared by all emulator instances.

Public Static Methods

Return	Name	Description
`string`	`version` `static`	Returns a version string for this release.
`string`	`build` `static`	Returns a build-number string for this release.
`string`	`snapshotVersion` `static`	Returns a version string for the snapshot file format.

version

static

cpp

static string version()

Defined in VAmiga.h:2546

Returns a version string for this release.

build

static

cpp

static string build()

Defined in VAmiga.h:2550

Returns a build-number string for this release.

snapshotVersion

static

cpp

static string snapshotVersion()

Defined in VAmiga.h:2554

Returns a version string for the snapshot file format.

VAmiga ​

Public Attributes ​

amiga ​

agnus ​

ciaA ​

ciaB ​

cpu ​

denise ​

mem ​

paula ​

rtc ​

audioPort ​

controlPort1 ​

controlPort2 ​

serialPort ​

videoPort ​

df0 ​

df1 ​

df2 ​

df3 ​

hd0 ​

hd1 ​

hd2 ​

hd3 ​

keyboard ​

msgQueue ​

remoteManager ​

retroShell ​

df ​

hd ​

Public Methods ​

getInfo ​

getCachedInfo ​

getMetrics ​

getCachedMetrics ​

isPoweredOn ​

isPoweredOff ​

isPaused ​

isRunning ​

isSuspended ​

isHalted ​

isWarping ​

isTracking ​

checkReady ​

powerOn ​

Exceptions ​

powerOnAsync ​

powerOff ​

Exceptions ​

powerOffAsync ​

run ​

Exceptions ​

runAsync ​

Exceptions ​

pause ​

Exceptions ​

pauseAsync ​

hardReset ​

Exceptions ​

hardResetAsync ​

softReset ​

Exceptions ​

softResetAsync ​

halt ​

warpOn ​

Parameters ​

Exceptions ​

warpOnAsync ​

Exceptions ​

warpOff ​

Parameters ​

Exceptions ​

warpOffAsync ​

Exceptions ​

trackOn ​

Parameters ​

Exceptions ​

trackOnAsync ​

Exceptions ​

trackOff ​

VAmiga

Public Attributes

amiga

agnus

ciaA

ciaB

cpu

denise

mem

paula

rtc

audioPort

controlPort1

controlPort2

serialPort

videoPort

df0

df1

df2

df3

hd0

hd1

hd2

hd3

keyboard

msgQueue

remoteManager

retroShell

df

hd

Public Methods

getInfo

getCachedInfo

getMetrics

getCachedMetrics

isPoweredOn

isPoweredOff

isPaused

isRunning

isSuspended

isHalted

isWarping

isTracking

checkReady

powerOn

Exceptions

powerOnAsync

powerOff

Exceptions

powerOffAsync

run

Exceptions

runAsync

Exceptions

pause

Exceptions

pauseAsync

hardReset

Exceptions

hardResetAsync

softReset

Exceptions

softResetAsync

halt

warpOn

Parameters

Exceptions

warpOnAsync

Exceptions

warpOff

Parameters

Exceptions

warpOffAsync

Exceptions

trackOn

Parameters

Exceptions

trackOnAsync

Exceptions

trackOff