1Name 2 3 NV_post_sub_buffer 4 5Name Strings 6 7 EGL_NV_post_sub_buffer 8 9Contributors 10 11 Arcady Goldmints-Orlov 12 James Jones 13 Daniel Kartch 14 15Contact 16 17 James Jones, NVIDIA Corporation (jajones 'at' nvidia.com) 18 19Status 20 21 Draft. 22 23Version 24 25 Version 3, November 5, 2010 26 27Number 28 29 EGL Extension #27 30 31Dependencies 32 33 Requires EGL 1.1 34 35 This extension is written against the wording of the EGL 1.4 36 Specification 37 38Overview 39 40 Many EGL client APIs do not support rendering to window surfaces 41 directly, so there is no way to efficiently make small updates to 42 window surfaces. Applications that need to perform many small updates 43 must either use the back-buffer preservation flag which forces 44 eglSwapBuffers to copy the entire back surface, or redraw the entire 45 back buffer on every update and hope eglSwapBuffers is implemented 46 using buffer-flipping. This extension provides a 3rd alternative: a 47 function which posts a sub-rectangle of a window surface and 48 preserves the back-buffer contents. 49 50New Types 51 52 None. 53 54New Procedures and Functions 55 56 EGLBoolean eglPostSubBufferNV(EGLDisplay dpy, 57 EGLSurface surface, 58 EGLint x, EGLint y, 59 EGLint width, EGLint height); 60 61New Tokens 62 63 Accepted by the <attribute> parameter of eglQuerySurface and by the 64 <attrib_list> parameter of eglCreateWindowSurface: 65 66 EGL_POST_SUB_BUFFER_SUPPORTED_NV 0x30BE 67 68Changes to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors) 69 70 Modify the second paragraph of Section 3.5.1, page 27 71 (Creating On-Screen Rendering Surfaces) 72 73 "<attrib_list> specifies a list of attributes for the window. The list 74 has the same structure as described for eglChooseConfig. Attributes 75 that can be specified in <attrib_list> include EGL_POST_SUB_BUFFER_- 76 SUPPORTED_NV, EGL_RENDER_BUFFER, EGL_VG_COLORSPACE, and EGL_VG_ALPHA_- 77 FORMAT." 78 79 Add the following between paragraphs 4 and 5 of Section 3.5.1, page 27 80 (Creating On-Screen Rendering Surfaces) 81 82 "EGL_POST_SUB_BUFFER_SUPPORTED_NV specifies whether the application 83 would perfer a surface that supports sub-buffer post operations, as 84 described in section 3.9.1. Its values can be EGL_TRUE, in which case 85 the implementation will attempt to allocate a surface that supports 86 sub-buffer posts, or EGL_FALSE, in which case the implementation will 87 not take sub-buffer post capabilities into account. 88 89 "Implementations may not be able to support sub-buffer post 90 mechanisms, or may support them only on some native windows. Use 91 eglQuerySurface to determine a surface's capabilities (see section 92 3.5.6)." 93 94 Add the following entry to Table 3.5, page 36 95 (Queryable surface attributes and types) 96 97 Attribute Type Description 98 -------------------------------- ------- ------------------------ 99 EGL_POST_SUB_BUFFER_SUPPORTED_NV boolean Surface can be used with 100 eglPostSubBufferNV 101 102 Add the following paragraph to Section 3.5.6, page 37 103 (Surface Attributes) 104 105 "Querying EGL_POST_SUB_BUFFER_SUPPORTED_NV returns EGL_TRUE if the 106 surface can use eglPostSubBufferNV (See section 3.9.1) to post sub- 107 rectangles of the back color buffer. Otherwise, EGL_FALSE is 108 returned." 109 110 Replace all but the last paragraph of section Section 3.9.1, page 50 111 (Posting to a Window) 112 113 "To post the color buffer to a window, call 114 115 EGLBoolean eglSwapBuffers(EGLDisplay dpy, 116 EGLSurface surface); 117 118 "To post a sub-rectangle of the color buffer to a window, call 119 120 EGLBoolean eglPostSubBufferNV(EGLDisplay dpy, 121 EGLSurface surface, EGLint x, EGLint y, 122 EGLint width, EGLint height); 123 124 "Where <x> and <y> are pixel offsets from the bottom-left corner of 125 <surface>. 126 127 "If <surface> is a back-buffered surface, then the requested portion 128 of the color buffer is copied to the native window associated with 129 that surface. If <surface> is a single-buffered window, pixmap, or 130 pbuffer surface, eglSwapBuffers and eglPostSubBufferNV have no 131 effect. 132 133 "The contents of ancillary buffers are always undefined after calling 134 eglSwapBuffers or eglPostSubBufferNV. The contents of the color 135 buffer are unchanged if eglPostSubBufferNV is called, or if 136 eglSwapBuffers is called and the value of the EGL_SWAP_BEHAVIOR 137 attribute of <surface> is EGL_BUFFER_PRESERVED. The value of EGL_- 138 SWAP_BEHAVIOR can be set for some surfaces using eglSurfaceAttrib, as 139 described in section 3.5.6. 140 141 "Native Window Resizing 142 143 "If the native window corresponding to <surface> has been resized 144 prior to the swap, <surface> must be resized to match. <surface> will 145 normally be resized by the EGL implementation at the time the native 146 window is resized. If the implementation cannot do this transparently 147 to the client, then eglSwapBuffers and eglPostSubBufferNV must 148 detect the change and resize <surface> prior to copying its pixels to 149 the native window. The sub-rectangle defined by <x>, <y>, <width>, and 150 <height> parameters to eglPostSubBufferNV will be clamped to the 151 extents of <surface>. If, after clamping, the rectangle contains no 152 pixels, eglPostSubBufferNV will have no effect." 153 154 Modify the following sentences in Section 3.9.3, page 51 (Posting 155 Semantics) 156 157 Paragraph 2, first sentence: 158 159 "If <dpy> and <surface> are the display and surface for the calling 160 thread's current context, eglSwapBuffers, eglPostSubBufferNV, and 161 eglCopyBuffers perform an implicit flush operation on the context 162 (glFlush for OpenGL or OpenGL ES context, vgFlush for an OpenVG 163 context)." 164 165 Paragraph 3, first sentence: 166 167 "The destination of a posting operation (a visible window, for 168 eglSwapBuffers or eglPostSubBufferNV, or a native pixmap, for 169 eglCopyBuffers) should have the same number of components and 170 component sizes as the color buffer it's being copied from." 171 172 Paragraph 6, first two sentences: 173 174 "The function 175 176 EGLBoolean eglSwapInterval(EGLDisplay dpy, EGLint 177 interval); 178 179 specifes the minimum number of video frame periods per color buffer 180 post operation for the window associated with the current context. The 181 interval takes effect when eglSwapBuffers or eglPostSubBufferNV is 182 first called subsequent to the eglSwapInterval call." 183 184 Modify the following sentences in Section 3.9.4, page 52 (Posting 185 Errors) 186 187 Paragraph 1, first sentence: 188 189 "eglSwapBuffers, eglPostSubBufferNV, and eglCopyBuffers return 190 EGL_FALSE on failure." 191 192 Paragraph 1, seventh sentence: 193 194 "If eglSwapBuffers or eglPostSubBufferNV are called and the native 195 window associated with <surface> is no longer valid, an EGL_BAD_- 196 NATIVE_WINDOW error is generated. If eglPostSubBufferNV is called 197 and <x>, <y>, <width>, or <height> are less than zero, EGL_BAD_- 198 PARAMETER is generated." 199 200Issues 201 202 1. Should all surfaces be required to support sub-buffer posts if 203 this extension is supported? 204 205 RESOLVED: No. Some implementations may support multiple types of 206 native windows. Support for sub-surface posting is therefore a 207 per-surface property, so a surface query should be used to determine 208 which surfaces support sub-surface posts. 209 210 2. What should this extension be called? 211 212 RESOLVED: Names considered EGL_NV_copy_sub_buffer, EGL_NV_present_sub- 213 surface, EGL_NV_post_sub_buffer. eglCopySubBuffer() sounded too 214 similar to eglCopyBuffer(), which operates on different types of 215 surfaces. EGL_present_sub_surface was originally chosen as it was 216 sufficiently different than eglCopyBuffer(), but based on internal 217 feedback, the term "Post" is preferable to "Present" because it is 218 already used in the EGL spec to describe buffer presentation 219 operations. "Buffer" was chosen over "surface" at this point as well, 220 because it is more consistent with the eglSwapBuffers() and 221 eglCopyBuffer() commands, and eglPostSubBuffer() is still 222 differentiated enough from eglCopyBuffer() that the two won't be 223 confused. 224 225Revision History 226 227#3 (James Jones, November 5, 2010) 228 -Renamed from NV_present_sub_surface to NV_post_sub_buffer based on 229 feedback from internal reviews. 230 231 -Allowed EGL_POST_SUB_BUFFER_SUPPORTED_NV to be used as a hint when 232 creating window surfaces. 233 234 -Clarified that eglSwapInterval applies to all color-buffer post 235 operations affecting on-screen surfaces, not just eglSwapBuffers. 236 237#2 (James Jones, November 1, 2010) 238 - Fixed a few typos. 239 240#1 (James Jones, October 22, 2010) 241 - Initial revision, based on GLX_MESA_copy_sub_buffer 242