AllegroGL: Option settings

# Option settings

OpenGL has many options controlling the way a video mode is selected. More...

## Defines

- #define AGL_FLOAT_COLOR 0x00800000
    Floating-point Color buffer.
- #define AGL_FLOAT_Z 0x01000000
    Floating-point Depth buffer.
- #define AGL_CONFIG_RESRVED 0xA000000

## Mode selection functions

- void allegro_gl_clear_settings (void)
    Clear the option settings All settings are set to their default values, and marked as neither suggested not required.
- void allegro_gl_set (int option, int value)
    Sets a configuration option.
- int allegro_gl_get (int option)
    Reads the setting of a configuration option.
- void allegro_gl_save_settings ()
    Saves the current settings (as specified by allegro_gl_set()) to the current config file, in the section [OpenGL].
- void allegro_gl_load_settings ()
    Loads the settings from the current config file, in the section [OpenGL].

## Frame Buffer Settings

- #define AGL_ALLEGRO_FORMAT 0x00000001
    Use Allegro-compatible framebuffer.
- #define AGL_RED_DEPTH 0x00000002
    Select the red depth of the frame buffer.
- #define AGL_GREEN_DEPTH 0x00000004
    Select the green depth of the frame buffer.
- #define AGL_BLUE_DEPTH 0x00000008
    Select the blue depth of the frame buffer.
- #define AGL_ALPHA_DEPTH 0x00000010
    Select the alpha depth of the frame buffer.
- #define AGL_COLOR_DEPTH 0x00000020
    Specify the total color depth of the frame buffer.
- #define AGL_ACC_RED_DEPTH 0x00000040
    Select the red depth of the accumulator buffer.
- #define AGL_ACC_GREEN_DEPTH 0x00000080
    Select the green depth of the accumulator buffer.
- #define AGL_ACC_BLUE_DEPTH 0x00000100
    Select the blue depth of the accumulator buffer.
- #define AGL_ACC_ALPHA_DEPTH 0x00000200
    Select the alpha depth of the accumulator buffer.
- #define AGL_DOUBLEBUFFER 0x00000400
    Creates a backbuffer if set.
- #define AGL_STEREO 0x00000800
    Creates seperate left/right buffers for stereo display.
- #define AGL_AUX_BUFFERS 0x00001000
    Creates additional auxiliary buffers.
- #define AGL_Z_DEPTH 0x00002000
    Select the depth of the z-buffer.
- #define AGL_STENCIL_DEPTH 0x00004000
    Select the depth of the stencil buffer.
- #define AGL_WINDOW_X 0x00008000
    Requests a placement of the window to a specified pixel location.
- #define AGL_WINDOW_Y 0x00010000
    Same as AGL_WINDOW_X, but for the y-axis.
- #define AGL_RENDERMETHOD 0x00020000
    Set it if you'd like AllegroGL to pay special attention on whether hardware acceleration is present or not.
- #define AGL_FULLSCREEN 0x00040000
    Set if you'd like a full screen mode.
- #define AGL_WINDOWED 0x00080000
    Set if you'd like a windowed mode.
- #define AGL_VIDEO_MEMORY_POLICY 0x00100000
    Define AllegroGL's policy relative to video memory usage.
- #define AGL_SAMPLE_BUFFERS 0x00200000
    Define multisample parameters Some OpenGL ICDs expose an extension called GL_ARB_multisample which provides a mechanism to anti-alias all GL primitives: points, lines, polygons, bitmaps and pixel rectangles.
- #define AGL_SAMPLES 0x00400000
    Define multisample samples Set this value to the number of samples that can be accepted in the multisample buffers.

## Mode selection priority options

- #define AGL_DONTCARE 0
    Ignore these settings.
- #define AGL_SUGGEST -1
    Prefer the assigned values for these settings.
- #define AGL_REQUIRE -2
    Reject other values for these settings.

## Video memory policy options

- #define AGL_KEEP 1
    Keep internal texture in video memory.
- #define AGL_RELEASE 2
    Release video memory occupied by internal texture.

## Detailed Description

OpenGL has many options controlling the way a video mode is selected.

AllegroGL has functions to set particular options, and to state whether choices are merely preferences or are essential.

