AmigaAPI

#include <VAmiga.h>

class AmigaAPI

Defined in VAmiga.h:126

API of the Amiga as a whole.

Public Methods

Return	Name	Description
const AmigaConfig &	getConfig const	Returns the component's current configuration.
const AmigaInfo &	getInfo const	Returns the component's current state.
const AmigaInfo &	getCachedInfo const	Returns the most recent state snapshot recorded by the emulator thread (see getInfo()).
void	dump const	Prints debug information about the component.
bool	getMsg	Reads a message from the message queue.
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.
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.
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.

---

getConfig

const

const AmigaConfig & getConfig() const

Defined in VAmiga.h:139

Returns the component's current configuration.

---

getInfo

const

const AmigaInfo & getInfo() const

Defined in VAmiga.h:150

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 AmigaInfo & getCachedInfo() const

Defined in VAmiga.h:152

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 VAmiga.h:159

Prints debug information about the component.

Parameters

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

---

getMsg

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

Defined in VAmiga.h:172

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)

---

loadWorkspace

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

Defined in VAmiga.h:185

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 VAmiga.h:216

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. The asynchronous version uses the object on the emulator thread: it 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 VAmiga.h:193

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 VAmiga.h:218

Saves the workspace into an SVM that is already open.

---

saveWorkspaceAsync

const

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

Defined in VAmiga.h:203

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.

Parameters

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

---

saveWorkspaceAsync

const

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

Defined in VAmiga.h:220

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 VAmiga.h:233

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 VAmiga.h:239

Loads a snapshot.

Parameters

Parameter	Type	Description
snapshot	const Snapshot &	Reference to a snapshot

---

loadSnapshot

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

Defined in VAmiga.h:247

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 VAmiga.h:253

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 VAmiga.h:262

Saves a snapshot to disk.

Parameters

Parameter	Type	Description
path	const std::filesystem::path &	Destination path
compressor	utl::Compressor	Compression method

Exceptions

Exception	Description
Error	if the file cannot be written.

---

saveSnapshot

const

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

Defined in VAmiga.h:285

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. The asynchronous version uses the object on the emulator thread: it 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 VAmiga.h:273

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.

Parameters

Parameter	Type	Description
path	const std::filesystem::path &	Destination path
compressor	utl::Compressor	Compression method

---

saveSnapshotAsync

const

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

Defined in VAmiga.h:287

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 VAmiga.h:300

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. The GUI is told with a WORKSPACE_SAVED and a SNAPSHOT_SAVED message as soon as the respective part is done.

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 VAmiga.h:321

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. The asynchronous version uses it on the emulator thread: it must stay alive, and untouched, 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 VAmiga.h:309

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 at the end, which carries the exception if the operation failed.

---

hibernateAsync

const

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

Defined in VAmiga.h:323

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

---

getAutoInspectionMask

const

u64 getAutoInspectionMask() const

Defined in VAmiga.h:339

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 VAmiga.h:354

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 Paula: setAutoInspectionMask(1LL << long(Class::CIA) | 1LL << long(Class::Paula));

Parameters

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

---

setAutoInspectionMaskAsync

void setAutoInspectionMaskAsync(u64 mask)

Defined in VAmiga.h:357

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