				-= Jarod a/k/a/ the Pretender =-
			       (very incomplete) Reference Manual
				        Version 001006
				           Mic, 2000


Requirements:
~~~~~~~~~~~~~
Under DOS nothing special is required except a video card that is compatible with the
VESA standard (>=1.2), although a couple of modes can be set directly through VGA. These
modes are 320*200*256, 256*256*256 and 256*240*256.
Under Windows you'll need DirectX if you want to use fullscreen mode and/or the sound-
features. DirectX 3 or higher should be sufficient. [ An application wich runs in windowed
mode and doesn't use any sound features should run even if DirectX isn't installed (like
on WinNT 4 or less without any service packs (?)). ]
(the stuff written inside []'s isn't true in this release)




Program structure:
~~~~~~~~~~~~~~~~~~
A typical Jarod application could look something like this:

<CODE BEGINS>

 function init()
   Do something
   ...
   if something went wrong
     return 1
   end if
   return 0
 end function

 function display()
   if user wants to quit
     return 1
   end if
   Do something
   ...
   return 0
 end function
 
 function clean_up()
   Free all resources
   ...
   return 0
 end function

 Main(init_id, main_id, exit_id)

<CODE ENDS>

init_id, main_id and exit_id symbolizes the routine_id():s of init(), display() and
clean_up() respectively. init_id and exit_id are optional (pass -1 to make Main() ignore them)
while main_is is required. Main() basically does the following:

 if init_id != -1 
   call init_id
 end if

 if init_id didn't return 1
   until main_id returns 1
     call main_id
   repeat
 end if
 
 if exit_id != -1 
   call exit_id
 end if




Global variables & constants:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

CURRENT_MODE_WIDTH	\
CURRENT_MODE_HEIGHT	 - These are set by SetColorDepth()/GraphicsMode().
CURRENT_MODE_DEPTH	/

BPP16IS15		You can try setting this variable to true (1) if you're having
			problems with weird-looking colors when using 16-bit modes.
			I should probably add some sort of GetPixelFormat()-thingy, but
			that'll be a future project...
 