Use allegro_gl_set() to set options. All options are integers. The value you set is, by default, ignored; you must tell AllegroGL how important it is. There are three levels of importance:

- AGL_DONTCARE: ignore this setting
- AGL_SUGGEST: this setting is a preference but not essential
- AGL_REQUIRE: this setting is important, so don't set a mode without it

To specify the importance of a setting, set AGL_REQUIRE, AGL_SUGGEST, or AGL_DONTCARE to contain that setting's flag, e.g.

       allegro_gl_set(AGL_COLOR_DEPTH, 16);
       allegro_gl_set(AGL_REQUIRE, AGL_COLOR_DEPTH);

Rather than calling allegro_gl_set once per setting you want to mark as required, you can OR the setting flags together:

       allegro_gl_set(AGL_REQUIRE, AGL_COLOR_DEPTH | AGL_DOUBLEBUFFER);

This has the same effect as marking the two settings separately.

After saying that you AGL_REQUIRE a particular setting, you can still go back and AGL_DONTCARE or AGL_SUGGEST it instead -- nothing happens until you try to set a graphics mode. At that stage, a mode is set (or set_gfx_mode() returns failure, if not all required settings could be satisfied), and you can then retrieve the actual settings used by calling allegro_gl_get(). Note that this is largely untested; some settings may not be retrieved properly. Please do let us know if you find any!

## Define Documentation

#define AGL_ALLEGRO_FORMAT 0x00000001

Use Allegro-compatible framebuffer.

Deprecated:
  This define is ignored.

Definition at line 189 of file alleggl.h.

Referenced by allegro_gl_get(), and allegro_gl_set().

#define AGL_RED_DEPTH 0x00000002

Select the red depth of the frame buffer.

This defines the number of bits for the red component you'd like. The driver may or may not find a suitable mode

Definition at line 195 of file alleggl.h.

Referenced by allegro_gl_get(), and allegro_gl_set().

#define AGL_GREEN_DEPTH 0x00000004

Select the green depth of the frame buffer.

This defines the number of bits for the green component you'd like. The driver may or may not find a suitable mode

Definition at line 201 of file alleggl.h.

Referenced by allegro_gl_get(), and allegro_gl_set().

#define AGL_BLUE_DEPTH 0x00000008

Select the blue depth of the frame buffer.

This defines the number of bits for the blue component you'd like. The driver may or may not find a suitable mode

Definition at line 207 of file alleggl.h.

Referenced by allegro_gl_get(), and allegro_gl_set().

#define AGL_ALPHA_DEPTH 0x00000010

Select the alpha depth of the frame buffer.

This defines the number of bits for the alpha component you'd like. Not many video cards support destination alpha, so be aware that the you may not get an alpha depth at all.

Definition at line 214 of file alleggl.h.

Referenced by allegro_gl_get(), and allegro_gl_set().

#define AGL_COLOR_DEPTH 0x00000020

Specify the total color depth of the frame buffer.

The driver is free to select any combination of red, green, blue and alpha bits.

Definition at line 219 of file alleggl.h.

Referenced by allegro_gl_get(), and allegro_gl_set().

#define AGL_ACC_RED_DEPTH 0x00000040

Select the red depth of the accumulator buffer.

This defines the number of bits to use for the red component. The driver may or may not find a suitable mode. Note that on many video cards, the accumulator buffer is not accelerated.

Definition at line 227 of file alleggl.h.

Referenced by allegro_gl_get(), and allegro_gl_set().

#define AGL_ACC_GREEN_DEPTH 0x00000080

Select the green depth of the accumulator buffer.

This defines the number of bits to use for the green component. The driver may or may not find a suitable mode. Note that on many video cards, the accumulator buffer is not accelerated.

Definition at line 234 of file alleggl.h.

Referenced by allegro_gl_get(), and allegro_gl_set().

#define AGL_ACC_BLUE_DEPTH 0x00000100

Select the blue depth of the accumulator buffer.

This defines the number of bits to use for the blue component. The driver may or may not find a suitable mode. Note that on many video cards, the accumulator buffer is not accelerated.

Definition at line 242 of file alleggl.h.

Referenced by allegro_gl_get(), and allegro_gl_set().

