Subversion Repositories Kolibri OS

Rev

Go to most recent revision | Blame | Last modification | View Log | RSS feed

  1. Name
  2.  
  3.     MESA_screen_surface
  4.  
  5. Name Strings
  6.  
  7.     EGL_MESA_screen_surface
  8.  
  9. Contact
  10.  
  11.     Brian Paul
  12.  
  13.     To discuss, join the dri-egl@lists.freedesktop.org list.
  14.  
  15. Status
  16.  
  17.     Obsolete.
  18.  
  19. Version
  20.  
  21.     11 (27 January 2006)
  22.  
  23. Number
  24.  
  25.     TBD
  26.  
  27. Dependencies
  28.  
  29.     EGL 1.0 or later.
  30.  
  31. Overview
  32.  
  33.     EGL 1.1 supports three types of drawing surfaces:
  34.       * Window surfaces
  35.       * Pixmap surfaces
  36.       * Pbuffer surfaces
  37.     This extension defines a fourth type of drawing surface:
  38.       * Screen surface
  39.  
  40.     A screen surface is a surface for which the (front) color buffer can
  41.     be directly displayed (i.e. scanned out) on a monitor (such as a flat
  42.     panel or CRT).  In particular the color buffer memory will be allocated
  43.     at a location in VRAM (and in a suitable format) which can be displayed
  44.     by the graphics hardware.
  45.  
  46.     Note that the width and height of the screen surface need not exactly
  47.     match the monitor's current resolution.  For example, while the monitor
  48.     may be configured to to show 1024x768 pixels, the associated screen
  49.     surface may be larger, such as 1200x1000.  The "screen origin" attribute
  50.     will specify which region of the screen surface which is visible on the
  51.     monitor.  The screen surface can be scrolled by changing this origin.
  52.  
  53.     This extension also defines functions for controlling the monitor's
  54.     display mode (width, height, refresh rate, etc), and specifing which
  55.     screen surface is to be displayed on a monitor.
  56.  
  57.     The new EGLModeMESA type and related functions are very similar to the
  58.     EGLConfig type and related functions.  The user may get a list of
  59.     supported modes for a screen and specify the mode to be used when
  60.     displaying a screen surface.
  61.  
  62.  
  63. Issues
  64.  
  65.     1. Should EGL_INTERLACE be a supported mode attribute?
  66.  
  67.        Arguments against:
  68.  
  69.            No, this should be provided by another extension which would
  70.            also provide the mechanisms needed to play back interlaced video
  71.            material correctly on hardware that supports it.
  72.            This extension should prefer non-interlaced modes. [M. Danzer]
  73.  
  74.        Arguments for:
  75.  
  76.            An interlaced display can be of use without considering video
  77.            material.  Being able to query whether a screen is operating in
  78.            interlaced mode can be used by applications to control their
  79.            drawing.  For example: avoid drawing 1-pixel-wide horizontal lines
  80.            if screen is interlaced. [B. Paul]
  81.  
  82.        Resolution: Defer for future extension?
  83.  
  84.  
  85.     2. Should EGL_REFRESH_RATE be a supported mode attribute?
  86.  
  87.        Arguments for:
  88.  
  89.            Yes, it's been shown that applications and/or users need to select
  90.            modes by this.  [M. Danzer]
  91.  
  92.            Many examples have been given in which it's desirable to let the
  93.            user choose from a variety of refresh rates without having to
  94.            restart/reconfigure.  [B. Paul]
  95.  
  96.        Arguments against:
  97.  
  98.            TBD.
  99.  
  100.        Resolution: Yes.
  101.  
  102.  
  103.     3. Exactly how should the list of modes returned by eglChooseConfigMESA
  104.        be sorted?
  105.  
  106.        Current method is described in the text below.  Subject to change.
  107.  
  108.        Alternately, leave the sorting order undefined so that each
  109.        implementation can return the modes in order of "most desirable"
  110.        to "least desirable" which may depend on the display technology
  111.        (CRT vs LCD, etc) or other factors.
  112.  
  113.  
  114.     4. How should screen blanking be supported?  Note that a screen can be
  115.        disabled or turned off by calling eglShowSurface(dpy, scrn,
  116.        EGL_NO_SURFACE, EGL_NO_MODE_MESA).  But what about power-save mode?
  117.  
  118.        I would defer this to other extensions that depend on this one.
  119.        I can imagine people wanting different semantics not just in
  120.        relation to the power management API being exposed (DPMS or whatever)
  121.        but also relating to what events can trigger EGL_CONTEXT_LOST.  Also
  122.        I'm not sure whether power management commands are properly operations
  123.        on the Display or on a screen surface. [A. Jackson]
  124.  
  125.  
  126.     5. Should the EGL_PHYSICAL_SIZE_EGL query be kept?  The size information
  127.        isn't always reliable (consider video projectors) but can still be
  128.        used to determine the pixel aspect ratio.
  129.  
  130.        Resolution: Omit.  The EGL 1.2 specification includes queries for
  131.        the display resolution and pixel aspect ratio.
  132.  
  133.  
  134.     6. Should detailed mode timing information be exposed by this API?
  135.  
  136.        Probably not.  Instead, offer that information in a layered extension.
  137.  
  138.  
  139.     7. How should the notion of a screen's "native" mode be expressed?
  140.        For example, LCD panels have a native resolution and refresh rate
  141.        that looks best but other sub-optimal resolutions may be supported.
  142.  
  143.        The mode attribute EGL_OPTIMAL_MESA will be set for modes which
  144.        best match the screen.  [M. Danzer]
  145.  
  146.  
  147.     8. Should eglQueryModeStringMESA() be included?  This function returns
  148.        a human-readable string which corresponds to an EGLMode.
  149.  
  150.        Arguments for:
  151.  
  152.            A mode name such as "HDTV-720P" might mean more to users than
  153.            "1280x720@60Hz" if the later were generated via code.
  154.  
  155.        Arguments against:
  156.  
  157.            There's no standard syntax for the strings.  May cause more
  158.            trouble than it's worth.
  159.  
  160.        Postpone for future extension. [A. Jackson]
  161.  
  162.        Latest discussion leaning toward omitting this function.
  163.  
  164.  
  165.     9. Should we use "Get" or "Query" for functions which return state?
  166.        The EGL 1.x specification doesn't seem to be totally consistent
  167.        in this regard, but "Query" is used more often.
  168.  
  169.        Use "Get" for mode-related queries (as for EGLConfigs) but "Query"
  170.        for everything else.
  171.  
  172.  
  173.     10. What should be the default size for screen surfaces?
  174.  
  175.         For Pbuffer surfaces the default width and height are zero.
  176.         We'll do the same for screen surfaces.  Since there's no function
  177.         to resize surfaces it's useless to have a 0x0 screen, but this isn't
  178.         a situation that'll normally be encountered.
  179.  
  180.  
  181.     11. Should there be a function for resizing a screen surface?
  182.  
  183.         Suppose one wants to change the screen's size in the EGL application.
  184.         Also suppose there's a hardware restriction such that only one screen
  185.         surface can exist at a time (either for lack of memory or because of
  186.         memory layout restrictions).
  187.  
  188.         The basic idea is that the currently displayed screen surface must
  189.         be deallocated before a new one can be created.  Perhaps a resize
  190.         function would work better?
  191.  
  192.  
  193.     12. How should sub-pixel LCD color information be made available?
  194.         What about the display's gamma value?
  195.  
  196.         Perhaps expose as additional read-only mode attributes.
  197.  
  198.         Perhaps postpone for a layered extension.
  199.  
  200.  
  201.     13. What happens if the user attempts to delete a screen surface that
  202.         is currently being shown?
  203.  
  204.         Spec currently says that's illegal and that an error (TBD) will be
  205.         generated.
  206.  
  207.  
  208.     14. What if the physical screen size can't be determined?  Should
  209.         a query of EGL_PHYSICAL_SIZE_MESA return [0,0]?
  210.  
  211.         Obsolete: EGL_PHYSICAL_SIZE_MESA not used.
  212.  
  213.  
  214.     15. Suppose the device's number of RAMDACs is different from the
  215.         number of output ports.  For example, a graphics card with
  216.         two RAMDACs but three ports (VGA, DVI, TV).
  217.  
  218.         Address this in a follow-on extension. [Matthias Hopf]
  219.  
  220.  
  221.     16. How should we deal with on-the-fly device changes?  For example,
  222.         the monitor being unplugged and replaced by another with different
  223.         characteristics?
  224.  
  225.         A HAL event could be received via DBUS in the application [J. Smirl,
  226.         A. Jackson].
  227.  
  228.         Should there be an EGL mechanism for detecting this?  Maybe an
  229.         EGL_SCREEN_LOST error (similar to EGL_CONTEXT_LOST) can be recorded
  230.         when there's a screen change.  At least then the application can
  231.         poll to detect this situation.
  232.  
  233.         Maybe leave that to a future extension.
  234.  
  235.         See also the EGL_SCREEN_COUNT_MESA query.
  236.  
  237.  
  238.     17. What if pixel-accurate panning is not supported (see
  239.         eglScreenPositionMESA)? [M. Danzer]
  240.  
  241.         Is this a common problem?  Can we ignore it for now?
  242.  
  243.  
  244.     18. Should eglShowSurfaceMESA be renamed to eglShowScreenSurfaceMESA?
  245.  
  246.         Probably.
  247.  
  248.  
  249.  
  250. New Procedures and Functions
  251.  
  252.     EGLBoolean eglChooseModeMESA(EGLDisplay dpy, EGLScreenMESA screen,
  253.                                  const EGLint *attrib_list,
  254.                                  EGLModeMESA *modes, EGLint modes_size,
  255.                                  EGLint *num_modes)
  256.  
  257.     EGLBoolean eglGetModesMESA(EGLDisplay dpy, EGLScreenMESA screen,
  258.                                EGLModeMESA *modes, EGLint modes_size,
  259.                                EGLint *num_modes)
  260.  
  261.     EGLBoolean eglGetModeAttribMESA(EGLDisplay dpy, EGLModeMESA mode,
  262.                                     EGLint attrib, EGLint *value)
  263.  
  264.  
  265.     EGLBoolean eglGetScreensMESA(EGLDisplay dpy, EGLScreenMESA *screens,
  266.                                  EGLint screens_size, EGLint *num_screens)
  267.  
  268.     EGLSurface eglCreateScreenSurfaceMESA(EGLDisplay dpy, EGLConfig config,
  269.                                           const EGLint *attrib_list)
  270.  
  271.     EGLBoolean eglShowSurfaceMESA(EGLDisplay dpy, EGLScreenMESA screen,
  272.                                   EGLSurface surface, EGLModeMESA mode)
  273.  
  274.     EGLBoolean eglScreenPositionMESA(EGLDisplay dpy, EGLScreenMESA screen,
  275.                                      EGLint x, EGLint y)
  276.  
  277.  
  278.     EGLBoolean eglQueryScreenMESA(EGLDisplay dpy, EGLScreenMESA screen,
  279.                                   EGLint attrib, EGLint *value);
  280.  
  281.     EGLBoolean eglQueryScreenSurfaceMESA(EGLDisplay dpy, EGLScreenMESA screen,
  282.                                          EGLSurface *surface)
  283.  
  284.     EGLBoolean eglQueryScreenModeMESA(EGLDisplay dpy, EGLScreenMESA screen,
  285.                                       EGLModeMESA *mode)
  286.  
  287.     const char *eglQueryModeStringMESA(EGLDisplay dpy, EGLMode mode);
  288.  
  289.  
  290. New Types
  291.  
  292.     EGLModeMESA
  293.     EGLScreenMESA
  294.  
  295. New Tokens
  296.  
  297.     New error codes:
  298.  
  299.     EGL_BAD_SCREEN_MESA        
  300.     EGL_BAD_MODE_MESA          
  301.  
  302.     Screen-related tokens:
  303.  
  304.     EGL_SCREEN_COUNT_MESA      
  305.     EGL_SCREEN_POSITION_MESA  
  306.     EGL_SCREEN_BIT_MESA        
  307.     EGL_SCREEN_POSITION_GRANULARITY_MESA
  308.  
  309.     Mode-related tokens:
  310.  
  311.     EGL_MODE_ID_MESA          
  312.     EGL_REFRESH_RATE_MESA      
  313.     EGL_INTERLACED_MESA
  314.     EGL_OPTIMAL_MESA
  315.     EGL_NO_MODE_MESA
  316.  
  317.  
  318. Additions to Chapter X of the EGL 1.1 Specification
  319.  
  320.     [XXX this all has to be rewritten to fit into the EGL specification
  321.     and match the conventions of an EGL extension.  For now, just list
  322.     all the functions with brief descriptions.]
  323.  
  324.  
  325.     EGLBoolean eglChooseModeMESA(EGLDisplay dpy, const EGLScreenMESA screen,
  326.                                  EGLint *attrib_list, EGLModeMESA *modes,
  327.                                  EGLint modes_size, EGLint *num_modes)
  328.  
  329.     Like eglChooseConfig, returns a list of EGLModes which match the given
  330.     attribute list.  This does not set the screen's current display mode.
  331.     The attribute list is a list of token/value pairs terminated with
  332.     EGL_NONE.  Supported attributes include:
  333.  
  334.         Name                   Description
  335.         ---------------------  ---------------------------------------------
  336.         EGL_WIDTH              Mode width (resolution)
  337.         EGL_HEIGHT             Mode height (resolution)
  338.         EGL_REFRESH_RATE_MESA  The mode's refresh rate, multiplied by 1000
  339.         EGL_INTERLACED_MESA    1 indicates an interlaced mode, 0 otherwise
  340.         EGL_OPTIMAL_MESA       Set if the most is especially optimal for the
  341.                                screen (ex. for particular LCD resolutions)
  342.  
  343.     Any other token will generate the error EGL_BAD_ATTRIBUTE.
  344.  
  345.     The list of modes returned by eglChooseModeMESA will be sorted
  346.     according to the following criteria.  See the discussion of table 3.3
  347.     in the EGL specification for more information.
  348.  
  349.                                             Selection   Sort   Sort
  350.         Attribute            Default        Criteria    Order  Priority
  351.         -------------------- -------------- ----------- ------ --------
  352.         EGL_OPTIMAL_MESA     EGL_DONT_CARE  Exact       1,0      1
  353.         EGL_INTERLACED_MESA  EGL_DONT_CARE  Exact       0,1      2
  354.         EGL_REFRESH_RATE     EGL_DONT_CARE  AtLeast     Larger   3
  355.         EGL_WIDTH            EGL_DONT_CARE  AtLeast     Larger   4
  356.         EGL_HEIGHT           EGL_DONT_CARE  AtLeast     Larger   5
  357.         EGL_MODE_ID_MESA     EGL_DONT_CARE  Exact       Smaller  6
  358.  
  359.  
  360.     EGLBoolean eglGetModesMESA(EGLDisplay dpy, EGLScreenMESA screen,
  361.                                EGLModeMESA *modes, EGLint modes_size,
  362.                                EGLint *num_modes)
  363.  
  364.     Like eglGetConfigs, returns a list of all modes supported by the
  365.     given screen.  The returned modes will be sorted in the same manner
  366.     as for eglChooseModeMESA().
  367.  
  368.  
  369.  
  370.     EGLBoolean eglGetModeAttribMESA(EGLDisplay dpy, EGLModeMESA mode,
  371.                                     EGLint attrib, EGLint *value)
  372.  
  373.     Used to query mode attributes.  The following attributes are supported:
  374.  
  375.         Name                   Return value description
  376.         ---------------------  ----------------------------------------------
  377.         EGL_OPTIMAL_MESA       1 indicates an optimal mode, 0 otherwise
  378.         EGL_INTERLACED_MESA    1 indicates an interlaced mode, 0 otherwise
  379.         EGL_REFRESH_RATE_MESA  The mode's refresh rate, multiplied by 1000
  380.         EGL_WIDTH              Mode width (resolution)
  381.         EGL_HEIGHT             Mode height (resolution)
  382.         EGL_MODE_ID_MESA       A unique small integer identifier for the mode
  383.  
  384.     Any other token will generate the error EGL_BAD_ATTRIBUTE.
  385.  
  386.  
  387.  
  388.     EGLBoolean eglGetScreensMESA(EGLDisplay dpy, EGLScreenMESA *screens,
  389.                                  EGLint screens_size, EGLint *num_screens)
  390.  
  391.     This function returns an array of all available screen handles.
  392.     <screens_size> is the maximum number of screens to return in the
  393.     <screens> array.  <num_screens> will return the number of screen handles
  394.     placed in the array, even if <screens> is NULL.
  395.  
  396.     The number of screens and the availability of each may change over
  397.     time (hot-plugging).  Screen handles will not be reused.  When a
  398.     screen handle becomes invalid, function calls which reference an
  399.     invalid handle will generate EGL_BAD_SCREEN_MESA.
  400.  
  401.     The first screen handle returned will be considered to be the primary
  402.     one.
  403.  
  404.  
  405.  
  406.     EGLSurface eglCreateScreenSurfaceMESA(EGLDisplay dpy, EGLConfig config,
  407.                                           const EGLint *attrib_list)
  408.  
  409.     Create a surface that can be displayed on a screen.  <attrib_list> is
  410.     an array of token/value pairs terminated with EGL_NONE.  Valid tokens
  411.     include:
  412.  
  413.         Name              Description
  414.         ----------------  --------------------------------
  415.         EGL_WIDTH         desired surface width in pixels
  416.         EGL_HEIGHT        desired surface height in pixels
  417.  
  418.     Any other token will generate the error EGL_BAD_ATTRIBUTE.
  419.     The default width and height are zero.
  420.  
  421.    
  422.  
  423.     EGLBoolean eglShowSurfaceMESA(EGLDisplay dpy, EGLScreenMESA screen,
  424.                                   EGLSurface surface, EGLModeMESA mode)
  425.  
  426.     This function causes a screen to show the given surface (or more
  427.     precisely, the surface's front color buffer) with the given mode.
  428.  
  429.     If the surface is in any way incompatible with the mode, the error
  430.     EGL_BAD_MATCH will be generated, EGL_FALSE will be returned, and the
  431.     previous screen state will remain in effect.  This might occur when
  432.     the bandwidth of the video-out subsystem is exceeded, or if the mode
  433.     specifies a width or height that's greater than the width or height
  434.     of the surface.
  435.  
  436.     To disable a screen, the values EGL_NO_SURFACE and EGL_NO_MODE_MESA
  437.     be passed as the <surface> and <mode> parameters.
  438.  
  439.     The values of EGL_SCREEN_POSITION_MESA are clamped to the new valid
  440.     range computed from the screen size and surface size.  If the new
  441.     surface is EGL_NO_SURFACE, EGL_SCREEN_POSITION_MESA is set to [0, 0].
  442.  
  443.  
  444.     Attempting to delete a screen surface which is currently being
  445.     displayed will result in the error EGL_BAD_ACCESS being generated.
  446.  
  447.  
  448.  
  449.     EGLBoolean eglScreenPositionMESA(EGLDisplay dpy, EGLScreenMESA screen,
  450.                                      EGLint x, EGLint y)
  451.  
  452.     Specifies the origin of the screen's view into the surface, if the
  453.     surface is larger than the screen.  Valid values for x and y are
  454.     [0, surfaceWidth - screenWidth] and [0, surfaceHeight - screenHeight],
  455.     respectively.
  456.  
  457.     The x and y values are also constrained to be integer multiples of the
  458.     EGL_SCREEN_POSITION_GRANULARITY_MESA values.
  459.  
  460.  
  461.  
  462.  
  463.     EGLBoolean eglQueryScreenMESA(EGLDisplay dpy, EGLScreenMESA screen,
  464.                                   EGLint attrib, EGLint *value);
  465.  
  466.     Used to query screen attributes.  <attrib> may be one of the following:
  467.  
  468.         Name                      Return value description
  469.         ------------------------  ---------------------------------------------
  470.         EGL_SCREEN_POSITION_MESA  x, y position of the screen's origin with
  471.                                   respect to the surface.  If no surface is
  472.                                   attached to the screen, [0, 0] is returned.
  473.         EGL_SCREEN_POSITION_GRANULARITY_MESA
  474.                                   Returns the granularity, in pixels, for
  475.                                   which the screen position is constrained.
  476.  
  477.     Any other token will generate the error EGL_BAD_ATTRIBUTE.
  478.  
  479.  
  480.  
  481.  
  482.     EGLBoolean eglQueryScreenSurfaceMESA(EGLDisplay dpy, EGLScreenMESA screen,
  483.                                          EGLSurface *surface)
  484.  
  485.     Returns the surface currently displayed on the given screen.  <surface>
  486.     may be EGL_NO_SURFACE if the screen isn't currently showing any surface.
  487.  
  488.  
  489.  
  490.  
  491.     EGLBoolean eglQueryScreenModeMESA(EGLDisplay dpy, EGLScreenMESA screen,
  492.                                       EGLModeMESA *mode)
  493.  
  494.     Returns the given screen's current display mode.  The mode may be
  495.     EGL_NO_MODE_MESA if the screen is currently disabled.
  496.  
  497.  
  498.  
  499.     const char *eglQueryModeStringMESA(EGLDisplay dpy, EGLModeMESA mode);
  500.  
  501.     Returns a human-readable string for the given mode.  The string is a
  502.     zero-terminated C string which the user should not attempt to free.
  503.     There is no standard syntax for mode strings.  Applications should
  504.     not directly rely on mode strings.
  505.  
  506.  
  507.  
  508. Version History
  509.  
  510.     1. 15 March 2005 - BrianP
  511.         Initial version
  512.  
  513.     2. 16 March 2005 - BrianP
  514.         Removed EGL_DEPTH_MESA
  515.         Added EGL_PHYSICAL_WIDTH_MESA, EGL_PHYSICAL_HEIGHT_MESA queries
  516.         Added EGL_OPTIMAL_MESA for width/height/refresh rate selection
  517.         Added possible eglQueryModeStringMESA() function
  518.         More details of the new functions explained.
  519.  
  520.     3. 18 March 2005 - BrianP
  521.         Added screen_number to eglChooseModeMESA().
  522.         Fix off by one mistake in value range for ORIGIN attributes
  523.         Added Issues section
  524.  
  525.     4. 21 March 2005 - BrianP
  526.         Removed eglScreenAttribsMESA().
  527.         Added eglScreenPositionMESA() to set screen origin.
  528.         Replaced EGL_SCREEN_X/Y_OFFSET_MESA with EGL_SCREEN_POSITION_MESA.
  529.         Replaced EGL_PHYSICAL_WIDTH/HEIGHT_MESA with EGL_PHYSICAL_SIZE_MESA.
  530.         Use EGL_OPTIMAL_MESA as a new mode attribute. (Michel Danzer)
  531.         Added a few more issues.
  532.  
  533.     5. 6 April 2005 - BrianP
  534.         More language for eglGetModeStringMESA().
  535.         Added issues 10, 11, 12, 13, 14.
  536.         Updated issue 3 discussion about mode sorting.
  537.  
  538.     6. 22 April 2005 - BrianP
  539.         Fixed "LDC" typo.
  540.         Added issues 15, 16.
  541.         Changed dependency on EGL 1.1 to EGL 1.0
  542.         s/EGL_NUM_SCREENS_MESA/EGL_SCREEN_COUNT_MESA/
  543.         Added eglQueryDisplayMESA() to New Functions section.
  544.         Clarified language for the EGL_SCREEN_COUNT_MESA query.
  545.  
  546.     7. 29 April 2005 - BrianP
  547.         Added EGLScreenMESA type and eglGetScreensMESA() function. [J. Smirl].
  548.         Replaced EGLint screen_number parameters with EGLScreenMESA screen.
  549.         Added issue 17 (pixel-accurate panning)
  550.  
  551.     8. 2 May 2005 - BrianP
  552.         Removed eglQueryDisplayMESA.
  553.         Fixed a few more EGLint -> EGLScreenMESA changes.
  554.  
  555.     9. 20 May 2005 - BrianP
  556.         Fixed a few typos.
  557.         Updated some open issues text.
  558.  
  559.     10. 10 August 2005 - BrianP
  560.         Added EGL_SCREEN_POSITION_GRANULARITY_MESA.
  561.  
  562.     11. 27 January 2006 - BrianP
  563.         EGL_PHYSICAL_SIZE_MESA removed since EGL 1.2 has a similar feature.
  564.  
  565.