Routines:
~~~~~~~~~
 Graphics:
 ~~~~~~~~~

 integer SetColorDepth(integer depth)
  Set the desired color depth. This only affects the library routines, you must
  call GraphicsMode() to actually change the display settings.
  Valid depths are 8, 15, 16 and 24. The default color depth (before SetColorDepth() is
  called for the first time) is 8.
  Returns 0 on success, otherwise 1.


 integer GraphicsMode(object mode)
  Set the desired graphics mode.
  mode can be either a sequence on the form {width, height) or 0. If mode is 0, the
  "default" graphics mode will be set.
  Returns 0 on success, otherwise 1.


 sequence LoadBitmap(sequence filename)
  Load a Windows bitmap (DIB) into memory.
  The returned sequence looks like this:
   {
    atom pointer,
    integer width,
    integer height,
    integer bitcount,
    integer errorcode,
    object palette
   }
  If errorcode!=0 then something went wrong and the bitmap shouldn't be used.
  The palette member will be a [256][3]-sequence if bitcount=8, otherwise it'll be set
  to 0.
  You can use the following enumerators to access the members of a bitmap:
   POINTER, WIDTH, HEIGHT, BITCOUNT, ERRORCODE, PALETTE


 sequence CreateBitmap(integer width,integer height,integer clear)
  Create a bitmap.
  width and height speaks for themselves.
  if clear!=0 then the bitmap will be cleared on creation (using color 0).
  The BITCOUNT-member of the created bitmap will be the same as CURRENT_MODE_DEPTH.
  The PALETTE-member will always be set to 0 !
 

 Blit(sequence xy,sequence source,sequence dest,integer method)
  Copy a chunk of memory from one place to another.
  xy is the destination origin ({x,y}).
  source is the source-bitmap.
  dest is the destination-bitmap.
  method is a bitmask wich specifies how pixels should be copied. You can add multiple
  methods together to form more complex methods.
  The following methods are available:
    SOURCECOPY		Copy all pixels from source to dest without any modification.

    NOTNULLCOPY		Only copy pixels that have a value >0. Note that the pixel-
			value will be tested *before* any other effects (masking, mixing
			etc.) are applied.			

    ANDCOPY		Performs a bitwise AND between the source & destination pixels.

    ORCOPY		Perfroms a bitwise OR between the source & destination pixels.

    XORCOPY		Performs a bitwise XOR between the source & destination pixels.

    MIXCOPY		Performs a 50/50 blend between the source & destination pixels.
			This is reasonably fast in 15- & 16-bit modes.

    TRANSCOPY		Performs a A/255-A blend between the source & destination pixels
 			(where A is the alpha-value specified with SetMixColor()).
			Needless to say, this method is slow (just look at jTest08.ex(w)).
  
    LITCOPY		Tints each source pixel before writing it to dest (simple RGB-
			addition). The color of the light is specified with SetMixColor().
			This method is faster than TRANSCOPY, but it's still slow.

    STRETCHCOPY		This method will stretch (or squeeze) the source bitmap to fit
			into the "rectangle" specified with SetStretchSize().
			NOTE: STRETCHCOPY doesn't clip images correctly at the moment.
 	
    HFLIP		Horizontal flip. Works only in combination with
			SOURCECOPY+NOCLIPCOPY, and not in 24-bit modes.

    VFLIP		Vertical flip. Works only in combination with
			SOURCECOPY+NOCLIPCOPY, and not in 24-bit modes.


    NOCLIPCOPY		Don't clip the source bitmap. This makes blitting a teeny, weeny
  			bit faster but you have to make sure that the source bitmap will
			fit onto the destination bitmap or you might get memory curruptions.

 Not all combination of methods are avaiable yet. Methods that doesn't exist are typically
 mapped to SOURCECOPY (with a few exceptions).
 NOTE: The source bitmap must have a pitch (actual # of bytes per row) wich is a multiple
       of four when in windowed mode and the destination bitmap is VIDEO.
 TIP: Use MIXCOPY instead of TRANSCOPY whenever possible.
   

 Pixel(sequence xy,integer c,sequence bitmap)
  Plot a pixel at xy on bitmap using color c.
  xy are the co-ordinates of the pixel ({x,y}).
  c is a direct color-value (or a palette index when in 256-color mode). (See table below)
  bitmap is a bitmap as created by CreateBitmap() or LoadBitmap().

   Depth: | Max. value:
   --------------------
     8    |   255		
     15   |   32727	(15-> 0RRRRRGG GGGBBBBB <-0)
     16   |   65535	(15-> RRRRRGGG GGGBBBBB <-0)
     24   |   16777215	(23-> RRRRRRRR GGGGGGGG BBBBBBBB <-0)


 Line(sequence coords,integer c,sequence bitmap)
  Draw a line between the co-ordinates coords on bitmap using color c.
  coords is a sequence of the two co-ordinates that should be connected ({{x1,y1},{x2,y2}}).
  The order of the co-ordinates in coords doesn't matter.
  c is the same type of color-value used with Pixel().


 Circle(sequence center,integer r,integer c,sequence bitmap)
  Draw a circle with radius r centered at center on bitmap using color c.
  center is the center (!) of the circle, not the top-left corner or whatnot.
  r is the radius (integers only!).
  Circle() uses Bresenham's method with a desicion-variable to avoid floating-point 
  calculations, wich makes it pretty fast in theory. But, Circle() (just like Line()) uses
  Pixel() to plot each pixel (except when drawing filled circles). And since Pixel() is
  slow, Circle() is slow..



 Input:
 ~~~~~~

 UpdateInput()
  Updates the input-data.


 integer GetKey()
  If a key is pressed, its scancode is retured, otherwise -1 is returned. See jaroddos.e/
  tinydinput.ew for a list of key enumerators.


 integer KeyDown(integer scancode)
  If key #scancode is down, 1 is returned, otherwise 0 is returned.
  

 Misc.:
 ~~~~~~

 sequence PATH(sequence s)
  When under DOS/Windows it replaces all /'s in s with \'s. It does the opposite under
  Linux.

 Message(sequence title,sequence message)
  Displays a message using either message_box() or puts() depending on the underlying OS.
  Message() should only be used before a graphics mode has been set, or after a 
  GraphicsMode(0)-call.


  

   
   




