Option settings

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

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.

Defines

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

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 184 of file alleggl.h.

Referenced by agl_parse_section(), allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), allegro_gl_set(), and build_settings().

#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 190 of file alleggl.h.

Referenced by __allegro_gl_fill_in_info(), agl_parse_section(), allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), allegro_gl_set(), build_settings(), and get_score().

#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 196 of file alleggl.h.

Referenced by __allegro_gl_fill_in_info(), agl_parse_section(), allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), allegro_gl_set(), build_settings(), and get_score().

#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 202 of file alleggl.h.

Referenced by __allegro_gl_fill_in_info(), agl_parse_section(), allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), allegro_gl_set(), build_settings(), and get_score().

#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 209 of file alleggl.h.

Referenced by __allegro_gl_fill_in_info(), agl_parse_section(), allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), allegro_gl_set(), build_settings(), and get_score().

#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 214 of file alleggl.h.

Referenced by __allegro_gl_fill_in_info(), agl_parse_section(), allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), allegro_gl_set(), build_settings(), and get_score().

#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 222 of file alleggl.h.

Referenced by agl_parse_section(), allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), allegro_gl_set(), build_settings(), and get_score().

#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 229 of file alleggl.h.

Referenced by agl_parse_section(), allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), allegro_gl_set(), build_settings(), and get_score().

#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 237 of file alleggl.h.

Referenced by agl_parse_section(), allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), allegro_gl_set(), build_settings(), and get_score().

#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 245 of file alleggl.h.

Referenced by agl_parse_section(), allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), allegro_gl_set(), build_settings(), and get_score().

#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 251 of file alleggl.h.

Referenced by __allegro_gl_fill_in_info(), agl_parse_section(), allegro_gl_clear_settings(), allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), allegro_gl_set(), build_settings(), and get_score().

#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 260 of file alleggl.h.

Referenced by __allegro_gl_fill_in_info(), agl_parse_section(), allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), allegro_gl_set(), build_settings(), and get_score().

#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 266 of file alleggl.h.

Referenced by agl_parse_section(), allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), allegro_gl_set(), build_settings(), and get_score().

#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 273 of file alleggl.h.

Referenced by agl_parse_section(), allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), allegro_gl_set(), build_settings(), and get_score().

#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 282 of file alleggl.h.

Referenced by agl_parse_section(), allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), allegro_gl_set(), build_settings(), and get_score().

#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 287 of file alleggl.h.

Referenced by agl_parse_section(), allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), allegro_gl_set(), and build_settings().

#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 301 of file alleggl.h.

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

#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 306 of file alleggl.h.

Referenced by agl_parse_section(), allegro_gl_clear_settings(), allegro_gl_default_gfx_init(), allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), allegro_gl_set(), and build_settings().

#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 311 of file alleggl.h.

Referenced by agl_parse_section(), allegro_gl_default_gfx_init(), allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), allegro_gl_set(), and build_settings().

#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 328 of file alleggl.h.

Referenced by agl_parse_section(), allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), allegro_gl_set(), and build_settings().

#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 352 of file alleggl.h.

Referenced by __allegro_gl_fill_in_info(), agl_parse_section(), allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), allegro_gl_set(), build_settings(), and get_score().

#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 360 of file alleggl.h.

Referenced by __allegro_gl_fill_in_info(), agl_parse_section(), allegro_gl_get(), allegro_gl_load_settings(), allegro_gl_save_settings(), allegro_gl_set(), build_settings(), and get_score().

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 __allegro_gl_required_settings, __allegro_gl_suggested_settings, AGL_DOUBLEBUFFER, AGL_FULLSCREEN, AGL_KEEP, AGL_RENDERMETHOD, and allegro_gl_display_info.

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.

Referenced by __allegro_gl_fill_in_info(), agl_parse_section(), and 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.