Amiga ISO Collection/AmigaUtilCD1.iso/GFX/Cad/INTROCAD1.9.DMS/in.adf/PrtDef/PrtDef_Docs/prtdef.doc

Text File | 1987-12-15 | 23.2 KB | 576 lines

          An author's description of IntroCAD PrtDef files


    A printer definition file ("PrtDef›0m" file) describes, to IntroCAD, the
physical specifications of a single printer when it is in (one or each of its
several) graphics mode(s).  Normally, a PrtDef›0m file also contains information
about the escape sequences which are to be sent to the printer along with
graphics data.

    Alternatively, a PrtDef›0m file can be used to describe a "virtual
printer" for the purpose of generating a file which is to be translated into
printer commands and data for an actual printer that IntroCAD cannot be made
to support directly.  In such a PrtDef›0m file it might be convenient to include
messages to the translator program in place of or in addition to the printer
escape sequences.


    First, the format of a PrtDef›0m file.  The first line of the file must
begin with the word "PrtDef›0m" followed by whitespace.  The rest of the line
may contain anything at all including nothing.  The remainder of the file is
divided into two sections: the color information section and the graphics
mode description section.  (There is no separating blank line between these
sections, nor are there blank lines between the several graphics mode
descriptions.  Generally, a PrtDef›0m file may contain no blank lines.)

    To simplify the following text, let's agree from the start that a
number can be called a "word", since it is an uninterrupted sequence of
non-blank characters.  Numbers which are to be part of escape sequences to be
sent to the printer must be given as two hexadecimal digits.  With one
general exception--the representation of bit masks--all other numbers in
a PrtDef›0m file are decimal.

    Most of a PrtDef›0m file is escape sequences.  These are always
represented in the file on a single line in the following manner:
    D H H H H›0m ... H›0m
where D›0m is the decimal number of H›0m's that occur on the line, and where
each H›0m is a hexadecimal number that can be encoded into a single byte.
D›0m is not part of the escape sequence.


*********************************
* THE COLOR INFORMATION SECTION *
*********************************›0m

    The color information section occupies a variable number of lines.
Generally the number is one greater than the number of colors the printer
supports, but for the special case of a one-color printer the entire color
information section is a single line with a zero in column 1.  For
color-capable printers, the section is terrifically easy to write once the
format is understood.  Unfortunately, the format is quite a bit more
difficult to describe than to understand, and so this description is
long and careful.

    The color information section is divided into three parts.  Part
one describes the color capability of the printer to IntroCAD. Part two
lists lists the colors available on the print ribbon, characterizes those
colors with "names›0m" (hexadecimal numbers that represent one byte bit masks),
and includes the escape sequences which select those colors.  Part three
lists the colors which can be printed by mixing two or more of the colors
on the print ribbon and indicates which colors to mix, again with one-byte
bit masks.


COLOR INFORMATION: Part 1›0m

    Part one is a single line which contains four words.  The first word
is the number of different colors available on the printer ribbon--these
colors will be called "pcolors›0m" in this description; we'll say there are
#pcolors›0m of them.  The printer is assumed capable of switching freely between
pcolors›0m, but will never be directed by IntroCAD to switch in the middle of a
line of graphics.

    The second word is the number of additional colors that can be
printed by mixing two or more of the ribbon colors--these colors will be
called "scolors›0m" here; we'll say there are #scolors›0m of them.

    Word three of part one specifies the correspondence between IntroCAD
