The Allegro Wiki is migrating to github at https://github.com/liballeg/allegro_wiki/wiki
This page should answer frequently and not-so-frequently asked questions regarding the Allegro 5 API, geared towards those not fully familiar with it.
This section is laid out as an interview, and should be read in order. Questions will eventually be moved above. Lines in this section are signed CGamesPlay 20:06, October 11, 2008 (MDT) unless otherwise stated.
Where is the appropriate to discuss API changes? We could use an issue tracker to track API issues, rather than bugs, if one is set up. We could use the wiki, but the project leads would need to check it regularly, and the Wiki format tends to be disorganized. Allegro.cc is another venue for discussion. IRC is not really appropriate because of limited availability.
pw - [AD]
What parts of the API are subject to change, and what parts are not? What parts are planned by one or two specific people, but aren't fully coded?
pw - For me, the main parts to look at are kcm_audio and the fshook/path API which has just been merged. The graphics, event, input, timer subsystems are pretty much fixed, but minor changes are still acceptable. Unicode/string handling needs an overhaul.
This page says, "only those functions that are fundamental operations or absolutely required to allow an addon library will become part of the core library." Obviously, a "fundamental operation" is any function that is required to fulfill the primary goals of Allegro. What are the primary goals of Allegro?
- I think the primary goal is what the people who work on it want to use it for. In my case that is mainly a cross-platform way to get an OpenGL context, input, sound, loading of png, ogg, ttf - and all together in one package and with a nice and consistent API. (Except for the latter I could of course already use A4, SDL, glfw or whatever else, so it's an important point.) --Elias 03:02, October 12, 2008 (MDT)
In my opinion, one of the primary goals of Allegro is to ease the process of game creation. With every addon, this process becomes more difficult. Presently, in order to load a graphic, display text, and play a sound, the user must link in five additional libraries. The user also needs to distribute five additional DLLs, in addition to the DLLs required for the individual file formats. Why is the loading of a bitmap from disk a not a "fundamental operation"?
- Assuming the five libraries are libpng, zlib, freetype, vorbis, sndfile - I don't see any way around it, unless we want to re-write them. (For sndfile that actually is planned.) However, we will have binary releases, so all the user needs to do is download it and use it, without installing any extra libraries. So it shouldn't be difficult. For using the source version of A5, we likely can do something similar - have a .zip (or installer) with all the mingw/msvc libraries and headers (in linux it already is only a matter of a single apt-get, OSX I don't know). All the above libraries also likely could be static linked, if the actual number of files is the problem.. --Elias 03:02, October 12, 2008 (MDT)
Presently, the line between the addons and the core library is very blurry, with parts spilling between them. The following few questions pertain to where the line lies. Will the al_iio_load function make it into the core? I think that the register_bitmap_filetype API from the old API is superior to requiring each codec pack to provide its own loading function.
- I think al_iio_load could be renamed to al_load_bitmap in the core - the only difference would be that a new bitmap type addon would not have to depend on iio (which to me wouldn't seem like a problem either). And al_iio_add_handler is about the same as as register_bitmap_filetype already from what I can see. --Elias 03:02, October 12, 2008 (MDT)
Will kcm_audio be moved into the core?
pw - Probably not. Not because it has no place there but because (so far) it happens to work well as an addon. Moreover, many people with more sophisticated needs would probably swap out kcm_audio for another audio library.
Once the packfile API is written, will it be moved into the core? It doesn't make much sense to have a packfile addon be distributed with Allegro if the other addons--or the core itself--can't even use it.
The packfile api won't be changed in any significant way, and will end up as an addon so people that depend on it can still use it. It will hook into the fshook api to provide an alternate to the built in stdio driver. All current packfile behaviors and formats shouldn't be changed, so it should be 100% compatible with a4's packfiles. DATAFILEs however are a different story, a5 has no palettes, so palette objects and 8bit bitmap objects may be difficult to translate. -- Tomasu
- I'd even say it should be a sub-addon of the "compatibility" addon (one we have that). The only use of it would be for porting A4 games - we should discourage use for new games. --Elias 03:02, October 12, 2008 (MDT)
- I'd be fine with a converter written in A4 which transforms a datafile into something that A5 can read :) Not much different forom the A4 dat utility. --Milan Mimica 09:25, October 12, 2008 (MDT)
Similarly, will the VFS API be moved into the core?
pw - isn't this already done? or is there another API floating around?
Tomasu - Just barely done. I think CGames is just a little behind the curve.
Will text rendering be moved into the core?
pw - Works fine as it is. I can't see any reason to.
Finally, which parts of the core library will be moved into addons? Consider features like the joystick, keyboard, and mouse subsystems, or even the event and display subsystems.
pw - all of the above stay in the core.
Any other comments about the addons?
milan - I would say that primary goal of addons is to force internal library modularity. I like it how addons use very few internal functions from A5 core lib which makes them independent and easier to maintain.
- I agree. Also, ideally it will become really easy to create external addons that way. My idea is that they will be able to somehow be dropped into a "contrib" folder or something, and then the A5 build could automatically pick them up. So addon authors won't have to deal with writing their own builds (compare to A4 where every single addon had their own broken build procedure). --Elias 03:03, October 12, 2008 (MDT)
Referring to Question 2, the five additional libraries I was referring to are a5_font, a5_iio, kcm_audio, a5_acodec, and allegro. Those are in addition to the external required libs: libpng, zlib, freetype, vorbis, sndfile. There have been numerous threads on Allegro.cc for newbies simply trying to link in Allegro. Now, the "Hello, World" Allegro program will require a user to link in Allegro, a5_font, and freetype. To load a bitmap, the user has to link an another library. To make matters worse, the addons depend on Allegro, external libraries, and other addons. This means that the order of the link lines has to be well-defined. This is a nightmare for a beginning coder who has no idea what a link phase is. Why is this not an important attribute for Allegro to consider?
Answer: Feel free to make a binary Windows download with a single a5.dll and a5.lib. Then someone who wants to use A5 only has to place the include/allegro5 folder, and link against a single library, and distribute a single DLL (or with a5-static.lib even only a single .exe). I personally don't have Windows so I can't do anything about it anyway, but besides that, I think it should be done (but keep the option to use one DLL per addon). In linux, I actually think we should go the other way and go back to run-time loading, like with the A4 modules. --Elias 07:23, October 12, 2008 (MDT)
I dunno, the modules idea was so allegro internal drivers could be dynamically loaded. They were essentially plugins. dynamic loading of plugins is easy, dynamic loading of an entire lib is not. -- Tomasu
At this point, the typical use case for Allegro is going to require three or four addons to be used. Shouldn't addons be for the atypical use case? What if some of the "addons" became part of the core during the link phase only? They would be compiled separately, using only Allegro public headers, and following whatever goals the developers have laid down for addons, but would be linked into the main Allegro library, which eliminates the problem of link-level dependencies and inter-addon dependency. Specifically, I am referring to the kcm_audio addon, the non-file-format portions of the a5_iio addon, and the non-file-format portions of the a5_font addon. Allegro's core will still be modular, but the user doesn't need to care how beautiful and clean the core is, he just needs a working library. Allegro's core library still needs to be able to load a minimal number of file formats (tga, pcm, wav), but the advanced formats (png, ogg ttf) can be moved away. Users with more advanced needs can simply not use the modules that are linked into the core.
I think Milan's and my answer to question 9 already said so - the real reason for the addons folder is internal modularity (and that it stopped the constant arguments what should be an addon and what core). It's up to build-maintainers/packagers to figure out the best distribution method - but I certainly would not be against an option to include multiple addons into one DLL/.so/static library (but also keep the option to have them separate). --Elias 07:26, October 12, 2008 (MDT)