src/egl/docs/EGL_MESA_screen_surface

   1 Name
   2
   3     MESA_screen_surface
   4
   5 Name Strings
   6
   7     EGL_MESA_screen_surface
   8
   9 Contact
  10
  11     Brian Paul
  12
  13     To discuss, join the dri-egl@lists.freedesktop.org list.
  14
  15 Status
  16
  17     Preliminary - totally subject to change.
  18
  19 Version
  20
  21     11 (27 January 2006)
  22
  23 Number
  24
  25     TBD
  26
  27 Dependencies
  28
  29     EGL 1.0 or later.
  30
  31 Overview
  32
  33     EGL 1.1 supports three types of drawing surfaces:
  34       * Window surfaces
  35       * Pixmap surfaces
  36       * Pbuffer surfaces
  37     This extension defines a fourth type of drawing surface:
  38       * Screen surface
  39
  40     A screen surface is a surface for which the (front) color buffer can
  41     be directly displayed (i.e. scanned out) on a monitor (such as a flat
  42     panel or CRT).  In particular the color buffer memory will be allocated
  43     at a location in VRAM (and in a suitable format) which can be displayed
  44     by the graphics hardware.
  45
  46     Note that the width and height of the screen surface need not exactly
  47     match the monitor's current resolution.  For example, while the monitor
  48     may be configured to to show 1024x768 pixels, the associated screen
  49     surface may be larger, such as 1200x1000.  The "screen origin" attribute
  50     will specify which region of the screen surface which is visible on the
  51     monitor.  The screen surface can be scrolled by changing this origin.
  52
  53     This extension also defines functions for controlling the monitor's
  54     display mode (width, height, refresh rate, etc), and specifing which
  55     screen surface is to be displayed on a monitor.
  56
  57     The new EGLModeMESA type and related functions are very similar to the
  58     EGLConfig type and related functions.  The user may get a list of
  59     supported modes for a screen and specify the mode to be used when
  60     displaying a screen surface.
  61
  62
  63 Issues
  64
  65     1. Should EGL_INTERLACE be a supported mode attribute?
  66
  67        Arguments against:
  68
  69            No, this should be provided by another extension which would
  70            also provide the mechanisms needed to play back interlaced video
  71            material correctly on hardware that supports it.
  72            This extension should prefer non-interlaced modes. [M. Danzer]
  73
  74        Arguments for:
  75
  76            An interlaced display can be of use without considering video
  77            material.  Being able to query whether a screen is operating in
  78            interlaced mode can be used by applications to control their
  79            drawing.  For example: avoid drawing 1-pixel-wide horizontal lines
  80            if screen is interlaced. [B. Paul]
  81
  82        Resolution: Defer for future extension?
  83
  84
  85     2. Should EGL_REFRESH_RATE be a supported mode attribute?
  86
  87        Arguments for:
  88
  89            Yes, it's been shown that applications and/or users need to select
  90            modes by this.  [M. Danzer]
  91
  92            Many examples have been given in which it's desirable to let the
  93            user choose from a variety of refresh rates without having to
  94            restart/reconfigure.  [B. Paul]
  95
  96        Arguments against:
  97
  98            TBD.
  99
 100        Resolution: Yes.
 101
 102
 103     3. Exactly how should the list of modes returned by eglChooseConfigMESA
 104        be sorted?
 105
 106        Current method is described in the text below.  Subject to change.
 107
 108        Alternately, leave the sorting order undefined so that each
 109        implementation can return the modes in order of "most desirable"
 110        to "least desirable" which may depend on the display technology
 111        (CRT vs LCD, etc) or other factors.
 112
 113
 114     4. How should screen blanking be supported?  Note that a screen can be
 115        disabled or turned off by calling eglShowSurface(dpy, scrn,
 116        EGL_NO_SURFACE, EGL_NO_MODE_MESA).  But what about power-save mode?
 117
 118        I would defer this to other extensions that depend on this one.
 119        I can imagine people wanting different semantics not just in
 120        relation to the power management API being exposed (DPMS or whatever)
 121        but also relating to what events can trigger EGL_CONTEXT_LOST.  Also
 122        I'm not sure whether power management commands are properly operations
 123        on the Display or on a screen surface. [A. Jackson]
 124
 125
 126     5. Should the EGL_PHYSICAL_SIZE_EGL query be kept?  The size information
 127        isn't always reliable (consider video projectors) but can still be
 128        used to determine the pixel aspect ratio.
 129
 130        Resolution: Omit.  The EGL 1.2 specification includes queries for
 131        the display resolution and pixel aspect ratio.
 132
 133
 134     6. Should detailed mode timing information be exposed by this API?
 135
 136        Probably not.  Instead, offer that information in a layered extension.
 137
 138
 139     7. How should the notion of a screen's "native" mode be expressed?
 140        For example, LCD panels have a native resolution and refresh rate
 141        that looks best but other sub-optimal resolutions may be supported.
 142
 143        The mode attribute EGL_OPTIMAL_MESA will be set for modes which
 144        best match the screen.  [M. Danzer]
 145
 146
 147     8. Should eglQueryModeStringMESA() be included?  This function returns
 148        a human-readable string which corresponds to an EGLMode.
 149
 150        Arguments for:
 151
 152            A mode name such as "HDTV-720P" might mean more to users than
 153            "1280x720@60Hz" if the later were generated via code.
 154
 155        Arguments against:
 156
 157            There's no standard syntax for the strings.  May cause more
 158            trouble than it's worth.
 159
 160        Postpone for future extension. [A. Jackson]
 161
 162        Latest discussion leaning toward omitting this function.
 163
 164
 165     9. Should we use "Get" or "Query" for functions which return state?
 166        The EGL 1.x specification doesn't seem to be totally consistent
 167        in this regard, but "Query" is used more often.
 168
 169        Use "Get" for mode-related queries (as for EGLConfigs) but "Query"
 170        for everything else.
 171
 172
 173     10. What should be the default size for screen surfaces?
 174
 175         For Pbuffer surfaces the default width and height are zero.
 176         We'll do the same for screen surfaces.  Since there's no function
 177         to resize surfaces it's useless to have a 0x0 screen, but this isn't
 178         a situation that'll normally be encountered.
 179
 180
 181     11. Should there be a function for resizing a screen surface?
 182
 183         Suppose one wants to change the screen's size in the EGL application.
 184         Also suppose there's a hardware restriction such that only one screen
 185         surface can exist at a time (either for lack of memory or because of
 186         memory layout restrictions).
 187
 188         The basic idea is that the currently displayed screen surface must
 189         be deallocated before a new one can be created.  Perhaps a resize
 190         function would work better?
 191
 192
 193     12. How should sub-pixel LCD color information be made available?
 194         What about the display's gamma value?
 195
 196         Perhaps expose as additional read-only mode attributes.
 197
 198         Perhaps postpone for a layered extension.
 199
 200
 201     13. What happens if the user attempts to delete a screen surface that
 202         is currently being shown?
 203
 204         Spec currently says that's illegal and that an error (TBD) will be
 205         generated.
 206
 207
 208     14. What if the physical screen size can't be determined?  Should
 209         a query of EGL_PHYSICAL_SIZE_MESA return [0,0]?
 210
 211         Obsolete: EGL_PHYSICAL_SIZE_MESA not used.
 212
 213
 214     15. Suppose the device's number of RAMDACs is different from the
 215         number of output ports.  For example, a graphics card with
 216         two RAMDACs but three ports (VGA, DVI, TV).
 217
 218         Address this in a follow-on extension. [Matthias Hopf]
 219
 220
 221     16. How should we deal with on-the-fly device changes?  For example,
 222         the monitor being unplugged and replaced by another with different
 223         characteristics?
 224
 225         A HAL event could be received via DBUS in the application [J. Smirl,
 226         A. Jackson].
 227
 228         Should there be an EGL mechanism for detecting this?  Maybe an
 229         EGL_SCREEN_LOST error (similar to EGL_CONTEXT_LOST) can be recorded
 230         when there's a screen change.  At least then the application can
 231         poll to detect this situation.
 232
 233         Maybe leave that to a future extension.
 234
 235         See also the EGL_SCREEN_COUNT_MESA query.
 236
 237
 238     17. What if pixel-accurate panning is not supported (see
 239         eglScreenPositionMESA)? [M. Danzer]
 240
 241         Is this a common problem?  Can we ignore it for now?
 242
 243
 244     18. Should eglShowSurfaceMESA be renamed to eglShowScreenSurfaceMESA?
 245
 246         Probably.
 247
 248
 249
 250 New Procedures and Functions
 251
 252     EGLBoolean eglChooseModeMESA(EGLDisplay dpy, EGLScreenMESA screen,
 253                                  const EGLint *attrib_list,
 254                                  EGLModeMESA *modes, EGLint modes_size,
 255                                  EGLint *num_modes)
 256
 257     EGLBoolean eglGetModesMESA(EGLDisplay dpy, EGLScreenMESA screen,
 258                                EGLModeMESA *modes, EGLint modes_size,
 259                                EGLint *num_modes)
 260
 261     EGLBoolean eglGetModeAttribMESA(EGLDisplay dpy, EGLModeMESA mode,
 262                                     EGLint attrib, EGLint *value)
 263
 264
 265     EGLBoolean eglGetScreensMESA(EGLDisplay dpy, EGLScreenMESA *screens,
 266                                  EGLint screens_size, EGLint *num_screens)
 267
 268     EGLSurface eglCreateScreenSurfaceMESA(EGLDisplay dpy, EGLConfig config,
 269                                           const EGLint *attrib_list)
 270
 271     EGLBoolean eglShowSurfaceMESA(EGLDisplay dpy, EGLScreenMESA screen,
 272                                   EGLSurface surface, EGLModeMESA mode)
 273
 274     EGLBoolean eglScreenPositionMESA(EGLDisplay dpy, EGLScreenMESA screen,
 275                                      EGLint x, EGLint y)
 276
 277
 278     EGLBoolean eglQueryScreenMESA(EGLDisplay dpy, EGLScreenMESA screen,
 279                                   EGLint attrib, EGLint *value);
 280
 281     EGLBoolean eglQueryScreenSurfaceMESA(EGLDisplay dpy, EGLScreenMESA screen,
 282                                          EGLSurface *surface)
 283
 284     EGLBoolean eglQueryScreenModeMESA(EGLDisplay dpy, EGLScreenMESA screen,
 285                                       EGLModeMESA *mode)
 286
 287     const char *eglQueryModeStringMESA(EGLDisplay dpy, EGLMode mode);
 288
 289
 290 New Types
 291
 292     EGLModeMESA
 293     EGLScreenMESA
 294
 295 New Tokens
 296
 297     New error codes:
 298
 299     EGL_BAD_SCREEN_MESA
 300     EGL_BAD_MODE_MESA
 301
 302     Screen-related tokens:
 303
 304     EGL_SCREEN_COUNT_MESA
 305     EGL_SCREEN_POSITION_MESA
 306     EGL_SCREEN_BIT_MESA
 307     EGL_SCREEN_POSITION_GRANULARITY_MESA
 308
 309     Mode-related tokens:
 310
 311     EGL_MODE_ID_MESA
 312     EGL_REFRESH_RATE_MESA
 313     EGL_INTERLACED_MESA
 314     EGL_OPTIMAL_MESA
 315     EGL_NO_MODE_MESA
 316
 317
 318 Additions to Chapter X of the EGL 1.1 Specification
 319
 320     [XXX this all has to be rewritten to fit into the EGL specification
 321     and match the conventions of an EGL extension.  For now, just list
 322     all the functions with brief descriptions.]
 323
 324
 325     EGLBoolean eglChooseModeMESA(EGLDisplay dpy, const EGLScreenMESA screen,
 326                                  EGLint *attrib_list, EGLModeMESA *modes,
 327                                  EGLint modes_size, EGLint *num_modes)
 328
 329     Like eglChooseConfig, returns a list of EGLModes which match the given
 330     attribute list.  This does not set the screen's current display mode.
 331     The attribute list is a list of token/value pairs terminated with
 332     EGL_NONE.  Supported attributes include:
 333
 334         Name                   Description
 335         ---------------------  ---------------------------------------------
 336         EGL_WIDTH              Mode width (resolution)
 337         EGL_HEIGHT             Mode height (resolution)
 338         EGL_REFRESH_RATE_MESA  The mode's refresh rate, multiplied by 1000
 339         EGL_INTERLACED_MESA    1 indicates an interlaced mode, 0 otherwise
 340         EGL_OPTIMAL_MESA       Set if the most is especially optimal for the
 341                                screen (ex. for particular LCD resolutions)
 342
 343     Any other token will generate the error EGL_BAD_ATTRIBUTE.
 344
 345     The list of modes returned by eglChooseModeMESA will be sorted
 346     according to the following criteria.  See the discussion of table 3.3
 347     in the EGL specification for more information.
 348
 349                                             Selection   Sort   Sort
 350         Attribute            Default        Criteria    Order  Priority
 351         -------------------- -------------- ----------- ------ --------
 352         EGL_OPTIMAL_MESA     EGL_DONT_CARE  Exact       1,0      1
 353         EGL_INTERLACED_MESA  EGL_DONT_CARE  Exact       0,1      2
 354         EGL_REFRESH_RATE     EGL_DONT_CARE  AtLeast     Larger   3
 355         EGL_WIDTH            EGL_DONT_CARE  AtLeast     Larger   4
 356         EGL_HEIGHT           EGL_DONT_CARE  AtLeast     Larger   5
 357         EGL_MODE_ID_MESA     EGL_DONT_CARE  Exact       Smaller  6
 358
 359
 360     EGLBoolean eglGetModesMESA(EGLDisplay dpy, EGLScreenMESA screen,
 361                                EGLModeMESA *modes, EGLint modes_size,
 362                                EGLint *num_modes)
 363
 364     Like eglGetConfigs, returns a list of all modes supported by the
 365     given screen.  The returned modes will be sorted in the same manner
 366     as for eglChooseModeMESA().
 367
 368
 369
 370     EGLBoolean eglGetModeAttribMESA(EGLDisplay dpy, EGLModeMESA mode,
 371                                     EGLint attrib, EGLint *value)
 372
 373     Used to query mode attributes.  The following attributes are supported:
 374
 375         Name                   Return value description
 376         ---------------------  ----------------------------------------------
 377         EGL_OPTIMAL_MESA       1 indicates an optimal mode, 0 otherwise
 378         EGL_INTERLACED_MESA    1 indicates an interlaced mode, 0 otherwise
 379         EGL_REFRESH_RATE_MESA  The mode's refresh rate, multiplied by 1000
 380         EGL_WIDTH              Mode width (resolution)
 381         EGL_HEIGHT             Mode height (resolution)
 382         EGL_MODE_ID_MESA       A unique small integer identifier for the mode
 383
 384     Any other token will generate the error EGL_BAD_ATTRIBUTE.
 385
 386
 387
 388     EGLBoolean eglGetScreensMESA(EGLDisplay dpy, EGLScreenMESA *screens,
 389                                  EGLint screens_size, EGLint *num_screens)
 390
 391     This function returns an array of all available screen handles.
 392     <screens_size> is the maximum number of screens to return in the
 393     <screens> array.  <num_screens> will return the number of screen handles
 394     placed in the array, even if <screens> is NULL.
 395
 396     The number of screens and the availability of each may change over
 397     time (hot-plugging).  Screen handles will not be reused.  When a
 398     screen handle becomes invalid, function calls which reference an
 399     invalid handle will generate EGL_BAD_SCREEN_MESA.
 400
 401     The first screen handle returned will be considered to be the primary
 402     one.
 403
 404
 405
 406     EGLSurface eglCreateScreenSurfaceMESA(EGLDisplay dpy, EGLConfig config,
 407                                           const EGLint *attrib_list)
 408
 409     Create a surface that can be displayed on a screen.  <attrib_list> is
 410     an array of token/value pairs terminated with EGL_NONE.  Valid tokens
 411     include:
 412
 413         Name              Description
 414         ----------------  --------------------------------
 415         EGL_WIDTH         desired surface width in pixels
 416         EGL_HEIGHT        desired surface height in pixels
 417
 418     Any other token will generate the error EGL_BAD_ATTRIBUTE.
 419     The default width and height are zero.
 420
 421
 422
 423     EGLBoolean eglShowSurfaceMESA(EGLDisplay dpy, EGLScreenMESA screen,
 424                                   EGLSurface surface, EGLModeMESA mode)
 425
 426     This function causes a screen to show the given surface (or more
 427     precisely, the surface's front color buffer) with the given mode.
 428
 429     If the surface is in any way incompatible with the mode, the error
 430     EGL_BAD_MATCH will be generated, EGL_FALSE will be returned, and the
 431     previous screen state will remain in effect.  This might occur when
 432     the bandwidth of the video-out subsystem is exceeded, or if the mode
 433     specifies a width or height that's greater than the width or height
 434     of the surface.
 435
 436     To disable a screen, the values EGL_NO_SURFACE and EGL_NO_MODE_MESA
 437     be passed as the <surface> and <mode> parameters.
 438
 439     The values of EGL_SCREEN_POSITION_MESA are clamped to the new valid
 440     range computed from the screen size and surface size.  If the new
 441     surface is EGL_NO_SURFACE, EGL_SCREEN_POSITION_MESA is set to [0, 0].
 442
 443
 444     Attempting to delete a screen surface which is currently being
 445     displayed will result in the error EGL_BAD_ACCESS being generated.
 446
 447
 448
 449     EGLBoolean eglScreenPositionMESA(EGLDisplay dpy, EGLScreenMESA screen,
 450                                      EGLint x, EGLint y)
 451
 452     Specifies the origin of the screen's view into the surface, if the
 453     surface is larger than the screen.  Valid values for x and y are
 454     [0, surfaceWidth - screenWidth] and [0, surfaceHeight - screenHeight],
 455     respectively.
 456
 457     The x and y values are also constrained to be integer multiples of the
 458     EGL_SCREEN_POSITION_GRANULARITY_MESA values.
 459
 460
 461
 462
 463     EGLBoolean eglQueryScreenMESA(EGLDisplay dpy, EGLScreenMESA screen,
 464                                   EGLint attrib, EGLint *value);
 465
 466     Used to query screen attributes.  <attrib> may be one of the following:
 467
 468         Name                      Return value description
 469         ------------------------  ---------------------------------------------
 470         EGL_SCREEN_POSITION_MESA  x, y position of the screen's origin with
 471                                   respect to the surface.  If no surface is
 472                                   attached to the screen, [0, 0] is returned.
 473         EGL_SCREEN_POSITION_GRANULARITY_MESA
 474                                   Returns the granularity, in pixels, for
 475                                   which the screen position is constrained.
 476
 477     Any other token will generate the error EGL_BAD_ATTRIBUTE.
 478
 479
 480
 481
 482     EGLBoolean eglQueryScreenSurfaceMESA(EGLDisplay dpy, EGLScreenMESA screen,
 483                                          EGLSurface *surface)
 484
 485     Returns the surface currently displayed on the given screen.  <surface>
 486     may be EGL_NO_SURFACE if the screen isn't currently showing any surface.
 487
 488
 489
 490
 491     EGLBoolean eglQueryScreenModeMESA(EGLDisplay dpy, EGLScreenMESA screen,
 492                                       EGLModeMESA *mode)
 493
 494     Returns the given screen's current display mode.  The mode may be
 495     EGL_NO_MODE_MESA if the screen is currently disabled.
 496
 497
 498
 499     const char *eglQueryModeStringMESA(EGLDisplay dpy, EGLModeMESA mode);
 500
 501     Returns a human-readable string for the given mode.  The string is a
 502     zero-terminated C string which the user should not attempt to free.
 503     There is no standard syntax for mode strings.  Applications should
 504     not directly rely on mode strings.
 505
 506
 507
 508 Version History
 509
 510     1. 15 March 2005 - BrianP
 511         Initial version
 512
 513     2. 16 March 2005 - BrianP
 514         Removed EGL_DEPTH_MESA
 515         Added EGL_PHYSICAL_WIDTH_MESA, EGL_PHYSICAL_HEIGHT_MESA queries
 516         Added EGL_OPTIMAL_MESA for width/height/refresh rate selection
 517         Added possible eglQueryModeStringMESA() function
 518         More details of the new functions explained.
 519
 520     3. 18 March 2005 - BrianP
 521         Added screen_number to eglChooseModeMESA().
 522         Fix off by one mistake in value range for ORIGIN attributes
 523         Added Issues section
 524
 525     4. 21 March 2005 - BrianP
 526         Removed eglScreenAttribsMESA().
 527         Added eglScreenPositionMESA() to set screen origin.
 528         Replaced EGL_SCREEN_X/Y_OFFSET_MESA with EGL_SCREEN_POSITION_MESA.
 529         Replaced EGL_PHYSICAL_WIDTH/HEIGHT_MESA with EGL_PHYSICAL_SIZE_MESA.
 530         Use EGL_OPTIMAL_MESA as a new mode attribute. (Michel Danzer)
 531         Added a few more issues.
 532
 533     5. 6 April 2005 - BrianP
 534         More language for eglGetModeStringMESA().
 535         Added issues 10, 11, 12, 13, 14.
 536         Updated issue 3 discussion about mode sorting.
 537
 538     6. 22 April 2005 - BrianP
 539         Fixed "LDC" typo.
 540         Added issues 15, 16.
 541         Changed dependency on EGL 1.1 to EGL 1.0
 542         s/EGL_NUM_SCREENS_MESA/EGL_SCREEN_COUNT_MESA/
 543         Added eglQueryDisplayMESA() to New Functions section.
 544         Clarified language for the EGL_SCREEN_COUNT_MESA query.
 545
 546     7. 29 April 2005 - BrianP
 547         Added EGLScreenMESA type and eglGetScreensMESA() function. [J. Smirl].
 548         Replaced EGLint screen_number parameters with EGLScreenMESA screen.
 549         Added issue 17 (pixel-accurate panning)
 550
 551     8. 2 May 2005 - BrianP
 552         Removed eglQueryDisplayMESA.
 553         Fixed a few more EGLint -> EGLScreenMESA changes.
 554
 555     9. 20 May 2005 - BrianP
 556         Fixed a few typos.
 557         Updated some open issues text.
 558
 559     10. 10 August 2005 - BrianP
 560         Added EGL_SCREEN_POSITION_GRANULARITY_MESA.
 561
 562     11. 27 January 2006 - BrianP
 563         EGL_PHYSICAL_SIZE_MESA removed since EGL 1.2 has a similar feature.
 564