USING SDUMP by Dilwyn Jones

SDUMP is a rather slow, but otherwise quite easy to use screen dump
facility. You can print using a new keyword in SuperBASIC, define a
hotkey to print as soon as you press ALT and that key, print a section
of the screen, print from a copy of the screen in memory and above all
it drives a large number of printers.

The simplest way of printing is via an SDUMP command from a basic
program. Before  using it, you need to tell it where to print to, and
the dump details with two other basic extensions.

The easiest is SDP DEV 'SER', , which simply tells SDUMP that all
printing is to be done via SER1. The name does not have to be in
quotes, or it can be a string variable, so all three of these forms
are acceptable:

    SDP_DEV 'SER1'
    SDP DEV ser1
    LET p$='SER1' : SDP DEV p$

SDP_SET is a command which tells SDUMP a few things like what type of
printer is to be used, scale (if there is a choice for the printer
concerned), whether or not to swap black and white (i.e. invert or
not) in the printout, and whether or not to introduce some randomness
in the printing to represent colours by using a little bit of shading.
Some dumps work on colour dot matrix printers, but most are for black
ink printers only.

The syntax of the command is

SDP_SET Printer_Number, Scale, Inverse, Random.

Printer Number - a number from 1 to 23, the names of the printers
corresponding to each number is listed in a table in the Miracle
Systems Toolkit 2 manuals, from Epson MX80 (1) to MT80 (23). For
example, if you have an Epson LQ2500 colour printer, you would use the
number 7 or 8. If your printer is not listed there, experiment a
little as many types are compatible. The 'standard' Epson FX80 8 pin
graphics compatible is likely to be type 2 or type 5, while a 24 pin
printer is likely to work with type 6. If you have a wide carriage
printer, there is some support for those too.

Scale. A number from 1 to 3, which lets you choose the size of the
printout. Some options may only print 480 out of the 512 pixels across
the QL screen, because for printers 4800 is a standard number of dots
across an 8 inch sheet of paper. The options which are not able to
print the whole screen may be useful for larger dumps of small areas
of the screen. for example.

Inverse. A value of 1 tells SDUMP to swap black and white when
printing. A value of 0 tells it to keep black and white as they are on
screen. The use of this facility is required when printing a screen
dump from programs like Quill, which use the colour scheme of black
background with white ink, so you need to swap the colours when
printing on the white paper used in printers.

Random. This parameter can be omitted, in which case it just stays as
it was the last time  you used it, or becomes 0 by default the first
time you use the command.

Suppose we want to print to an Epson FX80 (printer number 2), In scale
number 1 (smallest), inverting black and white (1) and using random
shading (1) to represent colours on the screen. First we define the
SDP_SET command as follows:

SDP_SET 2, 1, 1, 1
        ^  ^  ^  ^
        |  |  |  |
        |  |  |  +-- 1=random shading
        |  |  |
        |  |  +----- 1=invert colours
        |  |
        |  +-------- 1=scale number 1 (smallest)
        |
        +----------- 2=Epson FX80

Nest, we tell the SDUMP program where to send the output:

SDP DEV 'SER1'

Finally, we can tell SDUMP to start printing. This is done by using
the SDUMP command. Used by itself with no parameters this dumps the
whole screen to the printer.

SDUMP

There are other options available for dumping parts of the screen too.
These are specified by giving different parameters to the SDUMP
commands. For example, SDUMP #2 tells it to produce a printout of only
window #2 on the screen.

To print an area specified by pixel coordinates on the screen, you can
give a list of 4 parameters like a WINDOW command in basic.
SDUMP 256,128,96,64

That example prints a section of the screen 256 pixels wide, 128
pixels high, 96 pixels across the screen and 64 pixels down.

The other two options with 1 or 5 parameters are for use with copies
of screens in  memory saved in pointer environment area save format
(with the usual 10 byte header section). These are a bit too complex
for a beginners article like this one, but basically they are very
useful when you progress to writing programs which use the technique
of working on graphics stored in memory as a copy of the screen. I'll
mentionhere briefly the file format for a _PIC file (Pointer
Environment Area Save Graphic format). The 10 byte header consists of
5 sections as shown below:
BASE:
1 word   hex '4AFC' (decimal word 19196, or as two bytes, 74,252)
                    (flag indicating this type of file)
BASE+2:
1 word   width of picture in pixels

BASE+4:
1 word   height of picture in pixels

BASE+6:
1 word   number of bytes per line across this picture (i.e. length
                    in bytes between start of one line and start
                    of the next line - the line increment value)
BASE+8:
1 byte   mode number - 0 for 4 colour mode pictures, 8 for mode 8
                    (N.B. Some programs use 4 as the colour value
                    instead of 0 - avoid using 4 if possible, though
                    your program may have to cope with values of 4
                    stored by older graphics programs)
BASE+9:
1 byte   unused byte, although the QDesign program uses this as an
                    extra flag to indicate a compressed file. This
                    is not a standard supported feature.
BASE+10:
start of graphics data.

To convert a 512x256 QL screen picture 32,768 bytes long into this
format to be printed, all we have to do is reserve enough common heap
space for this file plus 10 bytes for the header, construct the 10
byte header, load the screen immediately after it and call the SDUMP
routine to print it.

base = ALCHP(10+32768)
IF base < 0 : PRINT'Error' : STOP
LBYTES filename,base+10
POKE_W base,19196 : REMark insert flag bytes
POKE_W base+2,512 : REMark screen width
POKE_W base+4,256 : REMark screen height
POKE_W base+6,128 : REMark 128 bytes per line
POKE   base+8,0 : REMark 0 for MODE 0, 8 for MODE 8 as required
REMark set up sdump parameters
SDUMP base : REMark print PIC file located at the flag
RECHP base : REMark release heap memory to tidy up afterwards


All this is perfectly well and good if you are able to use the SDUMP
keyword - i.e. it is a  basic program you have written yourself and
know where to insert the command. Typing it in from basic would of
course mark the screen.

So the designer of this system has also made it possible for you to
set up the dump first, but only to start printing when you press ALT
and a certain other key. This is very useful for printing out the
displays of other programs. The SDP_KEY command is used for doing
this. Just follow it with a key description. e.g. SDP KEY 's' means
that when you press ALT and the s key, the QL starts to print a screen
dump. It does not have to be a letter key, e.g. SDP_KEY CHR(48) would
allow ALT and the zero key to start the screen dump.

More advanced users can access the screen dump facilities through the
i/o device SDUMP. As this a rather advanced facility, I will take the
view that if your knowledge of programming is good enough for you to
be able to use this feature. you will be able to work out from the
Miracle manuals how to do this, and this article is getting quite long
as it is.


    Source: geocities.com/svenqhj