Using SDL_bgi
=============


Although SDL_bgi is almost perfectly compatible with the original BGI
library, a few minor differences were introduced to take advantage of
modern SDL graphics. You don't want a slow library!


Compiling programs
------------------

To port an old BGI program to SDL_bgi, in many cases all you have to
do is change the line that reads:

  #include <graphics.h>

to

  #include <SDL2/SDL_bgi.h>

but you could also do:

  $ sudo ln -s /usr/include/SDL2/SDL_bgi.h /usr/include/graphics.h

which lets you leave old programs untouched - unless they also include
dos.h and conio.h, which you'll have to remove or replace. The 
graphics.h link must be created manually, since other software
packages provide it (e.g. Allegro, wx, and others).

Then, to compile a program:

  $ gcc -o program program.c -lSDL_bgi -lSDL2

Most old programs that use the original BGI library should compile
unmodified. For instance,

  int gd = DETECT, gm;
  initgraph (&gd, &gm, "");

will open an 800x600 window, mimicking SVGA graphics. To specify the
window size, you can use the new SDL driver:

  gd = SDL;
  gm = <mode>;

where <mode> can be one of the following:

  SDL_640x480     640x480
  SDL_800x600     800x600
  SDL_1024x768    1024x768
  SDL_1152x900    1152x900
  SDL_1280x1024   1280x1024
  SDL_1366x768    1366x768
  SDL_FULLSCREEN  full screen

You may want to use initwindow (int width, int height) instead.


Screen update
-------------

The only real difference between the original BGI and SDL_bgi is the
way the screen is refreshed. In BGI, every pixel drawn on screen was
immediately displayed. This was a terribly inefficient way of drawing
stuff: the screen should be refreshed only when the drawing is done.
For example, in SDL2 this action is performed by SDL_RenderPresent ().

You can choose whether to open the graphics system using initgraph (),
which toggles BGI compatibility and forces a screen refresh after
every graphics command, or using initwindow () that leaves you in
charge of refreshing the screen when needed, using the new function
refresh (). The second method is *much* faster and is preferable.

Functions sdlbgifast (void) and sdlbgislow (void) are also available.

Documentation and sample BGI programs are available at this address:
http://www.cs.colorado.edu/~main/cs1300/doc/bgi/
Most programs can be compiled with SDL_bgi.


Differences
-----------

- The following functions are not implemented:

  _graphfreemem       - unneeded
  _graphgetmem        - unneeded
  installuserdriver   - it makes no sense in SDL
  installuserfont     (implement if for SDL_ttf?)
  registerbgidriver   - it makes no sense in SDL
  registerbgifont     - it makes no sense in SDL
  setgraphbufsize     - unneeded

- floodfill () only uses SOLID_FILL. Fill patterns are used by bar (),
bar3d (), and filledellipse ().

- setpalette () only affects future drawing. That is, you can't get a
"rotating palette animation" as in Turbo C.

- an 8x8 bitmap font is included, and it's the only one font. Changes
to other BGI fonts (e.g. TRIPLEX_FONT, and others) make no effect:
consider using SDL_ttf!

- fillpoly () only works correctly when the polygon is convex, and it
only uses SOLID_FILL.

- kbhit () (provided by conio.h in Turbo C/Borland C++) returns 1 when
any key is pressed, including Shift, Ctrl, etc.

- Key presses may not be detected during a delay ().


Additions
---------

Some functions and macros have been added to add functionality in a
manner compatible with other BGI implementations (namely, Xbgi and
WinBGIm).

Further, the following variables (declared in SDL_bgi.h) are
accessible:

  SDL_Window   *bgi_window;
  SDL_Renderer *bgi_renderer;
  SDL_Texture  *bgi_texture;

and can be used by native SDL2 functions.

- void initwindow (int width, int height) lets you open a window
specifying its size.

- void detectgraph (int *gd, int *gm) returns SDL, SDL_FULLSCREEN.

- void setrgbpalette (int color, int r, int g, int b) sets an
additional palette containing RGB colours (up to MAXRGBCOLORS + 1).
See example in test/mandelbrot.c.

- void setrgbcolor (int col) and void setbkrgbcolor (int col) are the
RGB equivalent of setcolor(int col) and setbkcolor(int col). 'col' is
an allocated colour entry in the RGB palette.

- COLOR (int r, int g, int b) can be used as an argument whenever a
colour value is expected (e.g. setcolor (int col) and other
functions). It's an alternative to setrgbcolor (int col) and
setbkrgbcolor (int col). Allocating colours with setrgbpalette () and
using setrgbcolor () is much faster, though.

- IS_BGI_COLOR (int c) and IS_RGB_COLOR (int c) return 1 if the current
colour is standard BGI or RGB, respectively.

- RED_VALUE (int c), GREEN_VALUE (int c), and BLUE_VALUE (int c) return
the R, G, B component of an RGB colour.

- setalpha (int col, Uint8 alpha) sets the alpha component of colour
'col'.

- void _putpixel (int x, int y) is equivalent to putpixel (int x, int
y, int col), but uses the current drawing colour and the pixel is not
refreshed in slow mode.

- random (range) is defined as macro: rand()%range

- int getch () waits for a key and returns its ASCII code. Special keys
are also reported; please see SDL_bgi.h.

- void delay (msec) waits for 'msec' milliseconds.

- int mouseclick (void) returns the code of the mouse button that was
clicked, or 0 if none was clicked. Mouse buttons are defined in
SDL_bgi.h:

  WM_LBUTTONDOWN  1
  WM_MBUTTONDOWN  2
  WM_RBUTTONDOWN  3

- int mousex (void) and int mousey (void) return the mouse coordinates
of the last click.

- int ismouseclick (int kind) returns 1 if the 'kind' mouse button was
clicked.

- void getmouseclick (int kind, int *x, int *y) sets the x, y
coordinates of the last button click expected by ismouseclick ().

- int getevent (void) waits for a keypress or mouse click, and returns
the code of the mouse button or key that was pressed.

- int event (void) is a non-blocking version of getevent ().

- void readimagefile (char *filename, int x1, int y1, int x2, int y2)
reads a .bmp file and displays it immediately (i.e. no refresh
needed).

- sdlbgifast (void) triggers "fast mode" even if the graphics system
was opened with initgraph (). Calling refresh () is needed to display
graphics.

- sdlbgislow (void) triggers "slow mode" even if the graphics system
was opened with initwindow (). Calling refresh () is not needed.

- void writeimagefile (char *filename, int left, int top, int right,
int bottom) writes a .bmp file from the screen rectangle defined by
(left,top--right,bottom).


Bugs & Issues
-------------

Drawing in BGI compatibility mode is much slower than it should, since
SDL_UpdateTexture () doesn't work as expected (bug?).

Colours don't have the same RGB values as the original BGI colours.
But they look better (IMHO).

Probably, this documentation is not 100% accurate. Your feedback is
more than welcome.
