Public API. More...

#include <VirtualC64.h>

Public Member Functions
Analyzing the emulator
const EmulatorConfig &	getConfig () const
	Returns the component's current configuration.

const EmulatorInfo &	getInfo () const
	Returns the component's current state.

const EmulatorInfo &	getCachedInfo () const
	Returns the component's current configuration.

const EmulatorStats &	getStats () const
	Returns statistical information about the components.

Querying the emulator state
bool	isPoweredOn ()
	Returns true iff the emulator if the emulator is powered on.

bool	isPoweredOff ()
	Returns true iff the emulator if the emulator is powered off.

bool	isPaused ()
	Returns true iff the emulator is in paused state.

bool	isRunning ()
	Returns true iff the emulator is running.

bool	isSuspended ()
	Returns true iff the emulator has been suspended.

bool	isHalted ()
	Returns true iff the emulator has shut down.

bool	isWarping ()
	Returns true iff warp mode is active.

bool	isTracking ()
	Returns true iff the emulator runs in track mode.

void	isReady ()
	Checks if the emulator is runnable.

Controlling the emulator state
void	powerOn ()
	Switches the emulator on.

void	powerOff ()
	Switches the emulator off.

void	run ()
	Starts emulation.

void	pause ()
	Pauses emulation.

void	halt ()
	Terminates the emulator thread.

void	suspend ()
	Suspends the emulator thread.

void	resume ()
	Suspends the emulator thread.

void	warpOn (isize source=0)
	Enables warp mode.

void	warpOff (isize source=0)
	Disables warp mode.

void	trackOn (isize source=0)
	Enables track mode.

void	trackOff (isize source=0)
	Disables track mode.

Single-stepping
void	stepInto ()
	Steps a single instruction.

void	stepOver ()
	Steps over the current instruction.

Synchronizing the emulator thread
void	wakeUp ()
	Sends a wakeup signal to the emulator thread.

Configuring the emulator
void	launch (const void listener, Callback func)
	Launches the emulator thread.

i64	get (Option option) const
	Queries a configuration option.

i64	get (Option option, long id) const
	Queries a configuration option.

void	set (C64Model model)
	Configures the emulator to match a specific C64 model.

void	set (Option opt, i64 value) throws
	Configures a component.

void	set (Option opt, i64 value, long id)
	Configures a component.

void	exportConfig (const std::filesystem::path &path) const
	Exports the current configuration.

void	exportConfig (std::ostream &stream) const
	Launches the emulator thread.

Using the command queue
void	put (const Cmd &cmd)
	Feeds a command into the command queue.

void	put (CmdType type, i64 payload=0, i64 payload2=0)
	Feeds a command into the command queue.

void	put (CmdType type, ConfigCmd payload)
	Feeds a command into the command queue.

void	put (CmdType type, KeyCmd payload)
	Feeds a command into the command queue.

void	put (CmdType type, CoordCmd payload)
	Feeds a command into the command queue.

void	put (CmdType type, GamePadCmd payload)
	Feeds a command into the command queue.

void	put (CmdType type, TapeCmd payload)
	Feeds a command into the command queue.

void	put (CmdType type, AlarmCmd payload)
	Feeds a command into the command queue.

Static Public Member Functions
static string	version ()
	Returns a version string for this release.

static string	build ()
	eturns a build-number string for this release.

Static Public Attributes
static DefaultsAPI	defaults
	Custom APIs of subcomponents.

Detailed Description

Public API.

This class declares the emulator's public API. It consists of functions controlling the execution state, such as running or pausing the emulator, as well as functions configuring the various components. The class contains separate sub-APIs for the subcomponents of the emulator. For example, a VICII API provides additional functions that interact directly with the VICII graphics chip.

Member Function Documentation

◆ exportConfig() [1/2]

void exportConfig ( const std::filesystem::path & path ) const

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.

◆ exportConfig() [2/2]

void exportConfig ( std::ostream & stream ) const

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.

Parameters

listener	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	The callback function.

◆ get() [1/2]

i64 get ( Option option ) const

Queries a configuration option.

This is the main function to query a configuration option.

Parameters

option The option to query

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

◆ get() [2/2]

i64 get	(	Option	option,
		long	id ) const

Queries a configuration option.

This is the main function to query a configuration option.

Parameters

option	The option to query
id	The component to query

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

◆ halt()

void halt ( )

Terminates the emulator thread.

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

◆ isReady()

void isReady ( )

Checks if the emulator is runnable.

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

Exceptions

Error	(ERROR_ROM_BASIC_MISSING)
Error	(ERROR_ROM_CHAR_MISSING)
Error	(ERROR_ROM_KERNAL_MISSING)
Error	(ERROR_ROM_CHAR_MISSING)
Error	(ERROR_ROM_MEGA65_MISMATCH)

◆ launch()

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

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.

Parameters

listener	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	The callback function.

◆ pause()

void pause ( )

Pauses emulation.

Pausing the emulator changes the interal state from STATE_RUNNING to STATE_PAUSED after completing the curent frame. The emulator enteres a frozes state where no more frames are computed.

◆ powerOff()

void powerOff ( )

Switches the emulator off.

Powering off the emulator changes the interal state of STATE_OFF. Calling this function on an already powered-off emulator has no effect.

◆ powerOn()

void powerOn ( )

Switches the emulator on.

Powering on the emulator changes the interal state to STATE_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.

◆ resume()

void resume ( )

Suspends the emulator thread.

See the Suspendable class for a detailes description of the suspend-resume machanism.

◆ run()

void run ( )

Starts emulation.

Running the emulator changes the internal state to STATE_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 powere-off emulator, an implicit call to powerOn() will be performed.

◆ set() [1/3]

void set ( C64Model model )

Configures the emulator to match a specific C64 model.

Parameters

model The C64 model to emulate

◆ set() [2/3]

void set	(	Option	opt,
		i64	value )

Configures a component.

This is the main function to set an configuration option.

Parameters

opt	The option to set
value	The option's value

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

◆ set() [3/3]

void set	(	Option	opt,
		i64	value,
		long	id )

Configures a component.

This is the main function to set an configuration option.

Parameters

opt	The option to set
id	The component to configure
value	The option's value

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

◆ stepInto()

void stepInto ( )

Steps a single instruction.

If the emulator is paused, calling this functions steps the CPU for a single instruction. Otherwise, calling this function has no effect. The CPU debugger utilizes this function to implement single stepping.

◆ stepOver()

void stepOver ( )

Steps over the current instruction.

If the emulator is paused, calling this functions runs the emulator until the instruction following the current instruction has been reached. Otherwise, calling this function has no effect. 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 it's target location.

◆ suspend()

void suspend ( )

Suspends the emulator thread.

See the Suspendable class for a detailes description of the suspend-resume machanism.

◆ wakeUp()

void wakeUp ( )

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.

The documentation for this class was generated from the following files:

VirtualC64.h
VirtualC64.cpp

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Function Documentation

◆ exportConfig() [1/2]

◆ exportConfig() [2/2]

◆ get() [1/2]

◆ get() [2/2]

◆ halt()

◆ isReady()

◆ launch()

◆ pause()

◆ powerOff()

◆ powerOn()

◆ resume()

◆ run()

◆ set() [1/3]

◆ set() [2/3]

◆ set() [3/3]

◆ stepInto()

◆ stepOver()

◆ suspend()

◆ wakeUp()