DEMO.TXT

If you  know how  to program  using Turbo C,  you can create a demo of
your own for SuperGraphix!

We recommend  you print this document out.  To print this document, at
the dos prompt type:

C:\>type demo.txt>prn


The visual  requirements for a demo are simple.  It simply must be fun
to look  at,   and should take time to display.  The rule of thumb is:
If it  would make  a good screen saver,  it would make a good graphics
demo.

Getting Your Demo Added To SuperGraphix
---------------------------------------
Write a  "driver independent" graphics demo using Turbo C 2.0 (or C++)
using .BGI  (Borland  Graphics  Interface)  standard  function  calls.
Examples are putpixel(), line(), circle(), clearviewport etc.  "Driver
independent"  also   means  that  your  demo  should  look  the  same,
regardless of the graphics mode (or resolution) used.

SuperGraphix uses  a .BGI  driver with a resolution from 320x200 up to
1024x768,  thus your demo must run on a wide variety of resolutions.

The beauty  of using standard (BGI) graphics functions is that someone
with an  CGA system  can write  a CGA demo for example, then take that
same source  code to a VGA machine,  compile and link it (with another
.BGI driver),   and run it in VGA mode.  Again, the reason for this is
that the  BGI functions  are  standard!  (i.e.  putpixel(),  circle(),
line(), clearviewport()  etc.)   Another reason  is because  most .BGI
graphics functions are "upward compatible".

For example:

setcolor(RED);
line(0,0,maxx,maxy);

will place diagonal red line,  starting at coordinate 0,0 to maxx,maxy
regardless of  the resolution  or BGI  used.   It doesn't matter which
system they are compiled on, as long as (at compile/link time) a valid
BGI driver is being used.

NOTE: To  say that  all BGI  functions will  work regardless,  is  not
completely correct.  There are graphics functions which will only work
with certain  drivers and  modes.   The function "setallpalette" is an
example (will work with VGA and EGA but not CGA).  In general however,
most functions  are common  to all  modes and  drivers.  Functions for
changing the  palette (which  are usually  graphic mode  specific) are
covered later.   Also covered later,  is a list of functions which are
recommended and not recommended due to incompatibility.

SuperGraphix uses  a non-standard  superVGA VESA  driver that does not
come with  Turbo C called SVGA256.BGI by Jordan Hargrave (you can look
for it  on GEnie  and CompuServe,  but again,   it is not necessary to
have a  superVGA driver  to create  a demo).   Look for the file title
SVGABGI.ZIP or SVGABGI4.ZIP.  You can also use "VGA256.BGI" (available
on many  BBSes, CompuServe  and GEnie)  for writing  256 color  demos.
VGA256.BGI is  contained in VGA256.ZIP or VGA256.ARC.  VGA256.BGI is a
320x200x256 color  driver only.   SVGABGI.BGI  supports 320x200  up to
1024x768x256 colors.

Your source  code/demo,   which you  will send,  will be combined with
SuperGraphix for all to see.  When the user selects your demo from the
"Select Demo"  menu,   a box  will pop  up with  your name  in it,  so
you'll receive all the credit for your demo.

SuperGraphix uses  a 256  color driver,   but you need not use all 256
colors in  your demo,   nor even use a 256 color driver to create your
demo. As  mentioned above,  you can use Turbo C's own graphics drivers
to create  your demo.  When OUR  superVGA  graphics  driver  (BGI)  is
initialized,   the first  16 colors (0 through 15) are set to standard
colors.   You can thus program your demo on a VGA or EGA system (using
only 16  colors).   The "New  York City"  demo is an example of a demo
that could  have been  written using  any BGI  driver,  including  the
standard VGAEGA.BGI which comes with Turbo C.


======================================================================

The following is a list of requirements and tips:

*   Your demo will be called from our main program.  When your demo is
complete,   you will send us your source code via disk (or upload) and
we will  append it  to the  end of our source code.  Your demo will be
involked from  the main  program. Therefore,   a  single function call
should start your demo.  Your function should be of type "void".

*  Use common graphics functions.  Examples of functions are:

putpixel();
getpixel();
setcolor();
circle();
line();
lineto();
setlinestyle();
drawpoly();
clearviewport();
cleardevice();
arc();
bar();
rectangle();
pieslice();
setrgbpalette();  /* In VGA256.BGI or SVGA256.BGI */

I have  not tested  the getimage();  and  putimage();  functions  with
SVGA256.BGI (the  driver used  with SuperGraphix),   so I cannot vouch
for them.  The following functions are not recommended:

setactivepage(); /* I don't think the SVGA modes have 2 pages anyway*/
setvisualpage();
setpalette();
setallpalette();
outtextxy();

