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 parameter of eglQuerySurface and by the 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) " specifies a list of attributes for the window. The list has the same structure as described for eglChooseConfig. Attributes that can be specified in 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 and are pixel offsets from the bottom-left corner of . "If is a back-buffered surface, then the requested portion of the color buffer is copied to the native window associated with that surface. If 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 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 has been resized prior to the swap, must be resized to match. 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 prior to copying its pixels to the native window. The sub-rectangle defined by , , , and parameters to eglPostSubBufferNV will be clamped to the extents of . 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 and 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 is no longer valid, an EGL_BAD_- NATIVE_WINDOW error is generated. If eglPostSubBufferNV is called and , , , or 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