Allegro.cc - Online Community

Allegro.cc Forums » Allegro Development » allegro 4.2 api on Tomasu's wiki

This thread is locked; no one can reply to it. rss feed Print
 1   2 
allegro 4.2 api on Tomasu's wiki
Elias
Member #358
May 2000

I'll not be here for 3 weeks - but I recently put some ideas about some minor changes for the 4.2 API on Tomasu's Wiki.

As I understand it, in 4.2 we want to be compatible with the current Allegro as much as possible, but just remove some of the worst inconsistencies in the API, along with prefixing it. In the long run (4.4, 4.6, 4.8...) we should get a quite nice API. The time in actual time, and not in version numbers, will depend on if we have developers of course (we decided on AD we don't have enough developers for a complete new API like A5 - AllegroPro (should I say Korval's lib?) will be there for that and hopefully we can mutually share some ideas for the driver implementations at some point..).

Not really sure a wiki is a good place for API discussions, since the changes will have to be discussed on [AD] anyway before going to CVS.. but since Tomasu's wiki looks quite empty except some code snippets, I thought I could put it there: http://awiki.strangesoft.net?AllegroAPIDesign

--
"Either help out or stop whining" - Evert

Evert
Member #794
November 2000
avatar

I'm not sure we should go for a prefixed api in 4.2.
The reason being that I'd personally like to get 4.2 out relatively soon and prefixing the whole API is something that takes time.

The main reason I'm eager to get 4.2 out soon is that currently, there is no officially stable Allegro version that supports MacOS X, and I think it is very important that one be available as soon as possible.
Ultimately, that's Angelo's call though.

Not that the version number matters that much anyway. If we clean up the TODO list and release the result as 4.2 and then start refitting the API for 4.3 or clean up the TODO list and start refitting the API while still in 4.1 doesn't really matter as far as time is concerned. It's not like development is a discrete process, jumping from version number to version number. ;)

Elias
Member #358
May 2000

Yes, I agree. Version numbers are nothing. But for a stable release like 4.2.0, we should do some extended testing, like, have a freeze period of 2 or 3 weeks or so, and only do testing and bugfixing. Probably should have release candidates like for 4.0.0. I'm actually also wanting to have it out soon, maybe as Christmas present :) (That would be about 5 months.. maybe can even do it sooner.)

And we'll need to decide what to do about 4_0_branch at some point.

--
"Either help out or stop whining" - Evert

Evert
Member #794
November 2000
avatar

There's a number of bugfixes that could be backported to the 4.0 branch. It's up to Eric when 4.0.4 goes out though. Unless major bugfixes are needed after that, I suppose we can more or less forget about 4_0_branch once 4.2 comes out.

And I agree that we could aim for a christmas release of 4.2... I think we should try to have a regular flow of WIP releases going in the mean time though.

A J
Member #3,025
December 2002
avatar

1. yes, a regular flow of WIPs is a good idea.

2. a christian holiday that has less and less meaning to most of the planet has zero to do with allegro, lets not align development with psuedo-religious festivals.

3. i think the pre-fixing is a long overdue thing, and the dropping of ex() etc, but all that for 4.2 seems like too soon. i think 4.2 should be the last nice stable release of the current API, that attempts to replace both the 4.0 branch and the 4.1._ WIP branch.

as soon as 4.2 is final and released, the next day we should do a major overhaul, and prefix at the same time, a few core developpers and a handful of 1/2 wits like myself, should get most of it done in a week.

idea: everyone with broadband should install a VOIP app, and the whole thing can get done in days not weeks!

___________________________
The more you talk, the more AJ is right. - ML

Elias
Member #358
May 2000

Quote:

2. a christian holiday that has less and less meaning to most of the planet has zero to do with allegro, lets not align development with psuedo-religious festivals.

Well, I didn't use this with any religious meaning. It's just a standard saying in English (even though I'm not a native speaker, I'm quite sure of that). And it won't influence the release date.

--
"Either help out or stop whining" - Evert

Thomas Fjellstrom
Member #476
June 2000
avatar

