Re: [AD] public state store/restore API

[Peter Wang <novalazy@xxxxxxxxxx>]

On 2008-09-03, Elias Pschernig <elias@xxxxxxxxxx> wrote:
> We briefly talked about this in #allegro-dev, so I made a patch. It's
> simply two functions:
> 
> void al_store_state(ALLEGRO_STATE *state, int flags);
> void al_restore_state(ALLEGRO_STATE *state, int flags);

One variant of this would be to remember the flags so the restore call
is a bit simpler.  Of course it's less flexible, but also less error
prone.

> The intended use would be something like for example:
> 
> void my_blended_draw(...)
> {
>     ALLEGRO_STATE state;
>     al_store_state(&state, ALLEGRO_STATE_BLENDER);
> 
>     al_set_blender(...);
> 
>     al_restore_state(&state, ALLEGRO_STATE_BLENDER);
> }
> 
> But then I found that only one single example currently would have use
> for it - so not sure now we really need it. And also currently, the
> above would look like:
> 
> void my_blended_draw(...)
> {
>     int src, dst;
>     ALLEGRO_COLOR color;
>     al_get_blender(&src, &dst, &color);
> 
>     al_set_blender(...);
> 
>     al_set_blender(src, dst, color);
> }
> 
> So not terribly long either. What does everyone think?

I'm mainly interested in saving and restoring the bitmap format
and target.

> Index: include/allegro5/tls.h
> ===================================================================
> --- include/allegro5/tls.h	(revision 0)
> +++ include/allegro5/tls.h	(revision 0)
> @@ -0,0 +1,70 @@
> +/*         ______   ___    ___
> + *        /\  _  \ /\_ \  /\_ \
> + *        \ \ \L\ \\//\ \ \//\ \      __     __   _ __   ___
> + *         \ \  __ \ \ \ \  \ \ \   /'__`\ /'_ `\/\`'__\/ __`\
> + *          \ \ \/\ \ \_\ \_ \_\ \_/\  __//\ \L\ \ \ \//\ \L\ \
> + *           \ \_\ \_\/\____\/\____\ \____\ \____ \ \_\\ \____/
> + *            \/_/\/_/\/____/\/____/\/____/\/___L\ \/_/ \/___/
> + *                                           /\____/
> + *                                           \_/__/
> + *
> + *      Timer routines.
> + *
> + *      See readme.txt for copyright information.
> + */
> +
> +/* Title: Timer routines
> + */

You'll want to fix that up.

> +
> +#ifndef ALLEGRO_TLS_H
> +#define ALLEGRO_TLS_H
> +
> +#include "allegro5/base.h"
> +
> +AL_BEGIN_EXTERN_C
> +
> +/* Enum: ALLEGRO_STATE
> + * 
> + * Flags which can be passed to al_store_state/al_restore_state.
> + * 
> + * ALLEGRO_STATE_NEW_DISPLAY_PARAMETERS - new_display_format,
> + *                                        new_display_refresh_rate,
> + *                                        new_display_flags
> + * ALLEGRO_STATE_NEW_BITMAP_PARAMETERS  - new_bitmap_format,
> + *                                        new_bitmap_flags
> + * ALLEGRO_STATE_DISPLAY                - current_display
> + * ALLEGRO_STATE_TARGET_BITMAP          - target_bitmap 
> + * ALLEGRO_STATE_BLENDER                - blender
> + */
> +#define ALLEGRO_STATE_NEW_DISPLAY_PARAMETERS 0x0001
> +#define ALLEGRO_STATE_NEW_BITMAP_PARAMETERS  0x0002
> +#define ALLEGRO_STATE_DISPLAY                0x0004
> +#define ALLEGRO_STATE_TARGET_BITMAP          0x0008
> +#define ALLEGRO_STATE_BLENDER                0x0010

You can use a enum.

> +
> +/* Type: ALLEGRO_STATE
> + * 
> + * Opaque type which is passed to al_store_state/al_restore_state.
> + */
> +/* FIXME: This should all be internal - what's a good way to do that in C? */
> +typedef struct ALLEGRO_STATE
> +{
> +   int new_display_format;
> +   int new_display_refresh_rate;
> +   int new_display_flags;
> +   int new_bitmap_format;
> +   int new_bitmap_flags;
> +   ALLEGRO_DISPLAY *current_display;
> +   ALLEGRO_BITMAP *target_bitmap;
> +   int blend_source;
> +   int blend_dest;
> +   ALLEGRO_COLOR blend_color;
> +   void *memory_blender;
> +} ALLEGRO_STATE;

To hide the internals, I suggest

    typedef struct ALLEGRO_STATE {
	int32_t __pad[32];
    } ALLEGRO_STATE;

or however much, so that sizeof(ALLEGRO_STATE) is big enough
plus some for the future.

Peter