
 BCC2GRX  -  Interfacing Borland based graphics programs to LIBGRX
 Copyright (C) 1993  Hartmut Schirmer

 This library is free software; you can redistribute it and/or
 modify it under the terms of the GNU Library General Public
 License as published by the Free Software Foundation; either
 version 2 of the License, or (at your option) any later version.

 This library is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 Library General Public License for more details.

 You should have received a copy of the GNU Library General Public
 License along with this library; if not, write to the Free
 Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

1. Introduction and overview
------------------------------------------------------------------------------

   The BCC2GRX was created to allow users of DJGPP/LIBGRX to compile
   graphics programs written for Borland's graphics interface. C code
   can be directly compiled and linked with BCC2GRX. Pascal code has
   to be converted by P2C.


   Please note that BCC2GRX was designed for use with the DJGPP compiled
   LIBGRX exclusively. The Borland-C++ LIBGRX isn't supported since
   one can use the native BGI interface !


   Using DJGPP/LIBGRX based graphics gives you some advantages :

      - 32 bit linear memory model
      - high efficient C/C++/Objective-C compiler
      - high resolution and high color graphics modes supported
      - easy way to support new graphics adapters
      - DJGPP, LIBGRX and BCC2GRX are free software
      - most ported applications run faster


   The actual BCC2GRX (v1.2a) does only a few error checks since
   it is assumed the progam was extensively tested before porting it
   to DJGPP. BCC2GRX is not a convenient  platform to develop new BGI
   programs. Of course you should use DJGPP's native LIBGRX in such
   cases!


2. What do I need to use BCC2GRX ?  Where can I find it ?
------------------------------------------------------------------------------

   There are some things you need to use BCC2GRX :

     DJGPP    DJ Delorie's port ot GNU-C to MS-DOS              (djdev???.zip)
     LIBGRX   Csaba Biegl's graphics library for BCC and DJGPP  (cbgrx???.zip)
     BCC2GRX  of course                                         (bccgrx12.zip)
     P2C      Dave Gillespie's Pascal to C converter (Optional) (hsp2c???.zip)
     make     The BCC2GRX makefiles are tested with Borland
	      make 3.0/3.6 . GNUish make (3.58) may also be
	      used (check all makefiles to be set up correct!)

   These are the basic files. At least the DJGPP packages requires additional
   files. Check the related documentation for more details.

   The home of all DJGPP related software is
		   omnigate.clarkson.edu (128.153.4.2)
   in the directory
		   /pub/msdos/djgpp/ , /pub/msdos/djgpp/pub/

   The whole djgpp directory on omnigate seems to be mirrored eg. by
       ftp.3com.com        (129.213.128.5) /mirrors/djgpp/
       ftp.th-darmstadt.de (130.83.55.75)  /pub/machines/ms-dos/386/gcc/
       rzserv3.rz.tu-bs.de (134.169.9.31)  /pub/pc/msdos/programmieren/djgpp/

   You should query an archie server to find a nearby server carrying
   the files mentioned above.


  ----------------------------------------------------------------------
  !                                                                    !
  ! ATTENTION: BCC2GRX 1.2a needs LIBGRX Version 1.03.maint1 or newer. !
  !                                                                    !
  ----------------------------------------------------------------------      


