Re: [AD] Documentation about new API

[Elias Pschernig <elias@xxxxxxxxxx>]

On Wed, 2007-12-19 at 17:32 +0100, Guillermo Martínez Jiménez wrote:
> Hello everybody.
> 
> Evert suggested me to join this list so here I am.
> 
> I worked in a wrapper for Pascal (allegro-pas.sourdeforge.net).
> Current version is mostly stable and I'm thinking start working in
> next version (4.9/5.0). I did download the 4.3 and the 4.9.2RC1 and
> look at the examples and documentation and I don't agree with some
> things about the new API, but before to discuss it I decided to ask
> you about documents or messages where you decided how the new API will
> be, which platforms and drivers will be supported and why you decided
> that. I looked for it in the list but I can't find it. Can you help me
> to find this documents (if they exists)? Once I read that
> documentation I'll decide what I'll do.
> 

After the last IRC meeting we decided sort of that we lack developer
capabilities for the 4.3 branch (we still want it I guess, but it just
has low priority) - so best to look at 4.9 only. And only the examples
with exnew_ are relevant, the rest is just the 4.2 examples which we
left in there (for easier merging I think).

Anyway, feel free to start discussion, we will be happy to point out why
things where done in specific way if there was a good reason - or if
they were just randomly done the way they are.

E.g. for the display API, we did look at several other APIs - but in the
end a lot more research could have been done if there were mode devs,
and the main idea was to make it map in a sane way onto underlying
OpenGL and Direct3D implementations and make things as simple and
obvious to use as possible for users (so e.g. each thread has a current
ALLEGRO_DISPLAY, which makes programs using a single window as simple as
the A4 API - when using multiple windows, an alternate API might have
been passing an ALLEGRO_DISPLAY pointer to each and every function
instead - but since multiple windows likely are rarly used, the
per-thread ALLEGRO_DISPLAY was chosen).

About documents.. different things were decided at different times, many
years ago there was a mailing list for A5 development, but both initial
attempts at actually implementing it failed and the list shut down.
Later we decided to do things more step by step, which resulted in a
version where the new events based input and timers was combined with
the old version, and the A4 API was still completely working on top of
that. Only recently we also added a new system/display/graphics
interface.

If you keep in mind that some things there are outdated, the wiki has
some info, e.g.:
http://wiki.allegro.cc/Allegro_roadmap
http://wiki.allegro.cc/NewAPI

Some parts of the implemented design are based on the results of the
mentioned initial A5 attempts and discussions on the A5 list (those only
serve as loose reference though, e.g. in the gfx API we found problems
with the proposal there, when trying to map it to OpenGL and Direct3D in
a good way):
http://wiki.allegro.cc/NewAPI/Documents
and
http://alleg.sourceforge.net/future/info.html
At least why we have the current naming scheme is really well
explained :)

Some ideas about the display API are here:
http://wiki.allegro.cc/NewAPI/Display
And the current API docs generated from SVN, showing that it changed a
bit from that:
http://www.liballeg.org/naturaldocs/files/display_new-c.html

Also, for some time now we've been hold monthly developer meetings in
#allegro-dev on irc.freenode.net, here's links to transcripts, which may
partly explain some things:
http://wiki.allegro.cc/Allegro_Hack_Day

I guess the IRC channel also is the reason why this list got rather
quiet, easier to just discuss things in #allegro and implement instead
of going through slow and lengthy discussions here. Especially as the
amount of people doing work on A5 is extremely small right now.


But again, you can just ask here even without reading any of that
stuff :)

-- 
Elias Pschernig <elias@xxxxxxxxxx>