README.txt

Due VGA Library

by stimmer

V0.987654321 - 23/11/2013

1) Quick start

==============

Place the VGA folder in your libraries directory

Start or restart the Arduino IDE

For VGA mono:

-------------

Upload File->Examples->VGA->HelloWorld

Connect pin 42 to VGA VSync (pin 14 on VGA D-connector)

Connect pin 43 to VGA HSync (pin 13 on VGA D-connector)

Connect GND to VGA GND (pins 5,6,7,8,10 on VGA D-connector)

Connect SPI MOSI pin (bottom middle pin on 6-pin SPI connector) through

a 100 ohm resistor to VGA Red, Green and Blue pins (pins 1,2 and 3 on D-connector)

Turn on monitor :-)

If the monitor has trouble, try some small resistors between 42 and VSync, and 43

and HSync (10 to 100 ohm)

For VGA colour:

---------------

Upload File->Examples->VGA->HelloWorldColour

Connect Due to monitor as follows:

Due pin 34 -> 820R resistor -> VGA pin 3 (blue)

Due pin 35 -> 390R resistor -> VGA pin 3 (blue)

Due pin 36 -> 2k2 resistor -> VGA pin 2 (green)

Due pin 37 -> 1k resistor -> VGA pin 2 (green)

Due pin 38 -> 470R resistor -> VGA pin 2 (green)

Due pin 39 -> 2k2 resistor -> VGA pin 1 (red)

Due pin 40 -> 1k resistor -> VGA pin 1 (red)

Due pin 41 -> 470R resistor -> VGA pin 1(red)

Due pin 42 -> VGA pin 14 (VSync)

Due pin 43 -> VGA pin 13 (HSync)

Due pin GND -> VGA pins 5,6,7,8,10

For NTSC/PAL:

-------------

Upload File->Examples->VGA->DrawingTestNTSC (or DrawingTestPAL)

Connect Due to TV as follows:

Due pin 36 -> 3k3 resistor -> Video In

Due pin 37 -> 1k6 resistor -> Video In

Due pin 38 -> 820R resistor -> Video In

Due pin 39 -> 390R resistor -> Video In

Due pin 40 -> 200R resistor -> Video In

Due pin 41 -> 100R resistor -> Video In

Due pin GND -> Video GND

On some TVs this will not work. You may need a 100uF capacitor between

the resistors and Video In.

2) Basic usage

==============

The library is very simple to use - see the examples

#include <VGA.h> at the top of your sketch,

VGA.begin(640,480); in setup for mono or

VGA.begin(320,240,VGA_COLOUR); for colour.

Then call various drawing functions, eg:

drawPixel(x, y, col); sets a single pixel to colour col

drawLine(x0, y0, x1, y1, col); draws a line from (x0,y0) to (x1,y1)

fillCircle(x, y, r, col); circle, center (x,y) radius r

For text, use VGA.print(...) and VGA.println(...) just like Serial.print(...) and

Serial.println(...)

3) Colours

==========

In mono mode, 1 is white, 0 is black, and -1 inverts the pixel.

In colour mode (and PAL and NTSC modes), colours are interpreted in

binary as RRRGGGBB. So for example:

0b11111111 = 255 = white 0b11110000 = 240 = orange

0b11100000 = 224 = red 0b10010010 = 146 = grey

0b00011100 = 28 = green 0b10000011 = 227 = purple

0b00000011 = 3 = blue 0b00000000 = 0 = black

In the draw* and fill* functions, negative colour values XOR with the current colour

of the pixel, ie newcol=oldcol^(-col)

4) API

======

int VGA.begin(int x, int y, int m=VGA_MONO);

Initializes the display, resolution (x,y). m is VGA_MONO or VGA_COLOUR

Returns: 0 on success, negative on failure

Not all resolutions work on all monitors. Highest recommended resolutions are

800x600 in mono and 320x240 in colour.

int VGA.beginNTSC();

Initializes the display in NTSC mode, 320x200 pixels.

Returns: 0 on success, negative on failure

int VGA.beginPAL();

Initializes the display in PAL mode, 320x240 pixels.

Returns: 0 on success, negative on failure

void VGA.end();

Stops the display, and frees memory.

void VGA.clear(int col=0);

Clears the screen to colour col, or black if col is not specified.

void VGA.drawPixel(int x, int y, int col);

Draws pixel at (x,y) in colour col

void VGA.drawLine(int x0, int y0, int x1, int y1, int col);

Draws line from (x0,y0) to (x1,y1) in colour col

void VGA.drawTri(int x0,int y0,int x1,int y1,int x2,int y2,int col);

void VGA.fillTri(int x0,int y0,int x1,int y1,int x2,int y2,int col);

Draws or fills triangle (x0,y0),(x1,y1),(x2,y2) in colour col

void VGA.drawRect(int x0, int y0, int x1, int y1, int col);

void VGA.fillRect(int x0, int y0, int x1, int y1, int col);

Draws or fills rectangle with corners (x0,y0),(x1,y1) in colour col

void VGA.drawCircle(int x, int y, int r, int col);

void VGA.fillCircle(int x, int y, int r, int col);

Draws or fills circle center (x,y) radius r in colour col

void VGA.drawEllipse(int x0, int y0, int x1, int y1, int col);

void VGA.fillEllipse(int x0, int y0, int x1, int y1, int col);