color numbers and printer color numbers.  IntroCAD color numbers run from
zero to fifteen: from left to right and top to bottom as seen in IntroCAD's
"Color" menu; from left to right as seen in IntroCAD's palette requester.
Printer numbers run from zero to (#pcolors›0m + #scolors›0m - 1) in the order in
which the lines describing them occur in the PrtDef›0m file.  It is assumed that
(part of) the range of colors in IntroCAD exactly reproduces the range of
colors available from the printer.

    Calling the number represented in word three "c_off›0m", the printer
color which corresponds to a given IntroCAD color is:
    Printer_color = ((IntroCAD_color + c_off›0m) % (#pcolors›0m + #scolors›0m))
where "%" is the modulus operator.

    The fourth and last word is a hexadecimal number.  It represents
the one-byte code which directs the printer to perform a carriage return
without advancing the page.


COLOR INFORMATION: Part 2›0m

    Part two of the color information section comprises #pcolors›0m
lines.  The first word on each line is the hexadecimal number which forms a
one byte bit map--by which bit map the color is "named›0m".  There is
absolutely no flexibility in this "naming›0m" system: the first color is "named›0m"
"01›0m", the second "02›0m", the third "04›0m", the fourth "08›0m", and so on.  IntroCAD
will enforce this if you don't.  The names, then, give IntroCAD no
information; they are there for your use in writing part three of the
color information section.
    The remainder of each pcolor›0m line represents an escape sequence:
a decimal number followed by exactly that many two-digit hexadecimal
numbers.  The hex numbers form the escape sequence which is to be sent to
the printer to select the pcolor›0m.  There may be at most five bytes in a
color selection escape sequence.
    Printer manufacturers generally recommend that light colors be
printed first when colors are to be mixed.  IntroCAD prints pcolors›0m in the
order in which they appear in the PrtDef›0m file.


COLOR INFORMATION: Part 3›0m

    Part three of the color information section comprises #scolors›0m lines
of one word each.  The word is the hexadecimal number which is the sum of the
"names›0m" of the pcolors›0m, given in the previous section, which are to be
combined to print the scolor›0m.



*****************************************
* THE GRAPHICS MODE DESCRIPTION SECTION *
*****************************************›0m

    There may be up to four graphics mode descriptions in a PrtDef›0m file;
each description takes six lines which I'll describe one by one.  (Refer to
the appended template files.)

    Line one contains instructions to IntroCAD.  This line is very much
more complicated than the rest and so each word on the line will be explained
in detail.

    The first three words on line 1 will be displayed in an Amiga
requester so that the user can know some details of the available graphics
modes.  The first word should be five characters long and followed by a
blank because the first six characters of the line are copied verbatim for
use in the requester; this word should tersely describe the printout a user
can expect from the graphics mode.

    The second and third words are, respectively, the horizontal and
vertical resolutions of the printer expressed in dots per inch.  The fourth
and fifth words are the total numbers of dot locations available on a
page--again, horizontally and vertically, respectively.  These specify the
page size to IntroCAD since the dot resolution has been given.  The number
of dots horizontally usually must agree with information specified later in
an escape sequence.  There is no limit to the vertical size of the page,
but if the number of vertical dot locations is specified as zero, IntroCAD
will enforce the default vertical page size of ten inches.  The sixth word
is the number of print head pins to be used for graphics printing.  The
number of pins must be one of the following: [1,2,3,4,5,6,7,8,16,24].

    The seventh and last word on line 1 is the "interlace level›0m".  The
interlace level›0m is one less than the number of passes the print head must
make for each "strip›0m" of printing.  (Here, a "strip›0m" is the area covered by a
single pass of the print head.)  Only printers which use eight or fewer pins
for graphics can be made, by IntroCAD, to produce interlaced printouts.  For
printers which use more than eight pins, the interlace level is ignored but
should, for clarity's sake, be zero.

    Lines two through six normally contain printer escape sequences
encoded in the usual way.  IntroCAD derives no information from these
sequences, but simply converts them to sequences of binary bytes and
parrots those to the printer at the appropriate times.  There may be at
most 24 bytes in each of these escape sequences.

    The first word in each escape sequence line is different from the
rest: it is not part of the escape sequence.  It is the (decimal) number of
bytes in the escape sequence.  It is, therefore, the number of hexadecimal
numbers which follow on the rest of the line.

    Line two contains the printer initialization sequence.  This line is
called "INIT›0m" in the template file.  The INIT›0m sequence is sent once before
printing starts.  Normally this sequence resets the printer and sets the
distance the paper is advanced by the line feed command which will be defined
in line four or five.  Some printers are capable of bi-directional graphics
printing; for these, the initialization sequence must disable the capability
because IntroCAD cannot take advantage of it.  Also, it is a good idea to
include one or more line feeds in this sequence so that the paper tension
during the first pass of the print head will be the same as that during the
remaining passes.

    Line three contains the escape sequence which readies the printer to
receive graphics data.  This line is called "GSTART›0m" in the template file.
It is sent before each pass of the print head.

    For most printers, the GSTART›0m sequence contains either the number of
horizontal locations the print head can assume or the total number of bytes
of graphics data which will be sent during a single pass of the print head.
The number is used by the printer to distinguish graphics data from escape
sequence data and printer manuals normally specify the maximum value of this
number for each graphics mode.  The number must agree with the number on line
one of the graphics mode description which tells IntroCAD how many dots to
print horizontally.

EXAMPLE: For the Epson_LQ-1000 printer.
    The INIT›0m line for the "QUICK" graphics mode is:
        "QUICK 60 60 480 0 8 0›0m"
    The GSTART›0m sequence line for this mode is:
        "4 1B 4B E0 01›0m"
    Here, "E0 01›0m" is the Epson method of specifying the
    number 480--the number that occurs on the INIT›0m line.

    Some printers implement a different method of distinguishing graphics
data from escape sequence data: a special character, different from any
possible graphics data "character", is used to end graphics printing.
IntroCAD does not support such printers directly unless very special and
difficult-to-describe circumstances obtain.  A translator program is normally
required.

    Line four contains the escape sequence which is sent immediately
after a complete strip›0m of graphics data.  This line is called "STRIP_FEED›0m"
in the template file.  For non-interlaced printing, a complete strip›0m is
the data for a single pass of the print head.  For interlaced printing it
is the data for (interlace level›0m + 1) passes, plus the "LACE_FEED›m" escape
sequences--described later--which are sent after each pass but the last.
For non-interlaced printing, this sequence normally instructs the printer
to simply do a carriage return and line feed.

    Line five is ignored if the interlace level›0m specified on line one
is zero.  Otherwise, it contains the escape sequence which instructs the
printer to do a carriage return and the tiny paper advance appropriate
for interlaced printing.  This line is called "LACE_FEED›0m" in the template
file.

    The sixth and last line contains the escape sequence sent after
printing is finished.  This line is called "CLOSE›0m" in the template
file.  Normally this will be simply a form feed.



*****************
* SPECIAL NOTES *
*****************›0m

    About the data bytes: The most significant bit of the first byte
maps to the topmost pin of the print head, the MSB of the second byte (if
there is one) maps to the ninth pin from the top, and so on.  This
assumption, on the part of IntroCAD, is perhaps the major source of
incompatibility with printers IntroCAD doesn't support.

    The size of a line feed, normally encoded into the INIT›0m escape
sequence should be equal to the number of print head pins used for graphics
multiplied by the pin spacing.  Printer manuals rarely document the pin
spacing and one must usually resort to trial and error here.  For eight pin
printers, the spacing is normally either two or three times the smallest
possible page advance: if that advance is 1/216 in. or 1/144 in., the pin
spacing is almost certainly 1/72 in.--a very common spacing.  For 16 and 24
pin printers emulating eight pin graphics modes, the pin spacing is usually
either 1/60 in. or 1/80 in.


    There is a potential problem with serial printers because the author
of the PrtDef›0m file cannot know in advance whether or not the MSB of each data
byte will be appropriated by the SER: device for use as a parity bit.  The
user has complete control of this bit via Preferences.  If this bit is
unavailable for graphics and the PrtDef›0m file indicates that all eight bits
are to be used, narrow horizontal blank lines will occur in the printout.
(Normally though, blank lines indicate an inappropriate line feed size.)
It seems like a bad idea to limit all PrtDef›0m files to seven bits as a
method of avoiding this problem, since most printers do not communicate
serially.  For 16 and 24 pin serial printers, parity cannot ever be used
because IntroCAD demands all eight bits of every data byte.


    For some printers, there is a hidden difficulty that makes the
writing of a PrtDef›0m file for interlaced or color printing almost into a
matter of trial and error.  The difficulty is that many printers buffer data
as it arrives and only print the buffered data on receipt of one of a small
number of control codes.  (The code for a carriage return can usually be
relied on to cause a buffer flush.)  For such printers, the STRIP_FEED›0m
command must always contain one of those special codes.

    Interlaced and color printing can present apparent problems with
these printers if 1) the desired LACE_FEED›0m and COLOR_SELECT›0m escape
sequences don't happen to contain buffer-flushers, and 2) the printer's
buffer isn't large enough to contain more than a single line of graphics.
The problem is especially difficult if the only buffer-flusher is a
combined carriage return/line feed.



***************************************
* IMPLEMENTING AND USING A TRANSLATOR *
***************************************›0m

    If IntroCAD cannot be made to support a certain printer, at least a
program can be written to translate IntroCAD's output into something that
printer will accept.  Since IntroCAD can direct its output to a file, as well
as to the PAR: and SER: devices, the use of a translator is certainly
practical.  Since the Amiga multitasks, such use can be nearly transparent.
Obviously, writing a translator requires detailed knowledge of the file
IntroCAD is to write.

    At the time you write the PrtDef›0m file, you will know some of the
numbers which describe the file IntroCAD will write.  The number of dots to
be printed horizontally, for example, is "hardwired" into the file.  You can
cause the INIT›0m string to contain a message to the translator program, giving
it this information.  This might be nice if you want to use more than one
printer resolution and don't want to have to keep track of sevaral
translator programs.

    You can never know in advance, however, what the number of dots to
be printed vertically will be since it depends on the drawing and how it is
scaled.  All that's required to work around this problem is the ability, on
the part of your translator, to distinguish the CLOSE›0m string from the
GSTART›0m string--quite easy if the CLOSE›0m string is a form feed.

    Your translator will probably need to know how many bytes each
escape sequence comprises.  The easiest way might be to prepend the number
to the sequence--that is, put the (hex) number in the PrtDef›0m file so that
IntroCAD will write it as the first byte of the sequence, and arrange that
the translator "eat" the byte and send the rest of the sequence to the
printer.

    Certainly you can get IntroCAD to "print" the graphics to disk or
to RAM:.  It would be nice if you didn't have to manually run your
translator in the background each time you printed a drawing, though.
Also, it would be nice if you didn't have to always have enough space
available (possibly as much as a megabyte) for an entire print dump.
There are two solutions I know of.

1)    Use Matt Dillon's PIPE: device.  This solves the memory problem,
       but you still have to run a background job each time you print.
       An example: you tell IntroCAD to print to the "file" PIPE:myfile.
       In a background CLI, you run the command
              "translate PIPE:myfile PAR:".
       Here I've assumed your program is called "translate" and that it's
       first command line argument is the name of the input file.
       To run the translator, you will need to remember "Left-Amiga-M"
       brings the Workbench screen to the front because IntroCAD has no
       screen gadgets.

