#define C_only
#define Pascal_only

Documentation of PRINTBGI package (C) Andrzej Resztak 1991,1992,
all rights reserved.

To contact the author write to

Andrzej Resztak
ul. K. Wallenroda 2c/18
20-607 Lublin
POLAND

or (preferably) to e-mail address:
[email protected]



========================================================================
FUNCTIONS DETAILS
========================================================================

Following section will describe in details all functions which
can be found in PRINTBGI package. This package as distributed in
shareware version was developed and tested in LARGE and HUGE memory
models (I suppose they are the modes most graphic programs use)
using BC++ v2.0. To use it in other memory model you may need
full sources of it (available from the author - see REGISTER.DOC).

When it is mentioned that the function returns zero on success and
nonzero on failure it means that one of the following codes may be
returned
0 - success.
PRT_NO_MEMORY 1
PRT_WRONG_PARAMETERS 2
PRT_NOT_INITIALIZED 3
PRT_IO_ERROR 4
PRT_ERROR 5
Occasionally you can get other code returned from standard Borland graphic
functions or write procedure. You may also get returned code from your own
DrawFunc routine if it returns nonzero code.


All functions can be divided into following categories.
- Functions used to set various work parameters.
PRT_Buffer
PRT_FormFeedNeeded
PRT_LinkDrivers
PRT_ReadDrivers
PRT_RescaleFillPattern
PRT_Send
PRT_SetBuffer
PRT_SetOutName
PRT_SetMargins
PRT_SetDriver
PRT_SetUserPrintFunc
PRT_SetViewSize
PRT_SetErrorFunc
PRT_SetHaltVariable
PRT_SetOpenFunc
PRT_SetCloseFunc
PRT_SetPrinterDrv
PRT_SetWriteFunc
PRT_EMSBuffer
PRT_XMSBuffer
setcharsize_Pix
setfillpattern16
- Functions used to print out the picture
PRT_End
PRT_PrintBGI
and some functions used internally by PRT_PrintBGI
(use them only if necessary, the preferable method is using
PRT_PrintBGI which will virtually do all necessary work for you).
PRT_AllocateBuffer
PRT_BuildBitMap
PRT_BufferNeeded
PRT_closegraph
PRT_EMSBufferNeeded
PRT_EndPrt
PRT_FreeBuffer
PRT_getpixel
PRT_initgraph
PRT_InitPrt
PRT_installuserdriver
PRT_PrintBuffer
PRT_registerfarbgidriver
PRT_Unregisterfarbgidriver
PRT_WritePCX
PRT_XMSBufferNeeded
- Functions used to get some information about package and current
settings of miscellaneous parameters.
getfillpattern16
PRT_DriverName
PRT_DriverNo
PRT_grapherrormsg
PRT_MaxDriver
PRT_MaxMode
PRT_ModeName
PRT_ModeParms
PRT_ModeNo
PRT_Resolution
PRT_Version

Global export variable
PRT_HaltPrinting


Here are all functions listed alphabetically. Specification will begin
with function declaration followed by exact description of all parameters.



BGI_LoadDriver
==============

#if C_only
void far* BGI_LoadDriver( int driverNo, const char far* bgiPath );
#endif C_only
#if Pascal_only
Function BGI_LoadDriver( driverNo: integer; bgiPath: string ): pointer;
#endif Pascal_only

It is internally used function to load BGI driver into RAM memory.
Parameter driverNo specifies driver to be load and bgiPath specifies
where to look for it. It returns pointer to memory at which driver was
loaded or NULL (NIL in pascal) in case of unsuccessful execution.
Why you may want to use it? O.K. I didn't write any replacement for
Borland's graphic kernel or for BGI drivers. In fact I use their
installuserdriver and registerbgidriver functions to let them know about
using BGI drivers. But there is one limitations. Both above mentioned
functions can be used only if no graphic system is active. So if you
initialized graphic video system already (using BGI_initgraph) and want
to initialize another BGI driver (for printer system example) which
has not been used already I use BGI_LoadDriver function to load
needed driver into memory. And it fails because you are in graphic mode
already and I cannot use either installuserdriver or registerbgidriver.
To avoid such situations you may want to load all needed drivers into
memory before initializing first BGI driver you will use.


BGI_installuserdriver
=====================

#if C_only
int BGI_installuserdriver( const char far *filename,
int huge (*detect)(void),
int BGIgroup );
#endif C_only
#if Pascal_only
Function BGI_installuserdriver( filename: string; detect: pointer,
int BGIgroup ): integer;
#endif Pascal_only

If you want to use "multiples BGI" feature you must use this
function to install any non Borland BGI driver rather than using
standard Borland installuserdriver function. From your point of
view the only difference between them two is that my version
has an extra third parameter which at call should specify
to which group of BGI drivers installed driver belongs. Currently
I divided all BGI drivers to two groups. One deals with
video displays and the other attends to printers.
You may use symbolic constants Scrn_BGIgroup and Prt_BGIgroup
to define to which group installed BGI driver belongs.
But note that in current version I ignore BGIgroup parameter.
Also the detect function should be specified as NULL (nil) in current
version for all non video drivers.
This function returns negative error code on failure and BGI driver
number on success.


BGI_ActiveDriverNo
==================

#if C_only
int BGI_ActiveDriverNo(void);
#endif C_only
#if Pascal_only
Function BGI_ActiveDriverNo: integer;

#endif Pascal_only

Returns positive number of currently active BGI driver or negative
error code if no BGI driver is active. Note that when you didn't use
BGI_initgraph but standard initgraph function to initialize graphic the
return value will be incorrect.

BGI_initgraph
=============

#define Scrn_BGIgroup 1
#define Prt_BGIgroup 2
#if C_only
int BGI_initgraph( int far *Driver, int far *Mode,
const char far *BGIPath, int BGIgroup );
#endif C_only
#if Pascal_only
Function BGI_initgraph( var Driver, Mode: integer;
BGIPath: string; BGIgroup: integer );
#endif Pascal_only

Use it instead of standard initgraph function. The extra parameter
BGIgroup specifies which kind of graphic devices we want to initialize.
You may specify either Scrn_BGIgroup for initializing video display
or PRT_BGIgroup for initializing graphic printer.
Rather don't use BGI_initgraph directly to initialize printer graphic
mode. Instead please use PRT_initgraph function or even better
PRT_PrintBGI which will do all work for you.
The system don't have to be in text mode to use BGI_initgraph
function. It's the difference from standard initgraph function.
Before call of standard Borland initgraph function the system
must be in text mode. That is no BGI driver can be active when
invoking standard initgraph function. It implies that you may use
use initgraph only after closegraph, of course except first time.
When using BGI_initgraph you have no such limitation. If there is
any BGI driver active when you invoke BGI_initgraph it is suspended
and new BGI driver receives control.


BGI_closegraph
==============

#if C_only
int BGI_closegraph(void);
#endif C_only
#if Pascal_only
Function BGI_closegraph: integer;
#endif Pascal_only

Closes down recently activated BGI driver. If there
were no previous BGI drivers active at last call to BGI_initgraph
it closes down the whole graphic system. Otherwise the BGI driver
active before last call of BGI_initgraph resumes control.
Returns 0 on success, nonzero on failure.


BGI_registerfarbgidriver
========================

#if C_only
int BGI_registerfarbgidriver(void far pascal (*driver)(void) );
#endif C_only
#if Pascal_only
Function BGI_registerfarbgidriver(driver: pointer): integer;
#endif Pascal_only


BGI_getgraphmode
================

#if C_only
int BGI_getgraphmode( int BGIgroup );
#endif C_only
#if Pascal_only
int BGI_getgraphmode( int BGIgroup );
#endif Pascal_only


BGI_setgraphmode
================
#if C_only
void BGI_setgraphmode(int mode);
#endif C_only
#if Pascal_only
Procedure BGI_setgraphmode(mode: integer);
#endif Pascal_only


