HTTPS clone URL
Subversion checkout URL
Ruby MRI bindings to the Allegro5 game library. Not complete, but already somewhat usable. Further development on hold until Allegro 5's speed becomes comparable to SDL 1.2
Fetching latest commit…
Cannot retrieve the latest commit at this time
|Failed to load latest commit information.|
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 firstname.lastname@example.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.