C64API

#include <VirtualC64.h>

class C64API

Defined in VirtualC64.h:1739

C64 API

Public Methods

Return	Name	Description
const C64Config &	getConfig const	Returns the component's current configuration.
const C64Info &	getInfo const	Returns the component's current state.
const C64Info &	getCachedInfo const	Returns the most recent state snapshot recorded by the emulator thread (see getInfo()).
void	dump const	Prints debug information about the component.
RomTraits	getRomTraits const	Returns information about one of the installed Roms.
bool	getMsg	Reads a message from the message queue.
u64	getAutoInspectionMask const	Gets the current auto-inspection mask The GUI utilizes Auto-Inspection to display life updates of the internal emulator state in the Inspector panel. As soon as an auto-inspection mask is set, the emulator caches the internal states of the inspected components at periodic intervals. The inspected components are specified as a bit mask.
void	setAutoInspectionMask	Sets the current auto-inspection mask.
void	setAutoInspectionMaskAsync	Asynchronous version of setAutoInspectionMask(): queues the request and returns at once.
void	loadWorkspace	Loads a workspace.
void	loadWorkspace	Loads, saves, or asynchronously saves the workspace of an SVM.
void	saveWorkspace const	Saves a workspace to disk.
void	saveWorkspace const	Saves the workspace into an SVM that is already open (see loadWorkspace()).
void	saveWorkspaceAsync const	Saves a workspace to disk asynchronously.
void	saveWorkspaceAsync const	Asynchronous version of saveWorkspace(): queues the request and returns at once.
std::unique_ptr< Snapshot >	takeSnapshot	Takes a snapshot.
void	loadSnapshot	Loads a snapshot.
void	loadSnapshot	Loads a snapshot.
void	loadSnapshotAsync	Asynchronous version of loadSnapshot(): queues the request and returns at once.
void	saveSnapshot const	Saves a snapshot to disk.
void	saveSnapshot const	Saves a snapshot, including a screenshot, into an SVM.
void	saveSnapshotAsync const	Saves a snapshot to disk asynchronously.
void	saveSnapshotAsync const	Asynchronous version of saveSnapshot(): queues the request and returns at once.
void	hibernate const	Hibernates the machine into a virtual machine bundle.
void	hibernate const	Hibernates the machine into an SVM that is already open.
void	hibernateAsync const	Hibernates the machine asynchronously.
void	hibernateAsync const	Asynchronous version of hibernate(): queues the request and returns at once.
void	loadRom	Loads a ROM from a file The ROM type is determined automatically.
void	loadRom	Loads a ROM from a file and installs it as the given ROM type.
void	loadRomAsync	Asynchronous version of loadRom(): queues the request and returns at once.
void	loadRomAsync	Asynchronous version of loadRom(path, rom).
void	deleteRom	Removes an installed ROM The ROM contents is overwritten with zeroes.
void	deleteRoms	Removes all installed ROMs including the floppy drive ROMs. The ROM contents is overwritten with zeroes.
void	saveRom	Saves a ROM to disk.
void	installOpenRom	Installes a MEGA65 OpenRom.
void	installOpenRoms	Install all three MEGA65 OpenROMs.
void	flash	Flashes a file into memory.
void	flashAsync	Asynchronous version of flash(): queues the request and returns at once.

---

getConfig

const

const C64Config & getConfig() const

Defined in VirtualC64.h:1752

Returns the component's current configuration.

---

getInfo

const

const C64Info & getInfo() const

Defined in VirtualC64.h:1763

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

const C64Info & getCachedInfo() const

Defined in VirtualC64.h:1765

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

---

dump

const

void dump(Category category, std::ostream & os) const

Defined in VirtualC64.h:1772

Prints debug information about the component.

Parameters

Parameter	Type	Description
category	Category	Debug information category
os	std::ostream &	Output stream

---

getRomTraits

const

RomTraits getRomTraits(RomType type) const

Defined in VirtualC64.h:1778

Returns information about one of the installed Roms.

Parameters

Parameter	Type	Description
type	RomType	The ROM type

---

getMsg

bool getMsg(Message & msg, std::exception_ptr & exception)

Defined in VirtualC64.h:1791

Reads a message from the message queue.

Returns

True if a message could be read, false if the queue was empty

Parameters

Parameter	Type	Description
msg	Message &	The returned message (if any)
exception	std::exception_ptr &	The exception the message reports (null if none)

---

getAutoInspectionMask

const

u64 getAutoInspectionMask() const

Defined in VirtualC64.h:1807

Gets the current auto-inspection mask The GUI utilizes Auto-Inspection to display life updates of the internal emulator state in the Inspector panel. As soon as an auto-inspection mask is set, the emulator caches the internal states of the inspected components at periodic intervals. The inspected components are specified as a bit mask.

