
                                GLCB
                                ----

                  Graphic Library for 'C' Beginners
                  ----------------------------------

hum... first, i apologize for my bloody english...

The contents of glcbase sub-directory is public domain.
You can copy all the files of glcbase sub-directory.
You can re-use them in order to build freeware, shareware or commercial
products without paying back their authors.
The aim of this operation is to encourage people to build up a large
number of public domain software 100% compatible with other machines,
even if these software use a lot of graphics, sounds, animated graphics,
fast mouse and keyboard events handling (Software easy to compile as well).
The only restriction is that you are not allowed to modify the name and the
parameters of the functions in order to protect the compatibility.
But you may freely modify, improve, or translate the documentation.
You will surely need also to optimize your favorite basic module...

If you release a commercial product that uses glcbase, please release your
product for all the machines.
(non-compatible PC machines are in a real mess, so help them. thanks)

If you use basic modules and you find them very good for your own usage,
please write at least, one public domain program and upload it on your
favorite ftp archiver or send it to any public domain software swapper.


Introduction:
-------------

Did you ever wish to write quickly a small C program with some graphics
and, as well, be sure that your program will work fine on other machines?

The basic modules (written in 'C' language) were created to help beginners
to achieve this task. They supply a complete set of functions in order to
use graphics, sprites, sound, mouse and keyboard events handling.
There is also, random functions, real time clock function, and a double
screens display system: the visual screen and an invisible work screen.
Swapping the screens correctly (i.e: when spot is out of screen area)
will give you very clean animations. This method is called the
"double buffering".

Of course, in order to be compatible, we will sacrifice the performances
of the best machines... We will use only 2 screens of 320x200 pixels with
a 16 colors palette, and only one voice for digitized sounds. But sound will
be played during execution of your program (doesn't freeze your program),
the sprites are fast, the mouse and keyboard events are memorized.
(you do not need to check the value of mouse state to detect events)
Basic modules provide internal font, as well, for quick and easy use.

Here are the basic modules supplied in this distribution kit:
x11.c		Xwindows (X11R5) for workstation vms,unix,etc...
x11local.c	The same with a different display strategy.
mac.c		macintosh
atari.c		st,ste,falcon,tt (laser C)
ataripur.c	st,ste,falcon,tt (Pure C)
+ataripu2.s
falcon.c	falcon (Pure C)
+falcon2.s
falcontc.c	falcon (Pure C)
+falcont2.s
amiga500.c	amiga 500/2000 (aztec C)
amiga.c		amiga (all) (lattice C)
amiga.lha	amiga (all) (enhanced version, more compatible)
pc.c		pc (Windows 3.1 and MultiMedia lib) (BC++ or TC++)
pcvga.c		pc (MsDos and 256ko VGA card) (TC or TC++)
+pcvga2.asm

Some modules are improved and supply some new functions. For example pcvga.c
gives an extended palette option. These extensions should be used only in
the case of commercial products, or public domain pictures viewers.
For public domain programs, you must remain compatible with 16 colors!
You musn't believe that interest of a program depends on the number of
colors! You must improve the global interest! And a good compatibility
improves greatly the global interest! Many modules will be granted this
extension (pcvga,falcon,amiga20,maclc,x11,mint etc...).
In header.h you must declare EXTENSION in order to access these functions.
If you release some public domain program sources, please do not use any
extension, or otherwise, use some constant definition to enable classic
16 color module to work fine with the program. thanks.

These modules, of course, may be improved. But keep in mind that you musn't
modify name and parameters of the basic modules functions. If your machine
has no basic modules and you create it, or you improve an existing one,
i would appreciate that you put it into the glcbase sub-directory.
(It's difficult to be good on every machine... You can for example write
 a basic module for a more recent C compiler - ANSI - or fix a bug)

The basic modules supply only the machine dependent functions. If you want
more sophisticated functions (for example: enter a text or a number into
a screen area), you just have to write another module (but this one will
be 100% compatible with other machines, since it calls only basic modules
functions).

Note: If a pointer in your program is moving on a memory zone larger than
64Ko, you must declare it as follow (for our friends, the PCs):
char huge *ptr; (for example)
In order to preserve compatibility with other machines,
in header.h yo must write:
#define huge /**/


Basic modules functions set:
----------------------------

useful globals:
---------------

real time mouse coordinates: mousex and mousey
real time mouse buttons state: mousek
  bit 0: left button   bit 1: middle button (or right)
last mouse coordinates updated by getmouse(): msex and msey
last mouse buttons state updated by getmouse(): msek
  bit 0: left button   bit 1: middle button (or right)  bit 2: button released
extern int mousex,mousey,mousek;    (updated continuously)
extern int msex,msey,msek;          (updated by getmouse())

real time keyboard keys state: use ascii code as index
extern char keymap[256]; (updated continuously)

Caution: continuous updates are effective on MAC,X11 and PC(Windows),
  only if you call often getmouse() or buthit() for the mouse,
  and kbhit() for the keyboard (or keyhit() for both).


14 bits trigonometric tables (256=one turn):
--------------------------------------------

extern int *sn; (defined between 0 and 255)
extern int *cs; (defined between 0 and 255)
extern int *tg; (defined between -32 and +32)

system initialisation:
----------------------

To initialise many things, don't forget it at the beginning of main()
extern int initsystem(void);  returns a non zero value if successful
extern void killsystem(void);


16 colors palette management (gray scales emulation on B&W):
------------------------------------------------------------

Definition of special colors for sprite construction:
#define FOND 0x100
#define MASK 0x1ff

the default palette is (EGA) (but you can redefine it):

(insert these lines in your program, if you want to use EGA colors)
#define noir         0
#define bleu         1
#define vert         2
#define cyan         3
#define rouge        4
#define violet       5
#define kaki         6
#define gris_clair   7
#define gris         8
#define bleu_violet  9
#define vert_clair   10
#define cyan_clair   11
#define marron       12
#define violet_clair 13
#define jaune        14
#define blanc        15

To select the current color, to get or set the palette:
Each color is defined by a 16 bits value with the structure 0xgRGB,
where R,G and B are the red, green and blue components (between 0 and 15)
and g is the black and white pattern for monochrom screens (between 0 and 8).
(0 is full black, 8 is full white)

extern void setcolor(int c);
extern void getpalette(unsigned int *pal);
extern void setpalette(unsigned int *pal);


extended palette management (extension for pcvga,x11,falcon):
-------------------------------------------------------------

extern void setbigcolor(int n,unsigned int r,unsigned int v,unsigned int b);
extern void getbigcolor(int n,unsigned int *r,unsigned int *v,unsigned int *b);
extern void setbigpalette(int no,int nb,unsigned int *ptr);
extern void getbigpalette(int no,int nb,unsigned int *ptr);

These functions get or set one or several colors in the extended palette.
RGB components are value between 0 and 65535. A piece of palette is an
integer array where one color needs 3 integers.
VGA physical RGB components are value between 0 and 63, but a 16 bit value
is necessary for compatibility with Xwindows, falcon, mac LC and amiga 1200
16 bits RGB values.
DO NOT USE THESE FUNCTIONS FOR A PUBLIC DOMAIN SOFTWARE (thanks)



graphic screens management:
---------------------------

extern void simplescreen(void); to use only one screen: avoid this mode!
extern void doublescreen(void); a visual screen and an invisible work screen.
  This is the default mode. Double buffering animations is possible in this
  mode: you draw in the invisible work screen, then you swap both screens
  with the swap() function.

extern void cls(void);         erases work screen (color 0).
extern void copyscreen(void);  copies visual screen into work screen.
extern void refresh(void);     updates visual screen (simplescreen).
extern void swap(void);	       swaps both screens (doublescreen).


drawing basic functions:
------------------------

c is the color parameter (between 0 and 15, FOND or MASK)
If c = -1 then the previous color set by setcolor or any other drawing
function is still active.

lx and ly are width and height.

extern void pellipse(int x,int y,int lx,int ly,int c); filled ellipse
extern void pbox(int x,int y,int lx,int ly,int c);     filled rectangle
extern void plot(int x,int y,int c);                   draws a pixel
extern void vline(int x,int y,int y2,int c);           vertical line
extern void hline(int x,int y,int x2,int c);           horizontal line
extern void dline(int x1,int y1,int x2,int y2,int c);  line
extern void rline(int x1,int y1,int x2,int y2,int c);  thin line
extern void dbox(int x,int y,int lx,int ly,int c);     rectangle
extern void polyline(int n,int *tp,int c);             thin polygon
extern void polyfill(int n,int *tp,int c);             filled polygon
  tp is an integer array that contains the corners coordinates.
 (you must repeat the 1st point at the end of the list if you want
  to draw a closed shape)
  n is the number of integers (twice the number of corners (+2)).


memory managemant:
------------------

extern long ramfree(void);        returns free RAM size in byte.
extern void *memalloc(long size); returns pointer on allocated RAM buffer
  If an error occurs, returns a null pointer
extern void memfree(void **ptr);  frees the RAM buffer and clears the pointer.


memory copy:
------------

extern void bmove(void *src,void *dst,long len); intelligent bytes copy.


clock management:
-----------------

extern unsigned long systime(void);    returns clock in milliseconds.
extern void waitdelay(unsigned int n); waits for n millisecondes (max:1mn).

random functions:
-----------------

extern int randint(void);  returns integer between 0 and 32767.
extern int randval(int n); returns integer between 0 and n-1.


files management:
-----------------

Syntax for path names is the Unix syntax:
  rep1/rep2/file (separator "/")
Advise:
Do not use coma in directories names.
Do not use more than 8+3 caracters in file names.
Do relative pathname from the executable location.
Do not give a pathname from the root.

extern long bsize(char *nom); returns the file size in bytes.
extern int bexist(char *nom); returns non zero value if file exists
extern int bsave(char *nom,void *adr,long offset,long len);
  saves data in an existing file at any location (offset,length in bytes).
extern int bload(char *nom,void *adr,long offset,long len);
  loads data from a file at any location (offset,length in bytes).
extern int bmake(char *nom,void *adr,long len);
  creates or replaces a file and saves data (length in bytes).

extern int bopen(char *nom);   opens file for reading. returns an handle f.
extern int bread(int f,void *adr,long len);  reads data.
extern int bclose(int f);                    closes file.
extern int bcreate(char *nom); opens file for writing. returns an handle f.
extern int bwrite(int f,void *adr,long len); writes data.

Trilogy bopen,bread,bclose enables continuous reading.
Trilogy bcreate,bwrite,bclose enables continuous writing.

f is an handle:enables you to select a file without copying its name.
If there is no error then f > 0.

bsave,bload,bmake,bread,bwrite,bclose functions return 0 when there are
  no errors.

mouse and keyboard management:
------------------------------

extern void hide(void); hides mouse cursor (does nothing on MAC and X11)
extern void show(void); shows mouse cursor (does nothing on MAC and X11)
extern int getmouse(void); returns last mouse event (buttons state change)
  or 0 if event queue is empty. If an event has been read the globals
  msek,msex,msey,mclk are updated and give you the event information.
  (at least 32 events may be memorized)
  msek: bit 0 left button  bit 1: right button  bit 2: button released
  on MAC the right button is the TABULATION key.
  on X11 the right button is the middle button.

extern int buthit(void); returns zero value if mouse event queue is empty.
extern char getch(void); waits for a keyboard event and gives its ascii code.
extern int kbhit(void);  returns zero if keyboard event queue is empty.
extern int keyhit(void); returns zero if keyboard and mouse queues are empty.
extern void confirm(void); waits for a mouse event.
extern void empty(void); empties keyboard and mouse event queues.

You should use confirm() and getch() because these functions will enable
multi-tasking operating systems to give CPU time to other processes.

Arrow keys will give ascii codes of '^','<','>' and 'v'.
Are detected also: Escape (27), Return (13) and Backspace (8).
On X11 Escape may be emulated by top-left key tilda ('~').

sprites management:
-------------------

There are two kinds of graphics blocks: rectangular plain blocks and sprites
which are rectangular plan blocks with another rectangular block which gives
the borders of the sprite (a mask).
In order to use a graphic block you must declare a (void *) type variable
which is to be initialized with initbloc() and destroyed with freebloc().
(You may declare the type Bloc with 'typedef void *Bloc' to help yourself)

extern void initbloc(void **blocptr);            initializes the block

extern void getbloc(void **blocptr,int x,int y,int lx,int ly);
  After the block is drawn on the work screen, you must grab it with
  getbloc(). lx and ly are the width and the height. In order to draw the
  block, use the normal colors (0-15). If the block is to be a sprite, use
  the FOND color in the transparent areas.
  CAUTION: x and lx must always be multiples of 16!!!

extern void getmask(void **blocptr,int x,int y);
  After the plain block is grabbed, you can build a sprite if you grab the
  mask block. The plain block and the mask block must have the same width
  and height. The mask block must have been drawn with the FOND and MASK
  colors. MASK color must be used to draw the sprite body. These special
  colors are te be used only when you want to draw blocks in the invisible
  work screen. x must be a multiple of 16!!!

extern void copybloc(void **blocptrs,int xs,int ys,int lxs,int lys,
	void **blocptrd,int xd,int yd);   (s:source d:destination)
  copybloc copies a block part into another block part.
  (both blocks must have the same kind: two plain blocks or two sprites)
  CAUTION:xs,lxs and xd must always be multiples of 16!!!

extern void putbloc(void **blocptr,int x,int y); displays a block (or sprite).
(at any pixel location, if it overlaps above or below the screen limits it
 will be truncated, if it overlaps left or right the screen sides it won't
 be displayed at all)

extern void putpbloc(void **blocptr,int x,int y,int xs,int ys,int lxs,int lys);
  Displays a part of a block (or sprite).
  xs and lxs must be multiples of 16!!!

extern void freebloc(void **blocptr);              frees a block.


internal font management:
-------------------------

The internal font is just a little quick and easy use font.

Only ascii codes between 32 and 95 are correctly displayed.
Above 95 (low case) you display ascii code 64 and above characters (up case).
The characters 10 and 13 are correctly handled by printchar() and print().

These functions draw characters with the current color.
On MAC only B&W pattern 8 will give a high display speed. In order to
  do fast animations with text, you should create graphic blocks.

extern void affchar(int x,int y,char c);  displays a character at (x,y).
extern void afftext(int x,int y,char *s); displays a string at (x,y).
extern void printchar(char c);            displays a character.
extern void print(char *s);               displays a string, then LF.

With printchar() and print(), a display below the low screen limit will
   generate a vertical scrolling.


digitized sounds management:
----------------------------

The samples are an array of bytes which describes the sound waveform.
We have chosen the following convention:
  255  -> maximum level
  128  -> silent level
   0   -> minimum level

extern void fixsample(void *adr,long len);
  This convention is not universal on machines hardware. Before playing
  samples with playsample() you must call fixsample() and give him the
  address and length of the sample. The function will transform the
  waveform and adapt it to your machine hardware.

extern void playsample(void *adr,long len,long freq);
  Plays the sample in playback (execution is not frozen).
  If a sample was being played while you call this function, the new sample
  will replace the old one.

extern void stopsample(void); stops any sample playback.

Conclusion:
-----------

Thic documentation is short. It is rather an quick index than a real
documentation. Feel free to re-write it, or translate it.

Development of these modules took us many months...
But i think it was worthy, because beginners who don't want to learn how
to use sophisticated operating systems, because they just want to write
simple programs with few graphics, are now able to develop their algorithm
without losing time in reading tricky manuals...

We won't write newer versions of GLCbase. So, library is very strong and
reliable. You can be sure that functions will not change. Indeed, we are
all terminating our studies and we won't have any more time to spend in
improving GLCbase... It's now time to write programs!



GLCB team:
----------

ROY Gilles		Supelec (94)	(kakanoid)
BOERI franck		Supelec (95)	(blockout)
JOUIN Christophe	Supelec (94)	(x11,amiga)
ROY Regis		Supelec (95)	(atari)
LAMONOCA Guillaume	Supelec (94)

For any question:

Guillaume LAMONOCA
7 allee lucien Mazan
13500 Martigues
FRANCE

(bal GL on some french transpac servers (minitel))

