Re: [AD] al_convert_bitmap

[Elias Pschernig <elias.pschernig@xxxxxxxxxx>]

On Mon, 2011-06-13 at 14:18 +1000, Peter Wang wrote:
> > 
> > The function could be named something like al_upload_bitmap_textures().
> 
> I would just tell the users to call al_upload_bitmap_textures().
> 

I think in the API it just is more user friendly to not require that.
Less clean, but more user friendly. Someone trying out Allegro will be
confused if we have to tell them "Either create your bitmaps after
al_create_display() or call al_upload_bitmap_textures() after
al_create_display()." Better to have it just work (in the simple case
where you have a single thread and don't ever call
al_set_new_bitmap_flags). That was my only motivation for this change :P

> Can I summarise the new flags like this, or propose that they
> work like this:
> 
> ALLEGRO_ANY_BITMAP|ALLEGRO_MEMORY_BITMAP
>     The bitmap actually does reside in system memory right now.
>     al_upload_bitmap_textures() will try to transition these to
>     ALLEGRO_ANY_BITMAP|ALLEGRO_VIDEO_BITMAP.
> 
> ALLEGRO_ANY_BITMAP|ALLEGRO_VIDEO_BITMAP
>     The bitmap actually is a texture right now.
>     al_destroy_display() may transition these to
>     ALLEGRO_ANY_BITMAP|ALLEGRO_MEMORY_BITMAP.
> 
> ALLEGRO_MEMORY_BITMAP
>     The bitmap actually really does reside in system memory right now.
>     al_upload_bitmap_textures() will NOT try to convert it.
> 
> ALLEGRO_VIDEO_BITMAP
>     The bitmap actually is a texture right now.
>     al_destroy_display() may transition these to
>     ALLEGRO_ANY_BITMAP|ALLEGRO_MEMORY_BITMAP
>     even if the ALLEGRO_ANY_BITMAP flag is not present.

Not how it works now. It would mean that any VIDEO bitmaps will be
transformed to VIDEO|ANY by re-creating the display. But I guess that's
just as unexpected as auto-destroying them.

> 
> al_set_new_bitmap_flags(ALLEGRO_MEMORY_BITMAP) means:
>     al_create_bitmap must return a memory bitmap, or NULL.
> 
> al_set_new_bitmap_flags(ALLEGRO_VIDEO_BITMAP) means:
>     al_create_bitmap must return a video bitmap, or NULL.
>     Unlike 5.0, it won't return a memory bitmap when no display is
>     present.
> 
> al_set_new_bitmap_flags(ALLEGRO_ANY_BITMAP) means:
>     al_create_bitmap will preferably return a video bitmap, but
>     may return a memory bitmap.
>     The bitmap has the flag ALLEGRO_ANY_BITMAP, so in the latter
>     case al_upload_bitmap_textures will try to convert it.
> 
> al_set_new_bitmap_flags(ALLEGRO_ANY_BITMAP|ALLEGRO_MEMORY_BITMAP) means:
>     al_create_bitmap must return a memory bitmap, or NULL.
>     The bitmap will have the flag ALLEGRO_ANY_BITMAP so
>     al_upload_bitmap_textures will try to convert it later.
> 
> al_set_new_bitmap_flags(ALLEGRO_ANY_BITMAP|ALLEGRO_VIDEO_BITMAP) means:
>     The same as al_set_new_bitmap_flags(ALLEGRO_VIDEO_BITMAP).
>     The bitmap will have the flag ALLEGRO_ANY_BITMAP but that is
>     immaterial.

With the above change, indeed, VIDEO would implicitly have the ANY flag
once created. In fact, I'd change it to just always set the flag then.
So the only possible combinations for the bitmap.flags field would be:

MEMORY
MEMORY+ANY
VIDEO+ANY (same as just VIDEO alone)

> al_set_new_bitmap_flags(0)
>     Now implies ALLEGRO_ANY_BITMAP instead of ALLEGRO_VIDEO_BITMAP.
> 

So in the end the possibilities for new bitmap flags would be:

0 / ANY (both are identical)
MEMORY
ANY+MEMORY
ANY+VIDEO / VIDEO (both are identical)

-- 
Elias Pschernig <elias.pschernig@xxxxxxxxxx>