AJ, its just a day... It only has meaning if you asign it meaning. For me, its when I get to see my extended family. And eat lost of good food, and candy. So, its all good. Oh, not to mention giving a little happyness to lovedones, and recieving some in return.

--
Thomas Fjellstrom - [website] - [email] - [Allegro Wiki] - [Allegro TODO]
"If you can't think of a better solution, don't try to make a better solution." -- weapon_S
"The less evidence we have for what we believe is certain, the more violently we defend beliefs against those who don't agree" -- https://twitter.com/neiltyson/status/592870205409353730

Kitty Cat
Member #2,815
October 2002
avatar

Okay, I don't really see a note like this anywhere, nor can remember any responses to me saying this before, but please let me say agian:

Prefixing the entire API at once is a very bad idea.

The reason is obvious.. do it right the first time around. Once we create al_play_sample/al_set_gfx_mode, or whatever, that's it. We won't be able to recreate them without resorting to things like al_play_sample_ex and the like. Prefixed functions/typedefs should start after 4.2 is released, and be incremental. Some functions will have prefixed/improved counterparts by 4.4, more by 4.6, etc. There's no reason we have to have the entire API prefixed before having the redesigned API.

--
"Do not meddle in the affairs of cats, for they are subtle and will pee on your computer." -- Bruce Graham

Chris Katko
Member #1,881
January 2002
avatar

(I very rarely use this expression but: )
O.M.G.

Your actually going to convert the functions in groups as opposed to a whole? So that every time someone gets a new version, they have to go back over their functions and replace them with the prefixed versions? Everytime you release a new version...?

I think I'm going to be sick...

-----sig:
“Programs should be written for people to read, and only incidentally for machines to execute.” - Structure and Interpretation of Computer Programs
"Political Correctness is fascism disguised as manners" --George Carlin

Thomas Fjellstrom
Member #476
June 2000
avatar

Quote:

I think I'm going to be sick...

Its going to stay backwards compatable. You can just keep the old functions in there.

--
Thomas Fjellstrom - [website] - [email] - [Allegro Wiki] - [Allegro TODO]
"If you can't think of a better solution, don't try to make a better solution." -- weapon_S
"The less evidence we have for what we believe is certain, the more violently we defend beliefs against those who don't agree" -- https://twitter.com/neiltyson/status/592870205409353730

Chris Katko
Member #1,881
January 2002
avatar

Then your not using the "strict" version of Allegro. And can you imagine functions with allegro al_ next to other allegro functions without them? ::hits the floor (along with Allegro's code readibility)::

And I assume all new functions with have that prefix. So if you don't convert it, and you want to use a new function, you have the same problem I listed above. ::jams pencil in left-eye::

-----sig:
“Programs should be written for people to read, and only incidentally for machines to execute.” - Structure and Interpretation of Computer Programs
"Political Correctness is fascism disguised as manners" --George Carlin

Thomas Fjellstrom
Member #476
June 2000
avatar

I have a feeling that the redability problems will only happen if you use WIPs. IF not you wont have any of the prefixed api.. I'd say the prefixing, if not done between now and 4.2, should be done between 4.3(WIP) and 4.4.

But I could be wrong. 2 years is enough time to get the prefixing done :)

--
Thomas Fjellstrom - [website] - [email] - [Allegro Wiki] - [Allegro TODO]
"If you can't think of a better solution, don't try to make a better solution." -- weapon_S
"The less evidence we have for what we believe is certain, the more violently we defend beliefs against those who don't agree" -- https://twitter.com/neiltyson/status/592870205409353730

Rash
Member #2,374
May 2002
avatar

Shawn warned STRENUOUSLY against casually breaking backwards compatibility. Here's the section about it in its entirety:

Shawn Hargreaves said:

Breaking Backwards Compatibility

Well, it looks like this is going to happen. I don't think I would have done it if I'd still been in charge, but this isn't my call any more, and there are some strong arguments for doing it. Please be aware that this is a very dangerous thing to do, though. If I had to list a handful of reasons why Allegro has been a success, excellent compatibility across versions would be right up there with the best of them. Sure, this has caused a lot of uglinesses in both the API and the implementation, and pissed a lot of people off, and required me to be a totally unflexible stubborn anal retentive dictator for several years, but it is also a major reason why so many thousands of people are using Allegro today.

