Abstract base for an emulation core. More...

#include <emulator.hpp>

Classes
struct	inputEntry_t
	Pairs an input's string form with its decoded, emulator-specific input data. More...

Public Member Functions
	Emulator (const nlohmann::json &config)
	Constructs the emulator, performing only configuration parsing (for dry runs).

void	initialize ()
	Initializes the emulator instance.

InputSet::inputIndex_t	registerInput (const std::string inputString)
	Registers an input string, avoiding repeated decoding of the same input.

const inputEntry_t &	getRegisteredInput (const InputSet::inputIndex_t inputIdx) const
	Returns the information about a previously registered input.

void	advanceState (const InputSet::inputIndex_t input)
	Advances the emulator state by applying a registered input.

size_t	getStateSize () const
	Computes the serialized size of the emulator state.

bool	isInitialized () const
	Returns whether the emulator instance has been initialized.

std::string	getName () const
	Returns the emulator's configured name.

virtual void	initializeImpl ()=0
	Core-specific initialization, invoked by initialize.

virtual void	serializeState (jaffarCommon::serializer::Base &serializer) const =0
	Serializes the emulator state into the given serializer.

virtual void	deserializeState (jaffarCommon::deserializer::Base &deserializer)=0
	Deserializes the emulator state from the given deserializer.

virtual jaffar::InputParser *	getInputParser () const =0
	Returns a reference to the emulator's input parser.

virtual void	printInfo () const =0
	Prints core-specific debug information.

virtual property_t	getProperty (const std::string &propertyName) const =0
	Returns a memory property by name.

virtual void	initializeVideoOutput ()=0
	Opens the video output (e.g., window).

virtual void	finalizeVideoOutput ()=0
	Closes the video output (e.g., window).

virtual void	enableRendering ()=0
	Enables rendering within the emulation core (does not output it to screen).

virtual void	disableRendering ()=0
	Disables rendering within the emulation core (typically enables faster emulation).

virtual void	updateRendererState (const size_t stepIdx, const std::string input)=0
	Updates the internal state of the renderer with the current game state.

virtual void	serializeRendererState (jaffarCommon::serializer::Base &serializer) const =0
	Gathers the data needed to render a given state/frame into the serializer.

virtual void	deserializeRendererState (jaffarCommon::deserializer::Base &deserializer)=0
	Loads the renderer state for a given state/frame from the deserializer.

virtual size_t	getRendererStateSize () const =0
	Returns the size of the renderer state.

virtual void	showRender ()=0
	Shows the contents of the emulator's renderer in the window.

virtual void	saveScreenshot (const std::string &)
	Saves the currently-rendered frame to an image file at the given destination path.

Static Public Member Functions
static std::unique_ptr< Emulator >	getEmulator (const nlohmann::json &emulatorConfig)
	Constructs the emulator core selected by the configuration.

Protected Member Functions
virtual void	advanceStateImpl (const jaffar::input_t &input)=0
	Core-specific state advancement, invoked by advanceState.

void	finalizeEmulatorConfig ()
	Asserts that every key in the emulator configuration has been recognized.

Protected Attributes
std::string	_emulatorName
	Emulator name (for runtime use).

nlohmann::json	_emulatorConfigRemaining
	Mutable working copy of the emulator config; recognized keys are popped, leftovers are unrecognized. See finalizeEmulatorConfig().

bool	_isInitialized = false
	Whether the emulator has been initialized.

Private Attributes
std::vector< inputEntry_t >	_inputMap
	Maps an input id to its input data.

Detailed Description

Abstract base for an emulation core.

Defines the interface JaffarPlus uses to drive a guest system: initializing the core, registering and advancing inputs, serializing/deserializing emulator state, exposing guest memory as named property_t segments, and (optionally) rendering frames and saving screenshots. Concrete cores implement the pure-virtual *Impl and rendering hooks; getEmulator constructs the appropriate core from configuration.

Definition at line 39 of file emulator.hpp.

