diff options
Diffstat (limited to 'glew/auto/EGL-Registry/extensions/EXT')
43 files changed, 9859 insertions, 0 deletions
diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_bind_to_front.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_bind_to_front.txt new file mode 100644 index 0000000..e83f9c9 --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_bind_to_front.txt @@ -0,0 +1,108 @@ +Name + + EXT_bind_to_front + +Name Strings + + EGL_EXT_bind_to_front + + +Contributors + + Daniel Herring + +Contacts + + Daniel Herring, Core Avionics & Industrial Inc., daniel dot herring at ch1group dot com + +Status + + Complete + +Version + + Version 1.0, February 21, 2017 + +Number + + EGL Extension #121 + +Dependencies + + Requires EGL 1.2. + +Overview + + This extension allows for using double buffered Pbuffers for rendering to textures, by + allowing a new enumeration to be used in eglBindTexImage. EGL_FRONT_BUFFER_EXT is used + to denote reading the textures data from the front buffer of a double buffered Pbuffer. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + EGL_FRONT_BUFFER_EXT 0x3464 + +Modify Section 3.6.1 of the EGL 1.2 Specification, paragraph 1 + Add EGL_FRONT_BUFFER_EXT to list of acceptable values for buffer attribute. + +Modify Section 3.6.2 of the EGL 1.2 Specification, paragraph 5 + Add EGL_FRONT_BUFFER_EXT to list of acceptable values for buffer attribute. + +Modify Section 3.5.2 of the EGL 1.2 Specification, paragraph 4 + Add EGL_RENDER_BUFFER to list of attributes which can be accepted in attrib_list. + +Add to Section 3.5.2 of the EGL 1.2 Specification + EGL_RENDER_BUFFER specifies the number of color buffers which should be useable by the + client API rendering to the Pbuffer. If its value is EGL_SINGLE_BUFFER, then there is + one color buffer the client APIs will render to directly. If its value is EGL_BACK_BUFFER, + then there are at least two color buffers the client API can render to. eglSwapBuffers + is used to switch which color buffer is currently being rendered to. By default, all + client APIs should render into the back buffer. The default value of EGL_RENDER_BUFFER + is EGL_SINGLE_BUFFER. + +Modify Section 2.2.2 of the EGL 1.2 Specification, paragraph 2 + Pbuffer surfaces have a back buffer but no associated window, so the back buffer + need not be copied. + Change to: + Pbuffer surfaces have no associated window, and include a back buffer, used by + default, for rendering to by the client API. Pbuffers may have a front buffer + used during render to texture operations to provide a read only texture which may + be used while the back buffer is being rendered to. + +Modify Section 3.5.6 + Querying EGL RENDER BUFFER returns the buffer which client API rendering + is requested to use. For a window surface, this is the same attribute value + specified when the surface was created. For a Pbuffer surface, it is always + EGL BACK BUFFER. For a pixmap surface, it is always EGL SINGLE BUFFER. To + determine the actual buffer being rendered to by a context, call eglQueryContext + (see section 3.7.4). + + Change to: + Querying EGL RENDER BUFFER returns the buffer which client API rendering + is requested to use. For a window surface or Pbuffer surface, this is the + same attribute value specified when the surface was created. For a pixmap + surface, it is always EGL SINGLE BUFFER. To determine the actual buffer being + rendered to by a context, call eglQueryContext (see section 3.7.4). + +Revision History + Version 1.0, 21/02/2017 - Initial Version + +Question: + What if the implementation already uses double buffering for single buffered PBuffers? + Such as when an implementation must insert a resolve to a texture instead of being + able to use the same memory. +Answer: + EGL_BACK_BUFFER would still refer to the resolved buffer. But in the case of the a + double buffer EGL_FRONT_BUFFER should be used to reference the resolved buffer instead + of EGL_BACK_BUFFER as in this case the user has specified 2 buffers and knows they want + the resolved buffer. + In the double buffer case where only a back draw and a front resolved buffer is used + the implementation may not support EGL_BACK_BUFFER and should generate an EGL_BAD_ + PARAMETER error when not supporting EGL_BACK_BUFFER texture binding. diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_buffer_age.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_buffer_age.txt new file mode 100644 index 0000000..5e46fa9 --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_buffer_age.txt @@ -0,0 +1,329 @@ +Name + + EXT_buffer_age + +Name Strings + + EGL_EXT_buffer_age + +Notice + + Copyright 2011,2012 Intel Cooperation + +IP Status + + No known IP claims. + +Contributors + + Robert Bragg + Neil Roberts + Tapani Pälli + Kristian Høgsberg + Acorn Pooley + James Jones + +Contacts + + Robert Bragg, Intel (robert.bragg 'at' intel.com) + +Status + + Complete. + +Version + + 12 - June 13, 2013 + +Number + + EGL Extension #52 + +Dependencies + + Requires EGL 1.4 + + This extension is written against the wording of the EGL 1.4 + Specification. + +Overview + + The aim of this extension is to expose enough information to + applications about how the driver manages the set of front and + back buffers associated with a given surface to allow applications + to re-use the contents of old frames and minimize how much must be + redrawn for the next frame. + + There are lots of different ways for a driver to manage these + buffers, from double buffering, different styles of triple + buffering and even n-buffering or simply single buffer rendering. + We also need to consider that power management events or memory + pressure events might also result in some of the buffers not + currently in-use being freed. + + This extension lets applications query the age of the back buffer + contents for an EGL surface as the number of frames elapsed since + the contents were most recently defined. The back buffer can + either be reported as invalid (has an age of 0) or it may be + reported to contain the contents from n frames prior to the + current frame. + + Once the application has queried the buffer age, the age of + contents remains valid until the end of the frame for all pixels + that continue to pass the pixel ownership test. + + For many use-cases this extension can provide an efficient + alternative to using the EGL_BUFFER_PRESERVED swap behaviour. The + EGL_BUFFER_PRESERVED swap behaviour adds a direct dependency for + any frame n on frame n - 1 which can affect the pipelining of + multiple frames but also implies a costly copy-back of data to + initialize the back-buffer at the start of each frame. + + For example if you consider a double buffered application drawing + a small spinning icon, but everything else in the scene is static. + If we know that 2 buffers are continuously being recycled each + time eglSwapBuffers is called then even though 100s of frames may + need to be drawn to animate the icon it can be seen that the two + buffers are remaining unchanged except within the bounds of the + icon. In this scenario ideally the application would simply + perform an incremental update of the old buffer instead of + redundantly redrawing all the static parts of the scene. The + problem up until now though has been that EGL doesn't report how + buffers may be recycled so it wasn't safe for applications to try + and reuse their contents. Now applications can keep track of all + the regions that have changed over the last n frames and by + knowing the age of the buffer they know how to efficiently repair + buffers that are re-cycled instead of redrawing the entire scene. + +New Procedures and Functions + + None + +New Tokens + + EGL_BUFFER_AGE_EXT 0x313D + +Additions to Section 2.2 of the EGL 1.4 Specification (Rendering +Contexts and drawing surfaces) + + Add the following text to a new subsection titled "Pixel + Ownership Test" after the subsection titled "Interaction With + Native Rendering": + + A fragment produced by a client api through rasterization + with windows coordinates (x, y) only modifies the pixel in the + rendering surface at that location if it passes the pixel + ownership test defined by the native window system. + + The pixel ownership test determines if the pixel at location + (x, y) in a rendering surface is currently owned by the client + api (more precisely, by this its context). If it is not, the + native window system decides the fate of the incoming + fragment. Possible results are that the fragment is discarded + or that some subset of the subsequent per-fragment operations + are applied to the fragment. This test allows the window + system to control the client api behavior, for instance, when + a window surface is obscured. + + The pixel ownership test can only fail for window surfaces, + not for pixmap surfaces or pbuffer surfaces. + + Most native window systems will be able to guarantee that no + fragment will ever fail the pixel ownership test, but a + notable exception to this is the X11 window system where, + depending on the driver, the pixel ownership test may fail + when portions of a window are obscured. + +Additions to Section 3.5 of the EGL 1.4 Specification (Rendering Surfaces) + + Add the following to the table of "Queryable surface attributes + and types": + + +----------------------+---------+-----------------------------+ + | Attribute | Type | Description | + +----------------------+---------+-----------------------------+ + | EGL_BUFFER_AGE_EXT | Integer | Age of back-buffer contents | + +----------------------+---------+-----------------------------+ + Table aaa: Queryable surface attributes and types. + + + Add the following text to the subsection titled "Surface + Attributes" in the description for eglQuerySurface + + Querying EGL_BUFFER_AGE_EXT returns the age of the color + contents of the current back-buffer as the number of frames + elapsed since it was most recently defined. Applications can, + under certain conditions described below, use this age to + safely rely on the contents of old back- buffers to + potentially reduce the amount of redrawing they do each frame. + A frame is the period between calls to any of the functions in + table 3.X, hereafter referred to as "frame boundaries." + + Function name + -------------------- + eglSwapBuffers + + Table 3.X, Frame Boundary Functions + + Buffers' ages are initialized to 0 at buffer creation time. + When a frame boundary is reached, the following occurs before + any exchanging or copying of color buffers: + + * The current back buffer's age is set to 1. + * Any other color buffers' ages are incremented by 1 if + their age was previously greater than 0. + + For the purposes of buffer age tracking, a buffer's content + is considered defined when its age is a value greater than 0. + + For example, with a double buffered surface and an + implementation that swaps via buffer exchanges, the age would + usually be 2. With a triple buffered surface the age would + usually be 3. An age of 1 means the previous swap was + implemented as a copy. An age of 0 means the buffer has only + just been initialized and the contents are undefined. Single + buffered surfaces have no frame boundaries and therefore + always have an age of 0. + + Frame boundaries are the only events that can set a buffer's + age to a positive value. Once EGL_BUFFER_AGE_EXT has been + queried then it can be assumed that the age will remain valid + until the next frame boundary. EGL implementations are + permitted, but not required, to reset the buffer age in + response to pixel ownership test changes for any pixels within + the drawable, or if new pixels are added to or removed from + the drawable, i.e., the drawable is resized. A reset of this + nature does not affect the age of content for pixels that pass + the pixel ownership test before and after the event that + caused the reset. In other words, applications can assume + that no event will invalidate the content of pixels that + continuously pass the pixel ownership test between when the + buffer age was queried and the following frame boundary. + + It is up to applications to track pixel ownership using data + collected from relevant window system events, such as + configuration and expose events on X11. + + If the EGL implementation decides to free un-used back-buffers + when the system is under memory pressure or in response to + power-management events then EGL will return an age of 0 when + it allocates a new buffer at the start of a new frame. + + If the EGL_BUFFER_PRESERVED swap behaviour is in use then + it can be assumed that the age will always be 1. It is + recommended where possible though that the + EGL_BUFFER_PRESERVED swap behaviour not be used since it can + have severe performance consequences. Keeping track of the + buffer age and the regions that have changed over the last 2 + or 3 frames instead can often replace the need for using + EGL_BUFFER_PRESERVED. + + EGL_BUFFER_AGE_EXT state is a property of the EGL surface that + owns the buffers and lives in the address space of the + application. That is, if an EGL surface has been created from + a native window or pixmap that may be shared between + processes, the buffer age is not guaranteed to be synchronized + across the processes. Binding and unbinding a surface to and + from one or more contexts in the same address space will not + affect the ages of any buffers in that surface. + + Add the following text to last paragraph of the subsection titled + "Surface Attributes" in the description for eglQuerySurface + errors. + + If querying EGL_BUFFER_AGE_EXT and <surface> is not bound as + the draw surface to the calling threads current context + an EGL_BAD_SURFACE error is generated. + +Dependencies on OpenGL ES + + None + +Dependencies on OpenVG + + None + +Issues + + 1) What are the semantics if EGL_BUFFER_PRESERVED is in use + + RESOLVED: The age will always be 1 in this case. More + clarification about this was added along with the + recommendation to use the buffer age to reuse buffers instead + of EGL_BUFFER_PRESERVED when possible to avoid the + in-efficiencies of introducing a dependency for each frame on + the previous frame. + + 2) How can an application know that all pixels of a re-usable + buffer were originally owned by the current context? + + RESOLVED: It is up to the application to track pixel ownership + using existing window system specific events, such as X11 + expose or configure notify events. + + 3) What are the semantics if the buffer age attribute is queried for + a surface that isn't bound to the calling thread's context as the + draw surface? + + RESOLVED: we report an EGL_BAD_SURFACE error as is similarly + done when calling eglSwapBuffers for such a surface. + + 4) What is the buffer age of a single buffered surface? + + RESOLVED: 0. This falls out implicitly from the buffer age + calculations, which dictate that a buffer's age starts at 0, + and is only incremented by frame boundaries. Since frame + boundary functions do not affect single buffered surfaces, + their age will always be 0. + + 5) What guarantees are provided after querying the buffer age? + + RESOLVED: The buffer age of pixels which continue to pass the + pixel ownership test must remain valid until the next frame + boundary otherwise applications can't be absolutely sure of + the consistency of their rendered content. Implementations + may reset the queryable age of the buffer when pixel ownership + changes occur. This is further clarified in section 3.5 + +Revision History + + Version 1, 25/07/2011 + - First draft + Version 2, 03/08/2011 + - Clarified semantics for using EGL_BUFFER_PRESERVED + Version 3, 01/09/2011 + - Fixed a prototype inconsistency + Version 4, 03/11/2011 + - Split out the buffer age parts from EGL_INTEL_start_frame + Version 5, 20/03/2012 + - Document that once the age is queried it remains valid until + the end of the frame so we can remove the need for a separate + EGL_EXT_start_frame extension. + Version 6, 20/03/2012 + - Clarify that only buffers who's contents were fully owned by + the context are tracked. + Version 7, 20/03/2012 + - Document that an error will be generated if querying the age + for a surface not bound to the current context. + Version 8, 25/08/2012 + - Update in line with changes made to the GLX_EXT_buffer_age draft spec + including more relaxed pixel ownership requirements and explicit + clarification of the buffer age calculation. + Version 9 20/09/2012 + - Update in line with changes made to the EGL_EXT_buffer age + draft space + Version 10 29/11/2012 + - Add pixel ownership test section and other minor + clarifications + Version 11 13/12/2012 + - Allocated enumerant and marked complete. + Version 12, 13/06/2013, Chad Versace <chad.versace@intel.com> + - Remove the "all rights reserved" clause from the copyright notice. The + removal does not change the copyright notice's semantics, since the + clause is already implied by any unadorned copyright notice. But, the + removal does diminish the likelihood of unwarranted caution in readers + of the spec. + - Add "IP Status" section to explicitly state that this extension has no + knonw IP claims. + Version 13, 14/10/2021, Guanzhong Chen + - Fix an incorrect token name diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_client_extensions.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_client_extensions.txt new file mode 100644 index 0000000..8e24447 --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_client_extensions.txt @@ -0,0 +1,408 @@ +Name + + EXT_client_extensions + +Name Strings + + EGL_EXT_client_extensions + +Contributors + + Chad Versace <chad.versace@intel.com> + Ian Romanick <ian.d.romanick@intel.com> + Jakob Bornecrantz <jakob@vmware.com> + James Jones <jajones@nvidia.com> + +Contacts + + Chad Versace <chad.versace@intel.com> + +Status + + Complete + +Version + + Version 11, 2013.10.10 + +Number + + EGL Extension #58 + +Extension Type + + EGL client extension + +Dependencies + + Requires EGL 1.4. + + This extension is written against the wording of the EGL 1.4 + Specification. + +Overview + + This extension introduces the concept of *extension type*, requires that + each EGL extension belong to exactly one type, and defines two types: + display and client. It also provides a method to query, without + initializing a display, the set of supported client extensions. + + A display extension adds functionality to an individual EGLDisplay. This + type of extension has always existed but, until EGL_EXT_client_extensions, + lacked an identifying name. + + A client extension adds functionality that is independent of any display. + In other words, it adds functionality to the EGL client library itself. This + is a new type of extension defined by EGL_EXT_client_extensions. + EGL_EXT_client_extensions is itself a client extension. + + We suggest that each future extension clearly state its type by including + the following toplevel section in its extension specification, preceding the + Dependencies section. For client extensions, this suggestion is + a requirement. + + Extension Type + + <Either "EGL display extension" or "EGL client extension" or + a future extension type.> + + By cleanly separating display extensions from client extensions, + EGL_EXT_client_extensions solves a bootstrap problem for future EGL + extensions that will modify display initialization. To query for such + extensions without EGL_EXT_client_extensions, an EGL client would need to + initialize a throw-away EGLDisplay solely to query its extension string. + Initialization of the throw-away display may have undesired side-effects + (discussed in the issues section below) for EGL clients that wish to use the + new methods of display initialization. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + None + +Additions to the EGL 1.4 Specification: + + + Add the following section to Chapter 2 "EGL Operation": + + "2.n Extensions + + EGL implementations may expose additional functionality beyond that + described by this specification. Additional functionality may include new + functions, new enumerant values, and extended behavior for existing + functions. Implementations advertise such extensions to EGL by exposing + *extension strings*, which are queryable with eglQueryString. + + Each EGL extension belongs to exactly one of the following types: + + Display Extensions + A *display extension* adds functionality to an individual + EGLDisplay. Different instances of EGLDisplay may support different + sets of display extensions. + + Client Extensions + A *client extension* adds functionality that is independent of any + display. In other words, it adds functionality to the EGL client + library itself. In a given process, there exists exactly one set, + possibly empty, of supported client extensions. When the client + extension string is first queried, that set becomes immutable." + + Replace the paragraph in section 3.3 "EGL Versioning" that begins "The + EGL_EXTENSIONS string" with the following text: + + "The EGL_EXTENSIONS string describes which set of EGL extensions are + supported. The string is zero-terminated and contains a space-separated + list of extension names; extension names themselves do not contain spaces. + If there are no extensions to EGL, then the empty string is returned. + + If <dpy> is EGL_NO_DISPLAY, then the EGL_EXTENSIONS string describes the set + of supported client extensions. If <dpy> is a valid, initialized display, + then the EGL_EXTENSIONS string describes the set of display extensions + supported by the given display. The set of supported client extensions is + disjoint from the set of extensions supported by any given display [fn]. + + [fn] This is a consequence of the requirement in Section 2.n Extensions that + each extension belong to exactly one extension type." + + Replace the last paragraph of section 3.3 "EGL Versioning" with: + + "On failure, NULL is returned. An EGL_BAD_DISPLAY error is generated if + <dpy> is not a valid display, unless <dpy> is EGL_NO_DISPLAY and <name> is + EGL_EXTENSIONS. An EGL_NOT_INITIALIZED error is generated if <dpy> is + a valid but uninitialized display. An EGL_BAD_PARAMETER error is generated + if <name> is not one of the values described above." + +Conformance Tests + + 1. Before any call to eglGetDisplay, call `eglQueryString(EGL_NO_DISPLAY, + EGL_EXTENSIONS)`. Verify that either + + a. The call returns NULL and generates EGL_BAD_DISPLAY. + b. The call returns an extension string that contains, at a minimum, + this extension and generates no error. + + 2. Obtain a display with eglGetDisplay but do not initialize it. Verity + that passing the uninitialized display to `eglQueryString(dpy, + EGL_EXTENSIONS)` returns NULL and generates EGL_NOT_INITIALIZED. + + 3. Obtain a list of display extensions by calling `eglQueryString(dpy, + EGL_EXTENSIONS)` on an initialized display. Obtain the list of client + extensions by calling `eglQueryString(EGL_NO_DISPLAY, EGL_EXTENSIONS)`. + If both calls succeed, verify the two lists are disjoint. + +Issues + + 1. How should clients detect if this extension is supported? + + RESOLVED: If an EGL implementation supports this extension, then + `eglQueryString(EGL_NO_DISPLAY, EGL_EXTENSIONS)` returns + a well-formed extension string and generates no error. Otherwise, it + returns NULL and generates EGL_BAD_DISPLAY. + + 2. On EGL platforms that define EGL_NO_DISPLAY as NULL, does not calling + `eglQueryString(EGL_NO_DISPLAY, EGL_EXTENSIONS)` risk a null pointer + dereference? Therefore, how is it possible on such platforms for + a client to safely detect if this extension is supported? + + RESOLVED: According to the EGL 1.4 specification, calling + `eglQueryString(EGL_NO_DISPLAY, name)` returns NULL and generates + EGL_BAD_DISPLAY. No null pointer dereference occurs even if the + platform defines EGL_NO_DISPLAY as NULL. + + 3. What existing extensions should returned by + `eglQueryString(EGL_NO_DISPLAY, EGL_EXTENSIONS)`? + + RESOLVED: Possibly EGL_NV_system_time. + + 4. What should be the relationship between the extension string of + EGL_NO_DISPLAY and the extension string of a valid display? That is, + should the former be a subset of the latter? Should the two be + disjoint? Should the relationship remain undefined? + + Another phrasing of this issue is: When, if ever, should client + extensions appear in a display's extension string? + + RESOLVED: The extension string of EGL_NO_DISPLAY must be disjoint + from the extension string of any valid display. That is, EGL_NO_DISPLAY + must advertise only client extensions, and valid displays must not + advertise client extensions. By defining a clear relationship between + the two types of extension strings, we enforce consistent behavior among + implementations, thus preventing possible confusion from application + developers. + + DISCUSSION: This resolution has special implications for systems where + libEGL is a vendor-independent library that loads and then dispatches + to the appropriate vendor-provided EGL library. The resolution requires + that client extensions, as well the construction of extension strings, + be at least partially implemented in the vendor-independent library. + + The alternative resolution of mandating the 'superset' relation (that + is, that the extension string of a valid display must be a superset of + that of EGL_NO_DISPLAY) was rejected due to potential confusion on + behalf of the application developer as well as the driver implementer. + What follows is an example of each. + + a) Suppose an EGL implementation supported creation of + a software-renderer EGLDisplay through a client extension named + EGL_XYZ_platform_software_renderer. If the 'superset' relation were + mandated, then each display, whether it were hardware-accelerated or + software-only, would advertise the EGL_XYZ_platform_software_renderer + extension string. This would likely confuse application developers. + + b) If the 'superset' relation were mandated, then the possibility + exists that a vendor would ship a hybrid extension that is both + a client extension and a display extension. Such a hybrid extension + poses subtle difficulties for systems where libEGL is + a vendor-independent library that dispatches to the appropriate + vendor-provided EGL driver. On such a system, the extension's hybrid + nature may require that each vendor-provided EGL driver support the + extension before the vendor-independent EGL library could safely + expose the extension. By choosing the 'disjoint' relation rather + than 'superset', we prevent this problematic situation from + occuring. + + 5. Should client extension specifications explicitly state they are + returned in the extension string of EGL_NO_DISPLAY? + + RESOLVED: Yes. Enforce this by requiring that client extension + specifications contain the toplevel section "Extension Type". + + 6. As explained in the overview section, this "extension solves + a bootstrap problem for future EGL extensions that modify display + initialization". What solutions to the bootstrap problem were + considered? Why was EGL_EXT_client_extensions chosen as the best + solution? + + DISCUSSION: First let's discuss the exact nature of the bootstrap + problem and of the future EGL extensions that modify display + initialization. + + Mesa's EGL implementation supports multiple native platforms (such as + Wayland, GBM, and X11) at runtime, and we expect that more + implementations will do so in the future. The EGL API is deficient for + such implementations because it does not yet provide a way for clients + to query the set of supported native platforms. Also, EGL provides no + way for clients to specify to which platform the native display belongs + during display initialization. (That is, eglGetDisplay has a native + display parameter, but no parameter specifying the native platform). + + Future EGL extensions, currently under progress, will solve these + deficiencies in the EGL API by (1) adding a variant of eglGetDisplay + that allows specification of the platform to which the native display + belongs and (2) by advertising the set of native platforms supported by + the implementation. + + However, there exists a bootstrap problem here. To query if a given + native platform is supported, the EGL client must initialize an + EGLDisplay to query its extension string. But, not yet knowing which + native platforms the EGL implementation supports, the client cannot + safely pass any native display to eglGetDisplay, and therefore cannot + obtain an extension string. + + The following solutions to this bootstrap problem have been considered. + For conciseness, let's refer to the future EGL extensions that modify + display initialization as "client extensions". + + 1. PROPOSED SOLUTION: To determine if an EGL implementation supports + a given client extension, require that the EGL client call + eglGetProcAddress on some function defined by the extension. If + eglGetProcAddress returns non-null, then the implementation + supports the extension. + + ANALYSIS: The EGL 1.4 spec permits eglGetProcAddress to return + non-null for unrecognized function names. Therefore, this + solution's method may produce false positives on some + implementations. + + Also, this solution does not permit detection of client extensions + that add no new functions. + + 2. PROPOSED SOLUTION: To determine if an EGL implementation supports + a given client extension, the EGL client should examine the + extension string of EGL_DEFAULT_DISPLAY. Querying + EGL_DEFAULT_DISPLAY is a failsafe mechanism by which the EGL + client can obtain an extension string, because EGL_DEFAULT_DISPLAY + is a valid input to eglGetDisplay regardless of which platforms + the EGL implementation supports. + + ANALYSIS: This solution is awkward. It requires that the client + initialize a throw-away EGLDisplay solely to query its extension + string, even though the desired extension is not a property of any + display but of the EGL library itself. + + This solution also has a subtle fatal problem. It is not backwards + compatible with Mesa. As of 2013-06-07, Mesa's EGL implementation + stores at runtime a user-chosen native platform in global + write-once state. Calling eglGetDisplay is one action that + results in writing to that state. Therefore, if a client process + running on such a problematic version of Mesa initialized + EGL_DEFAULT_DISPLAY solely to detect some client extension, then + the client process would be confined for its lifetime to use only + that platform to which EGL_DEFAULT_DISPLAY belongs. This + confinement may be fatal if the process had wanted to use + a different platform. + + 3. PROPOSED SOLUTION: Abandon the concept of client extensions. + Instead, in implementations that support multiple window systems + at runtime, eglGetDisplay should autodetect the platform to which + the native display belongs. A suitable error should be generated + if an unsupported native display is passed to eglGetDisplay. + + ANALYSIS: For some native platforms, the display type is opaque + with no defined ABI. (For example, in libX11 the 'Display' type is + an opaque typedef). There exists no method by which eglGetDisplay + could reliably detect that the given native display belongs to + such a platform. + + This solution also has a subtle fatal problem. The client + extensions will likely specify that an EGL client may create EGL + resources from multiple platforms in the same process. But, Mesa's + global write-once state, mentioned above, prevents using multiple + platforms in one process. Therefore, under this proposed solution + and on a system where a problematic version of Mesa is installed, + the client would be unable to detect if EGL supported multiple + platforms per process without committing to the platform to which + the first initialized display belonged. + + 4. ACCEPTED SOLUTION: Allow the EGL client to query the extension + string of EGL_NO_DISPLAY, which would contain the client + extensions. + + ANALYSIS: This solution does not require the initialization of + a throw-away EGLDisplay, nor does it require that native display + types have a fixed ABI. + + This is the solution described by this extension specification, + EGL_EXT_client_extensions. + +Revision History + + Version 11, 2013.10.10 (Chad Versace) + - Fix conformance test #3. It should require that the display extension + list be disjoint to rather than a superset of the client extension + list. (The 'superset' requirement was changed pre-publication to + 'disjoint' in version 8). + + Version 10, 2013.07.03 (Chad Versace) + - Version 9 and 10 are identical due to a versioning error. + + Version 9, 2013.07.03 (Chad Versace) + - Define the concept of *extension type*, require require that each EGL + extension belong to exactly one type, and define two types: display + and client. + - Suggest new section "Extension Type" for future extension + specifications. + - Add new section 2.n Extensions. + - Simplify modifications to section 3.3 by using the new extension type + terminology. + + Version 8, 2013.07.01 (Chad Versace) + - Change resolution of Issue 4 from the 'superset' relation to the + 'disjoint' relation, according to discussion with Jakob Bornecrantz. + Acked by James Jones. + + Version 7, 2013.06.10 (Chad Versace) + - Fix typos. + s/unitialized/uninitialized/ + s/EGL_NO_EXTENSIONS/EGL_EXTENSIONS/ + + Version 6, 2013.06.07 (Chad Versace) + - Remove the Motivation section, merging its content into the Overview + section and Issue 6. + + Version 5, 2013.06.07 (Chad Versace) + - Resolve issue 3 regarding classifying currently published extensions + as client extensions. + - Resolve issue 4 regarding the relationship among client and display + extension strings. + - Add and resolve issue 5, requiring client extension specifications + to contain language about the EGL_NO_DISPLAY extension string. + + Version 4, 2013.05.14 (Chad Versace) + - Add issue 4. + + Version 3, 2013.03.24 (Chad Versace) + - Fix conformance test condition 1.b. The returned extension string + should list, at a minimum, this extension. [Found by Ian Romanick]. + - Add section "Movivation". [Requested by Ian Romanick]. + + Version 2, 2013.03.06 (Chad Versace) + - Remove enum EGL_CLIENT_EXTENSIONS_EXT. Reuse EGL_EXTENSIONS for that + purpose. + - To obtain client extensions, require the eglQueryString be called + with dpy=EGL_NO_DISPLAY rather than dpy=NULL. [Suggested by James + Jones]. + - Add descriptions of conformance tests. [Suggested by Ian Romanick]. + - Add sections "Overview" and "Issues". + + Version 1, 2013.03.06 (Chad Versace) + - First draft + +# vim: filetype=text expandtab autoindent shiftwidth=4 textwidth=80: diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_client_sync.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_client_sync.txt new file mode 100644 index 0000000..1868feb --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_client_sync.txt @@ -0,0 +1,146 @@ +Name + + EXT_client_sync + +Name Strings + + EGL_EXT_client_sync + +Contributors + + Daniel Kartch + +Contacts + + Daniel Kartch, NVIDIA Corporation (dkartch 'at' nvidia.com) + +Status + + Complete + +Version + + Version 2, April 20, 2018 + +Number + + EGL Extension #129 + +Extension type + + EGL display extension + +Dependencies + + Requires EGL_EXT_sync_reuse + +Overview + + The EGL_KHR_reusable_sync extension defines an EGL_SYNC_REUSABLE_KHR + EGLSync type which is signaled and unsignaled by client events. The + EGL_EXT_sync_reuse extension allows all EGLSyncs to become reusable. + The signaling behavior associated with EGL_SYNC_REUSABLE_KHR is + still desirable, but the name becomes misleading if all EGLSyncs can + be reused. This extension defines an EGLSync type with equivalent + behavior, separating the signaling mechanism from the reusability. + +New Procedures and Functions + + EGLBoolean eglClientSignalSyncEXT( + EGLDisplay dpy, + EGLSync sync, + const EGLAttrib *attrib_list); + +New Types + + None + +New Tokens + + Accepted by the <type> parameter of eglCreateSync, and returned + in <value> when eglGetSyncAttrib is called with <attribute> + EGL_SYNC_TYPE: + + EGL_SYNC_CLIENT_EXT 0x3364 + + Returned in <value> when eglGetSyncAttrib is called with attribute + EGL_SYNC_CONDITION: + + EGL_SYNC_CLIENT_SIGNAL_EXT 0x3365 + +Add to the list of sync object decriptions in 3.8.1 Sync Objects + + A <client sync object> reflects the readiness of some client-side + state. Sync objects of this type are not visible to API contexts and + may not be used with eglWaitSync. They may be waited for with + eglClientWaitSync or polled with eglGetSyncAttrib as other sync + types. + +Add to the end of 3.8.1 Sync Objects + + The command + + EGLBoolean eglClientSignalSyncEXT(EGLDisplay dpy, EGLSync sync, + const EGLAttrib *attrib_list); + + may be called to switch sync objects which support it to the + signaled state. Currently only sync objects with type + EGL_SYNC_CLIENT_EXT provide this support. The attribute list may be + used to provide additional information to the signaling operation, + as defined for the sync type. + + Errors + + eglClientSignalSyncEXT returns EGL_FALSE on failure, and has no + effect on <sync>. + If <dpy> is not the name of a valid, initialized EGLDisplay, an + EGL_BAD_DISPLAY error is generated. + If <sync> is not a valid sync object associated with <dpy>, an + EGL_BAD_PARAMETER error is generated. + If <attrib_list> contains an attribute name not defined for the + type of <sync>, an EGL_BAD_ATTRIBUTE error is generated. + If <sync>'s type does not support this direct signaling, an + EGL_BAD_ACCESS error is generated. + +Insert new subsection in 3.8.1 Sync Objects + + 3.8.1.x Creating and Signaling Client Sync Objects + + If type is EGL_SYNC_CLIENT_EXT, a client sync object is created. The + EGL_SYNC_STATUS attribute may be specified as either EGL_UNSIGNALED + or EGL_SIGNALED, and will default to EGL_UNSIGNALED. No other + attributes may be specified for a client sync object. The value of + EGL_SYNC_CONDITION will be set to EGL_SYNC_CLIENT_SIGNAL_EXT. + + A client sync object in the unsignaled state will switch to the + signaled state when eglClientSignalSyncEXT is called. No attributes + are supported for signaling a sync object of this type. Signaling a + client sync object which is already in the signaled state will have + no effect. + + A client sync object which is in the signaled state may be switched + back to the unsignaled state with eglUnsignalSyncEXT. No attributes + are supported for unsignaling a sync object of this type. + +Add to the error list for eglWaitSync in 3.8.1.3 Waiting for Sync +Objects + + If <sync> is of type EGL_SYNC_CLIENT_EXT, an EGL_BAD_ACCESS error is + generated. + +Issues + + None + +Revision History + + #2 (April 20, 2018) Daniel Kartch + - Renamed to EXT + - Fixed missing attrib_list in New Functions section + - Eliminated condition as an allowed attribute at creation. This + is inconsistent with other sync extensions, and there is no + need to make it configurable at this time. Future extensions + can make the condition configurable if desired. + + #1 (Feburary 22, 2018) Daniel Kartch + - Initial draft as XXX diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_compositor.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_compositor.txt new file mode 100644 index 0000000..6e98428 --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_compositor.txt @@ -0,0 +1,400 @@ +Name + + EXT_compositor + +Name Strings + + EGL_EXT_compositor + +Contributors + + Marc Moody + Daniel Herring + +Contacts + + Marc Moody, Boeing Inc., marc dot d dot moody at boeing dot com + Daniel Herring, Core Avionics & Industrial Inc., daniel dot herring at ch1group dot com + +Status + + Complete + +Version + Version 1.0, February 3, 2017 + +Number + + EGL Extension #116 + +Dependencies + + Requires EGL 1.0. + + This extension is written against the wording of the EGL 1.4 + Specification - April 6, 2011, but may be implemented against earlier + versions. + +Overview + + This extension allows for the composition of multiple windows within + a multi-partition EGL system. The extension allows a primary EGLContext and + window to be created for each display. All other windows are created using + non-displayable surfaces. A handle to each off-screen window is provided + to the primary EGLContext to allow the composition of all non-displayable windows + on a single display. + + For each display, there is one EGLContext which has access to create on screen + windows, this is call the primary context for this display. All other EGLContexts + are referred to as secondary contexts. + + This extension requires a multi-partition EGL driver to support asynchronous + rendering of off screen surfaces. + + Information assurance is provided by preventing context and surface creation by + unregistered contexts and by preventing the non-primary contexts and surfaces + from rendering to the display. + +New Types + + None + +New Procedures and Functions + + EGLBoolean eglCompositorSetContextListEXT (const EGLint *external_ref_ids, + EGLint num_entries); + + EGLBoolean eglCompositorSetContextAttributesEXT (EGLint external_ref_id, + const EGLint *context_attributes, + EGLint num_entries); + + EGLBoolean eglCompositorSetWindowListEXT (EGLint external_ref_id, + const EGLint *external_win_ids, + EGLint num_entries); + + EGLBoolean eglCompositorSetWindowAttributesEXT (EGLint external_win_id, + const EGLint *window_attributes, + EGLint num_entries); + + EGLBoolean eglCompositorBindTexWindowEXT (EGLint external_win_id); + + EGLBoolean eglCompositorSetSizeEXT (EGLint external_win_id, + EGLint width, EGLint height); + + EGLBoolean eglCompositorSwapPolicyEXT (EGLint external_win_id, + EGLint policy); + + +New Tokens + + New attributes accepted by the <attrib_list> argument of + eglCreateContext: + + EGL_PRIMARY_COMPOSITOR_CONTEXT_EXT 0x3460 + + New attributes accepted by the <attrib_list> argument of + eglCreateContext and eglCreateWindowSurface: + + EGL_EXTERNAL_REF_ID_EXT 0x3461 + + New attributes accepted by the <policy> argument of + eglCompositorSwapPolicyHint: + + EGL_COMPOSITOR_DROP_NEWEST_FRAME_EXT 0x3462 + + EGL_COMPOSITOR_KEEP_NEWEST_FRAME_EXT 0x3463 + +Modify Section 3.7.1 of the EGL 1.4 Specification, paragraph 2 + (Creating Rendering Contexts) on pg. 43 + From: + If eglCreateContext succeeds, it initializes the context to the initial state defined + for the current rendering API, and returns a handle to it. The context can be + used to render to any compatible EGLSurface. + + To: + If eglCreateContext succeeds, it initializes the context to the initial state defined + for the current rendering API, and returns a handle to it. The context can be + used to render to any compatible off-screen rendering surface (Sections 3.5.2 + and 3.5.4). A secondary context can be used to render to compatible window surfaces + which have been associated with the context using eglCompositorSetWindowListEXT. A + non-secondary context can be used to render to any compatible EGLSurface. + +Modify Section 3.7.1 of EGL 1.4 Specification, paragraph 5 + (Creating Rendering Contexts) on pg. 43 + From: + attrib_list specifies a list of attributes for the context. The list has the same + structure as described for eglChooseConfig. The only attribute that can be specified + in attrib_list is EGL_CONTEXT_CLIENT_VERSION, and this attribute may only + be specified when creating a OpenGL ES context (e.g. when the current rendering + API is EGL_OPENGL_ES_API). + + To: + attrib_list specifies a list of attributes for the context. The list has the same + structure as described for eglChooseConfig. The attributes that can be specified + in attrib_list are EGL_CONTEXT_CLIENT_VERSION, EGL_PRIMARY_COMPOSITOR_CONTEXT_EXT, + EGL_EXTERNAL_REF_ID_EXT. + +Modify Section 3.7.1 of EGL 1.4 Specification, paragraph 7 + (Creating Rendering Contexts) on pg. 43 + From: + EGL_CONTEXT_CLIENT_VERSION determines which version of an OpenGL + ES context to create. An attribute value of 1 specifies creation of an OpenGL ES + 1.x context. An attribute value of 2 specifies creation of an OpenGL ES 2.x context. + The default value for EGL_CONTEXT_CLIENT_VERSION is 1. + + To: + EGL_CONTEXT_CLIENT_VERSION determines which version of an OpenGL + ES context to create. An attribute value of 1 specifies creation of an OpenGL ES + 1.x context. An attribute value of 2 specifies creation of an OpenGL ES 2.x context. + The default value for EGL_CONTEXT_CLIENT_VERSION is 1. EGL_CONTEXT_CLIENT_VERSION + may only be specified when creating a OpenGL ES context (e.g. when the current + rendering API is EGL_OPENGL_ES_API). + +Additions to Section 3.7.1 of the EGL 1.4 Specification (Creating Rendering Contexts). + + The first call to eglCreateContext with EGL_PRIMARY_COMPOSITOR_CONTEXT_EXT + set as EGL_TRUE in the <attrib-list> returns an EGLContext handle which will + act as the primary context for the specified EGLDisplay. This shall be the + only context on this EGLDisplay which is able to be bound to an on-screen window + on the EGLDisplay. Subsequent calls to eglCreateContext, for the same display, + in any address space with EGL_PRIMIARY_COMPOSITOR_CONTEXT_EXT set as EGL_TRUE + shall return EGL_NO_CONTEXT. + Subsequent calls, in any address space for the same display, to eglCreateContext + which do not use EGL_PRIMARY_COMPOSITOR_CONTEXT_EXT should use the the attribute + EGL_EXTERNAL_REF_ID_EXT and an external reference identifier to create a valid + EGLContext. + Subsequent calls, in any address space for the same display, to eglCreateContext + which do not use EGL_PRIMARY_COMPOSITOR_CONTEXT_EXT and do not use + EGL_EXTERNAL_REF_ID_EXT shall not create a context and shall return + EGL_NO_CONTEXT and set the error EGL_BAD_ACCESS. + + EGL_PRIMARY_COMPOSITOR_CONTEXT_EXT notifies EGL that this context is the only + context allowed to render to a on screen window surface for this display. This + attribute is followed in the attribute list by either EGL_TRUE or EGL_FALSE. + EGL_EXTERNAL_REF_ID_EXT is followed by an external reference identifier which + associates this context with the list of allowed contexts set by + eglCompositorSetContextListEXT. If the reference identifier has already been + used to initiate another call to eglCreateContext in any address space, this + call shall fail and set the error EGL_BAD_ATTRIBUTE. IF the external reference + identifier is not a valid identifier the error EGL_BAD_ATTRIBUTE shall be set + and the call shall fail. If this attribute is set and the primary context has + not yet been created then the error EGL_BAD_MATCH and the call shall fail. + + Only when the attributes specified via attrib_list and those specified for this + context using eglCompositorSetContextAttributesEXT are compatible will the + context be successfully created. + +Modify the list of parameters supported by eglCreateWindowSurface in section 3.5.1 + (Creating On-Screen Rendering Surfaces) on p. 27: + + An external window identifier (EGLuint external_win_id) is associated with + each off screen window. EGLNativeWindowType shall be EGLint and the + external window identifier shall be used as the value for the <win> parameter. + EGL_EXTERNAL_REF_ID_EXT with the context external reference id shall be in the + attrib_list. If the external window identifier and the external reference identifier + do not match a pair set using eglCompositorSetWindowListEXT window creation shall + fail. + +Add the function: + + EGLBoolean eglCompositorSetContextListEXT(const EGLint *external_ref_ids, + EGLint num_entries); + + This function is called by the primary context to establish the set of + all allowable secondary contexts by defining the set of external reference + identifiers. Secondary contexts shall identify their external reference + identifier by setting the EGL_EXTERNAL_REF_ID_EXT attribute when calling + eglCreateContext. + Calls to this function when the primary context for the display is not active, + shall return EGL_FALSE and do nothing. When this function is successful it + shall return EGL_TRUE and associate the list of external reference identifiers + with the active display. + This function shall only be called once per primary context. Subsequent calls + shall return EGL_FALSE and do nothing. + + external_ref_ids shall be an array of user generated integers greater than 1. + num_entries shall specify the number of external_ref_ids. + +Add the function: + + EGLBoolean eglCompositorSetContextAttributesEXT (EGLint external_ref_id, + const EGLint *context_attributes, + EGLint num_entries); + + This function is called by the primary context to establish a list of compatible + context attributes. + Calls to this function when the primary context for the display is not active + shall return EGL_FALSE and do nothing. When the function is successful it shall + return EGL_TRUE and associate the given attributes to the subsequent + eglCreateContext call using the given external reference id. + The list of acceptable context_attributes is the same as the list for + eglCreateContext. Only when this list of attributes is compatible with those + used during context creation will the secondary context be created. + This function shall only be called once per secondary context, and must be called + before the secondary context is able to be created. Subsequent calls shall + return EGL_FALSE and do nothing. + + num_entries shall specify the number of attributes in the list. This number + shall prevent accessing memory outside the attribute list, even if EGL_NONE is + not yet found in the list. If EGL_NONE is found sooner than this number of + attributes list parsing shall stop. + +Add the function: + + EGLBoolean eglCompositorSetWindowListEXT (EGLint external_ref_id, + const EGLint *external_win_ids, + EGLint num_entries); + + This function is called by the primary context to establish the set of + all allowable windows associated with a specific secondary context by defining + the set of external window identifiers. Window surface creation within secondary + contexts use the external window identifier as the native window handle parameter + of eglCreateWindowSurface and supply an external reference id as a window creation + attribute. + Calls to this function when the primary context for the display is not active, + shall return EGL_FALSE and do nothing. When this function is successful it + shall return EGL_TRUE and associate the list of external window identifiers + with the specified secondary context (external_ref_ids). + + external_win_ids shall be an array of user generated integers greater than 1. + external window identifiers are unique within the primary EGLContext. Any + external window identifier may be associated with multiple secondary contexts + however only the first context which calls eglCreateWindowSurface shall + successfully create a window surface for the given window. + num_entries shall specify the number of external_ref_ids. + +Add the function: + + EGLBoolean eglCompositorSetWindowAttributesEXT (EGLint external_win_id, + const EGLint *window_attributes, + EGLint num_entries); + + This function is called by the primary context to set window specific attributes + for the specified external window id. + + The list of valid attributes are: EGL_WIDTH, EGL_HEIGHT, EGL_VERTICAL_RESOLUTION, + EGL_HORIZONRAL_RESOLUTION, EGL_PIXEL_ASPECT_RATIO. + EGL_WIDTH and EGL_HEIGHT shall set the maximum width and height the secondary + context is able to create a window surface with. + EGL_VERTICAL_RESOLUTION, EGL_HORIZONTAL_RESOLUTION, and EGL_PIXEL_ASPECT_RATIO + shall set the values of these used by the secondary context. + Calls to this function when the primary context for the display is not active, + shall return EGL_FALSE and do nothing. When this function is successful it + shall return EGL_TRUE and associate the list of attributes with the off screen + window ID (external_win_id). + This function shall only be called once per window, and must be called before + the secondary context is able to create the window surface. Subsequent calls + shall return EGL_FALSE and do nothing. + + num_entries shall specify the number of attributes in the list. This number + shall prevent accessing memory outside the attribute list, even if EGL_NONE is + not yet found in the list. If EGL_NONE is found sooner than this number of + attributes list parsing shall stop. + +Add the function: + + EGLBoolean eglCompositorBindTexWindowEXT (EGLint external_win_id); + + This function is similar to eglBindTexImage in that it binds the windows + color buffers to a texture object which can then be composited on the native + window by the primary context. This function shall only be callable within + the primary context while there is a texture object actively bound by the + native rendering API. The function shall return EGL_TRUE if the window is + successfully bound to the active texture object. The function shall return + EGL_FALSE if binding fails, the context is not the primary context, or the + external_win_id is not a valid external window reference as set using + eglCompositorSetWindowListEXT. + +Add the function: + + EGLBoolean eglCompositorSetSizeEXT(EGLint external_win_id, + EGLint width, EGLint height); + + This function shall be called by the primary context to set the width and + height of the window. This function returns EGL_FALSE when called by a context + other than the primary context. This function will also return EGL_FALSE if + the new width and height are larger than the maximums set by + eglCompositorSetWindowAttributesEXT. Upon successful window resizing the function + shall return EGL_TRUE. + Secondary contexts may use EGL to query the windows width and height at runtime + to detect window resize events. The window buffer resizing shall be applied + to the newly active buffer after the secondary context calls eglSwapBuffers. + This will leave an average of 2 buffers which will have to be scaled by the + native rendering API to the new resolution. + +Add the function: + + EGLBoolean eglCompositorSwapPolicyEXT(EGLint external_win_id, + EGLint policy); + + This function shall be called by the primary context to specify the handling + of buffer swaps of the context specified by external_ref_id. + + When the policy is set to EGL_COMPOSITOR_DROP_NEWEST_FRAME_EXT, and the + secondary context completes a frame by calling eglSwapbuffers, and the + primary context is actively reading from the front buffer associated with + the external window ID, then the just completed frame is dropped, no buffer + swap occurs, and eglSwapBuffers will return EGL_TRUE. + If EGL_COMPOSITOR_KEEP_NEWEST_FRAME_EXT is specified and the primary context + is actively reading from the front buffer associated with the external window + ID then the secondary context's call to eglSwapBuffers will return EGL_FALSE. + eglSwapBuffers will continue to return EGL_FALSE as long as the primary context + is actively reading from the front buffer. Once the primary context finishes + reading from the front buffer the next call to eglSwapBuffers will + return EGL_TRUE. It is up to the application to decide if it will wait until + eglSwapBuffers returns EGL_TRUE before rendering again. If the secondary + context continues to render after eglSwapBuffers returns EGL_FALSE then it will + be as if the swap policy was EGL_COMPOSITOR_DROP_NEWEST_FRAME_EXT. + + +Revision History + Version 0.1, 30/08/2014 - first draft. + Version 0.2, 24/09/2014 second draft. + Version 0.3, 21/12/2016 + Khronos vendor extension clean-up. + Version 0.4, 05/01/2016 + - Change from context and display limitation to context and window limitations + - Added additional functions related to external window ids contexts. + Version 1.0, 03/02/2017 + - Fixed misc issues related to parameter names and types. + +Question: How are external reference and window IDs assigned and managed? Are they + reserved somehow within a new EGL C header file? +Answer: External IDs are assigned from the software component with the primary + context during an EGL initialization stage using eglCompositorSet*ListEXT. + The secondary contexts are provided the appropriate external reference ID + during end system integration. It is recommended that these values be able + to be set via a configuration parameter to the application, to ease + integration of multiple programs. + +Question: What happens when the secondary contexts render faster than the + primary context? +Answer: This is based on the swap policy set by the compositor, and the rate + difference between the render and the compositor. Secondary contexts + will be notified by EGL_FALSE being returned if the windows front buffer + is currently being read by the compositor. However, if the compositor is + not currently reading the front buffer the swap will succeed and the + secondary contexts latest rendered frame will now be in the front buffer + to be composited. + +Question: What happens when the primary context renders faster than the + secondary context(s)? +Answer: The contents of the windows front buffer will be repeated. + +Question: Does this infer any Z-ordering for the off-screen surfaces? +Answer: No, the Z-order is applied by the compositor when doing the final on + screen rendering of the off-screen surfaces. Or may be set if a Z-ordering + extension is applied to the attribute list of the window using + eglCompositorSetWindowAttributesEXT + +Comments: + +The driver should also have to have enough protection in it to prevent a random +software component from passing random buffer handles to the driver to prevent +access to other software components. + +The driver may force use of double buffering event if the window surface was created +using an EGL_RENDER_BUFFER attribute set to EGL_SINGLE_BUFFER. + +If EGL_PRIMARY_COMPOSITOR_CONTEXT_EXT is not used to create a context for a specified +display then EGL will act as though this extension is not enabled. diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_config_select_group.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_config_select_group.txt new file mode 100644 index 0000000..9721195 --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_config_select_group.txt @@ -0,0 +1,111 @@ +Name + + EGL_EXT_config_select_group + +Name Strings + + EGL_EXT_config_select_group + +Contributors + + Hal Gentz <zegentzy@protonmail.com> + Adam Jackson <ajax@redhat.com> + Robert Mader <robert.mader@posteo.de> + +Contacts + + Hal Gentz <zegentzy@protonmail.com> + +Status + + Draft + +Version + + Version 4, 2021-06-24 + +Number + + EGL Extension #145 + +Extension Type + + EGL client extension + +Dependencies + + This extension is written against the wording of the 2014.08.27 revision + of the EGL 1.5 Specification. + +Overview + + This extension provides a mechanism to lower the config selection priority + of the configs returned by eglChooseConfig. A new config attribute is + introduced, providing a way for the implementation to group configs into + different config selection categories. The config selection priorities of + all the configs in one category may be higher or lower than the ones in + other categories. The config selection priorities in one category follow + the rules of eglChooseConfig. See also GLX_SGIX_visual_select_group. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted as a new EGLConfig attribute: + + EGL_CONFIG_SELECT_GROUP_EXT 0x34C0 + +Additions to the EGL 1.5 Specification + + In section 3.4 "Configuration Management", under the "Buffer Descriptions + and Attributes" heading, append to table 3.1 the following: + + "EGL_CONFIG_SELECT_GROUP_EXT | integer | the config select group" + + In section 3.4 "Configuration Management", under the "Other EGLConfig + Attribute Descriptions" heading, append to the end the following: + + "The attribute EGL_CONFIG_SELECT_GROUP_EXT is used to specify the config + selection category of the config. Configs in the i-th category have a higher + config selection priority than those found in the (i+1)-th category. + + "The attribute EGL_CONFIG_SELECT_GROUP_EXT is used by the implementation to + override the default sorting rules, by collecting configurations into + groups. It is not accepted by the <attrib_list> parameter of + eglChooseConfig, but it is accepted as the <attribute> in + eglGetConfigAtrrib." + + In section 3.4 "Configuration Management", under the "Sorting of EGLConfigs" + heading, append to table 3.4 the following: + + "EGL_CONFIG_SELECT_GROUP_EXT | 0 | Ignore | Smaller | 0" + + In section 3.4 "Configuration Management", under the "Sorting of EGLConfigs" + heading, append before the list entry which starts with "1. Special: by + EGL_CONFIG_CAVEAT" the following entry: + + "0. Smaller EGL_CONFIG_SELECT_GROUP_EXT." + +Issues + + None + +Revision History + + Version 4, 2021-06-24 (Robert Mader) + - Moved to EXT, changed enum value to 0x34C0. + + Version 3, 2020-04-06 (Robert Mader) + - Changed enum value to 0x31DF, added contributors. + + Version 2, 2019-07-11 (Hal Gentz) + - Resolved issues pointed out by Adam Jackson. + + Version 1, 2019-06-21 (Hal Gentz) + - Initial draft diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_create_context_robustness.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_create_context_robustness.txt new file mode 100644 index 0000000..a78f878 --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_create_context_robustness.txt @@ -0,0 +1,169 @@ +Name + + EXT_create_context_robustness + +Name Strings + + EGL_EXT_create_context_robustness + +Contributors + + Daniel Koch, TransGaming + Contributors to EGL_KHR_create_context + +Contact + + Greg Roth (groth 'at' nvidia.com) + +Status + + Complete. + +Version + + Version 3, 2011/10/31 + +Number + + EGL Extension #37 + +Dependencies + + Requires EGL 1.4 + + Written against the EGL 1.4 specification. + + An OpenGL implementation supporting GL_ARB_robustness, an OpenGL ES + implementation supporting GL_EXT_robustness, or an implementation + supporting equivalent functionality is required. + +Overview + + This extension allows creating an OpenGL or OpenGL ES context + supporting robust buffer access behavior and a specified graphics + reset notification behavior. + +New Procedures and Functions + + None + +New Tokens + + Accepted as an attribute name in the <*attrib_list> argument to + eglCreateContext: + + EGL_CONTEXT_OPENGL_ROBUST_ACCESS_EXT 0x30BF + EGL_CONTEXT_OPENGL_RESET_NOTIFICATION_STRATEGY_EXT 0x3138 + + Accepted as an attribute value for EGL_CONTEXT_RESET_NOTIFICATION_- + STRATEGY_EXT in the <*attrib_list> argument to eglCreateContext: + + EGL_NO_RESET_NOTIFICATION_EXT 0x31BE + EGL_LOSE_CONTEXT_ON_RESET_EXT 0x31BF + +Additions to the EGL 1.4 Specification + + Replace section 3.7.1 "Creating Rendering Contexts" from the + fifth paragraph through the seventh paragraph: + + <attrib_list> specifies a list of attributes for the context. The + list has the same structure as described for eglChooseConfig. If an + attribute is not specified in <attrib_list>, then the default value + specified below is used instead. <attrib_list> may be NULL or empty + (first attribute is EGL_NONE), in which case attributes assume their + default values as described below. Most attributes are only meaningful + for specific client APIs, and will generate an EGL_BAD_ATTRIBUTE + error when specified to create for another client API context. + + Context Versions + ---------------- + + EGL_CONTEXT_CLIENT_VERSION determines which version of an OpenGL ES + context to create. This attribute may only be specified when creating + an OpenGL ES context (e.g. when the current rendering API is + EGL_OPENGL_ES_API). An attribute value of 1 specifies creation of an + OpenGL ES 1.x context. An attribute value of 2 specifies creation of an + Open GL ES 2.x context. The default value for EGL_CONTEXT_CLIENT_VERSION + is 1. + + Context Robust Access + ------------- + + EGL_CONTEXT_OPENGL_ROBUST_ACCESS_EXT indicates whether <robust buffer + access> should be enabled for the OpenGL ES context. Robust buffer + access is defined in the GL_EXT_robustness extension specification, + and the resulting context must support GL_EXT_robustness and robust + buffer access as described therein. The default value of + EGL_CONTEXT_OPENGL_ROBUST_ACCESS_EXT is EGL_FALSE. + + Context Reset Notification + -------------------------- + + The attribute name EGL_CONTEXT_OPENGL_RESET_NOTIFICATION_STRATEGY_- + EXT specifies the <reset notification behavior> of the rendering + context. This attribute is only meaningful for OpenGL ES contexts, + and specifying it for other types of contexts will generate an + EGL_BAD_ATTRIBUTE error. + + Reset notification behavior is defined in the GL_EXT_robustness + extension for OpenGL ES, and the resulting context must support + GL_EXT_robustness and the specified reset strategy. The attribute + value may be either EGL_NO_RESET_NOTIFICATION_EXT or EGL_LOSE_- + CONTEXT_ON_RESET_EXT, which respectively result in disabling + delivery of reset notifications or the loss of all context state + upon reset notification as described by the GL_EXT_robustness. The + default value for EGL_CONTEXT_OPENGL_RESET_NOTIFICATION_STRATEGY_EXT + is EGL_NO_RESET_NOTIFICATION_EXT. + + Add to the eglCreateContext context creation errors: + + * If <config> does not support a client API context compatible + with the requested context flags and context reset notification + behavior (for client API types where these attributes are + supported), then an EGL_BAD_CONFIG error is generated. + + * If the reset notification behavior of <share_context> and the + newly created context are different then an EGL_BAD_MATCH error is + generated. + + +Errors + + EGL_BAD_CONFIG is generated if EGL_CONTEXT_OPENGL_ROBUST_ACCESS_- + EXT is set to EGL_TRUE and no GL context supporting the GL_EXT_- + robustness extension and robust access as described therein can be + created. + + EGL_BAD_CONFIG is generated if no GL context supporting the + GL_EXT_robustness extension and the specified reset notification + behavior (the value of attribute EGL_CONTEXT_RESET_NOTIFICATION_- + STRATEGY_EXT) can be created. + + BAD_MATCH is generated if the reset notification behavior of + <share_context> does not match the reset notification behavior of + the context being created. + +New State + + None + +Conformance Tests + + TBD + +Sample Code + + TBD + +Issues + + None + +Revision History + + Rev. Date Author Changes + ---- ------------ --------- ---------------------------------------- + 3 31 Oct 2011 groth Reverted to attribute for robust access. Now it's a + companion to rather than subset of KHR_create_context + 2 11 Oct 2011 groth Merged ANGLE and NV extensions. + 1 15 July 2011 groth Initial version diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_base.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_base.txt new file mode 100644 index 0000000..aece774 --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_base.txt @@ -0,0 +1,243 @@ +Name + + EXT_device_base + +Name Strings + + EGL_EXT_device_base + +Contributors + + James Jones + Daniel Kartch + Jamie Madill + +Contacts + + James Jones, NVIDIA (jajones 'at' nvidia.com) + +Status + + Complete + + Rewritten in terms of split functionality in EXT_dispay_device and + EXT_device_enumeration. + +Version + + Version 9 - March 24th, 2015 + +Number + + EGL Extension #72 + +Extension Type + + EGL client extension + +Dependencies + + Written against the wording of EGL 1.5. + + The specifications of EGL_EXT_device_query and + EGL_EXT_device_enumeration are required to determine the + specification of this extension, although those extensions may not + be supported. + +Overview + + Increasingly, EGL and its client APIs are being used in place of + "native" rendering APIs to implement the basic graphics + functionality of native windowing systems. This creates demand + for a method to initialize EGL displays and surfaces directly on + top of native GPU or device objects rather than native window + system objects. The mechanics of enumerating the underlying + native devices and constructing EGL displays and surfaces from + them have been solved in various platform and implementation- + specific ways. The EGL device family of extensions offers a + standardized framework for bootstrapping EGL without the use of + any underlying "native" APIs or functionality. + + This extension defines the first step of this bootstrapping + process: Device enumeration. + +New Types + + As defined by EGL_EXT_device_query. + +New Functions + + As defined by EGL_EXT_device_query and EGL_EXT_device_enumeration. + +New Tokens + + As defined by EGL_EXT_device_query. + +Add to section "3.2 Devices" + + "EGL_EXT_device_base is equivalent to the combination of the + functionality defined by EGL_EXT_device_query and + EGL_EXT_device_enumeration." + +Issues + + 1. Should there be a mechanism (such as an attribute list) to + filter devices in eglQueryDevicesEXT()? + + RESOLVED: No. This could develop too much complexity, like + the EGLConfig mechanism. Instead, force applications to query + all devices and implement any desired filtering themselves. + + 2. Should there be an eglSetDeviceAttribEXT()? + + RESOLVED: No. Device properties are immutable. + + 3. Should a device file descriptor attribute be included in the + base specification? + + RESOLVED: No. It seems like an arbitrary attribute to include + in the base extension. Other extensions can easily be added + if this or other device attributes are needed. + + 4. Should EGLDeviceEXT handles be opaque pointers or 32-bit + values? + + RESOLVED: Opaque pointers. The trend seems to be to use + opaque pointers for object handles, and opaque pointers allow + more implementation flexibility than 32-bit values. + Additionally, the introduction of the EGLAttrib type allows + inclusion of pointer-sized types in attribute lists, which was + the only major advantage of 32-bit types. + + 5. Should eglQueryDisplayAttribEXT be defined as part of this + extension? + + RESOLVED: Yes. There are no other known uses for this + function, so it should be defined here. If other uses are + found, future extension specifications can reference this + extension or retroactively move it to a separate extension. + + 6. How should bonded GPU configurations, such as SLI or Crossfire + be enumerated? What about other hybrid rendering solutions? + + RESOLVED: Bonded GPUs should appear as one device in this API, + since the client APIs generally treat them as one device. + Further queries can be added to distinguish the lower-level + hardware within these bonded devices. + + Hybrid GPUs, which behave independently but are switched + between in a manner transparent to the user, should be + enumerated separately. This extension is intended to be used + at a level of the software stack below this type of automatic + switching or output sharing. + + 7. Should this extension require all displays to have an + associated, queryable device handle? + + RESOLVED: Yes. This allows creating new namespace containers + that all displays can be grouped in to and allows existing + applications with display-based initialization code to easily + add device-level functionality. Future extensions are + expected to expose methods to correlate EGL devices and native + devices, and to use devices as namespaces for future objects + and operations, such as cross-display EGL streams. + + 8. Are device handles returned by EGL valid in other processes? + + RESOLVED: No. Another level of indirection is required to + correlate two EGL devices in separate processes. + + 9. Is a general display pointer query mechanism needed, or should + an eglGetDevice call be added to query a display's associated + device? + + RESOLVED: A general mechanism is better. It may have other + uses in the future. + + 10. Should a new type of extension be introduced to query device- + specific extensions? + + RESOLVED: Yes. Without this mechanism, it is likely that most + device extensions would require a separate mechanism to + determine which devices actually support them. Further, + requiring all device-level extensions to be listed as client + extensions forces them to be implemented in the EGL client + library, or "ICD". This is unfortunate since vendors will + likely wish to expose vendor-specific device extensions. + + These advantages were weighed against the one known + disadvantage of a separate extension type: Increasing the + complexity of this extension and the EGL extension mechanism + in general. + + 11. Is eglQueryDeviceStringEXT necessary, or should the device + extension string be queried using eglQueryDeviceAttribEXT? + + RESOLVED: Using a separate query seems more consistent with + how the current extension strings are queried. + + 12. Should this extension contain both device enumeration and + the ability to query the device backing an EGLDisplay? + + RESOLVED: This extension initially included both of these + abilities. To allow simpler implementations to add only the + ability to query the device of an existing EGLDisplay, this + extension was split into two separate extensions: + + EGL_EXT_device_query + EGL_EXT_device_enumeration + + The presence of this extension now only indicates support + for both of the above extensions. + +Revision History: + + #9 (March 24th, 2015) James Jones + - Split the extension into two child extensions: + EGL_EXT_device_query + EGL_EXT_device_enumeration + + #8 (May 16th, 2014) James Jones + - Marked the extension complete. + - Marked all issues resolved. + + #7 (April 8th, 2014) James Jones + - Renamed eglGetDisplayAttribEXT back to + eglQueryDisplayAttribEXT. + - Update wording based on the EGL 1.5 specification. + - Use EGLAttrib instead of EGLAttribEXT. + - Assigned values to tokens. + + #6 (November 6th, 2013) James Jones + - Added EGL_BAD_DEVICE_EXT error code. + - Renamed some functions for consistency with the core spec + + #5 (November 6th, 2013) James Jones + - Specified this is a client extension + - Renamed eglQueryDisplayPointerEXT eglGetDisplayAttribEXT + and modified it to use the new EGLAttribEXT type rather than + a void pointer + - Introduced the "device" extension type. + - Added eglQueryDeviceStringEXT to query device extension + strings + - Removed issues 5, 10, and 12 as they are no longer relevant + - Added issues 10 and 11. + + #4 (May 14th, 2013) James Jones + - Merged in EGL_EXT_display_attributes + - Changed eglGetDisplayPointerEXT to eglQueryDisplayPointerEXT + - Remove eglGetDisplayAttribEXT since it has no known use case + + #3 (April 23rd, 2013) James Jones + - Include EGL_NO_DEVICE_EXT + - Added issues 8 and 9 + + #2 (April 18th, 2013) James Jones + - Reworded issue 3 and flipped the resolution + - Added issues 5, 6, and 7 + - Filled in the actual spec language modifications + - Renamed from EGL_EXT_device to EGL_EXT_device_base + - Fixed some typos + + #1 (April 16th, 2013) James Jones + - Initial Draft diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_drm.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_drm.txt new file mode 100644 index 0000000..fa125fc --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_drm.txt @@ -0,0 +1,223 @@ +Name + + EXT_device_drm + EXT_output_drm + +Name Strings + + EGL_EXT_device_drm + EGL_EXT_output_drm + +Contributors + + Daniel Kartch + James Jones + Christopher James Halse Rogers + +Contacts + + Daniel Kartch, NVIDIA (dkartch 'at' nvidia.com) + +Status + + Complete + +Version + + Version 5 - December 28th, 2015 + +Number + + EGL Extension #79 + +Extension Type + + EGL device extension for EGL_EXT_device_drm + + EGL display extension for EGL_EXT_output_drm + +Dependencies + + EGL_EXT_device_drm requires EGL_EXT_device_base. + + EGL_EXT_device_drm interacts with EGL_EXT_platform_device + + EGL_EXT_device_drm requires a DRM driver. + + EGL_EXT_output_drm requires EGL_EXT_output_base. + + EGL_EXT_output_drm requires a DRM driver which supports KMS. + + An EGLDisplay supporting EGL_EXT_output_drm must be associated + with an EGLDevice supporting EGL_EXT_device_drm. + +Overview + + Increasingly, EGL and its client APIs are being used in place of + "native" rendering APIs to implement the basic graphics + functionality of native windowing systems. This creates demand + for a method to initialize EGL displays and surfaces directly on + top of native GPU or device objects rather than native window + system objects. The mechanics of enumerating the underlying + native devices and constructing EGL displays and surfaces from + them have been solved in various platform and implementation- + specific ways. The EGL device family of extensions offers a + standardized framework for bootstrapping EGL without the use of + any underlying "native" APIs or functionality. + + These extensions define how to map device and output handles between + EGL and DRM/KMS. An EGL implementation which provides these + extensions must have access to sufficient knowledge of the DRM + implementation to be able to perform these mappings. No requirements + are imposed on how this information is obtained, nor does this + support have any implications for how EGL devices and outputs are + implemented. Among the possibilities, support may be implemented in + a generic fashion by layering on top of DRM, or EGL and DRM backends + may be provided by the same vendor and share privileged lower level + resources. An implementation which supports these extensions may + support other low level device interfaces, such as OpenWF Display, + as well. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Added by EXT_device_drm: + + Accepted as the <name> parameter of eglQueryDeviceStringEXT + + EGL_DRM_DEVICE_FILE_EXT 0x3233 + + If EGL_EXT_platform_device is present, the following is accepted + in the <attrib_list> of eglGetPlatformDisplayEXT(). + + EGL_DRM_MASTER_FD_EXT 0x333C + + Added by EXT_output_drm: + + Accepted in the <attrib_list> of eglGetOutputLayersEXT and as + the <attribute> parameter of eglQueryOutputLayerAttribEXT + + EGL_DRM_CRTC_EXT 0x3234 + EGL_DRM_PLANE_EXT 0x3235 + + Accepted in the <attrib_list> of eglGetOutputPortsEXT and as + the <attribute> parameter of eglQueryOutputPortAttribEXT + + EGL_DRM_CONNECTOR_EXT 0x3236 + +New Behavior for EXT_device_drm + + EGLDeviceEXTs may be mapped to DRM device files. + + To obtain a DRM device file for an EGLDeviceEXT, call + eglQueryDeviceStringEXT with <name> set to EGL_DRM_DEVICE_FILE_EXT. + The function will return a pointer to a string containing the name + of the device file (e.g. "/dev/dri/cardN"). + +If EGL_EXT_platform_device is present, replace the last sentence of the +third paragraph in section 3.2 "Initialization" with the following: + + When <platform> is EGL_PLATFORM_DEVICE_EXT, the only valid attribute + name is EGL_DRM_MASTER_FD_EXT. If specified, the value must be a file + descriptor with DRM master permissions on the DRM device associated + with the specified EGLDevice, as determined by EGL_DRM_DEVICE_FILE_EXT. + If the file descriptor does not refer to the correct DRM device or + does not have master permissions, the behavior is undefined. Calls to + eglGetPlatformDeviceEXT() with the same values for <platform> and + <native_display> but distinct EGL_DRM_MASTER_FD_EXT values will return + separate EGLDisplays. + + If EGL requires the use of the DRM file descriptor beyond the duration + of the call to eglGetPlatformDispay(), it will duplicate it. If no + file descriptor is specified and EGL requires one, it will attempt to + open the device itself. Applications should only need to specify a + file descriptor in situations where EGL may fail to open a file + descriptor itself, generally due to lack of permissions, or when EGL + will fail to acquire DRM master permissions due to conflicts with an + existing DRM client. DRM master permissions are only required when EGL + must modify output attributes. This extension does not define any + situations in which output attributes will be modified. + +New Behavior for EXT_output_drm + + KMS CRTC, plane, and connector IDs may be used to restrict EGL + output handle searches and may be queried from EGL output handles. + + Add to Table 3.10.3.1 in EGL_EXT_output_base: + + Attribute Type Access + --------------------- ------- ------ + EGL_DRM_CRTC_EXT integer S|R + EGL_DRM_PLANE_EXT integer S|R + + Add to Table 3.10.3.2 in EGL_EXT_output_base: + + Attribute Type Access + --------------------- ------- ------ + EGL_DRM_CONNECTOR_EXT integer S|R + + Add to description of eglOutputLayerAttribEXT: + + If <layer> corresponds to a KMS CRTC and <attribute> is + EGL_DRM_PLANE_EXT, or if <layer> corresponds to a KMS plane and + <attribute> is EGL_DRM_CRTC_EXT, an EGL_BAD_MATCH error is + generated. + +Issues + + 1) Should different values of EGL_DRM_MASTER_FD_EXT result in separate + EGLDisplays? + + RESOLVED: Yes. Consider an application made up of two independent + modules running in two independently scheduled threads. Each + module calls eglGetPlatformDisplayEXT(): + + int fd = open("/dev/dri/card0", O_RDWR); + int attr1[] = { EGL_DRM_MASTER_FD_EXT, fd }; + dpy1 = eglGetPlatformDisplayEXT(EGL_PLATFORM_DEVICE_EXT, + eglDev, + attr1); + + ... + + dpy2 = eglGetPlatformDisplayEXT(EGL_PLATFORM_DEVICE_EXT, + eglDev, + NULL); + + Presumably, if dpy1 == dpy2, they would both be using the same DRM + fd for output operations internally. That would mean display + attribute updates would likely fail if dpy2 happened to be created + before dpy1. This would be painful to debug. If dpy2 != dpy1, + failure for dpy2 would be consistent and obvious. The application + author would be required to work out a scheme to share the master + FD between modules before creating EGL displays. + +Revision History: + + #5 (December 28th, 2015) James Jones + - Added EGL_DRM_MASTER_FD_EXT and associated + language. + - Added issue 1. + + #4 (August 22nd, 2014) James Jones + - Marked complete. + - Listed Daniel as the contact. + + #3 (June 5th, 2014) Daniel Kartch + - Assigned enumerated values for constants. + + #2 (May 28th, 2014) Daniel Kartch + - Simplified description of new behavior based on refinements + to EGL_EXT_output_base. + + #1 (January 31st, 2014) Daniel Kartch + - Initial draft, representing a signficant reworking of + functionality previously proposed in + EGL_EXT_native_device_drm. diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_drm_render_node.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_drm_render_node.txt new file mode 100644 index 0000000..4c08844 --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_drm_render_node.txt @@ -0,0 +1,106 @@ +Name + + EXT_device_drm_render_node + +Name Strings + + EXT_device_drm_render_node + +Contributors + + James Jones + Simon Ser + Daniel Stone + +Contacts + + James Jones, NVIDIA (jajones 'at' nvidia.com) + +Status + + Draft + +Version + + Version 1 - June 4th, 2021 + +Number + + EGL Extension #144 + +Extension Type + + EGL device extension + +Dependencies + + Written based on the wording of the EGL 1.5 specification. + + EGL_EXT_device_query is required. + + EGL_EXT_device_drm interacts with this extension. + +Overview + + The EGL_EXT_device_drm extension provided a method for applications + to query the DRM device node file associated with a given + EGLDeviceEXT object. However, it was not clear whether it referred to + the primary or render device node. This extension adds an enum to + refer explicitly to the render device node and defines the existing + EGL_DRM_DEVICE_FILE_EXT as explicitly refering to the primary device + node. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted as the <name> parameter of eglQueryDeviceStringEXT + + EGL_DRM_RENDER_NODE_FILE_EXT 0x3377 + +Changes to section 3.2 (Devices) + + Add the following paragraph to the description of + eglQueryDeviceStringEXT: + + "To obtain a DRM device file for the render node associated with an + EGLDeviceEXT, call eglQueryDeviceStringEXT with <name> set to + EGL_DRM_RENDER_NODE_FILE_EXT. The function will return a pointer to + a string containing the name of the device file (e.g. + "/dev/dri/renderDN"), or NULL if the device has no associated DRM + render node." + + If EGL_EXT_device_drm is present, append the following to the + paragraph in the same section describing EGL_DRM_DEVICE_FILE_EXT: + + "If the EGL_EXT_device_drm_render_node extension is supported, the + value returned will refer to a primary device node, and will be NULL + if the device has no associated DRM primary node. If + EGL_EXT_device_drm_render_node is not supported, the value returned + will refer to a primary device node if there exists one associated + with the device. Otherwise, it will refer to a render device node if + there exists one associated with the device. If neither exists, NULL + is returned." + +Issues + + 1) Should this extension clarify that EGL_DRM_DEVICE_FILE_EXT refers + only to primary device nodes? + + RESOLVED: Yes, but only when this extension is supported. Existing + implementations return render node paths for that string when no + suitable primary node is available. + +Revision History: + + #2 (June 8th, 2021) James Jones + - Added issue #1 and related spec changes. + + #1 (June 4th, 2021) James Jones + - Initial draft. diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_enumeration.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_enumeration.txt new file mode 100644 index 0000000..c7920eb --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_enumeration.txt @@ -0,0 +1,111 @@ +Name + + EXT_device_enumeration + +Name Strings + + EGL_EXT_device_enumeration + +Contributors + + James Jones + Jamie Madill + +Contacts + + James Jones, NVIDIA (jajones 'at' nvidia.com) + +Status + + Complete. + +Version + + Version 1 - March 24th, 2015 + +Number + + EGL Extension #88 + +Extension Type + + EGL client extension + +Dependencies + + Written against the wording of EGL 1.5. + + Requires EGL 1.5 or an earlier verison of EGL with the + EGL_EXT_client_extensions extension. + + Requires the EGL_EXT_device_query extension. + +Overview + + Increasingly, EGL and its client APIs are being used in place of + "native" rendering APIs to implement the basic graphics + functionality of native windowing systems. This creates demand + for a method to initialize EGL displays and surfaces directly on + top of native GPU or device objects rather than native window + system objects. The mechanics of enumerating the underlying + native devices and constructing EGL displays and surfaces from + them have been solved in various platform and implementation- + specific ways. The EGL device family of extensions offers a + standardized framework for bootstrapping EGL without the use of + any underlying "native" APIs or functionality. + + The original EGL_EXT_device_base extension combined the conceptually + separate operations of querying the underlying device used by a + given EGLDisplay and enumerating devices from scratch. It was later + identified that the former is useful even in EGL implementations + that have no need or ability to allow enumerating all the devices + available on a system. To accommodate this, the extension was + split in two. + +New Types + + None + +New Functions + + EGLBoolean eglQueryDevicesEXT(EGLint max_devices, + EGLDeviceEXT *devices, + EGLint *num_devices); + +Add the following at the beginning of section "3.2 Devices" + + "EGL devices can be enumerated before EGL is initialized. Use: + + EGLBoolean eglQueryDevicesEXT(EGLint max_devices, + EGLDeviceEXT *devices, + EGLint *num_devices); + + "to obtain a list of all supported devices in the system. On + success, EGL_TRUE is returned, and <num_devices> devices are + stored in the array pointed to by <devices>. <num_devices> will + be less than or equal to <max_devices>. If <devices> is NULL, + then <max_devices> will be ignored, no devices will be returned in + <devices>, and <num_devices> will be set to the number of + supported devices in the system. All implementations must support + at least one device. + + "On failure, EGL_FALSE is returned. An EGL_BAD_PARAMETER error is + generated if <max_devices> is less than or equal to zero unless + <devices> is NULL, or if <num_devices> is NULL." + +Remove the following paragraph from section "3.4 Display Attributes" + + "Because the EGLDeviceEXT is a property of <dpy>, any use of an + associated EGLDeviceEXT after <dpy> has been terminated gives + undefined results. Querying an EGL_DEVICE_EXT from <dpy> after a + call to eglTerminate() (and subsequent re-initialization) may + return a different value." + +Issues + + None + +Revision History: + + #1 (March 24th, 2015) James Jones + - Initial branch from EGL_EXT_device_base version #8 diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_openwf.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_openwf.txt new file mode 100644 index 0000000..2fb4d3b --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_openwf.txt @@ -0,0 +1,230 @@ +Name + + EXT_device_openwf + EXT_output_openwf + +Name Strings + + EGL_EXT_device_openwf + EGL_EXT_output_openwf + +Contributors + + Daniel Kartch + James Jones + Christopher James Halse Rogers + +Contacts + + Daniel Kartch, NVIDIA (dkartch 'at' nvidia.com) + +Status + + Complete + +Version + + Version 5 - January 21, 2016 + +Number + + EGL Extension #80 + +Extension Type + + EGL device extension for EGL_EXT_device_openwf + + EGL display extension for EGL_EXT_output_openwf + +Dependencies + + EGL_EXT_device_openwf requires EGL_EXT_device_base. + + EGL_EXT_output_openwf requires EGL_EXT_output_base. + + Both require OpenWF Display + + EGL_EXT_device_openwf interacts with EGL_EXT_platform_device + + An EGLDisplay supporting EGL_EXT_output_openwf must be associated + with an EGLDevice supporting EGL_EXT_device_openwf. + +Overview + + Increasingly, EGL and its client APIs are being used in place of + "native" rendering APIs to implement the basic graphics + functionality of native windowing systems. This creates demand + for a method to initialize EGL displays and surfaces directly on + top of native GPU or device objects rather than native window + system objects. The mechanics of enumerating the underlying + native devices and constructing EGL displays and surfaces from + them have been solved in various platform and implementation- + specific ways. The EGL device family of extensions offers a + standardized framework for bootstrapping EGL without the use of + any underlying "native" APIs or functionality. + + These extensions define how to map device and output handles between + EGL and OpenWF Display. An EGL implementation which provides these + extensions must have access to sufficient knowledge of the OpenWF + implementation to be able to perform these mappings. No requirements + are imposed on how this information is obtained, nor does this + support have any implications for how EGL devices and outputs are + implemented. An implementation which supports these extensions may + support other low level device interfaces, such as DRM/KMS, as well. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Added by EXT_device_openwf: + + Accepted as the <attribute> parameter of eglQueryDeviceAttribEXT + + EGL_OPENWF_DEVICE_ID_EXT 0x3237 + + If EGL_EXT_platform_device is present, the following is accepted + in the <attrib_list> of eglGetPlatformDisplayEXT(). + + EGL_OPENWF_DEVICE_EXT 0x333D + + Added by EXT_output_openwf: + + Accepted in the <attrib_list> of eglGetOutputLayersEXT and as + the <attribute> parameter of eglQueryOutputLayerAttribEXT + + EGL_OPENWF_PIPELINE_ID_EXT 0x3238 + + Accepted in the <attrib_list> of eglGetOutputPortsEXT and as + the <attribute> parameter of eglQueryOutputPortAttribEXT + + EGL_OPENWF_PORT_ID_EXT 0x3239 + +New Behavior for EXT_device_openwf + + EGLDeviceEXTs may be mapped to OpenWF Display devices. + + To obtain a WFD_DEVICE_ID for an EGLDeviceEXT, call + eglQueryDeviceAtribEXT with <attribute> set to + EGL_OPENWF_DEVICE_ID_EXT. + +If EGL_EXT_platform_device is present, replace the last sentence of the +third paragraph in section 3.2 "Initialization" with the following: + + When <platform> is EGL_PLATFORM_DEVICE_EXT, the only valid attribute + name is EGL_OPENWF_DEVICE_EXT. If specified, the value must be a + WFDDevice created with the device ID returned by querying + EGL_OPENWF_DEVICE_ID_EXT from the specified EGLDevice. If the device + handle does not refer to the correct OpenWF device the behavior is + undefined. Calls to eglGetPlatformDeviceEXT() with the same values + for <platform> and <native_display> but distinct EGL_OPENWF_DEVICE_EXT + values will return separate EGLDisplays. + + EGL may require the use of the OpenWF device beyond the duration of + the call to eglGetPlatformDisplayEXT(). The application must ensure + the device handle remains valid for the lifetime of the display + returned. If no OpenWF device handle is specified and EGL requires + one, it will attempt to create the device itself. Applications + should only need to specify an OpenWF device in situations where EGL + may fail to create one itself due to an existing instance of the same + underlying device in the process. + +New Behavior for EXT_output_openwf + + OpenWF pipeline and port IDs may be used to restrict EGL output + handle searches and may be queried from EGL output handles. + + Add to Table 3.10.3.1 in EGL_EXT_output_base: + + Attribute Type Access + -------------------------- ------- ------ + EGL_OPENWF_PIPELINE_ID_EXT integer S|R + + Add to Table 3.10.3.2 in EGL_EXT_output_base: + + Attribute Type Access + -------------------------- ------- ------ + EGL_OPENWF_PORT_ID_EXT integer S|R + +Issues + + 1. Although the overview says that we do not impose any + restrictions on how the features are implemented, restrictions + in the OpenWF specification combined with the chosen interface + here do implicitly impose limitations. Specifically, the + wfdCreate* functions can only be called once to obtain OpenWF + handles. This means that an EGLDevice/Output implementation + cannot be layered on top of OpenWF without preventing the + application from calling these functions. So we must assume that + the implementation instead has some backdoor into OpenWF to + obtain the object IDs. Possible resolutions include: + a) Keep the access model as is. This assumption is a reasonable + one. + b) Flip the requirement. The EGL device/output implementation + should always create the OpenWF handles itself. We can add + queries so that the application can get these handles from + EGL. + c) Generalize this extension to support both models. The + application would have to first query EGL to determine + whether or not it owns the handles, and then be prepared to + either query them from EGL or create them itself. + d) Require the application to provide its OpenWF device handle + if it has one. + + RESOLVED: (d), though implementations are free to use (a) when + possible. + + 2. Should different values of EGL_OPENWF_DEVICE_EXT result in separate + EGLDisplays? + + RESOLVED: Yes. Consider an application made up of two independent + modules running in two independently scheduled threads. Each + module calls eglGetPlatformDisplayEXT(): + + WFDDevice wfdDev = wfdCreateDevice(WFD_DEFAULT_DEVICE_ID, NULL); + int attr1[] = { EGL_OPENWF_DEVICE_EXT, wfdDev }; + dpy1 = eglGetPlatformDisplayEXT(EGL_PLATFORM_DEVICE_EXT, + eglDev, + attr1); + + ... + + dpy2 = eglGetPlatformDisplayEXT(EGL_PLATFORM_DEVICE_EXT, + eglDev, + NULL); + + Presumably, if dpy1 == dpy2, they would both be using the same + WFDDevice for output operations internally. That would mean + output operations would likely fail if dpy2 happened to be created + before dpy1. This would be painful to debug. If dpy2 != dpy1, + failure for dpy2 would be consistent and obvious. The application + author would be required to work out a scheme to share the WFDDevice + between modules before creating EGL displays. + +Revision History: + + #5 (January 21st, 2016) James Jones + - Add EGL_OPENWF_DEVICE_EXT to resolve issue 1. + - Added possible solution (d) to issue 1, and resolve to use it. + - Added issue 2. + + #4 (August 22nd, 2014) James Jones + - Marked complete. + - Listed Daniel as the contact. + + #3 (June 5th, 2014) Daniel Kartch + - Assign enumerated values for constants. + + #2 (May 28th, 2014) Daniel Kartch + - Simplified description of new behavior based on refinements + to EGL_EXT_output_base. + + #1 (January 31st, 2014) Daniel Kartch + - Initial draft, representing a signficant reworking of + functionality previously proposed in + EGL_EXT_native_device_openwf. diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_persistent_id.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_persistent_id.txt new file mode 100644 index 0000000..081a6d1 --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_persistent_id.txt @@ -0,0 +1,202 @@ +Name + + EXT_device_persistent_id + +Name Strings + + EGL_EXT_device_persistent_id + +Contributors + + Kyle Brenneman, NVIDIA (kbrenneman 'at' nvidia.com) + +Contact + + Kyle Brenneman, NVIDIA (kbrenneman 'at' nvidia.com) + +Version + + Version 1 - April 19, 2021 + +Number + + EGL Extension #142 + +Extension Type + + EGL device extension + +Dependencies + + Written based on the wording of the EGL 1.5 specification. + + EGL_EXT_device_query is required. + +Overview + + Applications can query a list of EGLDeviceEXT handles, but those + handles are only valid within the process that queried them. An + application has no way, for example, to record its selection and + select the same device when run again later. + + This extension provides a vendor name and a set of UUID's, which + provide a unique, persistent identifier for EGLDeviceEXT handles. + This allows applications to find the EGLDeviceEXT for the same + device across multiple processes, and across multiple APIs. + +New Procedures and Functions + + EGLBoolean eglQueryDeviceBinaryEXT(EGLDeviceEXT device, + EGLint name, + EGLint max_size, + void *value, + EGLint *size); + +New Tokens + + Accepted by the <name> parameter of eglQueryDeviceStringEXT: + + EGL_DRIVER_NAME_EXT 0x335E + + Accepted by the <name> parameter of eglQueryDeviceBinaryEXT: + + EGL_DEVICE_UUID_EXT 0x335C + EGL_DRIVER_UUID_EXT 0x335D + +Changes to section 3.2 (Devices) + + Add the following paragraph to the description of + eglQueryDeviceStringEXT: + + EGL_DRIVER_NAME_EXT returns a string which identifies the driver + that controls the device. This string remains persistent across + multiple versions of a driver, and an application can use strcmp(3) + to compare the strings for equality. Otherwise, the contents are + implementation-defined. + + + Add to the end of section 3.2: + + To query a binary attribute for a device, use: + + EGLBoolean eglQueryDeviceBinaryEXT(EGLDeviceEXT device, + EGLint name, + EGLint max_size, + void *value, + EGLint *size); + + On success, EGL_TRUE is returned. If <value> is NULL, then + <max_size> is ignored, and the size of the attribute in bytes is + returned in <size>. + + On failure, EGL_FALSE is returned. An EGL_BAD_ATTRIBUTE error is + generated if <name> is not a valid attribute. An EGL_BAD_DEVICE_EXT + error is generated if <device> is not a valid EGLDeviceEXT. + + If <value> is not NULL, then the attribute value is returned in + <value>. At most <max_size> bytes are written. <size> returns the + number of bytes that were actually written. + + Note that the EGL_DEVICE_UUID_EXT and EGL_DRIVER_UUID_EXT attributes + are always 16-byte values, and so the application can simply use a + 16-byte buffer without needing to query the size beforehand. Future + extensions may add variable-length attributes. + + + EGL_DEVICE_UUID_EXT is a UUID that identifies a physical device, + returned as a 16-byte binary value. The device UUID uniquely + identifies a physical device, and is persistent across reboots, + processes, APIs, and (to the extent possible) driver versions. + + EGL_DEVICE_UUID_EXT may or may not be persistent across changes in + hardware configuration. Similarly, it is not guaranteed to be unique + or persistent across different (physical or virtual) computers. + + Note that EGL_DEVICE_UUID_EXT alone is not guaranteed to be unique + across all EGLDeviceEXT handles. If an EGL implementation supports + multiple drivers, and two drivers can use the same physical device, + then there will be a separate EGLDeviceEXT handle from each driver. + Both EGLDeviceEXT handles may use the same device UUID. + + In that case, an application must use EGL_DRIVER_NAME_EXT or + EGL_DRIVER_UUID_EXT to distinguish between the two EGLDeviceEXT + handles. + + + EGL_DRIVER_UUID_EXT is a UUID that identifies a driver build + in use for a device. The driver UUID is persistent across reboots, + processes, and APIs, but is not persistent across driver versions. + +Issues + + 1. Should we use UUID's or strings to identify devices? + + RESOLVED: Use UUID's for devices, plus a vendor name string to + disambiguate devices that are supported by multiple drivers. + + A device UUID and driver UUID allow an application to correlate + an EGLDeviceEXT with the same device in other APIs, such as a + VkPhysicalDevice in Vulkan. + + A UUID does not impose any additional requirements on an EGL + implementation compared to a string: If an EGL implementation + could generate a string identifier, then the implementation can + simply hash that string to generate a UUID value. + + 2. Can two EGLDeviceEXT handles have the same EGL_DEVICE_UUID_EXT? + + RESOLVED: Yes, if they correspond to the same physical device. + + The semantics of the device and driver UUID's are inherited from + Vulkan, which only requires that a device UUID be unique to a + physical device, not unique across VkPhysicalDevice handles. + + 3. Do we need the EGL_DRIVER_NAME_EXT string? + + RESOLVED: Yes, because the EGL_DEVICE_UUID_EXT alone is not + unique, and EGL_DRIVER_UUID_EXT is not persistent. + + A (EGL_DRIVER_NAME_EXT, EGL_DEVICE_UUID_EXT) pair provides a + unique, persistent identifier. + + In addition, on systems that use libglvnd, applications could + use EGL_DRIVER_NAME_EXT to match the vendor names from + GLX_EXT_libglvnd. + + 4. What happens if an application stores a device UUID, and the + hardware configuration or driver version changes? + + RESOLVED: The device UUID may become invalid, and the + application should select a new device. + + If a device is removed from a system, then there will be no + EGLDeviceEXT handle for it, and thus no device UUID for it. + + Similarly, if a device is moved within a system (e.g., plugged + into a different PCI slot), then a driver may not be able to + identify it as the same device, and so the device might get a + different UUID. + + While not a requirement, drivers should still try to keep device + UUID's persistent whenever possible, to avoid invalidating + config files. Similarly, if a device is removed or replaced, + then a driver should try to ensure that the same device UUID + does not refer to a different device. + + As an example, a driver could derive a UUID based on a PCI + vendor and device number, plus the PCI domain, bus, slot, and + function numbers: + + * The PCI device number ensures that replacing a GPU with a + different model in the same PCI slot produces a different + device UUID string. + * Using the PCI bus numbers ensures that two identical + GPU's in the same system have unique UUID's. + * The whole tuple can easily stay persistent across driver + versions. + +Revision History + + #1 (April 19, 2021) Kyle Brenneman + + - Initial draft diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_query.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_query.txt new file mode 100644 index 0000000..b976aa9 --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_query.txt @@ -0,0 +1,188 @@ +Name + + EXT_device_query + +Name Strings + + EGL_EXT_device_query + +Contributors + + James Jones, NVIDIA (jajones 'at' nvidia.com) + Jamie Madill, Google (jmadill 'at' google.com) + +Contacts + + Jamie Madill, Google (jmadill 'at' google.com) + +Status + + Complete. + +Version + + Version 1 - Mar 25rd, 2015 + +Number + + EGL Extension #89 + +Extension Type + + EGL client extension + +Dependencies + + Written against the wording of EGL 1.5. + + Requires EGL 1.5 or an earlier verison of EGL with the + EGL_EXT_client_extensions extension. + +Overview + + Increasingly, EGL and its client APIs are being used in place of + "native" rendering APIs to implement the basic graphics + functionality of native windowing systems. This creates demand + for a method to access native GPU or device objects directly + rather than calling EGL or GL entry points. + + This extension defines the method for an application to query + native device objects from an EGL Display. + +New Types + + This is the type of a handle that represents an EGLDeviceEXT + object. + + typedef void* EGLDeviceEXT; + + If EGL 1.5 is not supported, the following type is added, as + defined in the EGL 1.5 specification: + + typedef intptr_t EGLAttrib; + +New Functions + + EGLBoolean eglQueryDeviceAttribEXT(EGLDeviceEXT device, + EGLint attribute, + EGLAttrib *value); + + const char *eglQueryDeviceStringEXT(EGLDeviceEXT device, + EGLint name); + + EGLBoolean eglQueryDisplayAttribEXT(EGLDisplay dpy, + EGLint attribute, + EGLAttrib *value); + +New Tokens + + Functions with a return type of EGLDeviceEXT will return this + value on failure: + + EGL_NO_DEVICE_EXT ((EGLDeviceEXT)0) + + This error value will be generated by functions that take an + EGLDeviceEXT object as a parameter: + + EGL_BAD_DEVICE_EXT 0x322B + + Accepted by the <attribute> parameter of + eglQueryDisplayAttribEXT: + + EGL_DEVICE_EXT 0x322C + +Add a new section "2.1.2 Devices" after "2.1.1 Scalar Types" + + All EGL operations occur on an EGLDeviceEXT. However, devices + themselves expose no functionality. They are simple abstract + objects that exist only for the sake of enumeration and + defining a namespace. + +Modify the last sentence of section "2.1.3" Displays" to read: + + Besides devices, objects are always specified by the combination + of an EGLDisplay parameter with a parameter representing the + handle of the object. + +Add a new extension type to the list in section "2.8 Extensions" + + Device Extensions + A *device extension* adds functionality to an individual + EGLDeviceEXT. Different instances of EGLDeviceEXT may support + different sets of device extensions + +Add a new error to section "3.1 Errors" + + EGL_BAD_DEVICE_EXT + An EGLDeviceEXT argument does not refer to a valid + EGLDeviceEXT. Any command taking an EGLDeviceEXT parameter + may generate this error. + +Add a section "3.2 Devices" after "3.1 Errors" + + To query the properties of a device, use: + + EGLBoolean eglQueryDeviceAttribEXT(EGLDeviceEXT device, + EGLint attribute, + EGLAttrib *value); + + On success, EGL_TRUE is returned and the requested attribute value + is returned in <value>. Currently there are no valid values of + <attribute> defined. + + On failure, EGL_FALSE is returned. An EGL_BAD_ATTRIBUTE error is + generated if <attribute> is not a valid attribute. An + EGL_BAD_DEVICE_EXT error is generated if <device> is not a valid + EGLDeviceEXT. + + const char *eglQueryDeviceStringEXT(EGLDeviceEXT device, + EGLint name); + + returns a pointer to a static, zero-terminated string describing + some aspect of the specified EGLDeviceEXT. <name> must be + EGL_EXTENSIONS. + + The EGL_EXTENSIONS string describes which device extensions are + supported by <device>. The string is of the same format specified + for display and client extension strings in section 3.4. Note that + device extensions are properties of the device, and are distinct + from other extension strings. + + On failure, NULL is returned. An EGL_BAD_DEVICE_EXT error is + generated if <device> is not a valid EGLDeviceEXT. An + EGL_BAD_PARAMETER error is generated if <name> is not one of the + values described above. + +Add a section "3.4 Display Attributes" after "3.3 EGL Versioning" + + To query attributes of an initialized display, use: + + EGLBoolean eglQueryDisplayAttribEXT(EGLDisplay dpy, + EGLint name, + EGLAttrib *value); + + On success, EGL_TRUE is returned. If <name> is EGL_DEVICE_EXT, + the EGLDeviceEXT associated with <dpy> is returned in <value>. + All displays have an associated EGLDeviceEXT, regardless of how + they were created. A successful query of EGL_DEVICE_EXT will + never return EGL_NO_DEVICE_EXT. + + On failure, EGL_FALSE is returned. An EGL_NOT_INITIALIZED error + is generated if EGL is not initialized for <dpy>. An + EGL_BAD_ATTRIBUTE error is generated if <name> is not a valid + value. + + Because the EGLDeviceEXT is a property of <dpy>, any use of an + associated EGLDeviceEXT after <dpy> has been terminated gives + undefined results. Querying an EGL_DEVICE_EXT from <dpy> after a + call to eglTerminate() (and subsequent re-initialization) may + return a different value. + +Issues + + None. + +Revision History: + + #1 (Mar 25rd, 2015) Jamie Madill + - Initial Draft based on EGL_EXT_device_base diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_query_name.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_query_name.txt new file mode 100644 index 0000000..bb2be91 --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_query_name.txt @@ -0,0 +1,104 @@ +Name + + EXT_device_query_name + +Name Strings + + EGL_EXT_device_query_name + +Contributors + + Kyle Brenneman, NVIDIA (kbrenneman 'at' nvidia.com) + Daniel Kartch, NVIDIA (dkartch 'at' nvidia.com) + +Contact + + Kyle Brenneman, NVIDIA (kbrenneman 'at' nvidia.com) + +Status + + Complete + +Version + + Version 1 - June 12, 2020 + +Number + + EGL Extension #140 + +Extension Type + + EGL device extension + +Dependencies + + Written based on the wording of the EGL 1.5 specification. + + EGL_EXT_device_query is required. + +Overview + + The EGL_EXT_device_enumeration and EGL_EXT_device_query extensions + provide a list of devices and a list of extensions, but lacks a way + to find a name for a device that an application can present to a + user. + + This extension adds two new strings that an application can query to + find human-readable names. + +New Types + + None + +New Functions + + None + +New Tokens + + Accepted by the <name> parameter of eglQueryDeviceStringEXT: + + EGL_RENDERER_EXT 0x335F + +New Device Queries + + eglQueryDeviceStringEXT accepts two new attributes. + + EGL_VENDOR and EGL_RENDERER_EXT return a human-readable name for the + vendor and device, respectively. + + The format of the EGL_VENDOR and EGL_RENDERER strings is + implementation-dependent. + + The EGL_VENDOR string for an EGLDeviceEXT is not required to match + the EGL_VENDOR string for an EGLDisplay or the GL_VENDOR string for + a context. Similarly, the EGL_RENDERER string is not required to + match the GL_RENDERER string for a context. + +Issues + + 1. Do we need a device query, instead of just creating an + EGLDisplay and calling eglQueryString? + + RESOLVED: Yes, a device-level query is useful, because some + devices might not be usable with EGL_EXT_platform_device. This + is especially true on systems where different devices are + handled by different drivers. + + 2. If an application creates an EGLDisplay from an EGLDevice, + are the EGL_VENDOR strings required to match? + + RESOLVED: No. Some implementations might not load a driver until + eglInitialize, and so might have a different or more specific + EGL_VENDOR string associated with an EGLDisplay than with an + EGLDeviceEXT. In addition, an implementation might select a + driver to use based on other parameters in + eglGetPlatformDisplay. + +Revision History + + #1 (June 12, 2020) Kyle Brenneman + + - Initial draft + diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_explicit_device.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_explicit_device.txt new file mode 100644 index 0000000..2ba8834 --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_explicit_device.txt @@ -0,0 +1,136 @@ +Name + + EXT_explicit_device + +Name Strings + + EGL_EXT_explicit_device + +Contributors + + Adam Jackson + Nicolai Haehnle + Daniel Stone + Kyle Brenneman + +Contacts + + Adam Jackson <ajax@redhat.com> + +Status + + Complete + +Version + + Version 3, 2022-04-21 + +Number + + EGL Extension #148 + +Extension Type + + EGL client extension + +Dependencies + + Requires EGL_EXT_platform_base and EGL_EXT_device_enumeration. + + EGL_EXT_platform_device trivially interacts with this extension. + + This extension is written against the EGL 1.5 Specification. + +Overview + + A system may support rendering with multiple devices for the same + windowing system. In that case, an EGL implementation must select a + default device based on the native display. + + This extension allows an application to explicitly request a device + to use for rendering instead of the implementation's default. + + This differs from EGL_EXT_platform_device in that + EGL_EXT_platform_device uses an EGLDeviceEXT instead of a native + display. Thus, EGL_EXT_platform_device allows offscreen rendering + to a pbuffer or FBO, but it does not require or use a windowing + system, and thus does not allow pixmap or window surfaces. + + Using EGL_EXT_explicit_device with EGL_MESA_platform_surfaceless is + functionally identical to EGL_EXT_platform_device. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + None + +Additions to the EGL Specification + + None + +New Behavior + + If EGL_DEVICE_EXT is specified as an attribute for + eglGetPlatformDisplay, the value of the attribute is interpreted as + an EGLDeviceEXT as returned by eglQueryDevicesEXT. + + If the EGL_DEVICE_EXT attribute is EGL_NO_DEVICE_EXT, then the + implementation will select a device automatically, as it would + normally. + + If the EGL_DEVICE_EXT attribute is not EGL_NO_DEVICE_EXT, then the + implementation will use the specified device for rendering. If the + EGL_DEVICE_EXT attribute does not name a valid EGLDeviceEXT, then + EGL_BAD_DEVICE_EXT is generated. + + An implementation might not support all devices for all native + displays. If the device and native display are not compatible for + any reason, then EGL_BAD_MATCH is generated. + + If EGL_EXT_platform_device is supported, passing EGL_DEVICE_EXT as an + attribute to eglGetPlatformDisplay(EGL_PLATFORM_DEVICE_EXT) generates + EGL_BAD_ATTRIBUTE. + +Issues + + 1. Should we have a separate function to query whether a device is + compatible with a native display? + + RESOLVED: No. A separate query might require duplicating a lot of + the work that eglGetPlatformDisplay and eglInitialize would do, + which could be very slow. + + 2. If an implementation can't support a device with a particular + native display, then should it fail in eglGetPlatformDisplay, or + can it defer any compatibility checks until eglInitialize? + + RESOLVED: eglGetPlatformDisplay must check for compatibility and + should fail if the device and native display are not supported. + + Without a separate function to check for compatibility, the only + way for an application to know which devices can work with a + native display is to try to use each device and see if it gets an + error. If the error is in eglInitialize, then an application + would have to create (and leak) a bunch of EGLDisplay handles + that it never intends to use. + +Revision History + + Version 3, 2022-04-21 (Kyle Brenneman) + - Require eglGetPlatformDisplay (instead of eglInitialize) check + whether the device is supported with the native display. + + Version 2, 2017-08-08 (Adam Jackson) + - Renamed from MESA_platform_device to EXT_explicit_device + - Make it an error to use this new attribute in conjunction with + EGL_EXT_platform_device + + Version 1, 2017-07-14 (Adam Jackson) + - Initial version diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_gl_colorspace_bt2020_linear.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_gl_colorspace_bt2020_linear.txt new file mode 100644 index 0000000..37eb6ba --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_gl_colorspace_bt2020_linear.txt @@ -0,0 +1,175 @@ +Name + + EXT_gl_colorspace_bt2020 + +Name Strings + + EGL_EXT_gl_colorspace_bt2020_linear + EGL_EXT_gl_colorspace_bt2020_pq + +Contributors + + Tom Cooksey + Andrew Garrard + Jesse Hall + Mathias Heyer + Lauri Hyvarinen + Adam Jackson + James Jones + Daniel Koch + Jeff Leger + Weiwan Liu + Jeff Vigil + +Contact + + Weiwan Liu (weiwliu 'at' nvidia.com) + +IP Status + + No known IP claims. + +Status + + Complete + +Version + + Version 7 - Nov 22, 2016 + +Number + + EGL Extension #107 + +Dependencies + + These extensions are written against the wording of the EGL 1.5 + specification (August 27, 2014). + + These extensions require EGL_KHR_gl_colorspace. + +Overview + + Applications may wish to take advantage of a larger color gamut in the + BT.2020 (ITU-R Recommendation BT.2020) color space. These extensions allow + applications to do so by communicating to the platform the color space the + framebuffer data is in, i.e. BT.2020 color space, as well as the encoding + of the framebuffer data, which can be either linear or PQ (Dolby Perceptual + Quantizer - SMPTE ST 2084) encoding. Applications are expected to prepare + the framebuffer data properly. + +New Procedures and Functions + + None. + +New Tokens + + Accepted as attribute values for EGL_GL_COLORSPACE by + eglCreateWindowSurface, eglCreatePbufferSurface and eglCreatePixmapSurface: + + [[ If EGL_EXT_gl_colorspace_bt2020_linear is supported ]] + + EGL_GL_COLORSPACE_BT2020_LINEAR_EXT 0x333F + + [[ If EGL_EXT_gl_colorspace_bt2020_pq is supported ]] + + EGL_GL_COLORSPACE_BT2020_PQ_EXT 0x3340 + +Modifications to the EGL 1.5 Specification + + Insert below text in the 3rd paragraph on page 33 in 3.5.1 "Creating On- + Screen Rendering Surfaces, before "The default value of EGL_GL_COLORSPACE + is EGL_GL_COLORSPACE_LINEAR.": + + [[ If EGL_EXT_gl_colorspace_bt2020_linear is supported ]] + + If its value is EGL_GL_COLORSPACE_BT2020_LINEAR_EXT, then a linear BT.2020 + color space is assumed, with a corresponding GL_FRAMEBUFFER_ATTACHMENT_- + COLOR_ENCODING value of GL_LINEAR. + + [[ If EGL_EXT_gl_colorspace_bt2020_pq is supported ]] + + If its value is EGL_GL_COLORSPACE_BT2020_PQ_EXT, then a non-linear, PQ + encoded BT.2020 color space is assumed, with a corresponding GL_FRAMEBUFFER- + _ATTACHMENT_COLOR_ENCODING value of GL_LINEAR, as neither OpenGL nor OpenGL + ES supports PQ framebuffers. Applications utilizing this option need to + ensure that PQ encoding is performed on the application side. + + Modify the 4th paragraph on the same page: + + Note that the EGL_GL_COLORSPACE_SRGB attribute is used only by OpenGL and + OpenGL ES contexts supporting sRGB framebuffers. EGL itself does not + distinguish multiple colorspace models. Refer to the "sRGB Conversion" + sections of the OpenGL 4.4 and OpenGL ES 3.0 specifications for more + information. + + Add a paragraph after the 4th paragraph above: + + [[ If EGL_EXT_gl_colorspace_bt2020_linear is supported ]] + + When using a floating-point EGL surface with EGL_GL_COLORSPACE_BT2020_- + LINEAR_EXT, the output values in the display-referred range of [0.0, 1.0] + correspond to a luminance range of 0 to 80 nits, which is the same luminance + range for sRGB. To achieve a larger dynamic range of 0 to 10000 nits, which + is the same range for PQ, the display-referred output values can go beyond + 1.0 and to a range of [0.0, 125.0], where 0.0 corresponds to 0 nit and 125.0 + corresponds to 10000 nits. + + [[ If EGL_EXT_gl_colorspace_bt2020_pq is supported ]] + + When using a floating-point EGL surface with EGL_GL_COLORSPACE_BT2020_PQ_- + EXT, to achieve the luminance range of 0 to 10000 nits (candela per square + meter) as defined by the SMPTE 2084 standard, applications can output values + in a display-referred range of [0.0, 1.0], where 0.0 corresponds to 0 nit + and 1.0 corresponds to 10000 nits. + +Errors + + Modify below error in the "Errors" section on page 34: + + "If config does not support the OpenVG colorspace or alpha format at- + tributes specified in attrib list (as defined for eglCreatePlatformWindow- + Surface), an EGL_BAD_MATCH error is generated." + + To include OpenGL colorspace as well: + + "If config does not support the OpenGL colorspace, the OpenVG colorspace or + alpha format attributes specified in attrib list (as defined for eglCreate- + PlatformWindowSurface), an EGL_BAD_MATCH error is generated." + +Issues + + 1. When creating an EGL surface, what happens when the specified colorspace + is not compatible with or supported by the EGLConfig? + + RESOLVED: There is currently no way to query the compatibility of a + EGLConfig and colorspace pair. So the only option is to define an error + case similar to that of OpenVG colorspace, i.e. if config does not + support the colorspace specified in attrib list (as defined for egl- + CreateWindowSurface, eglCreatePbufferSurface and eglCreatePixmapSurface), + an EGL_BAD_MATCH error is generated. + +Revision History + + Version 1, 2016/04/27 + - Internal revisions + + Version 2, 2016/05/20 + - Rename to EXT + + Version 3, 2016/05/25 + - Add issues + + Version 4, 2016/06/06 + - Split up the extension and put each colorspace option into an individual + extension + + Version 5, 2016/06/17 + - Correct the meaning of the data from scene-referred to display-referred + + Version 6, 2016/10/27 + - Mark issue #1 as "RESOLVED" and add an error case + + Version 7, 2016/11/22 + - Change status to complete + diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_gl_colorspace_display_p3.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_gl_colorspace_display_p3.txt new file mode 100644 index 0000000..32e7ebc --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_gl_colorspace_display_p3.txt @@ -0,0 +1,137 @@ +Name + + EXT_gl_colorspace_display_p3 + +Name Strings + + EGL_EXT_gl_colorspace_display_p3_linear + EGL_EXT_gl_colorspace_display_p3 + +Contributors + + Courtney Goeltzenleuchter + Jesse Hall + +Contact + + Courtney Goeltzenleuchter (courtneygo 'at' google.com) + +IP Status + + No known IP claims. + +Status + + Draft + +Version + + Version 2 - Oct 4, 2018 + +Number + + EGL Extension #118 + +Extension Type + + EGL display extension + +Dependencies + + These extensions are written against the wording of the EGL 1.5 + specification (August 27, 2014). + + These extensions require EGL_KHR_gl_colorspace. + +Overview + + Applications that want to use the Display-P3 color space (DCI-P3 primaries + and linear or sRGB-like transfer function) can use this extension to + communicate to the platform that framebuffer contents represent colors in + the Display-P3 color space. + The application is responsible for producing appropriate framebuffer + contents, but will typically use built-in sRGB encoding in OpenGL and OpenGL + ES to accomplish this. + +New Procedures and Functions + + None. + +New Tokens + + Accepted as attribute values for EGL_GL_COLORSPACE by + eglCreateWindowSurface, eglCreatePbufferSurface and eglCreatePixmapSurface: + + [[ If EGL_EXT_gl_colorspace_display_p3_linear is supported ]] + + EGL_GL_COLORSPACE_DISPLAY_P3_LINEAR_EXT 0x3362 + + [[ If EGL_EXT_gl_colorspace_display_p3 is supported ]] + + EGL_GL_COLORSPACE_DISPLAY_P3_EXT 0x3363 + +Modifications to the EGL 1.5 Specification + + Insert below text in the 3rd paragraph on page 33 in 3.5.1 "Creating On- + Screen Rendering Surfaces, before "The default value of EGL_GL_COLORSPACE + is EGL_GL_COLORSPACE_LINEAR.": + + [[ If EGL_EXT_gl_colorspace_display_p3_linear is supported ]] + + If its value is EGL_GL_COLORSPACE_DISPLAY_P3_LINEAR_EXT, then a linear + Display-P3 color space is assumed, with a corresponding + GL_FRAMEBUFFER_ATTACHMENT_COLOR_ENCODING value of GL_LINEAR. + + [[ If EGL_EXT_gl_colorspace_display_p3 is supported ]] + + If its value is EGL_GL_COLORSPACE_DISPLAY_P3_EXT, then a non-linear, sRGB + encoded Display-P3 color space is assumed, with a corresponding GL_FRAME- + BUFFER_ATTACHMENT_COLOR_ENCODING value of GL_SRGB. + Only OpenGL and OpenGL ES contexts which support sRGB rendering must + respect requests for EGL_GL_COLORSPACE_SRGB_KHR, and only to sRGB + formats supported by the context (normally just SRGB8). + + Modify the 4th paragraph on the same page: + + Note that the EGL_GL_COLORSPACE_SRGB attribute is used only by OpenGL and + OpenGL ES contexts supporting sRGB framebuffers. EGL itself does not + distinguish multiple colorspace models. Refer to the "sRGB Conversion" + sections of the OpenGL 4.4 and OpenGL ES 3.0 specifications for more + information. + +Errors + + Modify below error in the "Errors" section on page 34: + + "If config does not support the OpenVG colorspace or alpha format at- + tributes specified in attrib list (as defined for eglCreatePlatformWindow- + Surface), an EGL_BAD_MATCH error is generated." + + To include OpenGL colorspace as well: + + "If config does not support the OpenGL colorspace, the OpenVG colorspace or + alpha format attributes specified in attrib list (as defined for eglCreate- + PlatformWindowSurface), an EGL_BAD_MATCH error is generated." + +Issues + + 1. Removed section talking about HDR features, e.g. luminance > 80nits. + Do we want to keep that here in anticipation of HDR support in the future? + + 2. When creating an EGL surface, what happens when the specified colorspace + is not compatible with or supported by the EGLConfig? + + RESOLVED: There is currently no way to query the compatibility of a + EGLConfig and colorspace pair. So the only option is to define an error + case similar to that of OpenVG colorspace, i.e. if config does not + support the colorspace specified in attrib list (as defined for egl- + CreateWindowSurface, eglCreatePbufferSurface and eglCreatePixmapSurface), + an EGL_BAD_MATCH error is generated. + +Revision History + + Version 1, 2017/03/22 + - Internal revisions + + Version 2, 2018/10/04 + - Fix typo to correct extension reference diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_gl_colorspace_display_p3_passthrough.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_gl_colorspace_display_p3_passthrough.txt new file mode 100644 index 0000000..f0223a6 --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_gl_colorspace_display_p3_passthrough.txt @@ -0,0 +1,139 @@ +Name + + EXT_gl_colorspace_display_p3_passthrough + +Name Strings + + EGL_EXT_gl_colorspace_display_p3_passthrough + +Contributors + + Chris Forbes + Courtney Goeltzenleuchter + +Contact + + Courtney Goeltzenleuchter (courtneygo 'at' google.com) + +IP Status + + No known IP claims. + +Status + + Draft + +Version + + Version 1 - Dec 4, 2018 + +Number + + EGL Extension #130 + +Extension Type + + EGL display extension + +Dependencies + + This extension is written against the wording of the EGL 1.5 + specification (August 27, 2014). + + This extension requires EGL_KHR_gl_colorspace. + +Overview + + Applications that want to use the Display-P3 color space (DCI-P3 primaries + with sRGB-like transfer function) can use this extension to + communicate to the platform that framebuffer contents represent colors in + the non-linear Display-P3 color space. + The application is responsible for producing appropriate framebuffer + contents. An application would want to use this extension rather than + EGL_EXT_gl_colorspace_display_p3 if they apply the sRGB transfer function + themselves and do not need the HW to do it. + +New Procedures and Functions + + None. + +New Tokens + + Accepted as attribute values for EGL_GL_COLORSPACE by + eglCreateWindowSurface, eglCreatePbufferSurface and eglCreatePixmapSurface: + + [[ If EGL_EXT_gl_colorspace_display_p3_linear is supported ]] + + EGL_GL_COLORSPACE_DISPLAY_P3_PASSTHROUGH_EXT 0x3490 + +Modifications to the EGL 1.5 Specification + + Insert below text in the 3rd paragraph on page 33 in 3.5.1 "Creating On- + Screen Rendering Surfaces, before "The default value of EGL_GL_COLORSPACE + is EGL_GL_COLORSPACE_LINEAR.": + + [[ If EGL_EXT_gl_colorspace_display_p3_passthrough is supported ]] + + If its value is EGL_GL_COLORSPACE_DISPLAY_P3_PASSTHROUGH_EXT, then a + non-linear, sRGB encoded Display-P3 color space is assumed, with a + corresponding GL_FRAMEBUFFER_ATTACHMENT_COLOR_ENCODING value of GL_LINEAR. + The application is responsible for applying the appropriate transfer + function when writing and reading pixels. + + Insert below text after the 4th paragraph on the same page: + + Note that the EGL_GL_COLORSPACE_DISPLAY_P3_PASSTHROUGH_EXT attribute + indicates that a colorspace of Display P3 will be communicated to the + Window system. While EGL itself is color space agnostic, the surface + will eventually be presented to a display device with specific color + reproduction characteristics. If any color space transformations are + necessary before an image can be displayed, the color space of the + presented image must be known to the window system. + +Errors + + Modify below error in the "Errors" section on page 34: + + "If config does not support the OpenVG colorspace or alpha format at- + tributes specified in attrib list (as defined for eglCreatePlatformWindow- + Surface), an EGL_BAD_MATCH error is generated." + + To include OpenGL colorspace as well: + + "If config does not support the OpenGL colorspace, the OpenVG colorspace or + alpha format attributes specified in attrib list (as defined for eglCreate- + PlatformWindowSurface), an EGL_BAD_MATCH error is generated." + +Issues + + 1. When creating an EGL surface, what happens when the specified colorspace + is not compatible with or supported by the EGLConfig? + + RESOLVED: There is currently no way to query the compatibility of a + EGLConfig and colorspace pair. So the only option is to define an error + case similar to that of OpenVG colorspace, i.e. if config does not + support the colorspace specified in attrib list (as defined for egl- + CreateWindowSurface, eglCreatePbufferSurface and eglCreatePixmapSurface), + an EGL_BAD_MATCH error is generated. + + 2. Why the new enum instead of DISPLAY_P3_EXT + EXT_srgb_write_control? + + RESOLVED: + We want to rely on "surface state" rather than a "context state", e.g. + EXT_srgb_write_control is global where we only want behavior to apply to + specific surface. + + 3. Should sRGB framebuffer support affect the pixel path? + + RESOLVED: No. + + sRGB rendering is defined by GL/GLES. Specifically, glReadPixels and + other pixel paths operations are not affected by sRGB rendering. But + glBlitFramebuffer is. Though, of course, if this extension were to + apply it would be a no-op. + +Revision History + + Version 1, 2018/12/04 + - Internal revisions + diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_gl_colorspace_scrgb.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_gl_colorspace_scrgb.txt new file mode 100644 index 0000000..708fb17 --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_gl_colorspace_scrgb.txt @@ -0,0 +1,130 @@ +Name + + EXT_gl_colorspace_scrgb + +Name Strings + + EGL_EXT_gl_colorspace_scrgb + +Contributors + + Courtney Goeltzenleuchter + Lauri Hyvarinen + Weiwan Liu + Arun Swain + +Contact + + Courtney Goeltzenleuchter (courtneygo 'at' google.com) + +IP Status + + No known IP claims. + +Status + + Draft + +Version + + Version 2 - August 25, 2017 + +Number + + EGL Extension #119 + +Dependencies + + This extension is written against the wording of the EGL 1.5 specification + (August 27, 2014). + + This extension requires EGL_KHR_gl_colorspace and EGL_EXT_pixel_format_- + float, and interacts with EGL_EXT_surface_SMPTE2086_metadata. This extension + is closely related to EGL_EXT_gl_colorspace_scrgb_linear. + +Overview + + This extension provides an extended sRGB (also called scRGB) color + space option for applications to choose from when creating an EGLSurface. + This extension defines the non-linear display referred scRGB color space. + It has the same white point and color primaries as sRGB, and thus is + backward-compatible with sRGB. Refer to the IEC 61966-2-2:2003 standard + for details on scRGB color space. + + This extension chooses to use floating-point formats for scRGB color space. + For each color channel, the floating-point values of 0.0 and 1.0 still + correspond to sRGB chromaticities and luminance levels. However, scRGB + space allows for color values beyond the range of [0.0, 1.0], and can thus + achieve a larger color volume than that of sRGB. As it is display referred, + scRGB space makes assumptions of how the floating-point color values should + map to luminance levels by the underlying display pipeline. The expected + mapping is such that a color value of (1.0, 1.0, 1.0) corresponds to a + luminance level of 80 nits on a standardized studio monitor. As the color + value per channel goes beyond 1.0 and up to ~7.83, the corresponding + luminance levels also increase to a maximum of 10000 nits. + + The application is responsible for applying the extended sRGB transfer + function to color values written to or read from a surface with a + colorspace of EGL_EXT_gl_colorspace_scrgb. + +New Procedures and Functions + + None. + +New Tokens + + Accepted as attribute values for EGL_GL_COLORSPACE by + eglCreateWindowSurface, eglCreatePbufferSurface and eglCreatePixmapSurface: + + EGL_GL_COLORSPACE_SCRGB_EXT 0x3351 + +Modifications to the EGL 1.5 Specification + + Insert below text in the 3rd paragraph on page 33 in 3.5.1 "Creating On- + Screen Rendering Surfaces", before "The default value of EGL_GL_COLORSPACE + is EGL_GL_COLORSPACE_LINEAR.": + + [[ If EGL_EXT_gl_colorspace_scrgb is supported ]] + + If its value is EGL_GL_COLORSPACE_SCRGB_EXT, then a non-linear scRGB + color space is assumed. with a corresponding GL_FRAMEBUFFER_ATTACHMENT_- + COLOR_ENCODING value of GL_LINEAR as neither OpenGL nor OpenGL ES + supports framebuffers using an scRGB transfer function. + The application is responsible for applying the appropriate extended + sRGB transfer function when reading or writing to this buffer. + scRGB is defined to use the same primaries and white-point as sRGB. + See IEC 61966-2-2:2003 for details. + + Add two paragraphs after the 4th paragraph above: + + When using a floating-point EGL surface with EGL_GL_COLORSPACE_SCRGB_EXT, + the display-referred values in the range of (0.0, 0.0, 0.0) to + (1.0, 1.0, 1.0) correspond to a luminance range of 0 to 80 nits, which is + the same luminance range for sRGB. To achieve a larger dynamic range of up + to 10000 nits, the output values can go beyond 1.0 and to a range of + [0.0, ~7.83] for each channel. + + The effective color gamut and luminance range of the content that extend + beyond those of sRGB may be described via EGL_EXT_surface_SMPTE2086_metadata. + It is highly recommended to supply such metadata, so the display pipeline + may use this information to transform the the colors in a manner that + attempts to preserve the creative intent of the color data. + + In the "Errors" section on page 34 in 3.5.1 "Creating On Screen Rendering + Surfaces", change the 3rd error definition to: + + * If config does not support the OpenGL colorspace, the OpenVG colorspace or + alpha format attributes specified in attrib list (as defined for + eglCreatePlatformWindowSurface), an EGL_BAD_MATCH error is generated. + +Issues + + * Clarifications on the scRGB colorspace extensions + +Revision History + + Version 1, 2017/06/21 + - Initial draft + + Version 2, 2017/08/25 + - Clarify definition of color space diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_gl_colorspace_scrgb_linear.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_gl_colorspace_scrgb_linear.txt new file mode 100644 index 0000000..084f4a0 --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_gl_colorspace_scrgb_linear.txt @@ -0,0 +1,127 @@ +Name + + EXT_gl_colorspace_scrgb_linear + +Name Strings + + EGL_EXT_gl_colorspace_scrgb_linear + +Contributors + + Courtney Goeltzenleuchter + Lauri Hyvarinen + Weiwan Liu + Arun Swain + +Contact + + Weiwan Liu (weiwliu 'at' nvidia.com) + +IP Status + + No known IP claims. + +Status + + Complete + +Version + + Version 4 - August 25, 2017 + +Number + + EGL Extension #108 + +Dependencies + + This extension is written against the wording of the EGL 1.5 specification + (August 27, 2014). + + This extension requires EGL_KHR_gl_colorspace and EGL_EXT_pixel_format_- + float, and interacts with EGL_EXT_surface_SMPTE2086_metadata. This extension + is closely related to the EGL_EXT_gl_colorspace_scrgb. + +Overview + + This extension provides an extended sRGB (also called scRGB) color + space option for applications to choose from when creating an EGLSurface. + This extension defines the linear display referred scRGB color space. + It has the same white point and color primaries as sRGB, and thus is + backward-compatible with sRGB. Refer to the IEC 61966-2-2:2003 standard + for details on scRGB color space. + + This extension chooses to use floating-point formats for scRGB color space. + For each color channel, the floating-point values of 0.0 and 1.0 still + correspond to sRGB chromaticities and luminance levels. However, scRGB + space allows for color values beyond the range of [0.0, 1.0], and can thus + achieve a larger color volume than that of sRGB. As it is display referred, + scRGB space makes assumptions of how the floating-point color values should + map to luminance levels by the underlying display pipeline. The expected + mapping is such that a color value of (1.0, 1.0, 1.0) corresponds to a + luminance level of 80 nits on a standardized studio monitor. As the color + value per channel goes beyond 1.0 and up to 125.0, the corresponding + luminance levels also increase linearly to a maximum of 10000 nits. + +New Procedures and Functions + + None. + +New Tokens + + Accepted as attribute values for EGL_GL_COLORSPACE by + eglCreateWindowSurface, eglCreatePbufferSurface and eglCreatePixmapSurface: + + EGL_GL_COLORSPACE_SCRGB_LINEAR_EXT 0x3350 + +Modifications to the EGL 1.5 Specification + + Insert below text in the 3rd paragraph on page 33 in 3.5.1 "Creating On- + Screen Rendering Surfaces", before "The default value of EGL_GL_COLORSPACE + is EGL_GL_COLORSPACE_LINEAR.": + + If its value is EGL_GL_COLORSPACE_SCRGB_LINEAR_EXT, then a linear scRGB + color space is assumed, with a corresponding GL_FRAMEBUFFER_ATTACHMENT_- + COLOR_ENCODING value of GL_LINEAR. scRGB is defined to use the same + primaries and white-point as sRGB. See IEC 61966-2-2:2003 for details. + + Add two paragraphs after the 4th paragraph above: + + When using a floating-point EGL surface with EGL_GL_COLORSPACE_SCRGB_- + LINEAR_EXT, the display-referred values in the range of (0.0, 0.0, 0.0) to + (1.0, 1.0, 1.0) correspond to a luminance range of 0 to 80 nits, which is + the same luminance range for sRGB. To achieve a larger dynamic range of up + to 10000 nits, the output values can go beyond 1.0 and to a range of + [0.0, 125.0] for each channel. + + The effective color gamut and luminance range of the content that extend + beyond those of sRGB may be described via EGL_EXT_surface_SMPTE2086_metadata. + It is highly recommended to supply such metadata, so the display pipeline + may use this information to transform the colors in a manner that + attempts to preserve the creative intent of the color data. + + In the "Errors" section on page 34 in 3.5.1 "Creating On Screen Rendering + Surfaces", change the 3rd error definition to: + + * If config does not support the OpenGL colorspace, the OpenVG colorspace or + alpha format attributes specified in attrib list (as defined for + eglCreatePlatformWindowSurface), an EGL_BAD_MATCH error is generated. + +Issues + + * Clarifications on the scRGB colorspace extensions + +Revision History + + Version 1, 2016/10/21 + - Initial draft + + Version 2, 2016/11/18 + - Add reference to IEC 61966-2-2:2003 standard and minor wording changes + + Version 3, 2016/11/22 + - Change status to complete + + Version 4, 2017/08/25 + - Clarifications on the definition of scRGB colorspace + diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_image_dma_buf_import.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_image_dma_buf_import.txt new file mode 100644 index 0000000..17350d7 --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_image_dma_buf_import.txt @@ -0,0 +1,428 @@ +Name + + EXT_image_dma_buf_import + +Name Strings + + EGL_EXT_image_dma_buf_import + +Contributors + + Jesse Barker + Rob Clark + Tom Cooksey + +Contacts + + Jesse Barker (jesse 'dot' barker 'at' linaro 'dot' org) + Tom Cooksey (tom 'dot' cooksey 'at' arm 'dot' com) + +Status + + Complete. + +Version + + Version 7, December 13, 2013 + +Number + + EGL Extension #53 + +Dependencies + + EGL 1.2 is required. + + EGL_KHR_image_base is required. + + The EGL implementation must be running on a Linux kernel supporting the + dma_buf buffer sharing mechanism. + + This extension is written against the wording of the EGL 1.2 Specification. + +Overview + + This extension allows creating an EGLImage from a Linux dma_buf file + descriptor or multiple file descriptors in the case of multi-plane YUV + images. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted by the <target> parameter of eglCreateImageKHR: + + EGL_LINUX_DMA_BUF_EXT 0x3270 + + Accepted as an attribute in the <attrib_list> parameter of + eglCreateImageKHR: + + EGL_LINUX_DRM_FOURCC_EXT 0x3271 + EGL_DMA_BUF_PLANE0_FD_EXT 0x3272 + EGL_DMA_BUF_PLANE0_OFFSET_EXT 0x3273 + EGL_DMA_BUF_PLANE0_PITCH_EXT 0x3274 + EGL_DMA_BUF_PLANE1_FD_EXT 0x3275 + EGL_DMA_BUF_PLANE1_OFFSET_EXT 0x3276 + EGL_DMA_BUF_PLANE1_PITCH_EXT 0x3277 + EGL_DMA_BUF_PLANE2_FD_EXT 0x3278 + EGL_DMA_BUF_PLANE2_OFFSET_EXT 0x3279 + EGL_DMA_BUF_PLANE2_PITCH_EXT 0x327A + EGL_YUV_COLOR_SPACE_HINT_EXT 0x327B + EGL_SAMPLE_RANGE_HINT_EXT 0x327C + EGL_YUV_CHROMA_HORIZONTAL_SITING_HINT_EXT 0x327D + EGL_YUV_CHROMA_VERTICAL_SITING_HINT_EXT 0x327E + + Accepted as the value for the EGL_YUV_COLOR_SPACE_HINT_EXT attribute: + + EGL_ITU_REC601_EXT 0x327F + EGL_ITU_REC709_EXT 0x3280 + EGL_ITU_REC2020_EXT 0x3281 + + Accepted as the value for the EGL_SAMPLE_RANGE_HINT_EXT attribute: + + EGL_YUV_FULL_RANGE_EXT 0x3282 + EGL_YUV_NARROW_RANGE_EXT 0x3283 + + Accepted as the value for the EGL_YUV_CHROMA_HORIZONTAL_SITING_HINT_EXT & + EGL_YUV_CHROMA_VERTICAL_SITING_HINT_EXT attributes: + + EGL_YUV_CHROMA_SITING_0_EXT 0x3284 + EGL_YUV_CHROMA_SITING_0_5_EXT 0x3285 + + +Additions to Chapter 2 of the EGL 1.2 Specification (EGL Operation) + + Add to section 2.5.1 "EGLImage Specification" (as defined by the + EGL_KHR_image_base specification), in the description of + eglCreateImageKHR: + + "Values accepted for <target> are listed in Table aaa, below. + + +-------------------------+--------------------------------------------+ + | <target> | Notes | + +-------------------------+--------------------------------------------+ + | EGL_LINUX_DMA_BUF_EXT | Used for EGLImages imported from Linux | + | | dma_buf file descriptors | + +-------------------------+--------------------------------------------+ + Table aaa. Legal values for eglCreateImageKHR <target> parameter + + ... + + If <target> is EGL_LINUX_DMA_BUF_EXT, <dpy> must be a valid display, <ctx> + must be EGL_NO_CONTEXT, and <buffer> must be NULL, cast into the type + EGLClientBuffer. The details of the image is specified by the attributes + passed into eglCreateImageKHR. Required attributes and their values are as + follows: + + * EGL_WIDTH & EGL_HEIGHT: The logical dimensions of the buffer in pixels + + * EGL_LINUX_DRM_FOURCC_EXT: The pixel format of the buffer, as specified + by drm_fourcc.h and used as the pixel_format parameter of the + drm_mode_fb_cmd2 ioctl. + + * EGL_DMA_BUF_PLANE0_FD_EXT: The dma_buf file descriptor of plane 0 of + the image. + + * EGL_DMA_BUF_PLANE0_OFFSET_EXT: The offset from the start of the + dma_buf of the first sample in plane 0, in bytes. + + * EGL_DMA_BUF_PLANE0_PITCH_EXT: The number of bytes between the start of + subsequent rows of samples in plane 0. May have special meaning for + non-linear formats. + + For images in an RGB color-space or those using a single-plane YUV format, + only the first plane's file descriptor, offset & pitch should be specified. + For semi-planar YUV formats, that first plane (plane 0) holds only the luma + samples and chroma samples are stored interleaved in a second plane (plane + 1). For fully planar YUV formats, the first plane (plane 0) continues to + hold the luma samples however the chroma samples are stored seperately in + two additional planes (plane 1 & plane 2). If present, planes 1 & 2 are + specified by the following attributes, which have the same meanings as + defined above for plane 0: + + * EGL_DMA_BUF_PLANE1_FD_EXT + * EGL_DMA_BUF_PLANE1_OFFSET_EXT + * EGL_DMA_BUF_PLANE1_PITCH_EXT + * EGL_DMA_BUF_PLANE2_FD_EXT + * EGL_DMA_BUF_PLANE2_OFFSET_EXT + * EGL_DMA_BUF_PLANE2_PITCH_EXT + + The ordering of samples within a plane is taken from the drm_fourcc + pixel_format specified for EGL_LINUX_DRM_FOURCC_EXT. For example, if + EGL_LINUX_DRM_FOURCC_EXT is set to DRM_FORMAT_NV12, the chroma plane + specified by EGL_DMA_BUF_PLANE1* contains samples in the order V, U, + whereas if EGL_LINUX_DRM_FOURCC_EXT is DRM_FORMAT_NV21, the order is U, + V. Similarly, the ordering of planes for fully-planar formats is also taken + from the pixel_format specified as EGL_LINUX_DRM_FOURCC_EXT. For example, + if EGL_LINUX_DRM_FOURCC_EXT is set to DRM_FORMAT_YUV410, the luma plane is + specified by EGL_DMA_BUF_PLANE0*, the plane containing U-samples is + specified by EGL_DMA_BUF_PLANE1* and the plane containing the V-samples is + specified by EGL_DMA_BUF_PLANE2*, whereas if EGL_LINUX_DRM_FOURCC_EXT is + set to DRM_FORMAT_YVU410, plane 1 contains the V-samples and plane 2 + contains the U-samples. + + In addition to the above required attributes, the application may also + provide hints as to how the data should be interpreted by the GL. If any of + these hints are not specified, the GL will guess based on the pixel format + passed as the EGL_LINUX_DRM_FOURCC_EXT attribute or may fall-back to some + default value. Not all GLs will be able to support all combinations of + these hints and are free to use whatever settings they choose to achieve + the closest possible match. + + * EGL_YUV_COLOR_SPACE_HINT_EXT: The color-space the data is in. Only + relevant for images in a YUV format, ignored when specified for an + image in an RGB format. Accepted values are: + EGL_ITU_REC601_EXT, EGL_ITU_REC709_EXT & EGL_ITU_REC2020_EXT. + + * EGL_YUV_CHROMA_HORIZONTAL_SITING_HINT_EXT & + EGL_YUV_CHROMA_VERTICAL_SITING_HINT_EXT: Where chroma samples are + sited relative to luma samples when the image is in a sub-sampled + format. When the image is not using chroma sub-sampling, the luma and + chroma samples are assumed to be co-sited. Siting is split into the + vertical and horizontal and is in a fixed range. A siting of zero + means the first luma sample is taken from the same position in that + dimension as the chroma sample. This is best illustrated in the + diagram below: + + (0.5, 0.5) (0.0, 0.5) (0.0, 0.0) + + + + + + + + + * + * + + x x x x + + + + + + + + + + + + + + + + + + + + + + + * + * + + x x x x + + + + + + + + + + + + + + + Luma samples (+), Chroma samples (x) Chrome & Luma samples (*) + + Note this attribute is ignored for RGB images and non sub-sampled + YUV images. Accepted values are: EGL_YUV_CHROMA_SITING_0_EXT (0.0) + & EGL_YUV_CHROMA_SITING_0_5_EXT (0.5) + + * EGL_SAMPLE_RANGE_HINT_EXT: The numerical range of samples. Only + relevant for images in a YUV format, ignored when specified for + images in an RGB format. Accepted values are: EGL_YUV_FULL_RANGE_EXT + (0-256) & EGL_YUV_NARROW_RANGE_EXT (16-235). + + + If eglCreateImageKHR is successful for a EGL_LINUX_DMA_BUF_EXT target, the + EGL will take a reference to the dma_buf(s) which it will release at any + time while the EGLDisplay is initialized. It is the responsibility of the + application to close the dma_buf file descriptors." + + + Add to the list of error conditions for eglCreateImageKHR: + + "* If <target> is EGL_LINUX_DMA_BUF_EXT and <buffer> is not NULL, the + error EGL_BAD_PARAMETER is generated. + + * If <target> is EGL_LINUX_DMA_BUF_EXT, and the list of attributes is + incomplete, EGL_BAD_PARAMETER is generated. + + * If <target> is EGL_LINUX_DMA_BUF_EXT, and the EGL_LINUX_DRM_FOURCC_EXT + attribute is set to a format not supported by the EGL, EGL_BAD_MATCH + is generated. + + * If <target> is EGL_LINUX_DMA_BUF_EXT, and the EGL_LINUX_DRM_FOURCC_EXT + attribute indicates a single-plane format, EGL_BAD_ATTRIBUTE is + generated if any of the EGL_DMA_BUF_PLANE1_* or EGL_DMA_BUF_PLANE2_* + attributes are specified. + + * If <target> is EGL_LINUX_DMA_BUF_EXT and the value specified for + EGL_YUV_COLOR_SPACE_HINT_EXT is not EGL_ITU_REC601_EXT, + EGL_ITU_REC709_EXT or EGL_ITU_REC2020_EXT, EGL_BAD_ATTRIBUTE is + generated. + + * If <target> is EGL_LINUX_DMA_BUF_EXT and the value specified for + EGL_SAMPLE_RANGE_HINT_EXT is not EGL_YUV_FULL_RANGE_EXT or + EGL_YUV_NARROW_RANGE_EXT, EGL_BAD_ATTRIBUTE is generated. + + * If <target> is EGL_LINUX_DMA_BUF_EXT and the value specified for + EGL_YUV_CHROMA_HORIZONTAL_SITING_HINT_EXT or + EGL_YUV_CHROMA_VERTICAL_SITING_HINT_EXT is not + EGL_YUV_CHROMA_SITING_0_EXT or EGL_YUV_CHROMA_SITING_0_5_EXT, + EGL_BAD_ATTRIBUTE is generated. + + * If <target> is EGL_LINUX_DMA_BUF_EXT and one or more of the values + specified for a plane's pitch or offset isn't supported by EGL, + EGL_BAD_ACCESS is generated. + + +Issues + + 1. Should this be a KHR or EXT extension? + + ANSWER: EXT. Khronos EGL working group not keen on this extension as it is + seen as contradicting the EGLStream direction the specification is going in. + The working group recommends creating additional specs to allow an EGLStream + producer/consumer connected to v4l2/DRM or any other Linux interface. + + 2. Should this be a generic any platform extension, or a Linux-only + extension which explicitly states the handles are dma_buf fds? + + ANSWER: There's currently no intention to port this extension to any OS not + based on the Linux kernel. Consequently, this spec can be explicitly written + against Linux and the dma_buf API. + + 3. Does ownership of the file descriptor pass to the EGL library? + + ANSWER: No, EGL does not take ownership of the file descriptors. It is the + responsibility of the application to close the file descriptors on success + and failure. + + 4. How are the different YUV color spaces handled (BT.709/BT.601)? + + ANSWER: The pixel formats defined in drm_fourcc.h only specify how the data + is laid out in memory. It does not define how that data should be + interpreted. Added a new EGL_YUV_COLOR_SPACE_HINT_EXT attribute to allow the + application to specify which color space the data is in to allow the GL to + choose an appropriate set of co-efficients if it needs to convert that data + to RGB for example. + + 5. What chroma-siting is used for sub-sampled YUV formats? + + ANSWER: The chroma siting is not specified by either the v4l2 or DRM APIs. + This is similar to the color-space issue (4) in that the chroma siting + doesn't affect how the data is stored in memory. However, the GL will need + to know the siting in order to filter the image correctly. While the visual + impact of getting the siting wrong is minor, provision should be made to + allow an application to specify the siting if desired. Added additional + EGL_YUV_CHROMA_HORIZONTAL_SITING_HINT_EXT & + EGL_YUV_CHROMA_VERTICAL_SITING_HINT_EXT attributes to allow the siting to + be specified using a set of pre-defined values (0 or 0.5). + + 6. How can an application query which formats the EGL implementation + supports? + + PROPOSAL: Don't provide a query mechanism but instead add an error condition + that EGL_BAD_MATCH is raised if the EGL implementation doesn't support that + particular format. + + 7. Which image formats should be supported and how is format specified? + + Seem to be two options 1) specify a new enum in this specification and + enumerate all possible formats. 2) Use an existing enum already in Linux, + either v4l2_mbus_pixelcode and/or those formats listed in drm_fourcc.h? + + ANSWER: Go for option 2) and just use values defined in drm_fourcc.h. + + 8. How can AYUV images be handled? + + ANSWER: At least on fourcc.org and in drm_fourcc.h, there only seems to be + a single AYUV format and that is a packed format, so everything, including + the alpha component would be in the first plane. + + 9. How can you import interlaced images? + + ANSWER: Interlaced frames are usually stored with the top & bottom fields + interleaved in a single buffer. As the fields would need to be displayed as + at different times, the application would create two EGLImages from the same + buffer, one for the top field and another for the bottom. Both EGLImages + would set the pitch to 2x the buffer width and the second EGLImage would use + a suitable offset to indicate it started on the second line of the buffer. + This should work regardless of whether the data is packed in a single plane, + semi-planar or multi-planar. + + If each interlaced field is stored in a separate buffer then it should be + trivial to create two EGLImages, one for each field's buffer. + + 10. How are semi-planar/planar formats handled that have a different + width/height for Y' and CbCr such as YUV420? + + ANSWER: The spec says EGL_WIDTH & EGL_HEIGHT specify the *logical* width and + height of the buffer in pixels. For pixel formats with sub-sampled Chroma + values, it should be trivial for the EGL implementation to calculate the + width/height of the Chroma sample buffers using the logical width & height + and by inspecting the pixel format passed as the EGL_LINUX_DRM_FOURCC_EXT + attribute. I.e. If the pixel format says it's YUV420, the Chroma buffer's + width = EGL_WIDTH/2 & height =EGL_HEIGHT/2. + + 11. How are Bayer formats handled? + + ANSWER: As of Linux 2.6.34, drm_fourcc.h does not include any Bayer formats. + However, future kernel versions may add such formats in which case they + would be handled in the same way as any other format. + + 12. Should the spec support buffers which have samples in a "narrow range"? + + Content sampled from older analogue sources typically don't use the full + (0-256) range of the data type storing the sample and instead use a narrow + (16-235) range to allow some headroom & toeroom in the signals to avoid + clipping signals which overshoot slightly during processing. This is + sometimes known as signals using "studio swing". + + ANSWER: Add a new attribute to define if the samples use a narrow 16-235 + range or the full 0-256 range. + + 13. Specifying the color space and range seems cumbersome, why not just + allow the application to specify the full YUV->RGB color conversion matrix? + + ANSWER: Some hardware may not be able to use an arbitrary conversion matrix + and needs to select an appropriate pre-defined matrix based on the color + space and the sample range. + + 14. How do you handle EGL implementations which have restrictions on pitch + and/or offset? + + ANSWER: Buffers being imported using dma_buf pretty much have to be + allocated by a kernel-space driver. As such, it is expected that a system + integrator would make sure all devices which allocate buffers suitable for + exporting make sure they use a pitch supported by all possible importers. + However, it is still possible eglCreateImageKHR can fail due to an + unsupported pitch. Added a new error to the list indicating this. + + 15. Should this specification also describe how to export an existing + EGLImage as a dma_buf file descriptor? + + ANSWER: No. Importing and exporting buffers are two separate operations and + importing an existing dma_buf fd into an EGLImage is useful functionality in + itself. Agree that exporting an EGLImage as a dma_buf fd is useful, E.g. it + could be used by an OpenMAX IL implementation's OMX_UseEGLImage function to + give access to the buffer backing an EGLImage to video hardware. However, + exporting can be split into a separate extension specification. + + +Revision History + +#7 (Kristian H. Kristensen, December 13, 2017) + - Clarify plane ordering to match Linux FOURCC conventions (Bug 16017). + +#6 (David Garbett, December 05, 2013) + - Application now retains ownership of dma_buf file descriptors. + +#5 (Tom Cooksey, February 19, 2013) + - Assigned enum values + - Moved out of drafts + +#4 (Tom Cooksey, October 04, 2012) + - Fixed issue numbering! + - Added issues 8 - 15. + - Promoted proposal for Issue 3 to be the answer. + - Added an additional attribute to allow an application to specify the color + space as a hint which should address issue 4. + - Added an additional attribute to allow an application to specify the chroma + siting as a hint which should address issue 5. + - Added an additional attribute to allow an application to specify the sample + range as a hint which should address the new issue 12. + - Added language to end of error section clarifying who owns the fd passed + to eglCreateImageKHR if an error is generated. + +#3 (Tom Cooksey, August 16, 2012) + - Changed name from EGL_EXT_image_external and re-written language to + explicitly state this for use with Linux & dma_buf. + - Added a list of issues, including some still open ones. + +#2 (Jesse Barker, May 30, 2012) + - Revision to split eglCreateImageKHR functionality from export + Functionality. + - Update definition of EGLNativeBufferType to be a struct containing a list + of handles to support multi-buffer/multi-planar formats. + +#1 (Jesse Barker, March 20, 2012) + - Initial draft. diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_image_dma_buf_import_modifiers.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_image_dma_buf_import_modifiers.txt new file mode 100644 index 0000000..41b91c0 --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_image_dma_buf_import_modifiers.txt @@ -0,0 +1,244 @@ +Name + + EXT_image_dma_buf_import_modifiers + +Name Strings + + EGL_EXT_image_dma_buf_import_modifiers + +Contributors + + Pekka Paalanen, Collabora Ltd. + Louis-Francis Ratté-Boulianne + Daniel Stone, Collabora Ltd. + Kristian Høgsberg + +Contacts + + Pekka Paalanen (pq 'at' collabora 'dot' com) + Daniel Stone (daniels 'at' collabora 'dot' com) + +Status + + Complete + +Version + + Version 5, March 12, 2019 + +Number + + EGL Extension #105 + +Dependencies + + EGL 1.2 is required. + + EGL_KHR_image_base is required. + EGL_EXT_image_dma_buf_import is required. + + The EGL implementation must be running on a Linux kernel supporting the + dma_buf buffer sharing mechanism. + + This extension is written against the wording of the EGL 1.2 Specification. + + In order to support imports for the GL_TEXTURE_EXTERNAL_OES target, a + compatible OpenGL ES implementation supporting GL_OES_EGL_image_external + must be present. + +Overview + + This extension builds on EGL_EXT_image_dma_buf_import, in order to support + format modifiers used for tiling, compression, and additional non-linear + modes. It also adds support for a fourth auxiliary plane, and queries for + the implementation-supported types. + +New Types + + None + +New Procedures and Functions + + EGLBoolean eglQueryDmaBufFormatsEXT( + EGLDisplay dpy, + EGLint max_formats, + EGLint *formats, + EGLint *num_formats) + + + EGLBoolean eglQueryDmaBufModifiersEXT( + EGLDisplay dpy, + EGLint format, + EGLint max_modifiers, + EGLuint64KHR *modifiers, + EGLBoolean *external_only, + EGLint *num_modifiers) + +New Tokens + + Accepted as an attribute in the <attrib_list> parameter of + eglCreateImageKHR: + + EGL_DMA_BUF_PLANE0_MODIFIER_LO_EXT 0x3443 + EGL_DMA_BUF_PLANE0_MODIFIER_HI_EXT 0x3444 + EGL_DMA_BUF_PLANE1_MODIFIER_LO_EXT 0x3445 + EGL_DMA_BUF_PLANE1_MODIFIER_HI_EXT 0x3446 + EGL_DMA_BUF_PLANE2_MODIFIER_LO_EXT 0x3447 + EGL_DMA_BUF_PLANE2_MODIFIER_HI_EXT 0x3448 + EGL_DMA_BUF_PLANE3_FD_EXT 0x3440 + EGL_DMA_BUF_PLANE3_OFFSET_EXT 0x3441 + EGL_DMA_BUF_PLANE3_PITCH_EXT 0x3442 + EGL_DMA_BUF_PLANE3_MODIFIER_LO_EXT 0x3449 + EGL_DMA_BUF_PLANE3_MODIFIER_HI_EXT 0x344A + +New Types + + This extension uses the 64-bit unsigned integer type EGLuint64KHR + first introduced by the EGL_KHR_stream extension, but does not + depend on that extension. The typedef may be reproduced separately + for this extension, if not already present in eglext.h. + + typedef khronos_uint64_t EGLuint64KHR; + + +Additions to Chapter 2 of the EGL 1.2 Specification (EGL Operation) + + Add to section 2.5.1 "EGLImage Specification" (as defined by the + EGL_KHR_image_base specification), in the description of + eglCreateImageKHR: + + If <target> is EGL_LINUX_DMA_BUF_EXT, both or neither of the following + attribute values may be given. These attribute values together form an + unsigned 64-bit value called a format modifier. Format modifiers are + specified by drm_fourcc.h and used as the modifier parameter of the + drm_mode_fb_cmd2 ioctl. If neither of the two attributes are given, or + if the modifier is explicitly declared to be DRM_FORMAT_MOD_INVALID, the + effective format modifier is implementation-defined. The two attributes + are: + + * EGL_DMA_BUF_PLANE0_MODIFIER_LO_EXT: The lowest 32 bits of the + 64-bit format modifier. + + * EGL_DMA_BUF_PLANE0_MODIFIER_HI_EXT: The highest 32 bits of the + 64-bit format modifier. + + For semi-planar and planar YUV formats, or other formats which require + multiple memory planes, planes 1, 2 and 3 are specified by the following + attributes, which have the same meanings as defined above for plane 0: + + * EGL_DMA_BUF_PLANE1_MODIFIER_LO_EXT + * EGL_DMA_BUF_PLANE1_MODIFIER_HI_EXT + * EGL_DMA_BUF_PLANE2_MODIFIER_LO_EXT + * EGL_DMA_BUF_PLANE2_MODIFIER_HI_EXT + * EGL_DMA_BUF_PLANE3_FD_EXT + * EGL_DMA_BUF_PLANE3_OFFSET_EXT + * EGL_DMA_BUF_PLANE3_PITCH_EXT + * EGL_DMA_BUF_PLANE3_MODIFIER_LO_EXT + * EGL_DMA_BUF_PLANE3_MODIFIER_HI_EXT + + Modifiers may modify any attribute of a buffer import, including but not + limited to adding extra planes to a format which otherwise does not have + those planes. As an example, a modifier may add a plane for an external + compression buffer to a single-plane format. The exact meaning and effect + of any modifier is canonically defined by drm_fourcc.h, not as part of this + extension. + + Implementations are required to validate the full combination of base + format and per-plane modifiers, and reject any combination which is not + explicitly supported. + + Add to the list of error conditions for eglCreateImageKHR: + + * If <target> is EGL_LINUX_DMA_BUF_EXT, and the list of attributes + contains EGL_DMA_BUF_PLANE0_MODIFIER_LO_EXT but not + EGL_DMA_BUF_PLANE0_MODIFIER_HI_EXT or vice versa, EGL_BAD_PARAMETER + is generated. This applies similarly for planes 1, 2, and 3 also. + + Add section 2.5.3 "EGLImage dma_buf formats and modifiers" + + The command + + EGLBoolean eglQueryDmaBufFormatsEXT( + EGLDisplay dpy, + EGLint max_formats, + EGLint *formats, + EGLint *num_formats) + + is used to query the dma_buf formats supported by <dpy>. Each format is + returned using its FourCC format as defined in the drm_fourcc.h header file. + EGL_TRUE is returned if QueryDmaBufFormatsEXT succeeds, EGL_FALSE indicates + failure to query. + + * If <dpy> is not the handle of a valid EGLDisplay object, the error + EGL_BAD_DISPLAY is generated. + + * If <max_formats> is 0, no formats are returned, but the total number + of formats is returned in <num_formats>, and no error is generated. + + * If <max_formats> has a negative value, the error EGL_BAD_PARAMETER + is generated. + + * If <max_formats> is a positive integer but <formats> is NULL, the error + EGL_BAD_PARAMETER is generated. + + The command + + EGLBoolean eglQueryDmaBufModifiersEXT( + EGLDisplay dpy, + EGLint format, + EGLint max_modifiers, + EGLuint64KHR *modifiers, + EGLBoolean *external_only, + EGLint *num_modifiers) + + is used to query the dma_buf format modifiers supported by <dpy> for the + given format. The format must be one of those returned by the + eglQueryDmaBufFormatsEXT command. The returned modifiers should be + defined in the canonical drm_fourcc.h header file. If the user also + passes an array for <external_only>, this will be populated with whether + the requested format and modifier combination is only supported for use + with the GL_TEXTURE_EXTERNAL_OES texture target. If <dpy> cannot support + any context with GL_OES_EGL_image_external, the array will be populated with + EGL_FALSE. EGL_TRUE is returned if QueryDmaBufModifiersEXT succeeds, + EGL_FALSE indicates failure. + + * If <dpy> is not the handle of a valid EGLDisplay object, the error + EGL_BAD_DISPLAY is generated. + + * If <max_modifiers> is 0, no modifiers are returned, but the total + number of modifiers is returned in <num_modifiers>, and no error is + generated. + + * If <max_modifiers> has a negative value, the error EGL_BAD_PARAMETER + is generated. + + * If <max_modifiers> is a positive integer but <modifiers> is NULL, the + error EGL_BAD_PARAMETER is generated. + + * If <format> is not one of the formats advertised by + QueryDmaBufFormatsEXT for the same <dpy>, the error EGL_BAD_PARAMETER + is generated. + + +Revision History + +#5 (Daniel Stone, March 12, 2019) + - Correct description of behaviour when a modifier is not explicitly given; + zero is not correct as it is an explicit modifier itself (linear). + +#4 (Daniel Stone, October 20, 2016) + - Switch to EGLuint64KHR for modifier types. + +#3 (Daniel Stone, October 20, 2016) + - Clarify that the effect that modifiers can have. + - Disambiguate references to displays. + - Explicitly refer to max_formats/max_modifiers behaviour when zero. + +#2 (Daniel Stone, September 29, 2016) + - Add missing tokens for plane 3 FD/offset/pitch. + - Fix description. + - Allow max_formats/max_modifiers to be zero, to get the counter. + - Add external_only to modifiers query. + +#1 (Pekka Paalanen, October 14, 2015) + - Initial draft. diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_image_gl_colorspace.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_image_gl_colorspace.txt new file mode 100644 index 0000000..ab53660 --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_image_gl_colorspace.txt @@ -0,0 +1,136 @@ +Name + + EXT_image_gl_colorspace + +Name Strings + + EGL_EXT_image_gl_colorspace + +Contributors + + Jesse Hall, Google + Philip Rideout, Google + Mohan Maiya, Qualcomm + Jan-Harald Fredriksen, ARM + +Contact + + Krzysztof Kosiński, Google (krzysio 'at' google.com) + +Status + + Complete + +Version + + Version 9, February 26, 2018 + +Number + + EGL Extension #125 + +Dependencies + + Written against the EGL 1.5 specification. + + Can be supported on EGL 1.4 provided that EGL_KHR_gl_colorspace is + implemented, as well as either EGL_KHR_image or EGL_KHR_image_base. + + Interacts with the GL_OES_EGL_image_external specification. + +Overview + + This extension relaxes the restriction that only the eglCreate*Surface + functions can accept the EGL_GL_COLORSPACE attribute. With this change, + eglCreateImage can also accept this attribute. + +New Tokens + + EGL_GL_COLORSPACE_DEFAULT_EXT 0x314D + +New Procedures and Functions + + None. + +Additions to the EGL 1.5 Specification + + Add to table 3.11 on page 75: + + "Attribute Type Description + -------------------- ---- ----------- + EGL_GL_COLORSPACE enum Color space for OpenGL and OpenGL ES" + + + Add the following paragraph to the end of section 3.9, "EGLImage + Specification and Management" on page 77: + + "EGL_GL_COLORSPACE specifies the color space used by OpenGL and OpenGL + ES when rendering to the image, or sampling from the image. It has the + same meaning as when used with eglCreatePlatformWindowSurface, with the + exception that its default value is EGL_GL_COLORSPACE_DEFAULT_EXT. This + means that the color space should not be overriden. For example, if an + image is created from an existing OpenGL texture, then + GL_COLORSPACE_DEFAULT_EXT means that the original color space should be + preserved." + + + Add the following paragraphs to the "Errors" subsection in section 3.9 + on page 76: + + "If EGL_GL_COLORSPACE is not one of the legal values, the error + EGL_BAD_PARAMETER is generated." + + "If ctx specifies a GL context that does not support creating an EGLImage + with the given value for EGL_GL_COLORSPACE, EGL_BAD_MATCH error is + generated." + + +Interaction with OES_EGL_image_external: + + The first sentence in the second to last paragraph in section 3.7.14 + should be changed from: + + "Sampling an external texture will return an RGBA vector in the same + colorspace as the source image." + + to: + + "Sampling an external texture will return an RGBA vector in the same color + space as the source image, unless the image's EGL_GL_COLORSPACE attribute + results in sRGB encoding as described in EGL_EXT_image_gl_colorspace." + + The three parenthetical sentences in this same paragraph should be + simplified since they partially conflict with existing language in the + ES30 specification. Change them from: + + "(But these RGB values will be in the same colorspace as the + original image. Colorspace here includes the linear or non-linear + encoding of the samples. For example, if the original image is in the + sRGB color space then the RGB value returned by the sampler will also + be sRGB, and if the original image is stored in ITU-R Rec. 601 YV12 + then the RGB value returned by the sampler will be an RGB value in the + ITU-R Rec. 601 colorspace.)" + + to: + + "(For example, if the original image is stored in ITU-R Rec. 601 YV12 + then the RGB value returned by the sampler will be an RGB value in the + ITU-R Rec. 601 colorspace.)" + + +Issues + +Revision History + + Rev. Date Author Changes + ---- -------- -------- ----------------------------------------- + 1 11/22/17 philip Initial draft + 2 12/8/17 philip Add note about OES_EGL_image_external + 3 12/11/17 philip Changed from KHR to EXT. + 4 12/15/17 philip Add diffs against the EGL 1.5 specification. + 5 12/20/17 philip Add EGL_GL_COLORSPACE_DEFAULT_EXT. + 6 1/2/18 philip Updated changes to OES_EGL_image_external. + 7 1/2/18 philip Tweaked the changes to OES_EGL_image_external. + 8 2/2/18 philip Add value for EGL_GL_COLORSPACE_DEFAULT_EXT. + 9 2/26/18 krzysio Update contact information, finalize. + 9 4/20/18 krzysio Fix stray reference to KHR. diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_image_implicit_sync_control.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_image_implicit_sync_control.txt new file mode 100644 index 0000000..5660e0a --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_image_implicit_sync_control.txt @@ -0,0 +1,131 @@ +Name + + EXT_image_implicit_sync_control + +Name Strings + + EGL_EXT_image_implicit_sync_control + +Contributors + + Daniel Stone, Collabora Ltd. + +Contacts + + Daniel Stone (daniels 'at' collabora 'dot' com) + +Status + + Complete + +Version + + Version 2, March 16, 2020 + +Number + + EGL Extension #120 + +Dependencies + + EGL 1.2 is required. + + EGL_KHR_image_base and EGL_EXT_image_dma_buf_import are required. + + The EGL implementation must be running on a Linux kernel supporting implicit + synchronization, as the usage is defined in the + EGL_ARM_implicit_external_sync extension, but does not require that extension. + + This extension is written against the wording of the EGL 1.2 Specification. + +Overview + + This extension allows a client to selectively use implicit or explicit + synchronization mechanisms when addressing externally-imported EGLImages. + A new token is added to EGLImage creation which allows the client to select + whether a platform's implicit synchronization will be in use for a buffer + imported into EGLImage. + + Heterogeneous systems (supporting multiple APIs, mixed legacy/updated + clients, etc) already supporting implicit synchronization, may not be able + to change to explict synchronization in a single switch. This extension + allows synchronization to be controlled on a per-buffer basis, so explicit + synchronization can be enabled for a complete pipeline which supports it, + or implicit synchronization used otherwise. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted as an attribute in the <attrib_list> parameter of + eglCreateImageKHR: + + EGL_IMPORT_SYNC_TYPE_EXT 0x3470 + + Accepted as the value for the EGL_IMPORT_SYNC_TYPE_EXT attribute: + + EGL_IMPORT_IMPLICIT_SYNC_EXT 0x3471 + EGL_IMPORT_EXPLICIT_SYNC_EXT 0x3472 + +New Types + + None. + +Additions to Chapter 2 of the EGL 1.2 Specification (EGL Operation) + + Add to section 2.5.1 "EGLImage Specification" (as defined by the + EGL_KHR_image_base specification), in the description of + eglCreateImageKHR: + + Add the following to Table bbb (Legal attributes for eglCreateImageKHR + <attr_list> parameter), Section 2.5.1 (EGLImage Specification) + + +-----------------------------+-------------------------+---------------------------+---------------+ + | Attribute | Description | Valid <target>s | Default Value | + +-----------------------------+-------------------------+---------------------------+---------------+ + | EGL_IMPORT_SYNC_TYPE_EXT | The type of | EGL_LINUX_DMA_BUF_EXT | EGL_IMPORT_ | + | | synchronization to | | IMPLICT_SYNC_ | + | | apply to previously | | EXT | + | | submitted rendering on | | | + | | the platform buffer | | | + +-----------------------------+-------------------------+---------------------------+---------------+ + Table bbb. Legal attributes for eglCreateImageKHR <attrib_list> parameter + + ... + + + Add to section 2.5.1 "EGLImage Specification" (as defined by the + EGL_KHR_image_base specification), in the description of + eglCreateImageKHR: + + The behaviour of the imported buffer with regard to commands previously + submitted (including via other APIs and from other clients) is controlled + by the EGL_IMPORT_SYNC_TYPE_EXT attribute. If the default value of + implicit synchronization is used, the platform may synchronize any access + to the imported buffer, against accesses previously made (including by + other clients or APIs) to that same buffer. If explicit synchronization + is specified, the platform will not synchronize access to that buffer + against other accesses; the client must use another synchronization + mechanism if it wishes to order its accesses with respect to others. + + Add to the list of error conditions for eglCreateImageKHR: + + * If <attrib_list> contains the EGL_IMPORT_SYNC_TYPE_EXT name, but the + value is not one of EGL_IMPORT_IMPLICIT_SYNC_EXT or + EGL_IMPORT_EXPLICIT_SYNC_EXT, EGL_BAD_ATTRIBUTE is generated. + + +Revision History + +#1 (Daniel Stone, May 15, 2017) + - Initial revision. + +#2 (Eric Engestrom, March 16, 2020) + - Change "bad attribute value" error from EGL_BAD_PARAMETER to + EGL_BAD_ATTRIBUTE to follow the EGL convention. diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_multiview_window.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_multiview_window.txt new file mode 100644 index 0000000..9cf0ff6 --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_multiview_window.txt @@ -0,0 +1,126 @@ +Name + + EXT_multiview_window + +Name Strings + + EGL_EXT_multiview_window + +Contributors + + Acorn Pooley + Greg Roth + +Contacts + + Greg Roth (groth 'at' nvidia.com) + +Status + + Complete + +Version + + Version 3, Sept 03, 2011 + +Number + + EGL Extension #42 + +Dependencies + + Requires EGL 1.4 + + Written against the EGL 1.4 specification. + +Overview + + Adds support for creating an onscreen EGLSurface containing + multiple color buffers. + + EXT_multi_draw_buffers can be used with this extension to + render and display multiple color buffers to a supported + device. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted as an attribute in the <attrib_list> parameter of + CreateWindowSurface: + + EGL_MULTIVIEW_VIEW_COUNT_EXT 0x3134 + +Additions to Chapter 3 of the EGL 1.2 Specification: + + Additions to section 3.5.1 (Creating On-Screen Rendering Surfaces) + + Alter the end of the second paragraph: + + Attributes that can be specified in <attrib_list> include + EGL_RENDER_BUFFER, EGL_VG_COLORSPACE, EGL_VG_ALPHA_FORMAT, and + EGL_MULTIVIEW_VIEW_COUNT_EXT. + + Add before the last paragraph of section 3.5.1: + + EGL_MULTIVIEW_VIEW_COUNT_EXT specifies how many multiview color + buffers should be created for the surface. Each color buffer has + the same properties as the primary color buffer as specified by + window and surface attributes. The default value of + EGL_MULTIVIEW_VIEW_COUNT_EXT is one. + + EGL may not be able to create as many multiview color buffers as + EGL_MULTIVIEW_VIEW_COUNT_EXT specifies. To determine the number + of multiview color buffers created by a context, call + eglQueryContext (see section 3.7.4). + + Add to the last paragraph of section 3.5.1: + + If the value specified for EGL_MULTIVIEW_VIEW_COUNT_EXT is less + than one, an EGL_BAD_PARAMETER error is generated. If the value + specified for EGL_MULTIVIEW_VIEW_COUNT_EXT is greater than one + and the <config> does not support multiple multiview color + buffers, an EGL_BAD_MATCH error is generated. + + Additions to section 3.5.6 (Surface Attributes) + + Add to table 3.5, "Queryable surface attributes and types" + + Attribute Type Description + --------- ---- ----------- + EGL_MULTIVIEW_VIEW_COUNT_EXT integer Requested multiview + color buffers + + Add before the last paragraph describing eglQuerySurface: + + Querying EGL_MULTIVIEW_VIEW_COUNT_EXT for a window surface + returns the number of multiview color buffers requested. For a + pbuffer or pixmap surface, the contents of <value> are not + modified. To determine the actual number of multiview color + buffers created by a context, call eglQueryContext (see + section 3.7.4). + + + Additions to section 3.7.4 (Context Queries) + + Add before the last paragraph describing eglQueryContext: + + Querying EGL_MULTIVIEW_VIEW_COUNT_EXT returns the number of + multiview color buffers created. The value returned depends on + properties of both the context, and the surface to which the + context is bound. + +Issues + + None + +Revision History + Version 3, 03 Sept 2011 EXTify add support for multiple or single depth buffer. + Version 2, 02 Aug 2011 Responses to feedback. + Version 1, 14 April 2011 First draft. diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_output_base.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_output_base.txt new file mode 100644 index 0000000..1cbd112 --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_output_base.txt @@ -0,0 +1,564 @@ +Name + + EXT_output_base + +Name Strings + + EGL_EXT_output_base + +Contributors + + Daniel Kartch + James Jones + Christopher James Halse Rogers + +Contacts + + Daniel Kartch, NVIDIA (dkartch 'at' nvidia.com) + +Status + + Complete + +Version + + Version 9 - August 22, 2014 + +Number + + EGL Extension #78 + +Extension Type + + EGL display extension + +Dependencies + + Written against the wording of EGL 1.5, plus the EGL_EXT_device_base + specification. + + Requires EGL_EXT_device_base + +Overview + + Increasingly, EGL and its client APIs are being used in place of + "native" rendering APIs to implement the basic graphics + functionality of native windowing systems. This creates demand + for a method to initialize EGL displays and surfaces directly on + top of native GPU or device objects rather than native window + system objects. The mechanics of enumerating the underlying + native devices and constructing EGL displays and surfaces from + them have been solved in various platform and implementation- + specific ways. The EGL device family of extensions offers a + standardized framework for bootstrapping EGL without the use of + any underlying "native" APIs or functionality. + + This extension defines new EGL resource types for referencing + display control hardware associated with an EGL device. Its purpose + is to allow rendering to be directed to a screen in the absence of + (or bypassing) a window system. Because the use models for these + resources are potentially diverse, only the objects themselves and + basic functions to acquire and query them are defined here. More + detailed functions and enumerants required to operate on outputs + are provided by separate extensions. + +New Types + + A handle representing a portion of display control hardware which + accepts a single image as input and processes it for output on a + display device: + + typedef void* EGLOutputLayerEXT; + + A handle representing a portion of display control hardware which + transmits a signal to a display device: + + typedef void* EGLOutputPortEXT; + +New Functions + + EGLBoolean eglGetOutputLayersEXT( + EGLDisplay dpy, + const EGLAttrib *attrib_list, + EGLOutputLayerEXT *layers, + EGLint max_layers, + EGLint *num_layers); + + EGLBoolean eglGetOutputPortsEXT( + EGLDisplay dpy, + const EGLAttrib *attrib_list, + EGLOutputPortEXT *ports, + EGLint max_ports, + EGLint *num_ports); + + EGLBoolean eglOutputLayerAttribEXT( + EGLDisplay dpy, + EGLOutputLayerEXT layer, + EGLint attribute, + EGLAttrib value); + + EGLBoolean eglQueryOutputLayerAttribEXT( + EGLDisplay dpy, + EGLOutputLayerEXT layer, + EGLint attribute, + EGLAttrib *value); + + const char* eglQueryOutputLayerStringEXT( + EGLDisplay dpy, + EGLOutputLayerEXT layer, + EGLint name); + + EGLBoolean eglOutputPortAttribEXT( + EGLDisplay dpy, + EGLOutputPortEXT port, + EGLint attribute, + EGLAttrib value); + + EGLBoolean eglQueryOutputPortAttribEXT( + EGLDisplay dpy, + EGLOutputPortEXT port, + EGLint attribute, + EGLAttrib *value); + + const char* eglQueryOutputPortStringEXT( + EGLDisplay dpy, + EGLOutputPortEXT port, + EGLint name); + +New Tokens + + Functions with a return type of EGLOutputLayerEXT will return this + value on failure: + + EGL_NO_OUTPUT_LAYER_EXT ((EGLOutputLayerEXT)0) + + Functions with a return type of EGLOutputPortEXT will return this + value on failure: + + EGL_NO_OUTPUT_PORT_EXT ((EGLOutputPortEXT)0) + + Functions which fail due to a bad EGLOutputLayerEXT handle will set + this error code: + + EGL_BAD_OUTPUT_LAYER_EXT 0x322D + + Functions which fail due to a bad EGLOutputPortEXT handle will set + this error code: + + EGL_BAD_OUTPUT_PORT_EXT 0x322E + + Functions which set or query the swap interval use this attribute + name: + + EGL_SWAP_INTERVAL_EXT 0x322F + +Add a new section "2.1.4 Outputs" after "2.1.3 Displays": + + An EGLDisplay may have zero or more associated EGLOutputLayerEXT + and EGLOutputPortEXT objects. These represent, respectively, the + inputs and outputs of display control hardware. + + An EGLOutputLayerEXT is an abstract handle representing an element + of display control hardware which receives image data and processes + it for display. This processing is hardware-dependent, and may + include, but is not limited to, color space transformation, scaling + and rotation, and composition/blending with images from other + EGLOutputLayerEXTs. + + An EGLOutputPortEXT is an abstract handle representing an element of + display control hardware which sends a signal to drive a display + screen. In general, this signal is the result of the processing of + one or more EGLOutputLayerEXTs. + +Add new entries to section "3.1 Errors": + + EGL_BAD_OUTPUT_LAYER_EXT + An EGLOutputLayerEXT argument does not name a valid + EGLOutputLayerEXT. Any command taking an EGLOutputLayerEXT + parameter may generate this error. + + EGL_BAD_OUTPUT_PORT_EXT + An EGLOutputPortEXT argument does not name a valid + EGLOutputPortEXT. Any command taking an EGLOutputPortEXT + parameter may generate this error. + +Add a new section "3.10 Device Outputs" after "3.9 Posting the Color Buffer": + + 3.10 Device Outputs + + A simple platform running a custom software suite may not require a + formal window system. Instead, individual applications or a + compositor may send rendering results directly to display control + hardware, represented by EGLOutputLayerEXT and EGLOutputPortEXT + handles. + + As with other EGL resources, EGLOutputLayerEXT and EGLOutputPortEXT + handles are owned by an EGLDisplay, but not all EGLDisplays are + required to support these objects. In general, they will only be + available for EGLDisplays obtained from platforms which allow direct + manipulation of display devices. + + 3.10.1 Acquiring Outputs + + To obtain EGLOutputLayerEXT handles associated with a display which + match a list of attributes, use + + EGLBoolean eglGetOutputLayersEXT( + EGLDisplay dpy, + const EGLAttrib *attrib_list, + EGLOutputLayerEXT *layers, + EGLint max_layers, + EGLint *num_layers) + + On success, EGL_TRUE is returned. If <layers> is NULL, <max_layers> + is ignored and the number of output layers which match <attrib_list> + is returned in <num_layers>. Otherwise, up to <max_layers> matching + layers will be returned in <layers> and <num_layers> will be set to + the number of layer handles returned. The states of the output + layers are not altered by this query, and output layer handles can + be retrieved by multiple calls to this function. + + <attrib_list> may be NULL or a list of name/value pairs terminated + by EGL_NONE. If no attributes are provided, all output layers + associated with <dpy> will match. Otherwise, only those layers + matching all attributes provided in the list will be returned, + unless the value specified is EGL_DONT_CARE. If there are no + matching layers but all parameters are otherwise valid, success is + returned but num_layers is set to 0. + + On failure, EGL_FALSE will be returned and the memory referenced by + <layers> and <num_layers> will be unaffected. If <dpy> is not a + valid, initialized EGLDisplay, an EGL_BAD_DISPLAY error is + generated. If any name in <attrib_list> is not a valid layer + attribute name defined in Table 3.10.3.1, an EGL_BAD_ATTRIBUTE error + is generated. If any name in <attrib_list> does not allow search + access, an EGL_BAD_ACCESS error is generated. + + To obtain EGLOutputPortEXT handles associated with a display which + match a list of attributes, use + + EGLBoolean eglGetOutputPortsEXT( + EGLDisplay dpy, + const EGLAttrib *attrib_list, + EGLOutputPortEXT *ports, + EGLint max_ports, + EGLint *num_ports) + + On success, EGL_TRUE is returned. If <ports> is NULL, <max_ports> is + ignored and the number of output ports which match <attrib_list> is + returned in <num_ports>. Otherwise, up to <max_ports> matching + layers will be returned in <ports> and <num_ports> will be set to + the number of port handles returned. The states of the output ports + are not altered by this query, and output port handles can be + retrieved by multiple calls to this function. + + <attrib_list> may be NULL or a list of name/value pairs terminated + by EGL_NONE. If no attributes are provided, all output ports + associated with <dpy> will match. Otherwise, only those ports + matching all attributes provided in the list will be returned, + unless the value specified is EGL_DONT_CARE. If there are no + matching ports but all parameters are otherwise valid, success is + returned but num_ports is set to 0. + + On failure, EGL_FALSE will be returned and the memory referenced by + <ports> and <num_ports> will be unaffected. If <dpy> is not a valid, + initialized EGLDisplay, an EGL_BAD_DISPLAY error is generated. If + any name in <attrib_list> is not a valid port attribute name defined + in Table 3.10.3.2, an EGL_BAD_ATTRIBUTE error is generated. If any + name in <attrib_list> does not allow search access, an + EGL_BAD_ACCESS error is generated. + + 3.10.2 Lifetime of Output Handles + + An initialized EGLDisplay has a fixed set of output layer and port + resources available. Implementations may defer creation of handles + and allocation of data structions for these objects until they are + first requested. However, once acquired, they remain valid as long + as the EGLDisplay is not terminated. + + 3.10.3 Output Attributes + + Valid attributes associated with output layers and ports are listed + in Tables 3.10.3.1 and 3.10.3.2, respectively. Additional attributes + may be defined by other extensions. The Access columns contain one + or more of the letters "S", "R", and W". A value of "S" indicates + the attribute may be used to restrict the search when obtaining a + list of output handles. A value of "R" indicates the value may be + queried from an output handle. A value of "W" indicates the value + may be modified using an output handle. + + Attribute Type Access + --------------------- ------- ------ + EGL_SWAP_INTERVAL_EXT integer R|W + EGL_MIN_SWAP_INTERVAL integer R + EGL_MAX_SWAP_INTERVAL integer R + + Table 3.10.3.1 Output layer attributes + + Attribute Type Access + --------------------- ------- ------ + [no attributes supported] + + Table 3.10.3.2 Output port attributes + + 3.10.3.1 Querying Output Attributes + + To query attributes of an EGLOutputLayerEXT, use + + EGLBoolean eglQueryOutputLayerAttribEXT( + EGLDisplay dpy, + EGLOutputLayerEXT layer, + EGLint attribute, + EGLAttrib *value) + + On success, this function returns EGL_TRUE and stores the value of + <attribute> in <value>. + + On failure, EGL_FALSE is returned. If <dpy> is not a valid, + initialized EGLDisplay, an EGL_BAD_DISPLAY error is generated. If + <layer> is not a valid EGLOutputLayerEXT associated with <dpy>, an + EGL_BAD_OUTPUT_LAYER_EXT error is generated. If <attribute> is not a + valid layer attribute name defined in Table 3.10.3.1, an + EGL_BAD_ATTRIBUTE error is generated. If <attribute> has string + type or does not allow read access, an EGL_BAD_ACCESS error is + generated. + + To query string properties of an EGLOutputLayerEXT, use + + const char* eglQueryOutputLayerStringEXT( + EGLDisplay dpy, + EGLOutputLayerEXT layer, + EGLint attribute) + + On success, this function returns a zero-terminated string + containing the value associated with <name>. + + On failure, NULL is returned. If <dpy> is not a valid, initialized + EGLDisplay, an EGL_BAD_DISPLAY error is generated. If <layer> is not + a valid EGLOutputLayerEXT associated with <dpy>, an + EGL_BAD_OUTPUT_LAYER_EXT error is generated. If <name> is not a + valid layer attribute name defined in Table 3.10.3.1, an + EGL_BAD_ATTRIBUTE error is generated. If <attribute> has non-string + type or does not allow read access, an EGL_BAD_ACCESS error is + generated. + + To query attributes of an EGLOutputPortEXT, use + + EGLBoolean eglQueryOutputPortAttribEXT( + EGLDisplay dpy, + EGLOutputPortEXT port, + EGLint attribute, + EGLAttrib *value) + + On success, this function returns EGL_TRUE and stores the value of + <attribute> in <value>. + + On failure, EGL_FALSE is returned. If <dpy> is not a valid, + initialized EGLDisplay, an EGL_BAD_DISPLAY error is generated. If + <port> is not a valid EGLOutputPortEXT associated with <dpy>, an + EGL_BAD_OUTPUT_PORT_EXT error is generated. If <attribute> is not a + valid port attribute name defined in Table 3.10.3.2, an + EGL_BAD_ATTRIBUTE error is generated. If <attribute> has string + type or does not allow read access, an EGL_BAD_ACCESS error is + generated. + + To query string properties of an EGLOutputPortEXT, use + + const char* eglQueryOutputPortStringEXT( + EGLDisplay dpy, + EGLOutputPortEXT port, + EGLint attribute) + + On success, this function returns a zero-terminated string + containing the value associated with <name>. + + On failure, NULL is returned. If <dpy> is not a valid, initialized + EGLDisplay, an EGL_BAD_DISPLAY error is generated. If <port> is not + a valid EGLOutputPortEXT associated with <dpy>, an + EGL_BAD_OUTPUT_PORT_EXT error is generated. If <name> is not a + valid port attribute name defined in Table 3.10.3.2, an + EGL_BAD_ATTRIBUTE error is generated. If <attribute> has non-string + type or does not allow read access, an EGL_BAD_ACCESS error is + generated. + + 3.10.3.2 Setting Output Attributes + + To set attributes of an EGLOutputLayerEXT, use + + EGLBoolean eglOutputLayerAttribEXT( + EGLDisplay dpy, + EGLOutputLayerEXT layer, + EGLint attribute, + EGLAttrib value) + + On success, this function returns EGL_TRUE and sets the value of + <attribute> to <value>. + + If <attribute> is EGL_SWAP_INTERVAL_EXT, the value provided will be + silently clamped to the range specified by the layer's + EGL_MIN_SWAP_INTERVAL and EGL_MAX_SWAP_INTERVAL values. + + On failure, EGL_FALSE is returned. If <dpy> is not a valid, + initialized EGLDisplay, an EGL_BAD_DISPLAY error is generated. If + <layer> is not a valid EGLOutputLayerEXT associated with <dpy>, an + EGL_BAD_OUTPUT_LAYER_EXT error is generated. If <attribute> is not a + valid layer attribute name defined in Table 3.10.3.1, an + EGL_BAD_ATTRIBUTE error is generated. If <attribute> does not + allow write access, an EGL_BAD_ACCESS error is generated. + + To set attributes of an EGLOutputPortEXT, use + + EGLBoolean eglOutputPortAttribEXT( + EGLDisplay dpy, + EGLOutputPortEXT port, + EGLint attribute, + EGLAttrib value) + + On success, this function returns EGL_TRUE and sets the value of + <attribute> to <value>. + + On failure, EGL_FALSE is returned. If <dpy> is not a valid, + initialized EGLDisplay, an EGL_BAD_DISPLAY error is generated. If + <port> is not a valid EGLOutputPortEXT associated with <dpy>, an + EGL_BAD_OUTPUT_PORT_EXT error is generated. If <attribute> is not a + valid port attribute name defined in Table 3.10.3.2, an + EGL_BAD_ATTRIBUTE error is generated. If <attribute> does not + allow write access, an EGL_BAD_ACCESS error is generated. + + 3.10.4 Setting Output Modes + + EGL does not currently define any mechanims to adjust display + modes through EGLOutputPortEXTs. These may be added via additional + extensions. + + 3.10.5 Posting to Outputs + + EGL does not currently define any mechanisms to post rendering + results to EGLOutputsLayerEXTs. These may be added via additional + extensions. However, unless otherwise specified, such mechanims + will respect the layer's EGL_SWAP_INTERVAL_EXT value, which + specifies the minimum number of video frame periods for which the + frames should be displayed, in a manner analogous to using + eglSwapInterval for the current draw surface. The default value of + EGL_SWAP_INTERVAL_EXT is 1, clamped to the layer's + EGL_MIN_SWAP_INTERVAL and EGL_MAX_SWAP_INTERVAL values. + + (Example: See extension specification + EGL_EXT_stream_consumer_egloutput) + +Issues + + 1. Should this extension provide a mechanism to enumerate outputs + associated with an EGLDevice and set their modes? + + RESOLVED: No. On many operating systems there already exist + standardized and/or widely accepted low level mechanisms for + performing these tasks. Duplicating this support in EGL would + impose an undesirable implementation burden where output handles + are only required as a means to direct rendering to a display + screen. Functions for enumerating screens or obtaining them from + platform-dependent representations will be provided by other + extensions. + + 2. Should output layer and port handles be associated with an + EGLDisplay, or vice versa? + + RESOLVED: Yes. Furthermore, it may only be possible to obtain + output handles from some EGLDisplays. The primary intended use + case is the EGLDisplay associated with an EGLDevice, through the + platform defined by EGL_EXT_platform_device. This represents raw + device access available in the absence of a window system. + EGLDisplays associated with other platforms typically represent + handles provided by window systems, which may not allow direct + access to the display control hardware. + + 3. Can the EGLDeviceEXT handle be returned by a query function + which returns integer attributes? + + RESOLVED: Yes. Function definition has been updated to use + EGLAttribEXT, which is compatible with EGL handles. + + 4. What display mode properties should be queriable by the base + extension? Does the application require width/height/refresh or + should those be left to other mechanisms or additional + extensions? If hardware supports selecting a portion of the + image for display, or restricting an image to a portion of the + screen, or scaling an image to a different resolution for + display, should all these settings be queriable? + + RESOLVED: The base extension will not define any display + properties. These will be left to future extensions if required. + + 5. How should stereo/multiview displays be handled? Should all + views share a single output or does each one have its own? + + UNRESOLVED. Left for a future extension to define. + + 6. This extension is currently focused on individual display layers + for the purpose of directing rendering output. An API covering + all hardware would associate one or more of those layers with a + display port. Do we need to abstract both? + + RESOLVED: Yes. Extension has been modified to abstract both + inputs (layers) and outputs (ports) of display control hardware. + An implementation is not required to return any ports in the + query function if it provides no means to operate on them. + +Revision History: + + #9 (August 22nd, 2014) James Jones + - Marked complete. + - Added minor coments to issue 5. + - Listed Daniel as the contact. + + #8 (June 10th, 2014) Daniel Kartch + - Fixed prototypes for layer/port attribute setting functions. + + #7 (June 5th, 2014) Daniel Kartch + - Assigned enumerated values for constants. + - Indicated default swap interval value. + + #6 (May 28th, 2014) Daniel Kartch + - Updated wording based on EGL 1.5 specification, using + EGLAttrib instead of EGLAttribEXT. + - Added functions to set layer and port attributes. + - Added table of valid attributes, with min/max/current swap + interval values, and adjusted function descriptions + accordingly. + - Refined description for output enumeration functions to better + indicate the effect of attribute list. + - Added effect of swap interval in posting section. + + #5 (January 31st, 2014) Daniel Kartch + - Added eglGetOutput* functions, folding in and generalizing + functionality previously provided by EXT_native_output + extension. + - Separated descriptions for layer and port query functions for + clarity. + + #4 (January 22nd, 2014) Daniel Kartch + - Added section clarifying that this extension provides no means + to use output ports to set display modes, but future + extensions may. + + #3 (January 17th, 2014) Daniel Kartch + - Updated names of example extension for obtaining and using + output handles. + - Fixed typos. + + #2 (November 12th, 2013) Daniel Kartch + - Replaced EGLOutput with EGLOutputLayer and added + EGLOutputPort (and modified/added corresponding functions), to + allow both inputs and outputs of display control hardware to + be abstracted. + - Modified attribute query functions to use EGLAttribEXT and + added string query functions. + - Removed display mode attributes. These can be defined by a + separate extension if desired. + - Removed destructor function for outputs and added section on + lifetime, as well as language describing their relationship to + EGLDisplays. + + #1 (October 25nd, 2013) Daniel Kartch + - Initial draft + diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_pixel_format_float.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_pixel_format_float.txt new file mode 100644 index 0000000..a14adcb --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_pixel_format_float.txt @@ -0,0 +1,136 @@ +Name + + EXT_pixel_format_float + +Name Strings + + EGL_EXT_pixel_format_float + +Contributors + + Tom Cooksey + Jesse Hall + Mathias Heyer + Adam Jackson + James Jones + Daniel Koch + Jeff Leger + Weiwan Liu + Jeff Vigil + +Contact + + Weiwan Liu, NVIDIA (weiwliu 'at' nvidia.com) + +Status + + Complete + +Version + + Version 4 - Nov 22, 2016 + +Number + + EGL Extension #106 + +Dependencies + + This extension is written against the wording of the EGL 1.5 specification + (August 27, 2014). + +Overview + + This extensions aims to provide similar functionality as GL_ARB_color_- + buffer_float, WGL_ARB_pixel_format_float and GLX_ARB_fbconfig_float. This + extension allows exposing new EGLConfigs that support formats with + floating-point RGBA components. This is done by introducing a new EGLConfig + attribute that represents the component type, i.e. fixed-point or + floating-point. Such new EGLConfigs can be used to create floating-point + rendering surfaces and contexts. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted as an attribute name in the <attrib_list> argument of + eglChooseConfig, and the <attribute> argument of eglGetConfigAttrib: + + EGL_COLOR_COMPONENT_TYPE_EXT 0x3339 + + Accepted as attribute values for the EGL_COLOR_COMPONENT_TYPE_EXT attribute + of eglChooseConfig: + + EGL_COLOR_COMPONENT_TYPE_FIXED_EXT 0x333A + EGL_COLOR_COMPONENT_TYPE_FLOAT_EXT 0x333B + + Additions to table 3.1, "EGLConfig attributes" in Section 3.4 "Configuration + Management": + + Attribute Type Notes + --------- ---- --------- + EGL_COLOR_COMPONENT_TYPE_EXT enum color component type + + Append one paragraph at the end of "The Color Buffer" section on page 21: + + EGL_COLOR_COMPONENT_TYPE_EXT indicates the color buffer component type, + and must be either EGL_COLOR_COMPONENT_TYPE_FIXED_EXT for fixed-point + color buffers, or EGL_COLOR_COMPONENT_TYPE_FLOAT_EXT for floating-point + color buffers. + + Add one entry to Table 3.4 and increment "Sort Priority" between "2" and + "11" by one for existing entries: + + Attribute Default + ----------- ------------ + EGL_COLOR_COMPONENT_TYPE_EXT EGL_COLOR_COMPONENT_TYPE_FIXED_EXT + + Selection Criteria Sort Order Priority + ------------------ ---------- -------- + Exact Special 2 + + Insert before the entry for EGL_COLOR_BUFFER_TYPE, and increment its + numbering and subsequent numbering by one: + + 2. Special: by EGL_COLOR_COMPONENT_TYPE_EXT where the precedence is + EGL_COLOR_COMPONENT_TYPE_FIXED_EXT, EGL_COLOR_COMPONENT_TYPE_FLOAT_EXT + + Change footnote 8 on page 30 to: + + Within the same EGL_COLOR_COMPONENT_TYPE_EXT, this rule places configs + with deeper color buffers first in the list returned by + eglChooseConfig... + +Issues + + 1. When reading from or rendering to a floating-point EGL surface, is there + any clamping performed on the values? + + RESOLVED: It depends on the behavior of the client API. For example, in + OpenGL and ES, by default no clamping will be done on the floating-point + values, unless the clamping behavior is changed via the client API. + + 2. When rendering to a floating-point EGL surface, since values may not be + clamped to [0, 1], what is the range of values that applications can use + to get display's "darkest black" and "brightest white"? + + RESOLVED: It is not in the scope of this extension to define a range of + values that corresponds to display's capability. Please refer to the EGL + specification for the chosen colorspace (EGL_GL_COLORSPACE), where such a + reference range may be defined. + +Revision History + + Rev. Date Author Changes + ---- -------- --------------- ------------------------------------------ + 1 12/11/15 Weiwan Liu Initial version + 2 05/18/16 Weiwan Liu Rename to EXT + 3 05/31/16 Weiwan Liu Add issues + 4 11/22/16 Weiwan Liu Change status to complete + diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_base.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_base.txt new file mode 100644 index 0000000..80bd1bc --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_base.txt @@ -0,0 +1,371 @@ +Name + + EXT_platform_base + +Name Strings + + EGL_EXT_platform_base + +Contributors + + Chad Versace <chad.versace@intel.com> + James Jones <jajones@nvidia.com> + +Contacts + + Chad Versace <chad.versace@intel.com> + +Status + + Complete + +Version + + Version 9, 2014.01.09 + +Number + + EGL Extension #57 + +Extension Type + + EGL client extension + +Dependencies + + Requires EGL 1.4. + + Requires EGL_EXT_client_extensions to query its existence without + a display. + + This extension is written against the wording of the 2013.02.11 revision + of the EGL 1.4 Specification. + +Overview + + This extension defines functionality and behavior for EGL implementations + that support multiple platforms at runtime. For example, on Linux an EGL + implementation could support X11, Wayland, GBM (Generic Buffer Manager), + Surface Flinger, and perhaps other platforms. + + In particular, this extension defines the following: + + 1. A mechanism by which an EGL client can detect which platforms the + EGL implementation supports. + + 2. New functions that enable an EGL client to specify to which + platform a native resource belongs when creating an EGL resource + from that native resource. For example, this extension enables an + EGL client to specify, when creating an EGLSurface from a native + window, that the window belongs to X11. + + 3. That an EGL client is not restricted to interacting with a single + platform per process. A client process can create and manage EGL + resources from multiple platforms. + + The generic term 'platform' is used throughout this extension + specification rather than 'window system' because not all EGL platforms + are window systems. In particular, those platforms that allow headless + rendering without a display server, such as GBM, are not window systems. + + This extension does not specify behavior specific to any platform, nor + does it specify the set of platforms that an EGL implementation may + support. Platform-specific details lie outside this extension's scope and + are instead described by extensions layered atop this one. + +New Types + + None + +New Procedures and Functions + + EGLDisplay eglGetPlatformDisplayEXT( + EGLenum platform, + void *native_display, + const EGLint *attrib_list); + + EGLSurface eglCreatePlatformWindowSurfaceEXT( + EGLDisplay dpy, + EGLConfig config, + void *native_window, + const EGLint *attrib_list); + + EGLSurface eglCreatePlatformPixmapSurfaceEXT( + EGLDisplay dpy, + EGLConfig config, + void *native_pixmap, + const EGLint *attrib_list); + +New Tokens + + None + +Additions to the EGL 1.4 Specification + + Replace each occurence of the term "window system" with "platform". The + rationale behind this change is that not all platforms are window systems, + yet the EGL 1.4 specification uses the two terms interchangeably. In + particular, platforms that allow headless rendering without a display + server, such as GBM, are not window systems. + + Append the following paragraph to the initial, unnamed subsection of + section 2.1 "Native Window System and Rendering APIs". + + "This specification does not define the set of platforms that may be + supported by the EGL implementation, nor does it specify behavior specific + to any platform. The set of supported platforms and their behavior is + defined by extensions. To detect if a particular platform is supported, + clients should query the EGL_EXTENSIONS string of EGL_NO_DISPLAY using + eglQueryString. + + Replace the text of section 3.2 "Initialization", from the start of the + section and up to and excluding the phrase "EGL may be intialized on + a display", with the following: + + "A display can be obtained by calling + + EGLDisplay eglGetPlatformDisplayEXT( + EGLenum platform, + void *native_display, + const EGLint *attrib_list); + + EGL considers the returned EGLDisplay as belonging to the native platform + specified by <platform>. This specification defines no valid value for + <platform>. Any specification that does define a valid value for + <platform> will also define requirements for the <native_display> + parameter. For example, an extension specification that defines support + for the X11 platform may require that <native_display> be a pointer to an + X11 Display, and an extension specification that defines support for the + Microsoft Windows platform may require that <native_display> be a pointer + to a Windows Device Context. + + All attribute names in <attrib_list> are immediately followed by the + corresponding desired value. The list is terminated with EGL_NONE. The + <attrib_list> is considered empty if either <attrib_list> is NULL or if + its first element is EGL_NONE. This specification defines no valid + attribute names for <attrib_list>. + + Multiple calls made to eglGetPlatformDisplayEXT with the same <platform> + and <native_display> will return the same EGLDisplay handle. + + An EGL_BAD_PARAMETER error is generated if <platform> has an invalid value. + If <platform> is valid but no display matching <native_display> is + available, then EGL_NO_DISPLAY is returned; no error condition is raised + in this case. + + A display can also be obtained by calling + + EGLDisplay eglGetDisplay(EGLNativeDisplayType display_id); + + The behavior of eglGetDisplay is similar to that of + eglGetPlatformDisplayEXT, but is specifided in terms of implementation- + specific behavior rather than platform-specific extensions. + As for eglGetPlatformDisplayEXT, EGL considers the returned EGLDisplay + as belonging to the same platform as <display_id>. However, the set of + platforms to which <display_id> is permitted to belong, as well as the + actual type of <display_id>, are implementation-specific. If <display_id> + is EGL_DEFAULT_DISPLAY, a default display is returned. Multiple calls + made to eglGetDisplay with the same <display_id> will return the same + EGLDisplay handle. If no display matching <display_id> is available, + EGL_NO_DISPLAY is returned; no error condition is raised in this case." + + In section 3.5.1 "Creating On-Screen Rendering Surfaces", replace the + second paragraph, which begins with "Using the platform-specific type" and + ends with "render into this surface", with the following: + + "Then call + + EGLSurface eglCreatePlatformWindowSurfaceEXT( + EGLDisplay dpy, + EGLConfig config, + void *native_window, + const EGLint *attrib_list); + + eglCreatePlatformWindowSurfaceEXT creates an onscreen EGLSurface and + returns a handle to it. Any EGL context created with a compatible + EGLConfig can be used to render into this surface. + + <native_window> must belong to the same platform as <dpy>, and EGL + considers the returned EGLSurface as belonging to that same platform. The + extension that defines the platform to which <dpy> belongs also defines + the requirements for the <native_window> parameter." + + In the remainder of section 3.5.1, replace each occurrence of + 'eglCreateWindowSurface' with 'eglCreatePlatformWindowSurfaceEXT'. + + Insert the sentence below after the first sentence of the last paragraph + of section 3.5.1: + + "If <dpy> and <native_window> do not belong to the same platform, then + undefined behavior occurs. [1]" + + Add the following footnote to section 3.5.1: + + "[1] See section 3.1.0.2 "Parameter Validation". + + Append the following to section 3.5.1: + + "An on-screen rendering surface may also be created by calling + + EGLSurface eglCreateWindowSurface( + EGLDisplay dpy, + EGLConfig config, + EGLNativeWindowType win, + const EGLint *attrib_list); + + The behavior of eglCreateWindowSurface is identical to that of + eglCreatePlatformWindowSurfaceEXT except that the set of platforms to + which <dpy> is permitted to belong, as well as the actual type of <win>, + are implementation specific. + + In section 3.5.4 "Creating Native Pixmap Rendering Surfaces", replace the + third paragraph, which begins with "Using the platform-specific type" and + ends with "render into this surface", with the following: + + "Then call + + EGLSurface eglCreatePlatformPixmapSurfaceEXT( + EGLDisplay dpy, + EGLConfig config, + void *native_pixmap, + const EGLint *attrib_list); + + eglCreatePlatformPixmapSurfaceEXT creates an offscreen EGLSurface and + returns a handle to it. Any EGL context created with a compatible + EGLConfig can be used to render into this surface. + + <native_pixmap> must belong to the same platform as <dpy>, and EGL + considers the returned EGLSurface as belonging to that same platform. The + extension that defines the platform to which <dpy> belongs also defines + the requirements for the <native_pixmap> parameter." + + In the remainder of section 3.5.4, replace each occurrence of + 'eglCreatePixmapSurface' with 'eglCreatePlatformPixmapSurfaceEXT' and each + occurence of 'eglCreateWindowSurface' with + 'eglCreatePlatformWindowSurfaceEXT'. + + Insert the sentence below after the first sentence of the last paragraph + of section 3.5.4: + + "If <dpy> and <native_pixmap> do not belong to the same platform, then + undefined behavior occurs. [1]" + + Add the following footnote to section 3.5.3: + + "[1] See section 3.1.0.2 "Parameter Validation". + + Append the following to section 3.5.2: + + "An offscreen rendering surface may also be created by calling + + EGLSurface eglCreatePixmapSurface( + EGLDisplay dpy, + EGLConfig config, + EGLNativePixmapType pixmap, + const EGLint *attrib_list); + + The behavior of eglCreatePixmapSurface is identical to that of + eglCreatePlatformPixmapSurfaceEXT except that the set of platforms to + which <dpy> is permitted to belong, as well as the actual type of + <pixmap>, are implementation specific. + +Issues + + 1. What rules define how EGL resources are shared among displays belonging + to different platforms? + + RESOLVED: Neither the EGL 1.4 specification nor any extension allow EGL + resources to be shared among displays. This extension does not remove + that restriction. + + 2. Rather than define the new function eglGetPlatformDisplayEXT(), should + this extension instead define new thread-local state for the currently + bound platform and an associated binding function, such as + eglBindPlatformEXT()? + + RESOLVED: No, for the following reasons. + + - A current trend among the Khronos workgroups is to remove use of + global state by introducing bindless objects. Introducing a new + thread-local binding point defies that trend. + + - Additional specification language would be required to define + the interactions between the currently bound platform and all + EGL functions that accept an EGLDisplay. (For example, if the + currently bound platform is Wayland, then what is the result of + calling eglCreateWindowSurface() with a display and native + window belonging to X11?) By choosing to not introduce the + notion of a "currently bound platform", we obtain a cleaner + extension specification and eliminate for EGL users a class of + potential bugs. + + 3. Should this extension define the notion of a default platform? + + RESOLVED: No. eglGetDisplay() can be used if a default platform is + needed. + + 4. Rather than define the new functions + eglCreatePlatform{Window,Pixmap}SurfaceEXT(), should we instead + redefine the EGLNative* types in eglplatform.h as void*? + + RESOLVED: No, this introduces problems for X11 applications. + + Suppose that a 64-bit X11 application is compiled against an old EGL + library (where EGLNativeWindowType is a typedef for XID, which is in + turn a typedef for a 64-bit unsigned integer on Fedora 18) and then + attempts to run against a new EGL library (where EGLNativeType is + a typedef for void*). To preserve the ABI of eglCreateWindowSurface() + in this situation, the new EGL library must re-interpret the + <native_window> parameter as an integer. + + However, this preservation of the ABI breaks source compatibility for + existing X11 applications. To successfully compile, each call to + + eglCreateWindowSurface(dpy, window, attribs) + + in existing X11 application source code would need to be replaced with + + eglCreateWindowSurface(dpy, (void*) window, attribs) . + + Requiring such widespread code modifications would be an unnecessary + burden to developers and Linux package maintainers. + +Revision History + + Version 9, 2014.01.09 (Jon Leech) + - Fix typo eglGetDisplayPlatformEXT -> eglGetPlatformDisplayEXT + + Version 8, 2013.07.03 (Chad Versace) + - Add "Extension Type" section, required by EGL_EXT_client_extensions v9. + + Version 7, 2013.06.07 (Chad Versace) + - Fix some awkward text (s/the EGL/EGL/). + - Remove text "attribute names are defined by platform-specific + extensions". + + Version 6, 2013.06.07 (Chad Versace) + - To "Dependencies" section, expand text that discusses + EGL_EXT_client_extensions. + + Version 5, 2013.05.18 (Chad Versace) + - Removed restriction that "attribute names are defined only by + platform-specific extensions". + - Resolve issue 3 as NO. + - Clarified some text and fixed grammatical errors. + + Version 4, 2013.05.14 (Chad Versace) + - Add <attrib_list> parameter to eglGetPlatformDisplayEXT, per + feedback at the April Khronos F2F. + + Version 3, 2013.04.26 (Chad Versace) + - Add issues 2, 3, 4. + + Version 2, 2013.03.24 (Chad Versace) + - Complete draft by adding text for pixmaps. + - The footnotes regarding undefined behavior, simplify them by + simply referring to section 3.1.0.2. + - Add issue 1 from Eric Anholt <eric@anholt.net>. + - Fix spelling and formatting errors. + + Version 1, 2013.03.13 (Chad Versace) + - Incomplete draft posted for review diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_device.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_device.txt new file mode 100644 index 0000000..45c4fe3 --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_device.txt @@ -0,0 +1,161 @@ +Name + + EXT_platform_device + +Name Strings + + EGL_EXT_platform_device + +Contributors + + James Jones + Daniel Kartch + +Contacts + + James Jones, NVIDIA (jajones 'at' nvidia.com) + +Status + + Complete + +Version + + Version 6 - May 16th, 2014 + +Number + + EGL Extension #73 + +Extension Type + + EGL client extension + +Dependencies + + Requires EGL_EXT_device_base + + Requires EGL_EXT_platform_base or EGL 1.5 + + Written against the wording of EGL 1.5 + +Overview + + Increasingly, EGL and its client APIs are being used in place of + "native" rendering APIs to implement the basic graphics + functionality of native windowing systems. This creates demand + for a method to initialize EGL displays and surfaces directly on + top of native GPU or device objects rather than native window + system objects. The mechanics of enumerating the underlying + native devices and constructing EGL displays and surfaces from + them have been solved in various platform and implementation- + specific ways. The EGL device family of extensions offers a + standardized framework for bootstrapping EGL without the use of + any underlying "native" APIs or functionality. + + This extension defines a method to create an EGLDisplay from an + EGLDeviceEXT by treating the EGLDeviceEXT as an EGLNativeDisplay + object. + +New Types + + None + +New Functions + + None + +New Tokens + + Accepted by the <platform> parameter of eglGetPlatformDisplayEXT + and eglGetPlatformDisplay: + + EGL_PLATFORM_DEVICE_EXT 0x313F + +Replace the last paragraph of section 2.1 "Native Window System and +Rendering APIs" + + "This specification defines only the EGLDeviceEXT platform, and + behavior specific to it. Implementations may support other + platforms, but their existence and behavior is defined by + extensions. To detect support for other platforms, clients should + query the EGL_EXTENSIONS string of EGL_NO_DISPLAY using + eglQueryString (see section 3.3). + +Replace the second sentence of the paragraph following the +eglGetPlatformDisplay prototype + + "The only valid value for <platform> is EGL_PLATFORM_DEVICE_EXT. + When <platform> is EGL_PLATFORM_DEVICE_EXT, <native_display> must + be an EGLDeviceEXT object. Platform-specific extensions may + define other valid values for <platform>." + +Add the following sentence to the end of the second paragraph after +the eglCreatePlatformWindowSurface prototype. + + "There are no valid values of <native_window> when <dpy> belongs + to the EGL_PLATFORM_DEVICE_EXT platform." + +Add the following sentence to the end of the second paragraph after +the eglCreatePlatformPixmapSurface prototype. + + "There are no valid values of <native_pixmap> when <dpy> belongs + to the EGL_PLATFORM_DEVICE_EXT platform. + +Issues + + 1. Do EGLDevice-backed displays support window or pixmap surfaces? + If so, what native objects are they associated with? If not, + are EGLDevice-backed displays useful in any way? + + RESOLVED: This extension defines no method to create window or + pixmap surfaces on the EGLDeviceEXT platform. Other + extensions may define such functionality. Presumably, if + there are no other extensions that expose native window or + pixmap types associated with EGL devices, EGLDeviceEXT-backed + displays could expose EGLConfigs that only support rendering + to EGLStreamKHR or EGLPbuffer surfaces. + + 2. Should the EGL_PLATFORM_DEVICE_EXT platform be included in the + EGL specification as a special "blessed" platform, or exist + only as an extension like other platforms? + + RESOLVED: EGL devices are defined as part of the EGL + specification, so there's no reason to exclude their + associated platform from the core EGL specification. They are + not native objects, therefore they can not be referred to as a + native platform, even though they are used interchangeably + with native objects in this extension. + +Revision History: + + #6 (May 16th, 2014) James Jones + - Marked the extension complete + - Marked all issues resolved + + #5 (April 8th, 2014) James Jones + - Updated wording based on the EGL 1.5 spec + - Assigned values to tokens + + #4 (November 6th, 2013) James Jones + - Specified this is a device extension + - Requires, rather than interacts with EGL_EXT_platform_base + - Removed EGL_SUPPORTS_PLATFORM_DEVICE_EXT. There is no need + for a separate query now that the name string is listed in + the per-device extension string + + #3 (April 23rd, 2013) James Jones + - Fixed minor typos + + #2 (April 18th, 2013) James Jones + - Moved eglGetDisplayPointerEXT to a stand-alone extension + - Renamed from EGL_EXT_device_display to + EGL_EXT_platform_device + - Filled in the actual spec language modifications + - Replaced issue 2, since the original was moved to + EGL_EXT_display_attributes + - Reworded issue 1. + - Fixed some typos + + #1 (April 16th, 2013) James Jones + - Initial Draft diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_wayland.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_wayland.txt new file mode 100644 index 0000000..3e5c0fa --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_wayland.txt @@ -0,0 +1,135 @@ +Name + + EXT_platform_wayland + +Name Strings + + EGL_EXT_platform_wayland + +Contributors + + Chad Versace <chad.versace@intel.com> + +Contacts + + Chad Versace <chad.versace@intel.com> + +Status + + Complete + +Version + + Version 4, 2014-03-10 + +Number + + EGL Extension #63 + +Extension Type + + EGL client extension + +Dependencies + + Requires EGL_EXT_client_extensions to query its existence without + a display. + + Requires EGL_EXT_platform_base. + + This extension is written against the wording of version 7 of the + EGL_EXT_platform_base specification. + +Overview + + This extension defines how to create EGL resources from native Wayland + resources using the functions defined by EGL_EXT_platform_base. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted as the <platform> argument of eglGetPlatformDisplayEXT: + + EGL_PLATFORM_WAYLAND_EXT 0x31D8 + +Additions to the EGL Specification + + None. + +New Behavior + + To determine if the EGL implementation supports this extension, clients + should query the EGL_EXTENSIONS string of EGL_NO_DISPLAY. + + To obtain an EGLDisplay backed by a Wayland display, call + eglGetPlatformDisplayEXT with <platform> set to EGL_PLATFORM_WAYLAND_EXT. The + <native_display> parameter specifies the Wayland display to use and must + either point to a `struct wl_display` or be EGL_DEFAULT_DISPLAY. If + <native_display> is EGL_DEFAULT_DISPLAY, then EGL will create a new + wl_display structure by connecting to the default Wayland socket. The + manual page wl_display_connect(3) defines the location of the default + Wayland socket. + + To obtain an on-screen rendering surface from a Wayland window, call + eglCreatePlatformWindowSurfaceEXT with a <dpy> that belongs to Wayland and + a <native_window> that points to a `struct wl_egl_surface`. + + It is not valid to call eglCreatePlatformPixmapSurfaceEXT with a <dpy> + that belongs to Wayland. Any such call fails and generates + EGL_BAD_PARAMETER. + +Issues + + 1. Should this extension permit EGL_DEFAULT_DISPLAY as input to + eglGetPlatformDisplayEXT()? + + RESOLUTION: Yes. When given EGL_DEFAULT_DISPLAY, eglGetPlatformDisplayEXT + returns a display backed by the default Wayland display. + + 2. Should this extension support creation EGLPixmap resources from Wayland + pixmaps? + + RESOLVED. No. Wayland has no pixmap type. + + 3. Should the extension namespace be EXT or MESA? + + The only shipping EGL implementation today (2013-04-26) that supports + Wayland is Mesa. However, perhaps the extension should reside in the + EXT namespace in expectation that other vendors will also begin + supporting Wayland. + + RESOLVED. Use the EXT namespace because other vendors have expressed + interest in Wayland. + +Revision History + + Version 4, 2014-03-10(Chad Versace) + - Change resolution of issue #1 from "no" to "yes". Now + eglGetPlatformDisplayEXT accepts EGL_DEFAULT_DISPLAY for Wayland. + - Explain in more detail how EGL connects to the default Wayland + display. + + Version 3, 2013-10-16 (Chad Versace) + - Resolve issue #3 to use EXT namespace. + + Version 2, 2013-09-12 (Chad Versace) + - Update to wording of version 7 of EGL_EXT_platform_base spec. + - Add section "Extension Type". + - Rephrase the discussion of how to create a Wayland EGLDisplay + to follow the analogous discussion in the published + EGL_EXT_platform_x11 spec. + - Change resolution of issue 1 from yes to no, because of likely type + mismatch between EGL_DEFAULT_DISPLAY_TYPE and void*. + + Version 1, 2013-04-26 (Chad Versace) + - Initial draft + +# vim:ai:et:sw=4:ts=4: + diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_x11.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_x11.txt new file mode 100644 index 0000000..19bfc35 --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_x11.txt @@ -0,0 +1,414 @@ +Name + + EXT_platform_x11 + +Name Strings + + EGL_EXT_platform_x11 + +Contributors + + Chad Versace <chad.versace@intel.com> + James Jones <jajones@nvidia.com> + +Contacts + + Chad Versace <chad.versace@intel.com> + +Status + + Complete + +Version + + Version 13, 2014-03-10 + +Number + + EGL Extension #59 + +Extension Type + + EGL client extension + +Dependencies + + Requires EGL_EXT_client_extensions to query its existence without + a display. + + Requires EGL_EXT_platform_base. + + This extension is written against the wording of version 7 of the + EGL_EXT_platform_base specification. + +Overview + + This extension defines how to create EGL resources from native X11 + resources using the functions defined by EGL_EXT_platform_base. + + This extension defines only how to create EGL resources from Xlib + resources. It does not define how to do so from xcb resources. All X11 + types discussed here are defined by the header `Xlib.h`. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted as the <platform> argument of eglGetPlatformDisplayEXT: + + EGL_PLATFORM_X11_EXT 0x31D5 + + Accepted as an attribute name in the <attrib_list> argument of + eglGetPlatformDisplayEXT: + + EGL_PLATFORM_X11_SCREEN_EXT 0x31D6 + +Additions to the EGL Specification + + None. + +New Behavior + + To determine if the EGL implementation supports this extension, clients + should query the EGL_EXTENSIONS string of EGL_NO_DISPLAY. + + On the X11 platform, an EGLDisplay refers to a specific X11 screen rather + than an X11 display connection. This is the case because separate X11 + screens, even when belonging to the same X11 display connection, may + reside on different GPUs and/or be driven by different drivers. Therefore, + different X11 screens may have different EGL capabilities. + + To obtain an EGLDisplay backed by an X11 screen, call + eglGetPlatformDisplayEXT with <platform> set to EGL_PLATFORM_X11_EXT. The + <native_display> parameter specifies the X11 display connection to use, and + must point to a valid X11 `Display` or be NULL. If <native_display> is + EGL_DEFAULT_DISPLAY, then EGL will create [1] a connection to the default + X11 display. The environment variable DISPLAY determines the default X11 + display as described in the manual page for XOpenDisplay(3). The value of + attribute EGL_PLATFORM_X11_SCREEN_EXT specifies the X11 screen to use. If + the attribute is omitted from <attrib_list>, then the display connection's + default screen is used. Otherwise, the attribute's value must be a valid + screen on the display connection. If the attribute's value is not a valid + screen, then an EGL_BAD_ATTRIBUTE error is generated. + + [fn1] The method by which EGL creates a connection to the default X11 + display is an internal implementation detail. The implementation may use + XOpenDisplay, xcb_connect, or any other method. + + To obtain an on-screen rendering surface from an X11 Window, call + eglCreatePlatformWindowSurfaceEXT with a <dpy> that belongs to X11 and + a <native_window> that points to an X11 Window. + + To obtain an offscreen rendering surface from an X11 Pixmap, call + eglCreatePlatformPixmapSurfaceEXT with a <dpy> that belongs to X11 and + a <native_pixmap> that points to an X11 Pixmap. + +Issues + + 1. Should this extension permit EGL_DEFAULT_DISPLAY as input to + eglGetPlatformDisplayEXT()? + + RESOLVED. Yes. When given EGL_DEFAULT_DISPLAY, eglGetPlatformDisplayEXT + returns an EGLDisplay backed by the default X11 display. + + 2. When given EGL_DEFAULT_DISPLAY, does eglGetPlatformDisplayEXT reuse an + existing X11 display connection or create a new one? + + RESOLVED. eglGetPlatformDisplayEXT creates a new connection because the + alternative is infeasible. EGL cannot reliably detect if the client + process already has a X11 display connection. + + +Example Code + + // This example program creates two EGL surfaces: one from an X11 Window + // and the other from an X11 Pixmap. + // + // If the macro USE_EGL_EXT_PLATFORM_X11 is defined, then the program + // creates the surfaces using the methods defined in this specification. + // Otherwise, it uses the methods defined by the EGL 1.4 specification. + // + // Compile with `cc -std=c99 example.c -lX11 -lEGL`. + + #include <stdlib.h> + #include <string.h> + + #include <EGL/egl.h> + #include <X11/Xlib.h> + + struct my_display { + Display *x11; + EGLDisplay egl; + }; + + struct my_config { + struct my_display dpy; + XVisualInfo *x11; + Colormap colormap; + EGLConfig egl; + }; + + struct my_window { + struct my_config config; + Window x11; + EGLSurface egl; + }; + + struct my_pixmap { + struct my_config config; + Pixmap x11; + EGLSurface egl; + }; + + static void + check_extensions(void) + { + #ifdef USE_EGL_EXT_PLATFORM_X11 + const char *client_extensions = eglQueryString(EGL_NO_DISPLAY, EGL_EXTENSIONS); + + if (!client_extensions) { + // EGL_EXT_client_extensions is unsupported. + abort(); + } + if (!strstr(client_extensions, "EGL_EXT_platform_x11")) { + abort(); + } + #endif + } + + static struct my_display + get_display(void) + { + struct my_display dpy; + + dpy.x11 = XOpenDisplay(NULL); + if (!dpy.x11) { + abort(); + } + + #ifdef USE_EGL_EXT_PLATFORM_X11 + dpy.egl = eglGetPlatformDisplayEXT(EGL_PLATFORM_X11_EXT, dpy.x11, + NULL); + #else + dpy.egl = eglGetDisplay(dpy.x11); + #endif + + if (dpy.egl == EGL_NO_DISPLAY) { + abort(); + } + + EGLint major, minor; + if (!eglInitialize(dpy.egl, &major, &minor)) { + abort(); + } + + return dpy; + } + + static struct my_config + get_config(struct my_display dpy) + { + struct my_config config = { + .dpy = dpy, + }; + + EGLint egl_config_attribs[] = { + EGL_BUFFER_SIZE, 32, + EGL_RED_SIZE, 8, + EGL_GREEN_SIZE, 8, + EGL_BLUE_SIZE, 8, + EGL_ALPHA_SIZE, 8, + + EGL_DEPTH_SIZE, EGL_DONT_CARE, + EGL_STENCIL_SIZE, EGL_DONT_CARE, + + EGL_RENDERABLE_TYPE, EGL_OPENGL_ES2_BIT, + EGL_SURFACE_TYPE, EGL_WINDOW_BIT | EGL_PIXMAP_BIT, + EGL_NONE, + }; + + EGLint num_configs; + if (!eglChooseConfig(dpy.egl, + egl_config_attribs, + &config.egl, 1, + &num_configs)) { + abort(); + } + if (num_configs == 0) { + abort(); + } + + XVisualInfo x11_visual_info_template; + if (!eglGetConfigAttrib(dpy.egl, + config.egl, + EGL_NATIVE_VISUAL_ID, + (EGLint*) &x11_visual_info_template.visualid)) { + abort(); + } + + int num_visuals; + config.x11 = XGetVisualInfo(dpy.x11, + VisualIDMask, + &x11_visual_info_template, + &num_visuals); + if (!config.x11) { + abort(); + } + + config.colormap = XCreateColormap(dpy.x11, + RootWindow(dpy.x11, 0), + config.x11->visual, + AllocNone); + if (config.colormap == None) { + abort(); + } + + return config; + } + + static struct my_window + get_window(struct my_config config) + { + XSetWindowAttributes attr; + unsigned long mask; + + struct my_window window = { + .config = config, + }; + + attr.colormap = config.colormap; + mask = CWColormap; + + window.x11 = XCreateWindow(config.dpy.x11, + DefaultRootWindow(config.dpy.x11), // parent + 0, 0, // x, y + 256, 256, // width, height + 0, // border_width + config.x11->depth, + InputOutput, // class + config.x11->visual, + mask, // valuemask + &attr); // attributes + if (!window.x11) { + abort(); + } + + #ifdef USE_EGL_EXT_PLATFORM_X11 + window.egl = eglCreatePlatformWindowSurfaceEXT(config.dpy.egl, + config.egl, + &window.x11, + NULL); + #else + window.egl = eglCreateWindowSurface(config.dpy.egl, + config.egl, + window.x11, + NULL); + #endif + + if (window.egl == EGL_NO_SURFACE) { + abort(); + } + + return window; + } + + static struct my_pixmap + get_pixmap(struct my_config config) + { + struct my_pixmap pixmap = { + .config = config, + }; + + pixmap.x11 = XCreatePixmap(config.dpy.x11, + DefaultRootWindow(config.dpy.x11), + 256, 256, // width, height + config.x11->depth); + if (!pixmap.x11) { + abort(); + } + + #ifdef USE_EGL_EXT_PLATFORM_X11 + pixmap.egl = eglCreatePlatformPixmapSurfaceEXT(config.dpy.egl, + config.egl, + &pixmap.x11, + NULL); + #else + pixmap.egl = eglCreatePixmapSurface(config.dpy.egl, + config.egl, + pixmap.x11, + NULL); + #endif + + if (pixmap.egl == EGL_NO_SURFACE) { + abort(); + } + + return pixmap; + } + + int + main(void) + { + check_extensions(); + + struct my_display dpy = get_display(); + struct my_config config = get_config(dpy); + struct my_window window = get_window(config); + struct my_pixmap pixmap = get_pixmap(config); + + return 0; + } + +Revision History + + Version 13, 2014-03-10 (Chad Versace) + - Update text to reflect resolution of issue #1. State that + <native_display> may be EGL_DEFAULT_DISPLAY. + - Explain in more detail how EGL connects to the default X11 display. + - Add and resolve issue #2. + + Version 12, 2014-02-11 (Chad Versace) + - Fix 2nd argument to XCreatePixmap in example code. + + Version 11, 2013-07-10 (Jon Leech) + - Fix enumerant values and assign extension number for publication + (Bug 10240). + + Version 10, 2013-07-03 (Chad Versace) + - Add "Extension Type" section, required by EGL_EXT_client_extensions v9. + + Version 9, 2013-06-11 (Chad Versace) + - Replace reference to version 5 of EGL_EXT_platform_base to version 7. + - Add James Jones as contributor. + + Version 8, 2013-06-07 (Chad Versace) + - Assign enum values to new tokens. + + Version 7, 2013-06-07 (Chad Versace) + - Explicitly require EGL_EXT_client_extensions in the Dependencies + section. + + Version 6, 2013-06-07 (Chad Versace) + - Add attribute EGL_PLATFORM_X11_SCREEN_EXT. + + Version 5, 2013-06-07 (Chad Versace) + - Rephrase against version 7 of EGL_EXT_platform_base. + + Version 4, 2013-06-07 (Chad Versace) + - Fix compilation of example code. + + Version 3, 2013-04-26 (Chad Versace) + - Add missing EXT suffix to new token. + + Version 2, 2013-04-22 (Chad Versace) + - Discuss EGL_DEFAULT_DISPLAY. + - Fix minor typographical and grammatical errors. + + Version 1, 2013.03.24 (Chad Versace) + - First draft diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_xcb.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_xcb.txt new file mode 100644 index 0000000..1411db6 --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_xcb.txt @@ -0,0 +1,382 @@ +Name + + EXT_platform_xcb + +Name Strings + + EGL_EXT_platform_xcb + +Contributors + + Yuxuan Shui <yshuiv7@gmail.com> + +Contacts + + Yuxuan Shui <yshuiv7@gmail.com> + +Status + + Complete + +Version + + Version 1, 2020-08-28 + +Number + + EGL Extension #141 + +Extension Type + + EGL client extension + +Dependencies + + Requires EGL_EXT_client_extensions to query its existence without + a display. + + Requires EGL_EXT_platform_base. + + This extension is written against the wording of version 9 of the + EGL_EXT_platform_base specification. + +Overview + + This extension defines how to create EGL resources from native X11 + resources using the functions defined by EGL_EXT_platform_base. + + The native X11 resources required by this extension are xcb resources. + All X11 types discussed here are defined by the header `xcb.h`. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted as the <platform> argument of eglGetPlatformDisplayEXT: + + EGL_PLATFORM_XCB_EXT 0x31DC + + Accepted as an attribute name in the <attrib_list> argument of + eglGetPlatformDisplayEXT: + + EGL_PLATFORM_XCB_SCREEN_EXT 0x31DE + +Additions to the EGL Specification + + None. + +New Behavior + + To determine if the EGL implementation supports this extension, clients + should query the EGL_EXTENSIONS string of EGL_NO_DISPLAY. + + This extension defines the same set of behaviors as EGL_EXT_platform_x11, + except Xlib types are replaced with xcb types. + + To obtain an EGLDisplay backed by an X11 screen, call + eglGetPlatformDisplayEXT with <platform> set to EGL_PLATFORM_XCB_EXT. The + <native_display> parameter specifies the X11 display connection to use, and + must point to a valid xcb `xcb_connection_t` or be EGL_DEFAULT_DISPLAY. If + <native_display> is EGL_DEFAULT_DISPLAY, then EGL will create [1] a + connection to the default X11 display. The environment variable DISPLAY + determines the default X11 display, and, unless overridden by the + EGL_PLATFORM_XCB_SCREEN_EXT attribute, the default X11 screen - as + described in the documentation of `xcb_connect`. If the environment + variable DISPLAY is not present in this case, the result is undefined. The + value of attribute EGL_PLATFORM_XCB_SCREEN_EXT specifies the X11 screen to + use. If the attribute is omitted from <attrib_list>, and <native_display> + is not EGL_DEFAULT_DISPLAY, then screen 0 will be used. Otherwise, the + attribute's value must be a valid screen on the display connection. If the + attribute's value is not a valid screen, then an EGL_BAD_ATTRIBUTE error is + generated. + + [fn1] The method by which EGL creates a connection to the default X11 + display is an internal implementation detail. The implementation may use + xcb_connect, or any other method. + + To obtain an on-screen rendering surface from an X11 Window, call + eglCreatePlatformWindowSurfaceEXT with a <dpy> that belongs to X11 and + a <native_window> that points to an xcb_window_t. + + To obtain an offscreen rendering surface from an X11 Pixmap, call + eglCreatePlatformPixmapSurfaceEXT with a <dpy> that belongs to X11 and + a <native_pixmap> that points to an xcb_pixmap_t. + +Issues + + 1. As xcb_connection_t doesn't carry a screen number, how should a screen be + selected in eglGetPlatformDisplayEXT()? + + RESOLVED. The screen will be chosen with the following logic: + + * If EGL_PLATFORM_XCB_SCREEN_EXT is specified, it will always take + precedence. Whether <native_display> is EGL_DEFAULT_DISPLAY or not. + + * Otherwise, if <native_display> is not EGL_DEFAULT_DISPLAY, then + screen 0 will be used. + + * Otherwise, which is to say <native_display> is EGL_DEFAULT_DISPLAY. + Then the DISPLAY environment variable will be used to determine the + screen number. If DISPLAY contains a screen number, that will be + used; if not, then 0 will be used. + + * If the DISPLAY environment variable is not present when + <native_display> is EGL_DEFAULT_DISPLAY, the result will be undefined. + +Example Code + + // This example program creates two EGL surfaces: one from an X11 Window + // and the other from an X11 Pixmap. + // + // Compile with `cc example.c -lxcb -lEGL`. + + #include <stddef.h> + #include <stdlib.h> + #include <string.h> + + #include <EGL/egl.h> + #include <EGL/eglext.h> + #include <xcb/xcb.h> + + struct my_display { + xcb_connection_t *x11; + int screen; + int root_of_screen; + EGLDisplay egl; + }; + + struct my_config { + struct my_display dpy; + xcb_colormap_t colormap; + xcb_visualid_t visualid; + int depth; + EGLConfig egl; + }; + + struct my_window { + struct my_config config; + xcb_window_t x11; + EGLSurface egl; + }; + + struct my_pixmap { + struct my_config config; + xcb_pixmap_t x11; + EGLSurface egl; + }; + + static void check_extensions(void) { + const char *client_extensions = + eglQueryString(EGL_NO_DISPLAY, EGL_EXTENSIONS); + + if (!client_extensions) { + // EGL_EXT_client_extensions is unsupported. + abort(); + } + if (!strstr(client_extensions, "EGL_EXT_platform_xcb")) { + abort(); + } + } + + xcb_screen_t *get_screen(xcb_connection_t *c, int screen) { + xcb_screen_iterator_t iter; + + iter = xcb_setup_roots_iterator(xcb_get_setup(c)); + for (; iter.rem; --screen, xcb_screen_next(&iter)) + if (screen == 0) + return iter.data; + + return NULL; + } + + int get_visual_depth(xcb_connection_t *c, xcb_visualid_t visual) { + const xcb_setup_t *setup = xcb_get_setup(c); + for (xcb_screen_iterator_t i = xcb_setup_roots_iterator(setup); i.rem; + xcb_screen_next(&i)) { + for (xcb_depth_iterator_t j = + xcb_screen_allowed_depths_iterator(i.data); + j.rem; xcb_depth_next(&j)) { + const int len = xcb_depth_visuals_length(j.data); + const xcb_visualtype_t *visuals = xcb_depth_visuals(j.data); + for (int k = 0; k < len; k++) { + if (visual == visuals[k].visual_id) { + return j.data->depth; + } + } + } + } + abort(); + } + + static struct my_display get_display(void) { + struct my_display dpy; + + dpy.x11 = xcb_connect(NULL, &dpy.screen); + if (!dpy.x11) { + abort(); + } + + dpy.egl = eglGetPlatformDisplayEXT(EGL_PLATFORM_XCB_EXT, dpy.x11, + (const EGLint[]){ + EGL_PLATFORM_XCB_SCREEN_EXT, + dpy.screen, + EGL_NONE, + }); + + if (dpy.egl == EGL_NO_DISPLAY) { + abort(); + } + + EGLint major, minor; + if (!eglInitialize(dpy.egl, &major, &minor)) { + abort(); + } + + xcb_screen_t *screen = get_screen(dpy.x11, dpy.screen); + dpy.root_of_screen = screen->root; + + return dpy; + } + + static struct my_config get_config(struct my_display dpy) { + struct my_config config = { + .dpy = dpy, + }; + + EGLint egl_config_attribs[] = { + EGL_BUFFER_SIZE, + 32, + EGL_RED_SIZE, + 8, + EGL_GREEN_SIZE, + 8, + EGL_BLUE_SIZE, + 8, + EGL_ALPHA_SIZE, + 8, + + EGL_DEPTH_SIZE, + EGL_DONT_CARE, + EGL_STENCIL_SIZE, + EGL_DONT_CARE, + + EGL_RENDERABLE_TYPE, + EGL_OPENGL_ES2_BIT, + EGL_SURFACE_TYPE, + EGL_WINDOW_BIT | EGL_PIXMAP_BIT, + EGL_NONE, + }; + + EGLint num_configs; + if (!eglChooseConfig(dpy.egl, egl_config_attribs, &config.egl, 1, + &num_configs)) { + abort(); + } + if (num_configs == 0) { + abort(); + } + + if (!eglGetConfigAttrib(dpy.egl, config.egl, EGL_NATIVE_VISUAL_ID, + (EGLint *)&config.visualid)) { + abort(); + } + + config.colormap = xcb_generate_id(dpy.x11); + if (xcb_request_check(dpy.x11, + xcb_create_colormap_checked( + dpy.x11, XCB_COLORMAP_ALLOC_NONE, config.colormap, + dpy.root_of_screen, config.visualid))) { + abort(); + } + + config.depth = get_visual_depth(dpy.x11, config.visualid); + + return config; + } + + static struct my_window get_window(struct my_config config) { + xcb_generic_error_t *e; + + struct my_window window = { + .config = config, + }; + + window.x11 = xcb_generate_id(config.dpy.x11); + e = xcb_request_check( + config.dpy.x11, + xcb_create_window_checked(config.dpy.x11, // connection + XCB_COPY_FROM_PARENT, // depth + window.x11, // window id + config.dpy.root_of_screen, // root + 0, 0, // x, y + 256, 256, // width, height + 0, // border_width + XCB_WINDOW_CLASS_INPUT_OUTPUT, // class + config.visualid, // visual + XCB_CW_COLORMAP, // mask + (const int[]){ + config.colormap, + XCB_NONE, + })); + if (e) { + abort(); + } + + window.egl = eglCreatePlatformWindowSurfaceEXT(config.dpy.egl, config.egl, + &window.x11, NULL); + + if (window.egl == EGL_NO_SURFACE) { + abort(); + } + + return window; + } + + static struct my_pixmap get_pixmap(struct my_config config) { + struct my_pixmap pixmap = { + .config = config, + }; + + pixmap.x11 = xcb_generate_id(config.dpy.x11); + if (xcb_request_check( + config.dpy.x11, + xcb_create_pixmap(config.dpy.x11, config.depth, pixmap.x11, + config.dpy.root_of_screen, 256, 256))) { + abort(); + } + + pixmap.egl = eglCreatePlatformPixmapSurfaceEXT(config.dpy.egl, config.egl, + &pixmap.x11, NULL); + + if (pixmap.egl == EGL_NO_SURFACE) { + abort(); + } + + return pixmap; + } + + int main(void) { + check_extensions(); + + struct my_display dpy = get_display(); + struct my_config config = get_config(dpy); + struct my_window window = get_window(config); + struct my_pixmap pixmap = get_pixmap(config); + + return 0; + } + +Revision History + + Version 2, 2020.10.13 (Yuxuan Shui) + - Some wording changes + - Address the question about screen selection + + Version 1, 2020.08.28 (Yuxuan Shui) + - First draft diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_present_opaque.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_present_opaque.txt new file mode 100644 index 0000000..de2f6d8 --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_present_opaque.txt @@ -0,0 +1,118 @@ +Name + + EXT_present_opaque + +Name Strings + + EGL_EXT_present_opaque + +Contributors + + Eric Engestrom + +Contacts + + Eric Engestrom (eric 'at' engestrom.ch) + +IP Status + + No known IP claims. + +Status + + Complete + +Version + + #1, August 8, 2021 + +Number + + EGL Extension #146 + +Extension Type + + EGL display extension + +Dependencies + + Requires EGL 1.4 and EGL_KHR_image_base extension + + This extension is written against the wording of the EGL 1.4 + specification, and EGL_KHR_image_base version 6. + +Overview + + This extension adds a new EGL surface attribute EGL_PRESENT_OPAQUE_EXT + to indicate that the surface should be presented as opaque, + disregarding any alpha channel if present. + If surface attribute EGL_PRESENT_OPAQUE_EXT is EGL_TRUE, then the + surface will be presented as opaque. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + New EGLSurface attribute name: + + EGL_PRESENT_OPAQUE_EXT 0x31DF + + +Additions to Chapter 3 of the EGL 1.4 Specification (Rendering Surfaces) + + Change the second paragraph in section 3.5 on p. 28 (describing + eglCreateWindowSurface): + + "Attributes that can be specified in attrib list include EGL_RENDER_BUFFER, + EGL_PRESENT_OPAQUE_EXT, EGL_VG_COLORSPACE, and EGL_VG_ALPHA_FORMAT." + + Add the following paragraph in section 3.5 on p. 28 before + "EGL_VG_COLORSPACE specifies the color space used by OpenVG" + (describing eglCreateWindowSurface attrib_list): + + "EGL_PRESENT_OPAQUE_EXT specifies the presentation opacity mode + of the window surface. If its value is EGL_TRUE, then the + surface's alpha channel (if any) will be ignored and considered + fully opaque. If its value is EGL_FALSE, then the compositor + doesn't change its behaviour, and considers the surface's alpha + channel the same way as if the extension wasn't implemented. The + default value of EGL_PRESENT_OPAQUE_EXT is EGL_FALSE." + + Add to Table 3.5: Queryable surface attributes and types on p. 37 + + EGL_PRESENT_OPAQUE_EXT boolean Surface presentation opacity mode + + Add following the second paragraph in section 3.6 on p. 39 (describing + eglQuerySurface): + + "Querying EGL_PRESENT_OPAQUE_EXT returns the presentation + opacity mode of the surface. The presentation opacity mode of + window surfaces is specified in eglCreateWindowSurface. The + presentation opacity mode of pbuffer and pixmap surfaces is + always EGL_FALSE." + + Add following after "which must be a valid native pixmap handle." in section 3.9.2 on + p. 53 (describing eglCopyBuffers): + + "If attribute EGL_PRESENT_OPAQUE_EXT of surface has value of EGL_TRUE, then + an EGL_BAD_ACCESS error is returned." + +Issues + + None + +Revision History + + Version 2, 2021-08-17 (Eric Engestrom) + - Re-worded the compositor's behaviour for EGL_FALSE. + - Marked extension as Complete. + + Version 1, 2021-08-08 (Eric Engestrom) + - Initial draft + diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_protected_content.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_protected_content.txt new file mode 100644 index 0000000..2421161 --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_protected_content.txt @@ -0,0 +1,329 @@ +Name + + EXT_protected_content + +Name Strings + + EGL_EXT_protected_content + +Contributors + + Ramesh Viswanathan + Brian Ellis + Colin Sharp + Rajeev Kulkarni + Mohan Maiya + Maurice Ribble + Craig Donner + Jan-Harald Fredriksen + Daniel Koch + Michael Golds + Ray Smith + +Contacts + + Maurice Ribble (mribble 'at' qti.qualcomm.com) + +IP Status + + No known IP claims. + +Status + + Complete. + +Version + + Version 13, December 6, 2021 + +Number + + EGL Extension #97 + +Dependencies + + Requires EGL 1.4. + + Interactions with EGL_KHR_image_base extension. + + This extension is written against the wording of the EGL 1.4. + Specification (12/04/2013) + + This extension has interactions with EGL_EXT_protected_surface if that + extension is supported. The interactions are described in the main text. + +Overview + + This extension introduces the concept of protected contexts and protected + resources, specifically surfaces and EGLImages. Applications can choose at + creation time whether a context, surface or EGLImage is protected or not. + + A protected context is required to allow the GPU to operate on protected + resources, including protected surfaces and protected EGLImages. + + An explanation of undefined behavior in this extension: Several places + in this extension mention undefined behavior can result, which can + include program termination. The reason for this is because one way + to handle protected content is by using a protected virtual to physical + memory translation layer. With this sort of solution a system may generate + read or write faults when a non-protected source tries to access a protected + buffer. Depending on the system these faults might be ignored or they might + cause process termination. This undefined behavior should not include + actually allowing a transfer of data from a protected surface to a + non-protected surface. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted as an attribute name in the <attrib_list> parameter of + eglCreateContext, eglCreateWindowSurface, and eglCreateImageKHR; + and as an parameter of eglQuerySurface and eglQueryContext: + + EGL_PROTECTED_CONTENT_EXT 0x32C0 + + +Add a new section 2.7 entitled "Protected Content" at the end of Chapter 2 (EGL +Operation) + + "The attribute EGL_PROTECTED_CONTENT_EXT can be applied to EGL contexts, + EGL surfaces and EGLImages. If the attribute EGL_PROTECTED_CONTENT_EXT + is set to EGL_TRUE by the application, then the newly created EGL object + is said to be protected. A protected context is required to allow the + GPU to operate on protected resources, including protected surfaces and + protected EGLImages. + + GPU operations are grouped into pipeline stages. Pipeline stages can be + defined to be protected or not protected. Each stage defines + restrictions on whether it can read or write protected and unprotected + resources, as follows: + + When a GPU stage is protected, it: + - Can read from protected resources + - Can read from unprotected resources + - Can write to protected resources + - Can NOT write to unprotected resources + + When a GPU stage is not protected, it: + - Can NOT read from protected resources + - Can read from unprotected resources + - Can NOT write to protected resources + - Can write to unprotected resources + + Any accesses not following these restrictions will result in undefined + behavior. + + This extension does not specify which pipeline stages of a protected + context are protected or not. This is left to a client API extension to + define. All stages in a regular (not protected) context are not + protected. However, if EGL_EXT_protected_surface is also supported, a + regular (not protected) context will execute stages where one or more + protected resources is accessed as if it were a protected context. + + Note that the protection state of a stage may be left implementation + defined by a client API extension. This means that no guarantees can be + made about whether the stage will be protected or not protected. + Practically this means that the permitted operations for such a stage + are the intersection of the allowed operations for protected and not + protected stages, i.e it: + + - Can NOT read from protected resources + - Can read from unprotected resources + - Can NOT write to protected resources + - Can NOT write to unprotected resources + + Since this is not a very useful set of operations refer to the client API + extension to see what operations are actually allowed. + + This extension does not guarantee the implementation abides by a + system's digital rights management requirements. It must be verified + beyond the existence of this extension that the implementation of this + extension is trustworthy according to the requirements of a content + protection system." + +Additions to Chapter 3 of the EGL 1.4 Specification (Rendering Contexts) + + Change the fifth paragraph in section 3.7.1 Creating Rendering Contexts: + + "attrib list specifies a list of attributes for the context. The + list has the same structure as described for eglChooseConfig. + Attributes that can be specified in attrib list include + EGL_CONTEXT_CLIENT_VERSION and EGL_PROTECTED_CONTENT_EXT. The + EGL_CONTEXT_CLIENT_VERSION attribute may only be specified when + creating a OpenGL ES context (e.g. when the current rendering API is + EGL_OPENGL_ES_API)." + + Add the following paragraph in section 3.7.1 on p. 44 before "attrib list + may be NULL or empty (first attribute is EGL_NONE), in which case + attributes assume their default values as described below." + + "EGL_PROTECTED_CONTENT_EXT specifies the protected state of the new + context. If its value is EGL_TRUE, then the context is said to be + protected. If its value is EGL_FALSE, then the context is not + protected. See section 2.7 (Protected Content) for more information + about protected contexts. + + The default value of EGL_PROTECTED_CONTENT_EXT is EGL_FALSE." + + Add the following paragraph in section 3.7.4 Context Queries. Add after + the last paragraph after eglQueryContext queries. + + "Querying EGL_PROTECTED_CONTENT_EXT returns the current value" + +Additions to Chapter 3 of the EGL 1.4 Specification (Rendering Surfaces) + + Change the second paragraph in section 3.5 on p. 28 (describing + eglCreateWindowSurface): + + "Attributes that can be specified in attrib list include + EGL_RENDER_BUFFER, EGL_PROTECTED_CONTENT_EXT, EGL_VG_COLORSPACE, and + EGL_VG_ALPHA_FORMAT." + + Add the following paragraph in section 3.5 on p. 28 before + "EGL_VG_COLORSPACE specifies the color space used by OpenVG" (describing + eglCreateWindowSurface(attrib_list): + + "EGL_PROTECTED_CONTENT_EXT specifies the protected state of the + window surface. If its value is EGL_TRUE, then the surface content + is said to be protected. If its value is EGL_FALSE, then the surface + content is not protected. See section 2.7 (Protected Content) for + more information about protected and non-protected surfaces. + + Client APIs will not allow contents of protected surfaces to be + accessed by non-protected contexts in the system (including + non-secure software running on the CPU). Such operations will result + in undefined behavior. + + Calling eglSwapBuffers on such a protected surface will succeed, but + the contents may or may not be posted successfully depending on + whether those parts of the pipeline are capable of handling + protected content. Any disallowed operation will fail and result in + undefined behavior. + + The default value of EGL_PROTECTED_CONTENT_EXT is EGL_FALSE." + + Add the following paragraph in section 3.5.6 Surface Attributes. Add after + the last paragraph after eglQuerySurface attribute queries. + + "Querying EGL_PROTECTED_CONTENT_EXT returns the current value" + +Additions to EGL_KHR_image_base extension specification + + Add to section 2.5.1 Table bbb: + +-----------------------------+-------------------------+---------------+ + | Attribute | Description | Default Value | + +-----------------------------+-------------------------+---------------+ + | EGL_NONE | Marks the end of the | N/A | + | | attribute-value list | | + | EGL_IMAGE_PRESERVED_KHR | Whether to preserve | EGL_FALSE | + | | pixel data | | + | EGL_PROTECTED_CONTENT_EXT | Content protection | EGL_FALSE | + | | state | | + +-----------------------------+-------------------------+---------------+ + Table bbb. Legal attributes for eglCreateImageKHR <attrib_list> + parameter + + Add the following paragraph to section 2.5.1 before "Errors" (describing + eglCreateImageKHR): + + "If the value of attribute EGL_PROTECTED_CONTENT_EXT is EGL_TRUE + and the EGLImage sources can be guaranteed to be protected, then the + EGLImage is said to be protected. See section 2.7 (Protected Content) + for more information about protected resources including EGLImages. + + If the value of attribute EGL_PROTECTED_CONTENT_EXT is EGL_FALSE then: + + - If EGLImage sources are not protected, the EGLImage is said to be + not protected. See section 2.7 (Protected Content) for more + information about non-protected resources including EGLImages. + - If EGLImage sources are protected then the EGLImage content will + be inaccessible to any client context irrespective of whether the + context is protected or not. Trying to access such an EGLImage's + content will result in undefined behavior." + + Add the following to the Errors list in section 2.5.1 + + "If the value specified in <attrib_list> for EGL_PROTECTED_CONTENT_EXT + is EGL_TRUE, and EGL and its client is unable to make guarantees + regarding the protected state of the EGLImage source, the error + EGL_BAD_ACCESS is generated." + +Issues + 1) Can a protected context be shared with a non-protected context? + + RESOLVED - Yes. The rule that protected surfaces can only be used by + protected contexts still applies. An example use case is where + someone wants to render to unprotected textures within an unprotected + context and then share it with a protected context to be used as a texture. + + 2) Should all surfaces within a protected context be protected by default? + + RESOLVED - No, several implementations have limited amounts of protected + memory, so the API will require opting into protected memory. + + 3) Can these protected surfaces be used by stages other than fragment + shader stage? + + RESOLVED - Some hardware can't handle this so this behavior is undefined + unless there is explicit working in some new spec saying the behavior is + defined. This is put as an issue because this is an EGL extension and + should not be controlling OpenGL functionality. + + 4) Why is EGL_PROTECTED_CONTENT_EXT flag needed for EGLImages? + + RESOLVED - A few reasons for having an explicit flag instead + of inferring the protected status from EGLImage sources - + + 1) There are multiple EGL image extensions (EGL QCOM image, EGL + android image and so on) that accept buffers from external modules + instead of client resources or allow internally allocated memory. + For these use cases a protected attribute is useful, so we want to + keep this flag. + 2) An implementation might have a few non-standard setup steps that + need to be completed before a protected EGL image can be accessed. + This attribute along with a corresponding protected buffer will act + as a signal for the graphics driver to initiate/complete any such + steps. + 3) An application creating an image from an external resource may not + be aware of the fact that the resource is protected or may be unable + to access its content. The successful mapping of and access to a + protected buffer through an EGLImage will be predicated on the + buffer being protected, having a protected context and the intent of + the application to access that buffer by passing in EGL_TRUE for the + attribute EGL_PROTECTED_CONTENT_EXT. + + +Revision History + + Rev. Date Author Changes + ---- -------- -------- ---------------------------------------------- + 1 09/24/14 Ramesh Initial draft. + 2 11/20/14 Rajeev Second draft. + 3 03/07/16 mribble Make EXT and clean up for release. + 4 03/10/16 mribble Cleanup. + 5 03/18/16 mribble Fix issues brought up by Khronos group. + 6 03/24/16 mribble Resolved some small issues found by Jan-Harald. + 7 03/25/16 mribble Fix createContext wording. + 8 03/30/16 mribble Added issue 5. + 9 04/05/16 mribble Added issue 6 and better defined eglImage case. + 10 04/08/16 rsmith - Added general section on protected content. + Protected context, surface and image creation now + refer to the general protected content principles. + - Added explicit definition of which stages are + protected, including allowing for the protected + state of a stage to be undefined. + - Formalised interactions with + EGL_EXT_protected_surface. + - Removed references to the GPU protected mode, + including issue 3. + 11 04/10/16 mribble Merge and cleanup. + 12 04/14/16 Jon Leech Cleanup formatting, reflow paragraphs and + quote additions consistently. Assign extension + number. + 13 12/06/21 Jeff Vigil Add queries for protected content attribute. diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_protected_surface.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_protected_surface.txt new file mode 100644 index 0000000..ec3665a --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_protected_surface.txt @@ -0,0 +1,230 @@ +Name + + EXT_protected_surface + +Name Strings + + EGL_EXT_protected_surface + +Contributors + + Frido Garritsen, Vivante + Yanjun Zhang, Vivante + Pontus Lidman, Marvell + Jesse Hall, Google + +Contacts + + Frido Garritsen (frido 'at' vivantecorp.com) + Yanjun Zhang (yzhang 'at' vivantecorp.com) + +Notice + + Copyright 2013 Vivante Corporation + +IP Status + + No known IP claims. + +Status + + Draft + +Version + + #7, January 20, 2014 + +Number + + EGL Extension #67 + +Dependencies + + Requires EGL 1.4 and EGL_KHR_image_base extension + + This extension is written against the wording of the EGL 1.4 + Specification (12/04/2013), and EGL_KHR_image_base spec. version 6. + +Overview + + This extension adds a new EGL surface attribute EGL_PROTECTED_CONTENT_EXT + to indicate if the content in the surface buffer is protected or not. + If surface attribute EGL_PROTECTED_CONTENT_EXT is EGL_TRUE, then the + surface content is only accessible to secure accesses. Any attempt to access + the buffer content non-securely will fail and result in undefined behavior + up to and including program termination. Also, any copy operations from the + protected surface to any non-protected surface by GPU are considered illegal. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + New EGLSurface attribute name: + + EGL_PROTECTED_CONTENT_EXT 0x32C0 + + +Additions to Chapter 3 of the EGL 1.4 Specification (Rendering Surfaces) + + Change the second paragraph in section 3.5 on p. 28 (describing eglCreateWindowSurface): + + "Attributes that can be specified in attrib list include EGL_RENDER_BUFFER, + EGL_PROTECTED_CONTENT_EXT, EGL_VG_COLORSPACE, and EGL_VG_ALPHA_FORMAT." + + Add the following paragraph in section 3.5 on p. 28 before "EGL_VG_COLORSPACE + specifies the color space used by OpenVG" (describing eglCreateWindowSurface + attrib_list): + + "EGL_PROTECTED_CONTENT_EXT specifies the protection state of the window + surface. If its value is EGL_TRUE, then the surface content resides in a + secure memory region. Secure surfaces may be written to by client APIs + using any combination of protected and non-protected input data. EGL and + client APIs will not allow contents of protected surfaces to be accessed + by non-secure devices in the system (including non-secure software + running on the CPU). They will also not allow the contents to be copied + to non-protected surfaces. Copies within a protected surface, or from one + protected surface to another, are allowed. eglSwapBuffers is allowed for + protected surfaces if and only if the window system is able to maintain + the security of the buffer contents. Any disallowed operation will + fail and result in undefined behavior, up to and including program + termination. If EGL_PROTECTED_CONTENT_EXT is EGL_FALSE, then the surface + content can be accessed by secure or non-secure devices and can be copied + to any other surfaces. The definition of secure and non-secure access is + up to the implementation and is out of scope of this specification. The + default value of EGL_PROTECTED_CONTENT_EXT is EGL_FALSE." + + Change the second paragraph in section 3.5 on p. 30 (describing + eglCreatePbufferSurface): + + "Attributes that can be specified in attrib list include EGL_WIDTH, + EGL_HEIGHT, EGL_LARGEST_PBUFFER, EGL_TEXTURE_FORMAT, EGL_TEXTURE_TARGET, + EGL_MIPMAP_TEXTURE, EGL_PROTECTED_CONTENT_EXT, EGL_VG_COLORSPACE, and + EGL_VG_ALPHA_FORMAT." + + Add following the second paragraph in section 3.5 on p. 31 (describing + eglCreatePbufferSurface attrib_list): + + "EGL_PROTECTED_CONTENT_EXT specifies the protection state of the pbuffer + surface. If its value is EGL_TRUE, then the surface content resides in a + secure memory region. Secure surfaces may be written to by client APIs + using any combination of protected and non-protected input data. EGL and + client APIs will not allow contents of protected surfaces to be accessed + by non-secure devices in the system (including non-secure software + running on the CPU). They will also not allow the contents to be copied + to non-protected surfaces. Copies within a protected surface, or from one + protected surface to another, are allowed. Any disallowed operation will + fail and result in undefined behavior, up to and including program + termination. If EGL_PROTECTED_CONTENT_EXT is EGL_FALSE, then the surface + content can be accessed by secure or non-secure devices and can be copied + to any other surfaces. The definition of secure and non-secure access is + up to the implementation and is out of scope of this specification. The + default value of EGL_PROTECTED_CONTENT_EXT is EGL_FALSE." + + Add to Table 3.5: Queryable surface attributes and types on p. 37 + + EGL_PROTECTED_CONTENT_EXT boolean Content protection state + + Add following the second paragraph in section 3.6 on p. 39 (describing + eglQuerySurface): + + "Querying EGL_PROTECTED_CONTENT_EXT returns the content protection state of + the surface. The protection state of window and pbuffer surfaces is specified + in eglCreateWindowSurface and eglCreatePbufferSurface. The protection state of + pixmap and client buffer (pbuffer) surfaces is always EGL_FALSE." + + Add following after "if either draw or read are bound to contexts in another thread, + an EGL_BAD_ACCESS error is generated." in section 3.7.3 p46 (describing eglMakeCurrent + errors): + + "If EGL_PROTECTED_CONTENT_EXT attributes of read is EGL_TRUE and + EGL_PROTECTED_CONTENT_EXT attributes of draw is EGL_FALSE, an + EGL_BAD_ACCESS error is generated." + + Add following after "which must be a valid native pixmap handle." in section 3.9.2 on + p. 53 (describing eglCopyBuffers): + + "If attribute EGL_PROTECTED_CONTENT_EXT of surface has value of EGL_TRUE, then + an EGL_BAD_ACCESS error is returned." + + +Additions to EGL_KHR_image_base extension specification + + Add to section 2.5.1 Table bbb: + + +-----------------------------+-------------------------+---------------+ + | Attribute | Description | Default Value | + +-----------------------------+-------------------------+---------------+ + | EGL_NONE | Marks the end of the | N/A | + | | attribute-value list | | + | EGL_IMAGE_PRESERVED_KHR | Whether to preserve | EGL_FALSE | + | | pixel data | | + | EGL_PROTECTED_CONTENT_EXT | Content protection | EGL_FALSE | + | | state | | + +-----------------------------+-------------------------+---------------+ + Table bbb. Legal attributes for eglCreateImageKHR <attrib_list> parameter + + Add the following paragraph to section 2.5.1 before "Errors" (describing + eglCreateImageKHR): + + "If the value of attribute EGL_PROTECTED_CONTENT_EXT is EGL_TRUE, then + image content is only accessible by secure devices in the system. A + complete definition of secure device is implementation-specific, but at + minimum a secure device must not expose the contents of a protected image + to non-secure devices or allow contents to be copied to non-protected + regions of memory. If an EGL client API cannot make such guarantees, + attempts to create an EGLImage sibling within that client API will fail + with an API-specific error. + + If the value of attribute EGL_PROTECTED_CONTENT_EXT is EGL_FALSE, then the + surface content can be accessed by secure or non-secure devices and can be + copied to any other surfaces." + +Issues + + 1. Should the spec define the behavior of secure and non-secure access? + + PROPOSED: No. Different CPU and GPU architectures have different secure access + implementations. The behavior of secure access violation is also different. Some + architectures will take a CPU exeception. On other architectures, reads will get + zeroes and writes will have no effect. This includes DMA transactions. So it is + better to leave the defination of illegal operation behavior out of this + specification. + + 2. Should the spec enumerate the legal and illegal operations in client APIs + such as OpenGL ES? + + PROPOSED: No. Enumerating these is possible, but is likely to get out of date + as new extensions and client API versions are introduced. Better to state the + principles that determine whether an operation is legal or illegal. If a version + of this extension is promoted to KHR or core status, enumerating the legal + operations because there will be a greater expectation that future extensions + will consider interactions. For OpenGL ES 3.0, a non-normative list of examples + would be: + * glReadPixels is illegal when the READ framebuffer is protected, + * glCopyTexImage2D is illegal when the READ framebuffer is protected, + * glCopyTexSubImage2D is illegal when the READ framebuffer is protected, unless + the target texture is a protected pbuffer, + * glBlitFramebuffer is illegal if the READ framebuffer is protected and the + DRAW framebuffer is not protected. + +Revision History + + Rev. Date Author Changes + ---- -------- -------- ------------------------------------------------- + 7 01/20/14 Jesse Reword PROTECTED_CONTENT descriptions to be more specific + about legality of client API operations. Add issue #2. + 6 01/14/14 Yanjun Change the extension from vendor specific to EXT. Add + EGL_BAD_ACCESS error to eglMakeCurrent, eglCopyBuffers. + 5 01/13/14 Jesse Define illegal operation behavior more broadly. + 4 01/10/14 Pontus Update description of illegal operation behavior in + terms of secure memory region and secure access. + 3 01/03/14 Yanjun Define the GPU and CPU behavior for illegal operations. + 2 12/13/13 Yanjun Prohibit GPU illegal copy from the protected surface to + non-protected surface. + 1 12/11/13 Yanjun Initial draft. diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_stream_consumer_egloutput.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_stream_consumer_egloutput.txt new file mode 100644 index 0000000..61f3b0e --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_stream_consumer_egloutput.txt @@ -0,0 +1,248 @@ +Name + + EXT_stream_consumer_egloutput + +Name Strings + + EGL_EXT_stream_consumer_egloutput + +Contributors + + Daniel Kartch + James Jones + Christopher James Halse Rogers + +Contacts + + Daniel Kartch, NVIDIA (dkartch 'at' nvidia.com) + +Status + + Complete + +Version + + Version 7 - December 28th, 2015 + +Number + + EGL Extension #81 + +Extension Type + + EGL display extension + +Dependencies + + Requires EGL_KHR_stream. + Requires EGL_EXT_output_base. + +Overview + + Increasingly, EGL and its client APIs are being used in place of + "native" rendering APIs to implement the basic graphics + functionality of native windowing systems. This creates demand + for a method to initialize EGL displays and surfaces directly on + top of native GPU or device objects rather than native window + system objects. The mechanics of enumerating the underlying + native devices and constructing EGL displays and surfaces from + them have been solved in various platform and implementation- + specific ways. The EGL device family of extensions offers a + standardized framework for bootstrapping EGL without the use of + any underlying "native" APIs or functionality. + + This extension describes how to bind EGLOutputLayerEXTs as stream + consumers to send rendering directly to a display device without an + intervening window system. + +New Types + + None + +New Functions + + EGLBoolean eglStreamConsumerOutputEXT( + EGLDisplay dpy, + EGLStreamKHR stream, + EGLOutputLayerEXT layer); + +New Tokens + + None + +Replace section "3.10.2.1 No way to connect consumer to EGLStream" in +the EGL_KHR_stream extension with: + + 3.10.2.1 EGLOutputLayerEXT consumer + + Call + + EGLBoolean eglStreamConsumerOutputEXT( + EGLDisplay dpy, + EGLStreamKHR stream, + EGLOutputLayerEXT layer); + + to connect <output> as the consumer of <stream>. + + On failure EGL_FALSE is returned and an error is generated. + + - EGL_BAD_DISPLAY is generated if <dpy> is not a valid, + initialized EGLDisplay. + + - EGL_BAD_STREAM_KHR is generated if <stream> is not a valid + EGLStreamKHR created for <dpy>. + + - EGL_BAD_STATE_KHR is generated if <stream> is not in state + EGL_STREAM_STATE_CREATED_KHR. + + - EGL_BAD_OUTPUT_LAYER_EXT is generated if <layer> is not a + valid EGLOutputLayerEXT created for <dpy>. + + On success, <layer> is bound to <stream>, <stream> is placed in the + EGL_STREAM_STATE_CONNECTING_KHR state, and EGL_TRUE is returned. + Initially, no changes occur to the image displayed on <layer>. When + the <stream> enters state EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR, + <layer> will begin displaying frames, without further action + required on the application's part, as they become available, taking + into account any timestamps, swap intervals, or other limitations + imposed by the stream or producer attributes. + + Modifying the output layer's display mode is outside the scope of + EGL. If the producer does not automatically adjust it's dimensions + to match the consumer, then the caller is responsible for ensuring + that the producer's frame size and the display mode are compatible + before the first frame is placed in the stream. If these are not + compatible, the behavior is implementation dependent, but may not + hang or terminate. Among other possible behaviors, the + implementation may scale or letterbox the frames, post a blank image + to the display, or discard the frames without posting. + + Many display mode setting APIs have a mechanism that restricts + which of their clients can modify output attributes. Since + EGLOutput stream consumers will need to modify output attributes, + they require access to a display mode setting API handle with the + appropriate capabilities. If the application fails to provide + access to such permissions or privileged native objects when creating + the EGLDisplay associated with an output stream consumer and EGL is + not able to acquire them, the behavior of the stream consumer will be + undefined. Similarly, if the application or operating system revokes + the output modification permissions provided to the EGLDisplay, or + revokes permissions from the privileged native objects provided to + the EGLDisplay, future behavior of the stream consumer is undefined. + + If <layer> is rebound to a different stream by a subsequent call + to eglStreamConumerOutputEXT, then <stream> will be placed into the + EGL_STREAM_STATE_DISCONNECTED_KHR state. + +Issues + + 1. What happens to the display if the stream is destroyed while + still connected? + + RESOLVED: The EGLOutputLayer will maintain a reference to the + last frame consumed from the stream until a new frame is + received (through connection of a new stream or some interface + defined by another extension) or until the EGLOutputLayer is + destroyed. Until one of these occurs, the output will ensure + that memory containing the frame remains valid, but will do no + further reprogramming of the display layer state. In the event + the EGLOutputLayer is destroyed, the reference to the frame is + released, and random/invalid images may subsequently be + displayed if the application does not take separate action to + reprogram or disable the display. This behavior should + probably be defined in the EGL_EXT_output_base extension and + be shared regardless of the means by which the displayed image + was posted. + + 2. What happens to the stream if the display output is flipped to a + different image by a mechanism outside EGL? + + RESOLVED: Using native display APIs to directly change the + visible framebuffer while an EGLStream is bound to an + EGLOutputLayer has undefined results which depend on the + implementation, the display capabilities, and the + compatibility of the competing framebuffer sizes and formats. + A partial list of possible outcomes includes one interface + overriding the other, the visible image alternating between + the two frames, or the visible image becoming corrupted or + displaying random memory. + + 3. What happens if the display mode settings are not compatible + with the size and/or format of the incoming frames? + + RESOLVED: The behavior is implementation and device dependent. + The display may not terminate or hang, but otherwise may modify + or ignore the incoming frames. Additional extensions can be + defined if greater control of this behavior is desired. + + 4. How can changes to the display mode settings be synchronized + with changes in the size/format of frames generated by the + producer? + + RESOLVED: The base specification will assume that the + producer's frame size and the output layer's display mode are + established at initialization time and do not change for the + life of the stream. The ability to modify these states and + synchronize such modifications must be provided by additional + extensions. + + 5. The EGL_KHR_stream_producer_eglsurface extension, which is + likely to be used as a producer for streams directed to outputs, + explicitly ignores eglSwapInterval. But a swap interval is + desirable when directing output to a display screen. How can + this functionality be provided? + + RESOLVED: EGL_SWAP_INTERVAL_EXT added as an attribute to output + layers in the EGL_EXT_output_base specification. + + 6. How does EGL acquire the necessary capabilities to modify + display attributes from the application? + + RESOLVED: The application provides EGL with the necessary + permissions or native object handles when creating its EGLDisplay. + + 7. What is the behavior of EGLOutput stream consumers when EGL does + not have the necessary permissions to modify output attributes? + + RESOLVED: The behavior is undefined. Other options would be to + block consumption of frames indefinitely until permissions are + acquired via unspecified or native mechanisms, or to return + frames to the producer immediately when consumption fails due to + lack of permissions. However, both of these options may rely on + assumptions about the behavior of the underlying mode setting + APIs. Future extensions may refined the behavior of streams in + this case. + +Revision History: + + #7 (December 28th, 2015) James Jones + - Added issues 6 and 7. + - Added language to document the resolution of issues 6 and 7. + + #6 (August 22nd, 2014) James Jones + - Marked complete. + - Marked remaining unresolved issues resolved. + - Added an "Extension Type" section. + - Listed Daniel as the contact. + + #5 (June 5th, 2014) Daniel Kartch + - Added resolution for issues 3 and 4 and updated description + accordingly. + + #4 (May 28th, 2014) Daniel Kartch + - Added Issue 5 and its resolution. + + #3 (January 17th, 2014) Daniel Kartch + - Updated issues section with some proposed solutions and new + issues. + + #2 (November 13th, 2013) Daniel Kartch + - Replaced EGLOutputEXT with EGLOutputLayerEXT, as per changes + to EXT_output_base. + - Updated possible error states to reflect requirement that + output handles are now associated with a particular + EGLDisplay. + + #1 (October 28th, 2013) Daniel Kartch + - Initial draft + diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_surface_CTA861_3_metadata.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_surface_CTA861_3_metadata.txt new file mode 100644 index 0000000..50764b5 --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_surface_CTA861_3_metadata.txt @@ -0,0 +1,136 @@ +Name + + EXT_surface_CTA861_3_metadata + +Name Strings + + EGL_EXT_surface_CTA861_3_metadata + +Contact + + Courtney Goeltzenleuchter (courtneygo 'at' google.com) + +Contributors + + James Jones + Weiwan Liu + +IP Status + + No known IP claims. + +Status + + Complete + +Version + + Version 5 - Nov 29, 2016 + +Number + + EGL Extension #117 + +Dependencies + + This extension requires EGL 1.5 and EGL_EXT_surface_SMPTE2086_metadata. + + This extension is written against the wording of the EGL 1.5 specification + (August 27, 2014). + +Overview + + This extension adds additional EGL surface attributes for the metadata + defined by the CTA (Consumer Technology Association) 861.3 standard. + This metadata, in addition to the SMPTE 2086 metadata, is used to define the + color volume of the mastering display as well as the content (CTA-861.3), + The mastering display is the display where creative work is done and creative + intent is established. To preserve such creative intent as much as possible + and achieve consistent color reproduction on different viewing displays, + it is useful for the display pipeline to know the color volume of the + original mastering display where content is created or tuned. This avoids + performing unnecessary mapping of colors that are not displayable on the + original mastering display. + + This extension adds the ability to pass the CTA-861.3 metadata via EGL, + from which the color volume can be derived. While the general purpose of the + metadata is to assist in the transformation between different color volumes + of different displays and help achieve better color reproduction, it is not + in the scope of this extension to define how exactly the metadata should be + used in such a process. It is up to the implementation to determine how to + make use of the metadata. + +New Procedures and Functions + + None. + +New Tokens + + Accepted as attribute by eglSurfaceAttrib and eglQuerySurface: + + EGL_CTA861_3_MAX_CONTENT_LIGHT_LEVEL_EXT 0x3360 + EGL_CTA861_3_MAX_FRAME_AVERAGE_LEVEL_EXT 0x3361 + +Additions to Chapter "3.5.6 Surface Attributes" of the EGL 1.5 Specification + + Add the following paragraph before the "Errors" section on page 43, + + If attribute is EGL_CTA861_3_MAX_CONTENT_LIGHT_LEVEL_EXT or EGL_CTA861_3_- + MAX_FRAME_AVERAGE_LEVEL_EXT, then value indicates the corresponding + maximum content light level and maximum frame average level. + The unit of value is 1 nit (candela per square meter). The + floating-point luminance values should be multiplied by + EGL_METADATA_SCALING, a constant scaling factor of 50000, before being + passed into eglSurfaceAttrib as integers. + + Exactly how the color volume information is used to assist the color + reproduction process is implementation dependant. + + The initial values of EGL_CTA861_3_MAX_CONTENT_LIGHT_LEVEL_EXT and + EGL_CTA861_3_MAX_FRAME_AVERAGE_LEVEL_EXT are EGL_DONT_CARE, which causes the + hints to be ignored. If value is not in the implementation's supported + range for attribute, a EGL_INVALID_VALUE error is generated, and some or + all of the metadata fields are ignored. + + Change the original footnote 12 at the end of section "3.5.6 Surface + Attributes" on page 45 to, + + [13] EGL_DISPLAY_SCALING (10000) and EGL_METADATA_SCALING_EXT (50000) + are used where EGL needs to take or return floating-point attribute + values, which would normally be smaller than 1, as integers while still + retaining sufficient precision to be meaningful. + + Addition to Table 3.5 "Queryable surface attributes and types", + + Attribute Type + ------------------------------------------------ + EGL_CTA861_3_MAX_CONTENT_LIGHT_LEVEL_EXT integer + EGL_CTA861_3_MAX_FRAME_AVERAGE_LEVEL_EXT integer + + Description + -------------------------------------------------------------------------------------- + Maximum content light level in nit multiplied by EGL_METADATA_SCALING_EXT + Maximum frame average light level in nit multiplied by EGL_METADATA_SCALING_EXT + + Add the following paragraph at the end of section "3.5.6 Surface Attributes" + on page 45, + + Querying EGL_CTA861_3_MAX_CONTENT_LIGHT_LEVEL_EXT EGL_CTA861_3_MAX_- + FRAME_AVERAGE_LEVEL_EXT returns respectively the maximum content light level + and maximum frame average level respectively. The values returned are + in units of 1 nit (candela per square meter), multiplied by the constant + value EGL_METADATA_SCALING_EXT (50000). The value of EGL_CTA861_3_MAX_- + CONTENT_LIGHT_LEVEL_EXT and EGL_CTA861_3_MAX_FRAME_AVERAGE_LEVEL_EXT can + be set via eglSurfaceAttrib as described above. + +Errors + + Described in the body text above. + +Issues + +Revision History + + Version 1, 2017/02/28 + - Initial draft + diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_surface_SMPTE2086_metadata.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_surface_SMPTE2086_metadata.txt new file mode 100644 index 0000000..2fa0b2e --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_surface_SMPTE2086_metadata.txt @@ -0,0 +1,247 @@ +Name + + EXT_surface_SMPTE2086_metadata + +Name Strings + + EGL_EXT_surface_SMPTE2086_metadata + +Contact + + Weiwan Liu (weiwliu 'at' nvidia.com) + +Contributors + + Tom Cooksey + Courtney Goeltzenleuchter + Mathias Heyer + Lauri Hyvarinen + James Jones + Daniel Koch + Jeff Leger + Sandeep Shinde + +IP Status + + No known IP claims. + +Status + + Complete + +Version + + Version 8 - Oct 16, 2017 + +Number + + EGL Extension #109 + +Dependencies + + This extension requires EGL 1.4. + + This extension is written against the wording of the EGL 1.5 specification + (August 27, 2014). + +Overview + + This extension adds a new set of EGL surface attributes for the metadata + defined by the SMPTE (the Society of Motion Picture and Television + Engineers) ST 2086 standard. The SMPTE 2086 metadata includes the color + primaries, white point and luminance range of the mastering display, which + all together define the color volume that contains all the possible colors + the mastering display can produce. The mastering display is the display + where creative work is done and creative intent is established. To preserve + such creative intent as much as possible and achieve consistent color + reproduction on different viewing displays, it is useful for the display + pipeline to know the color volume of the original mastering display where + content is created or tuned. This avoids performing unnecessary mapping of + colors that are not displayable on the original mastering display. + + This extension adds the ability to pass the SMPTE 2086 metadata via EGL, + from which the color volume can be derived. While the general purpose of the + metadata is to assist in the transformation between different color volumes + of different displays and help achieve better color reproduction, it is not + in the scope of this extension to define how exactly the metadata should be + used in such a process. It is up to the implementation to determine how to + make use of the metadata. + +New Procedures and Functions + + None. + +New Tokens + + Accepted as attribute by eglSurfaceAttrib and eglQuerySurface: + + EGL_SMPTE2086_DISPLAY_PRIMARY_RX_EXT 0x3341 + EGL_SMPTE2086_DISPLAY_PRIMARY_RY_EXT 0x3342 + EGL_SMPTE2086_DISPLAY_PRIMARY_GX_EXT 0x3343 + EGL_SMPTE2086_DISPLAY_PRIMARY_GY_EXT 0x3344 + EGL_SMPTE2086_DISPLAY_PRIMARY_BX_EXT 0x3345 + EGL_SMPTE2086_DISPLAY_PRIMARY_BY_EXT 0x3346 + EGL_SMPTE2086_WHITE_POINT_X_EXT 0x3347 + EGL_SMPTE2086_WHITE_POINT_Y_EXT 0x3348 + EGL_SMPTE2086_MAX_LUMINANCE_EXT 0x3349 + EGL_SMPTE2086_MIN_LUMINANCE_EXT 0x334A + +Additions to Chapter "3.5.6 Surface Attributes" of the EGL 1.5 Specification + + Add the following paragraph before the "Errors" section on page 43, + + If attribute is EGL_SMPTE2086_DISPLAY_PRIMARY_RX_EXT, EGL_SMPTE2086_- + DISPLAY_PRIMARY_RY_EXT, EGL_SMPTE2086_DISPLAY_PRIMARY_GX_EXT, EGL_- + SMPTE2086_DISPLAY_PRIMARY_GY_EXT, EGL_SMPTE2086_DISPLAY_PRIMARY_BX_EXT + or EGL_SMPTE2086_DISPLAY_PRIMARY_BY_EXT, then value indicates the + corresponding xy chromaticity coordinate[12] of the mastering display's + red, green or blue color primary, as configured for the mastering + process. The floating-point display primary coordinates should be + multiplied by EGL_METADATA_SCALING_EXT (50000)[13], before being passed + into eglSurfaceAttrib as integers. + + If attribute is EGL_SMPTE2086_WHITE_POINT_X_EXT or EGL_SMPTE2086_WHITE_- + POINT_Y_EXT, then value indicates the corresponding xy chromaticity + coordinate[12] of the mastering display's white point, as configured for + the mastering process. The floating-point white point chromaticity + coordinates should be multiplied by EGL_METADATA_SCALING_EXT (50000), + before being passed into eglSurfaceAttrib as integers. + + If attribute is EGL_SMPTE2086_MAX_LUMINANCE_EXT or EGL_SMPTE2086_MIN_- + LUMINANCE_EXT, then value indicates the maximum or minimum display + luminance of the mastering display, as configured for the mastering + process. The unit of value is 1 nit (candela per square meter). The + floating-point luminance values should be multiplied by + EGL_METADATA_SCALING_EXT, a constant scaling factor of 50000, before + being passed into eglSurfaceAttrib as integers. + + By defining the mastering display's color volume through color + primaries, white point, and luminance range, applications give EGL + and the underlying display pipeline hints as to how to reproduce colors + more closely to the original content when created on the mastering + display. Exactly how the color volume information is used to assist the + color reproduction process is implementation dependant. + + The initial values of EGL_SMPTE2086_DISPLAY_PRIMARY_RX_EXT, EGL_- + SMPTE2086_DISPLAY_PRIMARY_RY_EXT, EGL_SMPTE2086_DISPLAY_PRIMARY_GX_EXT, + EGL_SMPTE2086_DISPLAY_PRIMARY_GY_EXT, EGL_SMPTE2086_DISPLAY_PRIMARY_BX_- + EXT, EGL_SMPTE2086_DISPLAY_PRIMARY_BY_EXT, EGL_SMPTE2086_WHITE_POINT_X_- + EXT, EGL_SMPTE2086_WHITE_POINT_Y_EXT, EGL_SMPTE2086_MAX_LUMINANCE_EXT + and EGL_SMPTE2086_MIN_LUMINANCE_EXT are EGL_DONT_CARE, which causes the + hints to be ignored. If value is not in the implementation's supported + range for attribute, a EGL_BAD_PARAMETER error is generated, and some or + all of the metadata fields are ignored. + + Add the following footnote at the end of page 43, and increment all the + subsequent footnote numbers in Chapter 3, + + [12] Chromaticity coordinates x and y are as specified in CIE + 15:2004 "Calculation of chromaticity coordinates" (Section 7.3) and are + limited to between 0 and 1 for real colors for the mastering display. + + Change the original footnote 12 at the end of section "3.5.6 Surface + Attributes" on page 45 to, + + [13] EGL_DISPLAY_SCALING (10000) and EGL_METADATA_SCALING_EXT (50000) + are used where EGL needs to take or return floating-point attribute + values, which would normally be smaller than 1, as integers while still + retaining sufficient precision to be meaningful. + + Addition to Table 3.5 "Queryable surface attributes and types", + + Attribute Type + ------------------------------------------------ + EGL_SMPTE2086_DISPLAY_PRIMARY_RX_EXT integer + EGL_SMPTE2086_DISPLAY_PRIMARY_RY_EXT integer + EGL_SMPTE2086_DISPLAY_PRIMARY_GX_EXT integer + EGL_SMPTE2086_DISPLAY_PRIMARY_GY_EXT integer + EGL_SMPTE2086_DISPLAY_PRIMARY_BX_EXT integer + EGL_SMPTE2086_DISPLAY_PRIMARY_BY_EXT integer + EGL_SMPTE2086_WHITE_POINT_X_EXT integer + EGL_SMPTE2086_WHITE_POINT_Y_EXT integer + EGL_SMPTE2086_MAX_LUMINANCE_EXT integer + EGL_SMPTE2086_MIN_LUMINANCE_EXT integer + + Description + ------------------------------------------------------------------------------------------ + x chromaticity coordinate for red display primary multiplied by EGL_METADATA_SCALING_EXT + y chromaticity coordinate for red display primary multiplied by EGL_METADATA_SCALING_EXT + x chromaticity coordinate for green display primary multiplied by EGL_METADATA_SCALING_EXT + y chromaticity coordinate for green display primary multiplied by EGL_METADATA_SCALING_EXT + x chromaticity coordinate for blue display primary multiplied by EGL_METADATA_SCALING_EXT + y chromaticity coordinate for blue display primary multiplied by EGL_METADATA_SCALING_EXT + x chromaticity coordinate for white point multiplied by EGL_METADATA_SCALING_EXT + y chromaticity coordinate for white point multiplied by EGL_METADATA_SCALING_EXT + Maximum luminance in nit multiplied by EGL_METADATA_SCALING_EXT + Minimum luminance in nit multiplied by EGL_METADATA_SCALING_EXT + + Add the following paragraph at the end of section "3.5.6 Surface Attributes" + on page 45, + + Querying EGL_SMPTE2086_DISPLAY_PRIMARY_RX_EXT, EGL_SMPTE2086_DISPLAY_- + PRIMARY_RY_EXT, EGL_SMPTE2086_DISPLAY_PRIMARY_GX_EXT, EGL_SMPTE2086_- + DISPLAY_PRIMARY_GY_EXT, EGL_SMPTE2086_DISPLAY_PRIMARY_BX_EXT or EGL_- + SMPTE2086_DISPLAY_PRIMARY_BY_EXT returns respectively the xy + chromaticity coordinate of the mastering display's red, green or blue + color primary, multiplied by the constant value EGL_METADATA_SCALING_EXT + (50000). The display primary coordinates can be set via eglSurfaceAttrib + as described above. + + Querying EGL_SMPTE2086_WHITE_POINT_X_EXT, or EGL_SMPTE2086_WHITE_POINT_- + Y_EXT returns respectively the xy chromaticity coordinate of the + mastering display's white point, multiplied by the constant value EGL_- + METADATA_SCALING (50000). The white point coordinates can be set via + eglSurfaceAttrib as described above. + + Querying EGL_SMPTE2086_MAX_LUMINANCE_EXT or EGL_SMPTE2086_MIN_- + LUMINANCE_EXT returns respectively the maximum and minimum display + luminance of the mastering display. The values returned are in units of + 1 nit (candela per square meter), multiplied by the constant value EGL_- + METADATA_SCALING (50000). The value of EGL_SMPTE2086_MAX_LUMINANCE_EXT + and EGL_SMPTE2086_MIN_LUMINANCE_EXT can be set via eglSurfaceAttrib as + described above. + +Errors + + Described in the body text above. + +Issues + + 1. Should this extension define a valid data range for each metadata field? + + RESOLVED: No. It is not in the scope of this extension to define how the + metadata hints should be used in the display pipeline and, as a result, + what the valid data ranges are for the metadata fields. It is + implementation dependant, but related standards, such as SMPTE ST 2086, + can be used as reference. As described in the body, implemetations may + generate a EGL_BAD_PARAMTER error to notify applications that the input + metadata values are invalid or not supported. + +Revision History + + Version 1, 2016/04/22 + - Initial draft + + Version 2, 2016/05/25 + - Rename to EXT and introduce a new scaling factor + + Version 3, 2016/10/19 + - Add an error and revise issue 1 + + Version 4, 2016/11/22 + - Change status to complete + + Version 5, 2016/11/29 + - Add token assigments + + Version 6, 2017/02/28 + - Add 'EXT' suffix to 'EGL_METADATA_SCALING' + + Version 7, 2017/10/13 + - Rename EGL_INVALID_VALUE (which doesn't exist) to EGL_FALSE + + Version 8, 2017/10/16 + - Fix v7 change to use EGL_BAD_PARAMETER as the error code + generated vs. EGL_FALSE which is the expected return value of + the function. + diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_surface_compression.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_surface_compression.txt new file mode 100644 index 0000000..6610017 --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_surface_compression.txt @@ -0,0 +1,289 @@ +Name + + EXT_surface_compression + +Name Strings + + EGL_EXT_surface_compression + +Contributors + + Jan-Harald Fredriksen, Arm + Lisa Wu, Arm + George Liu, Arm + Laurie Hedge, Imagination Technologies + +Contact + + Jan-Harald Fredriksen (jan-harald.fredriksen 'at' arm.com) + +IP Status + + No known IP claims. + +Status + + Complete + +Version + + Version 1 - November 15, 2021 + +Number + + EGL Extension #147 + +Dependencies + + These extensions are written against the wording of the EGL 1.5 + specification (August 27, 2014). + + This extension interacts with EGL_EXT_yuv_surface. + +Overview + + Applications may wish to take advantage of framebuffer compression. Some + platforms may support framebuffer compression at fixed bitrates. Such + compression algorithms generally produce results that are visually lossless, + but the results are typically not bit exact when compared to a non-compressed + result. + + This extension enables applications to opt-in to fixed-rate compression + for EGL window surfaces. + + Compression may not be supported for all framebuffer formats. It can still + be requested for all formats and applications can query what level of compression + was actually enabled. + +New Procedures and Functions + + EGLBoolean eglQuerySupportedCompressionRatesEXT( + EGLDisplay dpy, EGLConfig config, const EGLAttrib *attrib_list, + EGLint *rates, EGLint rate_size, EGLint *num_rates); + +New Tokens + + New attributes accepted by the <attrib_list> argument of + eglCreatePlatformWindowSurface and eglCreateWindowSurface: + EGL_SURFACE_COMPRESSION_EXT 0x34B0 + + [Only if EGL_EXT_yuv_surface is supported] + EGL_SURFACE_COMPRESSION_PLANE1_EXT 0x328E + EGL_SURFACE_COMPRESSION_PLANE2_EXT 0x328F + + Accepted as attribute values for EGL_SURFACE_COMPRESSION_EXT by + eglCreatePlatformWindowSurface and eglCreateWindowSurface: + EGL_SURFACE_COMPRESSION_FIXED_RATE_NONE_EXT 0x34B1 + EGL_SURFACE_COMPRESSION_FIXED_RATE_DEFAULT_EXT 0x34B2 + + EGL_SURFACE_COMPRESSION_FIXED_RATE_1BPC_EXT 0x34B4 + EGL_SURFACE_COMPRESSION_FIXED_RATE_2BPC_EXT 0x34B5 + EGL_SURFACE_COMPRESSION_FIXED_RATE_3BPC_EXT 0x34B6 + EGL_SURFACE_COMPRESSION_FIXED_RATE_4BPC_EXT 0x34B7 + EGL_SURFACE_COMPRESSION_FIXED_RATE_5BPC_EXT 0x34B8 + EGL_SURFACE_COMPRESSION_FIXED_RATE_6BPC_EXT 0x34B9 + EGL_SURFACE_COMPRESSION_FIXED_RATE_7BPC_EXT 0x34BA + EGL_SURFACE_COMPRESSION_FIXED_RATE_8BPC_EXT 0x34BB + EGL_SURFACE_COMPRESSION_FIXED_RATE_9BPC_EXT 0x34BC + EGL_SURFACE_COMPRESSION_FIXED_RATE_10BPC_EXT 0x34BD + EGL_SURFACE_COMPRESSION_FIXED_RATE_11BPC_EXT 0x34BE + EGL_SURFACE_COMPRESSION_FIXED_RATE_12BPC_EXT 0x34BF + +Modifications to the EGL 1.5 Specification + + Modify section 3.5.1 "Creating On-Screen Rendering Surfaces: + + Add EGL_SURFACE_COMPRESSION_EXT to the list of attributes that can + be specified in <attrib_list> for eglCreatePlatformWindowSurface. + + Add the following paragraph: + + EGL_SURFACE_COMPRESSION_EXT specifies the fixed-rate compression that may + be enabled for rendering to the window. + If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_NONE_EXT, then fixed-rate + compression is disabled. + If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_DEFAULT_EXT, + then the implementation may enable compression at a default, + implementation-defined, rate. + If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_1BPC_EXT, then the + implementation may enable fixed-rate compression with a bitrate of at + least 1 bit and less than 2 bits per component. + If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_2BPC_EXT, then the + implementation may enable fixed-rate compression with a bitrate of at + least 2 bits and less than 3 bits per component. + If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_3BPC_EXT, then the + implementation may enable fixed-rate compression with a bitrate of at + least 3 bits and less than 4 bits per component. + If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_4BPC_EXT, then the + implementation may enable fixed-rate compression with a bitrate of at + least 4 bits and less than 5 bits per component. + If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_5BPC_EXT, then the + implementation may enable fixed-rate compression with a bitrate of at + least 5 bits and less than 6 bits per component. + If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_6BPC_EXT, then the + implementation may enable fixed-rate compression with a bitrate of at + least 6 bits and less than 7 bits per component. + If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_7BPC_EXT, then the + implementation may enable fixed-rate compression with a bitrate of at + least 7 bits and less than 8 bits per component. + If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_8BPC_EXT, then the + implementation may enable fixed-rate compression with a bitrate of at + least 8 bits and less than 9 bits per component. + If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_9BPC_EXT, then the + implementation may enable fixed-rate compression with a bitrate of at + least 9 bits and less than 10 bits per component. + If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_10BPC_EXT, then the + implementation may enable fixed-rate compression with a bitrate of at + least 10 bits and less than 11 bits per component. + If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_11BPC_EXT, then the + implementation may enable fixed-rate compression with a bitrate of at + least 11 bits and less than 12 bits per component. + If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_12BPC_EXT, then the + implementation may enable fixed-rate compression with a bitrate of at + least 12 bits per component. + + For pixel formats with different number of bits per component, the + specified fixed-rate compression rate applies to the component with + the highest number of bits. + + The default value of EGL_SURFACE_COMPRESSION_EXT is + EGL_SURFACE_COMPRESSION_FIXED_RATE_NONE_EXT. + + [Only if EGL_EXT_yuv_surface is supported] + + If _config_ describes a surface with multiple planes (the + value of the EGL_YUV_NUMBER_OF_PLANES_EXT attribute is larger than one), + then the fixed-rate compression rate can be specified independently for + the each plane. + In this case, EGL_SURFACE_COMPRESSION_EXT specifies the fixed-rate + compression that may be enabled for rendering to plane 0, + EGL_SURFACE_COMPRESSION_PLANE1_EXT specifies the fixed-rate + compression that may be enabled for rendering to plane 1, and + EGL_SURFACE_COMPRESSION_PLANE2_EXT specifies the fixed-rate compression + that may be enabled for rendering to plane 2. + The supported values of EGL_SURFACE_COMPRESSION_PLANE1_EXT and + EGL_SURFACE_COMPRESSION_PLANE2_EXT are the same as for + EGL_SURFACE_COMPRESSION_EXT. + + If _config_ has more than one plane and the + EGL_SURFACE_COMPRESSION_PLANE1_EXT attribute is not specified, + then the value of EGL_SURFACE_COMPRESSION_EXT is used for all planes. + If _config_ has more than two planes and the + EGL_SURFACE_COMPRESSION_PLANE2_EXT attribute is not specified, + then the value of EGL_SURFACE_COMPRESSION_PLANE1_EXT is also used + for plane 2. + + The default value of EGL_SURFACE_COMPRESSION_PLANE1_EXT and + EGL_SURFACE_COMPRESSION_PLANE2_EXT is EGL_SURFACE_COMPRESSION_FIXED_RATE_NONE_EXT. + + Modify section 3.5.6 "Surface Attributes" + + Add entries to Table 3.5 "Queryable surface attributes and types": + + EGL_SURFACE_COMPRESSION_EXT enum Fixed-rate compression + + [Only if EGL_EXT_yuv_surface is supported] + EGL_SURFACE_COMPRESSION_PLANE1_EXT enum Fixed-rate compression for plane 1 + EGL_SURFACE_COMPRESSION_PLANE2_EXT enum Fixed-rate compression for plane 2 + + Add the following paragraph: + + Querying EGL_SURFACE_COMPRESSION_EXT returns the actual fixed-rate + compression applied to a surface. For YUV surfaces, the value applied to + the luma plane is returned. This value may be different to the one + requested when the surface was created. + For pbuffer and pixmap surfaces, the contents of <value> are not modified." + + [Only if EGL_EXT_yuv_surface is supported] + Querying EGL_SURFACE_COMPRESSION_PLANE1_EXT returns the actual + fixed-rate compression applied to plane 1 of a YUV surface. + Querying EGL_SURFACE_COMPRESSION_PLANE2_EXT returns the actual + fixed-rate compression applied to plane 2 of a YUV surface. + These values may be different to the one requested when the surface was created. + For pbuffer and pixmap surfaces, the contents of <value> are not modified." + + To get the list of all fixed-rate compression rates that are available on + a specified display and EGLConfig, call + + EGLBoolean eglQuerySupportedCompressionRatesEXT( + EGLDisplay dpy, EGLConfig config, const EGLAttrib *attrib_list, + EGLint *rates, EGLint rate_size, EGLint *num_rates); + + <attrib_list> specifies a list of attributes that will be provided when a surface is created with + this combination of display and EGLConfig. The accepted attributes are the same as for + eglCreatePlatformWindowSurface. + <rates> is a pointer to a buffer containing <rate_size> elements. On success, EGL_TRUE is + returned. The number of rates is returned in <num_rates>, and elements 0 through <num_rates>-1 of + <rates> are filled in with the available compression rates. + No more than <rate_size> compression rates will be returned even if more are available + on the specified display and config. However, if eglQuerySupportedCompressionRatesEXT is called with + <rates> = NULL, then no rates are returned, but the total number of rates available will be returned + in <num_rates>. + The possible values returned in <rates> are the attribute values accepted for + EGL_SURFACE_COMPRESSION_EXT by eglCreatePlatformWindowSurface and eglCreateWindowSurface, except + EGL_SURFACE_COMPRESSION_FIXED_RATE_NONE_EXT and EGL_SURFACE_COMPRESSION_FIXED_RATE_DEFAULT_EXT. + +Errors + + [Only if EGL_EXT_yuv_surface is supported] + Add to the error section of eglCreatePlatformWindowSurface: + + If the EGL_SURFACE_COMPRESSION_PLANE1_EXT attribute is specified and + _config_ does not describe a surface with at least 2 planes (the + EGL_YUV_NUMBER_OF_PLANES_EXT attribute is not greater than or + equal to 2), an EGL_BAD_MATCH error is generated. + + If the EGL_SURFACE_COMPRESSION_PLANE2_EXT attribute is specified and + _config_ does not describe a surface with at least 3 planes (the + EGL_YUV_NUMBER_OF_PLANES_EXT attribute is not greater than or + equal to 3), an EGL_BAD_MATCH error is generated. + + Add to the section describing eglQuerySupportedCompressionRatesEXT: + + * On failure, EGL_FALSE is returned. + * An EGL_NOT_INITIALIZED error is generated if EGL is not initialized on <dpy>. + * An EGL_BAD_PARAMETER error is generated if <num_rates> is NULL. + +Issues + + 1. Should fixed-rate compression be supported for pixmap or pbuffer + surfaces? + + No, no use-cases have been identified for this. + + 2. What is the result of querying EGL_SURFACE_COMPRESSION_EXT if + EGL_SURFACE_COMPRESSION_FIXED_RATE_DEFAULT_EXT was requested? + + Resolved. + The result will be the specific compression ratio chosen by the + implementation, or EGL_SURFACE_COMPRESSION_FIXED_RATE_NONE_EXT if + no fixed-rate compression was applied. + + 3. Should we expose different compressions rates per plane in this extension? + + Yes. + + 4. How can an application query the set of supported compression rates? + + Resolved. Option B. + + Two options were considered. + + Option A: + Reuse eglGetConfigAttrib(EGLDisplay dpy, EGLConfig config, EGLint attribute, EGLint *value); + + This is not ideal because: + - the compression modes are currently tied to the surface, not the EGLConfig + - we don't want this to affect EGLConfig selection etc. + - this query can only return a single value, so you'd need to query each of the + 12 bit rates separately. + + Option B: + Add a new query, specifically for the compression rates. This addresses the concerns + with Option A, and is very similar to the mechanism used for the OpenGL ES API. Main + downside is that it adds additional functions to the API. + +Revision History + + Version 1, 2021/11/15 + - Internal revisions diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_swap_buffers_with_damage.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_swap_buffers_with_damage.txt new file mode 100644 index 0000000..7a1f7fc --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_swap_buffers_with_damage.txt @@ -0,0 +1,343 @@ +Name + + EXT_swap_buffers_with_damage + +Name Strings + + EGL_EXT_swap_buffers_with_damage + +IP Status + + No known IP claims. + +Contributors + + Robert Bragg + Tapani Pälli + Kristian Høgsberg + Benjamin Franzke + Ian Stewart + James Jones + +Contacts + + Robert Bragg, Intel (robert.bragg 'at' intel.com) + +Status + + Published + +Version + + Version 11, February 20, 2020 + +Number + + EGL Extension #55 + +Dependencies + + Requires EGL 1.4 + + This extension is written against the wording of the EGL 1.4 + Specification. + +Overview + + This extension provides a means to issue a swap buffers request to + display the contents of the current back buffer and also specify a + list of damage rectangles that can be passed to a system + compositor so it can minimize how much it has to recompose. + + This should be used in situations where an application is only + animating a small portion of a surface since it enables the + compositor to avoid wasting time recomposing parts of the surface + that haven't changed. + +New Procedures and Functions + + EGLBoolean eglSwapBuffersWithDamageEXT ( + EGLDisplay dpy, + EGLSurface surface, + const EGLint *rects, + EGLint n_rects); + +New Tokens + + None + +Changes to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors) + + Add the following text to subsection 3.9.1 titled "Posting to a + Window" after the description of eglSwapBuffers. + + As an alternative to eglSwapBuffers use: + + EGLBoolean eglSwapBuffersWithDamageEXT ( + EGLDisplay dpy, + EGLSurface surface, + const EGLint *rects, + EGLint n_rects); + + to do the same thing as eglSwapBuffers but additionally report + a list of rectangles that define the region that has truly + changed since the last frame. To be clear; the entire contents + of the back buffer will still be swapped to the front so + applications using this API must still ensure that the entire + back buffer is consistent. The rectangles are only a hint for + the system compositor so it can avoid recomposing parts of the + surface that haven't really changed. + <rects> points to a list of integers in groups of four that + each describe a rectangle in screen coordinates in this + layout: {x, y, width, height}. The rectangles are specified + relative to the bottom-left of the surface and the x and y + components of each rectangle specify the bottom-left position + of that rectangle. <n_rects> determines how many groups of 4 + integers can be read from <rects>. It is not necessary to + avoid overlaps of the specified rectangles. + If <n_rects> is 0 then <rects> is ignored and the entire + surface is implicitly damaged and the behaviour is equivalent + to calling eglSwapBuffers. + The error conditions checked for are the same as for the + eglSwapBuffers api. + + Modify the first paragraph of Section 3.9.1 titled "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 eglSwapBuffersWithDamageEXT must + detect the change and resize surface prior to copying its + pixels to the native window. In this case the meaningfulness + of any damage rectangles forwarded by + eglSwapBuffersWithDamageEXT to the native window system is + undefined." + + 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, + eglSwapBuffersWithDamageEXT, 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 eglSwapBuffersWithDamageEXT, 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); + + specifies 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 eglSwapBuffersWithDamageEXT 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, eglSwapBuffersWithDamageEXT, and + eglCopyBuffers return EGL_FALSE on failure." + + Paragraph 1, seventh sentence: + + "If eglSwapBuffers or eglSwapBuffersWithDamageEXT are called + and the native window associated with <surface> is no longer + valid, an EGL_BAD_NATIVE_WINDOW error is generated. If + eglSwapBuffersWithDamageEXT is called and <n_rects>, is less + than zero or <n_rects> is greater than zero but <rects> is + NULL, EGL_BAD_PARAMETER is generated." + +Dependencies on OpenGL ES + + None + +Dependencies on OpenVG + + None + +Issues + +1) Do applications have to make sure the rectangles don't overlap? + + RESOLVED: No, that would be inconvenient for applications and we + see no difficulty for implementations to supporting overlapping + rectangles. + +2) Would it be valid for an implementation to discard the list of + rectangles internally and work just in terms of the + eglSwapBuffers api? + + RESOLVED: Yes, the rectangles are only there for optimization + purposes so although it wouldn't be beneficial to applications if + it was convenient at times then it would be compliant for an + implementation to discard the rectangles and just call + eglSwapBuffers instead. The error conditions that should be + checked for are compatible with the requirements for + eglSwapBuffers. + +3) What origin should be used for damage rectangles? + + RESOLVED: Bottom left since this is consistent with all other + uses of 2D window coordinates in EGL and OpenGL that specify a + bottom left origin. + + Originally this specification was written with a top-left origin + for the damage rectangles even though it was known to be + inconsistent and that was because most window systems use a + top-left origin and there are some awkward semantic details + related to handling native window resizing that we had hoped to + simplify. + + This extension and also several other existing EGL extensions + struggle to guarantee a reliable behaviour in response to native + window resizing which can happen asynchronously on some platforms + and this can make it difficult for applications to avoid certain + visual artefacts. + + The crux of the problem is that when a native window is + asynchronously resized then the window system may maintain the old + buffer contents with respect to a different origin than EGL's + bottom left origin. For this extension that means that EGL damage + rectangles that are intended to map to specific surface contents + may end up mapping to different contents when a native window is + resized because the rectangles and buffer contents will be moved in + different directions in relation to the new window size. + + In the end we decided that this issue isn't simply solved by + choosing to use a top-left origin and so we can instead aim for + consistency and clarify what guarantees we offer in relation to + native window resizing separate from this issue. + +4) What guarantees do we provide about the meaningfulness of EGL + damage rectangles that are forwarded to the native window system + when presenting to a native window that has been resized? + + RESOLVED: The meaningfulness of those forwarded damage rectangles + is undefined since this simplifies the implementation requirements + and we saw very little benefit to applications from providing + stricter guarantees. + + The number of applications that would be able to avoid fully + redrawing the contents of a window in response to a window resize + is expected to be so low that there would be almost no benefit to + defining strict guarantees here. + + Since EGL already states that the contents of window surface + buffers become undefined when a native window has been resized, + this limitation doesn't introduce any new issue for applications + to consider. Applications should already fully redraw buffer + contents in response to a native window resize, unless they are + following some platform specific documentation that provides + additional guarantees. + + For an example of the implementation details that make this an + awkward issue to provide guarantees for we can consider X11 based + platforms where native windows can be resized asynchronously with + respect to a client side EGL surface: + + With X11 there may be multiple "gravity" transformations that can + affect how surface buffer content is positioned with respect to a + new native window size; there is the core X "bit gravity" and + there is the EGL driver gravity that determines how a surface's + contents with one size should be mapped to a native window with a + different size. Without very careful cooperation between the EGL + driver and the core X implementation and without the right + architecture to be able to do transforms atomically with respect + to different clients that may enact a window resize then it is not + possible to reliably map EGL damage rectangles to native window + coordinates. + + The disadvantage of a driver that is not able to reliably map EGL + damage rectangles to native window coordinates is that a native + compositor may re-compose the wrong region of window. This may + result in a temporary artefact until the full window gets redrawn + and then re-composed. X11 already suffers other similar transient + artefacts when resizing windows. + + The authors of this spec believe that even if a driver can't do + reliable mappings of EGL damage rectangles then compositors would + be able mitigate the majority of related artefacts by ignoring + sub-window damage during an interactive window resize. + + The authors of this spec believe that that if an X11 driver did + want to reliably map EGL damage rectangles to the native window + coordinates then that may be technically feasible depending on the + driver architecture. For reference one approach that had been + considered (but not tested) is as follows: + + 1) When eglSwapBuffersWithDamageEXT is called, send EGL damage + rectangles from the client to a driver component within the + xserver un-transformed in EGL window surface coordinates with a + bottom-left origin. + + 2) Within the X server the driver component should look at the + bit-gravity of a window and use the bit-gravity convention to + copy EGL surface content to the front-buffer of a native window. + + 3) Within the X server the driver component should use the same + gravity transform that was used to present the surface content + to also transform the EGL damage rectangle coordinates. + + Note that because this transform is done in the xserver then + this is implicitly synchronized with all clients that would + otherwise be able to enact an asynchronous window resize. + + +Revision History + + Version 1, 29/07/2011 + - First draft + Version 2, 03/08/2011 + - Clarify that the rectangles passed may overlap + Version 3, 01/09/2011 + - Fix a missing '*' in prototype to make rects a pointer + Version 4, 11,02,2012 + - Clarify that implementing in terms of eglSwapBuffers would be + compliant. + Version 5, 11,02,2012 + - Tweak the cases where we report BAD_PARAMETER errors + Version 6, 05/02/2013 + - Specify more thorough updates across the EGL 1.4 spec + wherever it relates to the eglSwapBuffers api + - Clarify that passing <n_rects> of 0 behaves as if + eglSwapBuffers were called. + Version 7, 14/02/2013 + - Specify that a bottom-left origin should be used for rectangles + Version 8, 19/03/2013 + - Add Ian and James as contributors + - Add an issue explaining why we changed to a bottom-left origin + - Clarify that the behaviour is undefined when presenting to a + native window that has been resized. + - Document the awkward details that would be involved in + providing more strict guarantees when presenting to a native + window that has been resized. + Version 9, 12/06/2013, Chad Versace <chad.versace@intel.com> + - Remove the "all rights reserved" clause from the copyright notice. The + removal does not change the copyright notice's semantics, since the + clause is already implied by any unadorned copyright notice. But, the + removal does diminish the likelihood of unwarranted caution in readers + of the spec. + - Add "IP Status" section to explicitly state that this extension has no + knonw IP claims. + Version 10, 23/10/2014, Jon Leech + - Remove copyright after signoff from Intel. + Version 11, 20/02/2020, Jon Leech + - Constify rects parameter (EGL-Registry issue 98). diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_sync_reuse.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_sync_reuse.txt new file mode 100644 index 0000000..4c8ebb1 --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_sync_reuse.txt @@ -0,0 +1,376 @@ +Name + + EXT_sync_reuse + +Name Strings + + EGL_EXT_sync_reuse + +Contributors + + Daniel Kartch + Jeff Vigil + Ray Smith + +Contacts + + Daniel Kartch, NVIDIA Corporation (dkartch 'at' nvidia.com) + +Status + + Complete + +Version + + Version 4, May 16, 2018 + +Number + + EGL Extension #128 + +Extension type + + EGL display extension + +Dependencies + + Requires EGL 1.5 or EGL 1.4 with EGL_KHR_fence_sync + + Interacts with EGL_KHR_reusable_sync + Interacts with EGL_ANDROID_native_fence_sync + Interacts with EGL_NV_cuda_event + + This extension is written against the wording of the EGL 1.5 + Specification. + +Overview + + The original EGLSync extensions separated sync objects into two + types: fence sync objects signaled by one time events in an + API command pipeline; and reusable sync objects signaled by commands + which can be issued again and again. However, this conflates + reusability of the event triggering a sync object with the EGLSync + object itself. + + Although the event associated with a fence sync object will only + occur once, there is no reason that it can't be replaced with a new + event. Doing so would avoid unnecessary allocation and free + operations in an application that repeatedly waits for events. With + the current interfaces, such applications must constantly create and + destroy new EGLSync objects. + + This extension allows all sync objects to be reusable. When a sync + object is in the signaled state, it can be reset back to an + unsignaled state, regenerating or reevaluating the events that + trigger them. For fence sync objects, this means generating a new + fence in the current API. For OpenCL event sync objects, this means + waiting for a new OpenCL event handle. This mechanism also allows + sync objects to be created in the signaled state with no associated + fence/event, and have one applied later. Thus all EGLSyncs required + by an application can be allocated up front, before any rendering + operations have begun. + +New Types + + None + +New Tokens + + None + +New Procedures and Functions + + EGLBoolean eglUnsignalSyncEXT( + EGLDisplay dpy, + EGLSync sync, + const EGLAttrib *attrib_list); + +Replace text of subsections of 3.8.1 through 3.8.1.2 of EGL 1.5 +Specification. Existing tables are preserved. + + 3.8.1 Sync Objects + + In addition to the aforementioned synchronization functions, which + provide an efficient means of serializing client and native API + operations within a thread, <sync objects> are provided to enable + synchronization of client API operations between threads and/or + between API contexts. Sync objects may be tested or waited upon by + application threads. + + Sync objects have a status with two possible states: <signaled> and + <unsignaled>, and may initially be in either state. EGL may be asked + to wait for a sync object to become signaled, or a sync objects + status may be queried. + + Depending on the type of a sync object, its status may be changed + either by an external event, or by explicitly signaling and/or + unsignaling the sync. All sync objects are reusable. Once they enter + the signaled state, they may be changed back to unsignaled, possibly + replacing the associated external event that signals them. + + Sync objects are associated with an EGLDisplay when they are + created, and have <attributes> defining additional aspects of the + sync object. All sync objects include attributes for their type and + their status. Additional attributes are discussed below for + different types of sync objects. If a sync object is created in the + signaled state, its initial attribute list may be incomplete, with + attributes necessary for its type provided when it is changed to + unsignaled. + + <Fence sync objects> have an associated fence command in a client + API. A new fence command is generated whenever the sync object + enters the unsignaled state. When the client API executes the fence + command, an event is generated which signals the corresponding fence + sync object. Fence sync objects may not be explicitly signaled. + Fence sync objects may be used to wait for partial completion of a + client API command stream, as a more flexible form of glFinish or + vgFinish. + + An <OpenCL event sync object> reflects the status of a corresponding + OpenCL event object to which the sync object is linked. This + provides another method of coordinating sharing of images between + EGL and OpenCL (see Chapter 9 of the OpenCL 1.0 Specification and + the cl_khr_egl_image extension). Waiting on such a sync object is + equivalent to waiting for completion of the linked OpenCL event + object. + + The command + + EGLSync eglCreateSync(EGLDisplay dpy, EGLenum type, const + EGLAttrib *attrib_list); + + creates a sync object of the specified <type> associated with the + specified display <dpy>, and returns a handle to the new object. + <attrib list> is NULL or an attribute-value list specifying other + attributes of the sync object, terminated by an attribute entry + EGL_NONE. Attributes not specified in the list will be assigned + their default values. + + The EGL_SYNC_STATUS attribute is defined for all sync types, but may + only be specified explicitly at creation time for some types of sync + objects, as discussed below. Other attributes are only allowed as + indicated below for the sync type. + + Errors + + eglCreateSync returns EGL_NO_SYNC on failure. + If <dpy> is not the name of a valid, initialized EGLDisplay, an + EGL_BAD_DISPLAY error is generated. + If <attrib_list> contains an attribute name not defined or not + allowed for the type of sync object being created, an + EGL_BAD_ATTRIBUTE error is generated. + If <type> is not a supported type of sync object, an + EGL_BAD_PARAMETER error is generated. + If <type> is EGL_SYNC_FENCE, the EGL_SYNC_STATUS attribute is + set to EGL_UNSIGNALED, and any of the following are true of the + current context for the bound API (the context returned by + eglGetCurrentContext), an EGL_BAD_MATCH error is generated: + * There is no current context (i.e., eglGetCurrentContext + returns EGL_NO_CONTEXT). + * <dpy> does not match the EGLDisplay of the context (the + EGLDisplay returned by eglGetCurrentDisplay). + * The context does not support fence commands. + + While in the unsignaled state, the synchronization event associated + with a sync object cannot be changed. When the <condition> of a sync + object in the unsignaled state is satisfied, the sync is signaled, + causing any eglClientWaitSync or eglWaitSync commands (see below) + blocking on the sync to unblock. + + Once signaled, a sync object may be reused for a new synchronization + event by switching it back to unsignaled. The command + + EGLBoolean eglUnsignalSyncEXT(EGLDisplay dpy, EGLSync sync, + const EGLAttrib *attrib_list); + + can be used to change the <sync> associated with display <dpy> from + the signaled state to the unsignaled state. The attribute list may + be used to provide or replace attributes specific to the sync type + as discussed below. The sync object's type and condition may not be + changed. + + Errors + + eglUnsignalSyncEXT returns EGL_FALSE on failure, and has no + effect on <sync>. + If <dpy> is not the name of a valid, initialized EGLDisplay, an + EGL_BAD_DISPLAY error is generated. + If <sync> is not a valid sync object associated with <dpy>, an + EGL_BAD_PARAMETER error is generated. + If <attrib_list> contains an attribute name not defined for the + type of <sync>, an EGL_BAD_ATTRIBUTE error is generated. + If <sync> is already in the unsignaled state, an EGL_BAD_ACCESS + error is generated. + If <sync>'s type is EGL_SYNC_FENCE and any of the following are + true of the current context for the bound API (the context + returned by eglGetCurrentContext), an EGL_BAD_MATCH error is + generated: + * There is no current context (i.e., eglGetCurrentContext + returns EGL_NO_CONTEXT). + * <dpy> does not match the EGLDisplay of the context (the + EGLDisplay returned by eglGetCurrentDisplay). + * The context does not support fence commands. + If <sync>'s type is EGL_SYNC_CL_EVENT and EGL_CL_EVENT_HANDLE + is not specified in <attrib_list>, then an EGL_BAD_ATTRIBUTE + error is generated. + + 3.8.1.1 Creating and Signaling Fence Sync Objects + + If type is EGL_SYNC_FENCE, a fence sync object is created. The + EGL_SYNC_STATUS attribute may be specified as either EGL_UNSIGNALED + or EGL_SIGNALED, and will default to EGL_UNSIGNALED. No other + attributes may be specified for a fence sync object, either with + eglCreateSync or eglUnsignalSyncEXT. Queriable attributes of the + fence sync object are set as shown in table 3.7. + + When a fence sync object is created in the unsignaled state, or + switched to that state with eglUnsignalSyncEXT, a fence command is + inserted into the command stream of the bound client APIs current + context (i.e., the context returned by eglGetCurrentContext), and is + associated with the sync object. + + The only condition supported for fence sync objects is + EGL_SYNC_PRIOR_COMMANDS_COMPLETE, which is satisfied by completion + of the fence command corresponding to the sync object, and all + preceding commands in the associated client API contexts command + stream. The sync object will not be signaled until all effects from + these commands on the client APIs internal and framebuffer state + are fully realized. No other state is affected by execution of the + fence command. + + Generation of fence commands for fence sync objects requires support + from the bound client API, and will not succeed unless the client + API satisfies one of the following properties. Note that eglWaitSync + (see section 3.8.1.3) also requires satisfying these conditions. + * client API is OpenGL, and either the OpenGL version is 3.2 or + greater, or the GL_ARB_sync extension is supported. + * client API is OpenGL ES, and either the OpenGL ES version is 3.0 + or greater, or the GL_OES_EGL_sync extension is supported. + * client API is OpenVG, and the VG_KHR_EGL_sync extension is + supported. + + 3.8.1.2 Creating and Signaling OpenCL Event Sync Objects + + If type is EGL_SYNC_CL_EVENT, an OpenCL event sync object is + created. The EGL_SYNC_STATUS attribute may not be explicitly + specified during creation of this type of sync object. If no + EGL_CL_EVENT_HANDLE attribute is specified at creation time, the + sync object will be created in the signaled state. Otherwise its + status will be determined by the provided OpenCL event, as described + below. An EGL_CL_EVENT_HANDLE must always be specified for + eglUnsignalSyncEXT. + + To use an OpenCL event sync object, the EGL_SYNC_CL_EVENT attribute + must be set to a valid OpenCL <event> handle returned by a call to + clEnqueueReleaseGLObjects or clEnqueueReleaseEGLObjects; other types + of OpenCL event handles are not supported. Implementations are not + required to validate the OpenCL event, and passing an invalid event + handle in <attrib_list> may result in undefined behavior up to and + including program termination. Note that EGL_CL_EVENT_HANDLE is not + a queriable property of a sync object. Queriable attributes of the + OpenCL event sync object are set as shown in table 3.8. + + The status of such a sync object depends on <event>. When the status + of <event> is CL_QUEUED, CL_SUBMITTED, or CL_RUNNING, the status of + the linked sync object will be EGL_UNSIGNALED. When the status of + <event> changes to CL_COMPLETE, the status of the linked sync object + will become EGL_SIGNALED. + + The only condition supported for OpenCL event sync objects is + EGL_SYNC_CL_EVENT_COMPLETE, which is satisfied when the status of + the OpenCL event associated with the sync object changes to + CL_COMPLETE. + + Associating an OpenCL event handle with a sync object places a + reference on the linked OpenCL object. When the sync object is + deleted or the event handle is replaced, the reference will be + removed from the OpenCL object. + +If EGL_KHR_reusable_sync is present, then for sync objects of type +EGL_SYNC_REUSABLE_KHR, the initial value of EGL_SYNC_STATUS may be +set to either EGL_UNSIGNALED or EGL_SIGNALED, and will default to +EGL_UNSIGNALED. + +If EGL_ANDROID_native_fence_sync is present, then for native fence sync +objects, the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute may be specified +in eglUnsignalSyncEXT as well as eglCreateSync. If it is set to anything +other than EGL_NO_NATIVE_FENCE_FD_ANDROID at creation time, then its +initial EGL_SYNC_STATUS will reflect the current status of the provided +fence FD, and it is an error to specifically set the status. If it is +set to EGL_NO_NATIVE_FENCE_FD_ANDROID, then its EGL_SYNC_STATUS may be +set to either EGL_UNSIGNALED (the default) or EGL_SIGNALED. If the +status is signaled, then no native fence will be generated until after +it is switched to unsignaled. If eglUnsignalSyncEXT is called for a +native fence sync object with an FD of EGL_NO_NATIVE_FENCE_FD_ANDROID, +then a new native fence will be generated at the next Flush(), as +described for eglCreateSync. + +If EGL_NV_cuda_event is present, then for CUDA event sync objects, the +EGL_CUDA_EVENT_HANDLE_NV may be specified in eglUnsignalSyncEXT as well +as eglCreateSync. The current CUDA event handle is evaluated at the time +the EGL sync object becomes unsignaled, and subsequent modification of +the CUDA object with cudaEventRecord has no effect on the sync object +until it is signaled. Subsequently restoring the sync object to +unsignaled will cause the CUDA object to be reevaluated. + +Issues + + 1. Should a new attribute be required to specify a sync object as + reusable? + + RESOLVED: No. The presence of this extension is sufficient to + indicate reusability of all sync objects. This will not create + any incompatibilities with existing applications that use sync + objects only once. + + 2. Can we leverage the existing eglSignalSyncKHR function from + EGL_KHR_reusable_sync for this extension? + + RESOLVED: No. Some types of sync objects require attributes + which are themselves single-use objects, and must be replaced + for the sync object to be reused. Therefore a new function which + takes an attribute list is required. + + 3. Should the function for unsignaling be based on eglSignalSyncKHR + from the KHR_reusable_sync extension, and take a mode parameter + to distinguish signaling/unsignaling? + + RESOLVED: No. While all sync objects will support unsignaling, + the reusable sync object is the only known one that supports + direct signaling, rather than signaling through some condition + being achieved. Therefore it is simplest to have the new + function only support unsignaling, and continue to use the old + extension for the one case where signaling is required. + + 4. If the initial attribute list is incomplete (e.g. an OpenCL + event handle is not provided during creation of an OpenCL event + sync object), should the EGL_SYNC_STATUS default to EGL_SIGNALED + rather than generating an error if it is left unspecified? + + RESOLVED: Handling of allowed/default values for EGL_SYNC_STATUS + is based on the sync type. For fence syncs, either value is + allowed, defaulting to EGL_UNSIGNALED. For OpenCL event syncs, + the value may not be specified, and instead is determined by + whether an OpenCL event is provided at creation time, and if so + by the status of that event. + +Revision History + + #4 (May 16, 2018) Daniel Kartch + - Minor corrections to wording + + #3 (April 20, 2018) Daniel Kartch + - Renamed to EXT + - Fixed grammatical errors and prepared for publication + + #2 (January 23, 2018) Daniel Kartch + - Rewrote some sections for clarity, and fixed typos + - Changed default/allowed behavior for signal state at creation + time to be determined by the sync type and other attributes. + - Simplified interaction with EGL_KHR_reusable_sync. + - Refined interaction with EGL_ANDROID_native_fence_sync to + clarify allowed initial states for the sync status and fix the + description of when new native fences are generated. + + #1 (January 16, 2018) Daniel Kartch + - Initial draft as XXX diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_yuv_surface.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_yuv_surface.txt new file mode 100644 index 0000000..15b854e --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_yuv_surface.txt @@ -0,0 +1,393 @@ +Name + + EXT_yuv_surface + +Name Strings + + EGL_EXT_yuv_surface + +Contributors + + Matt Trusten + Jeff Vigil + Arshad Bebal + Mohan Maiya + Amit Bansal + Tom Longo + Eric Engestrom + +Contacts + + Jeff Vigil, Qualcomm (jvigil 'at' qualcomm.com) + +Notice + + Copyright (c) 2014 Qualcomm Technologies, Inc. All Rights Reserved. + Qualcomm Technologies Proprietary and Confidential + +Status + + Complete + +Version + + Version 9, May 4th, 2017 + +Number + + EGL Extension #86 + +Dependencies + + EGL 1.4 is required. + + This extension is written against the wording of the EGL 1.4 + Specification. + +Overview + + This extension defines a set of new EGL configuration attributes and values + which allows EGL to create and use YUV surfaces. + + YUV formats can be described using a few simple parameters, and every format + can be given with these six parameters. These parameters include the color + order, the number of planes, subsample, plane depth, color conversion and + depth range. + + This extension describes how EGL will handle YUV surfaces, but requires that + the client API describe how to fill such a surface. An example of such an + extension would be GL_EXT_yuv_target. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + A new set of EGLConfig attributes are available: + EGL_YUV_ORDER_EXT 0x3301 + EGL_YUV_NUMBER_OF_PLANES_EXT 0x3311 + EGL_YUV_SUBSAMPLE_EXT 0x3312 + EGL_YUV_DEPTH_RANGE_EXT 0x3317 + EGL_YUV_CSC_STANDARD_EXT 0x330A + EGL_YUV_PLANE_BPP_EXT 0x331A + + Accepted as a new value for the EGL_COLOR_BUFFER_TYPE attribute: + EGL_YUV_BUFFER_EXT 0x3300 + + Accepted values for the EGL_YUV_ORDER_EXT attribute: + EGL_YUV_ORDER_YUV_EXT 0x3302 + EGL_YUV_ORDER_YVU_EXT 0x3303 + EGL_YUV_ORDER_YUYV_EXT 0x3304 + EGL_YUV_ORDER_UYVY_EXT 0x3305 + EGL_YUV_ORDER_YVYU_EXT 0x3306 + EGL_YUV_ORDER_VYUY_EXT 0x3307 + EGL_YUV_ORDER_AYUV_EXT 0x3308 + + Accepted values for the EGL_YUV_SUBSAMPLE_EXT attribute: + EGL_YUV_SUBSAMPLE_4_2_0_EXT 0x3313 + EGL_YUV_SUBSAMPLE_4_2_2_EXT 0x3314 + EGL_YUV_SUBSAMPLE_4_4_4_EXT 0x3315 + + Accepted values for the EGL_YUV_DEPTH_RANGE_EXT attribute: + EGL_YUV_DEPTH_RANGE_LIMITED_EXT 0x3318 + EGL_YUV_DEPTH_RANGE_FULL_EXT 0x3319 + + Accepted values for the EGL_YUV_CSC_STANDARD_EXT attribute: + EGL_YUV_CSC_STANDARD_601_EXT 0x330B + EGL_YUV_CSC_STANDARD_709_EXT 0x330C + EGL_YUV_CSC_STANDARD_2020_EXT 0x330D + + Accepted values for the EGL_YUV_PLANE_BPP_EXT attribute: + EGL_YUV_PLANE_BPP_0_EXT 0x331B + EGL_YUV_PLANE_BPP_8_EXT 0x331C + EGL_YUV_PLANE_BPP_10_EXT 0x331D + +Additions to Chapter 2 of the EGL 1.4 Specification (EGL Operation) + +Change the options of paragraph 6 from section 2.2: Rendering Contexts and +Drawing Surfaces + + A context can be used with any EGLSurface that it is compatible with + (subject to the restrictions discussed in the section on address space). A + surface and context are compatible if + * They support the same type of color buffer (RGB or luminance) + +To the following: + + A context can be used with any EGLSurface that it is compatible with + (subject to the restrictions discussed in the section on address space). A + surface and context are compatible if + * They support the same type of color buffer (RGB, YUV, or luminance) + +Additions to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors) + +Change the section marked from Buffer Descriptions and Attributes in Section 3.4 +to: + + The Color Buffer + + The color buffer contains pixel color values, and is shared by all + client APIs rendering to a surface. + EGL_COLOR_BUFFER_TYPE indicates the color buffer type, and must be + either EGL_RGB_BUFFER for an RGB color buffer, EGL_LUMINANCE_BUFFER for a + luminance color buffer, or EGL_YUV_BUFFER_EXT for a YUV color buffer. For + an RGB buffer, EGL_RED_SIZE, EGL_GREEN_SIZE, EGL_BLUE_SIZE must be non-zero, + and EGL_LUMINANCE_SIZE must be zero. For a luminance buffer, EGL_RED_SIZE, + EGL_GREEN_SIZE, EGL_BLUE_SIZE must be zero, and EGL_LUMINANCE_SIZE must be + non-zero. For both RGB and luminance color buffers, EGL_ALPHA_SIZE may be + zero or non-zero (the latter indicates the existence of a destination alpha + buffer). For a YUV buffer, all of EGL_RED_SIZE, EGL_GREEN_SIZE, EGL_BLUE_- + SIZE, EGL_LUMINANCE_SIZE, and EGL_ALPHA_SIZE must be zero. Instead, the + depth in bits per pixel for YUV is described using EGL_YUV_PLANE_BPP_EXT, + which describes the size of a single pixel in the Y plane, and the other + plane depths are derived from this. + EGL_YUV_ORDER_EXT is used to describe the plane order. + EGL_YUV_NUMBER_OF_PLANES_EXT describes the number of planes that will + be used for this surface. The allowed values for EGL_YUV_NUMBER_OF_PLANES_- + EXT must be greater than zero and not more than three. + EGL_YUV_SUBSAMPLE_EXT allows the user to decide how the surface will be + subsampled. + + Valid combinations are: + + EGL_YUV_SUBSAMPLE_EXT EGL_YUV_NUMBER_OF_PLANES_EXT EGL_YUV_ORDER_EXT EGL_YUV_PLANE_BPP_EXT + ------------------------- ----------------------------- ------------------ ------------------------ + EGL_YUV_SUBSAMPLE_4_2_0_EXT 2 or 3 EGL_YUV_ORDER_YUV_EXT or EGL_YUV_PLANE_BPP_8_EXT or + EGL_YUV_ORDER_YVU_EXT EGL_YUV_PLANE_BPP_10_EXT + + EGL_YUV_SUBSAMPLE_4_2_2_EXT 1 EGL_YUV_ORDER_YUYV_EXT or EGL_YUV_PLANE_BPP_8_EXT or + EGL_YUV_ORDER_YVYU_EXT or EGL_YUV_PLANE_BPP_10_EXT + EGL_YUV_ORDER_UYVY_EXT or + EGL_YUV_ORDER_VYUY_EXT + + EGL_YUV_SUBSAMPLE_4_2_2_EXT 2 or 3 EGL_YUV_ORDER_YUV_EXT or EGL_YUV_PLANE_BPP_8_EXT or + EGL_YUV_ORDER_YVU_EXT EGL_YUV_PLANE_BPP_10_EXT + + EGL_YUV_SUBSAMPLE_4_4_4_EXT 1 EGL_YUV_ORDER_AYUV_EXT EGL_YUV_PLANE_BPP_8_EXT or + EGL_YUV_PLANE_BPP_10_EXT + + Usage examples: + + Format Combination + ------------------ -------------------------------------------------------------- + NV12 EGL_YUV_SUBSAMPLE_EXT = EGL_YUV_SUBSAMPLE_4_2_0_EXT + - YUV420 EGL_YUV_NUMBER_OF_PLANES_EXT = 2 + - 2 Planes : Y + UV EGL_YUV_ORDER_EXT = EGL_YUV_ORDER_YUV_EXT + - 8 bit depth EGL_YUV_PLANE_BPP_EXT = EGL_YUV_PLANE_BPP_8_EXT + + NV21 EGL_YUV_SUBSAMPLE_EXT = EGL_YUV_SUBSAMPLE_4_2_0_EXT + - YUV420 EGL_YUV_NUMBER_OF_PLANES_EXT = 2 + - 2 Planes : Y + VU EGL_YUV_ORDER_EXT = EGL_YUV_ORDER_YVU_EXT + - 8 bit depth EGL_YUV_PLANE_BPP_EXT = EGL_YUV_PLANE_BPP_8_EXT + + YV12 EGL_YUV_SUBSAMPLE_EXT = EGL_YUV_SUBSAMPLE_4_2_0_EXT + - YUV420 EGL_YUV_NUMBER_OF_PLANES_EXT = 3 + - 3 Planes : Y + V + U EGL_YUV_ORDER_EXT = EGL_YUV_ORDER_YVU_EXT + - 8 bit depth EGL_YUV_PLANE_BPP_EXT = EGL_YUV_PLANE_BPP_8_EXT + + YUY2 EGL_YUV_SUBSAMPLE_EXT = EGL_YUV_SUBSAMPLE_4_2_2_EXT + - YUV422 EGL_YUV_NUMBER_OF_PLANES_EXT = 1 + - 1 Plane : Y + U + Y + V EGL_YUV_ORDER_EXT = EGL_YUV_ORDER_YUYV_EXT + - 8 bit depth EGL_YUV_PLANE_BPP_EXT = EGL_YUV_PLANE_BPP_8_EXT + + AYUV EGL_YUV_SUBSAMPLE_EXT = EGL_YUV_SUBSAMPLE_4_4_4_EXT + - YUV444 EGL_YUV_NUMBER_OF_PLANES_EXT = 1 + - 1 Plane : A + Y + U + V EGL_YUV_ORDER_EXT = EGL_YUV_ORDER_AYUV_EXT + - 8 bit depth EGL_YUV_PLANE_BPP_EXT = EGL_YUV_PLANE_BPP_8_EXT + + YUV420 Semi-Planar 10 Bit EGL_YUV_SUBSAMPLE_EXT = EGL_YUV_SUBSAMPLE_4_2_0_EXT + - YUV420 EGL_YUV_NUMBER_OF_PLANES_EXT = 2 + - 2 Planes : Y + UV EGL_YUV_ORDER_EXT = EGL_YUV_ORDER_YUV_EXT + - 10 bit depth EGL_YUV_PLANE_BPP_EXT = EGL_YUV_PLANE_BPP_10_EXT + + YUV422 Interleaved 10 Bit EGL_YUV_SUBSAMPLE_EXT = EGL_YUV_SUBSAMPLE_4_2_2_EXT + - YUV422 EGL_YUV_NUMBER_OF_PLANES_EXT = 1 + - 1 Plane : Y + U + Y + V EGL_YUV_ORDER_EXT = EGL_YUV_ORDER_YUYV_EXT + - 8 bit depth EGL_YUV_PLANE_BPP_EXT = EGL_YUV_PLANE_BPP_10_EXT + + EGL_YUV_PLANE_BPP_EXT describes the bit depth for the different + planes of a YUV surface. The available options are EGL_YUV_PLANE_BPP_0_- + EXT, EGL_YUV_PLANE_BPP_8_EXT and EGL_YUV_PLANE_BPP_10_EXT. If EGL_YUV_- + PLANE_BPP_0_EXT is specified, no color buffer will be created for the + surface. + EGL_YUV_DEPTH_RANGE_EXT describes the range of the pixel value and is + dependent on the EGL_YUV_PLANE_BPP_EXT setting: + + EGL_YUV_PLANE_BPP_EXT EGL_YUV_DEPTH_RANGE_LIMITED_EXT EGL_YUV_DEPTH_RANGE_FULL_EXT + (Inclusive) (Inclusive) + ------------------------- -------------------------------- ----------------------------- + EGL_YUV_PLANE_BPP_8_EXT or Y: 16 to 235, UV: 16 to 240 Y: 0 to 255, UV: 0 to 255 + EGL_YUV_PLANE_BPP_10_EXT Y: 64 to 940, UV: 64 to 960 Y: 0 to 1023, UV: 0 to 1023 + + If OpenGL or OpenGL ES rendering is supported for a luminance color + buffer (as described by the value of the EGL_RENDERABLE_TYPE attribute, + described below), it is treated as RGB rendering with the value of + GL_RED_BITS equal to EGL_LUMINANCE_SIZE and the values of GL_GREEN_BITS and + GL_BLUE_BITS equal to zero. The red component of fragments is written to the + luminance channel of the color buffer, the green and blue components are + discarded, and the alpha component is written to the alpha channel of the + color buffer (if present). + When rendering to the YUV surface, if EGL_YUV_ORDER_EXT is not EGL_- + YUV_ORDER_AYUV_EXT, the alpha channel will always be fully opaque. + Otherwise it is defined by the value provided to the alpha sample. + EGL_BUFFER_SIZE gives the total of the color component bits of the color + buffer for EGL_RGB_BUFFER or for EGL_LUMINANCE_BUFFER. For an RGB color + buffer, the total is the sum of EGL_RED_SIZE, EGL_GREEN_SIZE, EGL_BLUE_SIZE, + and EGL_ALPHA_SIZE. For a luminance color buffer, the total is the sum of + EGL_LUMINANCE_SIZE and EGL_ALPHA_SIZE. When EGL_COLOR_BUFFER_TYPE is of type + EGL_YUV_BUFFER_EXT, this will reflect the enumeration provided + as an integer) for EGL_YUV_PLANE_BPP_EXT, giving a value of 0, 8 or 10. + + Other EGLConfig Attribute Descriptions + + EGL_YUV_CSC_STANDARD_EXT can be set to either EGL_YUV_CSC_STANDARD_- + 601_EXT, EGL_YUV_CSC_STANDARD_709_EXT, or EGL_YUV_CSC_2020_EXT. If the + standard chosen is EGL_YUV_CSC_STANDARD_709_EXT, then the color conversion + follows the ITU-R BT.709 standard. If EGL_YUV_CSC_STANDARD_EXT is set to + EGL_YUV_CSC_2020_EXT, then the color conversion will be processed based on + ITU-R BT.2020. + + +Change option 2 in the section marked as 3.4.1.2 Sorting of EGLConfigs to: + + 2. Special: by EGL_COLOR_BUFFER_TYPE where the precendence is EGL_RGB_- + BUFFER, EGL_LUMINANCE_BUFFER, EGL_YUV_BUFFER_EXT. + +Change option 3 in the section marked as 3.4.1.2 Sorting of EGLConfigs to: + + 3. Special: by larger total number of color bits (for an RGB color buffer, + this is the sum of EGL_RED_SIZE, EGL_GREEN_SIZE, EGL_BLUE_SIZE, and + EGL_ALPHA_SIZE; for a luminance color buffer, the sum of EGL_LUMINANCE_SIZE + and EGL_ALPHA_SIZE; for YUV color buffers, this returns the integer value + with respect to the enumeration provided for EGL_YUV_PLANE_BPP_EXT) If the + requrested number of bits in attrib_list for a particular color component + is 0 or EGL_DONT_CARE, then the number of bits for the component is not + considered. Due to this, YUV color buffers are always last based on this + rule. + +The following options should be added between options 9 and 10 in section +3.4.1.2 (EGL_ALPHA_MASK_SIZE and EGL_NATIVE_VISUAL_TYPE): + + 10. Special: EGL_YUV_ORDER_EXT will be sorted in the following order: + EGL_NONE, EGL_YUV_ORDER_YUV_EXT, EGL_YUV_ORDER_YVU_EXT, EGL_YUV_ORDER_- + YUYV_EXT, EGL_YUV_ORDER_YVYU_EXT, EGL_YUV_ORDER_UYVY_EXT, EGL_YUV_ORDER_- + VYUY_EXT, and EGL_YUV_ORDER_AYUV_EXT. + +Change option 10 in section 3.4.1.2 (EGL_NATIVE_VISUAL_TYPE) to: + + 11. Special: by EGL_NATIVE_VISUAL_TYPE (the actual sort order is + implementation-defined, depending on the meaning of native visual types). + +New State + + Add to table 3.1 (EGLConfig Attributes): + + Attribute Type Notes + ----------------------------- ---- -------------------------------------------- + EGL_YUV_ORDER_EXT enum The order in which the samples will be found + inside the surface + EGL_YUV_NUMBER_OF_PLANES_EXT integer Number of planes for the surface, in the range of [1,3] + EGL_YUV_SUBSAMPLE_EXT enum Describes the sampling rate of the different planes. + EGL_YUV_DEPTH_RANGE_EXT enum Luma plane range. limited is [16,240] and + full range is [0,255] + EGL_YUV_CSC_STANDARD_EXT enum The standard used for color conversion. + EGL_YUV_PLANE_BPP_EXT enum How many bits are used for each plane of + the YUV surface + + Add to table 3.4 (Default values and match criteria for EGLConfig + attributes): + + Attribute Default Selection Sort Sort + Criteria Order Priority + ------------------------- -------------------------------- --------- ------- -------- + EGL_YUV_ORDER_EXT EGL_DONT_CARE Exact Special 10 + EGL_YUV_NUMBER_OF_PLANES_EXT 0 At least None + EGL_YUV_SUBSAMPLE_EXT EGL_DONT_CARE Exact None + EGL_YUV_DEPTH_RANGE_EXT EGL_DONT_CARE Exact None + EGL_YUV_CSC_STANDARD_EXT EGL_DONT_CARE Exact None + EGL_YUV_PLANE_BPP_EXT EGL_DONT_CARE Exact None + +Issues + 1. How will a EGL surface created with a YUV config properly detect that + valid values were used when filling pixel data? + + This problem occurs in situations when a specification which defines + rendering to the YUV surface cannot guarantee values that conform to the + configuration attributes. One possible situation for this is when a + the GL client is using GL_EXT_yuv_target and the EGL YUV surface is the + draw buffer. The shader can transform the values inside the shader, and + there is no guarantee that the values will fall into the EGL_YUV_DEPTH_- + RANGE_EXT value chosen. Other client specifications could have similar + issues and it may not be performant for some hardware to detect this + discrepancy. This includes interactions with extensions such as EGL_- + lock_surface, or any others that provide a mechanism to change the + contents of the YUV surface. + + One of the problems that can occur in situations like this will be + compound mathematical error should operations need to take place on the + buffer data. + + Proposal: Due to the performance problems or inability in some hardware + to deal with this issue, the pixel contents will be undefined and any + further operations to the pixel contents will also be undefined. + Therefore it is up to the application to guarantee the correct values + are stored within the surface. The EGL implementation need not attempt + any form of verification on the pixel data of the YUV surface, nor does + it have to guarantee the pixel data, even with communicating the surface + to other modules through a post or any other operation EGL performs. + + 2. Should an EGL_COLOR_BUFFER_TYPE = EGL_DONT_CARE request enumerate all + YUV configs? + + Resolved: Revision #9 changes the default values and selection criteria + to allow for full enumeration of all YUV configs. The default value of + EGL_COLOR_BUFFER_TYPE remains EGL_RGB_BUFFER, so this change only + affects explicit EGL_DONT_CARE requests. + +Example Configuration for NV12: + + const EGLint config_attribs[] = + { + EGL_SURFACE_TYPE, EGL_WINDOW_BIT, + EGL_RENDERABLE_TYPE, EGL_OPENGL_ES2_BIT, + EGL_COLOR_BUFFER_TYPE, EGL_YUV_BUFFER_EXT, + EGL_YUV_ORDER_EXT, EGL_ORDER_YUV_EXT, + EGL_YUV_NUMBER_OF_PLANES_EXT, 2, + EGL_YUV_SUBSAMPLE_EXT, EGL_YUV_SUBSAMPLE_4_2_0_EXT, + EGL_YUV_DEPTH_RANGE_EXT, EGL_YUV_DEPTH_RANGE_LIMITED_EXT, + EGL_YUV_CSC_STANDARD_EXT, EGL_YUV_CSC_STANDARD_601_EXT, + EGL_YUV_PLANE_BPP_EXT, EGL_YUV_PLANE_BPP_8_EXT, + EGL_NONE + }; + +Revision History +#1 March 12th, 2014 Initial Draft. + +#2 March 25th, 2014 Reformated and added more detail. + +#3 March 26th, 2014 Added usage examples. + Added memory layout definitions. + +#4 March 26th, 2014 Fixed some typos and formatting. + +#5 May 21st, 2014 Fixed some inconsistencies. + Added EGL_YUV_PLANE_DEPTH_0_QCOM. + +#6 May 27th, 2014 Relaxed some requirements. + Changed EGL_YUV_PLANE_DEPTH_<0,8,10>_QCOM to + EGL_YUV_PLANE_BPP_<0,8,10>_QCOM. + Added more detail. + +#7 October 7th, 2014 Issue (1) added. + Minor updates made (EXT_yuv_target) + +#8 October 24th, 2014 Updated for EXT and token values. + +#9 April 26th, 2017 Changed attributes default values and selection + criteria (see issue #2). + Changed status from Draft to Complete. |