television

type AudioMixer interface {
	SetAudio(audioData uint8) error

	// some mixers may need to conclude and/or dispose of resources gently.
	// for simplicity, the AudioMixer should be considered unusable after
	// EndMixing() has been called
	EndMixing() error
}

type ColorSignal int

type FrameResizeID string

type PixelRenderer interface {
	// Resize is called when the television implementation detects that extra
	// scanlines are required in the display.
	//
	// It may be called when television specification has changed. As a point
	// of convenience a reference to the currently selected specification is
	// provided. However, renderers should call GetSpec() rather than keeping a
	// private pointer to the specification, if knowledge of the spec is
	// required after the Resize() event.
	//
	// Renderers should use the values sent by the Resize() function, rather
	// than the equivalent values in the specification. Unless of course, the
	// renderer is intended to be strict about specification accuracy.
	//
	// Renderers should make sure that any data structures that depend on the
	// specification being used are still adequate.
	Resize(spec *Specification, topScanline, visibleScanlines int) error

	// NewFrame and NewScanline are called at the start of the frame/scanline
	NewFrame(frameNum int, isStable bool) error
	NewScanline(scanline int) error

	// setPixel() is called every cycle regardless of the state of VBLANK and
	// HBLANK.
	//
	// things to consider:
	//
	// o the x argument is measured from zero so renderers should decide how to
	//	handle pixels of during the HBLANK (x < ClocksPerHBLANK)
	//
	// o the y argument is also measured from zero but because VBLANK can be
	//	turned on at any time there's no easy test. the VBLANK flag is sent to
	//	help renderers decide what to do.
	//
	// o for renderers that are producing an accurate visual image, the pixel
	//	should always be set to video black if VBLANK is on.
	//
	//	some renderers however, may find it useful to set the pixel to the RGB
	//	value regardless of VBLANK. for example, DigestTV does this.
	//
	//	a vey important note is that some ROMs use VBLANK to control pixel
	//	color within the visible display area. ROMs affected:
	//
	//	* Custer's Revenge
	//	* Ladybug
	//	* ET (turns VBLANK off late on scanline 40)
	//
	SetPixel(x, y int, red, green, blue byte, vblank bool) error

	// some renderers may need to conclude and/or dispose of resources gently.
	// for simplicity, the PixelRenderer should be considered unusable after
	// EndRendering() has been called
	EndRendering() error
}

type SignalAttributes struct {
	VSync     bool
	VBlank    bool
	CBurst    bool
	HSync     bool
	Pixel     ColorSignal
	AudioData uint8

	// which equates to 30Khz
	AudioUpdate bool
}

type Specification struct {
	ID     string
	Colors []color.RGBA

	// the number of scanlines the 2600 Programmer's guide recommends for the
	// top/bottom parts of the screen:
	//
	// "A typical frame will consists of 3 vertical sync (VSYNC) lines*, 37 vertical
	// blank (VBLANK) lines, 192 TV picture lines, and 30 overscan lines. Atari’s
	// research has shown that this pattern will work on all types of TV sets."
	//
	// the above figures are in reference to the NTSC protocol
	ScanlinesVSync int

	ScanlinesVisible  int
	ScanlinesOverscan int

	// the total number of scanlines for the entire frame is the sum of the
	// four individual portions
	ScanlinesTotal int

	// the scanline at which the VBLANK should be turned off (Top) and
	// turned back on again (Bottom). the period between the top and bottom
	// scanline is the visible portion of the screen.
	//
	// in practice, the VCS can turn VBLANK on and off at any time; what the
	// two values below represent what "Atari's research" has shown to be safe.
	// by definition this means that:
	//
	//	Top = VSync + Vblank
	//
	//	Bottom = Top + Visible
	//
	// or
	//
	//	Bottom = Total - Overscan
	ScanlineTop    int
	ScanlineBottom int

	// AaspectBias transforms the scaling factor for the X axis.
	// values taken from Stella emualtor. useful for A/B testing
	AspectBias float32

	// the number of frames per second required by the specification
	FramesPerSecond float32
	// contains filtered or unexported fields
}

type StateReq int

type Television interface {
	String() string

	// Reset the television to an initial state
	Reset() error

	// AddPixelRenderer registers an (additional) implementation of PixelRenderer
	AddPixelRenderer(PixelRenderer)

	// AddAudioMixer registers an (additional) implementation of AudioMixer
	AddAudioMixer(AudioMixer)

	Signal(SignalAttributes) error

	// Returns the value of the requested state. eg. the current scanline.
	GetState(StateReq) (int, error)

	// Set the television's specification
	SetSpec(spec string) error

	// Returns the television's current specification. Renderers should use
	// GetSpec() rather than keeping a private pointer to the specification.
	GetSpec() (*Specification, bool)

	// IsStable returns true if the television thinks the image being sent by
	// the VCS is stable
	IsStable() bool

	// some televisions may need to conclude and/or dispose of resources
	// gently. implementations of End() should call EndRendering() and
	// EndMixing() on each PixelRenderer and AudioMixer that has been added.
	//
	// for simplicity, the Television should be considered unusable
	// after EndRendering() has been called
	End() error

	// SpecIDOnCreation() returns the string that was to ID the television
	// type/spec on creation. because the actual spec can change, the ID field
	// of the Specification type can not be used for things like regression
	// test recreation etc.
	//
	// we use this to help recreate the television that was used to make a
	// playback recording. we may need to expand on this (and maybe replace
	// with a more generalised function) if we ever add another television
	// implementation.
	SpecIDOnCreation() string

	// Set whether the emulation should wait for FPS limiter
	SetFPSCap(set bool)

	// Request the number frames per second. This overrides the frame rate of
	// the specification. A negative FPS value restores the specifcications
	// frame rate.
	//
	// Note that this is only a request, the emulation may not be able to
	// achieve that rate.
	SetFPS(fps float32)

	// The requested number of frames per second. Compare with GetActualFPS()
	// to check for accuracy
	GetReqFPS() float32

	// The current number of frames per second
	GetActualFPS() float32

	// Returns a copy of SignalAttributes for reference
	GetLastSignal() SignalAttributes
}