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

       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)