The trick is how to introduce a compatibility break without losing too many of those users.

  • Get it right the first time. Change things once, and most people will probably be happy to update there programs. Change things again, and they will be annoyed. Change once more, and most of them will probably leave. This means that you only have one chance to do this, so make sure you do it properly. Get rid of everything bad, and keep everything good. Plan it out in excruciating detail before anyone starts implementing. Work on the assumption that the 5.0 demo game will still be expected to compile and run flawlessly on the 2006 version of Allegro, so anything you are likely to want to change over the next half a decade, better do it now. I reckon one API breakage every five years is about right...

  • Design the API in such a way that new features and platforms can be added in a graceful manner, so that it can continue to grow without requiring another compatibility breakage. Examples: scroll_screen() is a bad API for page flipping (makes too big an assumption about how underlying hardware is working), whereas create_video_bitmap() / show_video_bitmap() is a good one (can be implemented on all sorts of weird hardware, as it maps directly onto what the program is trying to do rather than onto how the hardware is actually doing it).

  • Once you release the new API, go right back to being just as anal as I ever was about not breaking it any more. Don't let this degenerate into the first step towards compatibility chaos. Even if it risks upsetting people and making yourself unpopular, don't be afraid to say "no" (see above section about the need for a few clear leaders who will be able to do this).

  • Make it as easy as possible for people to upgrade existing Allegro programs to the new API. Automated scripts or a compatibility wrapper might go some way towards this, but also risk just postponing the moment when people do need to change their code, and limiting the sort of changes that are possible. I think a better strategy would be to make every change in such a way that code written to the old API will not compile using the new one (ie. remove functions, or add functions, or change the number of parameters to a function, but never just change the meaning of a parameter or the underlying semantics of what the function does, as this would still allow old code to compile but it would then fail to do what the programmer is expecting). If you follow this rule, every single API change will then produce a different compiler error when a program tries to use the old API. From this, it is a small step to generate a document listing all those errors, and how to fix them (this file could be generated by listing all the errors that are found while converting the tests and examples across to the new API). This way people would have to manually update their code, but it would be a fairly simple cycle of "compile / look up error / do what help file says about it / repeat until no more errors".

