EGL_MESA_screen_surface version 4
Brian Paul
brian.paul at tungstengraphics.com
Wed Mar 23 07:19:13 PST 2005
Here's the next version. My DSL connection was out for a few days so
I've been sitting on this since Saturday and it might not incorporate
recent discussion.
-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
4 (12 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.
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]
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.
3. Exactly how should the list of modes returned by eglChooseConfigMESA
be sorted?
Current method is desribed later. Subject to change.
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?
TBD.
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.
Arguments for:
X supports a similar query with DisplayWidthMM(), DisplayHeightMM().
If this information can be easily queried with EDID, why not
make it available to the user?
Arguments against:
Historically, these values aren't always accurate. Also, they're
not always applicable to the display device.
Other options:
Perhaps just a pixel aspect ratio should be supported. [M. Danzer]
Postpone for a future extension, if needed.
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
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 at 60Hz" if the later were generated via code.
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.
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 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)
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_POSITION_MESA
EGL_PHYSICAL_SIZE_MESA
EGL_SCREEN_BIT_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 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, EGLint screen_number,
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.
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_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].
EGLBoolean eglScreenPositionMESA(EGLDisplay dpy, EGLint screen_number,
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.
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_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_PHYSICAL_SIZE_MESA Physical width and 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_MESA if the screen is currently disabled.
const char *eglQueryModeStringMESA(EGLDisplay dpy, EGLModeMESA mode);
Return a human-readable string for the given 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
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.
More information about the dri-egl
mailing list