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 (a] lists.freedesktop.org list. 14 15 Status 16 17 Obsolete. 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 565
