That's not quite in the same context Thomas.

Thomas F. was discussing posts in general (in reference to your subtle post comment), whereas I was referring to the use of suggestions in the Allegro Development.

If you have personal problems with each other, take it in private. No one ever needs to display a negative attitude toward anyone who is either working on Allegro or making suggestions. There's also no reason to continually moan about the same issues over and over. Any posts from here on that have any off topic content will simply be deleted.

It's fine if a thread naturally evolves into a slightly different topic, but it never needs to degenerate into name calling and personal attacks. As a general rule of thumb, if your post contains negative vibes, then rephrase it until it no longer does. If anyone needs clarification then PM me, so that the discussion may continue without further interruption.

I must have missed that thread, could you explain how it might be done? Macro trickery? Or seperate trees for each platform? (more efficient, but means alot more maintenence work I assume).

I'm confused how you would otherwise provide one single api accross many platforms, and "targets" (where a "target" is something like the HPET timer, or a setitimer based method, or X11 vs. fbcon vs. svgalib vs. SDL for graphics "targets", on linux)

The conversation will have been years ago, probably when Allegro 5 was still an active rewrite. I believe the thrust was a layered API. So, for example in the current implementation of graphics, a very low level API might exist with a version of set_gfx_mode, a function for creating bitmaps with a parameter for type (e.g. memory, video, system), functions to lock and unlock bitmaps and to obtain read/write pointers for different lines in the bitmap. If the platform can provide a better than C blit then that function is written and a #define that disables the pure-C one is added to the platforms include file. And so on.

I did not mean to imply that the use of vtables was for platform independence, merely that at present it "intrudes" on platform independence in the sense that someone who wants to target a new platform needs to adjust existing vtables sitting in the existing code whereas with a clean API separation there is a realistic prospect of a new port to a new platform without any editing of existing code, other than to one file to make sure your platform dependent header is included, dictating which of the pure-C implementations of things are not required because the new code duplicates them in a more platform specific manner.

Of course, this simple design does complicate things for addon-libraries because by default only one version of every platform access function is defined. But AllegroGL itself must be relying on platform specific code in any area where it would need to modify the internal Allegro platform specific code so this isn't a problem. As for Glyph Keeper, I am curious why this would want anything to do with the vtables, especially given that it supports both Allegro and SDL.

When I asked "Is there any official line on the use of vtables in implementing the new API" I was not limiting the question to the timer. However I found the timer proposal a good example of something that doesn't need vtables and in addition it is certainly something that was already the focus of this thread.

It isn't any more ugly than the existing Allegro header file look. Function declarations in that look like this:

AL_FUNC(char *, fix_filename_case, (char *path));

It is already a requirement that all functions be declared in header files using an Allegro-specific macro. I don't see how using a different macro that also sets a define disabling a pure C implementation of something looks any different whatsoever.

By the "DOS or Windows port" you presumably mean the DOS and Windows specific code? I wasn't talking about them, I used "existing code" to include both platform specific and platform neutral sections. But if you have misunderstood then I have more so and my statement was based on an incorrect reading of the source code. As you've already said that vtables are not a problem if documented I wish to make no further comments on that.

Please keep in mind that I asked if there was a policy and have not tried to advocate either way or the other, merely explain my original comment that "vtables are unnecessary". I trust the Allegro developers have grasped the key point, made already in this thread by Stephen Apostolopoulos and agreed by Elias, that any act that requires a user to wade into the way the previous Allegro developers decided to do something when attempting to extend or adjust the library is becomes less likely to happen the deeper they have to wade.

If you accept that vtables are not necessary, as has been discussed to date, then the question should probably rightly be what is easiest for a newcomer to wade into? If the easiest solution doesn't add undue overhead to the work of anyone who knows what they are doing then why should it not be accepted?

That something providing platform dependent code does not require a platform neutral way to do so.

I am not arguing against vtables in total. You'll note I simply ask if there is a policy then highlight the topic of the meeting point between platform neutral and platform specific code. That's the only fault line I mean to discuss.

The underlying point is an obvious one, that in a large multifaceted project, turning as much as possible into individual black boxes which function as independently as possible while providing meaningful hooks where appropriate is desirable in order to promote easy code maintenance in a project that expects or would like a reasonable stream of new developers.

