Vector / Oscilloscope / CRT Display
–––––––––––––––––––––––––––––––––––

unscaled display area:		255 x 255 pixel		(-127 … +127)
maximum display area:		1k x 1k				(10 bit DACs)
ram for drawing commands:	8k x 16 bit			(shared memory with host)
drawing speed:				6,000,000 pixel/s	(raw speed, may vary)
							60,000 lines/s		(approximately)

The vector drawing display is split into two logical parts:
The computer (maybe a terminal) which stores data in a video ram
and the CRTC which reads data from the video ram and draws the frames.
Writing to and reading from the video ram is asynchronous.

The image can be scaled, distorted and rotated in hardware.
The display has 255 x 255 'pixels'.
HW and SW scaling can be used to achieve 2x or 4x resolution.



CRTC
––––

The drawing engine reads drawing commands from the video ram and draws lines at a fixed speed.

Drawing speed: (estimation)

The drawing engine CRTC is clocked at 6 MHz.
Raw drawing speed is 1 pixel every 1 clock cycles (6,000,000 pixels per second).
Each ram (2 bytes) read takes 6 clock cycles.
This results in approx. 60,000 lines per second or 1,000 lines per frame of 1/60 second.
As the drawing engine draws _pixels_ at a fixed speed, the number of lines per second decreases with higher HW resolution.


Registers:

Host-accessible registers are used to set HW scaling and the start address of a frame.
The four 1-bit flags are part of each drawing 'control' command.

			Width	After		Host
  Name		[bits]	reset		r/w		Description
  –––––––––	–––––––	–––––––––––	–––––––	––––––––––––––––––––––––––––––
  a,b,c,d	8  x 4	undefined	-/w		HW scaling (transformation)
  A			13		undefined	-/w		address register (program counter)
  RR		13 x 2	undefined	-/-		return stack (2 levels)
  X, Y		10 x 2	undefined	-/-		beam position (DAC input values)
  xx, yy	2  x 2 	0, 0		-/-		SW scaling (width and height)
  R 		1		0			-/-		addressing mode (0=absolute / 1=relative)
  C			1		0			-/-		cathode ray beam enable
  I			1		0			-/-		interrupt enable
  E			1		0			-/-		clock enable


Register 'E': Clock enable

This bit can only be cleared in control commands. All control commands must set this bit to 1. If a control command clears this bit, then the CRTC clock is stopped and, depending on the setting of bit 'I' in the same command, an interrupt is generated. The only time stopping the clock is desired is at the end of a frame. Then a NOP with E=0 is executed, which is called 'end of frame'.


Register 'I': 'end of frame' interrupt enable

This bit can only be set in control commands. Some commands change this bit accidentially. It only takes effect if a command also stops the CRTC clock, which is done at the end of a frame:
If the clock is stopped and bit 'I' is set, then the CRTC issues an interrupt. The interrupt will persist until the CRTC clock is restarted by writing a starting address into register 'A'.


Register 'C': Cathode ray beam enable

This bit is set by all line drawing commands, and it can only be cleared in control commands.
Bit 'C' switches the cathode ray beam on or off for the _next_ command. Normally line drawing commands draw lines. But if a line drawing command is prefixed with a NOP (or other control command) which switches off the beam, then it will only move the current drawing position.


Register 'R': Addressing mode

This bit can only be set in control commands. Coordinates (dx,dy) in all following line drawing commands are 'absolute' (R=0) or 'relative' (R=1).


Register xx and yy: Software scaling

These bits can only be set in a special control command. Software scaling can be programmed separately for width and height. SW scaling can be used to compensate HW scaling and, starting from the HW zoom factor, to draw at a higher resolution or to draw enlarged symbols and letters.

Coordinates (dx,dy) in all following line drawing commands are scaled to (dx<<xx,dy<<yy).

HW scaling can be set to 1/2 or 1/4 to increase resolution. To compensate this,
SW scaling can be set to 1*2 or 1*4 as one of the first commands after start of each frame.
Then seemingly nothing changed, but now you can switch to lower SW scaling for fine drawing.
SW scaling can also be used to draw larger versions of characters or symbols.
Recommendation: HW scaling should be set to 1/2 or 1/4 and SW scaling to 1*2 or 1*4.


