--- /dev/null
+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.
+
+++ /dev/null
-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.
-
projects / mesa.git / commitdiff