reflection

Documentation

Overview

Package reflection monitors the emulated hardware for conditions that would otherwise not be visible through normal emulation. The reflection system must be stepped every video cycle if all information is to be gathered.

Note that with regards to the debugger package, Step() is called manually from the input loop as appropriate. However, NewFrame() is handled by the television - the Reflector having been added as a FrameTrigger.

Index

• Variables
• type Broker
• type Hmove
• type Overlay
• type ReflectedInfo
• type ReflectedVideoStep
• type Reflector
  • func NewReflector(vcs *hardware.VCS) *Reflector
  • func (ref *Reflector) AddRenderer(renderer Renderer)
  • func (ref *Reflector) Clear()
  • func (ref *Reflector) NewFrame(_ television.FrameInfo) error
  • func (ref *Reflector) SetEmulationState(state govern.State)
  • func (ref *Reflector) Step(bank mapper.BankInfo) error
• type Renderer

Variables

var OverlayLabels = []string{"No overlay", "WSYNC", "Collisions", "HMOVE", "RSYNC", "Audio", "Coprocessor"}

OverlayLabels are names/labels for the the Policy type values.

Types

type Broker

type Broker interface {
	GetReflectionRenderer() Renderer
}

Broker implementations can identify a reflection.Renderer.

type Hmove

type Hmove struct {
	DelayCt  int
	Delay    bool
	Latch    bool
	RippleCt uint8
}

Hmove groups the HMOVE reflection information. It's too complex a property to distil into a single variable.

Ordering of the structure is important in order to keep memory usage at a minimum.

type Overlay

type Overlay int

Overlay is used to define the list of possible overlays that can be used to illustrate/visualise information in a ReflectedVideoStep instance.

We don't use this inside the reflection package itself but the type and associated values are useful and it makes sense to define them in this package.

const (
	OverlayNone Overlay = iota
	OverlayWSYNC
	OverlayCollision
	OverlayHMOVE
	OverlayRSYNC
	OverlayAudio
	OverlayCoproc
)

List of valid Overlay values.

type ReflectedInfo

type ReflectedInfo int

ReflectedInfo identifies specific information that has been reflected in a ReflectedVideoStep instance.

We don't use this inside the reflection package itself but the type and associated values are useful and it makes sense to define them in this package.

const (
	WSYNC ReflectedInfo = iota
	Collision
	CXCLR
	HMOVEdelay
	HMOVEripple
	HMOVElatched
	RSYNCalign
	RSYNCreset
	AudioPhase0
	AudioPhase1
	AudioChanged

	// for graphical purposes we only distinguish between active and inactive
	// coprocessor states. the underlying states as defined in the mapper
	// package (mapper.CoProcSynchronisation) are used to decided whether the
	// coproc is active or inactive
	CoProcInactive
	CoProcActive
)

List of valid ReflectedInfo values.

type ReflectedVideoStep

type ReflectedVideoStep struct {
	CPU          execution.Result
	Collision    video.Collisions
	Bank         mapper.BankInfo
	Signal       signal.SignalAttributes
	Hmove        Hmove
	VideoElement video.Element
	WSYNC        bool
	IsRAM        bool
	CoProcSync   coprocessor.CoProcSynchronisation
	IsHblank     bool
	RSYNCalign   bool
	RSYNCreset   bool
	AudioPhase0  bool
	AudioPhase1  bool
	AudioChanged bool
}

ReflectedVideoStep packages together the details of the the last video step that would otherwise be difficult for a debugger to access.

It includes the CPU execution result, the bank from which the instruction originates, the video element that produced the last video pixel on screen; among other information.

Note that ordering of the structure is important. There's a saving of about 2MB per frame compared to the unoptimal ordering.

type Reflector

type Reflector struct {
	// contains filtered or unexported fields
}

Reflector should be run (with the Check() function) every video cycle.

func NewReflector

func NewReflector(vcs *hardware.VCS) *Reflector

NewReflector is the preferred method of initialisation for the Monitor type.

func (*Reflector) AddRenderer

func (ref *Reflector) AddRenderer(renderer Renderer)

AddRenderer adds an implementation of the Renderer interface to the Reflector.

func (*Reflector) Clear

func (ref *Reflector) Clear()

Clear existing reflected information.

func (*Reflector) NewFrame

func (ref *Reflector) NewFrame(_ television.FrameInfo) error

NewFrame implements the television.FrameTrigger interface.

func (*Reflector) SetEmulationState

func (ref *Reflector) SetEmulationState(state govern.State)

SetEmulationState is called by the emulation whenever state changes. How we handle reflections depends on the current state.

func (*Reflector) Step

func (ref *Reflector) Step(bank mapper.BankInfo) error

Step should be called every video cycle to record a complete reflection of the system.

type Renderer

type Renderer interface {
	// Reflect is used to render a series of ReflectedVideoSteps. The number of
	// entries in the array will always be television.MaxSignalHistory.
	//
	// The layout of the ref array is roughly equivalent to the sig array sent
	// by PixelRenderer.SetPixels(). That is, the first entry always
	// corresponds to the top-left pixel.
	//
	// The array should be copied on reception (see note in the
	// ReflectedVideoStep type).
	Reflect(ref []ReflectedVideoStep) error
}

Renderer implementations display or otherwise process VideoStep values.