al_set_new_display_option - Allegro 5 API
-
#include <allegro5/allegro.h>
void al_set_new_display_option(int option, int value, int importance)
Set an extra display option, to be used when creating new displays
on the calling thread. Display options differ from display flags, and
specify some details of the context to be created within the window itself.
These mainly have no effect on Allegro itself, but you may want to specify
them, for example if you want to use multisampling.
The `importance' parameter can be either:
- •
- ALLEGRO_REQUIRE - The display will not be created if the setting can not
be met.
- •
- ALLEGRO_SUGGEST - If the setting is not available, the display will be
created anyway with a setting as close as possible to the requested one.
You can query the actual value used in that case by calling
al_get_display_option(3alleg5) after the display has been created.
- •
- ALLEGRO_DONTCARE - If you added a display option with one of the above two
settings before, it will be removed again. Else this does nothing.
The supported options are:
- ALLEGRO_COLOR_SIZE
- This can be used to ask for a specific bit depth. For example to force a
16-bit framebuffer set this to 16.
- ALLEGRO_RED_SIZE,
ALLEGRO_GREEN_SIZE, ALLEGRO_BLUE_SIZE, ALLEGRO_ALPHA_SIZE
- Individual color component size in bits.
- ALLEGRO_RED_SHIFT,
ALLEGRO_GREEN_SHIFT, ALLEGRO_BLUE_SHIFT, ALLEGRO_ALPHA_SHIFT
- Together with the previous settings these can be used to specify the exact
pixel layout the display should use. Normally there is no reason to use
these.
- ALLEGRO_ACC_RED_SIZE,
ALLEGRO_ACC_GREEN_SIZE, ALLEGRO_ACC_BLUE_SIZE,
ALLEGRO_ACC_ALPHA_SIZE
- This can be used to define the required accumulation buffer size.
- ALLEGRO_STEREO
- Whether the display is a stereo display.
- ALLEGRO_AUX_BUFFERS
- Number of auxiliary buffers the display should have.
- ALLEGRO_DEPTH_SIZE
- How many depth buffer (z-buffer) bits to use.
- ALLEGRO_STENCIL_SIZE
- How many bits to use for the stencil buffer.
- ALLEGRO_SAMPLE_BUFFERS
- Whether to use multisampling (1) or not (0).
- ALLEGRO_SAMPLES
- If the above is 1, the number of samples to use per pixel. Else 0.
- ALLEGRO_RENDER_METHOD:
- 0 if hardware acceleration is not used with this display.
- ALLEGRO_FLOAT_COLOR
- Whether to use floating point color components.
- ALLEGRO_FLOAT_DEPTH
- Whether to use a floating point depth buffer.
- ALLEGRO_SINGLE_BUFFER
- Whether the display uses a single buffer (1) or another update method
(0).
- ALLEGRO_SWAP_METHOD
- If the above is 0, this is set to 1 to indicate the display is using a
copying method to make the next buffer in the flip chain available, or to
2 to indicate a flipping or other method.
- ALLEGRO_COMPATIBLE_DISPLAY
- Indicates if Allegro's graphics functions can use this display. If you
request a display not useable by Allegro, you can still use for example
OpenGL to draw graphics.
- ALLEGRO_UPDATE_DISPLAY_REGION
- Set to 1 if the display is capable of updating just a region, and 0 if
calling al_update_display_region(3alleg5) is equivalent to
al_flip_display(3alleg5).
- ALLEGRO_VSYNC
- Set to 1 to tell the driver to wait for vsync in al_flip_display(3alleg5),
or to 2 to force vsync off. The default of 0 means that Allegro does not
try to modify the vsync behavior so it may be on or off. Note that even in
the case of 1 or 2 it is possible to override the vsync behavior in the
graphics driver so you should not rely on it.
- ALLEGRO_MAX_BITMAP_SIZE
- When queried this returns the maximum size (width as well as height) a
bitmap can have for this display. Calls to al_create_bitmap(3alleg5) or
al_load_bitmap(3alleg5) for bitmaps larger than this size will fail. It
does not apply to memory bitmaps which always can have arbitrary size (but
are slow for drawing).
- ALLEGRO_SUPPORT_NPOT_BITMAP
- Set to 1 if textures used for bitmaps on this display can have a size
which is not a power of two. This is mostly useful if you use Allegro to
load textures as otherwise only power-of-two textures will be used
internally as bitmap storage.
- ALLEGRO_CAN_DRAW_INTO_BITMAP
- Set to 1 if you can use al_set_target_bitmap(3alleg5) on bitmaps of this
display to draw into them. If this is not the case software emulation will
be used when drawing into display bitmaps (which can be very slow).
- ALLEGRO_SUPPORT_SEPARATE_ALPHA
- This is set to 1 if the al_set_separate_blender(3alleg5) function is
supported. Otherwise the alpha parameters will be ignored.
- ALLEGRO_AUTO_CONVERT_BITMAPS
- This is on by default. It causes any existing memory bitmaps with the
ALLEGRO_CONVERT_BITMAP flag to be converted to a display bitmap of the
newly created display with the option set.
- ALLEGRO_SUPPORTED_ORIENTATIONS
- This is a bit-combination of the orientations supported by the
application. The orientations are the same as for
al_get_display_orientation(3alleg5) with the additional
possibilities:
- •
- ALLEGRO_DISPLAY_ORIENTATION_PORTRAIT
- •
- ALLEGRO_DISPLAY_ORIENTATION_LANDSCAPE
- •
- ALLEGRO_DISPLAY_ORIENTATION_ALL
PORTRAIT means only the two portrait orientations are supported,
LANDSCAPE means only the two landscape orientations and ALL allows all four
orientations. When the orientation changes between a portrait and a
landscape orientation the display needs to be resized. This is done by
sending an ALLEGRO_EVENT_DISPLAY_RESIZE(3alleg5) message which should be
handled by calling al_acknowledge_resize(3alleg5).
Since: 5.1.0
- ALLEGRO_OPENGL_MAJOR_VERSION
- Request a specific OpenGL major version.
- ALLEGRO_OPENGL_MINOR_VERSION
- Request a specific OpenGL minor version.