2)    Write an Amiga device driver.  (I don't mean a printer driver
    here, although it might be possible to combine the translator
    function with general purpose printing.)
    This is the prettiest solution, but undoubtedly has the steepest
    learning curve.



**************************************
* APPENDIX A: PrtDef template files. *
**************************************›0m


-------------- for black-only printers ------------------------------------
PrtDef filename "company name"›0m
0›0m
QUICK Hdpi Vdpi HDots VDots PrtWires Interlace›0m
INIT›0m
GSTART›0m
STRIP_FEED›0m
LACE_FEED›0m
CLOSE›0m
DRAFT Hdpi Vdpi HDots VDots PrtWires Interlace›0m
INIT›0m
GSTART›0m
STRIP_FEED›0m
LACE_FEED›0m
CLOSE›0m
FINAL Hdpi Vdpi HDots VDots PrtWires Interlace›0m
INIT›0m
GSTART›0m
STRIP_FEED›0m
LACE_FEED›0m
CLOSE›0m
---------------------------------------------------------------------------

---------------- for color printers ---------------------------------------
PrtDef filename "company name"›0m
#pcolors #scolors color_offset CR_no_LF›0m
01 codes for pcolor #0›0m          \               \
02 codes for pcolor #1›0m           | primary       | if no colors,
04 codes for pcolor #2›0m           | colors        | these lines
.                                |               | do not occur
.                                |               | in PrtDef file.
.                               / ________       | There must be exactly
smask1›0m  smask is logical AND    \                | (#pcolors + #scolors)
.       of above pmasks          | secondary     | lines here.
.       (01, 02, 04...) for      | colors        |
.       pcolors which contribute |               |
.       to this scolor           |               |
smaskn›0m                          /               /
QUICK Hdpi Vdpi HDots VDots PrtWires Interlace›0m
INIT›0m
GSTART›0m
STRIP_FEED›0m
LACE_FEED›0m
CLOSE›0m
DRAFT Hdpi Vdpi HDots VDots PrtWires Interlace›0m
INIT›0m
GSTART›0m
STRIP_FEED›0m
LACE_FEED›0m
CLOSE›0m
FINAL Hdpi Vdpi HDots VDots PrtWires Interlace›0m
INIT›0m
GSTART›0m
STRIP_FEED›0m
LACE_FEED›0m
CLOSE›0m
---------------------------------------------------------------------------

--------------- sample PrtDef›0m file ----------------------------------------
PrtDef Epson_JX-80 "Epson America, Inc."›0m
4 4 7 0D›0m
01 3 1B 71 34›0m !yel
02 3 1B 71 32›0m !cyn
04 3 1B 71 31›0m !mag
08 3 1B 71 30›0m !blk
03›0m  !grn
05›0m  !org
06›0m  !blu
0C›0m  !brn
QUICK 60 72 480 0 8 0›0m
11 1B 40   1B 23   1B 55 01   1B 33 18 0A›0m
4  1B 4B E0 01›0m
2  0D 0A›0m
0›0m
3  0C 1B 40›0m
DRAFT 120 72 960 0 8 0›0m
11 1B 40   1B 23   1B 55 01   1B 33 18  0A›0m
4  1B 59 C0 03›0m
2  0D 0A›0m
0›0m
3  0C 1B 40›0m
FINAL 240 216 1920 0 8 2›0m
12 1B 40   1B 23   1B 55 01   1B 33 01   0A 0A›0m
4  1B 5A 80 07›0m
2  0D 0A›0m
9  0D 0A   1B 33 16   0A   1B 33 01›0m
3  0C 1B 40›0m
---------------------------------------------------------------------------



********************************************
* APPENDIX B: Details of the print output. *
********************************************›0m

    Probably the best way to concisely illustrate the format of the print
output is to give pseudo-code examples of the routine that generates that
output.  In the following examples, the words INIT›0m, GSTART›0m, STRIP_FEED›0m,
LACE_FEED›0m, CLOSE›0m, and CR_no_LF›0m refer to the escape sequences named and described above.


--- non-interlaced black-only printing ------------------------------------
send INIT›0m
for (i=0; i<num_lines; i++) {
   generate DATA
   if any of DATA are non-zero {
      send GSTART›0m
      send DATA
   }
   send STRIP_FEED›0m
}
send CLOSE›0m
---------------------------------------------------------------------------


--- black-only printing with Interlace = 1 --------------------------------
send INIT›0m
for (i=0; i<num_lines; i++) {

   generate PASS_0_DATA and PASS_1_DATA

   if any of PASS_0_DATA are non-zero {
      send GSTART›0m
      send PASS_0_DATA
   }
   send LACE_FEED›0m

   if any of PASS_1_DATA are non-zero {
      send GSTART›0m
      send PASS_1_DATA
   }
   send STRIP_FEED›0m
}
send CLOSE›0m
---------------------------------------------------------------------------


--- black-only printing with Interlace = 2 --------------------------------
send INIT›0m
for (i=0; i<num_lines; i++) {

   generate PASS_0_DATA, PASS_1_DATA, and PASS_2_DATA

   if any of PASS_0_DATA are non-zero {
      send GSTART›0m
      send PASS_0_DATA
   }
   send LACE_FEED›0m

   if any of PASS_1_DATA are non-zero {
      send GSTART›0m
      send PASS_1_DATA
   }
   send LACE_FEED›0m

   if any of PASS_2_DATA are non-zero {
      send GSTART›0m
      send PASS_2_DATA
   }
   send STRIP_FEED›0m

}
send CLOSE›0m
---------------------------------------------------------------------------


--- non-interlaced color printing (2 primary colors) ----------------------
send INIT›0m
for (i=0; i<num_lines; i++) {

   generate COLOR_0_DATA and COLOR_1_DATA

   if any of COLOR_0_DATA are non-zero {
      send SET_COLOR_0
      send GSTART›0m
      send COLOR_0_DATA
      send CR_no_LF›0m
   }

   if any of COLOR_1_DATA are non-zero {
      send SET_COLOR_1
      send GSTART›0m
      send COLOR_1_DATA
      send CR_no_LF›0m
   }

   send STRIP_FEED›0m

}
send CLOSE›0m
---------------------------------------------------------------------------


--- color printing with Interlace = 1 -------------------------------------
send INIT›0m
for (i=0; i<num_lines; i++) {

   for (j=0; j<num_primary_colors; j++)
      generate PASS_0_DATA[j] and PASS_1_DATA[j]

   for (j=0; j<num_primary_colors; j++) {
      if any of PASS_0_DATA[j] are non-zero {
         send SET_COLOR[j]
         send GSTART›0m
         send PASS_0_DATA[j]
         send CR_no_LF›0m
      }
   }
   send LACE_FEED›0m

   for (j=0; j<num_primary_colors; j++) {
      if any of PASS_1_DATA[j] are non-zero {
         send SET_COLOR[j]
         send GSTART›0m
         send PASS_1_DATA[j]
         send CR_no_LF›0m
      }
   }

   send STRIP_FEED›0m

}
send CLOSE›0m
---------------------------------------------------------------------------

Tim Mooney  12/7/87