
APPLE IIGS IMAGEWRITER LQ PRINTER DRIVER 4.2 	--		TECHNICAL DESCRIPTION (ERS)



High-level driver and low level speed optimizations written by Ben Koning

Low-level imager originally written by Jason Harper



June 1991



GENERAL

The ImageWriter LQ printer driver, initial version 4.0, is a genuine
Apple IIGS printer driver which takes full advantage of the resolution
inherent in the 'LQ.  It should be installed with the following pathname
and type:

*/SYSTEM/DRIVERS/IMAGEWRITER.LQ		type=$BB	auxtype=$0001

This driver contains the new type of entry point (starting with the zero
byte), and uses pop-up menus and the improved Control Manager tool set.
Therefore, it will only operate on System Disk 5.0 or later.

A new call, PrGetPrinterSpecs, is supported, which checks to see if the
device connected is really an ImageWriter LQ and returns information regarding
the existence of a color or black/white ribbon.



DIALOGS AND USER COMMUNICATION

Existence or nonexistence of the Cut Sheet Feeder and Color Ribbon options
is manifested by enabled or disabled (dimmed) items in the Job Dialog, even
if printer over a direct-connect port driver; the printer is actually polled
to check for these items.  WARNING: A new version of the various port drivers,
which offer nonblocking I/O to direct-connect devices, should be available.
Otherwise, if no printer is on-line, selecting the Job Dialog will cause the
system to hang.  If a port driver which does support nonblocking I/O (such as
AppleTalk) and the printer isn't on line, the Job Dialog call issues an alert
and returns the portNotOn tool error code.

Pop-up menus and the new control manager calls are used; better progress
indicators showing the number of sheets left to print, printer port error
messages with priority, etc., have been implemented.  All text is located
within one source code file for easy localization.

If the Shift-Option-Apple keys are down while the PrStlDialog or PrJobDialog
is being called, an about box will appear.

If bit 15 of wDev is set in the print record (by an application), then the
status message box usually displayed during the printing process is not shown.
The cursor is still changed to WaitCursor/InitCursor, however, and the manual
feed dialog box is still shown if required.



NEW DRAFT (TEXT) PRINTING FEATURES

