(c)  Copyright 1989 Commodore-Amiga, Inc.   All rights reserved.
The information contained herein is subject to change without notice, and 
is provided "as is" without warranty of any kind, either expressed or implied.  
The entire risk as to the use of this information is assumed by the user.

		Writing a V1.3 Graphics Printer Driver

			by David Berezowski



Under V1.3 of the Amiga system software, the printer device has been
enhanced.  This article gives you an overview of the changes and provides
some of the information you will need to bring you V1.2 drivers up to date.

Do not use this article alone as a 'how-to' reference.  You should also
review the source code for the V1.3 printer drivers on the devcon disk.
These are good examples to work from and show the changes needed from 
previous Workbench releases.  Additionally, the "ROM Kernel Reference 
Manual: Libraries and Devices" (chapter 15, Printer Device) should be used 
as reference material.  Use this article as a supplement.



Printer Driver Source
---------------------

To help you in developing your own V1.3 custom printer drivers for the Amiga, 
the source files to the Workbench printer drivers are included on the devcon 
disk.  All the Workbench printer drivers include six modules: data.c, 
dospecial.c, init.asm, printertag.asm, render.c, and transfer.c.  Additional 
source code files may be required to handle the special capabilities of the
printer you are working with.  The chart below shows the extra files needed
with the Workbench printer drivers:


      Printer         Extra Source Files       Printer Type
      -------         ------------------       ----------------------

      ColorMaster     prtready.c               YMC_BW, multi-pass,
                                               page oriented

      ColorMaster2    prtready.c               YMC_BW, page oriented

      EpsonQ          density.c                YMCB, 24 pin, multi-density 

      EpsonX          density.c                YMCB, 8 pin, multi-density,
                                               interleaved densities

      HP_LaserJet     density.c                BW, multi-density,
                                               page oriented

      Okimate_20      none                     YMC_BW

      Xerox_4020      none                     YMCB, ink jet,
                                               uses run-length encoding


	
V1.3 RENDER.C 
-------------

Render.c is the main module of a graphic printer driver.  The original
documentation for this module appears in the "ROM Kernel Manual:Libraries
and Devices".  Be sure to refer to the original docs as well as this
article when writing you printer driver.

Render.c now has seven cases.  Before we consider the details of each case,
there are two miscellaneous items not covered in the RKM that I want to 
mention.  First, be sure the arguments to render.c - ct, x, y, status - are
declared as longs.  Second, when you call PWrite, check the return code.  
If it isn't PDERR_NOERR you must exit immediately.  If you do not exit
immediately, the user may not be able to cancel the printing.


Case 5: Pre-Master Initialization
---------------------------------

This is a new case and the first call you will get.  The render.c parameters 
will be:

    ct - 0 or pointer to the IODRPReq structure passed to PCDumpRPort.
     x - io_Special flag from the IODRPReq structure.
     y - 0.

When the printer device is first opened it makes this call with ct=0.
This gives the driver a chance to to set up the density values before the 
actual graphic dump is called in a manner compatible with pre-1.3
software.

The x parameter will contain the density and other SPECIAL flags which are
defined in the file devices/printer.h.  Currently the only flags that 
you will be interested in are DENSITY1 to DENSITY7.  These are explained
further under case 1 below.  The flag SPECIAL_CENTER should be ignored as 
it will always be cleared.  This flag is handled by the printer device.

Never call PWrite during this case, unless you want to crash.  When you are
done handling this call, you should return PDERR_NOERR.

Case 0: Master Initialization
-----------------------------

The parameters for this case are:

    ct - a pointer to a IODRPReq structure.
     x - width (in pixels) of printed picture.
     y - height (in pixels) of printed picture.

As under V1.2, you should allocate the memory that you will need to store 
the printer data at this stage.  If the allocation fails, you should return a
PDERR_BUFFERMEMORY.  If the allocation succeeds, return PDERR_NOERR.  This is
also a good time to do any special one-time initializations to your printer
or buffer.  

