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.