Returns

A bit mask indicating the components under inspection

---

setAutoInspectionMask

void setAutoInspectionMask(u64 mask)

Defined in VirtualC64.h:1822

Sets the current auto-inspection mask.

Each bit selects one component class (the bit position is the numeric value of the Class entry). A component's getCachedInfo() and getCachedMetrics() only return up-to-date snapshots while its class is selected.

Example: The following call enables auto-inspections for the CIA chips and the CPU: setAutoInspectionMask(1LL << long(Class::CIA) | 1LL << long(Class::CPU));

Parameters

Parameter	Type	Description
mask	u64	A bit mask indicating the components under inspection

---

setAutoInspectionMaskAsync

void setAutoInspectionMaskAsync(u64 mask)

Defined in VirtualC64.h:1825

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

---

loadWorkspace

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

Defined in VirtualC64.h:1838

Loads a workspace.

Parameters

Parameter	Type	Description
path	const std::filesystem::path &	Path to a workspace folder

Exceptions

Exception	Description
Error	if the file cannot be read or does not contain valid data.

---

loadWorkspace

void loadWorkspace(retro::vault::SVMFile & svm)

Defined in VirtualC64.h:1870

Loads, saves, or asynchronously saves the workspace of an SVM.

These work on the workspace folder of an SVM that is already open. Saving replaces the workspace, notes its preview image in the manifest and persists the SVM. As with hibernateAsync, the object is used on the emulator thread and must stay alive, and untouched, until the WORKSPACE_SAVED message has arrived.

Exceptions

Exception	Description
Error	if the SVM file cannot be read or written, or if its content is invalid (synchronous versions).

---

saveWorkspace

const

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

Defined in VirtualC64.h:1846

Saves a workspace to disk.

Parameters

Parameter	Type	Description
path	const std::filesystem::path &	Destination path

Exceptions

Exception	Description
Error	if the file cannot be written.

---

saveWorkspace

const

void saveWorkspace(retro::vault::SVMFile & svm) const

Defined in VirtualC64.h:1872

Saves the workspace into an SVM that is already open (see loadWorkspace()).

---

saveWorkspaceAsync

const

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

Defined in VirtualC64.h:1857

Saves a workspace to disk asynchronously.

The request is handed to the emulator thread, which carries it out when it processes its command queue. The function returns immediately. The GUI is informed by a WORKSPACE_SAVED message, which carries an exception if the operation failed.

Parameters

Parameter	Type	Description
path	const std::filesystem::path &	Destination path

---

saveWorkspaceAsync

const

void saveWorkspaceAsync(retro::vault::SVMFile & svm) const

Defined in VirtualC64.h:1874

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

---

takeSnapshot

std::unique_ptr< Snapshot > takeSnapshot(utl::Compressor compressor, isize delay = 0, bool repeat = false)

Defined in VirtualC64.h:1887

Takes a snapshot.

Returns

A pointer to the created Snapshot object.

NOTE

The function transfers the ownership to the caller. It is his responsibility of the caller to free the object.

Parameters

Parameter	Type	Description
compressor	utl::Compressor	The snapshot compression method
delay	isize	Optional delay in seconds
repeat	bool	if true, snapshots are taken continuously

---

loadSnapshot

void loadSnapshot(const Snapshot & snapshot)

Defined in VirtualC64.h:1893

Loads a snapshot.

Parameters

Parameter	Type	Description
snapshot	const Snapshot &	Reference to a snapshot

---

loadSnapshot

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

Defined in VirtualC64.h:1901

Loads a snapshot.

Parameters

Parameter	Type	Description
path	const std::filesystem::path &	Source path

Exceptions

Exception	Description
Error	if the file cannot be read or does not contain valid data.

---

loadSnapshotAsync

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

Defined in VirtualC64.h:1907

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

Success and failure are both reported by the usual message (SNAPSHOT_RESTORED). If the request failed, the message carries the exception.

---

saveSnapshot

const

void saveSnapshot(const std::filesystem::path & path, utl::Compressor compressor) const

Defined in VirtualC64.h:1916

Saves a snapshot to disk.

Parameters

Parameter	Type	Description
path	const std::filesystem::path &	Destination path
compressor	utl::Compressor	The compression method applied to the snapshot data.

Exceptions

Exception	Description
Error	if the file cannot be written.

---

saveSnapshot

const

void saveSnapshot(retro::vault::SVMFile & svm, utl::Compressor compressor) const

Defined in VirtualC64.h:1941

Saves a snapshot, including a screenshot, into an SVM.