BGI_getmodename
===============

#if C_only
const char far* BGI_getmodename(int mode);
#endif C_only
#if Pascal_only
Function BGI_getmodename(int mode): string;
#endif Pascal_only


BGI_getresolution
=================

#if C_only
int BGI_getresolution(int far *x, int far*y);
#endif C_only
#if Pascal_only
Function BGI_getresolution(var x,y: integer): integer;
#endif Pascal_only

Assigns to x and y number of points per inch in horizontal and vertical
directions respectively.
In current release you will never see resolution larger than 178 dpi.
It is relevant to the bug in Borland graphic kernel. It seems that emulation
of arc function (my BGI driver does not contain routine to draw arc and
thus uses Borland arc emulation function) does not store arc start and
end position. So the call to getarccoords returns wrong result for devices
of vertical resolution of 179 dpi or larger. To eliminate this problem
I always inform graphic kernel that device has vertical resolution lower
than 179 dpi. To achieve correct aspect ratio the horizontal resolution
is also decreased accordingly.


getfillpattern16
=================

#if C_only
void getfillpattern16 ( char FAR * upattern );
#endif C_only
#if Pascal_only
Procedure GetFillPattern16 ( upattern: FillPatternType );
#endif Pascal_only

You may use this function to copy 16x16 bit fill pattern set by
setfillpattern16 function into the 32 (!) byte area pointed to by upattern.
This function may be used only when BITIMAGE BGI driver is active, for all
other BGI drivers it will be ignored.
See also PRT_RescaleFillPattern.



PRT_AllocateBuffer
===================

#if C_only
int PRT_AllocateBuffer ( void );
#endif C_only
#if Pascal_only
Function PRT_AllocateBuffer: integer;
#endif Pascal_only

This function allocates buffer for picture bit image map. It
allocates as much memory as allowed by PRT_SetBuffer but not more than
needed.
Note that attempt to allocate buffer is performed in the
following order. First it is tried to allocate XMS buffer next EMS and
at last conventional one. It may result in allocating buffer smaller
than available memory (e.g if there is 200k of free conventional memory
and 32k of free EMS memory then 32k EMS buffer will be allocated).
Note also that buffer always fits in one kind of memory. There is no
possibility to create buffer say 200K large containing of 60K of
conventional memory and rest of EMS or XMS memory.
Used internally by PRT_PrintBGI may also be called by user needing
some nonstandard possibilities.
Returns 0 on success, nonzero on failure.

see also PRT_SetBuffer, PRT_Buffer, PRT_EMSBuffer, PRT_XMSBuffer,
PRT_BufferNeeded, PRT_EMSBufferNeeded, PRT_XMSBufferNeeded.


PRT_Buffer
=============

#if C_only
int PRT_Buffer ( void far *address, long size, int usable )
#endif
#if Pascal_only
Function PRT_Buffer ( address: pointer; size: longint; usable: integer ):
integer;
#endif
Defines conventional memory buffer for use by the PrintBGI package.
Parameters:
usable : 0 (zero) means not to use conventional memory. Other
arguments are in that case ignored (but preferably should
also be zero).
address : Address of conventional memory buffer to use or NULL
(buffer will be allocated later by other functions of
this package).
size : If address is not NULL defines size (in bytes)
of the caller allocated buffer.
If address is NULL than
- positive value defines maximum number of memory
which can be used for the buffer by PrintBGI package.
- negative value defines minimum number of memory left
free after buffer allocation.
- zero allows to allocate as much memory as needed for
the buffer leaving only absolutely minimum free.

Note that allocating buffer larger than 64Kb (to be precise 64KB-16 bytes)
is a little tricky in Turbo Pascal. Although I done it in documented way
it might not work in future versions of Turbo Pascal ( that is if heap
memory manager will be changed). I can also give you no guarantee it will
work in all circumstances.
See also PRT_EMSBuffer,PRT_XMSBuffer.

PRT_BufferNeeded
=================

#if C_only
long PRT_BufferNeeded ( int x1, int y1, int x2, int y2 );
#endif C_only
#if Pascal_only
Function PRT_BufferNeeded ( x1,y1,x2,y2: integer ): longint;
#endif Pascal_only

Returns size of buffer needed to draw picture of specified size on
printer set by PRT_SetDriver. If there exist less free memory than needed
then picture would be drawn in pieces. In that case results of all
functions reading pixel values may be inaccurate.
XMS buffer requires some more memory to build a picture. Use
PRT_XMSBufferNeeded in that case.
May be called only after PRT_SetDriver.
See also PRT_EMSBufferNeeded, PRT_XMSBufferNeeded.


PRT_BuildBitMap
================

#if C_only
int PRT_BuildBitMap (
int far * graphdriver, int far *graphmode,
const char far *pathtodriver,
int x1,int y1, int x2,int y2,
int ( huge * far Draw)(void far* UserPointer),
void far * UserPointer );
#endif C_only
#if Pascal_only
Type DrawType = function DrawFunc(UserPointer:pointer) : integer;
Function PRT_BuildBitMap ( var graphdriver,graphmode: integer;
pathtodriver: string;
x1,y1,x2,y2: integer;
DrawFunc : DrawType,
UserPointer: pointer );
#endif Pascal_only

Parameters
graphdriver,graphmode,pathtodriver - see PRT_initgraph.
x1,y1,x2,y2 - coordinates of the rectangular area of the whole
picture currently being build by the BitImage BGI driver.
All requests to read or write outside the specified region
will be ignored. Functions reading pixel value from
outside of the specified region will always return zero
result (without error set).
DrawFunc - see PRT_PrintBGI.
UserPointer - see PRT_PrintBGI.

Initializes BITIMAGE BGI driver by calling PRT_initgraph. Calls
DrawFunc and DOES NOT close down BITIMAGE BGI driver (and does not free
the buffer with created bit image map). This should result in built
(x1,y1,x2,y2) rectangle of bit image map cut from the entire picture.

This function assumes that PRT buffer large enough to contain
(x1,y1),(x2,y2) rectangle was already allocated using PRT_AllocateBuffer
function.

Returns 0 on success, nonzero on failure.


PRT_closegraph
===============

#if C_only
int PRT_closegraph(void);
#endif C_only
#if Pascal_only
Function PRT_closegraph: integer;
#endif Pascal_only

Closes down the BGI driver which was being used to print the picture out.
In the case of BitImage BGI driver being used this function DOES NOT free
the buffer with created bit image map of the picture. Just you may close
down the BitImage BGI driver and still have buffer with created bit image
map of the picture. It enables you to activate any other BGI driver and
display created pixel map. But remember to free later the buffer calling
PRT_FreeBuffer function.

Returns 0 on success, nonzero on failure.


PRT_DriverName
===============

#if C_only
int PRT_DriverName ( unsigned driverno, char FAR * FAR* name_ptr );
#endif C_only
#if Pascal_only
Function PRT_DriverName ( driverno: word; var name_ptr: StringPtr ): integer;
#endif Pascal_only

Assigns to StringPtr pointer pointing to static string containing the name
of driver numbered driverno. The driver name is general name of all printers
supported by the driver or the name of the most common printer from
all supported by it. It can be used to list user all allowable printers and
let him choose the appropriate one.
Returns 0 on success, nonzero on failure.


PRT_DriverNo
=============

#if C_only

int PRT_DriverNo ( void );
#endif C_only
#if Pascal_only
Function PRT_DriverNo: integer;
#endif Pascal_only
Returns current driver number as set by PRT_SetDriver or minus one.


PRT_EMSBuffer
=============

