Graphics 16,000/graphics-16000.iso/msdos/viewers/showgl19/showhpgl.doc

Text File | 1992-08-18 | 23KB | 569 lines

SHOWHPGL    A viewing program for HP-GL and HP-GL/2 plotting programs.

Version 1.9


Introduction

This program is designed to preview HP-GL and HP-GL/2 plotting programs
on the console screen of an IBM PC or compatible computer.  It
impliments 47 of 97 HP-GL or HP-GL/2 instruction.  Of the 97
instruction, 22 either have no meaning for this type of program or
are otherwise unrelated to drawing.  Four instructions are included to
provide backward compatibility with the HP9872 plotter.  These instructions
are interpreted as NOP's.

It is written in Microsoft C, version 6.0.  It requires MS-DOS
version 3.0 or above to run.  This program is meant to be used as a
preview tools for HP-GL files.  It is as accurate as it could be made
with the limited information and resources available at the time it
was written.  Known bugs or deficiencies are listed after the
instruction set summary.

Version 1.9 adds solid fills to RR and RA (relative and absolute filled
rectangles), and fixes a bug which allowed drawing outside the hard clip
border when using IW (windowing).

Revision History

Version 1.9    17 August, 1992

- Added solid fill types to RA and RR.
- Added transparent data (TD) instruction.
- Fixed bug allowing drawing outside P1/P2 border using IW.


Version 1.8     8 August, 1992

- The LB command would not draw labels with more non-printing characters
  than printing characters.  This caused labels which used embedded
  backspaces for positioning to not be drawn.  Fixed.

- The LB command would not terminate properly at the end-of-file without
  a label terminator present.  Fixed.

- Relative text size on the CRT increased as paper size enlarged.
  'Should have decreased.  Fixed.

- IW clipping window incorrectly placed when P1/P2 (the corner
  hard clip limits) were not lower-left and upper-right, respectively.
  This resulted in no visible lines being drawn.  Fixed.  It also failed
  to restore the correct clipping when turned off if scaling was on.
  Fixed.

- DR drew characters in the wrong direction when P1/P2 were exchanged.
  Fixed.