#define AGL_ACC_ALPHA_DEPTH 0x00000200

Select the alpha depth of the accumulator buffer.

This defines the number of bits to use for the alpha component. The driver may or may not find a suitable mode. Note that on many video cards, the accumulator buffer is not accelerated. Not many cards support destination alpha either.

Definition at line 250 of file alleggl.h.

Referenced by allegro_gl_get(), and allegro_gl_set().

#define AGL_DOUBLEBUFFER 0x00000400

Creates a backbuffer if set.

The buffering mode may be double buffering or page flipping, depending on the driver settings. OpenGL programs cannot chose the buffering mode themselves.

Definition at line 256 of file alleggl.h.

Referenced by allegro_gl_clear_settings(), allegro_gl_get(), and allegro_gl_set().

#define AGL_STEREO 0x00000800

Creates seperate left/right buffers for stereo display.

Stereo display is used with special hardware (tipically glasses) for giving the illusion of depth by drawing the left and right buffers with a slight horizontal displacement. This makes the display appear to heavily flicker without the special hardware. Set to TRUE for enabling stereo viewing.

Definition at line 265 of file alleggl.h.

Referenced by allegro_gl_get(), and allegro_gl_set().

#define AGL_AUX_BUFFERS 0x00001000

Creates additional auxiliary buffers.

This allows you to have more than one rendering context. Few video cards support this feature.

Definition at line 271 of file alleggl.h.

Referenced by allegro_gl_get(), and allegro_gl_set().

#define AGL_Z_DEPTH 0x00002000

Select the depth of the z-buffer.

The z-buffer is used to properly display polygons in 3D without recurring to sorting. The higher the depth of the z-buffer, the more precise it is.

Definition at line 278 of file alleggl.h.

Referenced by allegro_gl_get(), and allegro_gl_set().

#define AGL_STENCIL_DEPTH 0x00004000

Select the depth of the stencil buffer.

The stencil buffer is used to to do per-pixel testing (like the z-buffer), but of an arbitrary pattern instead of depth. Please see the OpenGL documentation for details. Newer cards support stenciling in hardware, but older cards (TNT2s, Voodoos, ATI Rage) do not.

Definition at line 287 of file alleggl.h.

Referenced by allegro_gl_get(), and allegro_gl_set().

#define AGL_WINDOW_X 0x00008000

Requests a placement of the window to a specified pixel location.

The driver may or may not honnor the request.

Definition at line 292 of file alleggl.h.

Referenced by allegro_gl_get(), and allegro_gl_set().

#define AGL_RENDERMETHOD 0x00020000

Set it if you'd like AllegroGL to pay special attention on whether hardware acceleration is present or not.

Notice however this isn't a guarentee that the OpenGL operations will be accelerated, but rather a request that the operations go through the video card's drivers instead of Microsoft's software renderer. The video card driver is free to drop back to software mode if it deems it necessary. This setting has no effect in X.

Definition at line 306 of file alleggl.h.

Referenced by allegro_gl_clear_settings(), and allegro_gl_set().

#define AGL_FULLSCREEN 0x00040000

Set if you'd like a full screen mode.

Full screen may or may not be available on the current platform.

Definition at line 311 of file alleggl.h.

Referenced by allegro_gl_clear_settings(), allegro_gl_get(), and allegro_gl_set().

#define AGL_WINDOWED 0x00080000

Set if you'd like a windowed mode.

Windowed modes may or may not be available on the current platform.

Definition at line 316 of file alleggl.h.

Referenced by allegro_gl_get(), and allegro_gl_set().

#define AGL_VIDEO_MEMORY_POLICY 0x00100000

Define AllegroGL's policy relative to video memory usage.

Sometimes AllegroGL needs to create an internal 256x256 texture in order to perform graphics operations like masked_blit, draw_sprite and so on. This parameter defines the policy of AllegroGL relative to the management of this texture. Several options are available :

- AGL_RELEASE : internal texture is released in order to free video memory.
- AGL_KEEP : internal texture is kept in video memory. This option generally accelerate graphics operations when allegro_gl_set_allegro_mode() and allegro_gl_unset_allegro_mode() are often called. System with few video memory should use AGL_RELEASE while others should use AGL_KEEP since it allows the internal texture to be created once. Default value is AGL_KEEP.

