emulation

Documentation

Overview

Package emulation is an abstraction of the various modes Gopher2600 can operate in, principally play-mode and the debugger.

It is useful when linking packages/types that require a *passive* knowledge of the emulation. For example, a GUI might want to know what the current state of the emulation is.

Some package types might still need an active knowledge of the emulation however. In which case, simply relying on the Emulation interface is probably not enough.

Index

• Constants
• type Debugger
• type Emulation
• type Event
• type FeatureReq
• type FeatureReqData
• type Mode
  • func (m Mode) String() string
• type State
• type TV
• type VCS

Constants

const (
	UnsupportedEmulationFeature = "unsupported emulation feature: %v"
)

Sentinal error returned if emulation does no support requested feature.

Types

type Debugger

type Debugger interface {
}

VCS is a minimal abstraction of the Gopher2600 debugger. Exists mainly to avoid a circular import to the debugger package.

The only likely implementation of this interface is the debugger.Debugger type.

type Emulation

type Emulation interface {
	TV() TV
	VCS() VCS
	Debugger() Debugger
	UserInput() chan userinput.Event

	// Send a request to set an emulation feature
	SetFeature(request FeatureReq, args ...FeatureReqData) error

	// Immediate request for the state and mode of the emulation
	State() State
	Mode() Mode
}

Emulation defines the public functions required for a GUI implementation (and possibly other things) to interface with the underlying emulator.

type Event

type Event int

Event describes an event that might occur in the emulation which is outside of the scope of the VCS. For example, when the emulation is paused an EventPause can be sent to the GUI (see FeatureReq type in the gui package).

const (
	EventInitialising Event = iota
	EventPause
	EventRun
	EventRewindBack
	EventRewindFoward
	EventRewindAtStart
	EventRewindAtEnd
	EventScreenshot
	EventMute
	EventUnmute
)

List of defined events.

type FeatureReq

type FeatureReq string

FeatureReq is used to request the setting of an emulation attribute eg. a pause request from the GUI

const (
	// notify gui of the underlying emulation mode.
	ReqSetPause FeatureReq = "ReqSetPause" // bool

	// change emulation mode
	ReqSetMode FeatureReq = "ReqSetMode" // emulation.Mode
)

List of valid feature requests. argument must be of the type specified or else the interface{} type conversion will fail and the application will probably crash.

Note that, like the name suggests, these are requests, they may or may not be satisfied depending on other conditions in the GUI.

type FeatureReqData

type FeatureReqData interface{}

FeatureReqData represents the information associated with a FeatureReq. See commentary for the defined FeatureReq values for the underlying type.

type Mode

type Mode int

Mode inidicates the broad features of the emulation. For example, Debugger indicates that the emulation is capable or is willing to handle debugging features.

const (
	ModeNone Mode = iota
	ModeDebugger
	ModePlay
)

List of defined modes.

func (Mode) String

func (m Mode) String() string

type State

type State int

State indicates the emulation's state.

const (
	EmulatorStart State = iota
	Initialising
	Paused
	Stepping
	Rewinding
	Running
	Ending
)

List of possible emulation states.

EmulatorStart is the default state and should never be entered once the emulator has begun.

Initialising can be used when reinitialising the emulator. for example, when a new cartridge is being inserted.

Values are ordered so that order comparisons are meaningful. For example, Running is "greater than" Stepping, Paused, etc.

* There is a sub-state of the rewinding state that we can think of as the "catch-up" state. This occurs in the brief transition period between Rewinding and the Running or Pausing state.

Currently, we handle this state in the CartUpLoop() function of the debugger package. There is a good argument to be made for having the catch-up state as a distinct State listed below.

type TV

type TV interface {
}

TV is a minimal abstraction of the TV hardware. Exists mainly to avoid a circular import to the hardware package.

The only likely implementation of this interface is the television.Television type.

type VCS

type VCS interface {
}

VCS is a minimal abstraction of the VCS hardware. Exists mainly to avoid a circular import to the hardware package.

The only likely implementation of this interface is the hardware.VCS type.