3. Installing BCC2GRX
------------------------------------------------------------------------------

  1. DJGPP is installed and tested

  2. Install the LIBGRX package and check it.

    a. Unpack the cbgrx???.zip
    b. Set the environment variables
	  set GRXFONT=GCC/contrib/libgrx/fonts
	  set GO32=driver GCC/contrib/libgrx/drivers/stdvga.grn
       where GCC is the home directory of djgpp. Use stdega.grn with EGA
       cards. You shouldn't specify gw, gh or nc keywords. See DJGPP
       and LIBGRX documentation for more detailed information.
    c. goto GCC/contrib/libgrx/drivers and check our installation by
       running
		  go32 modetest
    d. if you succeded you can step on. You also may install a special
       graphics driver supporting your hardware (run modetest again !).
    e. Compile at least one test program (eg. test/test.c). If there are
       problems, check the environment variables of DJGPP and LIBGRX again.

  3. Install the BCC2GRX and check it

    a. Unpack bccgrx12.zip
    b. go to GCC/contrib/bcc2grx/test and issue the 'make' command.
       (the makefile is set up for Borland Make 3.0, it may need some
       changes with other make-s)
    c. run bccbgi.exe

  4. Set up BCC2GRX for your own programs

    a. Copy GCC/contrib/bcc2grx/lib/libbcc.a to a directory in your
       LIBRARY_PATH or add GCC/contrib/bcc2grx/lib to LIBRARY_PATH.
    b. Copy GCC/contrib/bcc2grx/include *subdir* to a directory in
       your C_INCLUDE_PATH or add GCC/contrib/bcc2grx/include to the
       ???_INCLUDE_PATH environment variables.

  5. Install P2C and check it

    a. Unpack hsp2c???.zip
    b. add set P2C_home=GCC/contrib/p2c/home to your environment
    c. switch to GCC/contrib/p2c/examples and say make
    d. run the test programs

  6. Set up P2C for BCC2GRX

    a. replace the 'graph' unit in GCC/contrib/p2c/home/turbo.imp
       by GCC/contrib/bcc2grx/tp2bcc/p2c/graph.imp
    b. Copy P2C.EXE to a directory in your PATH (eg. GCC/bin) or add
       GCC/contrib/p2c/home to your PATH.
    c. make sure that libp2c.a is found in your LIBRARY_PATH
    d. Switch to GCC/contrib/bcc2grx/tp2bcc and build the bgidemo.exe
       program by:
	 make cleanall
	 make
    e. run bgidemo.exe


  Now BCC2GRX should be installed. The last two steps (5.+6.) are
  only required if Turbo-Pascal sources will be used with DJGPP.

  If you have serious problems, you should notice it on the djgpp
  mailing list or contact me directly (see end of this text) !


4. Differences between BGI and BCC2GRX
------------------------------------------------------------------------------

   BCC2GRX is based on LIBGRX instead of the .bgi drivers. This fact
   introduce some differences compared with the Borland GI. The (known)
   differences are listed below.


   - GNU-C is a 32 bit compiler. An int will take 4 bytes instead of
     2 with Turbo-Pascal and BCC. If you need a 16 bit integer, change
     the definition from int to short witch is 16 bit on either system.
   - BLACK and WHITE are functions not constants with BCC2GRX. May cause
     problems in switch () statements.
   - BCC2GRX will not use .bgi drivers. Installing an user driver and
     the register(far)bgidriver will always cause an error.
   - registerfarbgifont() and registerbgifont() are the same. Both
     take a void* to the character font (whole file with header !)
   - initgraph()/detectgraph() work slightly different. See below for details.
   - getmodenames() and other functions can be called before initgraph()
   - character files won't be flushed at closegraph()
   - NOT_PUT isn't supported.
   - some constant's may differ in value (eg. VGA, ... )
   - BCC2GRX's outtext() and outtextxy() do correct clipping
   - some graphics primitives slightly differ in behaviour between BGI
     and LIBGRX. Eg. the "saucer" in bccbgi.c putimage()/getimage() demo looks
     different.
   - the BCC2GRX header file is <libbcc.h> . You have to change the
     #include statements since DJGPP defines an incompatible <graphics.h>.
     Conditional compilation is a good way to handle this problem :
	 #ifdef __GNUC__
	 #  include <libbcc.h>
	 #else
	 #  include <graphics.h>
	 #endif



5. Some useful internals of BCC2GRX
------------------------------------------------------------------------------

   Since LIBGRX provides a flexible and powerful set of graphics primitives,
   some of the basic routines are defined within bccgrx.h using "__inline__
   static" functions. GNU-C compiles these functions like macros but you can
   refer to their address. There is one exeption to this rule : When compiling
   code based on a pascal program, a macro is used for getaspectratio since
   the pascal and C graphics interfaces use different calling types. You
   should use src/whereis to find the file that implements a function.

   BGI has something called a 'viewport'. There are two very different behaviors
   depending on the clipping flag:

     If clipping is on, one introduces something like a subscreen where
     (nearly) all drawing operations are done.
     Otherwise the origin of the drawing coordinate system is shifted from
     the top left corner to some other point on screen.

   BCC2GRX allways adds the origin shift to all operations. If clipping is
   requested, GrSetClipBox() is called and LIBGRX restricts drawing to the
   selected subscreen.

   One may wonder why BCC2GRX has it's own drawpoly() function instead
   of using the LIBGRX function. In BGI a polygon isn't really
   a polygon but may be a union of several unconnected closed polygons.
   In more detail:

     If the start point of a polygon is reached again, the next point
     is the start point of a new polyon. No connection is drawn.

   So one may draw several closed polygons at once. I don't know whether
   this behavior of the BGI is a bug or a feature, but BCC2GRX is
   at least compatible ...


