From: Chad Versace Date: Thu, 13 Oct 2016 21:19:51 +0000 (-0700) Subject: egl: Move old EGL_MESA_screen_surface spec X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=88b5c36fe1a1546bf633ee161a6715efc593acbd;p=mesa.git egl: Move old EGL_MESA_screen_surface spec It was the lone file in src/egl/docs. Move it to where the other specs live, in $MESA_TOP/docs/specs. Reviewed-by: Emil Velikov --- diff --git a/docs/specs/OLD/EGL_MESA_screen_surface.txt b/docs/specs/OLD/EGL_MESA_screen_surface.txt new file mode 100644 index 00000000000..698a2405781 --- /dev/null +++ b/docs/specs/OLD/EGL_MESA_screen_surface.txt @@ -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. + is the maximum number of screens to return in the + array. will return the number of screen handles + placed in the array, even if 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. 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 and 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. 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. + 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. + diff --git a/src/egl/docs/EGL_MESA_screen_surface b/src/egl/docs/EGL_MESA_screen_surface deleted file mode 100644 index 698a2405781..00000000000 --- a/src/egl/docs/EGL_MESA_screen_surface +++ /dev/null @@ -1,564 +0,0 @@ -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. - is the maximum number of screens to return in the - array. will return the number of screen handles - placed in the array, even if 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. 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 and 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. 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. - 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. -