1Name
2
3    MESA_screen_surface
4
5Name Strings
6
7    EGL_MESA_screen_surface
8
9Contact
10
11    Brian Paul
12
13    To discuss, join the dri-egl@lists.freedesktop.org list.
14
15Status
16
17    Obsolete.
18
19Version
20
21    11 (27 January 2006)
22
23Number
24
25    TBD
26
27Dependencies
28
29    EGL 1.0 or later.
30
31Overview
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
63Issues
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
250New 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
290New Types
291
292    EGLModeMESA
293    EGLScreenMESA
294
295New 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
318Additions 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
508Version 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