0,0 → 1,564 |
Name |
|
MESA_screen_surface |
|
Name Strings |
|
EGL_MESA_screen_surface |
|
Contact |
|
Brian Paul |
|
To discuss, join the dri-egl@lists.freedesktop.org list. |
|
Status |
|
Obsolete. |
|
Version |
|
11 (27 January 2006) |
|
Number |
|
TBD |
|
Dependencies |
|
EGL 1.0 or later. |
|
Overview |
|
EGL 1.1 supports three types of drawing surfaces: |
* Window surfaces |
* Pixmap surfaces |
* Pbuffer surfaces |
This extension defines a fourth type of drawing surface: |
* Screen surface |
|
A screen surface is a surface for which the (front) color buffer can |
be directly displayed (i.e. scanned out) on a monitor (such as a flat |
panel or CRT). In particular the color buffer memory will be allocated |
at a location in VRAM (and in a suitable format) which can be displayed |
by the graphics hardware. |
|
Note that the width and height of the screen surface need not exactly |
match the monitor's current resolution. For example, while the monitor |
may be configured to to show 1024x768 pixels, the associated screen |
surface may be larger, such as 1200x1000. The "screen origin" attribute |
will specify which region of the screen surface which is visible on the |
monitor. The screen surface can be scrolled by changing this origin. |
|
This extension also defines functions for controlling the monitor's |
display mode (width, height, refresh rate, etc), and specifing which |
screen surface is to be displayed on a monitor. |
|
The new EGLModeMESA type and related functions are very similar to the |
EGLConfig type and related functions. The user may get a list of |
supported modes for a screen and specify the mode to be used when |
displaying a screen surface. |
|
|
Issues |
|
1. Should EGL_INTERLACE be a supported mode attribute? |
|
Arguments against: |
|
No, this should be provided by another extension which would |
also provide the mechanisms needed to play back interlaced video |
material correctly on hardware that supports it. |
This extension should prefer non-interlaced modes. [M. Danzer] |
|
Arguments for: |
|
An interlaced display can be of use without considering video |
material. Being able to query whether a screen is operating in |
interlaced mode can be used by applications to control their |
drawing. For example: avoid drawing 1-pixel-wide horizontal lines |
if screen is interlaced. [B. Paul] |
|
Resolution: Defer for future extension? |
|
|
2. Should EGL_REFRESH_RATE be a supported mode attribute? |
|
Arguments for: |
|
Yes, it's been shown that applications and/or users need to select |
modes by this. [M. Danzer] |
|
Many examples have been given in which it's desirable to let the |
user choose from a variety of refresh rates without having to |
restart/reconfigure. [B. Paul] |
|
Arguments against: |
|
TBD. |
|
Resolution: Yes. |
|
|
3. Exactly how should the list of modes returned by eglChooseConfigMESA |
be sorted? |
|
Current method is described in the text below. Subject to change. |
|
Alternately, leave the sorting order undefined so that each |
implementation can return the modes in order of "most desirable" |
to "least desirable" which may depend on the display technology |
(CRT vs LCD, etc) or other factors. |
|
|
4. How should screen blanking be supported? Note that a screen can be |
disabled or turned off by calling eglShowSurface(dpy, scrn, |
EGL_NO_SURFACE, EGL_NO_MODE_MESA). But what about power-save mode? |
|
I would defer this to other extensions that depend on this one. |
I can imagine people wanting different semantics not just in |
relation to the power management API being exposed (DPMS or whatever) |
but also relating to what events can trigger EGL_CONTEXT_LOST. Also |
I'm not sure whether power management commands are properly operations |
on the Display or on a screen surface. [A. Jackson] |
|
|
5. Should the EGL_PHYSICAL_SIZE_EGL query be kept? The size information |
isn't always reliable (consider video projectors) but can still be |
used to determine the pixel aspect ratio. |
|
Resolution: Omit. The EGL 1.2 specification includes queries for |
the display resolution and pixel aspect ratio. |
|
|
6. Should detailed mode timing information be exposed by this API? |
|
Probably not. Instead, offer that information in a layered extension. |
|
|
7. How should the notion of a screen's "native" mode be expressed? |
For example, LCD panels have a native resolution and refresh rate |
that looks best but other sub-optimal resolutions may be supported. |
|
The mode attribute EGL_OPTIMAL_MESA will be set for modes which |
best match the screen. [M. Danzer] |
|
|
8. Should eglQueryModeStringMESA() be included? This function returns |
a human-readable string which corresponds to an EGLMode. |
|
Arguments for: |
|
A mode name such as "HDTV-720P" might mean more to users than |
"1280x720@60Hz" if the later were generated via code. |
|
Arguments against: |
|
There's no standard syntax for the strings. May cause more |
trouble than it's worth. |
|
Postpone for future extension. [A. Jackson] |
|
Latest discussion leaning toward omitting this function. |
|
|
9. Should we use "Get" or "Query" for functions which return state? |
The EGL 1.x specification doesn't seem to be totally consistent |
in this regard, but "Query" is used more often. |
|
Use "Get" for mode-related queries (as for EGLConfigs) but "Query" |
for everything else. |
|
|
10. What should be the default size for screen surfaces? |
|
For Pbuffer surfaces the default width and height are zero. |
We'll do the same for screen surfaces. Since there's no function |
to resize surfaces it's useless to have a 0x0 screen, but this isn't |
a situation that'll normally be encountered. |
|
|
11. Should there be a function for resizing a screen surface? |
|
Suppose one wants to change the screen's size in the EGL application. |
Also suppose there's a hardware restriction such that only one screen |
surface can exist at a time (either for lack of memory or because of |
memory layout restrictions). |
|
The basic idea is that the currently displayed screen surface must |
be deallocated before a new one can be created. Perhaps a resize |
function would work better? |
|
|
12. How should sub-pixel LCD color information be made available? |
What about the display's gamma value? |
|
Perhaps expose as additional read-only mode attributes. |
|
Perhaps postpone for a layered extension. |
|
|
13. What happens if the user attempts to delete a screen surface that |
is currently being shown? |
|
Spec currently says that's illegal and that an error (TBD) will be |
generated. |
|
|
14. What if the physical screen size can't be determined? Should |
a query of EGL_PHYSICAL_SIZE_MESA return [0,0]? |
|
Obsolete: EGL_PHYSICAL_SIZE_MESA not used. |
|
|
15. Suppose the device's number of RAMDACs is different from the |
number of output ports. For example, a graphics card with |
two RAMDACs but three ports (VGA, DVI, TV). |
|
Address this in a follow-on extension. [Matthias Hopf] |
|
|
16. How should we deal with on-the-fly device changes? For example, |
the monitor being unplugged and replaced by another with different |
characteristics? |
|
A HAL event could be received via DBUS in the application [J. Smirl, |
A. Jackson]. |
|
Should there be an EGL mechanism for detecting this? Maybe an |
EGL_SCREEN_LOST error (similar to EGL_CONTEXT_LOST) can be recorded |
when there's a screen change. At least then the application can |
poll to detect this situation. |
|
Maybe leave that to a future extension. |
|
See also the EGL_SCREEN_COUNT_MESA query. |
|
|
17. What if pixel-accurate panning is not supported (see |
eglScreenPositionMESA)? [M. Danzer] |
|
Is this a common problem? Can we ignore it for now? |
|
|
18. Should eglShowSurfaceMESA be renamed to eglShowScreenSurfaceMESA? |
|
Probably. |
|
|
|
New Procedures and Functions |
|
EGLBoolean eglChooseModeMESA(EGLDisplay dpy, EGLScreenMESA screen, |
const EGLint *attrib_list, |
EGLModeMESA *modes, EGLint modes_size, |
EGLint *num_modes) |
|
EGLBoolean eglGetModesMESA(EGLDisplay dpy, EGLScreenMESA screen, |
EGLModeMESA *modes, EGLint modes_size, |
EGLint *num_modes) |
|
EGLBoolean eglGetModeAttribMESA(EGLDisplay dpy, EGLModeMESA mode, |
EGLint attrib, EGLint *value) |
|
|
EGLBoolean eglGetScreensMESA(EGLDisplay dpy, EGLScreenMESA *screens, |
EGLint screens_size, EGLint *num_screens) |
|
EGLSurface eglCreateScreenSurfaceMESA(EGLDisplay dpy, EGLConfig config, |
const EGLint *attrib_list) |
|
EGLBoolean eglShowSurfaceMESA(EGLDisplay dpy, EGLScreenMESA screen, |
EGLSurface surface, EGLModeMESA mode) |
|
EGLBoolean eglScreenPositionMESA(EGLDisplay dpy, EGLScreenMESA screen, |
EGLint x, EGLint y) |
|
|
EGLBoolean eglQueryScreenMESA(EGLDisplay dpy, EGLScreenMESA screen, |
EGLint attrib, EGLint *value); |
|
EGLBoolean eglQueryScreenSurfaceMESA(EGLDisplay dpy, EGLScreenMESA screen, |
EGLSurface *surface) |
|
EGLBoolean eglQueryScreenModeMESA(EGLDisplay dpy, EGLScreenMESA screen, |
EGLModeMESA *mode) |
|
const char *eglQueryModeStringMESA(EGLDisplay dpy, EGLMode mode); |
|
|
New Types |
|
EGLModeMESA |
EGLScreenMESA |
|
New Tokens |
|
New error codes: |
|
EGL_BAD_SCREEN_MESA |
EGL_BAD_MODE_MESA |
|
Screen-related tokens: |
|
EGL_SCREEN_COUNT_MESA |
EGL_SCREEN_POSITION_MESA |
EGL_SCREEN_BIT_MESA |
EGL_SCREEN_POSITION_GRANULARITY_MESA |
|
Mode-related tokens: |
|
EGL_MODE_ID_MESA |
EGL_REFRESH_RATE_MESA |
EGL_INTERLACED_MESA |
EGL_OPTIMAL_MESA |
EGL_NO_MODE_MESA |
|
|
Additions to Chapter X of the EGL 1.1 Specification |
|
[XXX this all has to be rewritten to fit into the EGL specification |
and match the conventions of an EGL extension. For now, just list |
all the functions with brief descriptions.] |
|
|
EGLBoolean eglChooseModeMESA(EGLDisplay dpy, const EGLScreenMESA screen, |
EGLint *attrib_list, EGLModeMESA *modes, |
EGLint modes_size, EGLint *num_modes) |
|
Like eglChooseConfig, returns a list of EGLModes which match the given |
attribute list. This does not set the screen's current display mode. |
The attribute list is a list of token/value pairs terminated with |
EGL_NONE. Supported attributes include: |
|
Name Description |
--------------------- --------------------------------------------- |
EGL_WIDTH Mode width (resolution) |
EGL_HEIGHT Mode height (resolution) |
EGL_REFRESH_RATE_MESA The mode's refresh rate, multiplied by 1000 |
EGL_INTERLACED_MESA 1 indicates an interlaced mode, 0 otherwise |
EGL_OPTIMAL_MESA Set if the most is especially optimal for the |
screen (ex. for particular LCD resolutions) |
|
Any other token will generate the error EGL_BAD_ATTRIBUTE. |
|
The list of modes returned by eglChooseModeMESA will be sorted |
according to the following criteria. See the discussion of table 3.3 |
in the EGL specification for more information. |
|
Selection Sort Sort |
Attribute Default Criteria Order Priority |
-------------------- -------------- ----------- ------ -------- |
EGL_OPTIMAL_MESA EGL_DONT_CARE Exact 1,0 1 |
EGL_INTERLACED_MESA EGL_DONT_CARE Exact 0,1 2 |
EGL_REFRESH_RATE EGL_DONT_CARE AtLeast Larger 3 |
EGL_WIDTH EGL_DONT_CARE AtLeast Larger 4 |
EGL_HEIGHT EGL_DONT_CARE AtLeast Larger 5 |
EGL_MODE_ID_MESA EGL_DONT_CARE Exact Smaller 6 |
|
|
EGLBoolean eglGetModesMESA(EGLDisplay dpy, EGLScreenMESA screen, |
EGLModeMESA *modes, EGLint modes_size, |
EGLint *num_modes) |
|
Like eglGetConfigs, returns a list of all modes supported by the |
given screen. The returned modes will be sorted in the same manner |
as for eglChooseModeMESA(). |
|
|
|
EGLBoolean eglGetModeAttribMESA(EGLDisplay dpy, EGLModeMESA mode, |
EGLint attrib, EGLint *value) |
|
Used to query mode attributes. The following attributes are supported: |
|
Name Return value description |
--------------------- ---------------------------------------------- |
EGL_OPTIMAL_MESA 1 indicates an optimal mode, 0 otherwise |
EGL_INTERLACED_MESA 1 indicates an interlaced mode, 0 otherwise |
EGL_REFRESH_RATE_MESA The mode's refresh rate, multiplied by 1000 |
EGL_WIDTH Mode width (resolution) |
EGL_HEIGHT Mode height (resolution) |
EGL_MODE_ID_MESA A unique small integer identifier for the mode |
|
Any other token will generate the error EGL_BAD_ATTRIBUTE. |
|
|
|
EGLBoolean eglGetScreensMESA(EGLDisplay dpy, EGLScreenMESA *screens, |
EGLint screens_size, EGLint *num_screens) |
|
This function returns an array of all available screen handles. |
<screens_size> is the maximum number of screens to return in the |
<screens> array. <num_screens> will return the number of screen handles |
placed in the array, even if <screens> is NULL. |
|
The number of screens and the availability of each may change over |
time (hot-plugging). Screen handles will not be reused. When a |
screen handle becomes invalid, function calls which reference an |
invalid handle will generate EGL_BAD_SCREEN_MESA. |
|
The first screen handle returned will be considered to be the primary |
one. |
|
|
|
EGLSurface eglCreateScreenSurfaceMESA(EGLDisplay dpy, EGLConfig config, |
const EGLint *attrib_list) |
|
Create a surface that can be displayed on a screen. <attrib_list> is |
an array of token/value pairs terminated with EGL_NONE. Valid tokens |
include: |
|
Name Description |
---------------- -------------------------------- |
EGL_WIDTH desired surface width in pixels |
EGL_HEIGHT desired surface height in pixels |
|
Any other token will generate the error EGL_BAD_ATTRIBUTE. |
The default width and height are zero. |
|
|
|
EGLBoolean eglShowSurfaceMESA(EGLDisplay dpy, EGLScreenMESA screen, |
EGLSurface surface, EGLModeMESA mode) |
|
This function causes a screen to show the given surface (or more |
precisely, the surface's front color buffer) with the given mode. |
|
If the surface is in any way incompatible with the mode, the error |
EGL_BAD_MATCH will be generated, EGL_FALSE will be returned, and the |
previous screen state will remain in effect. This might occur when |
the bandwidth of the video-out subsystem is exceeded, or if the mode |
specifies a width or height that's greater than the width or height |
of the surface. |
|
To disable a screen, the values EGL_NO_SURFACE and EGL_NO_MODE_MESA |
be passed as the <surface> and <mode> parameters. |
|
The values of EGL_SCREEN_POSITION_MESA are clamped to the new valid |
range computed from the screen size and surface size. If the new |
surface is EGL_NO_SURFACE, EGL_SCREEN_POSITION_MESA is set to [0, 0]. |
|
|
Attempting to delete a screen surface which is currently being |
displayed will result in the error EGL_BAD_ACCESS being generated. |
|
|
|
EGLBoolean eglScreenPositionMESA(EGLDisplay dpy, EGLScreenMESA screen, |
EGLint x, EGLint y) |
|
Specifies the origin of the screen's view into the surface, if the |
surface is larger than the screen. Valid values for x and y are |
[0, surfaceWidth - screenWidth] and [0, surfaceHeight - screenHeight], |
respectively. |
|
The x and y values are also constrained to be integer multiples of the |
EGL_SCREEN_POSITION_GRANULARITY_MESA values. |
|
|
|
|
EGLBoolean eglQueryScreenMESA(EGLDisplay dpy, EGLScreenMESA screen, |
EGLint attrib, EGLint *value); |
|
Used to query screen attributes. <attrib> may be one of the following: |
|
Name Return value description |
------------------------ --------------------------------------------- |
EGL_SCREEN_POSITION_MESA x, y position of the screen's origin with |
respect to the surface. If no surface is |
attached to the screen, [0, 0] is returned. |
EGL_SCREEN_POSITION_GRANULARITY_MESA |
Returns the granularity, in pixels, for |
which the screen position is constrained. |
|
Any other token will generate the error EGL_BAD_ATTRIBUTE. |
|
|
|
|
EGLBoolean eglQueryScreenSurfaceMESA(EGLDisplay dpy, EGLScreenMESA screen, |
EGLSurface *surface) |
|
Returns the surface currently displayed on the given screen. <surface> |
may be EGL_NO_SURFACE if the screen isn't currently showing any surface. |
|
|
|
|
EGLBoolean eglQueryScreenModeMESA(EGLDisplay dpy, EGLScreenMESA screen, |
EGLModeMESA *mode) |
|
Returns the given screen's current display mode. The mode may be |
EGL_NO_MODE_MESA if the screen is currently disabled. |
|
|
|
const char *eglQueryModeStringMESA(EGLDisplay dpy, EGLModeMESA mode); |
|
Returns a human-readable string for the given mode. The string is a |
zero-terminated C string which the user should not attempt to free. |
There is no standard syntax for mode strings. Applications should |
not directly rely on mode strings. |
|
|
|
Version History |
|
1. 15 March 2005 - BrianP |
Initial version |
|
2. 16 March 2005 - BrianP |
Removed EGL_DEPTH_MESA |
Added EGL_PHYSICAL_WIDTH_MESA, EGL_PHYSICAL_HEIGHT_MESA queries |
Added EGL_OPTIMAL_MESA for width/height/refresh rate selection |
Added possible eglQueryModeStringMESA() function |
More details of the new functions explained. |
|
3. 18 March 2005 - BrianP |
Added screen_number to eglChooseModeMESA(). |
Fix off by one mistake in value range for ORIGIN attributes |
Added Issues section |
|
4. 21 March 2005 - BrianP |
Removed eglScreenAttribsMESA(). |
Added eglScreenPositionMESA() to set screen origin. |
Replaced EGL_SCREEN_X/Y_OFFSET_MESA with EGL_SCREEN_POSITION_MESA. |
Replaced EGL_PHYSICAL_WIDTH/HEIGHT_MESA with EGL_PHYSICAL_SIZE_MESA. |
Use EGL_OPTIMAL_MESA as a new mode attribute. (Michel Danzer) |
Added a few more issues. |
|
5. 6 April 2005 - BrianP |
More language for eglGetModeStringMESA(). |
Added issues 10, 11, 12, 13, 14. |
Updated issue 3 discussion about mode sorting. |
|
6. 22 April 2005 - BrianP |
Fixed "LDC" typo. |
Added issues 15, 16. |
Changed dependency on EGL 1.1 to EGL 1.0 |
s/EGL_NUM_SCREENS_MESA/EGL_SCREEN_COUNT_MESA/ |
Added eglQueryDisplayMESA() to New Functions section. |
Clarified language for the EGL_SCREEN_COUNT_MESA query. |
|
7. 29 April 2005 - BrianP |
Added EGLScreenMESA type and eglGetScreensMESA() function. [J. Smirl]. |
Replaced EGLint screen_number parameters with EGLScreenMESA screen. |
Added issue 17 (pixel-accurate panning) |
|
8. 2 May 2005 - BrianP |
Removed eglQueryDisplayMESA. |
Fixed a few more EGLint -> EGLScreenMESA changes. |
|
9. 20 May 2005 - BrianP |
Fixed a few typos. |
Updated some open issues text. |
|
10. 10 August 2005 - BrianP |
Added EGL_SCREEN_POSITION_GRANULARITY_MESA. |
|
11. 27 January 2006 - BrianP |
EGL_PHYSICAL_SIZE_MESA removed since EGL 1.2 has a similar feature. |
|