Some typical initialization codes you might send to the printer are:

   a) Carriage Return - some printers start printing graphics from where ever
                        the printhead was last.  Sending a CR assures that
                        printing will always start from the left edge.

   b) Uni-Directional - if you allow the printer to print graphics in
      Mode              bi-directional mode you'll find that it will tend
                        to produce wavy vertical lines as the two passes
                        won't put dots in quite the same place.

   c) Clear Margins   - if your printer forces graphic dumps within text 
                        margins, you will have to clear the margins (set left
                        to minimum, right to maximum) before doing the dump.
                        Refer to the EpsonX or EpsonQ source for an example.

   d) Any other       - enter graphics mode, set density, etc.
      set-up

   
Do not reset the printer during master initialization since this will cause
problems during multiple dumps.  Also, do not use the value in ct unless 
your printer is one of those rare kinds for which a render function cannot 
be written.

With the addition of the Case 6 call and the PCC_MULTI_PASS color class 
type, there are no known printers that need this value.  But if you do use 
the value in ct to do the entire dump yourself then you must return an error
of PDERR_TOOKCONTROL which tells the printer device that the dump has 
already been done and to exit gracefully.


Case 1: Put Pixels in Buffer
----------------------------

    ct - pointer to a PrtInfo structure.
     x - PCM color code for this pass if the printer is PCC_MULTI_PASS.
	 The PCM defines from the file devices/prtgfx.h are PCMYELLOW, 
         PCMMAGENTA, PCMCYAN and PCMBLACK.  
     y - printer row # (range is 0 to height-1).

This case has changed completely from the V1.2 spec in order to facilitate
shorter dump times.  In the call you are passed an entire row of YMCB
(Yellow/Magenta/Cyan/Black) intensity values.  To handle this case, you should
call transfer.c, which you may remember is one of the required driver
modules.  This is described in more detail below.

You should return PDERR_NOERR after handling this case.


Case 2: Dump Buffer To Printer 
------------------------------

The parameters for this case are:

    ct - 0.
     x - 0.
     y - # of rows sent (the range is 1 to NumRows).

This call has changed slightly from the V1.2 spec and has some new
recommendations.  If your printer supports RLE (Run Length Encoding), now 
is the time to RLE your data.  

If your printer doesn't support RLE then your should white-space strip your 
data.  This involves scanning your buffer from back to front for the first 
occurrence of a non-zero value.  You should send only the data up to the 
first non-zero value.  In other words, do not send trailing white space data 
to the printer.  Use of either of these techniques will significantly reduce 
print times.  

Use the y parameter to determine how many pixels to advance the paper if 
your printer supports this feature.  Implementing this feature will allow 
successive graphic dumps to butt up against each other.

You should return the error from PWrite after this call.


Case 3: Clear and Init Buffer
-----------------------------

    ct - 0.
     x - 0.
     y - 0.

This call is made before each case 2 call.  Clear your active print buffer
- remember you are double buffering - and initialize it if necessary.

You should return PDERR_NOERR after this call.


Case 4: Close Down 
------------------

    ct - error code.
     x - io_Special flag from the IODRPReq structure.
     y - 0.

This call is made at the very end of a graphic dump or if the graphic dump
was canceled for some reason.  You should free the printer's buffer memory
at this point, but be careful.  The print buffer's memory should only be 
freed if you allocated it.  If PD->pd_PrintBuf is not NULL then you have 
allocated the memory, and must free it up.  

If your printer - usually a page oriented printer - requires a page eject 
command, do it here.  But first check for the SPECIAL_NOFORMFEED bit in x.
If it is set then you don't send the page eject command.  

If the error condition in ct is PDERR_CANCEL, then you should not PWrite.
This code indicates that the user is trying to cancel the print due to a 
printer problem, paper out condition, etc.  And for each PWrite you call,
another printer trouble requester is generated.  Obviously we want to avoid 
this. 

