Power-Programmierung/CD1.mdf/clarion/library/pcx3/pcx3.doc

Text File | 1992-08-19 | 21KB | 459 lines

  Welcome to my graphics LEM.  Let me start off by apologizing for my inability
to spell.  Also recognize that this program was written to suit the specific
needs where I work and it might not do everything you want it to do.  However,
I think its a very useful set of utilities for any Clarion programmer.    Any
comments or suggestions will be at least concidered in subsequent releases.
Note also that I hate writing documentation worse than anything.  So forgive
me if I'm a little short on explanations.  Just send me a message if this
document and the demos provided don't answer all your questions.

  Jay Cotton
  Rt.3 Box 3184
  Royston, GA 30622
  [phone]

  Clarion BBS userid is KPayne

  Compuserve ID is 70761,3223


   Version 3 changes:
    -added ability to print on HP Laser Jets and Epson compatibles

    -changed mouse commands (no more GETMX(),GETMY(),GETMB())

    -new command: OUTPUT('string') sends a character string to LPT1:

    -new command: INPUT('prompt') returns user answer from text or
       graphics screens

    -new commands: BLOB() and SAVEBLOB() to create and display cursors,
       pointers, icons, pictures, etc. independent of screen mode

    -support for displaying 24 bit PCX pictures in grey on VGA displays

    -changed use of SETVCARD() to set EGA, VGA, SuperVGA

    -added SETVMEM() command to set super VGA memory size

    -many commands now report errors...PCX(),SETPCX(),SAVEPCX(),EPDUMP(),
       HPDUMP(),SETVMODE(),SETVCARD(),SETVMEM(),SETVMONITOR(),BLOB(),
       SAVEBLOB().

    -built in support for additional SuperVGA cards
      3-Tseng: ET3000, EVA 1024; MicroLabs: VGA Solution; Genoa: VGA;
            STB: VGA EM/16, VGA Extra/EM; Orchid: ProDesigner Plus VGA;
            Quadram: QuadVGA Spectra; Sigma Designs: SigmaVGA;
            Willow: VGA-TV/Publisher's
      4-Tseng: ET4000, Orchid: ProDesigner II; MicroLabs: Ultimate VGA
            STB: EM 16+, PowerGraph, PowerView;
            Sigma Designs: SigmaVGA Legend
      5-Paradise: All standard SVGA modes
      6-ATI: All standard SVGA modes ... not fully tested
      7-Video7: All standard SVGA modes ... not fully tested


   First and foremost...I've put alot of work in this program and I never
intend to give it away.     It is not in the public domain.  It is shareware.
This means you can scope it out.  You can give copies to other people as long
as they get this file with it.    You may not put it in your programs unless
you pay a small fee.

   The cost of the program is $30.00 (US dollars).  I will provide a limited
amount of technical support and a very reduced rate on updates.     And, in
keeping with the Clarion tradition, there is no fee (beyond the normal
one time registration fee) for distributing software created using PCX3.

   I put too much time in this program to provide source code for free.     If
anyone is interested in purchasing the source, contact me and we can work
something out.    If any dealer's are interested in marketing this LEM I will
concider reasonable offers (and continue to offer service for a fee).

   The primary drive behind this program was to provide access to PCX files
in ways the Clarion graphics LEM just cannot do.  This program supports all
PCX formats that I have run across other than one 4 color CGA file. If you
have a picture that it cannot view let me know.     It will display all 2,4,8,16
color files on a 16 color EGA/VGA/SVGA screen, and all 256 color files on a
256 color VGA/SVGA screen.  It will also display 24 bit PCX pictures on VGA or
SVGA screens in 64 level grey scale.

   The next reason is size.  Clarions graphic LEM while providing great
graphing and statistical functions is huge.  Not everyone has 40K+ to spare.
You may only need to PCX functions and my program provides them without too
much overhead.    The PCX functions alone would be a valuable language extension.
But I figured it needed a few drawing commands to compliment it.

  I've included a demo which is a simplified paint program.  Almost all the
