EGL_MESA_screen_surface version 2
Benjamin Herrenschmidt
benh at kernel.crashing.org
Wed Mar 16 18:43:47 PST 2005
On Wed, 2005-03-16 at 19:20 -0700, Brian Paul wrote:
> Issues
>
> TBD
>
> New Procedures and Functions
>
> EGLBoolean eglChooseModeMESA(EGLDisplay dpy, 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)
So screens are defined by their "number" in the system right ? I would
suggest a couple of functions for returning manufacturer/model names for
the sake of configuration GUIs and the number of screens in the
system... Ok, now that I'm reaching the end of the document, I see the
number of screens ...
I also note that you don't deal at all with geometry information, which,
while you may not want to be able to configure it from this API, I think
needs to be made available at least. How screens are positioned relative
to each other.
.../...
> 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:
How do you specify what screen to query the modes from ? There is no
such thing as a "global" mode list. Don't we need a screen_number
argument here ? Or do you pass a list as input and get a sublist as
output ?
>
> 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.
I would add a couple more attributes (see my other message). In fact, I
think we need at least some read-only per-mode attributes that are
wether the mode is the display "native" mode, and the vertical and
horizontal DPI.
> 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.
That's a way to workaround the lack of 'Native' attribute, but I would
still prefer having one. If not, we could go that way, but then, it
would be nice to have an eglCompareModes() to compare 2 modes and check
wether they are identical.
The client could compare all attributes, but that would break if a
future extension to the spec adds more attributes. I think we should
really design the API so that the attributes set cna be extended as it's
the most debated thing at the moment and the most likely to need changes
in the future imho.
.../...
>
> 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.
See above comments about attributes. The more I think about it, the more
I beleive adding room for arbitrary driver defined attributes is doable
as long as it's explicitely defined that the client program is not
supposed to interpret them. I would call them "minor" attributes. We
could then query their name (or manipulate them by name in the first
place) and their type (boolean, integer+range, ...) for the sake of
GUIs, get and set them etc... That would allow something like driConfig
to be able to make accessible the whole set of attributes of the HW. And
I'm not thinking about mode details, like gory timing details, but more
high-lvel stuff that the user will see, like card specific things about
the type of outputs, TV standards, TV overscan (wether the mode has
borders or not), scaler modes, that sort of thing.
Of course, that's just an idea, you may not want to go that way, in
which case I would not insist, though I think at least a few more well
defined ones in the spec would still be useful then (especially thinking
about the TV thingies here).
> 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.
So the pixel format isn't part of the surface definition ? (Bit depth,
RGB vs. YUV, ....)
> 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.
So that is the one doing the HW mode setting right ? I would suggest an
additional one eglValidateSurfaceMESA() then, that would do everything
but actually applying it to the HW. It is not guaranteed that a success
from validate means a success from a further eglShowSurfaceMESA (and
unexpected error may occur, or some other card resource may have been
stolen in the meantime), but again, that would help providing the user
with a more consistent choice by letting the client check which, for
example, bit depth (part of the surface no ?) can be used with a given
mode.
Also, what about cloning ? Is this dealt with implicitely by the backend
when the same surface is "shown" on two screens ? (I mean HW cloning,
the case where the 2 CRTC output of the card can be sourced from the
same framebuffer region). Or simply out of what you want to deal with in
this spec ?
>
> 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 - 1]
> Valid values for Y are in [0, surfaceHeight - screenHeight - 1]
I would add the DPMS states (power management/blanking) here.
>
> 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
Ok, here, I have a problem (but it's not your fault) :) I'm not sur what
exactly an EGLDisplay is. Does it represent the global system
environment ? A specific video card ?
>
>
>
> 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.
What about native pixel width / height, technology (LCD, CRT, ...) may
affect choosing gama tables) and screen manufacturer/name, pixel
ordering on LCD (for proper subpixel rendering of text), plus a few
others I'm forgetting now. Are you open to extending the above list ?
>
> 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.
> _______________________________________________
> dri-egl mailing list
> dri-egl at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/dri-egl
--
Benjamin Herrenschmidt <benh at kernel.crashing.org>
More information about the dri-egl
mailing list