Definition at line 333 of file alleggl.h.

Referenced by allegro_gl_get(), and allegro_gl_set().

#define AGL_SAMPLE_BUFFERS 0x00200000

Define multisample parameters Some OpenGL ICDs expose an extension called GL_ARB_multisample which provides a mechanism to anti-alias all GL primitives: points, lines, polygons, bitmaps and pixel rectangles.

In order to get an AllegroGL mode which supports multisample, you have to set both AGL_SAMPLE_BUFFERS to 1 and AGL_SAMPLES to the number of desired samples for multisampling.

Notice however that since this feature relies on several extensions (GL_ARB_multisample and GLX_ARB_multisample or WGL_ARB_multisample), it isn't guaranteed that AllegroGL will find a graphics mode that supports multisample : many not-so-old video cards, like the GeForce 2, do not support multisampling

Hence, if you want your app to be able to run on most platforms, you should not require this parameter.

Set this value to 1 to enable multisampling.

See also:
  AGL_SAMPLES

Definition at line 357 of file alleggl.h.

Referenced by allegro_gl_get(), and allegro_gl_set().

#define AGL_SAMPLES 0x00400000

Define multisample samples Set this value to the number of samples that can be accepted in the multisample buffers.

See also:
  AGL_SAMPLE_BUFFERS

Definition at line 365 of file alleggl.h.

Referenced by allegro_gl_get(), and allegro_gl_set().

## Function Documentation

void allegro_gl_clear_settings | ( | void |  | ) |

Clear the option settings All settings are set to their default values, and marked as neither suggested not required.

The mode setting routines will now ignore all of the settings other than those which you explicitly mark with AGL_SUGGEST or AGL_REQUIRE.

Note:
  You should not rely on what the default values actually are - don't mark settings unless you've also assigned something to them.

  Some settings are turned on by default. AGL_DOUBLEBUFFER, AGL_RENDERMETHOD and AGL_FULLSCREEN are set to AGL_SUGGEST.

See also:
  allegro_gl_set(), allegro_gl_get()

Definition at line 193 of file alleggl.c.

References AGL_DOUBLEBUFFER, AGL_FULLSCREEN, AGL_KEEP, and AGL_RENDERMETHOD.

Referenced by install_allegro_gl().

void allegro_gl_set | ( | int | option,
|  | int | value |
| ) |  |  |

Sets a configuration option.

Use this routine to configure the framebuffer, *before* setting a graphics mode. Options are integer constants, and all values are effectively integers.

Three of the options are special. AGL_SUGGEST and AGL_REQUIRE are used to mark which of the other options are merely suggestions and which are absolute requirements. If the OpenGL implementation can't provide a feature which you mark with AGL_REQUIRE, the call to set_gfx_mode will fail. If you don't mark an option as either suggested or required, that option will be ignored (AGL_DONTCARE). You can OR (|) together the other constants when using one of these three options to indicate your preferences for several settings at one time. Selecting an option as one of the suggestion modes will remove it from the others. For example, if you first set the color depth to be required, but then decide that you want it to be suggested instead, then the option will be removed from the required settings. Setting any option to AGL_DONTCARE will remove any previous setting attributed to it, and default values will be used if necessary.

The remaining options are:

    		AGL_ALLEGRO_FORMAT,
    		AGL_RED_DEPTH,
    		AGL_GREEN_DEPTH,
    		AGL_BLUE_DEPTH,
    		AGL_ALPHA_DEPTH,
    		AGL_COLOR_DEPTH,
    		AGL_ACC_RED_DEPTH,
    		AGL_ACC_GREEN_DEPTH,
    		AGL_ACC_BLUE_DEPTH,
    		AGL_ACC_ALPHA_DEPTH,
    		AGL_DOUBLEBUFFER,
    		AGL_STEREO,
    		AGL_AUX_BUFFERS,
    		AGL_Z_DEPTH,
    		AGL_STENCIL_DEPTH,
    		AGL_WINDOW_X,
    		AGL_WINDOW_Y,
    		AGL_RENDERMETHOD
    		AGL_FULLSCREEN
    		AGL_WINDOWED
    		AGL_VIDEO_MEMORY_POLICY
    		AGL_SAMPLE_BUFFERS
    		AGL_SAMPLES
    		AGL_FLOAT_COLOR
    		AGL_FLOAT_Z