#if C_only
int PRT_EMSBuffer ( int handle, long size, int usable )
#endif
#if Pascal_only
Function PRT_EMSBuffer ( handle: integer; size: longint; usable: integer ):
integer;
#endif
Defines EMS buffer for use by the PrintBGI package.
Parameters:
usable : 0 (zero) means not to use EMS memory. Other arguments are
in that case ignored (but preferably should also be zero).
handle : Number of EMM handle to use for the buffer or zero (buffer
will be allocated by the package)
size : If handle is nonzero defines amount of memory (in bytes)
allocated to that handler by the caller.
If handle is zero then
- positive value defines maximum number of memory (which
will be rounded down to 16 KB boundary) that can be
used for the buffer by PrintBGI package.
- negative value defines minimum number of memory left
free after buffer allocation.
- zero allows to allocate as much memory as needed for
the buffer leaving only absolutely minimum free.

See also PRT_Buffer,PRT_XMSBuffer.


PRT_End
=======

#if C_only
int PRT_End(void);
#endif
#if Pascal_only
Function PRT_End: integer;
#endif

Finishes the PrintBGI toolkit. Closes down all files used, frees
memory. Usually used before end of the program.


PRT_EndPrt
==========

#if C_only
int FAR_PROC _PRT__pascal PRT_EndPrt ( int handle );
#endif
#if Pascal_only
Function PRT_EndPrt ( var handle: file ): integer;
#endif

Sends printer ending sequence to the specified handle.
To print it out uses PRT_write function set by PRT_SetWriteFunc routine.
Note also that my standard PRT_Write function will call PRT_WriteError
function (set by PRT_SetErrorFunc) whenever output error occurs.
Returns 0 on success, nonzero on failure.
See also PRT_SetOpenFunc, PRT_SetCloseFunc, PRT_SetWriteFunc,
PRT_SetErrorFunc.


PRT_FormFeedNeeded
==================

#if C_only
int PRT_FUNC PRT_FormFeedNeeded ( int ffneeded );
#endif
#if Pascal_only
Function PRT_FormFeedNeeded ( ffneeded: integer ): integer;
#endif

This function informs the printer driver whether to send form feed
command to the printer at the end of picture printing.
The current setting of form feed option is returned as a function
result.
If not called the default value is 1 for laser jet printers and
0 for all others.


PRT_grapherrormsg
============

#if C_only
char far * FAR_PROC PRT_grapherrormsg ( int errorcode );
#endif
#if Pascal_only
Function PRT_grapherrormsg ( errorcode: integer ): string;
#endif
Returns pointer to error message associated with errorcode.


PRT_FreeBuffer
==============

#if C_only
int PRT_FreeBuffer (void);
#endif
#if Pascal_only
Function PRT_FreeBuffer: integer;
#endif Pascal_only

Internal procedure freeing the buffer allocated by PRT_AllocateBuffer.
In the case of freeing EMS buffer does not restore EMS mapping to the state
from before PRT_AllocateBuffer. Thus you must be very careful if your
program uses also EMS memory.
Returns 0 on success, nonzero on failure.



PRT_getpixel
=============

#if C_only
int PRT_getpixel ( int x, int y );
#endif C_only
#if Pascal_only
Function PRT_getpixel ( x,y: integer );
#endif Pascal_only

Performs the same function as standard Borland getpixel function but with
two differences.
Parameters x and y are not whole picture relative
but buffer relative. It makes no difference if there is enough memory
for the whole picture. But if there is not enough free memory
PRT_getpixel(0,0) will return value of first pixel in the buffer
not the first pixel on the virtual screen. What this pixel is at the whole
picture depends on parameters x1 and y1 passed to PRT_SetViewSize.
The second difference is that if you load ( or link in) the driver
manually you will be able to call this function after closing BITIMAGE BGI
driver (after PRT_closegraph and maybe also after activating another BGI
driver) but, of course before releasing the screen buffer, and unregistering
the driver (see PRT_Unregisterfarbgidriver). If the driver is loaded
automatically (e.g. by PRT_initgraph) it will be deleted by PRT_closegraph
and you MUST NOT use this function in that case when BGI driver is not
active.



PRT_initgraph
==============

#if C_only
int PRT_initgraph( int far * graphdriver, int far *graphmode,

const char far *pathtodriver
);
#endif C_only
#if Pascal_only
Function PRT_initgraph ( var graphdriver,graphmode: integer;
pathtodriver: string ): integer;
#endif Pascal_only

Parameters
*graphdriver : an integer that specifies graphic driver to be used.
Note that earlier you should install BGI driver
(currently BitImage driver only is included into the
package) using PRT_installuserdriver function.
If you specify DETECT as a passing argument value
then the driver last used in PRT_initgraph or last installed
using PRT_installuserdriver will be used. If none BGI printer
driver was installed so far than PRT_installuserdriver will
be called to install appropriate driver for printer defined
by PRT_SetDriver. No true auto detection is (or will be)
available.
*graphmode : an integer that specifies graphic mode to be used.
It should be zero value since in current version you
must specify desired printing mode using PRT_SetDriver
function.
pathtodriver : Specifies path to BGI drivers and CHR fonts. This parameter
will be passed further to standard initgraph routine.


Initializes BITIMAGE BGI driver for creating bit image map.
Note that YOU MUST earlier specify rectangular area for which bit map will
be created by calling PRT_SetViewSize function.
All requests for drawing (or reading) pixels outside that
area will be ignored without any error codes. This would enable
building the screen from rectangular pieces and printing it out even if
there is not enough free memory to build the whole bit image map of
printed picture at once.

You must call PRT_SetViewSize before PRT_initgraph.
(x1,y1),(x2,y2) area (specified by PRT_SetViewSize) must fill
entirely within - PREVIOUSLY - allocated buffer (via PRT_AllocateBuffer),
otherwise an error code is return.
Returns 0 on success, nonzero on failure.


PRT_InitPrt
============

#if C_only
int FAR_PROC _PRT__pascal PRT_InitPrt ( int handle );
#endif
#if Pascal_only
Function PRT_InitPrt ( var handle: file ): file;
#endif

Sends printer initialization sequence to the specified handle.
To print it out uses PRT_write function set by PRT_SetWriteFunc routine.
Note also that my standard PRT_Write function will call PRT_WriteError
function (set by PRT_SetErrorFunc) whenever output error occurs.
Returns 0 on success, nonzero on failure.
See also PRT_SetOpenFunc, PRT_SetCloseFunc, PRT_SetWriteFunc,
PRT_SetErrorFunc.


PRT_installuserdriver
=====================

#if C_only
int PRT_installuserdriver ( const char far * name,
int huge (*detect)(void) );
#endif
#if Pascal_only
Type DetectFunc = function: integer;
PRT_installuserdriver ( name: string; detect: DetectFunc ): integer;
#endif

Used instead of standard Turbo installuserdriver function. You should
use it to install BitImage BGI driver.


PRT_LinkDrivers
===============

#if C_only
int PRT_LinkDrivers(void);
#endif
#if Pascal_only
Function PRT_LinkDrivers: integer;
#endif

Forces linking printers definitions into executable file at linking
time. You must use either PRT_LinkDrivers or PRT_ReadDrivers before
any other function of this toolkit.
Returns zero on success.
See also PRT_ReadDrivers.


PRT_MaxDriver
==============

#if C_only
int PRT_MaxDriver ( void );
#endif C_only
#if Pascal_only
Function PRT_MaxDriver : integer;
#endif Pascal_only

Returns maximum allowed printer driver number in PRINTBGI package
or -1 if there is no printers definitions file.
Printer drivers are numbered starting from 1. Please do not
use driver number 0. It is intended for future use. Use of it
in current version will give you unpredictable results.
See also PRT_SetDriver, PRT_DriverName, PRT_DriverNo.



PRT_MaxMode
============

#if C_only
int PRT_MaxMode ( unsigned driverno, int FAR *maxmode );
#endif C_only
#if Pascal_only
Function PRT_MaxMode ( printerno: word; var maxmode: integer ): integer;
#endif Pascal_only