[url http://alleg.sourceforge.net/future/shawns_thoughts.txt]

Thomas Fjellstrom
Member #476
June 2000
avatar

I don't think anyone's going to be ignoring that.

--
Thomas Fjellstrom - [website] - [email] - [Allegro Wiki] - [Allegro TODO]
"If you can't think of a better solution, don't try to make a better solution." -- weapon_S
"The less evidence we have for what we believe is certain, the more violently we defend beliefs against those who don't agree" -- https://twitter.com/neiltyson/status/592870205409353730

Kitty Cat
Member #2,815
October 2002
avatar

We will only be breaking compatibility once.. which is why we shouldn't rush in and prefix everything at once. We should only prefix what will be a part of the "new API". I'd also recommend against deprecating the old API functions when the new API replacements come up.. at least to not use the GCC deprecation flag (and generate so many warnings for compiling old programs).

--
"Do not meddle in the affairs of cats, for they are subtle and will pee on your computer." -- Bruce Graham

Peter Wang
Member #23
April 2000

I think Kitty Cat's idea might work, but it needs to be documented extremely well to get the point across to users, in bold, red, blinking text no less. The first time he said it on [AD] I didn't understand what he meant by breaking compatibility "only once".

Making sure I understand: If we followed Kitty Cat's way, then I think our timeline would work something like this. In each stable release (4.4, 4.6, 4.8) more and more sections of the API are redesigned. These will be lexically differentiated from the older API because of their "al_" prefixes. The newly introduced parts of the API will have the same API compatibility guarantees as the older API (i.e. stuff from 4.4 will exist in 4.6). At the same time, the parts of the older API which have been superceded will still be available. It is completely up to the user when and if he should update his programs to use the newer API. That bold text is the most important point to get across. If users don't see it, they will complain, and they will be pissed off, and we will get a bad rap.

At some stage, the entirety of the older API will have been replaced or updated. If a user prefers to upgrade his programs only once, he can wait until that time. If he prefers to not upgrade his programs at all, he can keep using the compatibility layer -- after all, if we decide that compatibility is to be retained throughout, it will not be any extra work for us to keep that compatibilty layer around (at least, initially).

The only problem is, how much compatibility can we retain? For really drastic changes, it may prove to be impossible. In that case, we are constrained by the past in what designs we can have for the future. I don't think that's entirely a bad thing, though. It prevents us from going too far over the edge.

BTW, I'd be happier if we moved this discussion to [AD].

Korval
Member #1,538
September 2001
avatar

Quote:

The only problem is, how much compatibility can we retain? For really drastic changes, it may prove to be impossible. In that case, we are constrained by the past in what designs we can have for the future. I don't think that's entirely a bad thing, though. It prevents us from going too far over the edge.

Well, it all depends on what "too far over the edge" entails.

Limiting yourself to an API that has already proven itself to not be able to conform to the modern way of handling things (graphics, in particular) is just silly. It is not only that, it is counterproductive to advancing an API.

One of the reasons why Shawn's suggestion for a sudden change in API is a good one is so that the new API is not constrained by the bounds of the old one. To do so only invites creating the same problems that required a new API to begin with.

It has been said that Allegro abstracts hardware into a DOS box. Some of that may be still useable, and some of it isn't. But creating an abstraction into a mutant DOS box, a mere modification of a DOS box rather than a modern 2D game API, is just wrongheaded, and doesn't solve Allegro's problems.

Quote:

BTW, I'd be happier if we moved this discussion to [AD].

This is, basically, the only significant discussion that the mainline Allegro developers have had with the actual Allegro users. Why are you so quick to move this to the ML, rather than discussing it openly?

Thomas Fjellstrom
Member #476
June 2000
avatar

Developement is done on the List. you want to help? go there. :) simple as that.

--
Thomas Fjellstrom - [website] - [email] - [Allegro Wiki] - [Allegro TODO]
"If you can't think of a better solution, don't try to make a better solution." -- weapon_S
"The less evidence we have for what we believe is certain, the more violently we defend beliefs against those who don't agree" -- https://twitter.com/neiltyson/status/592870205409353730

Kitty Cat
Member #2,815
October 2002
avatar

And, not all developers read these forums. Someone really should post weekly updates here of what's been happening on the mailing list again. That way, those that don't read the mailing list can still have some input.

Peter: That is exactly right. As for how much compatiblity we can keep this way.. I don't know. But it seems to be a better solution than to do a completely rewrite (re: Allegro 5) or to prefix everything and create/change the "new functions" as we see fit, until the new API is complete.

Quote:

the new API is not constrained by the bounds of the old one