Registers a,b,c,d: Hardware scaling and rotation

The 'hardware transformation' is programmed with 4 signed byte values.

The display is distorted according to these formulas:

	Vx = X*a/120 + Y*b/120
	Vy = X*c/120 + Y*d/120

By this the image can be scaled, flipped, distorted and rotated in hardware.
This can be used to compensate display errors on a real device or for effects.
The unscaled image is best for rotating or distorting the screen.

The X/Y amplification can be lowered to 1/2 or 1/4 to achieve a higher resolution.
This can be compensated by setting the SW scaling to 1*2 or 1*4 at the start of each frame.
Then seemingly nothing changed, but now you can switch to lower SW scaling for fine drawing.

Program values for registers a, b, c and d for an undistorted image:

	a=120, b=0, c=0, d=120		unscaled: X/Y = [-127 … +127]
	a=60,  b=0, c=0, d=60		1*2:      X/Y = [-254 … +254]
	a=30,  b=0, c=0, d=30		1*4:      X/Y = [-508 … +508]

If you don't want to rotate or distort the image, then setting HW scaling to 1/2 or 1/4 and SW scaling to 1*2 or 1*4 is recommended. This allows fine drawing with a lower SW scaling factor and magnification e.g. of letters if the SW scaling factor is raised. Beware, that setting HW scaling to 1/2 or 1/4 increases the number of pixels to be drawn for each line: This is directly related to the maximum number of lines per frame!


Register 'X' and 'Y': CRT beam position (DACs)

Two 10-bit registers contain the current x and y position of the CRT beam. These registers should be attached to the inputs of two DACs which generate the control voltage for the x and y plate of the CRT.


Register 'A': Address counter

The address counter is used by the drawing engine to read drawing commands from the video ram.
Writing to register 'A' restarts the drawing engine at the new address. This is required after each frame to start drawing the next frame.


Registers 'RR': Return stack

The drawing engine has a 2-level return stack. The return stack is not accessible by the host.


Reset:

Registers xx, yy, R, C, I and E are set to 0.
All other registers start with arbitrary values.

→ xx, yy: Software scaling is set to 1x1.
→ R: 	  Addressing mode in line drawing commands = absolute.
→ C:	  The cathode ray beam is switched off.
→ I:	  No interrupt is generated while the clock is disabled.
→ E:	  The clock is disabled: the drawing engine is stopped.

• The host should set the HW scaling registers a,b,c and d.
• Then it may write frame data into the video ram and start a frame by writing
  the start address into register A.


Frame start:

Writing to register 'A' restarts the drawing engine at the new address. This is required after each frame to start drawing the next frame. If the drawing engine was still busy, then drawing of the old frame is interrupted and aborted.


Drawing:

The drawing engine reads drawing commands from the video ram and draws lines at a fixed speed.
Reading a word from video ram takes 6 clock cycles and drawing is done at a speed of 1 pixel per clock cycle. This results in an overall performance of approx. 1000 lines / frame at 60 fps at 1*1 HW scaling.

dx and dy coordinates in drawing commands are signed bytes in range -127 … +127 and can be either absolute or relative depending on the current setting of register 'R'. The coordinates are multiplied with 1, 2, 4 or 8 (shifted left by 0, 1, 2 or 3) depending on register xx and yy.

Normally, this draws a line from the 'current position' to the new position.

Drawing may exceed the visible screen. The X and Y coordinate counters are 10 bit wide, (actually, the DACs are assumed to have a resolution of 10 bits) providing a 1k by 1k virtual drawing area. If drawing exceeds this area, the effect is not defined. Basically coordinates will wrap.

If dx = 128 then this is a 'control command'.


Special cases:
––––––––––––––

• The CRT beam is switched off:
  The CRT beam can be switched off by 'control commands'. Then the next command,
  if it is a line drawing command, will only move to the new position without actually drawing.
  Moving to the new position is 'immediate' and takes no time (as for drawing pixels).

• dx = 128: 'Control command'
  Then dy is the 'command'. Unused bits should be set to 0.