Assigns to maxmode maximum mode number allowed for given driverno.
Returns 0 on success, nonzero on failure.
See also PRT_ModeName, PRT_ModeNo.


PRT_ModeName
=============

#if C_only
int PRT_ModeName ( unsigned driverno, int modeno,
char FAR* FAR* name_ptr );
#endif C_only
#if Pascal_only
Function PRT_ModeName ( driverno: word; modeno: integer;
var name_ptr: StringPtr ): integer;
#endif Pascal_only

Assigns to StringPtr pointer pointing to static string containing name
of mode modeno and printer numbered driverno. Note that this static area
may be overwritten at next call to any other package function.
It can be used to list user all allowable modes and let him choose one.
Returns 0 on success, nonzero on failure.


PRT_ModeNo
==========

#if C_only
int PRT_ModeNo ( void );
#endif C_only
#if Pascal_only
Function PRT_ModeNo: integer;
#endif Pascal_only

Returns current mode number as set by PRT_SetDriver or negative
value.


PRT_ModeParms
=============

#if C_only
int PRT_ModeParms ( unsigned driverno, int modeno,
unsigned far* xRes, unsigned far* yREs,
unsigned far* colorsNo );
#endif C_only
#if Pascal_only
Function PRT_ModeName ( driverno: word; modeno: integer;
var xREs,yREs,colorsNO: word ): integer;
#endif Pascal_only

Assigns to xRes and yRes number of dots per inch in horizontal and
vertical directions respectively. To colorsNo assigns number of colors
available in mode modeno for driver driverno.
Returns 0 on success, nonzero on failure.




PRT_PrintBGI
=============

#if C_only
int far PRT_PrintBGI ( int far * graphdriver, int far *graphmode,
const char far
*pathtodriver,
int ( huge * far /* pascal */ Draw)
(void far* UserPointer),
void far* UserPointer );
#endif C_only
#if Pascal_only
Type DrawType = function DrawFunc(UserPointer: pointer): integer;
Function PRT_PrintBGI ( var graphdriver,graphmode: integer;
pathtodriver: string;
DrawFunc : DrawType,
UserPointer: pointer );
#endif Pascal_only

Parameters
graphdriver,graphmode,pathtodriver - see PRT_initgraph.
Draw : function drawing picture you want to print.
UserPointer : This parameter is not used by my library routines
and will be passed unchanged to your Draw function.
It may point to list of parameters for your Draw
function.

This is the main function of the whole package. In fact it does most
of the work and using it is the most recommended way to use the whole
PRINTBGI package. Of course in some nonstandard situations you may
want to use some lower level routines to get more control over the package.
But I think it will be very rarely case.

I'll list all functions it does in the order they are performed.
It should let you better understand other functions of this
package.

So it does the following.
1. Checks the correctness of arguments used in call to
PRT_SetDriver. Returns immediately PRT_NOT_INITIALIZED value if
they are incorrect, otherwise goes to step 2.
2. Checks if any BGI driver was active when it was called. If it
was then closes it down and saves information needed to restore
screen graphic mode. Note that this step (or step 7
restoring caller graphic mode) may not work correctly at all
circumstances (since for example it is very hardly to guess
what BGI driver was active at call to PRINTBGI).
So I highly recommend you to close down any BGI drivers you
were using before calling this function. Note also that
restorecrtmode function DOES NOT close down BGI driver but
only deactivates it. So you MUST USE closegraph function rather
than restorecrtmode before calling PRT_PrintBGI.
3. Allocates buffer using PRT_AllocateBuffer function.
If buffer allocation is unsuccessful returns immediately, otherwise
computes window size filling entirely in the allocated buffer
and calls PRT_SetViewSize to set it. This window may (or may not)
cover the whole printing picture.
4. Calls PRT_Open and PRT_InitPrt to open file handle and to send
initialization codes to the printer.
5. Calls PRT_BuildBitMap to create bit image map of current
rectangular piece of picture which fits into allocated buffer.
PRT_BuildBitMap is described earlier in this chapter.
6. Calls PRT_PrintBuffer to print out current buffer ( which now
contains one piece of picture). If it is not the last
(or the only one) piece to print returns to point 5.
7. Calls PRT_EndPrt and PRT_Close;
8. Calls PRT_closegraph to close down the BGI driver used to create
bit image map of the printed picture.
9. Frees allocated buffer by calling PRT_FreeBuffer.
10. If in step 2 the active BGI driver was closed down tries now to
reactivate it. Note that it uses standard detectgraph function to
determine which BGI driver reactivate. So if you had nonstandard
BGI drivers active (e.g. SVGA or VGA256) it may happen that standard
VGA driver will be reactivate instead of the actually active one.
To avoid this problem either close down video BGI driver (using
closegraph) before calling PRT_PrintBGI or install nonstandard
BGI drivers with appropriate auto detection function
(see installuserdriver function in Borland documentation).
Note also that screen image is not restored.
11. Returns to the caller.


Function DrawFunc passed as an argument should meet the following
conditions.
- It draws on the screen the picture you want to print.
- It does not use any nonstandard graphic procedures (that is not
defined in GRAPH.TPU or GRAPHICS.LIB) to manipulate screen
output.
- It does not use initgraph, restorecrtmode, closegraph or setgraphmode
procedure. It simply assumes that appropriate graphic mode was
established before calling it.
- It is written in BGI independent way. That is it uses getmaxx,
getmaxy, getmaxcolor, getaspectratio to get device dependent
characteristic and scales all output according to it.
- Although it is not necessary it is recommended that it draws
the same picture (if the same BGI driver is used) each time
it is called.
This may be because if there is not enough memory to build bit image
map of the entire picture at once it is necessary to call
DrawFunc routine few times to create the picture piece by
piece (lines by lines). If it would draw different output at
consecutive calls then printed lines would not suit each other.
- It returns zero on success and nonzero on failure. This nonzero code
will cause immediate finish of the PRT_PrintBGI function and will
be also returned by it to the caller.
- It is declared as huge function if you are using C compiler.


Note also that if there is not enough free memory to build the whole
bit image map at once then some graphic functions which read the
screen explicitly (e.g. getpixel,getimage) or implicitly (e.g. floodfill) may
produce inaccurate results. This may happen if they refer to currently
not building part of the picture.
Setting PRT_HaltPrinting variable to nonzero value lets you break
this function before it will finish.


PRT_PrintBuffer
================

#if C_only
typedef int* PRT__handleT;
int PRT_PrintBuffer (PRT__handleT *handlePtr);
#endif C_only
#if Pascal_only
typefilePtr = ^file;
Function PRT_PrintBuffer(var handlePtr: filePtr): integer;
#endif Pascal_only

Prints entire "screen" buffer to the specified handle
adding necessary control codes (see PRT_SetDriver).
To print out the buffer it uses PRT_Write function set by
PRT_SetWriteFunc routine.
Note also that my standard PRT_Write function will call PRT_WriteError
function (set by PRT_SetErrorFunc) whenever output error occurs.

Returns 0 on success, nonzero on failure.

See also PRT_SetOpenFunc, PRT_SetCloseFunc, PRT_SetWriteFunc,
PRT_SetErrorFunc.


PRT_ReadDrivers
===============

#if C_only
int PRT_ReadDrivers
( const char PRT__FAR_PTR* path, const char PRT__FAR_PTR* filename );

#endif
#if Pascal_only
Type FnameStr = string[12];
Function PRT_ReadDrivers (path: DirStr; filename: FnameStr): integer;
#endif

Reads printers definitions from filename file at execution time.
Path parameter may point to path containing printers definition file.
You must use either PRT_LinkDrivers or PRT_ReadDrivers before
any other function of this toolkit.
Returns zero on success.
See also PRT_LinkDrivers.


PRT_registerfarbgidriver
========================

