src/third_party/angle/extensions/EGL_ANGLE_window_fixed_size.txt

   1 Name
   2
   3     ANGLE_window_fixed_size
   4
   5 Name Strings
   6
   7     EGL_ANGLE_window_fixed_size
   8
   9 Contributors
  10
  11     John Bauman
  12     Shannon Woods
  13
  14 Contacts
  15
  16     John Bauman, Google Inc. (jbauman 'at' google.com)
  17
  18 Status
  19
  20     Complete
  21
  22 Version
  23
  24     Version 4, February 24, 2014
  25
  26 Number
  27
  28     EGL Extension #??
  29
  30 Dependencies
  31
  32     This extension is written against the wording of the EGL 1.4
  33     Specification.
  34
  35 Overview
  36
  37     This extension allows creating a window surface with a fixed size that is
  38     specified when it is created.
  39
  40 New Types
  41
  42     None
  43
  44 New Procedures and Functions
  45
  46     None
  47
  48 New Tokens
  49
  50     Accepted by the <attribute> parameter of eglQuerySurface and by the
  51     <attrib_list> parameter of eglCreateWindowSurface:
  52
  53     EGL_FIXED_SIZE_ANGLE        0x3201
  54
  55 Additions to Chapter 3 of the EGL 1.4 Specification:
  56
  57     Modify the third paragraph of Section 3.5.1 (Creating On-Screen Rendering Surfaces)
  58
  59     "<attrib_list> specifies a list of attributes for the window. The list has
  60     the same structure as described for eglChooseConfig.  Attributes that can
  61     be specified in <attrib_list> include EGL_RENDER_BUFFER,
  62     EGL_VG_COLORSPACE, EGL_VG_ALPHA_FORMAT, EGL_FIXED_SIZE_ANGLE, EGL_WIDTH,
  63     and EGL_HEIGHT."
  64
  65     Add before the last paragraph of Section 3.5.1
  66
  67     "EGL_FIXED_SIZE_ANGLE specifies whether the surface must be resized by the
  68     implementation when the native window is resized.  The default value is
  69     EGL_FALSE.  Its value can be EGL_TRUE, in which case the size must be
  70     specified when the window is created, or EGL_FALSE, in which case the size
  71     is taken from the native window. Its default value is EGL_FALSE.
  72
  73     If the value of EGL_FIXED_SIZE_ANGLE is EGL_TRUE, the window surface's
  74     size in pixels is specified by the EGL_WIDTH and EGL_HEIGHT attributes,
  75     and will not change throughout the lifetime of the surface. If its value
  76     is EGL_FALSE, then the values of EGL_WIDTH and EGL_HEIGHT are ignored and
  77     the window surface must be resized by the implementation subsequent to the
  78     native window being resized, and prior to copying its contents to the
  79     native window (e.g. in eglSwapBuffers, as described in section 3.9.1.1).
  80     The default values for EGL_WIDTH and EGL_HEIGHT are zero. If the value
  81     specified for either of EGL_WIDTH or EGL_HEIGHT is less than zero then an
  82     EGL_BAD_PARAMETER error is generated."
  83
  84     Add the following entry to Table 3.5
  85     (Queryable surface attributes and types)
  86
  87     Attribute            Type    Description
  88     -------------------- ------- ---------------------------------------------
  89     EGL_FIXED_SIZE_ANGLE boolean Surface will not be resized with a native
  90                                  window
  91
  92     Replace the last paragraph on page 37 in Section 3.5.6 (Surface Attributes)
  93
  94     "Querying EGL_WIDTH and EGL_HEIGHT returns respectively the width and
  95     height, in pixels, of the surface. For a pixmap surface or window surface
  96     with EGL_FIXED_SIZE_ANGLE set to EGL_FALSE, these values are initially
  97     equal to the width and height of the native window or pixmap with respect
  98     to which the surface was created. If the native window is resized and the
  99     corresponding window surface is not fixed size, the corresponding window
 100     surface will eventually be resized by the implementation to match (as
 101     discussed in section 3.9.1). If there is a discrepancy because EGL has not
 102     yet resized the window surface, the size returned by eglQuerySurface will
 103     always be that of the EGL surface, not the corresponding native window."
 104
 105     Add the following paragraph to Section 3.5.6 (Surface Attributes)
 106
 107     "Querying EGL_FIXED_SIZE_ANGLE returns EGL_FALSE if the surface will be
 108     resized to match a native window, and EGL_TRUE if the surface cannot be
 109     resized."
 110
 111     Alter the beginning of the first paragraph of Section 3.9.1.1 (Native
 112     Window Resizing)
 113
 114     "If <surface> does not have EGL_FIXED_SIZE_ANGLE set and the native window
 115     corresponding to <surface> has been resized prior to the swap, <surface>
 116     must be resized to match."
 117
 118 Issues
 119
 120     1. Should there be a way to resize a window surface that had its size
 121     specified initially.
 122
 123     RESOLVED: No. Surfaces that have their sizes specified initially must have
 124     EGL_FIXED_SIZE_ANGLE set and can never be resized.
 125
 126 Revision History
 127
 128     Version 4, 2014/02/24 - formatting changes.
 129
 130     Version 3, 2014/02/12 - ignore EGL_WIDTH and EGL_HEIGHT if
 131     EGL_FIXED_SIZE_ANGLE is EGL_FALSE
 132
 133     Version 2, 2014/02/07 - rename to EGL_ANGLE_window_fixed_size, and add an
 134     EGL_FIXED_SIZE_ANGLE token.
 135
 136     Version 1, 2014/02/05 - first draft.