True, but nevertheless, the visible difference would be zero as a result. Anyway, I don't suppose for a moment that this was your main objection.

I don't see how there is complication. At a guess, you believe that the result would be that something equivalent to the current library wide system of multiple would simply devolve to the platform specific level and end up being reimplemented adhoc for every new target?

In that case, and answering the rest of your message noting that the answer to my earlier question seems to be that the decision is to keep vtables, could a system of functions for adding to the vtable be implemented? So, for example, the following might be meaningful code:

int _al_init_platform(void)
{
_al_add_driver(); /* at this point an additional driver vtable is created and filled with sufficient placeholder functions that Allegro will now function, albeit without producing any output or accepting any input */

_al_set_driver_vtable(premade_vtable); /* most existing drivers probably do this a few times then end - communicates a premade vtable directly to Allegro */

_al_add_driver();
_al_set_driver_name("GFX_MYVIDEODRIVER"); /* the name of the driver associated with the newest vtable is now "GFX_MYVIDEODRIVER" - I'm assuming that video driver names are no longer preprocessor constants in the new API */
_al_set_driver_func(AL_SET_GFX_FUNC, my_set_gfx_function); /* replace the set_gfx_mode type function with my_set_gfx_function */
_al_finish_driver();
}

Besides anything else, function access to driver internals would make addons like AllegroGL cleaner, and would take most of the scariness out of people coming to the source.

Anyway, on a different topic, I've been looking at the API proposals and have a comment.

The contents of AL_EVENT_SOURCE seem to be undocumented, if not undecided. May I request that AL_EVENT_SOURCE is documented and the addition of new event sources be made an explicit part of the public API? May I also request that whatever form the structure takes it be explicitly made to allow for sources that may require polling?

The intention was just to pass one of the existing vtable structs to the magical internal Allegro program, so that existing drivers can be very quickly adapted. A function for copying an existing driver would obviously also be highly desirable. Presumably such a copying function would also need to be able to accept GFX_AUTODETECT, etc, in order to properly hide specific driver names as much as possible from users.

What would be the line on making these functions a documented part of the public API? That would make things even nicer for developing new drivers or modifying new ones. In the example already discussed, supposing I wanted to try and write a function that used the DirectX Blt instead of Allegro's stretch_blit, I would not need to open the library sources or at any point look at them, I could simply put something similar to the following into my main function:

al_driver_duplicate_from(GFX_AUTODETECT); /* as _al_add_driver before, but copies an existing vtable to create a new one */
al_driver_set_function(AL_STRETCH_BLIT_FUNC, my_new_attempt_at_stretch_blit);

Then try and interface my personal function my_new_attempt_at_stretch_blit with whatever way the AL_BITMAP internals store the DirectX surface. Once it works I could even post it in that form and someone who knows the internals could probably add it to the core distribution in about 2 minutes.

On the pure api side, there is probably no need for an al_driver_duplicate_from and an al_add_driver (or whatever correct form these functions should have to fit with Allegro naming conventions) if a GFX_NULL style driver is a default part of the source. Although it would be useless for most, it would probably add 1/2kb to library size if that and would help with development for those with no interest in the other library internals a lot.

True, that would also work. The advantage of the method using driver ID's is that you (probably) don't need to recompile an addon if you want to use it with a newer version of Allegro where the vtable has changed. Not crucial, perhaps, but it is nice as a courtesy: we can also muck around with vtables without breaking ABI compatibility for addons and programmes that use the vtable API.

And yes, those functions and vtables would have to be documented. Not nescessarily as part of the normal user API, but as part of a sortof Allegro Addon-wRiter's Guide (the AARG).

See this I like.

I know you didn't mean me, but at the moment, I can't see a more explicit way thats as flexible and efficient as the current method.

Basically AL_EVENT_SOURCE is made up of the AL_EVENT_HEADER items, and whatever else you wish to add. AL_EVENT is a convinence union making up the standard sources and a bare AL_EVENT_HEADER item for allowing access to any of the standard HEADER items (at least thats what I gleaned after glancing at the events.h header, yes docs need made )

Now, onto me. If you have any ideas for the vfs, I'm all ears

edit:
p.s. Ok, I started that mail list to forum gateway thing a while back, if anyone at all is interested enough in it, you must let me know. Otherwise I might just keep putting it off