You should return either PDERR_NOERR or the error returned by PWrite if you
called it.  Typical reasons for calling PWrite in this case are:

   a) reset line spacing -  if your printer doesn't have an advance n dots
                            command, then you'll probably advance the paper
                            by changing the line spacing.  If you do, then
                            you should set it back to either 6 or 8 lpi
                            (depending on Preferences).

   b) bi-directional mode - set it back if you selected uni-directional
                            printing in case 0.

   c) black text          - some printers print the text in the last color
                            used - even if it was in graphics mode.  If you 
                            don't set the color to black, the text color 
                            after a graphic dump will be a surprise.

   d) any other one time  - exit graphics mode, eject paper, etc.
      commands

   e) If you cancelled the margins in case 0, you should restore them here.
      Refer to the EpsonX or EpsonQ source code for an example.

Case 6: Switch to Next Color
----------------------------

    ct - 0.
     x - 0.
     y - 0.

This is a new call provided to support printers which require that colors be 
sent in separate passes.  When this call is made you should instruct the 
printer to advance its color panel.  You will not have to handle this case
unless you are writing a driver for a printer type of PCC_MULTI_PASS, such as
the CalComp ColorMaster.




PRINTERTAG.ASM
--------------

Printertag.asm is a standard printer description file you should create
for all your printer drivers.  Here is a listing of the file and some
typical values:

        MOVEQ   #0,D0              ;in case any one tries to run us
        RTS
        DC.W    VERSION            ;must be 35 (for V1.3)
        DC.W    REVISION           ;your own revision number
_PEDData:
        DC.L    printerName        ;ptr to name
        DC.L    _Init              ;ptr to initialization code
        DC.L    _Expunge           ;ptr to expunge code
        DC.L    _Open              ;ptr to open code
        DC.L    _Close             ;ptr to close code
        DC.B    PPC_COLORGFX       ;PrinterClass
        DC.B    PCC_YMCB           ;ColorClass
        DC.B    136                ;MaxColumns
        DC.B    10                 ;NumCharSets
        DC.W    8                  ;NumRows
        DC.L    1632               ;MaxXDots
        DC.L    0                  ;MaxYDots
        DC.W    120                ;XDotsInch
        DC.W    72                 ;YDotsInch
        DC.L    _CommandTable      ;ptr to Command Strings
        DC.L    _DoSpecial         ;ptr to Command Code
        DC.L    _Render	           ;ptr to Graphics Render
        DC.L    30                 ;Timeout
        DC.L    _ExtendedCharTable ;ptr to 8BitChars table($a0 to $ff)
        DS.L    1                  ;PrintMode (reserve space)
        DC.L    0                  ;ConvFunc (ptr to char conversion function)

printerName:
	STRING	'EpsonX'

Be sure to set the VERSION field of printertag.asm to 35.  This identifies
it as a V1.3 driver.  It is also important that you declare enough storage
for this file.  Notice that three new fields have been added since V1.2.
These new fields are 8BitChars, PrintMode and ConvFunc.

The 8BitChars field should contain a pointer to a table of chararacters for
the ascii codes $a0-$ff.  The symbols for these codes are shown in the 
"Amiga DOS Developer's Manual" Appendix.  Make this field null (DC.L 0) if
you don't provide the table.  If you make the pointer null or use a VERSION
number less than 33, a default table will be used instead.  

Creating your own table to handle codes $a0-$ff can be tricky because of
the way the table is parsed by the printer device.  Valid expressions in
the table include \011 where 011 is an octal number, \\000 for null and
\\n where n is a 1-3 digit decimal number.  To enter an actual backslash in 
the table requires the very awkward \\\\.  Shown below are the first few
entries from the EpsonX[CBM_MPS-1250] table.  