commands are used in this demo.     If you read the demo code, alot of your
questions may be answered.  Feel free to modify the demo in any way you see
fit.  View the PAINT.CLA file for instructions on how to operate the paint
demo.


  Well, here we go.  Over 40 commands to make your video card strut its stuff.
One of the nice features is the user definable patterns.  These patterns
are useful for drawing bar charts with combinations of colors and patterns.
I'll leave it to you to write the routines to draw the graphs.
Sorry, no region FILL with patterns...yet.  Only the DISC and BOX commands
use the patterns.

   I would like to thank Richard Wilton and Steve Rimmer for writing the books
I used for reference.  If you are interested in this type of programming
these two books are excellent.

Steve Rimmer            Richard Wilton
Bit-Mapped Graphics        Programmer's Guide to PC & PS/2 Video Systems
1990 Windcrest Books        1987 Microsoft Press


------------------------------------------------------------------------------
Setup commands:
------------------------------------------------------------------------------
SETVMODE(video_mode)        Selects video mode
SETVCARD(video_card)        Selects type of video card
SETVMONITOR(video_monitor)  Selects type of video monitor
SETSVGA(svga_type)        Selects type of Super VGA card


------------------------------------------------------------------------------
Graphics Commands:
------------------------------------------------------------------------------
DOT(x,y,pal#)            Draws one dot on the screen
LINE(x1,y1,x2,y2,pal#)        Draws a line from x1,y1 to x2,y2
CIRCLE(x,y,w,h,pal#)        Draws a circle centered at x,y
DISC(x,y,w,h,pal#)        Draws and fills a circle with current pattern
FRAME(x1,y1,x2,y2,pal#)        Draws a rectangle
BOX(x1,y1,x2,y2,pal#)        Draws and fills a rectangle with current pattern
CLRSCREEN(pal#)            Clears screen to specified color (graphics only)
SETCOLOR(pal#,r,g,b)        Change the value in a palette register
FILL(x,y,pal#)            Shades a region of the screen
SETPOS(x,y)            Sets current draw position
DRAWTO(x,y,pal#)        Draws a line from the current position to x,y
DRAW('string',pal#)        Draws a vector shape defined by string
SETPATTERN(pat#,'pattern')  Create a user defined pattern
USEPATTERN(pat#)        Selects current pattern
BLOB(file,x,y,a)        Draws a BLOB (Binary Loaded Object Block?)
SAVEBLOB(file,x1,y1,x2,y2)  Creates a BLOB from the screen data


------------------------------------------------------------------------------
Graphics Functions:
------------------------------------------------------------------------------
VMODE()        Returns current video mode
WIDTH()        Returns screen width in pixels
DEPTH()        Returns screen depth in pixels
RED(pal#)    Returns red value of a palette register
GREEN(pal#)    Returns green value of a palette register
BLUE(pal#)    Returns blue value of a palette register
READDOT(x,y)    Returns color (pal#) of a pixel
GETX()        Returns current x coordinate
GETY()        Returns current y coordinate


------------------------------------------------------------------------------
PCX Commands:
------------------------------------------------------------------------------
PCX(file)        Auto selects display mode and shows PCX file.
SETPCX(file,x,y,w,d)    Places PCX picture on current screen if possible.
SAVEPCX(file,x,y,w,d)    Save a portion of the screen as a PCX file.


------------------------------------------------------------------------------
MOUSE Commands:
------------------------------------------------------------------------------
MOUSEINIT        Initializes mouse
MOUSEON            Turns on mouse cursor
MOUSEOFF        Turns off mouse cursor
SETMPOS(x,y)        Sets position of mouse cursor
GETMPOS(x,y,b)        Runs BIOS routine to read mouse
WINDOW(x1,y1,x2,y2)    Sets mouse movement window
MSPEED()        Sets speed of mouse


------------------------------------------------------------------------------
PRINTER Commands:
------------------------------------------------------------------------------
HPDUMP(x1,y1,x2,y2,size,backgroud)    Prints graphics to HP Laser Jet
EPDUMP(x1,y1,x2,y2,size,backgroud)    Prints graphics to Epson compatibles
SETMATRIX('set','norm','double','quad','bump',spacing)      Sets printer codes
OUTPUT('string')                        Sends 'string' to LPT1:




------------------------------------------------------------------------------
Extended descriptions
------------------------------------------------------------------------------
SETVCARD selects the type of video card in the computer. This value is used
by the PCX command to determine the best mode to display a picture.
  1 = EGA
  2 = VGA *default
  3 = Tseng ET3000
  4 = Tseng ET4000
  5 = Paradise
  6 = ATI        ;not tested... Let me know it it works on your computer.
  7 = Video 7        ;not tested... I don't have a way to test them.

SETVMONITOR, like SETVCARD, is used by the PCX command to determine the best
video mode for a picture.
  1 = EGA 640X350
  2 = VGA 640X480  *default
  3 = SVGA 800X600
  4 = SVGA 1024X768

SETVMEM, like SETVCARD and SETVMONITOR is used by the PCX command to determine
the best video mode for displaying a picture.
  1 = 256K  *default  (EGA,VGA use this value)
  2 = 512K
  3 = 1024K


SETMODE calls the DOS BIOS function to select a video mode.  An attempt to set
a video mode not supported by your video card will return a errorcode() = 1, or
error() = 'Invalid Function Number.'

  EGA or VGA modes:
     3 - standard color text
    13 - 320X200X16
    14 - 640x200x16
    16 - 640x350x16

  VGA only modes:
    18 - 640x480x16
    19 - 320x200x256

  SVGA modes: (uses VESA mode numbers although VESA not yet supported)
    100 - 640x400x256
    101 - 640x480x256
    102 - 800x600x16
    103 - 800x600x256
    104 - 1024x768x16    -PCX only. No support for drawing commands.
    105 - 1024x768x256



GRAPHICS COMMANDS:
   Most of the graphics commands and functions use a value called "pal#."
"pal#" refers to an internal palette register which holds a color. The DOS
BIOS has a default set of colors for any given screen. This palette can be
altered by the SETCOLOR or PCX commands. SETCOLOR changes a specific palette
register, while PCX set the entire palette to that of the picture. After using
the PCX command don't expect the default palette to be in effect. For example
drawing with pal# = 15 might not be white (usually pal#=15 is bright white.)
One more note regarding pal#...on 16 color screens, only 0-15 produce different
colors, and on 256 color screens, 0-255 produce different colors. By adding
256 to any pal# on a drawing command will cause to value to be XORed on the
screen. This will allow the user to remove a drawing by repeating the same
command.
  ex.    CIRCLE(100,100,50,50,15+256) will draw a white circle if the backgroud
                     is black
    CIRCLE(100,100,50,50,15+256) will erase the previous circle.
   Just play with it and see what happens when you use it on backgrounds other
then black.


   DRAW is an oversimplified vector drawing routine to draw shapes on the
screen.     The 'string' variable is a list of instructions on how to draw a shape.
See the PAINT.CLA demo for an example of the DRAW command.
    L[n]    draws to the left by 'n' pixels. 'n' is optional (2-9)
    R[n]    draws to the right
    U[n]    draws up
    D[n]    draws down
    E[n]    draws up and right
    F[n]    draws right and down
    G[n]    draws down and left
    H[n]    draws up and left


   SETPATTERN allows the user to define a pattern for use with BOX and DISC.
The pattern is an 8 digit string containing the pixel pattern of an 8X8 cell
matrix in binary format. The default pattern is 0 which is a solid fill.
Valid values for pat# are 0-15.

PAT    STRING(8)
PATB    BYTE,DIM(8),OVER(PAT)

    PATB[1] = 10001000b
    PATB[2] = 01000100b
    PATB[3] = 00100010b
    PATB[4] = 00010001b
    PATB[5] = 10001000b
    PATB[6] = 01000100b
    PATB[7] = 00100010b
    PATB[8] = 00010001b
    SETPATTERN(1,PAT)

   USEPATTERN selects which pattern to use on the next BOX or DISC.


   SETCOLOR allows the user to change the red, green, and blue values of a
palette register.  RED(), GREEN(), and BLUE() return the values. Values for
r,g, and b are 0-63. 0 is none and 63 is full intensity.

   BLOB and SAVEBLOB are commands needed to create and display pictures or
objects.  These objects can be anything from an animated cursor (See PAINT
demo) to an icon.  The Paint demo can be used to draw and save these BLOBs.
The demo as is will save any BLOB as 'TEMP.BLB' in the current directory. The
Paint demo could be changed to allow the user to type in a name for the BLOB.
To create a BLOB simply use the SAVEBLOB command with the screen coordinates
of the shape to save:
   SAVEBLOB('MYBLOB.BLB',100,100,120,120) ...this command will save a BLOB of
                         size 21 by 21 pixels into the file
                         named 'MYBLOB.BLB'.  *note the BLB
                         extension is NOT required. Rather
                         it is a convention like the PCX
                         extension.

  To display a BLOB simply use the BLOB command and specify where and how to
display the BLOB. *note that BLOBs are screen independent. This means that a
BLOB created on a 320X200X256 screen will display on a 640X400X16 screen using
only the first 16 colors:
   BLOB('MYBLOB.BLB',50,50,0)  ...this command will display a BLOB at the
                  screen coordinates 50,50 using draw mode 0.

   Draw modes for BLOB:
   0- Normal  -the BLOB will replace whatever is in the screen area
   1- XOR     -the BLOB will be XORed with the screen contents
   2- Outline -the BLOB will replace the screen anywhere the BLOB has a
           foreground (non zero) color attribute)

   The Normal mode behaves similar to the SETPCX command but with BLOBs.  Any
BLOB drawn on the screen will replace the screen contents with the BLOB
contents (including any blank/background area saved with the BLOB).
   Using the XOR (1) mode a BLOB can be drawn and then erased by a subsequent
BLOB() call using the same parameters (See the Paint demo mouse function).
   The Outline (2) mode allows irregular shaped BLOBs (pointers, icons, etc) to
be displayed without blacking out the square area around the BLOB.



MOUSE COMMANDS:
   MOUSEINIT must be run before any other mouse commands.  MOUSEON and MOUSEOFF
are relative commands. If MOUSEOFF is issued twice then MOUSEON must be issued
twice to get the mouse back on. This way a subroutine which does something like
SAVEPCX can issue MOUSEOFF at the beginning and MOUSEON at the end, and leave
the mouse in the state it was before.


   GETMPOS(x,y,b) will set the variables in the parenthesis to the mouse
coordinates and button status.    IMPORTANT: the variables for x,y, and b must be
declared as SHORT.

example:
MOUSEX    SHORT
MOUSEY    SHORT
MOUSEB    SHORT

    CODE
    GETMPOS(MOUSEX,MOUSEY,MOUSEB)
    IF MOUSEB = 1 THEN DRAWTO(MOUSEX,MOUSEY).



PCX COMMANDS:
  The PCX command and the SETPCX commands are used differently.     The PCX command
will choose the optimal screen size and resolution based on the picture, video
card, and available video memory.  2,4,8, and 16 color pictures always display
on a 16 color screen.  256 color and 24 bit pictures always display on a 256
color screen.  The screen size is determined by the picture size.  The PCX
command will place the picture on a screen large enough to display all of the
picture as long as the video mode is supported.     For example, if the picture
is 800x600x256 and the user has a standard VGA card, the picture will be
displayed in video mode 19 (13h). If the user has a super VGA card with 256K
of video RAM the picture will be displayed on the 640x400x256 screen for that
card. If the user has a super VGA card with 512K of video RAM and a monitor
which can display 800x600 the picture will be displayed on the 800x600x256
screen. The same picture will NOT display on an EGA display system.
  The SETPCX command makes no attempt to determine a video mode.  Instead, it
will display a picture on whichever screen has been selectly...if it can.  The
user will first select a video mode using SETVMODE and then use the SETPCX
command to place the picture.  If the picture and the video mode are not
compatible the picture will not display.  For example, to display a 320x200x256
picture in the upper right corner of a 640x400x256 screen:
  SETVMODE(100h)
  SETPCX('picture.pcx',320,0,639,199)

If the picture is not found, no action is taken and the error 'FILE NOT FOUND'
will be set (check with IF ERROR() command.)  If the file is not a PCX file,
no action is taken and the error 'INVALID FORMAT' is returned.    If the file is
a PCX, but is corrupted, an error message will be returned and the picture may
or may not be displayed (depends on extent of corruption.)



PRINTER COMMANDS:
  Both EPDUMP (Epson dump) and HPDUMP (Hewlett Packard Dump) have a size and a
background parameter.  The size parameter will tell the printer which
resolution to print.
  On HP printers:    size=0    300 dpi (tiny)
            size=1    150 dpi (medium)
            size=2     75 dpi (big)

  On Epson printers:    size=0    quad density graphics (tiny)
            size=1    double density graphics (medium)
            size=2    standard graphics mode (big)

  The background parameter selects the palette register to treat as the back-
ground color. Normally this is 0. However, if you fill a screen with white
(palette #7) and draw with black lines, you would probably want to see the
output as black on white.
  On 16 color screens the background# may be 0-15, on 256 color screens 0-255.
Any color on the screen equal to the background# will be white; any other
color will print black.
  The HPDUMP command will print 16 level half-tone grey scale if the background
is set to 256 or greater.  This results in a picture 4 times larger than the
equivalant 2 color printout (due to a 4 by 4 half-tone pixel).    The largest
picture printable is 600X800.

  EPDUMP(0,0,640,480,2,7) will print the screen to an Epson printer in standard
      mode and use pal# 7 (white) as the background (not-printed) color.
  HPDUMP(0,0,640,480,0,256) will print the screen to an HP printer at 300 dpi
      and use 16 level half-tone grey scale.

  Both EPDUMP and HPDUMP will print the image at the current printer row, but
the HPDUMP command also prints at the current print column.  To place a picture
on the right side of the paper on an HP, place the cursor at the desired
position before using the HPDUMP command.  Examples for HPDUMP:

  OUTPUT(ALL(' ',40))           !space the cursor 40 columns to the right
  OUTPUT(CHR(13) & '          ')   !move cursor 10 spaces from left margin
  OUTPUT(CHR(27) & '*p1200x1600Y') !place cursor near middle of page

  *see LaserJet user's manual for explanations and other escape sequences

  If an error occurs while printing, Clarion will usually prompt a printer
message, and an error message will be returned if the user selects the option
to return the error to the program.



  SETMATRIX allows the user to set the EPDUMP command for near Epson compatible
printers: Star, Texas Instruments, IBM graphics, etc.  This command is only
necessary when a printer cannot be selected as an Epson compatible.  Some
printers (Panasonic, Okidata) have the ability to emulate Epsons exactly. This
command will not be needed on these.  This command will not work on printers
that are programmed completely differently (Okidata Pacemark, Qume, others).
  Examples:
     SETMATRIX('@','K','L','Z','J',24)     ! Epson (default)
     SETMATRIX('@','K','Y','Z','J',24)     ! Epson (hi-speed mode 1)
     SETMATRIX('@','K','L','O','3',24)     ! TI 850 (IBM graphics?)
     SETMATRIX('@','K','y','z','J',16)     ! Star NX10


  INPUT allows the program to prompt the user for a response on text or
graphics screens.  The 'prompt' parameter will be displayed on the screen and
the command will wait for input from the user.
  Example:
      SETCURSOR(10,10)                ;place the cursor
      file = INPUT('Enter file to load: ')  ;ask for user input
      PCX(file)                    ;display a picture


  OUTPUT allows the user to send any character string to the printer.  Font
codes, setup strings, special graphic commands, and regular test can be sent
to LPT1.
  Example:
      OUTPUT('E')    !sends reset command to an HP laser printer (Esc + 'E')
              !Hold down the Alt key while typing '27' to get the Esc