Constructor & Destructor Documentation

◆ Emulator()

jaffarPlus::Emulator::Emulator ( const nlohmann::json & config )

inline

Constructs the emulator, performing only configuration parsing (for dry runs).

Parameters

config Emulator configuration object; must contain the "Emulator Name" field.

Keeps a mutable working copy of config in _emulatorConfigRemaining and consumes (pops) the common keys it reads from it, so that a derived core can pop ITS own keys from the same copy and then call finalizeEmulatorConfig() to reject any leftover (unrecognized) key. Strict checking is opt-in: a core that does not call finalizeEmulatorConfig() is never checked, so unconverted cores keep working unchanged.

Definition at line 64 of file emulator.hpp.

Member Function Documentation

◆ advanceState()

void jaffarPlus::Emulator::advanceState ( const InputSet::inputIndex_t input )

inline

Advances the emulator state by applying a registered input.

Parameters

input The index of the registered input to apply.

Definition at line 122 of file emulator.hpp.

◆ advanceStateImpl()

virtual void jaffarPlus::Emulator::advanceStateImpl ( const jaffar::input_t & input )

protectedpure virtual

Core-specific state advancement, invoked by advanceState.

Parameters

input The decoded, emulator-specific input data to apply.

◆ deserializeRendererState()

virtual void jaffarPlus::Emulator::deserializeRendererState ( jaffarCommon::deserializer::Base & deserializer )

pure virtual

Loads the renderer state for a given state/frame from the deserializer.

Parameters

deserializer The deserializer to read the renderer state from.

◆ deserializeState()

virtual void jaffarPlus::Emulator::deserializeState ( jaffarCommon::deserializer::Base & deserializer )

pure virtual

Deserializes the emulator state from the given deserializer.

Parameters

deserializer The deserializer to read the emulator state from.

◆ finalizeEmulatorConfig()

void jaffarPlus::Emulator::finalizeEmulatorConfig ( )

inlineprotected

Asserts that every key in the emulator configuration has been recognized.

Call this at the END of a derived core's constructor, after it has consumed all of its own configuration keys (via the jaffarCommon::json::pop* helpers) from _emulatorConfigRemaining. The base ctor has already popped the common keys, so anything still present is an unrecognized key (a typo or unsupported option) and is reported by name. Cores that do not call this remain lenient (opt-in strict validation).

Definition at line 244 of file emulator.hpp.

◆ getEmulator()

static std::unique_ptr< Emulator > jaffarPlus::Emulator::getEmulator ( const nlohmann::json & emulatorConfig )

static

Constructs the emulator core selected by the configuration.

Parameters

emulatorConfig Emulator configuration object.

Returns: An owning pointer to the constructed emulator.

◆ getInputParser()

virtual jaffar::InputParser * jaffarPlus::Emulator::getInputParser ( ) const

pure virtual

Returns a reference to the emulator's input parser.

Returns: Pointer to the input parser owned by the core.

◆ getName()

std::string jaffarPlus::Emulator::getName ( ) const

inline

Returns the emulator's configured name.

Definition at line 139 of file emulator.hpp.

◆ getProperty()

virtual property_t jaffarPlus::Emulator::getProperty ( const std::string & propertyName ) const

pure virtual

Returns a memory property by name.

Parameters

propertyName The name of the property to look up.

Returns: The property's memory pointer and size.

◆ getRegisteredInput()

const inputEntry_t & jaffarPlus::Emulator::getRegisteredInput ( const InputSet::inputIndex_t inputIdx ) const

inline

Returns the information about a previously registered input.

Parameters

inputIdx The index of the registered input.

Returns: A reference to the registered input entry.

Definition at line 116 of file emulator.hpp.

◆ getRendererStateSize()

virtual size_t jaffarPlus::Emulator::getRendererStateSize ( ) const

pure virtual

Returns the size of the renderer state.

Returns: The size, in bytes, of the serialized renderer state.

◆ getStateSize()

