PGLIB 1.0 - The Atari Portfolio Graphics Library by Don Messerli (Compuserve 72500,1671 or GEnie DMESS) Copyright (c)1991 Software Vineyard. 1/9/91 All Rights Reserved (see "Licensing" at end of docs) What is it? ----------- PGLIB is a 'C' Library of graphics routines for the Atari Portfolio. Included in the archive (.ZIP) are small model libraries for Microsoft C 5.0 and above and Borland's Turbo C (only tested on Turbo C 2.0). The library includes basic graphics functions (turn pixels on and off, line drawing) as well as functions to handle PGC graphics (show, load, and save). I hope this library makes it easier for people to write graphic applications for the Portfolio and in particular to support the PGC graphic file standard. How do I use it? ---------------- Just copy the appropriate library file (PGMS.LIB for Microsoft or PGTC.LIB for Turbo C) to the directory specified in your LIB environment variable (usually called LIB). Copy the header file (PGLIB.H) to the directory specified in your INCLUDE environment variable (usually called INCLUDE). Make sure you put a line in your program to "include" the header file at the beginning of your program: #include "pglib.h" Link the library in with your program. In Quick C this can be specified in a *.mak file. In Turbo C it is a *.prj file. In Microsoft C 5.0, 5.1, or 6.0 this can be done in a make file or specified on the LINK command line. General Usage Hints ------------------- You should always call PG_Init before using any other library functions. It would behoove you to put the Portfolio into graphics mode before calling any library functions. This can be accomplished painlessly by calling PG_GoGraphic(); Changes will not show up on the screen until you force a screen refresh (Portfolio battery saving feature!). This can be done with PG_Refresh() function. If a library function does it's own screen refresh, it is noted in the function reference below. If a library routine says to pass it a far pointer, do it. If you pass it a near pointer, problems might not surface until runtime. Follow the rules and you won't get stung. Function Groupings ------------------ Housekeeping PG_Init, PG_GoGraphic, PG_GoText General PG_ClearScreen, PG_Refresh Drawing PG_Plot, PG_QPlot, PG_GetPixel, PG_Line PGC PG_Show, PG_Load, PG_Move, PG_Save Screen Coordinates ------------------ The Portfolio screen is 240 pixels wide and 64 pixels high. PGLIB requires coordinates passed as integers starting at (0,0) in the upper left corner of the screen. PGLIB currently does not checking to make sure coordinates are in this range. See diagram below: 239 0 ---------------------------------------> | | | | 63 \/ Buffers and the Screen ---------------------- The PGC functions in PGLIB can read to, write to disk from, and move images between buffers and the screen. If you specify the constant SCREEN as a parameter to PG_Read, PG_Save or PG_Move instead of a far pointer to a buffer, PGLIB will create a far pointer to the screen for you and use that as the buffer. (This is a good place to remind you to be sure to use far pointers to buffers.) This buffer flexibility allows you to read in PGC images without displaying them and hold multiple PGC images in memory at one time. The following command will copy an image from a memory buffer to the screen: result = PG_Move(SCREEN, (char far *)mybuffer); Buffers can be dynamically allocated or static char arrays. They must be 1920 bytes in size. Any time you specify SCREEN as the target of a PGC function, a screen refresh is also performed. Function Reference (alphabetical) ------------------ void PG_ClearScreen(void) Parameters: None Returns: Nothing Clears the screen in Graphics or Text mode. int PG_GetPixel(int x, int y) Parameters: int x - the x (horizontal) pixel coordinate int y - the y (vertical) pixel coordinate Returns: 1 if on, 0 if off This function is used to determine whether a pixel on the screen is on (BLACK) or off (WHITE). The constants BLACK and WHITE can be used. See "Coordinates" section above. I do not use the BIOS to read the pixel because it did not work on earlier versions of the Portfolio ROMs. void PG_GoGraphic(void) Parameters: None Returns: Nothing Puts the Portfolio into Graphics mode and clears the screen. No refresh required. void PG_GoText(void) Parameters: None Returns: Nothing Puts the Portfolio into Text mode and clears the screen. No refresh required. int PG_Init(void) Parameters: None Returns: 1 if successful, 0 if not a Portfolio Checks to make sure program is running on a Portfolio and initializes the Portfolio int61 routines which are used by some library routines. void PG_Line(int x1, int y1, int x2, int y2, int color) Parameters: int x1 - upper left horiz. coordinate int y1 - upper left vertical coordinate int x2 - lower right horiz. coordinate int y2 - lower right vertical coordinate int color - BLACK or WHITE Returns: Nothing Draws a line from (x1,y1) to (x2,y2) in either BLACK or WHITE. No refresh required. See "Coordinates" section above. int PG_Read(char *filename, char far *buffer) Parameters: char *filename - pointer to name of PGC file char *far buffer - buffer to receive image Returns: 0 if successful, error code if not This routine reads a PGC file from disk into the specified buffer or to the screen. See "Buffers" section above. If reading to the screen, a screen refresh is done. Error Codes: BADOPEN - error opening file NOTPGC - not a PGC file void PG_Move(char far *destbuffer, char far *srcbuffer) Parameters: char far *destbuffer - pointer to destination buffer. char far *frombuffer - pointer to source buffer. Returns: Nothing Copies a PGC image from one buffer to another. Either of the buffers can be the screen. See "Buffers" section above. void PG_Plot(int x, int y, int color) void PG_QPlot(int x, int y, int color) Parameters: int x - the x (horizontal) pixel coordinate int y - the y (vertical) pixel coordinate Returns: Nothing This function is used to turn pixels on and off. The constants BLACK and WHITE can be used. See "Coordinates" section above. No refresh required. The PG_QPlot routine write directly to the screen. It is not any faster than the BIOS because PGLIB is currently written in C. The "Q" is for quiet, not quick. PG_QPlot does not refresh the screen; therefore, you can plot a bunch of pixels and then call PG_Refresh at the end. void PG_Refresh(void) Parameters: None Returns: Nothing Forces a screen refresh so changes can be seen. int PG_Show(char *filename) Parameters: char *filename - pointer to name of PGC file Returns: 0 if successful, error code if not Reads a PGC file from disk directly to the screen and then forces a screen refresh. Error Codes: BADOPEN - error opening file NOTPGC - not a PGC file int PG_Save(char *filename, char far *buffer) Parameters: char *filename - pointer to name of PGC file char far *buffer - pointer to buffer holding image Returns: 0 if successful, error code if not Save the contents of a buffer or the screen to a PGC file. See "Buffers" section above. Error Codes: BADOPEN - error opening file BADWRITE - error writing file Sample Programs --------------- I have only included one sample program with this release of PGLIB. It is called pgsample.c. It should compile under small model with either Microsoft or Turbo C. It uses all the PGLIB functions except PG_GETPIXEL. The strange screen wipe look is just the way the Portfolio does a screen refresh. Future Enhancements ------------------- PGLIB is written in C with some in-line assembler. I will be converting more of the functions to in-line assembler and ultimately pure assembly language. This should make it a little smaller and faster. Don't expect miracles. I also plan to add routines to do text output onto graphics screens, something that isn't supported by the Portfolio's BIOS. If you have any suggestions of features to add to PGLIB (within reason), please contact me. Revision History ---------------- Version 1.0 - 1/9/91 Initial Release Licensing --------- PGLIB contains an embedded copyright message. You are not allowed under any circumstances to remove or alter it in any way. If you use LZEXE to compress your programs, I understand that the copyright message is not readable in the executable file on disk. That is an acceptable situation. However, if the file is uncompressed, the copyright message must be intact. I have defined three types of applications. Check the paragraph below for further licensing restrictions based on the type of application you are creating: Public Domain or Freeware [This is a program you donate to the public domain and ask for no money in return. You may still retain rights to the program and restrict it's sale.] I place no further licensing restrictions on Public Domain programs created using PGLIB. Shareware [This is a program that contains a request for a donation of some sort. Sometimes promising added value if one registers (i.e. a printed manual).] If you create a Shareware program using PGLIB, you must send a copy (electronically or by mail) to Software Vineyard and consider Don Messerli a "registered user" of your program granting me all rights that entitles me to (if any). You must also mention Software Vineyard in your program's documentation with the a message similar to the following: "PGC Graphics Routines are Copyright (c)1991 Software Vineyard." Commercial Software [This is a program that you require payment for.] If you create a Commercial program using PGLIB, you must fulfill all of the requirements listed above for Shareware (including sending a copy to Software Vineyard) and pay a one time fee of $25 (US). I don't think these terms are unfair. If you do, we can discuss it. Or you can write your own routines and not use PGLIB. How to Contact Don Messerli (Software Vineyard) ----------------------------------------------- Compuserve 72500,1671 Mail: Software Vineyard GEnie DMESS 1394 Amherst St. #17 Buffalo, NY 14216 A Final Word (for now) ---------------------- If you like PGLIB, let me know. Feedback is the only way I can improve my programs. Most importantly, have fun! DM