W2000A Screenshot Utility
=========================
--- Version 0.3 ---

Changelog
---------

* v0.1 (Initial Release):

  Provides new RS232 command # (pound) to initiate b/w screendump with simple
  RLE compression.  Usually only around 10-15kB to be transferred.

* v0.2:

  Additional ' (tick) command to initiate full plane dump with same simple RLE
  compression as with the # command.  Around 60-65kB total to be transferred.

  Planes are coloured and combined into an PPM image file.  Individual planes
  are also available as numbered PGM image files for inspection or partial
  export.

  New -h and -f command line options.  More status and progress messages on
  stderr.

  Since multiple planes can be output, data is written to file(s) in v0.2, no
  longer to stdout.  Use -f option to specify target file prefix.

* v0.3:

  Native windows support.  New command line option -c to specify COM port.
  Third party ComTools from Anton Zechner are used for now, likely to be
  replaced in upcoming releases.  Precompiled EXE is bundled from now on.

  Alternative BMP output instead of PPM/PGM.

  Makefile is provided.  Please note that we changed from .c to .cpp just for
  the third party ComTools, actual C++ features are not used.

  Patch is now included in BF1.2-0.80-beta upwards, so diff is no longer
  provided.  ' and # RS232 commands were removed, instead screenshots may be
  triggered in the Quick Print of the DSO.

Known Issues
------------

  The BMP file format uses the somewhat uncommon storing order of
  "upside-down", in contrast to the usual raster scan order starting top-left
  (0, 0) and ending bottom-right (640, 480).

  Turns out that using the "normal" order is possible and specified by using a
  negative height value.  But after implementing this it further turns out
  that some programs and image libraries just don't expect that option to be
  used.

DSO Preperation
---------------

  * Firmware BF1.2-0.80-beta or newer installed:
    No preperation needed.

  * Older firmware:
    Patch and compile firmware with .diff in v0.2 package or use precompiled
    TomCat.ram in same package.  Upload firmware (i.e., with GERMSloader.pl)
    to DSO.

Building
--------

  (not needed on Windows)

  $ make unix
  or
  $ make win

Setup Serial Device
-------------------

  (not needed on Windows,
   automatically done)

  $ stty -F $device 115200 raw -echo
  (stty -f for *BSD usually)

Making A Screenshot
-------------------

  Windows:

     Run w2000a-screenshot or edit and use
     provided .BAT file.

  Unixoid:

  (1) Start w2000a-screenshot:

        $ ./w2000a-screenshot < $device

  Pre BF1.2-0.80-beta firmware with patch:

     (2a) Initiate screendump by executing # or ' command on RS232:

           $ echo '#' > $device
           $ echo "'" > $device

  BF1.2-0.80-beta or later:

     (2b) Use the Quick Print menu on the DSO.

  (3) The utility decompresses the RLE data from the DSO to PGM files
      and colours and combines the retrieved planes to a single PPM image file.

      You might want to use ppmto*/pgmto*(1) of NetPBM or convert(1) of
      ImageMagick to make more handy files out of the PPM/PGM images, i.e.:

        $ convert screenshot.ppm screenshot.png

