al_set_new_display_option(3alleg5)

✨ al_set_new_display_option ✨

okay bestie, welcome to the Allegro 5 API manual page for al_set_new_display_option, and yes we are going to make display options make sense together 💖

---

🌸 SYNOPSIS 🌸

#include <allegro5/allegro.h>

void al_set_new_display_option(int option, int value, int importance)

---

💅 DESCRIPTION 💅

So basically, this function sets an extra display option that gets used whenever you create new displays on the thread you're calling it from. 🫶

Quick vibe check: display options are not the same thing as display flags, okay? Options are about the fine details of the context that gets created inside the window itself. Most of the time Allegro doesn't care about them at all — they're just you telling the driver what you want. Like, say you're obsessed with multisampling? This is where you ask for it. ✨

🎀 the importance parameter 🎀

It can be one of these three, and honestly this is the part that matters most:

• ALLEGRO_REQUIRE — bestie, this is the strict one. If the setting can't be met, the display will not be created. Periodt. 💀
• ALLEGRO_SUGGEST — the chill one. If your setting isn't available, the display gets created anyway with a setting as close as possible to what you asked for. You can peek at what you actually got by calling al_get_display_option(3alleg5) after the display exists. 👀
• ALLEGRO_DONTCARE — if you'd previously added a display option with one of the two settings above, it gets removed again. Otherwise this does literally nothing. 🙈

👑 the supported options 👑

These are the options you can pass, and no we are not skipping a single one:

• ALLEGRO_COLOR_SIZE — ask for a specific bit depth. Like, to force a 16-bit framebuffer, set this to 16. 🎨
• ALLEGRO_RED_SIZE, ALLEGRO_GREEN_SIZE, ALLEGRO_BLUE_SIZE, ALLEGRO_ALPHA_SIZE — the size in bits of each individual color component.
• ALLEGRO_RED_SHIFT, ALLEGRO_GREEN_SHIFT, ALLEGRO_BLUE_SHIFT, ALLEGRO_ALPHA_SHIFT — together with the previous settings, these let you specify the exact pixel layout the display should use. Normally there is no reason to use these. Like, none. Leave them alone bestie. 🙏
• ALLEGRO_ACC_RED_SIZE, ALLEGRO_ACC_GREEN_SIZE, ALLEGRO_ACC_BLUE_SIZE, ALLEGRO_ACC_ALPHA_SIZE — define the required accumulation buffer size. 🧚
• ALLEGRO_STEREO — whether the display is a stereo display.
• ALLEGRO_AUX_BUFFERS — how many 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, this is 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. And if you request a display that isn't useable by Allegro, you can still use, for example, OpenGL to draw graphics. slay 🔥
• 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 Allegro does not try to modify the vsync behavior, so it may be on or off. 👀

Heads up: 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. No cap.

• 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, since 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. ✨

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(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. 👑

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(3alleg5). The default is ALLEGRO_SHADER_AUTO. 🌟

Since: 5.2.8

---

🦋 SEE ALSO 🦋

• al_set_new_display_flags(3alleg5)
• al_get_display_option(3alleg5)

---

and that's the whole page bestie, you ate 💅✨ this one's from the Allegro reference manual, page al_set_new_display_option(3alleg5) — go forth and configure your displays, ily, bye 🎀🫶