--- name: "al_set_new_display_option" section: "3" platform: "linux" package: "allegro" version: "5.2.11.3-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/al_set_new_display_option" --- # al\_set\_new\_display\_option(3) Allegro 5 API ## NAME al\_set\_new\_display\_option - Allegro 5 API ## SYNOPSIS - ``` #include void al_set_new_display_option(int option, int value, int importance) ``` ## DESCRIPTION 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(3)](/al_get_display_option/3.md) 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(3)](/al_update_display_region/3.md) is equivalent to [al\_flip\_display(3)](/al_flip_display/3.md). - ALLEGRO\_VSYNC Set to 1 to tell the driver to wait for vsync in [al\_flip\_display(3)](/al_flip_display/3.md), 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(3)](/al_create_bitmap/3.md) or [al\_load\_bitmap(3)](/al_load_bitmap/3.md) 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(3)](/al_set_target_bitmap/3.md) 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(3)](/al_set_separate_blender/3.md) 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. Since: 5.1.0 - 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(3)](/al_get_display_orientation/3.md) 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(3) message which should be handled by calling [al\_acknowledge\_resize(3)](/al_acknowledge_resize/3.md). Since: 5.1.0 - ALLEGRO\_OPENGL\_MAJOR\_VERSION Request a specific OpenGL major version. Since: 5.1.13 - ALLEGRO\_OPENGL\_MINOR\_VERSION Request a specific OpenGL minor version. Since: 5.1.13 - ALLEGRO\_DEFAULT\_SHADER\_PLATFORM Specify the shader platform to use for the default shader. See [ALLEGRO\_SHADER\_PLATFORM(3)](/ALLEGRO_SHADER_PLATFORM/3.md). The default is ALLEGRO\_SHADER\_AUTO. Since: 5.2.8 ## SEE ALSO [al\_set\_new\_display\_flags(3)](/al_set_new_display_flags/3.md), [al\_get\_display\_option(3)](/al_get_display_option/3.md)