char *ExtendedCharTable[] = {
        " ",                                    /* NBSP*/
	"\033R\007[\033R\\0",                   /* i */
	"c\010|",                               /* c| */
	"\033R\003#\033R\\0",                   /* L- */
	"\033R\005$\033R\\0",                   /* o */
	"\033R\010\\\\\033R\\0",                /* Y- */
	"|",                                    /* | */
	"\033R\002@\033R\\0",                   /* SS */
	"\033R\001~\033R\\0",                   /* " */
	"c",                                    /* copyright */
        /* more entries etc. */

        };


The PrintMode field is a flag set by the printer device and used by you in 
DoSpecial and Render if you are working with a page oriented printer such 
as the HP-LaserJet.  This field requires 4 bytes of storage  (ie. DS.L 1).

The ConvFunc field contains a  pointer to a character conversion function 
that allows you to selectively translate any character to a combination of 
any other characters.  If you don't have a translation function - most 
printers won't - then you must declare the pointer to be null (ie. DC.L 0).  

ConvFunc's arguments are a pointer to a buffer, the character in question, 
and a CR/LF flag.  Your ConvFunc routine should return a -1 if you didn't 
do any conversion (ie. you want the character sent to the printer as is).  
Return 0 if you do not want the character passed to the printer.  Or return 
the number of characters that you translated the original character into.

The code for the conversion function can be put virtually anywhere (ie. 
data.c, dospecial.c, etc.).  Here is an example of a simple conversion 
function:

        ConvFunc(buf, c, flag)
        char *buf, c;
        int flag;        /* expand lf into lf/cr flag (0-yes, else no ) */
        {
              int err;
              if (c == 0x7f) {          /* change DELETE to <DEL> */
                        *buf++ = '<';
                        *buf++ = 'D';
                        *buf++ = 'E';
                        *buf++ = 'L';
                        *buf++ = '>';
                        err = 5;      /* I added this many chars to buffer */
              }
              else {
                   err = -1;    /* I didn't do anything with the char */ 
              }
        return(err);
        }


Another possible use for this routine would be to support underlining on a
printer that doesn't do automatic underlining.  You could have an underline 
flag that would tell you if underlining was on or off.  If off, your routine 
would do nothing and return -1.  If on, your routine would put the character, 
backspace, and the underline character in the buffer and return 3. 
  
When expanding one character into several chars with ConvFunc, try to keep 
the expansions to a minimum.  This will help throughput and reduce the 
possibility of data overrunning the printer.device buffer.  One other note,
I recommended that you pass 0x1b (ESC) and 0x9b (CSI) back to the printer 
device without processing them.  Simply return -1.


DENSITY.C
---------

Density.c is a new printer driver module which implements multiple densities
The handling of densities has changed quite a bit from V1.2.  Look at the
Workbench printer driver source files on the devcon disk for examples of
how to create this module.

Density.c gets called by render.c during pre-master initialization.  The
density.c code should select either the desired density or, if the user asked 
for a density higher than you support, the maximum density.  For example,
if your driver supports four densities, DENSITY1 through DENSITY4, and the
user selects DENSITY6, then your code should select DENSITY4.  The density.c 
code is also responsible for handling narrow and wide tractor paper.  Refer 
to the EpsonX or EpsonQ density.c source code for an example of this.

Density.c should not support densities below 80 dpi.  This convention
results in a minimum of 640 dots across for a standard 8.5 x 11 inch piece
of paper (8 inches x 80 dpi = 640 dots) and gives a 1-1 correspondence of
dots on the printer to dots on the screen in x under standard screen sizes. 

The HP LaserJet  driver is a minor exception to this rule.  Its minimum 
density is 75 dpi.  This was done as the HP LaserJet (not the Plus or II) has
so little internal memory that 75 dpi is the only density at which it is able
to output a full page.



TRANSFER.C
----------

This is the heart of the new printer drivers which consists of 2 parts -
dithering and then rendering an entire row of source pixels.

Dithering is the process of thresholding, grey-scale dithering, or color
dithering each destination pixel.  If PInfo->pi_threshold is non-zero,
then the dither value is PInfo->pi_threshold ^ 15.  If PInfo->pi_threshold
is zero, then the dither value is computed by

	*(PInfo->pi_dmatrix + ((y & 3) * 2) + (x & 3))

