NAME

       al_set_new_display_option - Allegro 5 API

SYNOPSIS

              #include <allegro5/allegro.h>

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

              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

SEE ALSO

       al_set_new_display_flags(3alleg5), al_get_display_option(3alleg5)