# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1541182258 -3600
# Node ID 17260539b04d09c0f9ee998a281bbc5147277488
# Parent  caa06f34e4cc2e1b7ce194f3868feb76092a6a2b
Added general documentation and updated the vga-dual example documentation to
indicate that it does not seem to work with horizontal scrolling.

diff -r caa06f34e4cc -r 17260539b04d README.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README.txt	Fri Nov 02 19:10:58 2018 +0100
@@ -0,0 +1,57 @@
+Introduction
+------------
+
+The CommonPIC32 distribution contains library code and examples demonstrating
+various features and applications of MIPS-based products in the PIC32
+microcontroller family. The following examples are provided:
+
+demo        A demonstration of an assortment of peripherals, changing pin
+            output levels (to turn LEDs on and off) and communicating using a
+            UART peripheral.
+
+vga         A collection of examples investigating approaches to provide an
+vga-cpu     analogue VGA signal, displaying the contents of the
+vga-dual    microcontroller's memory on a suitable display. Each example has
+vga-pmp     documentation describing its approach, benefits and limitations,
+vga-timer   but a summary is provided below.
+
+Contact, Copyright and Licence Information
+------------------------------------------
+
+The author can be contacted at the following e-mail address:
+
+paul@boddie.org.uk
+
+Copyright and licence information can be found in the docs directory - see
+docs/COPYING.txt and docs/gpl-3.0.txt for more information.
+
+VGA Output Example Comparison
+-----------------------------
+
+In investigating different techniques, the following observations have been
+made about the behaviour of the different VGA examples:
+
+            DMA       Horizontal  Picture   Pixel       Scrolling
+            Channels  Resolution  Stability Consistency Operational
+            --------  ----------  --------- ----------- -----------
+vga         1         High        No        No          Yes
+vga-cpu     0         High        Yes       Yes         Yes
+vga-dual    2         High        No        No          No
+vga-pmp     1         High        No        No          Yes
+vga-timer   2         Low         Yes       Yes         Yes
+
+Here, picture stability is assessed with the CPU accessing RAM. In general,
+all of the approaches can provide stable pictures with limited RAM access
+loading. However, under load, the picture will stretch and ripple for all
+examples where picture stability is given as "No".
+
+It should be noted that the vga-timer example employs two DMA channels, but
+this is only to maximise horizontal resolution. With a single channel,
+horizontal resolution is diminished still further in comparison to the other
+examples.
+
+It would appear that two most viable approaches are the vga-cpu and vga-timer,
+if only because they produce consistently-sized pixels, retain picture
+stability under load, and provide operational horizontal scrolling. These
+approaches provide a tradeoff between performance (vga-timer being faster) and
+resolution (vga-cpu being better).
diff -r caa06f34e4cc -r 17260539b04d examples/vga-dual/README.txt
--- a/examples/vga-dual/README.txt	Fri Nov 02 18:26:06 2018 +0100
+++ b/examples/vga-dual/README.txt	Fri Nov 02 19:10:58 2018 +0100
@@ -21,6 +21,10 @@
 group of four pixels), the effect persists. However, the picture is perhaps
 more stable than in the vga example.
 
+One significant problem with this example is that scrolling causes the DMA
+channels to become ordered incorrectly. This does not affect the vga-timer
+example which also employs two DMA channels.
+
 Hardware Details
 ================