#if C_only
int PRT_registerfarbgidriver ( void far pascal
(*driver)(void) );
#endif
#if Pascal_only
Type DriverProc = procedure;
PRT_registerbgidriver ( driver: DriverProc ): integer;
#endif
To register BGI driver from the package use PRT_registerfarbgidriver
instead of standard registerbgidriver or registerfarbgidriver function.
But note that before deleting registered driver from memory you
MUST use PRT_Unregisterfarbgidriver function.


PRT_RescaleFillPattern
=======================

#if C_only
int PRT_RescaleFillPattern ( int r );
#endif C_only
#if Pascal_only
Function PRT_RescaleFillPattern ( r: integer ): integer;
#endif Pascal_only

Since external graphic devices have in most cases grater maximum
possible resolution than screens, standard 8x8 fill patterns seem to be
too small to use. This procedure let you demand of rescaling standard
8x8 fill patterns to 16x16 ones.
Parameter r means
0 = never rescale to 16x16,
1 = always rescale to 16x16,
-1 = rescale to 16x16 at high densities only.
The default value is -1.
Returns 0 on success, nonzero on failure.
If used must be called before initializing BITIMAGE BGI driver.

See also setfillpattern16.


PRT_Resolution
===============

#if C_only
int PRT_Resolution ( int FAR *Xres, int FAR *Yres );
#endif C_only
#if Pascal_only
Function PRT_Resolution ( var Xres,Yres : integer ): integer;
#endif Pascal_only

Assigns to Xres and Yres dpi (dots per inch) resolution in
appropriate direction according to last call of PRT_SetDriver.
Returns 0 on success, nonzero on failure.


PRT_Send
========

#if C_only
int PRT_Send( const void far *p, unsigned slen);
#endif
#if Pascal_only
Function PRT_Send( p: string): integer;
#endif

Calls PRT_Open, PRT_Write, PRT_Close to send slen bytes
pointed to by p to the output file of a name set by PRT_SetOutName.
Returns zero om success, nonzero on failure.
See also PRT_SetOutName, PRT_Open, PRT_Write, PRT_Close.

PRT_SetBuffer
==============

#if C_only
int PRT_SetBuffer ( long size, unsigned BufOpt );
#endif C_only
#if Pascal_only
Function PRT_SetBuffer ( size : longint; BufOpt: word ): integer;
#endif Pascal_only

Parameters
BufOpt : specifies what kind of memory may be used for buffer.
Allowed values.
NotUseEMS (1) - use XMS or conventional memory
NotUseXMS (2) - use EMS or conventional memory.
NotUseEMS+NotUseXMS - use conventional memory only.
0 - use any memory.
size : if positive specifies maximum amount of memory that
can be used for the buffer.
If negative specifies how minimum amount of memory that
must be left free after buffer allocation.
This parameter is currently meaningful only if conventional
memory is used.
Returns
0 on success, nonzero on failure.


PRINTBGI package uses the so called screen buffer to build bit
image map of printing output in it. This procedure specifies what kind
of memory can be used for that buffer. The whole buffer is allocated
in one kind of memory in the following priority order XMS, EMS,
conventional memory.

If you have no particular need you should not call this procedure.
If not called PRINTBGI will behave as you call it with both parameters
zeroed thus enabling allocation of the buffer of the best size.

If you let PRINTBGI to use EMS memory then keep in mind that DrawFunc
(set as parameter to PRT_PrintBGI) or any procedure called by it may not use
EMS memory.
Note also that PRINTBGI does not save and restore EMS mapping at
any time. So if you want you can save EMS mapping before call of any
function that uses it and restore it afterwards. Following functions
may change EMS mapping: PRT_PrintBuffer, PRT_PrintBGI, PRT_BuildBitMap,
PRT_getpixel as well as any graphic routines using BitImage BGI driver.

If used, must be called before initializing BITIMAGE BGI driver.

Try to use PRT_Buffer, PRT_EMSBuffer or PRT_XMSBuffer instead.


PRT_SetCloseFunc
=====================

#if C_only
typedef int ( FAR_PROC * PRT_CloseFuncP)( int* handle );
PRT_CloseFuncP PRT_SetCloseFunc ( int far f(int* handle) );
#endif C_only
#if Pascal_only
Type CloseFuncType = Function(var handle:file): integer;
Function PRT_SetCloseFunc ( f: CloseFuncType ): CloseFuncType;
#endif Pascal_only

Defines function (passed as an argument f) which will be called to close
file handle used to print out the picture. The f function takes an integer*
argument which is supposed to contain an opened file handle. Exactly this is
the case if you do not specified your own open function. if you specified
your own open function the argument passed to close f function
contains a number returned from your open function (see PRT_SetOpenFunc).
This f function should return zero on success and suitable nonzero code
otherwise.
If NULL is passed as an argument f then the old close function used so far
will not be changed.
PRT_SetCloseFunc returns pointer to previously used close function.

See also PRT_SetOpenFunc, PRT_SetCloseFunc, PRT_SetErrorFunc.


PRT_SetUserPrintFunc
====================

#if C_only
typedef int PRT_UserPrintFuncT( void far* UserPtr,
PRT__handleT *handlePPtr,
const char far* BGIpath);
PRT_UserPrintFuncT far *
PRT_SetUserPrintFunc(PRT_UserPrintFuncT far* func);
#endif
#if Pascal_only
Type
PRT_UserPrintFuncT = function ( UserPtr:pointer;
var handlePPtr: filePtr;
BGIpath:PathStr ): integer;
PRT_UserPrintFuncP = ^PRT_UserPrintFuncT;
Function PRT_SetUserPrintFunc (func:PRT_UserPrintFuncT): PRT_UserPrintFuncP;
#endif

Ordinary after creating buffer with binary image of the picture
the PRT_PrintBuffer function is called. But to give you greater control
over what's doing I decided to let you define function which may be
called alternatively instead of PRT_PrintBuffer. And this is what
PRT_SetUserPrintFunc does. It enables you to define your own printing
function. In fact, to use some features, like screen preview (sorry,
this is not WYSIWYG) or printing in PCX format you must use
PRT_SetUserPrintFunc.
Since writing your own printing function may not be very easy for
everyone I included examples of such functions in this package
(see UserPRTf.C, TVprtF.cpp or UserUnit.PAS).


PRT_SetDriver
==============

#if C_only
int PRT_SetDriver ( unsigned drv, unsigned mode,
unsigned width, unsigned height, unsigned options );
#endif C_only
#if Pascal_only
Function PRT_SetDriver ( drv,mode : word; width,height : word;
options: word ) : integer;
#endif Pascal_only


Parameters
drv : defines driver (and thus printer) number which will be
used. Allowed values (See PRINTBGI.H or PRINTBGI.INT) are:
IBM9, EPSON9, PANASONIC9, EPSON24, IBM24, HPLJII, HPPaintJet,
LaserJet, PaintJet, IBM9c, EPSON9c, EPSON24c, IBM24c.
mode : defines driver (printer) mode number which will be
used. Allowed values are defined in PRINTBGI.H
(or PRINTBGI.INT for pascal version).
width,height : defines width and height of the next printing
picture in 1/1000 inch values. That is 4000
means 4 inches.
options : can be defined as zero or it may have set one of the
following bits
PRT_ROTATE : if not set picture will be printed horizontally
if set picture will be printed vertically.
PRT_INVERSE : if not set pixel of value 0 will be printed
as black and pixel of value 1 will be printed white.
1 means otherwise.
For color printers 1 will force bit negation
of pixel value before printing.
Returns
0 on success, nonzero on failure.
Default values.
Must be called. No default values assumed.