where x is initialized to PInfo->pi_xpos and is incremented for each of the
destination pixels.  Since the printer device uses a 4x4 dither matrix, you
must calculate the dither value exactly as given above.  If you don't, you
will be writing a non-standard driver and the results will be unpredictable.

Rendering is the process of putting the pixel in the print buffer based on
the dither value.  If the intensity value for the pixel is greater than the
dither value as computed above then the pixel should be put in the printer
buffer.  If it is less than the dither value, skip it and process the next 
pixel.

 Printer     Type of
 ColorClass  Dithering      Rendering Logic
 ----------  ------------   -----------------------------------

 PCC_BW      Thresholding   Test the black value against the threshold value
                            to see if you should render a black pixel.

             Grey Scale     Test the black value against the dither value
                            to see if you should render a black pixel.

             Color          NA

                            (see HP_LaserJet transfer.c file)

PCC_YMC      Thresholding   Test the black value against the threshold value
                            to see if you should render a black pixel. Print
                            a yellow, magenta, and cyan pixel to make black.

             Grey_Scale     Test the black value against the dither value
                            to see if you should render a black pixel. Print
                            a yellow, magenta, and cyan pixel to make black.

	     Color          Test the yellow value against the dither value
                            to see if you should render a yellow pixel.
                            Repeat this process for magenta and cyan.     

                            (see CalComp_ColorMaster2 transfer.c file)

PCC_YMCB     Thresholding   Test the black value against the threshold value
                            to see if you should render a black pixel.

             Grey_Scale     Test the black value against the dither value
                            to see if you should render a black pixel.

             Color          Test the black value against the dither value to 
                            to see if you should render a black pixel.  If
                            black is not rendered then test the yellow value
                            against the dither value to see if you should 
                            render a yellow pixel and repeat for magenta
                            and cyan.

                            (see EpsonQ, EpsonX or Xerox_4020 transfer.c file)

PCC_YMC_BW   Thresholding   Test the black value against the threshold value
                            to see if you should render a black pixel.

             Grey_Scale     Test the black value against the dither value
                            to see if you should render a black pixel.

             Color          Test the yellow value against the dither value
                            to see if you should render a yellow pixel.
                            Repeat this for magenta and cyan.

                            (see Okimate_20 transfer.c file)

In general, if black is rendered for a specific printer dot then the YMC
values should be ignored since the combination of YMC is black.  Also I
recommend that you construct your print buffer so that the order of colors
printed is yellow, magenta, cyan, black.  This is most important on color
ribbon printers because it reduces the amount of ribbon color contamination.
If you print black and then yellow, the yellow ribbon will get some black
ink on it.

The bulk of the execution time of a graphic dump is spent in this call.  So
this module is an excellent candidate for down-coding to 68000 assembler.  
Experiments here at Commodore have shown that down coding transfer.c can halve
the time for a graphic dump.


DOSPECIAL.C
-----------

The dospecial.c module implements the special ANSI functions which cannot be
handled by substitution.  For instance, if you are writing a driver for a 
page oriented printer such as  the HP LaserJet, you should delete the dummy 
Close routine from the init.asm file and insert a real Close routine in
dospecial.c.  The Close routine is responsible for ejecting the paper after 
text has been sent to the printer and the printer has been closed.   

Some printers lose data when sent their own reset command.  For this reason,
I recommend that if you are using the printer's own reset command that you
define the variable PD->pd_PWaitEnabled to be a character that the printer 
will not print.  Put this character in the reset string in data.c before and 
after the reset character(s).  For example, in the EpsonX dospecial.c source 
code you will see the line:

    if (*command == aRIS) {         /* reset command */
        PD->pd_PWaitEnabled = 253;  /* same as \375  */
    }