6. initgraph()/detectgraph()
-----------------------------------------------------------------------------

  It's recommented to use something like the following code to
  initialize the graphics interface :

   int gd, gm, err;
   gd = DETECT;                         /* or detectgraph(&gd,&gm); */
   initgraph(&gd,&gm,PATH_TO_CHR_FILES);
   err = graphresult();
   if (err != grOk) ...

  This code sets up the default graphics mode defined in the GO32
  environment variable. If you need a special mode set by your program,
  you should call it running a batch file:

     @echo off
     set GO32 = <special_driver> <special_mode> ....
     myprog.exe %1 %2 %3 ...

  This can not be done with every program due to DOS restrictions
  (eg. maximum 9 parameters passed, environment space may exceed).
  To overcome these problems, BCC2GRX uses a special graphics driver
  called NATIVE_GRX. This new driver supports 3 abstract, one special
  and of course all .grn driver modes. The following example shows the
  usage of NATIVE_GRX :

      int gd, gm, err;
    #ifdef __GNUC__
      gd = NATIVE_GRX;
      gm = <mode>;
    #else
      /* BCC stuff */
    #endif
      initgraph(&gd,&gm,PATH_TO_CHR_FILES);
      err = graphresult();
      if (err != grOk) ...

  where <mode> can take to following values :

     GRX_DEFAULT_GRAPHICS                (same as DETECT)
     GRX_BIGGEST_NONINTERLACED_GRAPHICS  (see LIBGRX documentation for details)
     GRX_BIGGEST_GRAPHICS                (see LIBGRX documentation for details)
     GRX_BGI_EMULATION                   (see below)
     GRX_BGI_EMULATION+1 .. ?            (Graphics modes from .grn drivers)

  The GRX_BGI_EMULATION mode is the most flexible one and needs to be
  initialized before calling initgraph(). The mean idea is to select the
  graphics resolution and colors by calling

      void set_BGI_mode(int *graphdriver, int *graphmode);
  or
      void set_BGI_mode_whc(int *graphdriver, int *graphmode,
			    int width, int height, int colors);

  Lets have a look at some examples. If you need eg. 640x480x16 standard
  VGA mode, use something like

	   gd = VGA; gm = VGAHI;
	 #ifdef __GNUC__
	   set_BGI_mode( &gd, &gm);
	 #endif
	   initgraph( &gd, &gm, "");

  Non standard resolutions (eg. 800x600x256) use set_BGI_mode_whc() :

	 #ifdef __GNUC__
	   set_BGI_mode_whc( &gd, &gm 800, 600, 256);
	 #else
	   /* BGI stuff invoking a high resolution mode */
	 #endif
	   initgraph( &gd, &gm, "");


  The BCC2GRX requests to desired resolution by a
	GrSetMode( GR_width_height_color_graphics, ...)
  function call. If there is no such mode in the current driver, a related
  one will be used by LIBGRX. If you program needs a special resolution
  (say eg. Hercules 720x348) you should check getmaxx() and getmaxy() after
  initgraph() .

  Please note that

    - set_BGI_mode(HERCMONO, HERCMONOHI) uses 720x350x16 on VGA cards,
    - all drivers != NATIVE_GRX behave like DETECT with BCC2GRX,
    - set_BGI_mode[_whc]() sets up local variables used by initgraph() and
      setgraphmode(). You may change the resolution after initgraph() done
      by
	     gd = DETECT;
	     initgraph(&gd, &gm, "");
	     /* Default graphics mode */
	     ....
	   #ifdef __GNUC__
	     set_BGI_mode_whc(&gd, &gm, 1024, 768, 256);
	   #else
	     /* BGI stuff to set up 1024x768x256 mode */
	     gm = ... ;
	   #endif
	     setgraphmode( gm);
	     /* Now in 1024x768x256 mode */

    - closegraph() doesn't free any memory allocated for vector fonts. So
      you can't switch to a second (different) set of fonts. Every font will
      be loaded once and stay in (virtual) memory until the program terminates.
      If this behaviour doesn't work with your program (eg. something like a
      font editor) or you get short of memory loading hundreds of fonts,
      please tell me about.