- HP-GL/2 defaults to SI (absolute character sizes) at initialization
  (IN) or when issuing the DF (default) instruction, as does the
  DraftPro plotter.  However, the HP7475 and HP7470 plotters specify
  SR (relative character sizes for these cases.  Two switches were
  added (-70 and -75) to select relative character scaling as the
  default condition.

- XT and YT (tick drawing commands: not HP-GL/2 instructions) were able
  to draw ticks outside the P1/P2 hard clip border.  Fixed.  Also,
  tick length was not rescaling when P1/P2 changed unless TL was
  executed after P1/P2 changed.  Fixed

- Type 1 scaling (isotropic, with no left and bottom parameters
  specified) did not result in symmetric spacing on the axis which
  was lengthened to achieve isotropic scaling.  Fixed.

- A single pixel line would terminate the program with an integer
  divide overflow. Fixed.

- Filled rectangles didn't work properly if scaling was on.  Fixed.

- Operation of IR not clearly specified for the case of P1/P2 being
  exchanged.  IR as implimented is based on hard clip borders and
  assumes, for reference, P1 is the lower left corner and P2 is the
  upper left corner.


Version 1.6    25 July, 1992

- Fixed bug in graphix.lib preventing labeling from having more non-
  printing characters than printing chars and still be drawn.

- Relative character sizes increased as larger paper sizes were selected.
  They should have decreased due to the necessary reduction in size to
  fit the drawing to the screen.

- DR set the wrong character direction when P1/P2 (the hard clip corner
  points) were exchanged.

- IW set the wrong window coordinates when P1/P2 were exchanged.  The
  result was no drawing on the screen.


Version 1.5    30 December, 1991

- Added debugging flag.  Error messages regarding the source file are now
  suppressed.  The -db flag turns them on.  Error messages are printed to
  stdout and may be redirected to a file.

- Added four instructions for HP9872 plotter backward compatibility.

- re-wrote the graphics adapter identification code to make maintaining
  the code easier.

- Added PE (polyline encoded) instruction.


Version 1.0    3 September, 1991

- Original release.

The P1/P2 Exchange Problem

There is an issue of semantics which arises for the case of P1/P2
being exchanged.  On a plotter, entering the P1 and P2 points is a
physical process whereby the operator mechanically places the cursor
at the desired corner points.  When one places P1 in the upper left
corner and P2 in the lower left corner of the page, the logical
coordinate system and the physical coordinate system of the plotter
become reflected and inverted.  The plotter defines P1 as the lower
left corner of the page and P2 as the upper right corner of the page.
Thus, if you move the pen to the physical location P1 or P2
coordinates (using the control panel), the plotter moves the pen to
the upper right or lower left corner, respectively.  However, if you
told the plotter to move to the coordinates of P1 or P2, it would
move to a point opposite of the respective location.  For example, if
one sets P1 = (10250, 7479) and P2 = (250, 279), issuing "PU250,279;"
would move the plotter to the upper right corner of the page, even
though the physical P2 location is in the lower left corner of the
page.

The plotter is being forced to perform a translation from physical
coordinates into logical coordinates.  By choosing P1 = (10250, 7479)
and P2 = (250, 279), we have inverted and reflected the logical
coordinate system.  Thus, moving the pen to the logical
coordinates of P1 (we are not commanding the plotter to move to the
physical location of P1) moves the pen to the lower left corner of
the page.  Our choice of coordinate values for P1 and P2 has placed
larger numerical values in the lower left corner of the page and
smaller values in the upper right corner.

What does this mean? If you examine the display for program
SHOW_TST.DPF, two of the four frames show P2 in the lower left corner
of the frame.  These frames have P1 and P2 exchanged.  If you examine
the program, the coordinate values given for point P2 are the values
of the P1 coordinate.  The labels are intended to show where the
physical location of P2 would be if you could display it.  However,
the P2 logical coordinate is always in the upper right corner, and
the P1 logical coordinate is always in the lower left corner.  Thus,
wer are forced to appear to mislabel the graph in order to show the
physical P1 and P2 coordinate locations.



Usage

SHOWHPGL -[video][paper][plotter][debug]  [filename]

where

    filename    optional filename for HP-GL source file.  If a
            filename is not supplied, standard input is
            assumed.

    video        option to force usage of a particular video
            mode.  Values are: c, e, v, for CGA, EGA, or
            VGA.
              'c' will force CGA 640 x 200 monochrome mode,
              'e' will force EGA 640 x 350 16 color mode,
              'v' will force VGA 640 x 480 16 color mode.

            Default mode is autodetect and select
            highest resolutions standard mode available.
            No SVGA modes are supported.

    paper        One of the following standard paper sizes:
            A, B, C, D, E, or A4, A3, A2, A1, A0 .
            Default size is A. Case is important!!
            A0 is a paper size option: a0 is unknown.

    plotter        Default emulation is HPGL/2.
            'dp'  will select DraftPro emulation.
            '70'  will select HP7470 emulation.
            '75'  will select HP7475 emulation.

            The HP 7470/7475 have the plotter units coordinate
            origin in the lower left corner.  The DraftPro
            uses the center of the page as the origin.  Note also
            that the 7470 and 7475 emulations do NOT limit the
            number of pens available to 2 and 6, respectively.  Pen
            colors are limited to those available on the graphics
            mode you are running (i.e., CGA, EGA, or VGA).

    debug        Default is to silently pass errors.  -db will
            turn on error output to stdout.


The user may also set the environment variable HP-GL to a default set
of switches, i.e.,

set hpgl=dpA3

specifies default options of DraftPro mode and A3 size paper.

If command line switches are present, the environment settings are
ignored.  Multiple paper size selections will cause the program to
abort.  Multiple video mode selections will default to the highest
resolution autodetected mode.

The switch character is defined as '-'.   It is hard coded into the
program.  Directory path names may include either or both '\' and '/'
directory separators.  This program has been tested under MS-DOS 3.20
and MS-DOS 5.0 .

All video graphics functions draw using the video BIOS.  No direct
screen I/O is used.  Additional BIOS supported graphics modes may be
supported by defining the appropriate structures in graphix.h and the
macros in graph.h and making appropriate changes to the mode lists in
autogrph.c and showhpgl.c .

When the debugging flag is turned on, this program generates diagnostic
output text strings when illegal or unsupported instructions are
encountered.  THESE STRINGS APPEAR IN THE GRAPHICS DISPLAY AND MAY
INTERFERE WITH THE DRAWING IF SUFFICIENT ERRORS OCCUR.  If you expect
large numbers of errors and wish to retain a listing of the output,
redirect any generated output to a file.

Note that this program DOES NOT restore the video mode which was
in use prior to calling this program.  Although the EGA and VGA
display systems are capable of better than 80 columns and 25 rows on
the screen, they do not appear as supported IBM BIOS video modes.
Determination of nonstandard video mode parameters was beyond the
scope of this program.  If you want to restore a recognized video mode
at the end of program execution, add the following code to showhpgl.c just
before the end of main ():

    twait (infile, 50);
    graphics_off ();

This will introduce a 50 second delay before restoring the video mode.
Shorter delays can be had by changing the value 50 to a more reasonable
number.  If the initial video mode was not a BIOS standard video mode,
graphics_off () may not be able to restore it properly.


Compilation

The entire package is compiled as follows:

cl showhpgl.c hpgl1.c hpgl2.c getargs.c autogrph.c graphix.lib

Note that this package is compiled with the default optimizations.  Failure
use at least the default optimizations when compiling showhpgl.c may
result in a _TEXT segment which exceeds 64K and linking will fail.
graphix.lib is compiled in the small memory model.

Because graphix.lib internally uses Microsoft interrupt calling
functions, showhpgl must be compiled using the Microsoft compiler.  The object
module mscio.obj, which is in graphix.lib, contains all Microsoft, and PC
in general, specific functions.  This module must be replace in order to
use this package with other compilers and platforms.  Contact the author for
the required information.


Distribution Package

The distribution package includes the following:

showhpgl.doc        this document
showhpgl.exe        the executable program file
showhpgl.c        main program
hpgl1.c            additional functions
hpgl2.c            additional functions
hpgl.h            header file for showhpgl.c, hpgl1.c hpgl2.c
getargs.c        command line options and arguments
autogr.c        video graphix adapter detection
labels.c        labeling font for showhpgl (part of graphix.lib)
graphix.lib        graphics functions library
graphix.h        header file for main program (showhpgl.c)
graph.h            header file for additional modules (hpgl1.c,
            hpgl2.c)
license.doc        license agreement

    HP-GL test programs

aa_artst.dpf        AA, AR, CI, IP, SC, CT, PR: test general performance
                of arc and circle drawing with fixed and adaptive
                segment lengths
attest.dpf        AT: 3-point arc, absolute
actest.dpf        AC: anchor corner test
cptest.dpf        CP: character plot
ct_citst.dpf        CI, CT: circles with fixed and adaptive segment
                lengths
di_drtst.dpf        DI, DR: absolute and relative label directions.
dv_sltst.dpf        SL, DV: test slant with DV command.
dvtest.dpf        DV: variable text path (fails this test)
ea_ertst.dpf        EA, ER: edge rectangle absolute and relative
estest.dpf        ES: extra inter-character spacing
ewtest.dpf        EW: outline wedge
ip_irtst.dpf        IP, IR: test & display usage of IP and IR
iwtest.dpf        IW: soft-clip window
labels.dpf        LB, LO, SL, SR, DV: labels and label origins, char.
                slant, char. size (relative), direction vertical.
lttest.dpf        LT: line type: note that types 6-9 are identical as
                types 7-9 are unsupported.
pa_prtst.dpf        PA, PR: test absolute and relative line drawing
petest.dpf        PE: polyline encoded
ra_rrtst.dpf        RA, RR: filled rectangle, absolute (no solid fills)
rttest.dpf        RT: 3-point arc, relative
sc_test.dpf        SC, DR, DI, LB: test all scaling types, DI, DR, and LB
                instructions in normal and P1/P2 exchanged
                coordinate systems.
smtest.dpf        SM: symbol mode
tl_lotst.dpf        LB,LO,TL,XT,YT: test labels, label origins, x-,
                & y-ticks
fwdaltbx.dpf        drawing to demonstrate the -dp drawing option.
                Use -C or larger for paper size.

Note: many of these program are dependent on using A-size paper to correctly
display the intended test functions.  Different results may occur from using
other paper sizes unless another paper size is specifically noted.

Some of these test programs are taken from "The HP-GL/2 Reference Guide"
and, as such are copyright 1990 by Hewlett-Packard.  This book provides
illustrations of what the output of some of these programs should look
like accompanying the description of the instruction.

The file labels.c is included for those who wish to modify the font used
for labeling.  This font is incorporated into graphix.lib.  To modify the
font, make the required changes to labels.c, compile it to a ".obj" file,
and update the library using "LIB -+labels;" (Microsoft library manager).
You may then re-link the remaining files to create a new program which
uses the new fonts.


Licensing

Please refer to the license agreement in license.doc.  Use of this
software and the enclosed source code is limited to the terms of the
license.

Bug Reports:

Please report any bugs to

[e-mail]   (Robert Becker).

If you prefer, mail them to me at

Robert Becker
15836 Quebec Circle
Eden Prairie, MN   55346


Instructions Status

The following is a list of instructions and the level of implimentation
in showhpgl.exe of HP-GL/2 instructions.  Note that not all instructions
are HP-GL/2 instructions.  Those with notations in the source column
indicate where this instruction was found.  Status indicates the level of
implimentation of the instruction.  There are four levels of implimentation:

Full:        instruction is fully functional as per HP-GL/2
Partial:    instruction implimentation is incomplete
NOP:        no action or action not meaningful for this application
N/A:        not available: instruction was not implimented.

There are 38 Full, 8 partial, 26 NOP, and 29 N/A instructions.  Of the N/A
instructions, 11 are related to character set or font selection.  Of the
NOP instructions, 12 are related to output or digitizing a point and 4 are
for backward compatibility with earlier products.  All output instruction
that have no meaning in this application and are implimented as NOP
instructions.  No dual context mode instructions (HP-GL & PCL) have been
inplimented.

Command    Description            Status    source        Comments

AA    arc absolute            Full
AC    anchor corner            Full
AD    alternate font definition    N/A
AF    advance full page        NOP            compatibility w/HP9872
AH    advance half-page        NOP            compatibility w/HP9872
AR    arc relative            Full
AT    3 point arc absolute        Full
BP    begin plot            Partial            waits TWAIT seconds before clearing plot from screen
CA    designate alternate char. set    N/A    7470
CF    char. fill mode            N/A
CI    circle                Full
CP    character plot            Full
CS    designate std. character set    N/A
CR    color range            N/A
CT    chord tolerance            Full
DC    digitizer clear            NOP
DF    default                Full
DI    absolute label direction    Full
DL    download character        N/A
DP    digitize point            NOP
DR    relative label direction    Full
DS    designate char. set into slot    N/A    DraftPro
DT    Define label terminator        Full
DV    Define variable text path    Partial            No line feed reversal
EA    edge rectangle absolute        Full
EC    enable cutter            NOP
EP    edge polygon            N/A
ER    edge rectangle relative        Full
ES    extra space            Full
ESC    escape code instructions    Partial            No PCL mode switch commands
EW    edge wedge            Full
FI    primary font selection by ID    N/A
FN    secondary font selection by ID    N/A
FP    fill polygon            N/A
FR    frame advance            N/A
FT    fill type            Partial            Only hatched and cross-hatched fills
GM    graphics memory            NOP    DraftPro
IM    input mask            NOP    7470
IN    initialize            Full            Since there is no 'front panel', IN1 is same as IN
IP    input P1 & P2            Full
IR    input relative P1 & P2        Full
IW    input window            Full
LA    line attributes            NOP            No wide lines available
LB    label                Full
LO    label origin            Full
LT    line type            Partial            No adaptive line patterns: types 0-6, only.
MC    merge control            N/A
MG    message to panel        NOP
MT    media type            NOP
NP    number of pens            NOP
NR    not ready            Full
OA    output pen position & status    NOP    7470
OC    output commanded positon & sts    NOP    7470
OD    output digitized point & sts    NOP
OE    output error            NOP
OH    output hard-clip limits        NOP
OI    output identification        NOP
OO    output options            NOP    7470
OP    output P1 & P2            NOP
OS    output status            NOP
OW    output window            NOP    7470
PA    plot absolute            Full
PC    assign pen colors        N/A
PD    pen down            Full
PE    polyline encoded        Full
PG    page advance            Modified        Waits 6 seconds before clearing screen
PM    polygon mode            N/A
PR    plot relative            Full
PS    plot size            Full
PU    pen up                Full
PW    pen width            N/A
QL    quality level            NOP
RA    fill rectangle absolute        Partial            no user defined fills
RF    raster fill definition        N/A
RO    rotate coordinate system    N/A
RP    replot                N/A
RR    fill rectangle relative        Partial            no user defined fills
RT    relative arc 3-point        Full
SA    select alternate font        N/A
SB    scalable or bitmap font        N/A
SC    scale plot            Full
SD    standard font definition    N/A
SI    absolute char. size        Full
SL    char. slant            Full
SM    symbol mode            Full
SP    select pen            Full
SR    relative char. size        Full
SS    select standard char. set    N/A
ST    sort vectors            NOP
SV    screened vectors        N/A
TL    tick length            Full    7470
TD    transparent data        Partial            fn. char. set limited.
TR    transparency mode        N/A
UC    user defined character        N/A
UL    user defined line pattern    N/A
VA    adaptive pen velocity        NOP            compatibility w/HP9872
VN    normal pen velocity        NOP            compatibility w/HP9872
VS    velocity select            NOP
WG    fill wedge            Partial            Outline of wedge, only (no filling available)
WU    pen width unit selection    N/A
XT    x-tick                Full    7470
YT    y-tick                Full    7470

Notes:

    BP instruction is checked for syntax.  BP will wait PG_DELAY seconds
    before clearing the screen if the screen was plotted on.  If the
    screen was not plotted on, the plotter is initialized.  In either
    case, the plotter is initialized.

    PG instruction generates a wait of PG_DELAY seconds before clearing
    the screen.

    PG_DELAY is defined in hpgl.h as 6 seconds.

    HP-GL and HP-GL/2 distinguish between <cr> and <lf> for
    positioning on labels.  The C-language, being based in UNIX,
    assumes the <lf> is the newline character and <cr> has no
    meaning.  This assumption is also present in this program and
    some test case labeling and character plotting tests will fail
    because of this.  The test program dvtest.dpf fails because of
    this.  The display should look something like:

          D A                  ABC
          E B                  DEF
          F C                     GHI
        G
        H
        I

    Several of the HP-GL/2 specifications are incomplete.  For
    example, when one is drawing a wedge with symbol mode on,
    placement of the symbol is unspecified.  Similarly, when TD
    (transparent data) mode is on, the font used to display the
    control characters is not specified.  Error handling is not
    always specified.  For example, when CT is used to specify
    deviation distance on circles and arcs, this reference does
    not specify what action to take if a distance tolerance is
    not specified for subsequent circles and arcs.  The DraftPro
    manual specifies that the default shall be 5 degrees in this
    case.  The Addison-Wesley book does not specify what action
    to take.

    For hatch and cross-hatch fills, it is not clearly specified
    for the case of user-unit defined hatch x-spacing if the scale
    in the y-direction should affect the spacing of the hatch. In this
    implimentation, it was decided that the hatch spacing displayed on
    the screen should be invariant with the rotation angle.

    Additional questions arise in the case of the IR instruction.  One
    would think that, for the case of P1 and P2 being opposite of their
    normal locations (lower left, and upper right, respectively), that
    the IR instruction would work off of these coordinates.  However,
    there are indications of the HP-GL/2 reference guide that IR works
    off of the default P1 and P2 locations.  That being the case, then
    an IR of two arguments (IR x,y;) following an IP which exchanges
    the P1 and P2 corners will take the x- and y-values as percentage
    values based on the corners of convention for P1 and P2.  For
    example, if one assumes IP10250,7479,250,279; and later executes an
    IR 10,10;, for A-size paper, the IR corner plotter coordinates will
    be (1030, 765), which, because P2 tracks P1 changes for only one
    coordinate pair arguments to IR or IP, will force P2 to assume the
    value of (-8970, -6534).  This is unlikely to be the assumed
    result.  Further, executing an IR of four arguments
    (IR x1, y2, xy, y2;) following an IP which exchanges P1 and P2
    corners will have the effect of reverting the coordinate system to
    the normal locations for the P1 and P2 corners

    To use IR to exchange the P1 and P2 corners, the first coordinate
    pair (x1, y2) must be greater than 50% (IR works in percent of the
    hardclip limits), and the second pair (x2, y2) should be less than
    50%.

    HP-GL, HP-GL/2, HP, Hewlett-Packard, and DraftPro are registered
    trademarks of the Hewlett-Packard company.

    PC, CGA, EGA, VGA are or may be registered trademarks of the IBM
    company.

    UNIX is a trademark of AT&T.

Reference:

    "The HP-GL/2 Reference Guide", Addison-Wesley Publishing Company.