home *** CD-ROM | disk | FTP | other *** search
/ Liren Large Software Subsidy 9 / 09.iso / l / l002 / 1.ddi / PRINTBGI.DOC < prev    next >
Encoding:
Text File  |  1992-05-19  |  57.2 KB  |  1,388 lines
  1.  
  2. Documentation of PRINTBGI package copyright (C) Andrzej Resztak 1991,1992,
  3. all rights reserved.
  4.  
  5.  
  6. Introduction
  7.  
  8.    This is a version 0.94 of my PrintBGI toolkit. It was developed to 
  9. help programmers using Borland languages (Borland/Turbo C(++)
  10. or Turbo Pascal) and BGI drivers to print graphics on the printer
  11. (and in the future on the other devices) as easy as you can draw it
  12. on the screen. In fact even more, the same function can produce
  13. it's output on a screen or on a printer according to conditions
  14. at which it was called.
  15.    It's really easy to learn. Developing your own applications does
  16. not require writing two similar procedures (one for screen drawing
  17. and the other for printer or plotter).
  18. Maintenance of the code is simple, since all extensions or bug fixes
  19. must be made in one place only. I hope you will enjoy this package.
  20.  
  21.    For registration, license and payment see REGISTER.DOC.
  22.  
  23. This file contains all technical news you must understand to use
  24. this package easy and effectively.
  25.  
  26.  
  27.             SOME OVERVIEW
  28.             ==============
  29.  
  30.    This package can be divided into two independent parts. First is
  31. BGI driver called by me BItImage BGI driver. This driver can be used
  32. to create bit maps of any size of any picture. (By bit map I mean
  33. two dimensional array of 1,2,4 or 8 bits elements). Note however that
  34. the BGI driver does only some low level work (hardware specific) and
  35. in most cases it depends on high level routines contained in Borland
  36. graphics library kernel. Since there are some differences between printer
  37. and screen oriented devices the initialization of my BitImage BGI
  38. driver is somewhat different of initialization of standard Borland
  39. video BGI drivers. For example it cannot perform any auto detection,
  40. specifying printer being used does not determine the size of the graphic
  41. output and there is some more minor differences. Because of these
  42. differences you must call some PRT_Setxxxxxxx functions of the package to
  43. specify parameters at which you want the BitImage driver to work. And
  44. initialization of the driver should be done using PRT_initgraph function
  45. not standard initgraph routine.
  46.    The second part of the package make routines contained in PRTGRAPH library
  47. which hide some of the differences between my BitImage driver and
  48. standard Borland video drivers. They also will make it very easy to print
  49. something on your output device (currently only the dot matrix printers).
  50.  
  51.  
  52.    Now I describe you the easiest way you can add graphic output
  53. to your programs using this PRINTBGI toolkit. Other sections
  54. will let you know some more features, but this section is very good
  55. for beginning, I hope.
  56.  
  57.    For C users.
  58.  
  59.    First, I highly recommend you to include prototypes of all functions
  60. defined in PRINTBGI package by just inserting
  61. #include <PRTGRAPH.H>
  62. statement at  the  beginning  of  your  module.  Although  it  is  not
  63. necessary I also recommend you to place PRTGRAPH module after any standard
  64. modules you use. It'll enable me some tricky modifications in the future
  65. versions of this package.
  66.    You must also remember about linking in PRTGRAPH.LIB either
  67. listing it in PRJ file in integrated environment or adding at the
  68. command line invoking stand alone version of the compiler (or linker).
  69.  
  70.    For Pascal users.
  71.  
  72.    You must list PRTGRAPH unit (among other units you are using) in the
  73. uses clause. You may also list PDrivers unit if you want to use symbolic
  74. constants defined in it.
  75.    Although it is not necessary I recommend you to place PRTGRAPH
  76. module after any standard modules you use. It'll enable me some tricky
  77. modifications in the future versions of this package.
  78.  
  79.  
  80.    Next I assume that you like modular structure programming and have
  81.    routine called (say) DrawFunc which meets following conditions.
  82.       - It draws on the screen picture you want to print it out.
  83.       - It does not use any nonstandard procedures (that is not
  84.         defined in GRAPH.TPU or GRAPHICS.LIB) to manipulate screen
  85.         output.
  86.       - It does not use initgraph,restorecrtmode,closegraph or setgraphmode
  87.         function. It simply assumes that appropriate graphic mode was
  88.         established before calling it and will be close down after
  89.         it finishes.
  90.       - It is written in BGI independent way. That is it uses getmaxx,
  91.         getmaxy, getmaxcolor, getaspectratio to get device dependent
  92.         characteristic and scales all output according to it.
  93.       - If you are using my recommended way to print your picture out, that
  94.         is you are using PRT_PrintBGI function then it may happen that this
  95.         function will call your drawing routine few or several times to print
  96.         out the whole picture. This may happen when there is not enough free
  97.         memory to build the whole bit image map of the picture at once. In
  98.         that case the bit map will be created piece by piece (each time
  99.         calling your drawing routine).
  100.         So, although it is not necessary it is recommended that your routine
  101.         will draw the same picture (pixel in pixel) each time it will be
  102.         called by PRT_PrintBGI function. Of course in the next invoke
  103.         of the PRT_PrintBGI routine your DrawFunc may draw something
  104.         completely different.
  105.  
  106.       ( If it is not your case (you don't have such a function)  you may
  107.         either rewrite your code to have such a function or use some lower
  108.         level functions included in this package. I once again highly
  109.         recommend you to choose the first method. )
  110.  
  111.       If you have such a function you must inform the package what kind
  112.    of printer you have and at what resolution you want it to operate.
  113.    To do that just call PRT_SetDriver function with appropriate parameters
  114.    PrinterNo and ModeNo (use constants defined in PRTGRAPH.H or in 
  115.    PRTGRAPH.PAS) as well as picture size and options.
  116.    For example the following statements may print out picture drawn by
  117.    DrawFunc on the IBM ProPrinter.
  118.  
  119.    {  /* C version */
  120.       int   PRTdrv,PRTmode,ReturnCode;
  121.       PRT_SetDriver ( IBM9, IBM9_120x72, 4000,3000, PRT_INVERSE );
  122.       PRTdrv = DETECT;
  123.       PRTmode=0;
  124.       /* If you want you may linked in the BitImage BGI driver into the */
  125.       /* EXE file. To do so uncomment  following two lines. */
  126.       /* PRTdrv = PRT_installuserdriver ( "BitImage", NULL );  */
  127.       /* PRT_registerfarbgidriver ( &BitImage );               */
  128.       ReturnCode = PRT_PrintBGI ( &PRTdrv,&PRTmode,"d:\\bc\\bgi",
  129.                                   DrawFunc, NULL );
  130.    }
  131.  
  132.    (* Pascal version *)
  133.    var PRTdrv,PRTmode,ReturnCode : integer;
  134.    Begin
  135.       rc := PRT_SetDriver ( IBM9, IBM9_120x72, 4000,300, 0 or PRT_INVERSE );
  136.       { rc := PRT_SetOutName('file.tst'); }
  137.       PRTdrv := DETECT;
  138.       PRTmode := 0;
  139.       (* If you want you may linked in the BitImage BGI driver into the *)
  140.       (* EXE file. To do so uncomment  following two lines. *)
  141.       { PRTdrv := PRT_installuserdriver ( 'BitImage', NIL ); }
  142.       { rc := PRT_registerbgidriver ( @BitImage ); }
  143.       rc := PRT_PrintBGI ( PRTdrv,PRTmode,'d:\tp\bgi', Draw, nil );
  144.    End;
  145.  
  146.    In the best case it's all you have to do. Isn't it easy? I'm sure you
  147. must admit it is.
  148.  
  149.    Of course in most situations it is not enough. Above statements
  150. will cause all output to be sent to the standard PRN device.
  151. If you would like (or have to cause you don't have the printer at
  152. LPT1 for example) to change these parameters you
  153. should call some more functions of the PRINTBGI package as well
  154. as you should code some lines to let user of your program specify
  155. his own requirements. But all of this can be done!
  156.    You may also wish to print in inverse, reverse, with any density
  157. at any size. The only disadvantage of using this package is that it
  158. is perceptible slower than usual Print Screen procedures.
  159.  
  160.  
  161.  
  162. ========================================================================
  163.          FUNCTIONS DETAILS
  164. ========================================================================
  165.  
  166.    Following section will describe in details all functions which
  167. can be found in PRINTBGI package. This package as distributed in
  168. shareware version was developed and tested in LARGE and HUGE memory
  169. models (I suppose they are the modes most graphic programs use)
  170. using BC++ v2.0. To use it in other memory model you may need
  171. full sources of it (available from the author - see REGISTER.DOC).
  172.  
  173.    When it is mentioned that the function returns zero on success and
  174. nonzero on failure it means that one of the following codes may be
  175. returned
  176.    0                       -  success.
  177.    PRT_NO_MEMORY           1
  178.    PRT_WRONG_PARAMETERS    2
  179.    PRT_NOT_INITIALIZED     3
  180.    PRT_IO_ERROR            4
  181.    PRT_ERROR               5
  182.  Occasionally you can get other code returned from standard Borland graphic
  183. functions or write procedure. You may also get returned code from your own
  184. DrawFunc routine if it returns nonzero code.
  185.  
  186.  
  187. All functions can be divided into following categories.
  188.    - Functions used to set various work parameters.
  189.       PRT_Buffer
  190.       PRT_RescaleFillPattern
  191.       PRT_Send
  192.       PRT_SetBuffer
  193.       PRT_SetOutName
  194.       PRT_SetMargins
  195.       PRT_SetDriver
  196.       PRT_SetViewSize
  197.       PRT_SetErrorFunc
  198.       PRT_SetOpenFunc
  199.       PRT_SetCloseFunc
  200.       PRT_SetWriteFunc
  201.       PRT_EMSBuffer
  202.       PRT_XMSBuffer
  203.       getfillpattern16
  204.       setcharsize_Pix
  205.       setfillpattern16
  206.    - Functions used to print out the picture
  207.       PRT_PrintBGI
  208.       and some functions used internally by PRT_PrintBGI
  209.       (use them only if necessary, the preferable method is using
  210.       PRT_PrintBGI which will virtually do all necessary work for you).
  211.          PRT_AllocateBuffer
  212.          PRT_BuildBitMap
  213.          PRT_BufferNeeded
  214.          PRT_closegraph
  215.          PRT_EndPrt
  216.          PRT_FreeBuffer
  217.          PRT_getpixel
  218.          PRT_initgraph
  219.          PRT_InitPrt
  220.          PRT_installuserdriver
  221.          PRT_PrintBuffer
  222.          PRT_registerfarbgidriver
  223.          PRT_Unregisterfarbgidriver
  224.    - Functions used to get some information about package and current
  225.      settings of miscellaneous parameters.
  226.       PRT_DriverName
  227.       PRT_DriverNo
  228.       PRT_grapherrormsg
  229.       PRT_MaxDriver
  230.       PRT_MaxMode
  231.       PRT_ModeName
  232.       PRT_ModeNo
  233.       PRT_Resolution
  234.  
  235.  
  236. Global export variable
  237.    PRT_HaltPrinting
  238.  
  239.  
  240.    Here are all functions listed alphabetically. Specification will begin
  241. with function declaration followed by exact description of all parameters.
  242.  
  243.  
  244.    getfillpattern16
  245.    =================
  246.  
  247. void getfillpattern16 ( char FAR * upattern );
  248. Procedure GetFillPattern16 ( upattern: FillPatternType );
  249.  
  250.    You may use this function to copy 16x16 bit fill pattern set by
  251. setfillpattern16 function into the 32 (!) byte area pointed to by upattern.
  252. This function may be used only when BITIMAGE BGI driver is active, for all
  253. other BGI drivers it will be ignored.
  254.    See also PRT_RescaleFillPattern.
  255.  
  256.  
  257.  
  258.    PRT_AllocateBuffer
  259.    ===================
  260.  
  261. int PRT_AllocateBuffer ( void );
  262. Function PRT_AllocateBuffer: integer;
  263.  
  264.    This function allocates buffer for picture bit image map. It
  265. allocates as much memory as allowed by PRT_SetBuffer but not more than
  266. needed.
  267.    Note that attempt to allocate buffer is performed in the
  268. following order. First it is tried to allocate XMS buffer next EMS and
  269. at last conventional one. It may result in allocating buffer smaller
  270. than available memory (e.g if there is 200k of free conventional memory
  271. and 32k of free EMS memory then 32k EMS buffer will be allocated).
  272. Note also that buffer always fits in one kind of memory. There is no
  273. possibility to create buffer say 200K large containing of 60K of
  274. conventional memory and rest of EMS or XMS memory.
  275. Used internally by PRT_PrintBGI may also be called by user needing
  276. some nonstandard possibilities.
  277.    Returns 0 on success, nonzero on failure.
  278.  
  279.    see also PRT_SetBuffer, PRT_Buffer, PRT_EMSBuffer, PRT_XMSBuffer,
  280. PRT_BufferNeeded.
  281.  
  282.  
  283.    PRT_Buffer
  284.    =============
  285.  
  286. int FAR_PROC pascal PRT_Buffer ( void far *address, long size, int usable )
  287. Function PRT_Buffer ( address: pointer; size: longint; usable: integer ):
  288.                     integer;
  289.    Defines conventional memory buffer for use by the PrintBGI package.
  290.    Parameters:
  291.       usable   :  0 (zero) means not to use conventional memory. Other
  292.                   arguments are in that case ignored (but preferably should
  293.                   also be zero).
  294.       address  :  Address of conventional memory buffer to use or NULL
  295.                   (buffer will be allocated later by other functions of
  296.                   this package).
  297.       size     :  If address is not NULL defines size (in bytes)
  298.                   of the caller allocated buffer.
  299.                   If address is NULL than
  300.                     -   positive value defines maximum number of memory
  301.                         which can be used for the buffer by PrintBGI package.
  302.                     -   negative value defines minimum number of memory left
  303.                         free after buffer allocation.
  304.                     -   zero allows to allocate as much memory as needed for
  305.                         the buffer leaving only absolutely minimum free.
  306.  
  307.    Note that allocating buffer larger than 64Kb (to be precise 64KB-16 bytes)
  308. is a little tricky in Turbo Pascal. Althoug I done it in documented way
  309. it might not work in future versions of Turbo Pascal ( that is if heap
  310. memory manager will be changed).
  311.    See also PRT_EMSBuffer,PRT_XMSBuffer.
  312.  
  313.    PRT_BufferNeeded
  314.    =================
  315.  
  316. long PRT_BufferNeeded ( int x1, int y1, int x2, int y2 );
  317. Function PRT_BufferNeeded ( x1,y1,x2,y2: integer ): longint;
  318.  
  319.    Returns size of buffer needed to draw picture of specified size on
  320. printer set by PRT_SetDriver. If there exist less free memory than needed
  321. then picture would be drawn in pieces. In that case results of all
  322. functions reading pixel values may be inaccurate.
  323.    XMS buffer requires some more memory to build a picture. Use
  324. PRT_XMSBufferNeeded in that case.
  325.    May be called only after PRT_SetDriver.
  326.    See also PRT_XMSBufferNeeded.
  327.  
  328.  
  329.    PRT_BuildBitMap
  330.    ================
  331.  
  332. int FAR_PROC pascal  PRT_BuildBitMap (
  333.                   int far * graphdriver, int far *graphmode,
  334.                   const char far *pathtodriver,
  335.                   int x1,int y1, int x2,int y2,
  336.                   int ( FAR_PTR * FAR_PROC  Draw)(void far* UserPointer),
  337.                   void far * UserPointer );
  338.    Type DrawType = function DrawFunc(UserPointer:pointer) : integer;
  339. Function PRT_BuildBitMap ( var graphdriver,graphmode: integer;
  340.                         pathtodriver: string;
  341.                         x1,y1,x2,y2: integer;
  342.                         DrawFunc : DrawType,
  343.                         UserPointer: pointer );
  344.  
  345. Parameters
  346.    graphdriver,graphmode,pathtodriver - see PRT_initgraph.
  347.    x1,y1,x2,y2 - coordinates of the rectangular area of the whole
  348.                  picture currently being build by the BitImage BGI driver.
  349.                  All requests to read or write outside the specified region
  350.                  will be ignored. Functions reading pixel value from
  351.                  outside of the specified region will always return zero
  352.                  result (without error set).
  353.    DrawFunc    - see PRT_PrintBGI.
  354.    UserPointer - see PRT_PrintBGI.
  355.  
  356.    Initializes BITIMAGE BGI driver by calling PRT_initgraph. Calls
  357. DrawFunc and DOES NOT close down BITIMAGE BGI driver (and does not free
  358. the buffer with created bit image map). This should result in built
  359. (x1,y1,x2,y2) rectangle of bit image map cut from the entire picture.
  360.  
  361.    This function assumes that PRT buffer large enough to contain
  362. (x1,y1),(x2,y2) rectangle was already allocated using PRT_AllocateBuffer
  363. function.
  364.  
  365.    Returns 0 on success, nonzero on failure.
  366.  
  367.  
  368.    PRT_closegraph
  369.    ===============
  370.  
  371. int PRT_closegraph(void);
  372. Function PRT_closegraph: integer;
  373.  
  374.    Closes down the BGI driver which was being used to print the picture out.
  375. In the case of BitImage BGI driver being used this function DOES NOT free
  376. the buffer with created bit image map of the picture. Just you may close
  377. down the BitImage BGI driver and still have buffer with created bit image
  378. map of the picture. It enables you to activate any other BGI driver and
  379. display created pixel map. But remember to free the buffer calling
  380. PRT_FreeBuffer function.
  381.  
  382.    Returns 0 on success, nonzero on failure.
  383.  
  384.  
  385.    PRT_DriverName
  386.    ===============
  387.  
  388. int PRT_DriverName ( unsigned driverno, char FAR * FAR* name_ptr  );
  389. Function PRT_DriverName ( driverno: word; var name_ptr: StringPtr ): integer;
  390.  
  391.    Assigns to StringPtr pointer pointing to static string containing the name
  392. of driver numbered driverno. The driver name is general name of all printers
  393. supported by the driver or the name of the most common printer from
  394. all supported by it.  It can be used to list user all allowable printers and
  395. let him choose the appropriate one.
  396.    Returns 0 on success, nonzero on failure.
  397.  
  398.  
  399.    PRT_DriverNo
  400.    =============
  401.  
  402. int PRT_DriverNo ( void );
  403. Function PRT_DriverNo: integer;
  404.    Returns current driver number as set by PRT_SetDriver or minus one.
  405.  
  406.  
  407.    PRT_EMSBuffer
  408.    =============
  409.  
  410. int FAR_PROC pascal PRT_EMSBuffer ( int handle, long size, int usable )
  411. Function PRT_EMSBuffer ( handle: integer; size: longint; usable: integer ):
  412.          integer;
  413.    Defines EMS buffer for use by the PrintBGI package.
  414.    Parameters:
  415.       usable   :  0 (zero) means not to use EMS memory. Other arguments are
  416.                   in that case ignored (but preferably should also be zero).
  417.       handle   :  Number of EMM handle to use for the buffer or zero (buffer
  418.                   will be allocated by the package)
  419.       size     :  If handle is nonzero defines amount of memory (in bytes)
  420.                   allocated to that handler by the caller.
  421.                   If handle is zero then
  422.                     -   positive value defines maximum number of memory (which
  423.                         will be rounded down to 16 KB boundary) that can be
  424.                         used for the buffer by PrintBGI package.
  425.                     -   negative value defines minimum number of memory left
  426.                         free after buffer allocation.
  427.                     -   zero allows to allocate as much memory as needed for
  428.                         the buffer leaving only absolutely minimum free.
  429.  
  430.    See also PRT_Buffer,PRT_XMSBuffer.
  431.  
  432.    PRT_EndPrt
  433.    ==========
  434.  
  435. int FAR_PROC _PRT__pascal PRT_EndPrt ( int handle );
  436. Function PRT_EndPrt ( var handle: file ): integer;
  437.  
  438.    Sends printer ending sequence to the specified handle.
  439. To print it out uses PRT_write function set by PRT_SetWriteFunc routine.
  440.    Note also that my standard PRT_Write function will call PRT_WriteError
  441. function (set by PRT_SetErrorFunc) whenever output error occurs.
  442.    Returns 0 on success, nonzero on failure.
  443. See also PRT_SetOpenFunc, PRT_SetCloseFunc, PRT_SetWriteFunc,
  444. PRT_SetErrorFunc.
  445.  
  446.  
  447.    PRT_grapherrormsg
  448.    ============
  449.  
  450. char far * FAR_PROC PRT_grapherrormsg ( int errorcode );
  451. Function PRT_grapherrormsg ( errorcode: integer ): string;
  452.    Returns pointer to error message associated with errorcode.
  453.  
  454.  
  455.    PRT_FreeBuffer
  456.    ==============
  457.  
  458. int PRT_FreeBuffer (void);
  459. Function PRT_FreeBuffer: integer;
  460.  
  461.    Internal procedure freeing the buffer allocated by PRT_AllocateBuffer.
  462. In the case of freeing EMS buffer does not restore EMS mapping to the state
  463. from before PRT_AllocateBuffer.
  464.    Returns 0 on success, nonzero on failure.
  465.  
  466.  
  467.  
  468.    PRT_getpixel
  469.    =============
  470.  
  471. int  PRT_getpixel ( int x, int y );
  472. Function PRT_getpixel ( x,y: integer );
  473.  
  474.    Performs the same function as standard Borland getpixel function but with
  475. two differences.
  476.    Parameters x and y are not whole picture relative
  477. but buffer relative. It makes no difference if there is enough memory
  478. for the whole picture. But if there is not enough free memory 
  479. PRT_getpixel(0,0) will return value of first pixel in the buffer
  480. not the first pixel on the virtual screen. What this pixel is at the whole
  481. picture depends on parameters x1 and y1 passed to PRT_SetViewSize.
  482.    The second difference is that if you load ( or link in) the driver
  483. manually you will be able to call this function after closing BITIMAGE BGI
  484. driver (after PRT_closegraph and maybe also after activating another BGI
  485. driver) but, of course before releasing the screen buffer, and unregistering
  486. the driver (see PRT_Unregisterfarbgidriver). If the driver is loaded
  487. automatically (e.g. by PRT_initgraph) it will be deleted by PRT_closegraph
  488. and you MUST NOT use this function in that case when BGI driver is not
  489. active.
  490.  
  491.  
  492.  
  493.    PRT_initgraph
  494.    ==============
  495.  
  496. int FAR_PROC pascal PRT_initgraph( int far * graphdriver, int far *graphmode,
  497.                                    const char far *pathtodriver );
  498. Function PRT_initgraph ( var graphdriver,graphmode: integer;
  499.                          pathtodriver: string ): integer;
  500.  
  501. Parameters
  502.    *graphdriver : an integer that specifies graphic driver to be used.
  503.                  Note that earlier you should install BGI driver
  504.                  (currently BitImage driver  only is included into the
  505.                  package) using PRT_installuserdriver function.
  506.                  If you specify DETECT as a passing argument value
  507.                  then the driver last used in PRT_initgraph or last installed
  508.                  using PRT_installuserdriver will be used. If none BGI printer
  509.                  driver was installed so far than PRT_installuserdriver will
  510.                  be called to install appropriate driver for printer defined
  511.                  by PRT_SetDriver. No true auto detection is (or will be)
  512.                  available.
  513.    *graphmode   : an integer that specifies graphic mode to be used.
  514.                  It should be zero value since in current version you
  515.                  must specify desired printing mode using PRT_SetDriver
  516.                  function.
  517.    pathtodriver : Specifies path to BGI drivers and CHR fonts. This parameter
  518.                  will be passed further to PRT_initgraph.
  519.  
  520.  
  521.    Initializes BITIMAGE BGI driver for creating bit image map.
  522. Note that YOU MUST earlier specify rectangle area for which bit map will
  523. be created by calling PRT_SetViewSize function.
  524. All requests for drawing (or reading) pixels outside that
  525. area will be ignored without any error codes. This would enable
  526. building the screen from rectangle pieces and printing it out even if
  527. there is not enough free memory to build the whole bit image map of
  528. printed picture at once.
  529.  
  530.    You must call PRT_SetViewSize before PRT_initgraph.
  531. (x1,y1),(x2,y2) area (specified by PRT_SetViewSize) must fill
  532. entirely within  - PREVIOUSLY - allocated buffer (via PRT_AllocateBuffer),
  533. otherwise an error code is return.
  534.    Returns 0 on success, nonzero on failure.
  535.  
  536.  
  537.    PRT_InitPrt
  538.    ============
  539.  
  540. int FAR_PROC _PRT__pascal PRT_InitPrt ( int handle );
  541. Function PRT_InitPrt ( var handle: file ): file;
  542.  
  543.    Sends printer initialization sequence to the specified handle.
  544. To print it out uses PRT_write function set by PRT_SetWriteFunc routine.
  545.    Note also that my standard PRT_Write function will call PRT_WriteError
  546. function (set by PRT_SetErrorFunc) whenever output error occurs.
  547.    Returns 0 on success, nonzero on failure.
  548. See also PRT_SetOpenFunc, PRT_SetCloseFunc, PRT_SetWriteFunc,
  549. PRT_SetErrorFunc.
  550.  
  551.  
  552.    PRT_installuserdriver
  553.    =====================
  554.  
  555. int FAR_PROC pascal PRT_installuserdriver ( const char far * name,
  556.                                             int huge (*detect)(void) );
  557. Type DetectFunc = function: integer;
  558. PRT_installuserdriver ( name: string; detect: DetectFunc ): integer;
  559.  
  560.    Used instead of standard Turbo installuserdriver function. You should
  561. use it to install BitImage BGI driver.
  562.  
  563.  
  564.    PRT_MaxDriver
  565.    ==============
  566.  
  567. int PRT_MaxDriver ( void );
  568. Function PRT_MaxDriver : integer;
  569.  
  570.    Returns maximum allowed printer driver number in PRINTBGI package;
  571.    See also PRT_SetDriver, PRT_DriverName, PRT_DriverNo.
  572.  
  573.  
  574.  
  575.    PRT_MaxMode
  576.    ============
  577.  
  578. int PRT_MaxMode ( unsigned driverno, int FAR *maxmode );
  579. Function PRT_MaxMode ( printerno: word; var maxmode: integer ): integer;
  580.  
  581.    Assigns to maxmode maximum mode number allowed for given driverno.
  582.    Returns 0 on success, nonzero on failure.
  583.    See also PRT_ModeName,  PRT_ModeNo.
  584.  
  585.  
  586.    PRT_ModeName
  587.    =============
  588.  
  589. int PRT_ModeName ( unsigned driverno, int modeno,
  590.                      char FAR* FAR* name_ptr );
  591. Function PRT_ModeName ( driverno: word; modeno: integer;
  592.                         var name_ptr: StringPtr ): integer;
  593.  
  594.    Assigns to StringPtr pointer pointing to static string containing name
  595. of mode modeno and printer numbered driverno. It can be used to list user
  596. all allowable modes and let him choose one.
  597.    Returns 0 on success, nonzero on failure.
  598.  
  599.  
  600.    PRT_ModeNo
  601.    ==========
  602.  
  603. int PRT_ModeNo ( void );
  604. Function PRT_ModeNo: integer;
  605.  
  606.    Returns current mode number as set by PRT_SetDriver or negative
  607. value.
  608.  
  609.  
  610.  
  611.    PRT_PrintBGI
  612.    =============
  613.  
  614. int far PRT_PrintBGI ( int far * graphdriver, int far *graphmode,
  615.                        const char far *pathtodriver,
  616.                        int ( FAR_PTR * FAR_PROC  /* pascal */ Draw)
  617.                            (void far* UserPointer),
  618.                        void far* UserPointer );
  619.    Type DrawType = function DrawFunc(UserPointer: pointer): integer;
  620. Function PRT_PrintBGI ( var graphdriver,graphmode: integer;
  621.                         pathtodriver: string;
  622.                         DrawFunc : DrawType,
  623.                         UserPointer: pointer );
  624.  
  625. Parameters
  626.    graphdriver,graphmode,pathtodriver - see PRT_initgraph.
  627.    Draw        : function drawing picture you want to print.
  628.    UserPointer : This parameter is not used by my library routines
  629.                  and will be passed unchanged to your Draw function.
  630.                  It may point to list of parameters for your Draw
  631.                  function.
  632.  
  633.    This is the main function of the whole package. In fact it does most
  634. of the work and using it is the most recommended way to use the whole
  635. PRINTBGI package. Of course in some nonstandard situations you may
  636. want to use some lower level routines to get more control over the package.
  637. But I think it will be very rarely case.
  638.  
  639.    I'll list all functions it does in the order they are performed.
  640. It should let you better understand other functions of this
  641. package.
  642.  
  643.    So it does the following.
  644.    1. Checks the correctness of arguments used in call to
  645.       PRT_SetDriver. Returns immediately PRT_NOT_INITIALIZED value if
  646.       they are incorrect, otherwise goes to step 2.
  647.    2. Checks if any BGI driver was active when it was called. If it
  648.       was closes it down and saves information needed to restore
  649.       screen graphic mode. Note that this step (or step 7
  650.       restoring caller graphic mode) may not work  correctly at all
  651.       circumstances (since for example it is very hardly to guess
  652.       what BGI driver was active at call to PRINTBGI).
  653.       So I highly recommend you to close down any BGI drivers you
  654.       were using before calling this function. Note also that
  655.       rectorecrtmode functions DOES NOT close down BGI driver but
  656.       only deactivates it. So you MUST USE closegraph function rather
  657.       than rectorecrtmode one before calling PRT_PrintBGI.
  658.    3. Allocates buffer using PRT_AllocateBuffer function.
  659.       If buffer allocation is unsuccessful returns immediately, otherwise
  660.       computes window size filling entirely in the allocated buffer.
  661.       This window may (or may not) cover the whole printing picture.
  662.    4. Calls PRT_Open,PRT_InitPrt to open file handle and to send
  663.       initialization codes to the printer.
  664.    5. Calls PRT_BuildBitMap to create bit image map of current
  665.       rectangle piece of picture went into allocated buffer. PRT_BuildBitMap
  666.       is described earlier in this chapter.
  667.    6. Calls PRT_PrintBuffer to print out current buffer ( which now
  668.       contains one piece of picture). If it is not the last
  669.       (or the only one) piece to print returns to point 5.
  670.    7. Calls PRT_EndPrt, PRT_Close;
  671.    8. Calls PRT_closegraph to close down the BGI driver used to create
  672.       bit image map of the printed picture.
  673.    9. Frees allocated buffer by calling PRT_FreeBuffer.
  674.   10. If in step 2 the active BGI driver was closed down tries now to
  675.       reactivate it. Note that it uses standard detectgraph function to
  676.       determine which BGI driver reactivate. So if you had nonstandard
  677.       BGI drivers active (e.g. SVGA or VGA256) it may happen that standard
  678.       VGA driver will be reactivate instead of the actually active one.
  679.       To avoid this problem either close down video BGI driver (using
  680.       closegraph) before calling PRT_PrintBGI or install nonstandard
  681.       BGI drivers with appropriate auto detection function
  682.       (see installuserdriver function in Borland documentation).
  683.       Note also that screen image is not restored.
  684.   11. Returns to the caller.
  685.  
  686.  
  687.    Function DrawFunc passed as an argument should meet the following
  688.    conditions.
  689.       - It draws on the screen the picture you want to print it out.
  690.       - It does not use any nonstandard graphic procedures (that is not
  691.         defined in GRAPH.TPU or GRAPHICS.LIB) to manipulate screen
  692.         output.
  693.       - It does not use initgraph, restorecrtmode, closegraph or setgraphmode
  694.         procedure. It simply assumes that appropriate graphic mode was
  695.         established before calling it.
  696.       - It is written in BGI independent way. That is it uses getmaxx,
  697.         getmaxy, getmaxcolor, getaspectratio to get device dependent
  698.         characteristic and scales all output according to it.
  699.       - Although it is not necessary it is recommended that it draws
  700.         the same picture (if the same BGI driver is used) each time
  701.         it is called.
  702.         This may be because if there is not enough memory to build bit image
  703.         map of the entire picture at once it is necessary to call
  704.         DrawFunc routine few times to create the picture piece by
  705.         piece (line by line). If it would draw different output at
  706.         consecutive calls then printed lines would not suit each other.
  707.       - It returns zero on success and nonzero on fail. This nonzero code
  708.         will cause immediate finish of the PRT_PrintBGI function and will
  709.         be also returned by it to the caller.
  710.  
  711.  
  712.    Note also that if there is not enough free memory to build the whole
  713. bit image map at once then some graphic functions which read the
  714. screen explicitly (e.g. getpixel,getimage) or implicitly (e.g. floodfill) may
  715. produce inaccurate results. This may happen if they refer to currently
  716. not building part of the picture.
  717.    Setting PRT_HaltPrinting variable to nonzero value lets you break
  718. this function before it will finish.
  719.  
  720.  
  721.    PRT_PrintBuffer
  722.    ================
  723.  
  724. typedef int*   PRT__handleT;
  725. int  PRT_PrintBuffer (PRT__handleT handle);
  726. Function PRT_PrintBuffer(var handle: file): integer;
  727.  
  728.    Prints entire "screen" buffer to the specified handle
  729. adding necessary control codes (see PRT_SetDriver).
  730.    To print out the buffer it uses PRT_write function set by
  731. PRT_SetWriteFunc routine.
  732.    Note also that my standard PRT_Write function will call PRT_WriteError
  733. function (set by PRT_SetErrorFunc) whenever output error occurs.
  734.  
  735.    Returns 0 on success, nonzero on failure.
  736.  
  737. See also PRT_SetOpenFunc, PRT_SetCloseFunc, PRT_SetWriteFunc,
  738. PRT_SetErrorFunc.
  739.  
  740.  
  741.    PRT_registerfarbgidriver
  742.    ========================
  743.  
  744. int FAR_PROC pascal PRT_registerfarbgidriver ( void far pascal
  745.                                                (*driver)(void) );
  746. Type DriverProc = procedure;
  747. PRT_registerfarbgidriver (  driver: DriverProc ): integer;
  748.    Use it instead of standard  registerbgidriver or registerfarbgidriver
  749. function. But note that before deleting registered driver from memory you
  750. MUST use PRT_Unregisterfarbgidriver function.
  751.  
  752.  
  753.    PRT_RescaleFillPattern
  754.    =======================
  755.  
  756. int PRT_RescaleFillPattern ( int r );
  757. Function PRT_RescaleFillPattern ( r: integer ): integer;
  758.  
  759.    Since external graphic devices have in most cases grater maximum
  760. possible resolution than screens, standard 8x8 fill patterns seem to be
  761. too small to use. This procedure let you demand of rescaling standard
  762. 8x8 fill patterns to 16x16 ones.
  763.    Parameter r means
  764.          0 = never rescale to 16x16,
  765.          1 = always rescale to 16x16,
  766.          -1 = rescale to 16x16 at high densities only.
  767.    The default value is -1.
  768.    Returns 0 on success, nonzero on failure.
  769.    If used must be called before initializing BITIMAGE BGI driver.
  770.  
  771.    See also setfillpattern16.
  772.  
  773.  
  774.    PRT_Resolution
  775.    ===============
  776.  
  777. int  PRT_Resolution ( int FAR *Xres, int FAR *Yres );
  778. Function PRT_Resolution ( var Xres,Yres : integer ): integer;
  779.  
  780.    Assigns to Xres and Yres dpi (dots per inch) resolution in
  781. appropriate direction according to last call of PRT_SetDriver.
  782.    Returns 0 on success, nonzero on failure.
  783.  
  784.  
  785.    PRT_Send
  786.    ========
  787.  
  788. int pascal PRT_Send( const void far *p, unsigned slen);
  789. Function PRT_Send( p: pointer; slen: word): integer;
  790.  
  791.    Calls PRT_Open, PRT_Write, PRT_Close to send slen bytes
  792. pointed to by p to the output file of a name set by PRT_SetOutName.
  793.    Returns zero om success, nonzero on failure.
  794. See also PRT_SetOutName, PRT_Open, PRT_Write, PRT_Close.
  795.  
  796.    PRT_SetBuffer
  797.    ==============
  798.  
  799. int PRT_SetBuffer ( long size, unsigned BufOpt );
  800. Function PRT_SetBuffer ( size : longint; BufOpt: word ): integer;
  801.  
  802.    Parameters
  803.       BufOpt : specifies what kind of memory may be used for buffer.
  804.                Allowed values.
  805.                   NotUseEMS (1) - use XMS or conventional memory
  806.                   NotUseXMS (2) - use EMS or conventional memory.
  807.                   NotUseEMS+NotUseXMS - use conventional memory only.
  808.                   0             - use any memory.
  809.       size   : if positive specifies maximum amount of memory that 
  810.                can be used for the buffer.
  811.                If negative specifies how minimum amount of memory that
  812.                must be left free after buffer allocation.
  813.                This parameter is currently meaningful only if conventional
  814.                memory is used.
  815.    Returns
  816.       0 on success, nonzero on failure.
  817.  
  818.  
  819.    PRINTBGI package uses the so called screen buffer to build bit
  820. image map of printing output in it. This procedure specifies what kind
  821. of memory can be used for that buffer. The whole buffer is allocated
  822. in one kind of memory in the following priority order XMS, EMS,
  823. conventional memory.
  824.  
  825.    If you have no particular need you should not call this procedure.
  826. If not called PRINTBGI will behave as you call it with both parameters
  827. zeroed thus enabling allocation of the buffer of the best size.
  828.  
  829.    If you let PRINTBGI use EMS memory keep in mind that DrawFunc ( set
  830. as parameter to PRT_PrintBGI) or any procedure called by it may not use
  831. EMS memory. Of course unless you save current EMS mapping at start
  832. and restore it at the end of your DrawFunc routine,
  833. which will make your use of EMS completely invisible by PRINTBGI.
  834. Note also that PRINTBGI does not save and restore EMS mapping at
  835. any time. So if you want you can save EMS mapping before call of any
  836. function that uses it and restore it afterwards. Following functions
  837. may change EMS mapping: PRT_PrintBuffer, PRT_PrintBGI, PRT_BuildBitMap,
  838. PRT_getpixel as well as any graphic routines using BitImage BGI driver.
  839.    If used, must be called before initializing BITIMAGE BGI driver.
  840.  
  841. Try to use PRT_Buffer, PRT_EMSBuffer or PRT_XMSBuffer instead.
  842.  
  843.  
  844.    PRT_SetCloseFunc
  845.    =====================
  846.  
  847.    typedef int ( FAR_PROC * PRT_CloseFuncP)( int* handle );
  848. PRT_CloseFuncP PRT_SetCloseFunc ( int far f(int* handle) );
  849.    Type CloseFuncType = Function(var handle:file): integer;
  850. Function PRT_SetCloseFunc ( f: CloseFuncType ): CloseFuncType;
  851.  
  852.    Defines function (passed as an argument f) which will be called to close
  853. file handle used to print out the picture. The f function takes an integer*
  854. argument which is supposed to contain an opened file handle. Exactly this is
  855. the case if you do not specified your own open function in which case it
  856. contains a number returned from your open function (see PRT_SetOpenFunc).
  857. This f function should return zero on success and suitable nonzero code
  858. otherwise.
  859.    If NULL is passed as an argument f then the old close function used so far
  860. will not be changed.
  861.    PRT_SetCloseFunc returns pointer to previously used close function.
  862.  
  863.    See also PRT_SetOpenFunc, PRT_SetCloseFunc, PRT_SetErrorFunc.
  864.  
  865.  
  866.    PRT_SetDriver
  867.    ==============
  868.  
  869. int PRT_SetDriver ( unsigned drv, unsigned mode,
  870.                      unsigned width, unsigned height, unsigned options );
  871. Function PRT_SetDriver ( drv,mode : word; width,height : word;
  872.                           options: word ) : integer;
  873.  
  874.  
  875.    Parameters
  876.       drv   : defines driver (and thus printer) number which will be
  877.               used. Allowed values (See PRINTBGI.H or PRINTBGI.INT) are:
  878.               IBM9, EPSON9, PANASONIC9, EPSON24, IBM24, HPLJII, HPPaintJet,
  879.               IBM9c, EPSON9c, EPSON24c, IBM24c.
  880.       mode  : defines driver (printer) mode number which will be
  881.               used. Allowed values are defined in PRINTBGI.H
  882.               (or PRINTBGI.INT for pascal version).
  883.       width,height : defines width and height of the next printing
  884.                      picture in 1/1000 inch values. That is 4000
  885.                      means 4 inches.
  886.       options      : can be defined as zero or it may have set one of the
  887.                      following bits
  888.          PRT_ROTATE  : if not set picture will be printed horizontally
  889.                        if set picture will be printed vertically.
  890.          PRT_INVERSE : if not set pixel of value 0 will be printed
  891.                        as black and pixel of value 1 will be printed white.
  892.                        1 means otherwise.
  893.                        For color printers 1 will force bit negation
  894.                        of pixel value before printing.
  895.    Returns
  896.       0 on success, nonzero on failure.
  897.    Default values.
  898.       Must be called. No default values assumed.
  899.  
  900.    Values defined by PRT_SetDriver stay in effect until next call of
  901. that procedure changing them explicitly.
  902.    Must be called before initializing BITIMAGE BGI driver.
  903.    No checking is (or will be) made if specified values are correct for your
  904. hardware. It is responsibility of the caller to detect hardware (or rather
  905. ask user to define it) and specify picture size acceptable by it.
  906.  
  907.  
  908.    PRT_SetErrorFunc
  909.    =====================
  910.  
  911.    typedef int ( FAR_PROC * PRT_ErrorFuncP) ( int* handle );
  912. PRT_ErrorFuncP PRT_SetErrorFunc ( int WrErrFunc(int* handle) );
  913.    Type ErrFuncType = Function ( var handle: file ): integer;
  914. Function PRT_SetErrorFunc ( ErrFunc: ErrFuncType ): ErrFuncType;
  915.  
  916.    Defines function (passed as an argument ErrFunc) which will be
  917. called whenever I/O error occur during printing. ErrFunc must
  918. return zero to retry printing or nonzero error code to abort
  919. printing. In that case the function in which an error occurred
  920. returns immediately to the caller with the same return code as received
  921. from ErrorFunc.
  922.    If ErrFunc argument passed is NULL no ErrFunc will be called
  923. whenever I/O error occurs.
  924.    PRT_SetErrorFunc returns pointer to currently used ErrFunc.
  925.  
  926.  
  927.    PRT_SetMargins
  928.    ===============
  929.  
  930. int PRT_SetMargins ( int left, int top );
  931. Function PRT_SetMargins ( left,top : integer ) : integer;
  932.  
  933.    Specifies (in 1/1000 inch) the left and top margins that should be
  934. left free during printing. Note that in most cases margins left will
  935. be only some approximation of the specified values and may considerably
  936. differ from them.
  937.    Returns 0 on success, nonzero on failure.
  938.  
  939.  
  940.    PRT_SetOpenFunc
  941.    =====================
  942.  
  943.    typedef int* ( FAR_PROC * PRT_OpenFuncP)( void );
  944. PRT_OpenFuncP PRT_SetOpenFunc ( int* far f(void) );
  945.    Type PRT__FilePtr = ^file;
  946.    Type OpenFuncType = Function: PRT__FilePtr;
  947. Function PRT_SetOpenFunc ( f: OpenFuncType ): OpenFuncType;
  948.  
  949.    Defines function (passed as an argument f) which will be called to open
  950. file handle for printing out the picture. The f function takes no arguments
  951. and should return opened file handle. Returning nonpositive value will be
  952. treated as an error.
  953.    If NULL is passed as an argument f then the old open function used so far
  954. will not be changed.
  955.    PRT_SetOpenFunc returns pointer to previously used open function.
  956.  
  957.    See also PRT_SetCloseFunc, PRT_SetWriteFunc, PRT_SetErrorFunc.
  958.  
  959.  
  960.    PRT_SetOutName
  961.    ==================
  962.  
  963. int PRT_SetOutName ( const char FAR * DeviceName );
  964. Function PRT_SetOutName ( DeviceName : string );
  965.  
  966.    Specifies where the graphic output should be sent. DeviceName
  967. can be any valid DOS device name (such as PRN,LPT1,LPT2,COM1, etc.)
  968. or file name (with or without the path). It is used in pascal assign
  969. procedure or C open function. Note that string pointed to by DeviceName
  970. is not copied but only reference is remembered. So DeviceName should
  971. not point to local dynamic area but to STATIC one rather.
  972.    Returns 0 on success, nonzero on failure.
  973.  
  974.  
  975.  
  976.    PRT_SetViewSize
  977.    ===============
  978.  
  979. int FAR_PROC pascal PRT_SetViewSize( int x1, int y1, int x2, int y2 );
  980. Function PRT_SetViewSize( x1,y1, x2,y2: integer ): integer;
  981.  
  982. Parameters
  983.    x1,y1,x2,y2 - specifies rectangular piece of picture which will be
  984.                  build by the BitImage BGI driver.
  985. See also PRT_initgraph.
  986.  
  987.  
  988.    PRT_SetWriteFunc
  989.    =====================
  990.  
  991.    typedef int ( FAR_PROC * PRT_WriteFuncP)
  992.                       ( int* handle, const void FAR_PTR * b, unsigned len );
  993. PRT_WriteFuncP FAR_PROC pascal PRT_SetWriteFunc
  994.                                ( int far f(int* handle,void FAR_PTR* buf,
  995.                                  unsigned len) );
  996.    Type WriteFuncType = Function(var handle:file; var b; len: word ): integer;
  997. Function PRT_SetWriteFunc ( f: WriteFuncType ): WriteFuncType;
  998.  
  999.    Defines function (passed as an argument f) which will be called to print
  1000. out len bytes pointed to by buf pointer.
  1001.    Parameters of f function
  1002.       handle  : an integer number returned by an open function set by
  1003.                 PRT_SetOpenFunc. My default open function simply returns
  1004.                 file handle.
  1005.       buf     : Pointer to data bytes which must be printed out.
  1006.       len     : Number of bytes to print.
  1007. If function f returns nonzero value it will be treated as an I/O error.
  1008.    If NULL is passed as an argument f then the old write function used so far
  1009. will not be changed.
  1010.    PRT_SetWriteFunc returns pointer to previously used write function.
  1011.  
  1012.    See also PRT_SetOpenFunc, PRT_SetCloseFunc, PRT_SetErrorFunc.
  1013.  
  1014.  
  1015.  
  1016.    PRT_Unregisterfarbgidriver
  1017.    ========================
  1018.  
  1019. int FAR_PROC pascal PRT_Unregisterfarbgidriver ( void far pascal
  1020.                                                  (*driver)(void) );
  1021. Type DriverProc = procedure;
  1022. PRT_Unregisterfarbgidriver (  driver: DriverProc ): integer;
  1023.  
  1024.    Used to unregister driver installed with PRT_registerfarbgidriver function.
  1025. You MUST use it before erasing registered BitImage driver from memory.
  1026.  
  1027.  
  1028.  
  1029.    PRT_XMSBuffer
  1030.    =============
  1031.  
  1032. int FAR_PROC pascal PRT_XMSBuffer ( int handle, long size, int usable )
  1033. Function PRT_XMSBuffer ( handle: integer; size: longint; usable: integer ):
  1034.          integer;
  1035.    Defines XMS buffer for use by the PrintBGI package.
  1036.    Parameters:
  1037.       usable   :  0 (zero) means not to use XMS memory. Other arguments are
  1038.                   in that case ignored (but preferably should also be zero).
  1039.       handle   :  Number of XMM handle to use for the buffer or zero (buffer
  1040.                   will be allocated by the package)
  1041.       size     :  If handle is nonzero defines amount of memory (in bytes)
  1042.                   allocated to that handler by the caller.
  1043.                   If handle is zero then
  1044.                     -   positive value defines maximum number of memory (which
  1045.                         will be rounded down to 16 KB boundary) that can be
  1046.                         used for the buffer by PrintBGI package.
  1047.                     -   negative value defines minimum number of memory left
  1048.                         free after buffer allocation.
  1049.                     -   zero allows to allocate as much memory as needed for
  1050.                         the buffer leaving only absolutely minimum free.
  1051.  
  1052.       Note that XMS buffer requires also some conventional memory buffer to
  1053.    be allocated.
  1054.       See also PRT_Buffer,PRT_EMSBuffer.
  1055.  
  1056.    PRT_XMSBufferNeeded
  1057.    =================
  1058.  
  1059. long PRT_XMSBufferNeeded ( int x1, int y1, int x2, int y2 );
  1060. Function PRT_XMSBufferNeeded ( x1,y1,x2,y2: integer ): longint;
  1061.  
  1062.    Returns size of buffer needed to draw picture in XMS memory of specified
  1063. size and on printer set by PRT_SetDriver. The returned value will be somewhat
  1064. larger than from PRT_BufferNeeded. If there exist less free memory than
  1065. needed then picture would be drawn in pieces. In that case results of all
  1066. procedures reading pixel values may be inaccurate.
  1067.    May be called only after PRT_SetDriver.
  1068.    See also PRT_BufferNeeded.
  1069.  
  1070.  
  1071.    setcharsize_Pix
  1072.    ===============
  1073.  
  1074. void  setcharsize_Pix (int width, int height);
  1075. Procedure  setcharsize_Pix ( width,height: integer );
  1076.  
  1077.    Sets char size width and heigth. The parameters should be given
  1078. in pixels. You may use it to obtain text proportional to the picture
  1079. sizes. For example if you want text height to be 1/60 of the whole
  1080. picture height and width 1/80 of the whole picture width you may use
  1081. following statement (in C language)
  1082.    setcharsize_Pix ( getmaxx()/80, getmaxy()/60 );
  1083.  
  1084.  
  1085.    setfillpattern16
  1086.    =================
  1087.  
  1088. void setfillpattern16 ( char FAR * upattern, int color );
  1089. Procedure SetFillPattern16 ( upattern: FillPatternType; color: word );
  1090.  
  1091.    If standard 8x8 fill patterns are not satisfied for you use this
  1092. function to define 16x16 patterns. Note that calling this function take
  1093. effect only when BITIMAGE BGI driver is active, for all other BGI drivers it
  1094. will be ignored. So the best approach is probably calling standard
  1095. setfillpattern function and then setfillpattern16. In that case ignoring
  1096. setfillpattern16 will cause that the pattern set by standard setfillpattern
  1097. function will be still in effect.
  1098.  
  1099.  
  1100.    PRT_HaltPrinting
  1101.    ================
  1102.  
  1103. Global variable. Is set to zero when PRT_PrintBGI starts. You may set it
  1104. to nonzero value to force almost immediate return from PRT_PrintBGI function
  1105. (without ending printing). This variable is tested after each line printed.
  1106. Note however that if PRT_PrintBGI called your Draw function then it will wait
  1107. for the Draw function to end before testing PRT_HaltPrinting.
  1108.  
  1109.  
  1110.  
  1111. ========================================================================
  1112.          GRAPHIC   FUNCTIONS
  1113. ========================================================================
  1114.  
  1115.    This section will describe all graphics functions that can be found
  1116. in Borland Graph.TPU unit for TP or GRAPHICS.LIB for B/TC(++). Note
  1117. that detailed description of each function can be found in appropriate
  1118. Borland documentation. Here are only given some differences from their
  1119. use in PRINTBGI package and standard Borland BGI drivers.
  1120.  
  1121.    Following functions can be used with my BitImage BGI driver in the
  1122. same way as with standard Borland BGI drivers.
  1123.  
  1124.  
  1125. void far   arc(int x, int y, int stangle, int endangle, int radius);
  1126. void far   bar(int left, int top, int right, int bottom);
  1127. void far   bar3d(int left, int top, int right, int bottom,
  1128.                 int depth, int topflag);
  1129. void far   circle(int x, int y, int radius);
  1130. void far   clearviewport(void);
  1131. void far   drawpoly(int numpoints, int far *polypoints);
  1132. void far   ellipse(int x, int y, int stangle, int endangle,
  1133.                    int xradius, int yradius);
  1134. void far   fillellipse( int x, int y, int xradius, int yradius );
  1135. void far   fillpoly(int numpoints, int far *polypoints);
  1136. void far   getarccoords(struct arccoordstype far *arccoords);
  1137. void far   getaspectratio(int far *xasp, int far *yasp);
  1138. int  far   getbkcolor(void);
  1139. int  far   getcolor(void);
  1140. void far   getfillpattern(char far *pattern);
  1141. void far   getfillsettings(struct fillsettingstype far *fillinfo);
  1142. int  far   getgraphmode(void);
  1143. void far   getlinesettings(struct linesettingstype far *lineinfo);
  1144. int  far   getmaxcolor(void);
  1145. int  far   getmaxx(void);
  1146. int  far   getmaxy(void);
  1147. char * far getmodename( int mode_number );
  1148. void far   getpalette(struct palettetype far *palette);
  1149. int  far   getpalettesize( void );
  1150. void far   gettextsettings(struct textsettingstype far *texttypeinfo);
  1151. void far   getviewsettings(struct viewporttype far *viewport);
  1152. int  far   getx(void);
  1153. int  far   gety(void);
  1154. void far   graphdefaults(void);
  1155. char * far grapherrormsg(int errorcode);
  1156. void far   _graphfreemem(void far *ptr, unsigned size);
  1157. void far * far  _graphgetmem(unsigned size);
  1158. int  far   graphresult(void);
  1159. unsigned   far  imagesize(int left, int top, int right, int bottom);
  1160. int  far   installuserfont( char far *name );
  1161. void far   line(int x1, int y1, int x2, int y2);
  1162. void far   linerel(int dx, int dy);
  1163. void far   lineto(int x, int y);
  1164. void far   moverel(int dx, int dy);
  1165. void far   moveto(int x, int y);
  1166. void far   pieslice(int x, int y, int stangle, int endangle,
  1167.                     int radius);
  1168. void far   putimage(int left, int top, void far *bitmap, int op);
  1169. void far   putpixel(int x, int y, int color);
  1170. void far   rectangle(int left, int top, int right, int bottom);
  1171. int        registerbgifont (void (*font)(void));
  1172. int  far   registerfarbgifont (void far *font);
  1173. void far   sector( int X, int Y, int StAngle, int EndAngle,
  1174.                    int XRadius, int YRadius );
  1175. void far   setaspectratio( int xasp, int yasp );
  1176. void far   setcolor(int color);
  1177. void far   setfillpattern(char far *upattern, int color);
  1178. void far   setfillstyle(int pattern, int color);
  1179. unsigned far  setgraphbufsize(unsigned bufsize);
  1180. void far   setlinestyle(int linestyle, unsigned upattern,
  1181.                         int thickness);
  1182. void far   settextjustify(int horiz, int vert);
  1183. void far   setusercharsize(int multx, int divx,
  1184.                            int multy, int divy);
  1185. void far   setviewport(int left, int top, int right, int bottom,
  1186.                        int clip);
  1187. int  far   textheight(char far *textstring);
  1188. int  far   textwidth(char far *textstring);
  1189.  
  1190.  
  1191.    Following functions may differ somewhat when used with printer
  1192. devices. See short descritption after function declaration.
  1193.  
  1194.  
  1195. void far  cleardevice(void);
  1196.    Does not enforce printing. Buffer is cleared and if mot printed
  1197. earlier its content is lost forever.
  1198.  
  1199. void far  closegraph(void);
  1200.    You rather shouldn't use it with BitImage BGI driver. Use PRT_closegraph
  1201. instead.
  1202.  
  1203. void far  detectgraph(int far *graphdriver,int far *graphmode);
  1204.    It will return detect values for screen not for external devices.
  1205.  
  1206.  
  1207. void far  floodfill(int x, int y, int border);
  1208.    Not implemented in current release. It'll be implemented in future
  1209. releases but remember that may produce some inaccurate results if
  1210. there is less memory than needed to build whole bit map for the
  1211. picture. Compare with PRT_PrintBGI description. Note also that it
  1212. cannot be implemented for some kind of output devices.
  1213.  
  1214.  
  1215. struct palettetype far * far  getdefaultpalette( void );
  1216.    Not implemented.
  1217.  
  1218. char * far  getdrivername( void );
  1219.    Returns BGI driver name. Since the package uses always the
  1220. same BGI driver (called BITIMAGE BGI driver) it will always return
  1221. the word BITIMAGE. To obtain names of printer drivers supported call
  1222. PRT_DriverName function described in earlier section.
  1223.  
  1224. void far  getfillpattern(char far *pattern);
  1225.    See also getfillpattern16 and PRT_RescaleFillPattern.
  1226.  
  1227.  
  1228. void far  getimage( int left, int top, int right, int bottom,
  1229.                     void far *bitmap);
  1230.    May not work if there is not enough memory for the entire picture.
  1231. Otherwise is fully supported.
  1232.  
  1233. int  far  getmaxmode(void);
  1234.    You should use rather PRT_MaxMode instead. Currently it always
  1235. returns zero since BitImage BGI driver being used supports one mode
  1236. only. Parameters which configure the driver for your needs can be set
  1237. using PRT_SetDriver function.
  1238.  
  1239.  
  1240. int  far  getmaxx(void);
  1241.    You should use it to rescale output according to screen sizes.
  1242.  
  1243. int  far  getmaxy(void);
  1244.    You should use it to rescale output according to screen sizes.
  1245.  
  1246. void far  getmoderange(int graphdriver, int far *lomode,
  1247.          int far *himode);
  1248.    Shouldn't be used.
  1249.  
  1250. unsigned   far  getpixel(int x, int y);
  1251.    May not work if there is not enough memory for the entire picture.
  1252. Otherwise is fully supported.
  1253.  
  1254. char * far  grapherrormsg(int errorcode);
  1255.    You may use PRT_grapherrormsg instead.
  1256.  
  1257. void far  initgraph(int  far *graphdriver,
  1258.             int  far *graphmode,
  1259.             char far *pathtodriver);
  1260.    To initialize BitImage BGI driver you must use PRT_initgraph instead.
  1261.  
  1262. int  far  installuserdriver( char far *name, int huge (*detect)(void) );
  1263.    You must use PRT_installuserdriver to install PRINTBGI drivers.
  1264.  
  1265. void far  outtext(char far *textstring);
  1266.    To print standard fonts of code 128 or higher you should use DOS
  1267. GrafTabl command before, otherwise printing is garbage. Note also
  1268. that fonts table for characters 127 or lower is taken from ROM BIOS.
  1269. If you have no such a table in standard place some problems may also
  1270. occur.
  1271.    See also settextstyle comments.
  1272.  
  1273. void far  outtextxy(int x, int y, char far *textstring);
  1274.    See outtext and settextstyle comments.
  1275.  
  1276.  
  1277. int         registerbgidriver (void (*driver)(void));
  1278.    To register BitImage driver you should use PRT_registerfarbgidriver
  1279. instead.
  1280.  
  1281. int   far   registerfarbgidriver (void far *driver);
  1282.    To register BitImage driver you should use PRT_registerfarbgidriver
  1283. instead.
  1284.  
  1285. void far  restorecrtmode(void);
  1286.    Shouldn't be used. Before using PrintBGI toolkit functions you must
  1287. close down any active video BGI driver. To do this use closegraph not
  1288. restorecrtmode function. On the other hand using restorecrtmode with
  1289. BitImage BGI driver has little sense.
  1290.  
  1291. void far  setactivepage(int page);
  1292.    Not implemented.
  1293.  
  1294. void far  setallpalette(struct palettetype far *palette);
  1295.    Not implemented.
  1296.  
  1297. void far  setaspectratio( int xasp, int yasp );
  1298.    You may use it to change current aspect ratio but remember that
  1299. default values are correct.
  1300.  
  1301. void far  setbkcolor(int color);
  1302.    Not implemented in current release.
  1303.  
  1304. void far  setfillpattern(char far *upattern, int color);
  1305.    See setfillpattern16 and PRT_RescaleFillPattern in previous section.
  1306.  
  1307. void far  setfillstyle(int pattern, int color);
  1308.    See PRT_RescaleFillPattern in previous section.
  1309.  
  1310. void far  setgraphmode(int mode);
  1311.    Shouldn't be used.
  1312.  
  1313. void far  setpalette(int colornum, int color);
  1314.    Not implemented.
  1315.  
  1316. void far  setrgbpalette(int colornum,
  1317.           int red, int green, int blue);
  1318.    Not implemented.
  1319.  
  1320. void far  settextstyle(int font, int direction, int charsize);
  1321.    May produce different results for standard fonts (DEFAULT_FONT)
  1322. and direction other than HORIZ_DIR or VERT_DIR. May also behave
  1323. slightly different when text expands beyond clip region. You may use
  1324. setcharsize_Pix function to set font size in pixels.
  1325.  
  1326. void far  setvisualpage(int page);
  1327.    Not implemented.
  1328.  
  1329. void far  setwritemode( int mode );
  1330.    In difference with Borland's BGI drivers write mode defined by
  1331. that procedure is valid for all subsequent write operations. Mode
  1332. argument may be one of the following: COPYPUT, XORPUR, ORPUT,
  1333. AND_PUT, NOT_PUT not just limited to fist two constants only (as is
  1334. in Borland's library).
  1335.  
  1336.  
  1337.  
  1338.       DEFINING YOUR OWN PRINTERS
  1339.       ==========================
  1340.  
  1341.    Printers descriptions used by the package are contained in Drivers
  1342. module. I included in this package all files necessary to compile
  1343. Drivers.ASM. So you may modify this file and compile it creating OBJ file
  1344. which in turn you should added to PRTGRAPH.LIB replacing old OBJect member
  1345. of the same name. Turbo Pascal users should compile Drivers.Pas file
  1346. instead of modifying PRTGRAPH.LIB.
  1347.    I must tell you that defining your own printer is not easy. You probably
  1348. will have a lot of troubles with it unless you are an expert in using
  1349. printers in graphic mode. In that case you should not have troubles. Read
  1350. Drivers.INC and then copy one of the closest printer already defined in
  1351. Drivers.ASM and modify parameters you need.
  1352.    I suppose there are some printers which cannot be added this way. If you
  1353. have such a one it means that it requires the modification of printers
  1354. definitions structure as well as some other source code modifications.
  1355. Please contact the author in that case.
  1356.  
  1357.  
  1358.       THE FUTURE
  1359.       ==========
  1360.  
  1361.    If there is some interest in this package I will write 1.0 version
  1362. which will
  1363.    - support all dot matrix printers, postscript printers and some
  1364.      others as well as some plotters,
  1365.    - contain table (and function to use it) with names of all available
  1366.      printers and appropriate driver number used by the package (if users
  1367.      support me in doing it) ,
  1368.    - let you keep printers definitions in separate file or linked it with
  1369.      the main module,
  1370.    - work in all memory models (except tiny of course),
  1371.    - be tested on more printers,
  1372.    - contain some more improvements, I hope.
  1373. All registered users will obtain this 1.0 version completely free.
  1374.  
  1375.  
  1376. To contact the author write to
  1377.  
  1378.    Andrzej Resztak
  1379.    ul. K. Wallenroda 2c/18
  1380.    20-607 Lublin
  1381.    POLAND
  1382.  
  1383. or (preferably) to e-mail address:
  1384.    Resztak@PLUMCS11.bitnet
  1385.  
  1386.  
  1387.    /* end of PRINTBGI.DOC  */
  1388.