and in the data.c file the string for reset is "\375\033@\375".  This means 
that when the printer device goes to output the reset string "\033@", it
will first eat the "\375" and wait one second.  The "\033@" will be passed 
and the printer will reset.  Finally, the printer device will eat the second
"\375" and wait one more second.  This insures that no data will be lost if 
a reset command is imbedded within a string as in "Hello \033#1world", where
\033#1 is the code for reset.



DATA.C
------

The data.c module implements the special ANSI functions which can be handled
by simple substitution.  It also contains the extended character translation 
table if you choose to include it.  Data.c has been changed a little for V1.3.

Typefaces
---------

There is now support for selecting different typefaces.  Due to the extended
character translation table, the character set selection commands (aFNT0 -
aFNT10) are no longer really needed.  If you want your driver to support
different typefaces you can use the FNT commands to select typefaces 0
through 10.  Please include comments in the data.c file that tell which
typefaces are selected by which commands.  The recommended standard for
for selecting typefaces can be found in devices/printer.h.


Raw Mode:
---------

There is now an escape sequence command (aRAW) which sets the printer device
into raw mode for a given number of characters.  In raw mode, no translation
of the data is done.  This command can be used to send commands directly to 
the printer from the CLI.  

The format is ESC[Pn"r where Pn is an ascii digit argument specifying that 
the next Pn characters are not to be translated, but sent directly to the 
printer.  For example, ESC[5"r means that the next 5 characters are to be 
sent directly to the printer.  For future compatibility, you should also
add a dummy entry of \377 in the data.c table.


TESTING
-------

A comprehensive test of your printer driver is an important step and I
have some recommendations.

    First, do a black and white (threshold = 7), grey scale, and color dump 
of the same picture.  The color dump should be in color.  The grey scale dump 
should look like the color dump except it will consist of patterns of black 
dots - sort of like looking at a BW television.  The black and white dump 
will have areas of solid black and areas of solid white.  

    Next do a dump with the DestX and DestY dots set to an even multiple of 
the XDotsInch and YDotsInch for your printer.  For example, if your printer 
has a resolution of 120 x 144 dpi, do a 480 x 432 dump.  The printed picture 
should be 4 x 3 inches on the paper.  If the width of the picture is off 
then you have put the wrong value for XDotsInch in printertag.asm.  If the 
height of the picture is off then you have put the wrong value for YDotsInch 
in printertag.asm.

    Test your driver at its maximums.  Do a color dump as wide as the printer
can handle with the density set to 7.  Use the PrinterTest program on the 
devcon disk to give the alpha commands a real workout.

    Check to make sure that your printer doesn't force graphic dumps to
exist within text margins.  An easy test would be to set the text margins 
to 30 and 50, pitch to 10 cpi and then do a graphic dump that would be wider
than 2 inches.  If the printout is left justified and is as wide as you asked 
for then all is fine.  If the printout starts at character position 30 and is
cut off at character position 50 then you'll need to make some changes to
your driver.  

     The changes involve clearing the margins before the dump (case 0) and 
restoring the margins after the dump (case 4).  Refer to the any of of driver's
render.c source code for an example.  Note that before the graphic dump you 
must send some text (even just a carriage return) to the printer to get the 
printer device to initialize the printer.  Optionally, you could invoke the 
InitPrinter program before the graphic dump.

     As a final test, construct an image with a white background that has 
objects in it surrounded by white space.  Dump this as a BW, grey scale, and 
color printout.  This will test your white-space stripping or run-length 
encoding and your ability to handle null lines.  Note that the non-white data 
areas should be separated by at least as many lines of white space as the 
NumRows value in your printertag.asm file.  The diagram below should help.

				Display Area
	 ---------------------------------------------------------------
	|								|
	|	 -----------------------				|
	|	|			|				|
	|	| non-white data	|				|
	|	|			|				|
	|	 -----------------------				|
	|								|
	|		white background				|
	|								|
	|		 -----------------------			|
	|		|			|			|
	|		| non-white data	|			|
	|		|			|			|
	|		 -----------------------			|
	|								|
	 ---------------------------------------------------------------