For draft printing, a mini-spooling method (see below for the actual spooling
methodology) has been implemented which allows multiple-copy draft-mode printing
to work (most applications do not print more than one copy when requested in
draft mode when the ImageWriter II driver is selected).  Applications which
repeat the printing loop in order to print the extra copies should set the
oiCopies field of the print record to 1 before executing the printing loop(s).
In addition, this methodology allows top-to-bottom printing, so that reverse
paper feed (which isn't possible because of the way the Cut Sheet Feeder works)
is not necessary.

In draft printing, font attributes such as boldface, underline, italic, point
size, and font name, as well as special international characters, are all
considered dynamically while selecting an appropriate native 'LQ ASCII
characters.  The code is optimized so that characters are sent to the printer
in blocks.  These blocks are flushed when an international character is printed
or when the end of a QuickDraw string is reached.  Thus, printing many small
strings or many consecutive international characters will result in lower
speed performance.



"SPOOL" (GRAPHICS) PRINTING FEATURES

Standard-resolution graphics printing and 3X Letter-Quality graphics printing
are offered, with 50% vertical condense and 100/66/33-% life size scaling
options, in portrait or landscape orientations.  Unidirectional head scan
and boldface are also supported.

In the 3X high-quality ("Better") graphics mode, the off-screen graphics are
drawn at 300% life size, resulting in improved resolution for mathematically
defined QuickDraw objects such as ovals, rects, roundrects, etc., as well as
fonts, provided large font sizes are installed in the current system.  The 'LQ
then prints them using 3 times the number of printer pixels/inch, resulting in
an image with the same measurements at three times the resolution for near-
laser printer quality.

Thus, the meanings of the names in the Print Quality dialog item are as follows:

Name				Meaning
----				-------
Draft Mode		ASCII text only; however, 'LQ has really nice-looking fonts
Standard			Graphics; Drawn offscreen at 1X and printed at LQ or IW resolution
Better			Graphics; Drawn offscreen at 3X and printed at LQ resolution



SPEED PERFORMANCE ENHANCEMENTS

The pixelmap-to-printer-graphics-command code (the heart of the imager) has
been modified to support ImageWriter II - style graphics command output if a
certain internal bit is set.  This mode is enabled by the higher level print
driver routines whenever Standard Mode, Portrait Orientation, Fullsize Reduction,
and not Darker has been selected.  Its advantage is much greater speed.

While converting pixels from the offscreen bitmap to printer-ready graphics data,
a trivial-white-space elimination catalyst algorithm has been implemented.  It
attemps to determine the value of a 2-byte word full of white pixels, in order to
skip over large white areas very quickly.  A very general-case version of this
algorithm is in place in portrait mode and a limited version (with more
restrictions) is in place in landscape mode.

For certain very special (but common) cases (640-mode portrait with hscaling=1),
pure black/white pixels whose RGB values come from standard color table locations
are imaged especially quickly.

Before the printer-ready pixel data is sent to the port driver, it is broken up
into chunks of zero, nonzero repeating, and nonzero nonrepeating head-fire byte
groups, and the 'LQ's positioning, print-repeating-graphics, and print-non-
repeating-graphics commands are issued accordingly.  This run-length-encoding
scheme greatly improves speed performance while improving compactness of data to
be sent across communication channels or stored up in a background printing
spooler.



DATA SPOOLING METHODOLOGY

The new psuedo-"virtual memory" spool method is used by both the Draft (text)
and Standard/Better (graphics, or "spool") printing modes.

For spool printing, memory is allocated to memory and then disk virtually,
thus allowing arbitrary-length documents to be spooled, assuming enough disk
space is available, unlike the older ImageWriter driver. During the actual
printing, the band buffer size is also dynamically allocated; in many cases,
only one band and banding pass is necessary.  Still, the standard (Command-Period
abort) and user-installed idle procedure is called at least four times as often
as in the older printer driver, resulting in better abort-command response time.

During print spooling, memory is allocated a block at a time, optionally
controllable by setting pFileBlockSize in the print record.  When total memory
in the system becomes less than a certain threshold, optionally controllable by
setting pFileMemLimit in the print record, the entire spool file in memory is
flushed to disk, and the memory space already allocated is subsequently used as
a buffer which is repeatedly flushed to disk when it fills up.  Memory is
allocated with a user ID whose "type" field is $1000.

If spooling to disk becomes necessary, the default pathname, optionally
controllable by modifying pFileName (which is set to long 0 by default)
in the print record, is:

*/SYSTEM/DRIVERS/TMP.XXXX		type=$00	auxtype=$0000 access=%Drb---WR

where the trailing X's are replaced by a random hexadecimal number.  If such
a filename already exists, then a different random suffix is used.  If the
user supplies its own filename, then no such unique suffix addition is done;
supplying one's own filename is not recommended due to possible filename
collisions when using shared volumes.  When disk spool playback is finished,
the file is deleted, whether or not it was supplied by the user.



COMMAND-PERIOD/IDLE PROCEDURE

The internal Command-Period-abort idle procedure is always executed in addition
to any user-installed idle procedure, unlike earlier drivers.



NEW PRINT RECORD FIELDS

Several new fields have been defined in the print record.  Most are set to
default (0) values during print record initialization (PrDefault); they may
be left alone or modified by the advanced user:

New Field Name		Offset		Offset	Size		Description
--------------		------		------	----		-----------
internA				prStl+2		$1A		word		MasterSCB during PrValidate
pFileBlockSize		printX+0		$64		long		Chunkiness of spool mallocs
pFileMemLimit		printX+4		$68		long		Spool min mem left in system
pCTable				printX+8		$6C		long		Color table for imaging
pSCBList				printX+12	$70		long		SCB list for imaging
wQuality				printX+16	$74		word		Internal quality mode selection
wPaperCrWidth		printX+18	$76		word		Variable crWidth value
wResScaling			printX+20	$78		word		Blow-up amount for Better quality

pFileBlockSize and pFileMemLimit are discussed in the section about the data
spooling algorithm above.  internA is examined by PrPicFile during banding buffer
memory allocation, for example.

If pCTable and PSCBList are left alone, the PrPicFile call will print with
the current screen color table and SCB list.  Alternatively, the user may
write their own pointers at these locations in the print record, so as to
avoid having to change screen colors.  Note that this will affect the entire
document being printed, however (unless they were changed in the recorded
picture definition by certain PicComments; see the section "COLOR CONTROL").

The following table describes the behavior of wQuality, along with two other
data in the print record which define the current print quality/method selection:

Name			wDev "Better" (bit)	bJDocLoop (byte)	wQuality (word)	Internal code
----			-------------------	----------------	---------------	-------------
Draft Mode	%0							$00					0						0
Standard		%0							$80					1						1
Better		%1							$80					2						2

Since it appears that most applications expect the "crWidth" field, in the
print record at offset oprStl+ocrWidth, to contain a constant value of 960 for
historical reasons, the new wPaperCrWidth field will contain actual carriage
width information based on the current paper type in use.  One of the uses of
this new field is to communicate from the metrics calculations to the imager in
order to inform the latter of where the right margin is for doing landscape, etc.,
based on the width of the current paper type.

The wResScaling is a constant which describes how much this printer driver scales
up the image (just prior to scaled-down printing at finer dot pitch) in order to
obtain higher resolution.



COLOR CONTROL WITHIN DOCUMENT

The SCBs/Color Tables used during the imaging of each page are taken from the
current screen values unless overridden by certain actions taken by the applica-
tion.  None of these actions will ever affect the colors on the display screen.

The colors used for imaging are taken from the following sources, starting with
the highest priority:

		1. pCTable/pSCBList print record fields, if not set to 0 (see above)
		2. PicComments (see below)
		3. Current screen values

Since PicComments are recorded as part of a picture definition, inserting these
PicComments provides a method of changing colors on the fly in a document.
Following the convention that all grafport settings are reset to default values
when each _PrOpenPage is called, all colors are assumed to be the current screen
values unless overridden by a PicComment unless overridden by field in the print
record.

Thus, for custom colors, the following PicComment should be made right after each
_PrOpenPage call, before doing any drawing:


		PICCOMMENT KIND=251 -- Fill A Color Table With New Values

		version			WORD			set to 0
		signature		WORD			set to $A55A
		tableno			WORD			set to 0..15 -- the table to be modified
		table				WORDS [16]	set to the new values for the color table
		reserved			LONG			set to 0
		
		
		
In order to use these different colors, an application must also be able to
modify the SCB's for each line from their screen-default ($80 or $00) values.
This can be accomplished by issuing another type of PicComment:


		PICCOMMENT KIND=252 -- Change A (Range) Of SCB Values
		
		version			WORD			set to 0
		signature		WORD			set to $A55A
		Y1					WORD			line no. of first SCB to change (0..rPage.Y2)
		Y2					WORD			line no. of last SCB to change (0..rPage.Y2)
		SCBvalue			WORD			scanline-control-byte
		reserved			LONG			set to 0
		


The driver internally uses a PicComment of its own, to keep track of where a
new page starts within the spooled data area filled with picture definitions
representing a page each.  For reference only, it looks like this:
		
		
		
		PICCOMMENT KIND=250 -- End Of Page Marker (Internal Driver Use Only)
		
		version			WORD			set to 0
		signature		WORD			set to $A55A