7. Using fonts
------------------------------------------------------------------------------

   The BCC2GRX v1.2 or newer can link vector fonts into the .exe file.
   The standard fonts are in the libgrx.a :

	   _bold_font, _euro_font, _goth_font, _lcom_font
	   _litt_font, _sans_font, _scri_font, _simp_font
	   _trip_font, _tscr_font

   Call registerbgifont() to enable font usage :

	   registerbgifont( &_bold_font);
	   registerbgifont( &_euro_font);
	   registerbgifont( &_goth_font);
	   registerbgifont( &_lcom_font);
	   registerbgifont( &_litt_font);
	   registerbgifont( &_sans_font);
	   registerbgifont( &_scri_font);
	   registerbgifont( &_simp_font);
	   registerbgifont( &_trip_font);
	   registerbgifont( &_tscr_font);

   Of course you can also link non standard fonts :

	   - copy the .chr file(s) to bcc2grx/chr
	   - say nonbgi <font_name>      (font_name: 4 letters, no extension)
	   - copy the <font_name>.o to your source files
	   - add
		   extern int _<font_name>_font;
		   registerbgifont( &_<font_name>_font);
	     to your source
	   - add it to the linker command line
	      ( gcc -o test test.o <font_name>.o -lbcc -lgrx )

   The actual BCC2GRX handels the 11 standard and up to 10 user fonts. If you
   need mode user fonts, you should change the definition of LastUserFont in
   bccgrx06.c !


   Starting with BCC2GRX V1.2 you can also use the LIBGRX bitmapped fonts.
   Just get a font handle and set the new text style. Eg. you may want to
   use the 8x16 VGA font in high resolution graphics:

      font_handle = installuserfont( "@:pc8x16.fnt");
      settextstyle( font_handle, HORIZ_DIR, 1);

   See test/ttext.c for more examples.


8. What's new in this release ?
------------------------------------------------------------------------------

   - makefiles prepeared for GNUish make
   - set_BGI_mode() / set_BGI_mode_whc() stuff
   - Linkable vector fonts
   - nearly complete error checking

   The complete list of changes or new features in the current version of
   BCC2GRX can be found in src/changes .


9. Short description of BCC2GRX files
------------------------------------------------------------------------------

The BCC2GRX library contains the following files :

README                 This file.
MAKEFILE               General makefile  (Borland make 3.0 tested)
INCLUDE/               Global header files
INCLUDE/P2C/           Global header files needed in P2C converted stuff
SRC/                   Source code of BCC2GRX
TP2BCC/                Pascal test files, p2c resources
TEST/                  C test files
LIB/                   BCC2GRX library
CHR/                   Borland font files
COPYING.LIB            The license conditions of the BCC2GRX distribution

TP2BCC.H               Definitions needed in P2C converted code
TASTEN.H               Definitions of keycodes returned by getkey(). May be
		       set up for a german keyboard.
BGIEXT.H               Functions and data not defined by BGI
LIBBCC.H               Standard include files when using BCC2GRX
		       (Includes  BGIEXT.H, BCCGRX.H, GRX.H, delay)
TP_PORT.H              Definitions of useful Borland-like functions ( random
		       number generator, readkey, ...)
BCCGRX.H               Declaration of standard BGI functions, ...

LIBBCC.A               This is BCC2GRX. May be copied to your DJGPP
		       library directory. (gcc 2.4.1 compiled)

BCCGRX.C               Basic interface file. Holds global data and the
		       mode switching code.
BCCGRX??.C             Graphics primitives.
BGIEXT??.C             New graphic routines useful with BCC2GRX and the
		       Borland C compiler.
DELAY.S                Source of a Borland like delay procedure.
RAND_TP.C              Source of a Borland like random number generator
READKEY.C              Source of a Turbo-Pascal like readkey function

BCCBGI.C               This is an extended copy of the BGIDEMO.C that
		       comes with BCC 3.0.
HTMEXT.INC             Extended demo routines, included by BCCBGI.C.

P2CRC                  P2C resource file needed to translate Pascal BGI
		       into BCC BGI code.
GRAPH.IMP              Definitions exported by graph.tpu, should replace the
		       unit 'graph' in TURBO.IMP that comes with P2C (1.20)
BGIDEMO.PAS            Corrected source code of the BGIDEMO.PAS that comes
		       with TP 6.0

-----------------------------------------------------------------------------

DJGPP mailing list :

	There are two DJGPP related lists :

	  DJGPP@sun.soe.clarkson.edu
	  DJGPP-announce@sun.soe.clarkson.edu

	Send an email containing only 'help' to

	  LISTSERV@sun.soe.clarkson.edu

	for more information.

-----------------------------------------------------------------------------
Contact :                Hartmut Schirmer
			 Feldstrasse 118
		  D-2300 Kiel 1
			 Germany


    NOTE : Please use
			 Hartmut Schirmer
			 Feldstrasse 118
		 D-24105 Kiel
			 Germany

	   after July 1 1993 !!


    email : PHC27@rz.uni-kiel.dbp.de   (subject to change)

