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