Works on an SVM that is already open: the snapshot is added to its manifest, and the SVM is persisted. As with hibernateAsync, the object is used on the emulator thread by the asynchronous version and must stay alive, and untouched, until the SNAPSHOT_SAVED message has arrived.

Exceptions

Exception	Description
Error	if the SVM file cannot be read or written, or if its content is invalid (synchronous versions).

---

saveSnapshotAsync

const

void saveSnapshotAsync(const std::filesystem::path & path, utl::Compressor compressor) const

Defined in VirtualC64.h:1928

Saves a snapshot to disk asynchronously.

The request is handed to the emulator thread, which carries it out when it processes its command queue. The function returns immediately. The GUI is informed by a SNAPSHOT_SAVED message, which carries an exception if the operation failed.

Parameters

Parameter	Type	Description
path	const std::filesystem::path &	Destination path
compressor	utl::Compressor	The compression method applied to the snapshot data.

---

saveSnapshotAsync

const

void saveSnapshotAsync(retro::vault::SVMFile & svm, utl::Compressor compressor) const

Defined in VirtualC64.h:1943

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

---

hibernate

const

void hibernate(const std::filesystem::path & path, bool snapshot, bool workspace) const

Defined in VirtualC64.h:1955

Hibernates the machine into a virtual machine bundle.

Saves the workspace (if workspace is true) and a snapshot including a screenshot (if snapshot is true) into the SVM, and updates its manifest.

Parameters

Parameter	Type	Description
path	const std::filesystem::path &	Path of the SVM
snapshot	bool	Save a snapshot
workspace	bool	Save the workspace

---

hibernate

const

void hibernate(retro::vault::SVMFile & svm, bool snapshot, bool workspace) const

Defined in VirtualC64.h:1976

Hibernates the machine into an SVM that is already open.

Works like the versions that take a path, but updates and persists the given object, so its manifest is current afterwards. The asynchronous version uses the object on the emulator thread: it must stay alive and must not be touched until the HIBERNATED message has arrived.

Exceptions

Exception	Description
Error	if the SVM file cannot be read or written, or if its content is invalid (synchronous versions).

---

hibernateAsync

const

void hibernateAsync(const std::filesystem::path & path, bool snapshot, bool workspace) const

Defined in VirtualC64.h:1964

Hibernates the machine asynchronously.

The request is handed to the emulator thread, which carries it out when it processes its command queue. The function returns immediately. The GUI is informed by a HIBERNATED message, which carries an error code and description if the operation failed.

---

hibernateAsync

const

void hibernateAsync(retro::vault::SVMFile & svm, bool snapshot, bool workspace) const

Defined in VirtualC64.h:1978

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

---

loadRom

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

Defined in VirtualC64.h:1990

Loads a ROM from a file The ROM type is determined automatically.

Exceptions

Exception	Description
Error	if the file cannot be read or does not contain valid data.

---

loadRom

void loadRom(const std::filesystem::path & path, RomType rom)

Defined in VirtualC64.h:1992

Loads a ROM from a file and installs it as the given ROM type.

---

loadRomAsync

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

Defined in VirtualC64.h:1998

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

Success and failure are both reported by a ROM_LOADED message. If the request failed, the message carries the exception.

---

loadRomAsync

void loadRomAsync(const std::filesystem::path & path, RomType rom)

Defined in VirtualC64.h:2000

Asynchronous version of loadRom(path, rom).

---

deleteRom

void deleteRom(RomType type)

Defined in VirtualC64.h:2005

Removes an installed ROM The ROM contents is overwritten with zeroes.

---

deleteRoms

void deleteRoms()

Defined in VirtualC64.h:2010

Removes all installed ROMs including the floppy drive ROMs. The ROM contents is overwritten with zeroes.

---

saveRom

void saveRom(const std::filesystem::path & path, RomType rom)

Defined in VirtualC64.h:2016

Saves a ROM to disk.

Exceptions

Exception	Description
Error	if the file cannot be written.

---

installOpenRom

void installOpenRom(RomType type)

Defined in VirtualC64.h:2020

Installes a MEGA65 OpenRom.

---

installOpenRoms

void installOpenRoms()

Defined in VirtualC64.h:2024

Install all three MEGA65 OpenROMs.

---

flash

void flash(const std::filesystem::path & path, isize item = 0)

Defined in VirtualC64.h:2033

Flashes a file into memory.

---

flashAsync

void flashAsync(const std::filesystem::path & path, isize item = 0)

Defined in VirtualC64.h:2040

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

The file is read on the emulator thread. Success and failure are both reported by the usual message (e.g., CRT_ATTACHED). If the request failed, the message carries the exception.