The Allegro Wiki is migrating to github at https://github.com/liballeg/allegro_wiki/wiki

Convert Bitmap Proposal

From Allegro Wiki
Jump to: navigation, search

Allegro 5.0 automatically converts bitmaps from video to memory upon the display's destruction. This is a proposal to support conversion in the other direction.

New bitmap flag: ALLEGRO_CONVERT_BITMAP

If set, the bitmap would always be part of an internal "need to convert" list while it is presently a memory bitmap.

New function: al_convert_bitmaps();

It would try to convert all of those memory bitmaps on the list to video bitmaps attached to the active display.

New display option: ALLEGRO_AUTO_CONVERT_BITMAPS

If set to 1 it would convert any bitmaps on the list when a display is created.

Default Behavior

No bitmaps would be tagged as auto conversion unless explicitly requested.

No display would automatically convert the list of memory bitmaps to video bitmaps unless explicitly set.

However, all video bitmaps would always be converted down to a memory bitmap after the final compatible display is destroyed. There would be no way to change that behavior.

Usage

To enable auto conversion, you would have to set:

<highlightSyntax language="c">

   al_set_new_display_option(ALLEGRO_AUTO_CONVERT_BITMAPS, 1, ALLEGRO_DONTCARE);
   al_set_new_bitmap_flags(ALLEGRO_CONVERT_BITMAP);

</highlightSyntax>

al_set_new_bitmap_flags()

  • No flags: Create video bitmap. If it fails, create memory bitmap.
  • ALLEGRO_MEMORY_BITMAP: Create memory bitmap.
  • ALLEGRO_VIDEO_BITMAP: Create video bitmap.
  • ALLEGRO_CONVERT_BITMAP: Try video. If it fails then create memory bitmap and tag it.
  • ALLEGRO_CONVERT_BITMAP | ALLEGRO_MEMORY_BITMAP: Create memory bitmap, and add it to the list of pending conversions.
  • ALLEGRO_CONVERT_BITMAP | ALLEGRO_VIDEO_BITMAP: Create video bitmap. When the final compatible display is destroyed, add it to the list of pending conversions.

al_convert_bitmaps(ALLEGRO_DISPLAY *display)

Convert all memory bitmaps on the list to video bitmaps.

Use Cases

You may want to load many images, fonts, etc on a separate thread. Once finished, you want to convert them to video bitmaps.

<highlightSyntax language="c">

   al_set_new_bitmap_flags(ALLEGRO_MEMORY_BITMAP | ALLEGRO_CONVERT_BITMAP);
   // load all bitmaps
   al_convert_bitmaps(display);

</highlightSyntax>

You may want to load some images for a future display:

<highlightSyntax language="c">

   d1 = al_create_display(320, 240);
   al_set_new_bitmap_flags(ALLEGRO_MEMORY_BITMAP | ALLEGRO_CONVERT_BITMAP);
   // load all bitmaps
   // set incompatible display options
   d2 = al_create_display(320, 240);
   al_convert_bitmaps(d2);

</highlightSyntax>

You may just be very lazy and not want to manage anything.

<highlightSyntax language="c">

   al_set_new_display_option(ALLEGRO_AUTO_CONVERT_BITMAPS, 1, ALLEGRO_DONTCARE);
   al_set_new_bitmap_flags(ALLEGRO_CONVERT_BITMAP);
   // load all bitmaps
   d = al_create_display(640, 480);
   // bitmaps automatically converted back to video
   // create more bitmaps
   al_destroy_display(d);
   // bitmaps now downgraded to memory
   al_create_display(800, 600);
   // bitmaps automatically converted back to video

</highlightSyntax>

Comments

Of course this is simply a convenience layer which isn't absolutely required. With the functions al_convert_bitmap() and al_convert_font() (i.e., a function for any structure that uses a bitmap internally), a person could manage it themselves.

But as Allegro is already converting from video to memory, it seems natural to support both directions.

The display option ALLEGRO_AUTO_CONVERT_BITMAPS could also be used to disable conversion from VIDEO to MEMORY upon destroying a display. But that is probably not very useful.

al_convert_bitmaps() could use a better name.