Parameters:

  | option | Selects which option to change.
  | value | The new option value.

Example:

        allegro_gl_set(AGL_COLOR_DEPTH, 32);
        allegro_gl_set(AGL_RENDERMETHOD, 1);
        allegro_gl_set(AGL_REQUIRE, AGL_COLOR_DEPTH | AGL_RENDERMETHOD);

See also:
  allegro_gl_get(), allegro_gl_clear_settings()

Definition at line 274 of file alleggl.c.

References AGL_ACC_ALPHA_DEPTH, AGL_ACC_BLUE_DEPTH, AGL_ACC_GREEN_DEPTH, AGL_ACC_RED_DEPTH, AGL_ALLEGRO_FORMAT, AGL_ALPHA_DEPTH, AGL_AUX_BUFFERS, AGL_BLUE_DEPTH, AGL_COLOR_DEPTH, AGL_DONTCARE, AGL_DOUBLEBUFFER, AGL_FLOAT_COLOR, AGL_FLOAT_Z, AGL_FULLSCREEN, AGL_GREEN_DEPTH, AGL_KEEP, AGL_RED_DEPTH, AGL_RELEASE, AGL_RENDERMETHOD, AGL_REQUIRE, AGL_SAMPLE_BUFFERS, AGL_SAMPLES, AGL_STENCIL_DEPTH, AGL_STEREO, AGL_SUGGEST, AGL_VIDEO_MEMORY_POLICY, AGL_WINDOW_X, AGL_WINDOW_Y, AGL_WINDOWED, and AGL_Z_DEPTH.

Referenced by allegro_gl_load_settings().

int allegro_gl_get | ( | int | option | ) |

Reads the setting of a configuration option.

This routine can be used to read back the configuration of the framebuffer. You can do this either before setting a graphics mode to check what configuration you are requesting, or afterwards to find out what settings were actually used. For a list of option constants, see documentation for allegro_gl_set().

Parameters:

  | option | The option to have its value returned.

Returns:
  The value of the option selected by the parameter, or -1 if the option is invalid.

See also:
  allegro_gl_set(), allegro_gl_clear_settings()

Definition at line 421 of file alleggl.c.

References AGL_ACC_ALPHA_DEPTH, AGL_ACC_BLUE_DEPTH, AGL_ACC_GREEN_DEPTH, AGL_ACC_RED_DEPTH, AGL_ALLEGRO_FORMAT, AGL_ALPHA_DEPTH, AGL_AUX_BUFFERS, AGL_BLUE_DEPTH, AGL_COLOR_DEPTH, AGL_DONTCARE, AGL_DOUBLEBUFFER, AGL_FLOAT_COLOR, AGL_FLOAT_Z, AGL_FULLSCREEN, AGL_GREEN_DEPTH, AGL_RED_DEPTH, AGL_REQUIRE, AGL_SAMPLE_BUFFERS, AGL_SAMPLES, AGL_STENCIL_DEPTH, AGL_STEREO, AGL_SUGGEST, AGL_VIDEO_MEMORY_POLICY, AGL_WINDOW_X, AGL_WINDOW_Y, AGL_WINDOWED, and AGL_Z_DEPTH.

Referenced by allegro_gl_save_settings().

void allegro_gl_save_settings | ( |  | ) |

Saves the current settings (as specified by allegro_gl_set()) to the current config file, in the section [OpenGL].

See also:
  allegro_gl_load_settings()

Definition at line 560 of file alleggl.c.

References AGL_FLOAT_Z, AGL_REQUIRE, AGL_SUGGEST, and allegro_gl_get().

void allegro_gl_load_settings | ( |  | ) |

Loads the settings from the current config file, in the section [OpenGL].

Note that this function will not clear any settings currently set, but will add them up, as if each of the setting were set manually.

See also:
  allegro_gl_save_settings()

Definition at line 741 of file alleggl.c.

References AGL_FLOAT_Z, AGL_REQUIRE, AGL_SUGGEST, and allegro_gl_set().