Values defined by PRT_SetDriver stay in effect until next call of
that procedure changing them explicitly.
Must be called before initializing BITIMAGE BGI driver. You must earlier
call PRT_LinkDrivers or PRT_ReadDrivers function.
No checking is (or will be) made if specified values are correct for your
hardware. It is responsibility of the caller to detect hardware (or rather
ask user to define it) and specify picture size acceptable by it.
See also PRT_SetPrinterDrv, PRT_SetPictureInch, PRT_SetPicturePix.

PRT_SetErrorFunc
=====================

#if C_only
typedef int ( FAR_PROC * PRT_ErrorFuncP) ( int* handle );
PRT_ErrorFuncP PRT_SetErrorFunc ( int WrErrFunc(int* handle) );
#endif C_only
#if Pascal_only
Type ErrFuncType = Function ( var handle: file ): integer;
Function PRT_SetErrorFunc ( ErrFunc: ErrFuncType ): ErrFuncType;
#endif Pascal_only

Defines function (passed as an argument ErrFunc) which will be
called whenever I/O error occur during printing. ErrFunc must
return zero to retry printing or nonzero error code to abort
printing. In the second case the function in which an error occurred
returns immediately to the caller with the same return code as received
from ErrorFunc.
If ErrFunc argument passed is NULL no ErrFunc will be called
whenever I/O error occurs.
PRT_SetErrorFunc returns pointer to currently used ErrFunc.


PRT_SetHaltVariable
===================

#if C_only
void PRT_SetHaltVariable(const byte far *haltVariable);
#endif C_only
#if Pascal_only
Procedure PRT_SetHaltVariable(var haltVariable);
#endif Pascal_only

Defines so called halt variable. This variable must be set to zero
before starting printing. Setting haltVariable to any non zero during
printing process value will stop it.


PRT_SetMargins
===============

#if C_only
int PRT_SetMargins ( int left, int top );
#endif C_only
#if Pascal_only
Function PRT_SetMargins ( left,top : integer ) : integer;
#endif Pascal_only

Specifies (in 1/1000 inch) the left and top margins that should be
left free during printing. Note that in most cases real margins left will
be only some approximation of the specified values and may considerably
differ from them.
Returns 0 on success, nonzero on failure.


PRT_SetOpenFunc
=====================

#if C_only
typedef int* ( FAR_PROC * PRT_OpenFuncP)( const char far*fname, int omode );
PRT_OpenFuncP PRT_SetOpenFunc ( int* far f(void) );
#endif C_only
#if Pascal_only
Type PRT__FilePtr = ^file;
Type OpenFuncType = Function PRT__FilePtr(var fname:PathStr;int omode): PRT__FilePtr;
Function PRT_SetOpenFunc ( f: OpenFuncType ): OpenFuncType;
#endif Pascal_only

Defines function (passed as an argument f) which will be called to open
file handle for printing out the picture. This f function takes two arguments:
file name and open mode. Open mode is defined as in C standard open function.
For pascal the only meaningfull bit is O_APPEND. If this bit is on file should
be opened in "append" mode, otherwise it should be opened in "truncated"
mode. Defined open function is used by PRT_WritePCX (in "truncated" mode)
and PRT_PrintBuffer (in "appended" mode). The new defined f function should
return as a result pointer to a opened file handle (or to a file in TP).
In case on failure it should return a pointer to a negative error code.
Using PRT_SetOpenFunc you may define your own function used to open
file for output.
If NULL is passed as an argument f then the old open function used so far
will not be changed.
PRT_SetOpenFunc returns pointer to previously used open function.

See also PRT_SetCloseFunc, PRT_SetWriteFunc, PRT_SetErrorFunc.


PRT_SetOutName
==================

#if C_only
int PRT_SetOutName ( const char FAR * DeviceName );
#endif C_only
#if Pascal_only
Function PRT_SetOutName ( DeviceName : string );
#endif Pascal_only

Specifies where the graphic output should be sent. DeviceName
can be any valid DOS device name (such as PRN,LPT1,LPT2,COM1, etc.)
or file name (with or without the path). It is used in pascal assign
procedure or C open function. Note that string pointed to by DeviceName
is not copied but only reference is remembered. So DeviceName should
not point to local dynamic area but to STATIC one rather.
Returns 0 on success, nonzero on failure.


PRT_SetPictureInch
==============

#if C_only
int PRT_SetPictureInch ( unsigned width, unsigned height,
unsigned options );
#endif C_only
#if Pascal_only
int PRT_SetPictureInch ( unsigned width, unsigned height,
unsigned options );
#endif Pascal_only


Parameters
width,height : defines width and height of the next printing
picture in 1/1000 inch values. That is 4000
means 4 inches.
options : see PRT_SetPictureInch for description of this
parameter.

Returns
0 on success, nonzero on failure.

Must be called before initializing BITIMAGE BGI driver. You must earlier
call PRT_LinkDrivers or PRT_ReadDrivers function and PRT_SetPrinterDrv.
No checking is (or will be) made if specified values are correct for your
hardware. It is responsibility of the caller to detect hardware (or rather
ask user to define it) and specify picture size acceptable by it.
See also PRT_SetPrinterDrv, PRT_SetPictureInch.


PRT_SetPicturePix
==============

#if C_only
int PRT_SetPictureInch ( unsigned width, unsigned height,
unsigned options );
#endif C_only
#if Pascal_only
int PRT_SetPictureInch ( unsigned width, unsigned height,
unsigned options );
#endif Pascal_only


Parameters
width,height : defines width and height of the next printing
picture in pixels values.
options : can be defined as zero or it may have set any of the
following bits
PRT_ROTATE : if not set picture will be printed horizontally
if set picture will be printed vertically.
PRT_INVERSE : if not set pixel of value 0 will be printed
as black and pixel of value 1 will be printed white.
1 means otherwise.
For color printers 1 will force bit negation
of pixel value before printing.
To make picture rotated and inverse specify
PRT_ROTATE | PRT_INVERSE for C
PRT_ROTATE or PRT_INVERSE for Pascal.
Returns
0 on success, nonzero on failure.

Must be called before initializing BITIMAGE BGI driver. You must earlier
call PRT_LinkDrivers or PRT_ReadDrivers function and PRT_SetPrinterDrv.
No checking is (or will be) made if specified values are correct for your
hardware. It is responsibility of the caller to detect hardware (or rather
ask user to define it) and specify picture size acceptable by it.
See also PRT_SetPrinterDrv, PRT_SetPicturePix.


PRT_SetPrinterDrv
==============

#if C_only
int PRT_SetPrinterDriver ( unsigned drv, unsigned mode);
#endif C_only
#if Pascal_only
Function PRT_SetPrinterDriver ( drv,mode : word ) : integer;
#endif Pascal_only


Parameters
drv : defines driver (and thus printer) number which will be
used. Allowed values (See PRINTBGI.H or PRINTBGI.INT) are:
IBM9, EPSON9, PANASONIC9, EPSON24, IBM24, HPLJII, HPPaintJet,
LaserJet, PaintJet, IBM9c, EPSON9c, EPSON24c, IBM24c.
Printer drivers are numbered starting from 1. Please do not
use driver number 0. It is intended for future use. Use of it
in current version will give you unpredictable results.
mode : defines driver (printer) mode number which will be
used. Allowed values are defined in PRINTBGI.H
(or PRINTBGI.INT for pascal version).
Returns
0 on success, nonzero on failure.

Values defined by PRT_SetPrinterDrv stay in effect until next call of
that procedure changing them explicitly.
Must be called before initializing BITIMAGE BGI driver. You must earlier
call PRT_LinkDrivers or PRT_ReadDrivers function. You must call
PRT_SetPictureInch or PRT_SetPicturePix to specify picture size.
No checking is (or will be) made if specified values are correct for your
hardware. It is responsibility of the caller to detect hardware (or rather
ask user to define it) and specify picture size acceptable by it.
See also PRT_SetDriver, PRT_SetPictureInch, PRT_SetPicturePix.


PRT_SetViewSize
===============