The lower 4 bits _always_ set the registers 'I' (interrupt enable), 'E' (clock enable), 'R' (relative addressing mode) and 'C' (cathode ray beam enable). Obviously 'E' should normally always be set, 'I' does not matter if 'E' is set and 'R' and 'C' must be set as desired.

• dy = %000.I0RC: End of frame
• dy = %000..1RC: No operation
• dy = %001..1RC: Call subroutine
• dy = %010..1RC: Return from subroutine
• dy = %011..1RC: undefined
• dy = %1xxyy1RC: set SW scaling for width and height


• dy = %000.I0RC: End of frame

  If bit 2 ('E') is cleared, then the CRTC clock is stopped and, if bit 3 ('I') is also set,
  an interrupt is issued.
  Bit 0 ('C') should be cleared to switch of the cathode ray beam.
  Bit 1 ('R') will have effect to the first command of the next frame.
  The high bits should be set to %000 (NOP). Any other combination will have side effects
  according to the chosen command. Especially don't use %001 ('call').


• dy = %000..1RC: No operation
  Set absolute or relative addressing mode and switch on or off the CRT beam.


• dy = %001..1RC: Call subroutine
  The drawing engine has a 'stack' for 2 return addresses. Typical use of subroutines is
  for drawing letters. The current program position is pushed on this stack and the next word
  is loaded into the program counter. Unused upper bits of the address should be set to 0.

  If not in a subroutine:
  A jump can be performed by "call subroutine" and ignoring the return address.


• dy = %010..1RC: Return from subroutine
  The program counter is popped from the return address stack.


• dy = %1xxyy1RC: Set software scaling:
  Set width and height scaling
  Valid until changed.

  Coordinates (dx,dy) in all following drawing commands are scaled to (dx<<xx,dy<<yy).

  HW scaling can be set to 1/2 or 1/4 to increase resolution. To compensate this,
  SW scaling can be set to 1*2 or 1*4 as one of the first commands after start of each frame.
  Then seemingly nothing changed, but now you can switch to lower SW scaling for fine drawing.
  SW scaling can also be used to draw larger versions of characters or symbols.


Computer (Host)
–––––––––––––––

The computer writes display data into a video ram, which is read by the CRTC.
The computer may be a terminal, which receives drawing commands and data over a serial line.


Reset:

• Set the hardware transformation registers a, b, c and d.
• Store subroutines, e.g. for drawing letters, into the video ram.
  (the MMU may map parts of the ROM into the vram address space for fixed letter glyphes.)
