specification

type Rotation int

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

	// the nominal refresh rate for the specification. this refresh rate will
	// be produced if the actual number of scanlines per frame is the same as
	// OptimalTotal defined below.
	RefreshRate float32

	// 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 quoted figures above are in reference to the NTSC protocol
	ScanlinesVSync    int
	ScanlinesVBlank   int
	ScanlinesVisible  int
	ScanlinesOverscan int

	// the optimal number of total scanlines for the entire frame. is the sum of
	// the four regions defined above.
	//
	// if the actual TV frame has a different number than this then the refresh
	// rate will not be optimal.
	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" (according to page 1
	// of the "Stella Programmer's Guide") has shown to be safe. by definition
	// this means that:
	//
	//	Top = VSync + Vblank
	//
	//	Bottom = Top + Visible
	//
	// or
	//
	//	Bottom = Total - Overscan
	AtariSafeVisibleTop    int
	AtariSafeVisibleBottom int

	// resizing of the TV is problematic because we can't rely on the VBLANK to
	// tell us when the pixels are meant to be in view. The NewSafeVisibleTop an
	// SafeBottom are the min/max values that the resizer should allow.
	//
	// think of these as the "modern" safe values as compared to the Atari
	// defined safe values.
	NewSafeVisibleTop    int
	NewSafeVisibleBottom int
}