-*- outline -*-

Bigloo is "a practical Scheme compiler".  Allegro is a practical game
and multimedia programming library.  One meets the other, and you get
Bigloo-Allegro.

Well, you would, if it wasn't incomplete and abandoned.  I've decided
to work on Allegro 5, so I'm releasing this as-is.

Hopefully, Bigloo and Allegro will meet again some day, in another
form.

--pw 2002-11-28


The rest are some notes I wrote during development, and a piece of
text that would have been a nice advertisement.

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

* Notes

- Being C functions, most Allegro functions return nothing.
Therefore, if you write:

	(if some-condition
	    (draw-sprite ...))

Bigloo would complain because it is expecting a value out of the `if'
construct.  To get around this, you just need to return a value, e.g.

	(cond (some-condition
	       (draw-sprite ...)
               'void))

Yes, it's annoying but not too bad.


* To do

- how come GFX-SAFE selects a fullscreen mode instead of windowed?


* Object finalisation

The work on this has started, but isn't finished and needs testing.
Some things:

- objects created by Allegro need to be registered for finalisation,
  e.g. bitmaps, samples, etc.

- loaders/creators have to be wrapped in alloogro.scm so that the
  objects they return receive finalisation registration

- destroyers have to be wrapped so that they remove any finalisation
  procs before freeing (else if the finalizer kicks in later, it will
  have nothing to finalize and probably cause some random and hard to
  debug crashes)

- objects created by bigloo, e.g. PALETTEs, don't need finalization
  registration


* File map

For future reference...

- Most of Allegro's public symbols are written down in an [mostly]
  implementation-unspecific format (ALLEGRO.DEFS).

- Using a Scheme program (PARSE-DEFS.SCM) we translate from the
  implementation-unspecific format into Bigloo's FFI language
  (ALLOOGRO1.SCH).

- We also need some support code, in C (ALLOOGRO-AUX.C) and rather
  more in Scheme (ALLOOGRO.SCM).

- User-generated programs need to know what library to link against,
  etc.  This is written down in ALLOOGRO.INIT.  Macros are also
  written in there, because macros can't be exported.

- Bigloo libraries also need a ``_heap_ that describes the locations
  of the library'' (ALLOOGRO.HEAP).  This is generated with the help
  of MAKE-LIB.SCM.


* Propaganda

Scripting is old hat.  Everyone knows why it's good to have
scriptibility in programs, yada yada yada...  I'll just clarify that
by "scripts", I mean code that is not explicitly compiled.  It may or
may not be code written by the user.

The majority of scriptable programs come in two flavours:

(i) The application written in a low-level language, compiled to
    native code, and scripts written in some _other_, high-level
    language.

(ii) The application written in the same high-level, interpreted
     language as the scripts.  Access to OS or hardware features are
     done via some support code written in a low-level, compiled
     language.

The advantage of the first approach is that the application is in
native code and runs faster.  However, it requires "glue" code between
the application and the interpreter.  This is labour on the part of
the application writer (footnote: automatic generation is never good
enough).  A second problem is that data crossing the boundary between
the application and scripts is necessarily of the lowest common
denominator.  Data types are often restricted to strings, numbers, a
few structures, etc.

The second approach favours more flexibility, in that there is less of
a mismatch between the application and its interpreted scripts.  Since
the application and scripts are both in the same language (and running
in the same environment), they can pass around higher-order data type,
such as first-class procedures.

Clearly, the second approach is better.  However, it may be
impractical because the application is now interpreted and may be too
slow.


What about a third possibility, where the application code is compiled
to native code, but is written in the same _high-level_ language as
the scripts that will get interpreted?  Then there is no "language
mismatch" and no glue code necessary between the two pieces.  Access
to OS and hardware features is done via C code, which still requires
glue.

This is what bigloo-allegro allows.  You can write your game (or
whatever) in compiled Scheme, and at the same time write scripts in
interpreted Scheme.  Bigloo-Allegro binds Allegro to compiled Scheme,
which you can reexport to interpreted code if you wish.

I think moving the glue code down to level is much better.  During
development application code can change rapidly, and so any glue that
exists needs to be updated often.  On the other hand, ready-made
libraries (such as Allegro) change interfaces rarely, so the glue code
does not have to be updated so often.  And as the glue is written at a
low level, the problem of the "least common denominator" is less
likely to get in your way.

Besides, the gluing has already been done for you.


(Future possibility: you could develop your application in the bigloo
interpreter (faster development cycle).  When it is time to release,
you can compile it.  You can't do this just yet.)


* On fixed point numbers

I've had to pretty much keep fixed point number support to a bare
minimum.  The problem is that Bigloo integers are only 30-or-so bits
wide, whereas a `fixed' requires 32 bits.  To store a fixed point
number properly requires boxing (AFAIK), and that isn't practical for
a number type.

Reals are the "default" in bigloo-allegro.  That means the floating
point variants of the 3d math routines do not have the "_f" suffix and
angles are in *radians* (they should be automatically converted to the
"binary angle" system used by Allegro).


* Sections in the manual

I try to follow this order where applicable to keep things organised.

 General
 Unicode routines
 Configuration routines
 Mouse routines
 Timer routines
 Keyboard routines
 Joystick routines
 Graphics modes
 Bitmap objects
 Loading image files
 Palette routines
 Truecolor pixel formats
 Drawing primitives
 Blitting and sprites
 RLE sprites
 Compiled sprites
 Text output
 Polygon rendering
 Transparency and patterned drawing
 Converting between color formats
 Direct access to video memory
 FLIC routines
 Sound init routines
 Digital sample routines
 MIDI music routines
 Audio stream routines
 Recording routines
 File and compression routines
 Datafile routines
 Fixed point math routines
 3D math routines
 Quaternion math routines
 GUI routines