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 emulation.State)
  • func (ref *Reflector) Step(bank mapper.BankInfo) error
• type Renderer

Variables

var OverlayLabels = []string{"No overlay", "WSYNC", "Collisions", "HMOVE", "RSYNC", "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
	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
	CoprocessorActive
)

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
	CoprocessorActive bool
	IsHblank          bool
	RSYNCalign        bool
	RSYNCreset        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 emulation.State)

SetEmulationState is called by 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.
	//
	// It's important that implementations forget about and do not reference
	// any previous arrays as otherwise this will cause race errors with the
	// reflection package (which is probably running in a different thread).
	Reflect(ref []ReflectedVideoStep) error
}

Renderer implementations display or otherwise process VideoStep values.