| Name |
| |
| NV_post_sub_buffer |
| |
| Name Strings |
| |
| EGL_NV_post_sub_buffer |
| |
| Contributors |
| |
| Arcady Goldmints-Orlov |
| James Jones |
| Daniel Kartch |
| |
| Contact |
| |
| James Jones, NVIDIA Corporation (jajones 'at' nvidia.com) |
| |
| Status |
| |
| Draft. |
| |
| Version |
| |
| Version 3, November 5, 2010 |
| |
| Number |
| |
| EGL Extension #27 |
| |
| Dependencies |
| |
| Requires EGL 1.1 |
| |
| This extension is written against the wording of the EGL 1.4 |
| Specification |
| |
| Overview |
| |
| Many EGL client APIs do not support rendering to window surfaces |
| directly, so there is no way to efficiently make small updates to |
| window surfaces. Applications that need to perform many small updates |
| must either use the back-buffer preservation flag which forces |
| eglSwapBuffers to copy the entire back surface, or redraw the entire |
| back buffer on every update and hope eglSwapBuffers is implemented |
| using buffer-flipping. This extension provides a 3rd alternative: a |
| function which posts a sub-rectangle of a window surface and |
| preserves the back-buffer contents. |
| |
| New Types |
| |
| None. |
| |
| New Procedures and Functions |
| |
| EGLBoolean eglPostSubBufferNV(EGLDisplay dpy, |
| EGLSurface surface, |
| EGLint x, EGLint y, |
| EGLint width, EGLint height); |
| |
| New Tokens |
| |
| Accepted by the <attribute> parameter of eglQuerySurface and by the |
| <attrib_list> parameter of eglCreateWindowSurface: |
| |
| EGL_POST_SUB_BUFFER_SUPPORTED_NV 0x30BE |
| |
| Changes to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors) |
| |
| Modify the second paragraph of Section 3.5.1, page 27 |
| (Creating On-Screen Rendering Surfaces) |
| |
| "<attrib_list> specifies a list of attributes for the window. The list |
| has the same structure as described for eglChooseConfig. Attributes |
| that can be specified in <attrib_list> include EGL_POST_SUB_BUFFER_- |
| SUPPORTED_NV, EGL_RENDER_BUFFER, EGL_VG_COLORSPACE, and EGL_VG_ALPHA_- |
| FORMAT." |
| |
| Add the following between paragraphs 4 and 5 of Section 3.5.1, page 27 |
| (Creating On-Screen Rendering Surfaces) |
| |
| "EGL_POST_SUB_BUFFER_SUPPORTED_NV specifies whether the application |
| would perfer a surface that supports sub-buffer post operations, as |
| described in section 3.9.1. Its values can be EGL_TRUE, in which case |
| the implementation will attempt to allocate a surface that supports |
| sub-buffer posts, or EGL_FALSE, in which case the implementation will |
| not take sub-buffer post capabilities into account. |
| |
| "Implementations may not be able to support sub-buffer post |
| mechanisms, or may support them only on some native windows. Use |
| eglQuerySurface to determine a surface's capabilities (see section |
| 3.5.6)." |
| |
| Add the following entry to Table 3.5, page 36 |
| (Queryable surface attributes and types) |
| |
| Attribute Type Description |
| -------------------------------- ------- ------------------------ |
| EGL_POST_SUB_BUFFER_SUPPORTED_NV boolean Surface can be used with |
| eglPostSubBufferNV |
| |
| Add the following paragraph to Section 3.5.6, page 37 |
| (Surface Attributes) |
| |
| "Querying EGL_POST_SUB_BUFFER_SUPPORTED_NV returns EGL_TRUE if the |
| surface can use eglPostSubBufferNV (See section 3.9.1) to post sub- |
| rectangles of the back color buffer. Otherwise, EGL_FALSE is |
| returned." |
| |
| Replace all but the last paragraph of section Section 3.9.1, page 50 |
| (Posting to a Window) |
| |
| "To post the color buffer to a window, call |
| |
| EGLBoolean eglSwapBuffers(EGLDisplay dpy, |
| EGLSurface surface); |
| |
| "To post a sub-rectangle of the color buffer to a window, call |
| |
| EGLBoolean eglPostSubBufferNV(EGLDisplay dpy, |
| EGLSurface surface, EGLint x, EGLint y, |
| EGLint width, EGLint height); |
| |
| "Where <x> and <y> are pixel offsets from the bottom-left corner of |
| <surface>. |
| |
| "If <surface> is a back-buffered surface, then the requested portion |
| of the color buffer is copied to the native window associated with |
| that surface. If <surface> is a single-buffered window, pixmap, or |
| pbuffer surface, eglSwapBuffers and eglPostSubBufferNV have no |
| effect. |
| |
| "The contents of ancillary buffers are always undefined after calling |
| eglSwapBuffers or eglPostSubBufferNV. The contents of the color |
| buffer are unchanged if eglPostSubBufferNV is called, or if |
| eglSwapBuffers is called and the value of the EGL_SWAP_BEHAVIOR |
| attribute of <surface> is EGL_BUFFER_PRESERVED. The value of EGL_- |
| SWAP_BEHAVIOR can be set for some surfaces using eglSurfaceAttrib, as |
| described in section 3.5.6. |
| |
| "Native Window Resizing |
| |
| "If the native window corresponding to <surface> has been resized |
| prior to the swap, <surface> must be resized to match. <surface> will |
| normally be resized by the EGL implementation at the time the native |
| window is resized. If the implementation cannot do this transparently |
| to the client, then eglSwapBuffers and eglPostSubBufferNV must |
| detect the change and resize <surface> prior to copying its pixels to |
| the native window. The sub-rectangle defined by <x>, <y>, <width>, and |
| <height> parameters to eglPostSubBufferNV will be clamped to the |
| extents of <surface>. If, after clamping, the rectangle contains no |
| pixels, eglPostSubBufferNV will have no effect." |
| |
| Modify the following sentences in Section 3.9.3, page 51 (Posting |
| Semantics) |
| |
| Paragraph 2, first sentence: |
| |
| "If <dpy> and <surface> are the display and surface for the calling |
| thread's current context, eglSwapBuffers, eglPostSubBufferNV, and |
| eglCopyBuffers perform an implicit flush operation on the context |
| (glFlush for OpenGL or OpenGL ES context, vgFlush for an OpenVG |
| context)." |
| |
| Paragraph 3, first sentence: |
| |
| "The destination of a posting operation (a visible window, for |
| eglSwapBuffers or eglPostSubBufferNV, or a native pixmap, for |
| eglCopyBuffers) should have the same number of components and |
| component sizes as the color buffer it's being copied from." |
| |
| Paragraph 6, first two sentences: |
| |
| "The function |
| |
| EGLBoolean eglSwapInterval(EGLDisplay dpy, EGLint |
| interval); |
| |
| specifes the minimum number of video frame periods per color buffer |
| post operation for the window associated with the current context. The |
| interval takes effect when eglSwapBuffers or eglPostSubBufferNV is |
| first called subsequent to the eglSwapInterval call." |
| |
| Modify the following sentences in Section 3.9.4, page 52 (Posting |
| Errors) |
| |
| Paragraph 1, first sentence: |
| |
| "eglSwapBuffers, eglPostSubBufferNV, and eglCopyBuffers return |
| EGL_FALSE on failure." |
| |
| Paragraph 1, seventh sentence: |
| |
| "If eglSwapBuffers or eglPostSubBufferNV are called and the native |
| window associated with <surface> is no longer valid, an EGL_BAD_- |
| NATIVE_WINDOW error is generated. If eglPostSubBufferNV is called |
| and <x>, <y>, <width>, or <height> are less than zero, EGL_BAD_- |
| PARAMETER is generated." |
| |
| Issues |
| |
| 1. Should all surfaces be required to support sub-buffer posts if |
| this extension is supported? |
| |
| RESOLVED: No. Some implementations may support multiple types of |
| native windows. Support for sub-surface posting is therefore a |
| per-surface property, so a surface query should be used to determine |
| which surfaces support sub-surface posts. |
| |
| 2. What should this extension be called? |
| |
| RESOLVED: Names considered EGL_NV_copy_sub_buffer, EGL_NV_present_sub- |
| surface, EGL_NV_post_sub_buffer. eglCopySubBuffer() sounded too |
| similar to eglCopyBuffer(), which operates on different types of |
| surfaces. EGL_present_sub_surface was originally chosen as it was |
| sufficiently different than eglCopyBuffer(), but based on internal |
| feedback, the term "Post" is preferable to "Present" because it is |
| already used in the EGL spec to describe buffer presentation |
| operations. "Buffer" was chosen over "surface" at this point as well, |
| because it is more consistent with the eglSwapBuffers() and |
| eglCopyBuffer() commands, and eglPostSubBuffer() is still |
| differentiated enough from eglCopyBuffer() that the two won't be |
| confused. |
| |
| Revision History |
| |
| #3 (James Jones, November 5, 2010) |
| -Renamed from NV_present_sub_surface to NV_post_sub_buffer based on |
| feedback from internal reviews. |
| |
| -Allowed EGL_POST_SUB_BUFFER_SUPPORTED_NV to be used as a hint when |
| creating window surfaces. |
| |
| -Clarified that eglSwapInterval applies to all color-buffer post |
| operations affecting on-screen surfaces, not just eglSwapBuffers. |
| |
| #2 (James Jones, November 1, 2010) |
| - Fixed a few typos. |
| |
| #1 (James Jones, October 22, 2010) |
| - Initial revision, based on GLX_MESA_copy_sub_buffer |