To maintain  compatibility with  the wide  range of  video cards  that
SVGA256.BGI works  with,   please do  not use  any of  your own custom
functions with assembly code,  interrupts,  or direct screen writes.

*  When programming your demo,  keep your initgraph() and closegraph()
functions separate from your demo.  This will make it easier for me to
incorporate your  demo into  the main()  program.   One function  call
should start your demo.  Our source, combined with your code will look
like the following:


main()                     /* OUR MAIN PROGRAM!!!   */
{ a=getch();
  switch(a){
   case '1':
     initgraph(Gm,Gd,'');  /* OUR call to init graphics system */
     yourdemo();           /* CALL TO YOUR DEMO */
     closegraph();         /* OUR main program will closegraph() */
     break;
}

void yourdemo()            /* YOUR source code/demo */
{  int x,y;
   putpixel(x,y);          /* Send these functions only! */
} /* End Your Demo */


*   Your demo  should repeat until a key is pressed.  Do not handle or
remove the  character from  the keyboard  buffer.  Users will have the
option to  "rotate the  palette" should  they press  the "R" key.  The
main() will check to see which key is pressed.

*   I recommend  that  you  do  NOT  use  specific  (absolute)  screen
coordinates.   Your demo will be run on several different systems with
different resolutions (from 320x200 up to 1024x768).  Your demo should
look the  same regardless  of the resolution selected,  though this is
not always  necessary.  To help scale your demo,  two global variables
have been  defined:    maxx,  and  maxy  (both  type  int).      Since
coordinates 0,0  are common  to all graphics modes,  you may use them.
This should  be the  only exception however.  You can use these global
variables to "scale" your demo so that it looks the same regardless of
the resolution selected.

For example,   in  the "New York" demo,  I calculated a unit length as
follows:

L=maxx / 20;  /* L is 1/20th of the horizontal screen. */

L (for  length) can thus be used to draw an object which will look the
same,  regardless of the screen resolution selected.  For example:

circle(maxx/2,maxy/2,L);

will create  a circle  that will  look the  same,  regardless  of  the
resolution selected.   Remember  however that not all demos have to be
scaled.   Don't kill  yourself attempting  to get scale something that
will give the same effect unscaled.

*   Those wishing  to create  256 color  demos: I  recommend that  you
obtain VGA256.BGI (VGA256.ZIP) or SVGA256.BGI (SVGABGI4.ZIP) from your
local BBS,   GEnie  or CompuServe.   These are true 256 color drivers.
These  drivers   have  standard   BGI  functions   including   line();
putpixel(); setcolor(); circle(); clearviewport(); etc.

There are  three main  differences however  that allow  you to program
with 256 colors.

First,   the setcolor();  function can  take values  from 0 to 255 (in
contrast to  standard VGA  which can  only be  0 to 15).  As mentioned
above,   the first  16 of  the 256  colors (0-15)  are set to standard
colors to provide compatibility.

The second  difference in  256 color  programming is  the  putpixel();
function.   The putpixel()  function will  take values  from 0 through
255.  For example:

putpixel(0,0,255);

You may  ask yourself,   what is color number 255 anyway? This palette
entry can  be any  color you  wish it  to be  and is changed using the
third unique function.

The third unique function is called "setrgbpalette();".  This function
allows you to change the "palette" from its default.

A "palette"  is a  look up  table that tells the computer what color a
pixel is.   For  example, with the standard default palette,  color 15
is white.  If you called "setcolor(15);" and then "circle(10,10,10);",
a white  circle would  be displayed  centered  at  screen  coordinates
10,10.   The computer sort of "looks up" what color 15 is set to.  You
can change  the actual  color that  palette entry 15 is assigned to by
using the setrgbpalette() function.

For example:

setrgbpalette(15,63,0,0);

will change  palette entry  15 RED!  The general form of this function
is:

setrgbpalette(i,r,g,b);

where i  is the  palette entry,  and r,g,b are the red, green and blue
values for  that palette entry.  Each r,g,b value can be between 0 and
63. Note: Any subsequent call to setcolor(WHITE) will actually set the
color to red.  This is because "WHITE" is #DEFINEd as the number 15.

The following statement:

setrgbpalette(1,0,0,63);

changes palette  entry 1  to BLUE since the red and green value is set
to 0 and the blue value is set to 63 (its highest possible value).  If
you then used the following statements:

setcolor(1);
circle(10,10,10);


a blue  circle  would  be  placed  around  screen  coordinates  10,10!
Remember though,  that you do not want to use actual (absolute) screen
coordinates.

Changing the  palette creates  spectacular effects.  For example,  the
SuperBall demo is a simple function as follows:

void SuperBall()
{ int i,r,g,b;
  r=0;
  g=0;
  b=0;
  for(i=1;i<64;i++){         /* this loop will set palette entries */
     setrgbpalette(i,r,g,b); /* 1 through 63 */
     r=r+1;   /* an increasing r and b value makes magenta */
     g=g+1;
  }
  while(!kbhit()){
    x=random(maxx);    /* pick a random x,y */
    y=random(maxy);
    for(i=1;i<64;i++){ /* start at color 1 (dark magenta) and  */
       setcolor(i);    /* increase to 63 (light magenta). */
       circle(x,y,i);  /* close circles look like balls */
    }
  } /* end while */
}   /* end function */

This function  will put  magenta balls  on your screen.  Note that the
function only  uses 63  of the 256 palette entries.  256 color palette
demos  are   achieved  through   the  use   of  these   two  functions
(setrgbpalette(); and setcolor();).

Note:   Notice that setrgbpalette() will only set one palette entry at
a time.   Functions  do exist  that will  set the whole palette in one
shot, but these functions are not standard.  Remember that Borland, as
far as  I know,  does not  make a  256 color  driver,  therefore  this
function has  not been  standardized.   If  you  obtain  "VGA256.BGI",
source code  is included  to set the entire palette at once (contained
withing the  BGIDEMO.PAS file).  Look for the procedure "setdacblock".
"SVGA256.BGI" also  includes separate  source code which allows you to
set the  entire palette.  The function is called "setvgapalette256()".
Since these  functions are  not standard,  try not to use them in your
demo.   If you  must use these functions,  please contact the original
author listed at the end of this document.

In general,   the  "setrgbpalette()" function (which is common to both
VGA256.BGI AND  SVGA256.BGI) will  be fast  enough to  set  the  whole
palette prior  to your  demo.   If you  would like  to  "rotate"  your
palette (a process that requires the whole palette be set at once),  a
function written by the author will help you do so (described next).



After each  call to  initgraph(),   the palette  is set to its default
palette.   You may  write your  own code to change the palette to suit
your demo.   Two  functions written  by the  author, are available for
your use.  They are  setrainbowpal() and  setfourshadespal()  and  are
contained in the file PALETTE.C.

setrainbowpal() is  used in  the "Prism" demo. Palette entry 1 through
127 are  set to  the colors of a rainbow.  Starting with palette entry
1, the  colors slowly turn from red to yellow to green to cyan to blue
to magenta, and by palette entry 127, back to red. This function is of
type void. To call, just use:

setrainbowpal();

This function is particularly effective when used in demos such as:

setrainbowpal();      /* set palette */
for(i=1;i<128;i++){   /* set up loop */
  setcolor(i);        /* cycle up palette */
  DoSomthing();       /* put something on screen */
}

setfourshadespal() splits  the 256  colors into 4 shades of one color.
1-63 are  various shades  of magenta  (1  being  the  darkest  and  63
lightest), 64-127 are shades of green, 128-191 are shades of blue, and
finally 192-256  are shades of red.  setfourshadespal() is used in the
ribbon demo.

Included with  SuperGraphix is  the source code for setfourshadespal()
and setrainbowpal().   You must be in a 256 color graphics mode to use
these functions.

A function  is also available to "rotate" the palette.  The "Triangle"
demo makes  use of this function (among others).  The palette rotation
function available to you is as follows:


void rotatep(start,end);

where start  is the first (lowest in palette) color used in your demo,
and "end" is the last color used.  For example:

rotatep(1,128);

will rotate  palette entries  1 through  128.   You may call rotatep()
after the  completion of  the drawing  phase of  your demo.   See  the
"Triangle" demos to see how this looks as part of the demo.


* Be original! Please do not copy someone else's work.

* The producer (me) reserves the exclusive right to accept or reject a
demo.   In addition,  the producer reserves the right to change or add
to the demo or source code to give the demo the best possible look.

*   Finally,  don't worry about all the details!  Though I have listed
many tips  and "requirements",   if  you design  a working demo and it
looks good,  send it!  The original code for "Plasma" for example, was
actually programmed  in Pascal.   If  the demo is good,  I will gladly
rewrite and fine tune the code.

*   If you  have any questions,  or source code you wish to send,  you
can reach  the author in several ways.  Write:  Joseph W. Szarmach Jr.
2295 Nichols  Ave. Stratford,  CT 06497.   Via  GEnie: J.SZARMACH. Via
CompuServe 76436,3107.   Or  can reach me voice at: (203) 933-3633.  I
prefer source code via disk,  or private upload to GEnie (J.SZARMACH).

Don't  forget  to  include  your  number  or  address  (home  address,
CompuServe,  or GEnie address) in case I have any questions.