#if C_only
int PRT_SetViewSize( int x1, int y1, int x2, int y2 );
#endif
#if Pascal_only
Function PRT_SetViewSize( x1,y1, x2,y2: integer ): integer;
#endif

Parameters
x1,y1,x2,y2 - specifies rectangular piece of picture which will be
built by the BitImage BGI driver.
See also PRT_initgraph.


PRT_SetWriteFunc
=====================

#if C_only
typedef int ( FAR_PROC * PRT_WriteFuncP)
( int* handle, const void FAR_PTR * b, unsigned len );
PRT_WriteFuncP PRT_SetWriteFunc
( int far f(int* handle,void FAR_PTR* buf,
unsigned len) );
#endif C_only
#if Pascal_only
Type WriteFuncType = Function(var handle:file; var b; len: word ): integer;
Function PRT_SetWriteFunc ( f: WriteFuncType ): WriteFuncType;
#endif Pascal_only

Defines function (passed as an argument f) which will be called to print
out len bytes pointed to by buf pointer.
Parameters of f function
handle : an integer number returned by an open function set by
PRT_SetOpenFunc. My default open function simply returns
file handle.
buf : Pointer to data bytes which must be printed out.
len : Number of bytes to print.
If function f returns nonzero value it will be treated as an I/O error.
If NULL is passed as an argument f then the old write function used so far
will be not changed.
PRT_SetWriteFunc returns pointer to previously used write function.

See also PRT_SetOpenFunc, PRT_SetCloseFunc, PRT_SetErrorFunc.



PRT_Unregisterfarbgidriver
========================

#if C_only
int PRT_Unregisterfarbgidriver ( void far pascal
(*driver)(void) );
#endif
#if Pascal_only
Type DriverProc = procedure;
PRT_Unregisterfarbgidriver ( driver: DriverProc ): integer;
#endif

Used to unregister driver installed with PRT_registerfarbgidriver function.
You MUST use it before erasing registered BitImage driver from memory.


PRT_Version
===========

#if C_only
int PRT_Version(void);
#endif
#if Pascal_only
Function PRT_Version integer;
#endif

Returns toolkit major version on high byte and minor version number
on lower byte.

PRT_XMSBuffer
=============

#if C_only
int PRT_XMSBuffer ( int handle, long size, int usable )
#endif
#if Pascal_only
Function PRT_XMSBuffer ( handle: integer; size: longint; usable: integer ):
integer;
#endif
Defines XMS buffer for use by the PrintBGI package.
Parameters:
usable : 0 (zero) means not to use XMS memory. Other arguments are
in that case ignored (but preferably should also be zero).
handle : Number of XMM handle to use for the buffer or zero (buffer
will be allocated by the package)
size : If handle is nonzero defines amount of memory (in bytes)
allocated to that handle by the caller.
If handle is zero then
- positive value defines maximum number of memory (which
will be rounded down to 16 KB boundary) that can be
used for the buffer by PrintBGI package.
- negative value defines minimum number of memory left
free after buffer allocation.
- zero allows to allocate as much memory as needed for
the buffer leaving only absolutely minimum free.

Note that XMS buffer requires also some conventional memory buffer to
be allocated.
See also PRT_Buffer,PRT_EMSBuffer.


PRT_WritePCX
============
#if C_only

typedef int* PRT__handleT;
int PRT_WritePCX ( PRT__handleT *handlePtr )
#endif
#if Pascal_only
type filePtr = ^file;
Function PRT_PrintBuffer(var handle: filePtr): integer;
#endif

Prints entire "screen" buffer to the specified handle
in a PCX format. So the output should be directed rather to a file
than a real printer. You may later use a graphic program
to work with your picture. Note, I'm not sure all programs
will accept created PCX file, even if they are specified to do it.
You cannot use it to create rotated pictures. Also if you specify
that you want inverse picture colors will be reversed.
To print out the buffer it uses PRT_Write function set by
PRT_SetWriteFunc routine.
Note also that my standard PRT_Write function will call PRT_WriteError
function (set by PRT_SetErrorFunc) whenever output error occurs.
This function is never called by my code. To create PCX file you
must

Returns 0 on success, nonzero on failure.

See also PRT_SetOpenFunc, PRT_SetCloseFunc, PRT_SetWriteFunc,
PRT_SetErrorFunc.


PRT_XMSBufferNeeded
=================

#if C_only
long PRT_XMSBufferNeeded ( int x1, int y1, int x2, int y2 );
#endif C_only
#if Pascal_only
Function PRT_XMSBufferNeeded ( x1,y1,x2,y2: integer ): longint;
#endif Pascal_only

Returns size of buffer needed to draw picture in XMS memory of specified
size and on printer set by PRT_SetDriver. The returned value will be somewhat
larger than that from PRT_BufferNeeded. If there exist less free memory than
needed then picture would be drawn in pieces. In that case results of all
procedures reading pixel values may be inaccurate.
May be called only after PRT_SetDriver.
See also PRT_EMSBufferNeeded, PRT_BufferNeeded.


setcharsize_Pix
===============

#if C_only
void setcharsize_Pix (int width, int height);
#endif
#if Pascal_only
Procedure setcharsize_Pix ( width,height: integer );
#endif

Sets char size width and height. The parameters should be given
in pixels. You may use it to obtain text proportional to the picture
sizes. For example if you want text height to be 1/60 of the whole
picture height and width 1/80 of the whole picture width you may use
following statement (in C language)
setcharsize_Pix ( getmaxx()/80, getmaxy()/60 );


setfillpattern16
=================

#if C_only
void setfillpattern16 ( char FAR * upattern, int color );
#endif C_only
#if Pascal_only
Procedure SetFillPattern16 ( upattern: FillPatternType; color: word );
#endif Pascal_only

If standard 8x8 fill patterns are not satisfied for you use this
function to define 16x16 patterns. Note that calling this function take
effect only when BITIMAGE BGI driver is active, for all other BGI drivers it
will be ignored. So the best approach is probably calling standard
setfillpattern function and then setfillpattern16. In that case ignoring
setfillpattern16 will cause that the pattern set by standard setfillpattern
function will be still in effect.



PRT_HaltPrinting
================

Global variable. It is set to zero when PRT_PrintBGI starts. You may set it
to nonzero value to force almost immediate return from PRT_PrintBGI function
(without ending printing). This variable is tested after each line printed.
Note however that if PRT_PrintBGI called your Draw function then it will wait
for the Draw function to end before testing PRT_HaltPrinting.
You may use PRT_SetHaltVariable function to specify different stop
variable.



========================================================================
GRAPHIC FUNCTIONS
========================================================================

This section will describe all graphics functions that can be found
in Borland Graph.TPU unit for TP or GRAPHICS.LIB for B/TC(++). Note
that detailed description of each function can be found in appropriate
Borland documentation. Here are only given some differences from their
use in PRINTBGI package and standard Borland BGI drivers.

Following functions can be used with my BitImage BGI driver in the
same way as with standard Borland BGI drivers.