Draws or fills ellipse bounded by rectangle (x0,y0),(x1,y1) in colour col

void VGA.drawText(char *text, int x, int y, int fgcol, int bgcol= -256, int dir=0);

Draws text at any pixel position.

(x,y) is the top-left corner of the text before rotation.

fgcol is the colour of the text. bgcol is the colour of the text background

or -256 for a transparent background.

dir is the direction of the text. 0 is normal, 1 is up, 2 is upside-down and 3

is down. -1 draws the text going downwards but with the individual characters

oriented normally.

void VGA.scroll(int x, int y, int w, int h, int dx, int dy,int col=0);

Scrolls an area of the screen, top left corner (x,y), width w, height h

by (dx,dy) pixels. If dx>0 scrolling is right, dx<0 is left. dy>0 is down,

dy<0 is up.

void VGA.moveCursor(int column, int line);

Moves the print position to (column, line)

void VGA.setPrintWindow(int left, int top, int width, int height);

Restricts the printing window to an area of width x height characters, at a

position left characters in and top characters down.

void VGA.unsetPrintWindow(){tww=tw;twh=th;twx=twy=0;}

Restores the print window to be the whole screen.

void VGA.clearPrintWindow();

Clears the print window to the current text paper colour.

void VGA.scrollPrintWindow();

Scrolls the print window up one line and moves the print position to the bottom.

void VGA.setInk(int i){ink=i;}

Sets the text colour to i.

void VGA.setPaper(int p){paper=p;}

Sets the text background colour to p

virtual size_t VGA.write(const uint8_t *buffer, size_t size);

virtual size_t VGA.write(uint8_t c);

These functions are similar to Serial.write, except output gets printed to

the screen. These functions enable print and println to work correctly.

void VGA.waitBeam()

void VGA.waitSync()

These functions wait for the beam position to be off-screen. waitBeam will return

immediately if the beam is already off-screen, waitSync will always wait for the

next frame. These can be used to reduce flicker.

void VGA.setMonitorFreqRange(int hmin, int hmax, int vmin, int vmax)

This function can be tried if your monitor has trouble syncing to some modes.

All frequencies are in Hz, eg setMonitorFreqRange(27000, 82000, 58, 65);

Call this before VGA.begin(...)

void VGA.setSyncPolarity(bool h, bool v)

Swaps the polarity of the sync signals. Most monitors don't need this.

Call this before VGA.begin(...)

void VGA.putPPixelFast(int x, int y, int c)

int VGA.getPPixelFast(int x, int y)

void VGA.putCPixelFast(int x, int y, int c)

int VGA.getCPixelFast(int x, int y)

Fast inline pixel put/get routines. The P functions are for mono modes and the

C functions are for colour modes.

5) Low Level

============

In mono modes, the screen is arranged as an array of 16-bit words. Each line has enough words for the pixels (eg 40 words in 640x480 mode) plus 2 spare words which are used for blanking and must always be 0.

uint16_t *VGA.pb; // Pixel buffer memory address

int VGA.pw; // Count of words from one line to the next (aka stride or pitch)

int VGA.pbsize; // Total size of pixel buffer (note these sizes are 16-bit words)

The SAM3X also supports a bit-banding alias region in memory, where each bit is mapped to a 32-bit address.

uint32_t *VGA.pbb; // Pixel buffer bit-banding alias address (read datasheet p75)

int VGA.pbw; // Pixel buffer bit-banding stride (in 32-bit words)

To help understand usage of these, look at the following functions:

void putPPixelFast(int x, int y, int c){pbb[y*VGA.pbw+(x^15)]=c;}

int getPPixelFast(int x, int y){return pbb[y*VGA.pbw+(x^15)];}

In colour modes there are no spare words needed so the colour buffer is just an

array of uint8_t[width*height].

uint8_t *VGA.cb; // Colour buffer memory address

int VGA.cw; // Colour buffer stride, in bytes

int VGA.cbsize; // Size of colour buffer in bytes

6) How it works

===============

Don't ask ;-)

Basically it uses nested interrupts. Each line the PWM hardware generates the

horizontal sync signal then interrupts the processor. Unfortunately it interrupts

at a very slightly different time each line, which would cause a shimmering

effect. So the PWM interrupt puts the processor to sleep, waiting to be interrupted

again by a timer interrupt at higher priority. Since the processor wasn't doing

anything, this interrupt is precisely synchronized to the timer and the display

is rock solid :-)

The mono modes use DMA and SPI hardware (42MHz for 800x600!) and are therefore

quite fast. The SPI DMA uses another interrupt to signal the end of a line.

Unfortunately at the end of transmission the SPI output goes HIGH, which would

cause a white line. That's why there are spare blanking words at the end of the

line - when the interrupt fires the DMA is out of data but the blanking words are

still being output, so the interrupt routine quickly sets the pin back to PIO mode,

putting it low, and avoiding the white line.

The colour mode uses DMA to the SMC - static memory controller - to output 8 bits

of data at a time to pins 34-41. No end-of-line interrupt is needed here because

the output goes high impedance when data is not being written. The pixel width

is controlled by changing the memory timing registers in the SMC.

The NTSC and PAL modes use a pair of DMA buffers. One is outputting the signal for

the line whilst the interrupt routine is filling the other buffer for the next line.

The colour burst and chroma phase tables have been precalculated (which is why these

modes use so much flash).

Have fun!