size_t jaffarPlus::Emulator::getStateSize ( ) const

inline

Computes the serialized size of the emulator state.

Returns: The size, in bytes, of the serialized emulator state.

Definition at line 128 of file emulator.hpp.

◆ initialize()

void jaffarPlus::Emulator::initialize ( )

inline

Initializes the emulator instance.

Calls the core-specific initializeImpl and marks the instance as initialized.

Exceptions

A	logic error if the instance was already initialized.

Definition at line 77 of file emulator.hpp.

◆ isInitialized()

bool jaffarPlus::Emulator::isInitialized ( ) const

inline

Returns whether the emulator instance has been initialized.

Definition at line 136 of file emulator.hpp.

◆ registerInput()

InputSet::inputIndex_t jaffarPlus::Emulator::registerInput ( const std::string inputString )

inline

Registers an input string, avoiding repeated decoding of the same input.

If the input is already registered, returns its existing id; otherwise decodes it via the input parser and stores a new entry. Registration is linear O(n) to keep read access O(1).

Parameters

inputString The input string to register.

Returns: The index of the registered input entry.

Definition at line 95 of file emulator.hpp.

◆ saveScreenshot()

virtual void jaffarPlus::Emulator::saveScreenshot ( const std::string & )

inlinevirtual

Saves the currently-rendered frame to an image file at the given destination path.

Default: no-op (emulators without a screenshot backend simply ignore the request), so the player can request a screenshot emulator-agnostically. Overrides take the destination file path as their sole argument.

Definition at line 226 of file emulator.hpp.

◆ serializeRendererState()

virtual void jaffarPlus::Emulator::serializeRendererState ( jaffarCommon::serializer::Base & serializer ) const

pure virtual

Gathers the data needed to render a given state/frame into the serializer.

Parameters

serializer The serializer to write the renderer state into.

◆ serializeState()

virtual void jaffarPlus::Emulator::serializeState ( jaffarCommon::serializer::Base & serializer ) const

pure virtual

Serializes the emulator state into the given serializer.

Parameters

serializer The serializer to write the emulator state into.

◆ updateRendererState()

virtual void jaffarPlus::Emulator::updateRendererState	(	const size_t	stepIdx,
		const std::string	input
	)

pure virtual

Updates the internal state of the renderer with the current game state.

Parameters

stepIdx	The index of the step/frame being rendered.
input	The input string associated with the step/frame.

Member Data Documentation

◆ _emulatorConfigRemaining

nlohmann::json jaffarPlus::Emulator::_emulatorConfigRemaining

protected

Mutable working copy of the emulator config; recognized keys are popped, leftovers are unrecognized. See finalizeEmulatorConfig().

Definition at line 250 of file emulator.hpp.

◆ _emulatorName

std::string jaffarPlus::Emulator::_emulatorName

protected

Emulator name (for runtime use).

Definition at line 247 of file emulator.hpp.

◆ _inputMap

std::vector<inputEntry_t> jaffarPlus::Emulator::_inputMap

private

Maps an input id to its input data.

Definition at line 257 of file emulator.hpp.

◆ _isInitialized

bool jaffarPlus::Emulator::_isInitialized = false

protected

Whether the emulator has been initialized.

Definition at line 253 of file emulator.hpp.

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

emulator.hpp

Classes

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Emulator()

Member Function Documentation

◆ advanceState()

◆ advanceStateImpl()

◆ deserializeRendererState()

◆ deserializeState()

◆ finalizeEmulatorConfig()

◆ getEmulator()

◆ getInputParser()

◆ getName()

◆ getProperty()

◆ getRegisteredInput()

◆ getRendererStateSize()

◆ getStateSize()

◆ initialize()

◆ isInitialized()

◆ registerInput()

◆ saveScreenshot()

◆ serializeRendererState()

◆ serializeState()

◆ updateRendererState()

Member Data Documentation

◆ _emulatorConfigRemaining

◆ _emulatorName

◆ _inputMap

◆ _isInitialized