Nor is Allegro's new API going to be constrained by the old one. Since the new API will be prefixed with al_, there's no risk of function clashes, and if needs be, we can have: allegro/src/old_funcs (as a last case scenario for those pesky functions that just won't fit otherwise).

--
"Do not meddle in the affairs of cats, for they are subtle and will pee on your computer." -- Bruce Graham

Peter Wang
Member #23
April 2000

f*ck, I spent 20 min writing a reply in firefox, then promptly lost it all when I hit "Add Reply". Another reason email is better.

Anyway, the important part was in response to Kitty Cat: I have a feeling that a lot of things are possible given a background thread (e.g. emulating the a4 input API on top of the event-based input API which was slated for a5). This does tend to rule out DOS support, though, which I am personally willing to forsake. If we decide that, then we must say that the backward compatibility does not mean that all currently-supported OSes will remain supported. Actually, we should say that anyway. Slippery slope and all that, though.

Evert
Member #794
November 2000
avatar

Quote:

So that every time someone gets a new version, they have to go back over their functions and replace them with the prefixed versions? Everytime you release a new version...?

Stable releases will be backward compatible. If you're using WIP releases, then that's a risk you're taking.

But yeah, as Peter said: this needs to be documented very well.
Once a new API is available under the hood of the old one, (and the new one by no means needs to be constrained to DOS), then we can either decide wether we break the API for good, or we can just tell users to use the new header file and ignore the old API.
At any rate, a new API would need to be tested in action prior to official release anyway. As far as I know, the plan used to be to test the redesgined "Allegro 5" API on top of current Allegrlo to see how it would work.

Quote:

Someone really should post weekly updates here of what's been happening on the mailing list again. That way, those that don't read the mailing list can still have some input.

I used to do that for a while a (long) time a go. Writing actual summaries of discussion may be a little too much some of the time, but I guess I could post the changelog...

Quote:

This is, basically, the only significant discussion that the mainline Allegro developers have had with the actual Allegro users. Why are you so quick to move this to the ML, rather than discussing it openly?

Nothing has been said that hasn't been said in previous threads already. Actual design threads on a forum like this tend to end in endless silly arguments where everyone has an opinion and everyone disagrees. There's just too much random noice. At least on a mailing list, people have to take more trouble to make a reply, forcing them to think more.
Beside which, as somone already said somewhere, Allegro development is a dictatorship, not a democracy.

Thomas Fjellstrom
Member #476
June 2000
avatar

Quote:

Allegro development is a dictatorship, not a democracy.

As can be noted elsewhere, democracy really doesn't work all that well.

--
Thomas Fjellstrom - [website] - [email] - [Allegro Wiki] - [Allegro TODO]
"If you can't think of a better solution, don't try to make a better solution." -- weapon_S
"The less evidence we have for what we believe is certain, the more violently we defend beliefs against those who don't agree" -- https://twitter.com/neiltyson/status/592870205409353730

Peter Wang
Member #23
April 2000

[Please, guys, keep the noise levels down.]

Quote:

I'd also recommend against deprecating the old API functions when the new API replacements come up.. at least to not use the GCC deprecation flag (and generate so many warnings for compiling old programs).

We won't need or use the deprecation flag if the new API is declared in a new header file. Either that, or the new API takes over allegro.h and the old API goes elsewhere. I prefer the former.

Also, the GTK+ and other folks have started a convention that headers go like /usr/include/gtk-2.0/gtk/gtk.h on Unix. This is a good convention I feel we should follow, as it allows you to install incompatible versions of the same library in parallel). It might be feasible for 4.2, even (I know Vincent has been advocating it for a while). Replies to 4.2 stuff => [AD].

Kitty Cat
Member #2,815
October 2002
avatar

I don't quite like that idea, though. Perhaps something like <allegro/allegro.h>, but we couldn't use <allegro-4.2/allegro.h> because that would implicitly break compatibility with 4.0, 4.1, 4.3, 4.4, etc..

Quote:

We won't need or use the deprecation flag if the new API is declared in a new header file.

The deprecation flag has nothing to do with what header the function is declared in, AFAIK. I just don't like the prospect that, by completing a new sound API, for instance, that every old sound function would produce a deprecation warning. Taking this a bit farther, one could argue that the deprecation flag shouldn't be used at all, since if a project uses -Werror it will fail to compile.. which is breaking compatiblity with older versions.

--
"Do not meddle in the affairs of cats, for they are subtle and will pee on your computer." -- Bruce Graham

Thomas Fjellstrom
Member #476
June 2000
avatar

Quote:

but we couldn't use <allegro-4.2/allegro.h> because that would implicitly break compatibility with 4.0, 4.1, 4.3, 4.4, etc..

Gtk's include gets added to the include path, as does Qts. (my qt is in usr/qt/3*)

--
Thomas Fjellstrom - [website] - [email] - [Allegro Wiki] - [Allegro TODO]
"If you can't think of a better solution, don't try to make a better solution." -- weapon_S
"The less evidence we have for what we believe is certain, the more violently we defend beliefs against those who don't agree" -- https://twitter.com/neiltyson/status/592870205409353730

 1   2 


Go to: