$Id: API,v 1.4 2000/11/26 00:44:28 perdig Exp $

Someday I will have documented the entire XRally API... the following is my
sketch of what should have become the new graphics API. Hopefully that's what
will be implemented, but I advice you to take a look at the headers files as
well... :)

--------- XRally Graphics API -----------------------------------------------

The Graphics API is made of 4 files:

  - graphics.c
  - graphics.h
	
  The main graphics stuff. To use the basic graphics functions, you just need
  to #include graphics.h and link to graphics.c

  - effects.c
  - effects.h

  The special effects stuff. To use it, you just need to #include effects.h
  and link to effects.c and graphics.c

  You can see examples of the graphics API in action on:

  - menu.c

    The main menu interface

  - game.c

    The game graphics.

---* Basic Graphics API *----------------------------------------------------

*** Drawing functions


void blit(Pixmap src, Drawable dest, int x, int y, int w, int h)

  Draw the specified src Pixmap on the dest Pixmap, on the specified location
  and size. It should use the XFillRectangle functions, and the tileGC. It
  doesn't use masks (so it should set a none ClipMask)!

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

void m_blit(Pixmap srcPix, Pixmap srcMask, Drawable dest, int x, int y, int w, 
						int h)

  Draw the specified srcPix Pixmap on the dest Drawable, using srcMask as 
  Mask, on the specified location and size. It also should use the 
  XFillRectanlge functions, and the tileGC.

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

void i_blit(XImage *src, Drawable dest, int x, int y, int w, int h)

  Draw the specified src image on the dest Drawable. It should use 
  XPutImage and the tileGC.

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

void rect(Drawable dest, int x, int y, int w, int h, ulong color_index, 
					int filled)

  Draw a rectangle of the specified color_index, filled or not, on the dest 
  Drawable. It should use XDrawRectangle (or XFillRectangle) and the solidGC.

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

void point(Drawable dest, int x, int y, ulong color_index)

  Draw a point of the specified color_index on the dest Drawable. It should 
  use XDrawPoint and the solidGC.

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

void text(Drawable dest, int x, int y, const char *text_string, 
					ulong color_index, int font)

  Draw text_string on the dest Drawable, of the color_index color. The font 
  integer should be a index to the XFontStruct *ft[a] array. The text can 
  contain \n, that will result on the text after it being draw height() pixels 
  lower. (Like the current ltext function). Uses the textGC.

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

void circle(Drawable dest, int x, int y, int w, int h, ulong color_index, 
						int filled) 

  Draw a circle on dest, pretty much like rect. (will use Xlib's arc 
  functions, but - at first - should only draw a circle. If there is need to 
  draw a arc, then we will add it)

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

*** Image manipulation


XImage *get_image(Pixmap src, int x, int y, int w, int h)
	
  Returns the specified image

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

#define get_pixel(src, x, y) XGetPixel(src, x, y)
#define put_pixel(src, x, y, pixel) XPutPixel(src, x, y, pixel)

  Gets (or Puts) the specified pixel on a XImage*.

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

*** Color manipulation


long get_color(const char *color_string)

  Returns the color index for color_string on the default colormap.

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

void alloc_color(XColor *color);

  Will run XAllocColor() on the specified color

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

void query_color(XColor *color);

  Will run XQueryColor() on the specified color

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

*** Infrastructure functions


int init_display()

  Init's the display and creates the buffers and GCs. Returns where it had
  success or not.

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

void resize_window(int width, int height)

  Resize's the current window and it's buffers, to width x height.

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

void load_pixmap(Pixmap *pix, Pixmap *mask, const char *filename, int *width, 
                 int *height)

  Loads the "filename" pixmap and mask, and store it on the pix and mask 
  variables.  The width and height variables will return the size
  of the pixmap. 

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

Pixmap create_pixmap(int width, int height)

  Creates a Pixmap of specified width and height.

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

void graphics_sync()

  Updates the display, using the double buffer and XSync

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

void close_display()

  Closes the display and finishes the graphics stuff.

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

*** Misc functions


Pixmap dbuffer()

  Returns the double buffer (no need to declare it extern)

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

KeySym check_key()

  If there is a KeyPress event on the queue, then returns the pressed key.
  If there isn't, returns XK_VoidSymbol. If there is a Exposure event on the
  queue, then updates the display (but still returns false if there isn't any 
  KeyPress one).

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

KeySym wait_key()

  Similar to check_key, but will wait until there is a KeyPress event. If 
  there are any Exposure events, it will update the display but will continue 
  waiting.

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

KeySym wait_char(char *char_return)

  Waits until the user presses a key. It will return the KeySym the user
  pressed, and char_return will return which char is it. char_return must be a
  char array of at least 3 characters. (For a example of how it works, see
  getName() on menu.c)

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

void wait_time(long time)

  Waits for the specified amount of time, in microseconds (1000000 microseconds
  = 1 sec). While it is waiting, updates the window when exposed and cleans the
  event queue.

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

int text_width(char *txt, int font)

  Returns the width of the text. It *doesn't* support complex text (with '\n')
  For that, use text_rectangle!

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

int text_height(int font)

  Returns the height of the font. It *doesn't* support complex text (with '\n')
  For that, use text_rectangle!

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

void text_rectangle(char *txt, int font, int *w, int *h)

  Returns the bounding rectangle of the specified text. It can contain \n 
  and stuff, that it will still work.

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

