EGL_MESA_screen_surface version 3
Brian Paul
brian.paul at tungstengraphics.com
Fri Mar 18 06:46:30 PST 2005
The 3rd revision is attached. See the Version History section for
changes. The main thing is the addition of the Issues section. I
invite people with a strong opinion to contribute a concise argument
for or against each issue. I'll insert that text into the spec. At
some point in the future I expect there'll be a vote on the
outstanding issues to reach resolution.
-Brian
-------------- next part --------------
Name
MESA_screen_surface
Name Strings
EGL_MESA_screen_surface
Contact
Brian Paul
To discuss, join the dri-egl at lists.freedesktop.org list.
Status
Preliminary - totally subject to change.
Version
3 (18 March 2005)
Number
TBD
Dependencies
EGL 1.1 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.
Issues
1. Should EGL_INTERLACE be a supported mode attribute?
2. Should EGL_REFRESH_RATE be a supported mode attribute?
3. Exactly how should the list of modes returned by eglChooseConfigMESA
be sorted?
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). But what about power-save mode?
5. Should the EGL_PHYSICAL_WIDTH/HEIGHT_EGL tokens be kept? They're
not always reliable (i.e. projectors) but can still be used to
determine the 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 LDC panels have a native resolution and refresh rate
but may support other sub-optimal resolutions.
At this time, the EGL_OPTIMAL_MESA values may be specified in
eglChooseModeMESA() for EGL_WIDTH, EGL_HEIGHT, etc.
However, that violates the principle that eglChooseModeMESA()
should be fully implementable in terms of the eglGetModesMESA and
eglGetModeAttribMESA functions (as for eglChooseConfig).
New Procedures and Functions
EGLBoolean eglChooseModeMESA(EGLDisplay dpy, EGLint screen_number,
const EGLint *attrib_list,
EGLModeMESA *modes, EGLint modes_size,
EGLint *num_modes)
EGLBoolean eglGetModesMESA(EGLDisplay dpy, EGLint screen_number,
EGLModeMESA *modes, EGLint modes_size,
EGLint *num_modes)
EGLBoolean eglGetModeAttribMESA(EGLDisplay dpy, EGLModeMESA mode,
EGLint attrib, EGLint *value)
EGLSurface eglCreateScreenSurfaceMESA(EGLDisplay dpy, EGLConfig config,
const EGLint *attrib_list)
EGLBoolean eglShowSurfaceMESA(EGLDisplay dpy, EGLint screen_number,
EGLSurface surface, EGLModeMESA mode)
EGLBoolean eglScreenAttribsMESA(EGLDisplay dpy, EGLint screen_number,
const EGLint *attrib_list)
EGLBoolean eglQueryDisplayMESA(EGLDisplay dpy, EGLint attrib,
EGLint *value)
EGLBoolean eglQueryScreenMESA(EGLDisplay dpy, EGLint screen_number,
EGLint attrib, EGLint *value);
EGLBoolean eglQueryScreenSurfaceMESA(EGLDisplay dpy, EGLint screen_number,
EGLSurface *surface)
EGLBoolean eglQueryScreenModeMESA(EGLDisplay dpy, EGLint screen_number,
EGLModeMESA *mode)
[Possible addition]
const char *eglQueryModeStringMESA(EGLDisplay dpy, EGLMode mode);
New Types
EGLModeMESA
New Tokens
New error codes:
EGL_BAD_SCREEN_MESA
EGL_BAD_MODE_MESA
Screen-related tokens:
EGL_SCREEN_COUNT_MESA
EGL_SCREEN_X_ORIGIN_MESA
EGL_SCREEN_Y_ORIGIN_MESA
EGL_PHYSICAL_WIDTH_MESA
EGL_PHYSICAL_HEIGHT_MESA
EGL_SCREEN_BIT_MESA
Mode-related tokens:
EGL_MODE_ID_MESA
EGL_REFRESH_RATE_MESA
EGL_INTERLACED_MESA
EGL_OPTIMAL_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 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 The mode's refresh rate, multiplied by 1000
EGL_INTERLACED 1 indicates an interlaced mode, 0 otherwise
Any other token will generate the error EGL_BAD_ATTRIBUTE.
The value for any attribute may be the special value EGL_OPTIMAL_MESA
to indicate that the "best" value for the given screen should be used.
For example, with LCD screens setting EGL_WIDTH = EGL_OPTIMAL_MESA and
EGL_HEIGHT = EGL_OPTIMAL_MESA will choose the screen's native resolution.
The list of modes returned by eglChooseModeMESA will be sorted
according to the following criteria (ordered by importance).
[XXX redo this to be like Table 3.3 in the EGL spec]
1. Interlaced (non-interlaced modes first)
2. Width (largest first)
3. Height (largest first)
5. Refresh rate (highest first)
EGLBoolean eglGetModesMESA(EGLDisplay dpy, EGLint screen_number,
EGLModeMESA *modes, EGLint modes_size,
EGLint *num_modes)
Like eglGetConfigs, returns a list of all modes supported by the
given screen.
EGLBoolean eglGetModeAttribMESA(EGLDisplay dpy, EGLModeMESA mode,
EGLint attrib, EGLint *value)
Used to query mode attributes. The following attributes are supported:
Name Description
----------------- ----------------------------------------------
EGL_MODE_ID A unique small integer identifier for the mode
EGL_WIDTH Mode width (resolution)
EGL_HEIGHT Mode height (resolution)
EGL_REFRESH_RATE The mode's refresh rate, multiplied by 1000
EGL_INTERLACED 1 indicates an interlaced mode, 0 otherwise
Any other token will generate the error EGL_BAD_ATTRIBUTE.
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.
EGLBoolean eglShowSurfaceMESA(EGLDisplay dpy, EGLint screen_number,
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 should
be passed as the <surface> and <mode> parameters.
EGLBoolean eglScreenAttribsMESA(EGLDisplay dpy, EGLint screen_number,
const EGLint *attrib_list)
Used to set attributes for a screen. <attrib_list> is an array of
token/value pairs, terminated with EGL_NONE. Valid tokens include:
Name Description
------------------------ ------------------------------------------
EGL_SCREEN_X_ORIGIN_MESA X origin of surface with respect to screen
EGL_SCREEN_Y_ORIGIN_MESA Y origin of surface with respect to screen
Any other token will generate the error EGL_BAD_ATTRIBUTE.
The origin parameters are significant when the screen's width/height
is less than the surface's width/height.
Valid values for X are in [0, surfaceWidth - screenWidth]
Valid values for Y are in [0, surfaceHeight - screenHeight]
EGLBoolean eglQueryDisplayMESA(EGLDisplay dpy, EGLint screen_number,
EGLint attrib, EGLint *value)
Used to query display parameters. <attrib> may be one of the following:
Name Return value description
------------------ ---------------------------------------------
EGL_NUM_SCREENS Number of screens associated with the display
EGLBoolean eglQueryScreenMESA(EGLDisplay dpy, EGLint screen_number,
EGLint attrib, EGLint *value);
Used to query screen attributes. <attrib> may be one of the following:
Name Return value description
------------------------ ---------------------------------------------
EGL_SCREEN_X_ORIGIN_MESA X origin of surface with respect to screen
EGL_SCREEN_Y_ORIGIN_MESA Y origin of surface with respect to screen
EGL_PHYSICAL_WIDTH_MESA Physical width of the screen in millimeters
EGL_PHYSICAL_HEIGHT_MESA Physical height of the screen in millimeters
Any other token will generate the error EGL_BAD_ATTRIBUTE.
EGLBoolean eglQueryScreenSurfaceMESA(EGLDisplay dpy, EGLint screen_number,
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, EGLint screen_number,
EGLModeMESA *mode)
Returns the given screen's current display mode. The mode may be
EGL_NO_MODE if the screen is currently disabled.
[Possible addition]
const char *eglQueryModeStringMESA(EGLDisplay dpy, EGLModeMESA mode);
Query the human-readable string associated with the mode. The string
is a zero-terminated C string which the user should not attempt to free.
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
More information about the dri-egl
mailing list