We seem to be talking at crossed purposes! All I know about event source is the stuff contained in the API proposal which says nearly nothing, other than that they exist and that you can restrict the messages they can produce on a source by source basis. I can see no mention of AL_EVENT_HEADER anywhere in the API proposals, so I have no idea what it involves.

My basic requests if they are not already implemented is that it be possible for the user to create their own sources in a clean and documented fashion that is an official and stable part of the API and that the facility be incorporated to support event sources that work in a polling fashion. From what you're saying, I guess some as yet undocumented work not based on a formally published proposal rests in CVS?

My main concerns remain the same as they have always been, that the Allegro source by remaining monolithic and largely undocumented has become increasingly impenetrable to people who would like to add to or improve the library. Meanwhile those that can follow the thing contribute overwhelmingly just the things they would want to use themselves (to paraphrase Peter Wang) rather than based on any real world surveying of the userbase. You'll notice that my comments and API suggestions tend to focus on exposing internals sufficiently that the library can be modified without having to read anyone else's code.

With that in mind I have very little to say about VFS proposals because they will do little or nothing to add confusion to the main body of the code, and while they are likely in some form to provide a leg that the library stands on, I can't see that they will actually use anything from the library in the way that a software bitmap stretcher will have to reach back into the library to use the raw pixel access stuff.

Nevertheless, let me recap what you proposed as you left things very slightly implicit. As I understand it, there may be multiple VFSs open at once, the user instantiates a VFS from a resource (e.g. a folder on their hard drive) and then obtains VFS_STREAMs from it, which are similar to FILE *s, albeit probably without the weirdness of fread/fwrite. Presumably whatever standard file format supporting code is included in the base library, it will be capable of reading from VFS_STREAMs.

A further modification allows an existing VFS to be augmented with information from other resources at specified mount points. The design uses a filter system such that information to/from any source may be filtered (e.g. zlib as you suggest, presumably any cipher could be applied).

I have no modifications, although the question of what should be in the base library and what should be an addon is worth addressing. As you have commented, an addon won't work as a standalone and would need to leave something in the main library or the other file functions in the main library would be unable to use the virtual file systems.

Can I suggest that VFS selection be modal? The idea would be that the only way Allegro knows to read files would be via VFS_STREAMs. Functions such as al_load_bmp(name) would use name to obtain a VFS_STREAM from the currently selected VFS. When Allegro is inited, a VFS with "/" mapped to the folder where Allegro would expect resources to be located is created. That is the folder with the executable in DOS/Windows/UNIX and executable.app/Contents/Resources on OS X. No support for anything grander, other than VFS creation and selection, is included in the base library. So the VFS functions are purely:

AL_VFS *al_vfs_create();
void al_vfs_destroy(AL_VFS *);
void al_vfs_select(AL_VFS *);

Presumably public members of VFS are something like:

void (* destroy)(void); /* closes the VFS, deallocating memory */
AL_VFS_STREAM * (* open)(char *name, char *mode); /* opens a VFS_STREAM) */

And public members of VFS_STREAM are something like:

void (* destroy)(void); /* closes the VFS_STREAM */
int (* read)(void *buf, int len); /* reads 'len' bytes storing them to buf, returns number of bytes read */
int (* write)(const void *buf, int len);

Everything else is bundled into a separate addon library. That includes mounting existing datafiles into the VFS. As a simple policy decision, I think the recommended and easy route for newcomers is not to get datafile support without zip support as a simple policy decision. I'm guessing the addon would include things like:

AL_VFS *alv_create(); /* probably should be called something smarter to avoid confusion with al_vfs_create */
alv_mount /* as per your vfs_mount */

Plus a way to chain ciphers at VFS points. I've no idea what the best implementation was, but I'm imagining that if you chain a cipher at say /art then it affects everything that is a child of /art, e.g. /art/img1.png, /art/pictures/folder1/hi.bmp, etc. Ideally you should be able to chain arbitrarily many ciphers for your choice of encryption and compression.

Have I even really understoof what you are suggesting?

EDIT:

That might bring a degree of self documentation to the proceedings, but unless you do not mean it as an alternative it would lack the advances in runtime modification and creation of drivers by non-library code that to me seem like a very good idea.

You see, I may sometimes be stubborn but underneath it all I'm a very understanfing person! (sic)