void far arc(int x, int y, int stangle, int endangle, int radius);
void far bar(int left, int top, int right, int bottom);
void far bar3d(int left, int top, int right, int bottom,
int depth, int topflag);
void far circle(int x, int y, int radius);
void far clearviewport(void);
void far drawpoly(int numpoints, int far *polypoints);
void far ellipse(int x, int y, int stangle, int endangle,
int xradius, int yradius);
void far fillellipse( int x, int y, int xradius, int yradius );
void far fillpoly(int numpoints, int far *polypoints);
void far getarccoords(struct arccoordstype far *arccoords);
void far getaspectratio(int far *xasp, int far *yasp);
int far getbkcolor(void);
int far getcolor(void);
void far getfillpattern(char far *pattern);
void far getfillsettings(struct fillsettingstype far *fillinfo);
int far getgraphmode(void);
void far getlinesettings(struct linesettingstype far *lineinfo);
int far getmaxcolor(void);
int far getmaxx(void);
int far getmaxy(void);
char * far getmodename( int mode_number );
void far getpalette(struct palettetype far *palette);
int far getpalettesize( void );
void far gettextsettings(struct textsettingstype far *texttypeinfo);
void far getviewsettings(struct viewporttype far *viewport);
int far getx(void);
int far gety(void);
void far graphdefaults(void);
char * far grapherrormsg(int errorcode);
void far _graphfreemem(void far *ptr, unsigned size);
void far * far _graphgetmem(unsigned size);
int far graphresult(void);
unsigned far imagesize(int left, int top, int right, int bottom);
int far installuserfont( char far *name );
void far line(int x1, int y1, int x2, int y2);
void far linerel(int dx, int dy);
void far lineto(int x, int y);
void far moverel(int dx, int dy);
void far moveto(int x, int y);
void far pieslice(int x, int y, int stangle, int endangle,
int radius);
void far putimage(int left, int top, void far *bitmap, int op);
void far putpixel(int x, int y, int color);
void far rectangle(int left, int top, int right, int bottom);
int registerbgifont (void (*font)(void));
int far registerfarbgifont (void far *font);
void far sector( int X, int Y, int StAngle, int EndAngle,
int XRadius, int YRadius );
void far setaspectratio( int xasp, int yasp );
void far setcolor(int color);
void far setfillpattern(char far *upattern, int color);
void far setfillstyle(int pattern, int color);
unsigned far setgraphbufsize(unsigned bufsize);
void far setlinestyle(int linestyle, unsigned upattern,
int thickness);
void far settextjustify(int horiz, int vert);
void far setusercharsize(int multx, int divx,
int multy, int divy);
void far setviewport(int left, int top, int right, int bottom,
int clip);
int far textheight(char far *textstring);
int far textwidth(char far *textstring);


Following functions may differ somewhat when used with printer
devices. See short descritption after function declaration.


void far cleardevice(void);
Does not enforce printing. Buffer is cleared and if mot printed
earlier its content is lost forever.

void far closegraph(void);
You rather shouldn't use it with BitImage BGI driver. Use PRT_closegraph
instead.

void far detectgraph(int far *graphdriver,int far *graphmode);
It will return detect values for screen not for external devices.


void far floodfill(int x, int y, int border);
Not implemented in current release. It'll be implemented in future
releases but remember that may produce some inaccurate results if
there is less memory than needed to build whole bit map for the
picture. Compare with PRT_PrintBGI description. Note also that it
cannot be implemented for some kind of output devices.


struct palettetype far * far getdefaultpalette( void );
Not implemented.

char * far getdrivername( void );
Returns BGI driver name. Since the package uses always the
same BGI driver (called BITIMAGE BGI driver) it will always return
the word BITIMAGE. To obtain names of printer drivers supported call
PRT_DriverName function described in earlier section.

void far getfillpattern(char far *pattern);
See also getfillpattern16 and PRT_RescaleFillPattern.


void far getimage( int left, int top, int right, int bottom,
void far *bitmap);
May not work if there is not enough memory for the entire picture.
Otherwise is fully supported.

int far getmaxmode(void);
You should use rather PRT_MaxMode instead. Currently it always
returns zero since BitImage BGI driver being used supports one mode
only. Parameters which configure the driver for your needs can be set
using PRT_SetDriver function.


int far getmaxx(void);
You should use it to rescale output according to screen sizes.

int far getmaxy(void);
You should use it to rescale output according to screen sizes.

void far getmoderange(int graphdriver, int far *lomode,
int far *himode);
Shouldn't be used.

unsigned far getpixel(int x, int y);
May not work if there is not enough memory for the entire picture.
Otherwise is fully supported.

char * far grapherrormsg(int errorcode);
You may use PRT_grapherrormsg instead.

void far initgraph(int far *graphdriver,
int far *graphmode,
char far *pathtodriver);
To initialize BitImage BGI driver you must use PRT_initgraph instead.

int far installuserdriver( char far *name, int huge (*detect)(void) );
You must use PRT_installuserdriver to install PRINTBGI drivers.

void far outtext(char far *textstring);
To print standard fonts of code 128 or higher you should use DOS
GrafTabl command before, otherwise printing is garbage. Note also
that fonts table for characters 127 or lower is taken from ROM BIOS.
If you have no such a table in standard place some problems may also
occur.
See also settextstyle comments.

void far outtextxy(int x, int y, char far *textstring);
See outtext and settextstyle comments.


int registerbgidriver (void (*driver)(void));
To register BitImage driver you should use PRT_registerfarbgidriver
instead.

int far registerfarbgidriver (void far *driver);
To register BitImage driver you should use PRT_registerfarbgidriver
instead.

void far restorecrtmode(void);
Shouldn't be used. Before using PrintBGI toolkit functions you must
close down any active video BGI driver. To do this use closegraph not
restorecrtmode function. On the other hand using restorecrtmode with
BitImage BGI driver has little sense.

void far setactivepage(int page);
Not implemented.

void far setallpalette(struct palettetype far *palette);
Not implemented.

void far setaspectratio( int xasp, int yasp );
You may use it to change current aspect ratio but remember that
default values are correct.

void far setbkcolor(int color);
Not implemented in current release.

void far setfillpattern(char far *upattern, int color);
See setfillpattern16 and PRT_RescaleFillPattern in previous section.

void far setfillstyle(int pattern, int color);
See PRT_RescaleFillPattern in previous section.

void far setgraphmode(int mode);
Shouldn't be used.

void far setpalette(int colornum, int color);
Not implemented.

void far setrgbpalette(int colornum,
int red, int green, int blue);
Not implemented.

void far settextstyle(int font, int direction, int charsize);
May produce different results for standard fonts (DEFAULT_FONT)
and direction other than HORIZ_DIR or VERT_DIR. May also behave
slightly different when text expands beyond clip region. You may use
setcharsize_Pix function to set font size in pixels.

void far setvisualpage(int page);
Not implemented.

void far setwritemode( int mode );
In difference with Borland's BGI drivers write mode defined by
that procedure is valid for all subsequent write operations. Mode
argument may be one of the following: COPYPUT, XORPUR, ORPUT,
AND_PUT, NOT_PUT not just limited to fist two constants only (as is
in Borland's library).



DEFINING YOUR OWN PRINTERS
==========================

Printers descriptions used by the package are contained in Drivers
module. I included in this package all files necessary to compile
Drivers.ASM. So you may modify this file and compile it creating OBJ file
which in turn you should added to PRTGRAPH.LIB replacing old OBJect member
of the same name. Turbo Pascal users should compile Drivers.Pas file
instead of modifying PRTGRAPH.LIB.
I must tell you that defining your own printer is not easy. You probably
will have a lot of troubles with it unless you are an expert in using
printers in graphic mode. In that case you should not have troubles. Read
Drivers.INC and then copy one of the closest printer already defined in
Drivers.ASM and modify parameters you need.
I suppose there are some printers which cannot be added this way. If you
have such a one it means that it requires the modification of printers
definitions structure as well as some other source code modifications.
Please contact the author in that case.


THE FUTURE
==========

If there is some interest in this package I will write 1.0 version
which will
- support all dot matrix printers, postscript printers and some
others as well as some plotters,
- contain table (and function to use it) with names of all available
printers and appropriate driver number used by the package (if users
support me in doing it) ,
- let you keep printers definitions in separate file or linked it with
the main module,
- work in all memory models (except tiny of course),
- be tested on more printers,
- contain some more improvements, I hope.
All registered users will obtain this 1.0 version completely free.


To contact the author write to

Andrzej Resztak
ul. K. Wallenroda 2c/18
20-607 Lublin
POLAND

or (preferably) to e-mail address:
[email protected]


/* end of FUNCTION.DOC */