Ralleg5. Ruby bindings to the Allegro 5 game library.  
=====================================================

Introduction
------------
These will be Ruby MRI Bindings to allegro5., using the Ruby C API. 
I won't use FFI since speed is of essence for game libraries. Currently, 
this project is on hold since for my my test on my older weaksauce PC,
is Allegro5 is about half as slow under Linux than SDL is, even though 
it should be  hardware accellerated. 

For example, for drawing a one layer tilemap of 32x32 tiles on a 640x480 screen:
SDL 1.2   : Delta, fps: 5.013000, 199.481348
Allegro 5 : Delta, fps: 11.727150, 85.272210
Hopefully this will be fixed somehow...



Prerequisites 
-------------
Ruby: MRI 1.9.x. Others untested. 
For compiling: allegro-5.0.0, and it's dependencies.
For testing: watchr, autowatchr. Nanotest has been vendored.
For documentation generation: YARD.

Installation
------------

cd ext/ralleg5
ruby ./extconf.rb
make 
make install


APIs
----
There are two API's: a lowlevel one and a highlevel one. Normally, most people
who are familiar with Ruby will want to use the high level API. But for those
more familiar with C or with Allegro, the low level API may be atttractive. 

For both API's, I have only wrapped functionality which is either not already 
available in Ruby, or needed to use Allegro in Ruby. So, for example 
ALLEGRO_USTR has only very simple wrappers, and no functionality in Al::Ustr,
since Ruby 1.9.x already does UTF-8 and other encodings fine. 
 
The high level api is currently undocumented, but can be seen in the tests.
It should become documented with Yard over time.

The lowlevel api is in the module Al::Low, which follows the C API and closely.
 
An important remark is that, garbage collection is *disabled* for all objects 
generated by the low level API. You will have to call al_destroy_xxx manually 
on the generated objects to clear up the memory used, and keep track of their 
references as to prevent leaking them.  For example, if you call al_create_mixer 
to get a Mixer object, you have to call al_destroy_mixer to free the associated
memory. After doing this, do not use the dangling referece anymore, it will 
crash Allegro and Ruby with it. It's reccomended to set it to nil. 

In the lowlevel API, function names and constant names are exactly the same 
as those in the C api. For example:
 
 require 'ralleg5.so'
 include Al::Low
 al_init
 al_install_audio
 ...

The function signature is mostly the same as in c, as are the results, but there
are some exceptions involving pointers. In case primitives are returned by 
reference, the function does not take those by reference, but returns an array 
of them in stead, in the same order of the C function call. In case these 
primitives are also passed in, the parameter list remainst he same, but the 
result is still returned as an array.
  
So for example in C, al_get_text_dimensions has the parameter list 
(const ALLEGRO_FONT *f, char const *text, int *bbx, int *bby, int *bbw, int *bbh)
This becomes al_get_text_dimensions(f, text) in Ruby, but it returns an array 
like this: [bbx, bby, bbw, bbh]. But al_transform_coordinates with parameters 
(const ALLEGRO_TRANSFORM* trans, float* x, float* y) becomes 
al_transform_coordinates(trans, x, y) and returns an array [x, y].

The return values of are numally similar to those in C. However, since in Ruby, 
there are no void functions, and to enable method chaining, void functions in 
the C API will return self in the low level Ruby API. Also, booleans or integers 
used as booleans in the C API will become real booleans in the Ruby API. C NULLs
will be replaced by nil in Ruby. Nil is also often returned on errors.  

The names of the Ruby classes that wrap the Allegro structs have been changed 
from all uppercase to camel case with the ALLEGRO_ prefix and any _ removed. 
So ALLEGRO_BITMAP becomes Al:Bitmap, ALLEGRO_SAMPLE_ID becomes A::SampleId, etc. 
This is to avoid redundancy between the lowlevel and highlevel API, and to allow 
high level functionality to be defined for these Ruby classes. 

Even for the low level API, these classses may have some accessors defined to 
simulate similar behaviour with the the C struct's members that are publicly
accessible in Allegro.

For C structs ALLEGRO_XXX that Allegro does not have an al_create_xxx or 
al_destroy_xxx for, I still provide these functions, as to keep the low 
level API usable. 

The low level API is not documented in detail apart from here, because the C 
documentation of Allegro describes it well: http://www.allegro.cc/manual/5/ 
Please look there to learn more about it.  

It also does not have any unit tests yet, because the lowlevel bindings are 
quite straightforward. 



License:
--------

Copyright (c) 2011 beoran@rubyforge.org

This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.

Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:

    1. The origin of this software must not be misrepresented; you must not
    claim that you wrote the original software. If you use this software
    in a product, an acknowledgment in the product documentation would be
    appreciated but is not required.

    2. Altered source versions must be plainly marked as such, and must not be
    misrepresented as being the original software.

    3. This notice may not be removed or altered from any source
    distribution.