1Name 2 3 NOK_swap_region2 4 5Name Strings 6 7 EGL_NOK_swap_region2 8 9Notice 10 11 Copyright 2010 Nokia. All rights reserved. 12 13Contributors 14 15 Robert Palmer 16 Sami Kyöstilä 17 18Contacts 19 20 Robert Palmer, Nokia (robert.palmer 'at' nokia.com) 21 Sami Kyöstilä, Nokia (sami.kyostila 'at' nokia.com) 22 23Status 24 25 Internally reviewed 26 27Version 28 29 2 - April 29, 2010 30 31Number 32 33 EGL Extension #23 34 35Dependencies 36 37 Requires EGL 1.4 38 39 This extension is written against the wording of the EGL 1.4 40 Specification. 41 42Overview 43 44 This extension adds a new function which provides an alternative to 45 eglSwapBuffers. eglSwapBuffersRegion2NOK accepts two new parameters 46 in addition to those in eglSwapBuffers. The new parameters consist 47 of a pointer to a list of 4-integer blocks defining rectangles 48 (x, y, width, height) and an integer specifying the number of 49 rectangles in the list. 50 51 The new parameters allow users to declare the region of the surface 52 that has been updated. The implementation uses this information to transfer 53 the updated region to the front buffer. Only the pixels within the 54 specified region are copied; any rendering outside that region will not 55 become visible on the window surface. This in contrast with the 56 EGL_NOK_swap_region extension which treats the modified region only as a 57 hint. 58 59 This functional change is aimed at further reducing the processing and 60 bandwidth requirements of optimizations of applications whose graphics are 61 commonly subjected to region-based changes. Specifically, this extension 62 enables partial surface updates without requiring the use of preserved 63 swaps. 64 65New Procedures and Functions 66 67 EGLAPI EGLBoolean EGLAPIENTRY eglSwapBuffersRegion2NOK( 68 EGLDisplay dpy, 69 EGLSurface surface, 70 EGLint numRects, 71 const EGLint* rects); 72 73New Types 74 75 None 76 77New Tokens 78 79 None 80 81Additions to Chapter 3 of the EGL 1.4 Specification (EGL Functions 82and Errors) 83 84 Add the following text to the end of the first subsection in 85 section 3.9.1 (prior to 'Native Window Resizing' subsection): 86 87 "eglSwapBuffersRegion2NOK is an alternative to eglSwapBuffers 88 that allows the client to provide the region of the surface 89 which has been updated. This will allow processing and 90 bandwidth optimizations for applications whose graphics are 91 commonly subject to region-based changes. 92 93 eglSwapBuffersRegion2NOK behaves in the same way as 94 eglSwapBuffers with the following modification: the additional 95 parameters <numRects> and <rects> provide specify a region which was 96 rendered to by the application. The implementation uses this 97 information to combine the modified backbuffer region with the previous 98 frontbuffer to form the new frontbuffer. The implementation guarantees 99 that all of the pixels within the modified region are posted for 100 display and none of the pixels outside the region are sourced. Only 101 back buffered surfaces can be used with eglSwapBuffersRegion2NOK. 102 103 <rects> specifies a pointer to a list of 4-integer blocks 104 defining rectangles. The area covered by the rectangles 105 constitutes the region of the color buffer which has been 106 updated by the client. <numRects> specifies the number of 107 rectangles in the <rects> list. If <numRects> is set to zero 108 the update region is set to the width and height of the 109 surface. 110 111 Each rectangle is specified as an integer 4-tuple in the form 112 (x, y, width, height). The x and y values provided by the client 113 must specify the bottom left corner of each rectangle as the 114 origin of the coordinate system is bottom left. Rectangles are 115 clipped (restricted) to the bounds of the EGLSurface. A 116 rectangle with width or height less than or equal 0 is ignored. 117 The region is defined by the union of all the specified 118 rectangles. The rectangles as specified must be disjoint. If 119 the rectangles are not disjoint or the user has rendered 120 outside of the region declared, the rendering results are 121 undefined." 122 123 Insert "eglSwapBuffersRegion2NOK" appropriately after each instance 124 of "eglSwapBuffers" in the first paragraph in section 3.9.4 125 126 Add the following before the last sentence in the first 127 paragraph in section 3.9.4 128 129 "If eglSwapBuffersRegion2NOK is called and <numRects> is greater 130 than zero and <rects> is NULL, an EGL_BAD_PARAMETER error is 131 generated. If <numRects> is less than zero, an 132 EGL_BAD_PARAMETER error is generated." 133 134 "If eglSwapBuffersRegion2NOK is called with a single buffered 135 <surface>, an EGL_BAD_MATCH error is generated." 136 137Dependencies on OpenGL ES 138 139 None 140 141Dependencies on OpenVG 142 143 None 144 145 146Issues 147 148 1) Is there a limit on the number of rectangles that can be used? 149 Should there be a specified number which are guaranteed to be 150 supported? 151 152 RESOLVED: This is limited by the amount of resources available to the 153 implementation. The implementation is free to fail with EGL_BAD_ALLOC if a 154 given update region cannot be processed due to resource constraints. 155 156 2) Are there any limitations on the location or size of rectangles? 157 158 RESOLVED: The limitations placed on the validity of a rectangle is 159 that the width and height must be greater than zero and should not 160 overlap. Rectangles which have a width or height less than or equal 161 to zero will be ignored. If rectangles overlap the rendering 162 results are undefined. In addition all rectangles are clipped to 163 the area of the surface. Rectangles which are partially or 164 completely outside the boundary of the surface will not generate an 165 error. 166 167 3) How does eglSwapBuffersRegion2NOK interact with incremental 168 rendering? 169 170 RESOLVED: This extension does not affect the client's ability to 171 perform incremental rendering. The ability to perform incremental 172 rendering is determined solely by the EGLSurface's 173 EGL_SWAP_BEHAVIOR attribute. The use of eglSwapBuffersRegion2NOK to 174 describe changed regions can still assist window system composition 175 optimizations even if the client is physically redrawing the entire 176 surface on every frame. 177 178 If EGL_SWAP_BEHAVIOR is EGL_BUFFER_PRESERVED, the client can 179 restrict their rendering to a particular region (e.g. using scissor 180 rects) and then declare this region using eglSwapBuffersRegion2NOK. 181 182 If EGL_SWAP_BEHAVIOR is EGL_BUFFER_DESTROYED, the client can 183 also restrict rendering to a particular region of the surface, but that 184 region must be completely re-rendered because the previous frame contents 185 are no longer available within that region. The application can then post 186 this region with eglSwapBuffersRegion2NOK. Since the buffer posting is 187 guaranteed to be limited to the declared region, the application does not 188 need to re-render or otherwise ensure pixel data outside the updated region 189 is valid. 190 191 4) How is this extension an improvement over EGL_NOK_swap_region? 192 193 RESOLVED: This extension builds on the previous EGL_NOK_swap_region 194 extension by requiring that the implementation considers the update region 195 provided by the application as a mandate rather than a hint. This allows 196 for region-restricted rendering without requiring the use of preserved buffer 197 swaps which may be relatively expensive for the implementation. 198 199 Furthermore, whilst preserved swap behaviour is necessary for incremental 200 rendering, many applications fully re-render modified surface regions and 201 so don't require preserved swap behaviour. This extension provides a 202 lighter weight surface update mechanism for such applications. 203 204 5) How does this extension compare to MESA_copy_sub_buffer? 205 206 RESOLVED: There are two main differences between MESA_copy_sub_buffer and 207 this extension: 208 209 1. This extension allows for arbitrary update regions instead of a 210 single rectangle. 211 212 2. eglSwapBuffersRegion2NOK is specified to be a frame swap, so the 213 implementation is free to apply destructive swap behavior in 214 conjunction with this function call. This may allow for a 215 performance improvement. 216 217Revision History 218 219 Version 1, 2010/04/28 (Sami Kyöstilä) 220 - First revision based on EGL_NOK_swap_region version 10. 221 Version 2, 2010/04/29 (Sami Kyöstilä) 222 - Specify operation in terms of copying from the back buffer into the 223 front buffer instead of involving the the system composition or the 224 display. 225 - Disallowed usage with anything else than back buffered surfaces. 226 - Clarified some sentences. 227