• Store first frame into video ram.
• Start drawing of this frame by writing it's start address into register A.
  (this is probably done in the host's regular timer interrupt, which should run at 60 Hz)


Widget API
––––––––––

The display can be emulated in software as a widget.
Drawing should be implemented as a co-routine.
Then all timing is up the caller.

The widget may expose the following methods:

  		creator(float a=1,b=0,c=0,d=1)			// create and set HW transformation
  void	setTransform(float a, b, c, d);			// HW scaling: 1.0: [-127 … +127]
  uint16* setVideoRam(uint size=8*1024, uint16* ram=null);
  uint16* getVideoRam();						// return the video ram in use

  void	reset();								// disable drawing until setAddress() is called
  void	setAddress(uint32 now=0,uint address=0);// and start drawing (set register 'E' to 1)
  bool	run(uint32 now);						// run co-routine. return value of register 'E'

  TODO: touch / mouse feedback?






Letters, 6 pixel high:
––––––––––––––––––––––

call letters with 'c' = 0 and 'R' = 1.

'A':
	1,0		; space, then switch on
	0,3		; up
	4,0		; hor line
	0,4		; back (todo: better in OFF state?)
	2,3		; up to top
	2,-3	; down to right side
	0,-3	; down to base line
	return	; return with 'R'=1 and 'c'=0

'B':
	1,0		; space, then switch on
	0,6		; up
	3,0		; right
	1,-2	; right-down
	-1,-1	; left-down
	-3,0	; hor line
	3,0		; back
	1,-2	; right-down
	-1,-1	; left-down
	-3,0	; hor line
	OFF		; NOP with 'R'=1 and 'c'=0
	4,0		; move to position for next char
	return	; return with 'R'=1 and 'c'=0

'C':
	4,1		; move to bottom-right end of 'C'
	-1,-1	; down-left
	-2,0	; left
	-1,1	; left-up
	0,4		; up
	1,1		; right-up
	2,0		; right
	1,-1	; right-down
	OFF
	0,-5	; move to position for next char
	return











Terminal commands
–––––––––––––––––

• Letter 'A': reset terminal
	The terminal does a power-up reset and sends the identification string.
	See above.

• Letter 'B': identify
	The terminal sends the identification string.

• Letter 'C': set frames per second
	Arguments: 1 byte
	valid values: 0 or 1 … 60.

	The argument sets frames per second to 60/N.
	1 ➞ 60/1 = 60 frames/second (up to 1000 lines per frame, default after reset)
	2 ➞ 60/2 = 30 frames/second (up to 2000 lines per frame)
	…
	60 ➞ 60/60 = 1 frame/second

	0 = no delay.

	When setting fps to 1 … 60, each frame is drawn and displayed for N/60 seconds.
	When drawing finishs with command 'end of program', the back end waits.
	When the next ffb interrupt occurs, drawing restarts at address $0000, even if
	the back end was still drawing.

	When setting fps to 0, there is no ffb interrupt. (there may be a hard limit
	built into the terminal.) Drawing the next frame starts immediately after
	a frame is finished.

	When a new frame is started, a status byte is sent:
		'B' drawing started, previous frame was fully drawn
		'C' drawing started, previous frame was prematurely ended by ffb

	Low refresh rates will flicker,
	high refresh rates limit the number of lines per frame.

• Letter 'D': set hardware scaling, distortion and rotation
	Arguments: 4 bytes
	a,b,c,d = signed bytes in range -128 … 0 … +127

	The image can be scaled and rotated in hardware. Scaling is intended for scaling down only.
	This increases the X/Y resolution while the resolution for rotation is reduced.

	This can be used to compensate display errors on a real device or for effects.

	The display is distorted like this:

	X = a*x/120 + b*y/120
	Y = c*x/120 + d*y/120

	An unscaled, undistorted image with X/Y = [-255 … +255] is achieved with:
	'D',120,0,0,120	(default after reset)
	A double resolution, undistorted image with X/Y = [-510 … +510] is achieved with:
	'D',60,0,0,60

• Letter 'E': Transmission padding
	No arguments.
	No function.
	The terminal responds with status byte 'E'.

• Letter 'F': send data to video ram starting at address
	Arguments: 2+2+2*N bytes
		2 bytes address A
		2 bytes count N
		N*2 bytes data

	The first argument is the destination address (2 bytes, hi-lo).
	Next comes 'number of words' (2 bytes, hi-lo).
	Then this number of 2-byte words are received and stored into the video ram.
		the first byte is either x/dx or the high byte of an address or $80.
		the second byte is either y/dy or the low byte of an address or a command.
	The sender must handle race conditions between the asynchronously sent and read data.

	After all frame data is received, status byte 'F' is sent.

• Letter 'G': overwrite one word in ram at address $0000
	Arguments: 2 bytes
		2 bytes value N

• Letter 'H': overwrite one word in ram at address $0001
	Arguments: 2 bytes
		2 bytes value N

; • Letter 'I': copy block inside ram
; 	Arguments: 2+2+2 bytes
; 		2 bytes source address Q
; 		2 bytes destination address Z
; 		2 bytes count N
;
; 	Copy N words from source address Q to destination address Z. The memory is copied with i++.
; 	This may be used to implement two frame buffers.


• Status bytes sent by the terminal:

	'B' drawing started, previous frame was fully drawn
	'C' drawing started, previous frame was prematurely ended by ffb
	'D' some kind of problem detected. You should reset and restart everything.
	'E' letter 'E' (padding) received
	'F' frame data received



Register 'F': Frames per second

The F register may be part of the CRTC, or frame interrupts are generated by a timer device.
Then the CRTC must at least have a 1-bit F register to distinguish between F=0 and F≠0.

The duration of a frame is programmable in 1/60 second increments.
Available range is from 1/60 second to 60/60 seconds = 1 second.
A variable length mode is programmed with F = 0.
Low refresh rates will flicker, high refresh rates limit the number of lines per frame.

When the host writes to the address register, the CRTC starts drawing.
When command 'end of program' is encountered, the CRTC suspends drawing.
If F = 0 then the CRTC also generates an interrupt.
In the interrupt handler the host restarts the CRTC by writing to the address register.
Drawing restarts even if the CRTC was still busy drawing the old frame.


Terminal reset:
  Wait 1 second (60 frames) discarding all received data and sending no status bytes.
  Then send the identification string: "\nVector511,8k,60e3\n".
  This declares the display size, the vram size (words) and the drawing speed.

Tips:

• Store subroutines at the end of the ram.
• After reset upload subroutines to draw letters and symbols.
  The drawing ram is never erased by the terminal. (except: reset overwrites address $0000)
  Take care not to overwrite the subroutines.

When the status byte at the start of a frame is received, you can start overwriting the video ram with commands for the next frame. But you must be careful not to overwrite data for the current frame before it is displayed.
At 19200 Baud (1920 char/sec) and 60,000 lines per sec, already 30*(1+5+1) = 210 lines are drawn before the first byte can possibly be received and stored. Actually a RS232 serial line is so slow that only (small) parts of the screen can be updated within one frame. (320 lines/frame at 60Hz)








ALTERNATE
–––––––––

display: 256 x 256 pixel, 8-bit DACs
HW transformation for rotation and zoom effects


Drawing Commands:
–––––––––––––––––

Some bits are set in each command for the next command:
  R - 0 = absolute positioning		1 = relative positioning (or control code)
  C - 1 = beam on
  E - 1 = enable drawing clock		0 = end of frame
  I - 1 = raise interrupt if clock stopped

There 3 kinds of commands:
  absolute positioning
  relative drawing or moving
  control codes

A frame is started by writing the start address into the address counter register 'A'.
Start of frame does:
  set R to 1 (relative position or control code)
  set C to 1 (enable beam)
  set E to 1 (enable drawing clock)

All commands, except control codes, set the next command to:
  Relative position (or control code)
  beam on
  drawing clock enabled

Absolute position:
  Used to move to the start of a new line.
  set the counters for the X and Y DACs to dx and dy.
  all values allowed. (256 x 256 pixel)

  Absolute positioning is 'immediate' and therefore virtually never drawing.
  Absolute positioning has no free bits and no free 'unused' values.

Relative position:
  Used to draw lines or to move relative.
  Relative position command technically always 'draw', though the beam may be switched off.
  So Relative position should only be used for 'moving' short distances.
  (not yet required but handy for symbols when call/return implemented.)

  For simple hardware relative offsets are stored as sign bit + 7 bit absolute value:
    dx.sign = dx.bit7, dx.absvalue = dx & 0x7F
    dy.sign = dy.bit7, dy.absvalue = dy & 0x7F
  The hardware needs to know the absolute values to decide whether to draw in x or y direction,
  for the number of pixels to draw (in major direction) and for the calculation of side steps.
  The sign bits control whether the DAC counters count up or down.

Control codes:
  Relative drawing commands have some 'unusable' values,
  e.g. the 'major' line length may be 0 or any of both offsets may be a negative zero.
  If dx contains negative zero (dx=$80) this a control code.
  Then dy contains a command:

  dy = %ff00RICE

  The RICE bits set the RICE flags for the next command.
  ff = 0	NOP:  no other action
  ff = 1	CALL: call subroutine: the next two bytes are the subroutine address (future)
  ff = 2	RETN: return from subroutine
  ff = 3	unused

  If possible, the beam should be switched off during control code execution,
  else 'spotlights' may appear at these positions.


Example:
  To draw a rectangle around the entire screen:
  (one might wish to reduce the actually used screen to 255 x 255 pixels in this case)

  dx	dy
  –––––	–––––––––
  CMD	NOP + R + E	; select absolute address (and keep clock enabled)
  0 	0			; absolute address = (0,0) = bottom left corner
  127	0			; draw 127 pixel rightwards (max. possible value)
  127	0			; draw again
  1		0			; draw a total of 255 pixels
  0		127			; draw upwards
  0		127
  0		1
  -127	0			; draw leftwards
  -127	0
  -1	0
  0		-127		; draw downwards
  0		-127
  0		-1
  CMD	NOP + I		; stop clock and raise interrupt