AllegroGL 0.4.4

- Main Page
- Related Pages
- Modules
- Files

Macros
Option settings

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

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

## Frame Buffer Settings
#define | AGL_ALLEGRO_FORMAT 0x00000001
| Use Allegro-compatible framebuffer. More...
#define | AGL_RED_DEPTH 0x00000002
| Select the red depth of the frame buffer. More...
#define | AGL_GREEN_DEPTH 0x00000004
| Select the green depth of the frame buffer. More...
#define | AGL_BLUE_DEPTH 0x00000008
| Select the blue depth of the frame buffer. More...
#define | AGL_ALPHA_DEPTH 0x00000010
| Select the alpha depth of the frame buffer. More...
#define | AGL_COLOR_DEPTH 0x00000020
| Specify the total color depth of the frame buffer. More...
#define | AGL_ACC_RED_DEPTH 0x00000040
| Select the red depth of the accumulator buffer. More...
#define | AGL_ACC_GREEN_DEPTH 0x00000080
| Select the green depth of the accumulator buffer. More...
#define | AGL_ACC_BLUE_DEPTH 0x00000100
| Select the blue depth of the accumulator buffer. More...
#define | AGL_ACC_ALPHA_DEPTH 0x00000200
| Select the alpha depth of the accumulator buffer. More...
#define | AGL_DOUBLEBUFFER 0x00000400
| Creates a backbuffer if set. More...
#define | AGL_STEREO 0x00000800
| Creates seperate left/right buffers for stereo display. More...
#define | AGL_AUX_BUFFERS 0x00001000
| Creates additional auxiliary buffers. More...
#define | AGL_Z_DEPTH 0x00002000
| Select the depth of the z-buffer. More...
#define | AGL_STENCIL_DEPTH 0x00004000
| Select the depth of the stencil buffer. More...
#define | AGL_WINDOW_X 0x00008000
| Requests a placement of the window to a specified pixel location. More...
#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. More...
#define | AGL_FULLSCREEN 0x00040000
| Set if you'd like a full screen mode. More...
#define | AGL_WINDOWED 0x00080000
| Set if you'd like a windowed mode. More...
#define | AGL_VIDEO_MEMORY_POLICY 0x00100000
| Define AllegroGL's policy relative to video memory usage. More...
#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. More...
#define | AGL_SAMPLES 0x00400000
| Define multisample samples Set this value to the number of samples that can be accepted in the multisample buffers. More...

## 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.

## 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. More...
void | allegro_gl_set (int option, int value)
| Sets a configuration option. More...
int | allegro_gl_get (int option)
| Reads the setting of a configuration option. More...
void | allegro_gl_save_settings ()
| Saves the current settings (as specified by allegro_gl_set()) to the current config file, in the section [OpenGL]. More...
void | allegro_gl_load_settings ()
| Loads the settings from the current config file, in the section [OpenGL]. More...

## 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!

## Macro Definition Documentation

#define AGL_ALLEGRO_FORMAT 0x00000001

Use Allegro-compatible framebuffer.

Deprecated:
  This define is ignored.

Definition at line 193 of file alleggl.h.

Referenced by allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), 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 199 of file alleggl.h.

Referenced by allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), 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 205 of file alleggl.h.

Referenced by allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), 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 211 of file alleggl.h.

Referenced by allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), 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 218 of file alleggl.h.

Referenced by allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), 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 223 of file alleggl.h.

Referenced by allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), 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 231 of file alleggl.h.

Referenced by allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), 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 238 of file alleggl.h.

Referenced by allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), 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 246 of file alleggl.h.

Referenced by allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), 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 254 of file alleggl.h.

Referenced by allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), 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 260 of file alleggl.h.

Referenced by allegro_gl_clear_settings(), allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), 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 269 of file alleggl.h.

Referenced by allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), 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 275 of file alleggl.h.

Referenced by allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), 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 282 of file alleggl.h.

Referenced by allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), 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 291 of file alleggl.h.

Referenced by allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), 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 296 of file alleggl.h.

Referenced by allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), 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 310 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 315 of file alleggl.h.

Referenced by allegro_gl_clear_settings(), allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_opengl_version(), allegro_gl_save_settings(), 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 320 of file alleggl.h.

Referenced by allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_opengl_version(), allegro_gl_save_settings(), 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 337 of file alleggl.h.

Referenced by allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), 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 361 of file alleggl.h.

Referenced by allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), 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 369 of file alleggl.h.

Referenced by allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), 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(), and allegro_gl_save_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_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_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, AGL_Z_DEPTH, allegro_gl_get(), and allegro_gl_set().

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_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_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, AGL_Z_DEPTH, and allegro_gl_set().