diff options
Diffstat (limited to 'engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR')
35 files changed, 14062 insertions, 0 deletions
diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_cl_event.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_cl_event.txt new file mode 100644 index 0000000..92f4a73 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_cl_event.txt @@ -0,0 +1,278 @@ +Name + + KHR_cl_event + +Name Strings + + EGL_KHR_cl_event + +Contributors + + Jon Leech, Khronos + Alon Or-bach, Samsung Electronics + +Contact + + Jon Leech (jon 'at' alumni.caltech.edu) + +IP Status + + No known claims. + +Notice + + Copyright (c) 2010-2013 The Khronos Group Inc. Copyright terms at + http://www.khronos.org/registry/speccopyright.html + +Status + + This extension is obsolete and has been replaced by EGL_KHR_cl_event2. + Khronos recommends implementers who support this extension also + implement cl_event2, and begin transitioning developers to using that + extension. See issue 17 for the reason. + + Complete. Approved by the EGL Working Group on 2013/05/15. + Approved by the Khronos Board of Promoters on 2013/07/19. + +Version + + Version 10, December 4, 2013 + +Number + + EGL Extension #60 + +Dependencies + + EGL 1.4 and the EGL_KHR_fence_sync extension are required. + + This extension is written against the language added to EGL 1.2 by + the EGL_KHR_fence_sync extension. + + An OpenCL implementation supporting sharing OpenCL event objects + with EGL is required. + +Overview + + This extension allows creating an EGL fence sync object linked to an + OpenCL event object, potentially improving efficiency of sharing + images between the two APIs. The companion cl_khr_egl_event + extension provides the complementary functionality of creating an + OpenCL event object from an EGL fence sync object. + +New Types + + None. However, event handles of type cl_event, defined in the OpenCL + header files, may be included in the attribute list passed to + eglCreateSyncKHR. + +New Procedures and Functions + + None + +New Tokens + + Accepted as attribute names in the <attrib_list> argument + of eglCreateSyncKHR: + + EGL_CL_EVENT_HANDLE_KHR 0x309C + + Returned in <values> for eglGetSyncAttribKHR <attribute> + EGL_SYNC_TYPE_KHR: + + EGL_SYNC_CL_EVENT_KHR 0x30FE + + Returned in <values> for eglGetSyncAttribKHR <attribute> + EGL_SYNC_CONDITION_KHR: + + EGL_SYNC_CL_EVENT_COMPLETE_KHR 0x30FF + +Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors) + + Add following the description of fence sync objects in section 3.8.1 + (e.g. following the paragraph beginning "<Fence sync objects> are + created..." + + "A <CL 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_sharing extension). Waiting on such a sync object is + equivalent to waiting for completion of the linked CL event object." + + Add following the description of fence sync objects (prior to the + "Errors" section for eglCreateSyncKHR): + + "If <type> is EGL_SYNC_CL_EVENT_KHR, a CL event sync object is + created. In this case <attrib_list> must contain the attribute + EGL_CL_EVENT_HANDLE_KHR, set to a valid OpenCL event. Note that + EGL_CL_EVENT_HANDLE_KHR is not a queriable property of a sync + object. Attributes of the CL event sync objects are set as follows: + + Attribute Name Initial Attribute Value(s) + ------------- -------------------------- + EGL_SYNC_TYPE_KHR EGL_SYNC_CL_EVENT_KHR + EGL_SYNC_STATUS_KHR Depends on status of <event> + EGL_SYNC_CONDITION_KHR EGL_SYNC_CL_EVENT_COMPLETE_KHR + + 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_KHR. When the status + of <event> changes to CL_COMPLETE, the status of the linked sync + object will become EGL_SIGNALED_KHR. + + Creating a linked sync object places a reference on the linked + OpenCL event object. When the sync object is deleted, the reference + will be removed from the event object. + + However, 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." + + Add to the "Errors" section for eglCreateSyncKHR: + + "* If <type> is EGL_SYNC_CL_EVENT_KHR then + + ** If EGL_CL_EVENT_HANDLE_KHR is not specified in <attrib_list> + or is not a valid OpenCL event handle returned by a call to + clEnqueueReleaseGLObjects or clEnqueueReleaseEGLObjects, then + EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE error is + generated. + + Replace the EGL_SYNC_CONDITION_KHR row of table 3.cc with: + + "Attribute Description Supported Sync Objects + ----------------- ----------------------- ---------------------- + EGL_SYNC_CONDITION_KHR Signaling condition EGL_SYNC_FENCE_KHR or + EGL_SYNC_CL_EVENT_KHR + + Table 3.cc Attributes Accepted by eglGetSyncAttribKHR Command" + + + Replace the second paragraph describing eglDestroySync with: + + "If any eglClientWaitSyncKHR commands are blocking on <sync> when + eglDestroySyncKHR is called, <sync> is flagged for deletion and will + be deleted when the associated fence command or CL event object has + completed, and <sync> is no longer blocking any eglClientWaitSyncKHR + command. Otherwise, the sync object is destroyed immediately." + +Sample Code + + None + +Conformance Tests + + None yet + +Issues + + 1) Does this extension need to introduce eglWaitSync + functionality? + + RESOLVED: The EGL_KHR_wait_sync extension introduces this, to allow + server-side synchronization, without blocking the client from issuing + commands. Whilst this is not a required dependency, GPU-to-GPU + synchronization is the most likely use of this extension. + + 2) What should the command to create a sync object linked to an + OpenCL event look like? + + RESOLVED: We reuse the general attribute list mechanism rather than + having a constructor specific to CL events. This was intended in the + sync object design from the start. + + 3) How will the OpenCL header dependencies interact with + specifying the API for this extension? + + DISCUSSION: To use this extension, OpenCL event handles of type cl_event + are specified in the attribute lists passed to eglCreateSyncKHR. Because + no formal parameters are of type cl_event, the EGL headers do not need + to define this type. Applications must #include the appropriate OpenCL + header files as well as <EGL/eglext.h> when using this extension. + + This issue resolution is consistent with the equivalent issue for + GL_ARB_cl_event. + + 4) Should all possible statuses of the CL event be reflected through to the + state of the sync object? + + DISCUSSION: CL event objects have four execution statuses: + CL_QUEUED, CL_SUBMITTED, CL_RUNNING, and CL_COMPLETE. GL sync + objects have only two statuses: UNSIGNALED and SIGNALED. The + cl_khr_gl_event extension maps UNSIGNALED into CL_SUBMITTED, and + SIGNALED into CL_COMPLETE. + + RESOLVED: Invert the cl_khr_egl_event mapping. CL_QUEUED, + CL_SUBMITTED, and CL_RUNNING all map into UNSIGNALED. + CL_COMPLETE maps into SIGNALED. + + This issue resolution is consistent with the equivalent issue for + GL_ARB_cl_event. + + 5) Are there any restrictions on the use of a sync object linked to a CL + event object? + + RESOLVED: No restrictions. + + 6) How are sync object lifetimes defined? + + RESOLVED: A sync object linked to a CL event object places a single + reference on the event. Deleting the sync object removes that reference. + + eglDestroySync has a dependency on the completion of the linked event + object, and will not delete the sync objectwhile the event object has not + yet completed. This is equivalent to behavior of deleting a fence sync + object, where deletion of the object will be deferred until the underlying + fence command has completed. + + This issue resolution is consistent with the equivalent issue for + GL_ARB_cl_event. + + 7) Should all OpenCL events be supported? + + RESOLVED: No. Only events returned by clEnqueueReleaseGLObjects, or + clEnqueueReleaseEGLObjects since those are the only known use cases for + this extension. + + 8) Why has this extension been obsoleted and replaced by + EGL_KHR_cl_event2? + + RESOLVED: Starting with the December 4, 2013 release of EGL 1.4, EGLint + is defined to be the same size as the native platform "int" type. Handle + and pointer attribute values *cannot* be represented in attribute lists + on platforms where sizeof(handle/pointer) > sizeof(int). Existing + extensions which assume this functionality are being replaced with new + extensions specifying new entry points to work around this issue. See + the latest EGL 1.4 Specification for more details. + +Revision History + + Version 10, 2013/12/04 (Jon Leech) - add issue 8 explaining that OpenCL + event handles cannot be safely passed in attribute lists on 64-bit + platforms, and suggest using EGL_KHR_cl_event2 instead. + + Version 9, 2013/08/12 (Jon Leech) - remove unused cl_event type from the + extension and from <EGL/eglext.h> (Bug 10661). + + Version 8, 2013/07/19 (Jon Leech) - assign extension number and + missing enum value, and clean up a few typos for publication. + + Version 7, 2013/07/08 (Jon Leech) - assign enums (Bug 10490). + + Version 6, 2013/06/11 (Alon Or-bach) - typo correction + + Version 5, 2013/05/30 (Alon Or-bach) - wording cleanup + + Version 4, 2013/05/15 (Alon Or-bach) - updated issue resolutions as agreed, + consistent with GL_ARB_cl_event, including using typedef for cl_event + + Version 3, 2013/04/25 (Alon Or-bach) - remove use of CL context, + accept events from clEnqueueAcquireEGLObjects and minor cleanup + + Version 2, 2012/06/26 (Jon Leech) - update link to complementary CL + extension. + + Version 1, 2010/05/18 (Jon Leech) - initial version based on + equivalent GL_ARB_cl_event extension. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_cl_event2.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_cl_event2.txt new file mode 100644 index 0000000..953487c --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_cl_event2.txt @@ -0,0 +1,364 @@ +Name + + KHR_cl_event2 + +Name Strings + + EGL_KHR_cl_event2 + +Contributors + + Jon Leech, Khronos + Alon Or-bach, Samsung Electronics + Tom Cooksey, ARM + +Contact + + Jon Leech (jon 'at' alumni.caltech.edu) + +IP Status + + No known claims. + +Notice + + Copyright (c) 2010-2013 The Khronos Group Inc. Copyright terms at + http://www.khronos.org/registry/speccopyright.html + +Status + + Complete. + Approved by the EGL Working Group on December 4, 2013. + +Version + + Version 5, December 4, 2013 + +Number + + EGL Extension #65 + +Dependencies + + EGL 1.4 and the EGL_KHR_fence_sync extension are required. + + This extension is written against the language added to EGL 1.2 by + the EGL_KHR_fence_sync extension. + + An OpenCL implementation supporting sharing OpenCL event objects + with EGL is required. + + Khronos recommends obsoleting and replacing implementations of + EGL_KHR_cl_event with this extension as soon as possible. + +Overview + + This extension allows creating an EGL sync object linked to an OpenCL + event object, potentially improving efficiency of sharing images between + the two APIs. The companion cl_khr_egl_event extension provides the + complementary functionality of creating an OpenCL event object from an + EGL sync object. + + This extension is functionally identical to EGL_KHR_cl_event, but is + intended to replace that extension. It exists only to address an + implementation issue on 64-bit platforms where passing OpenCL event + handles in an EGLint attribute list value is impossible, because the + implementations use a 32-bit type for EGLint. + + This extension also incorporates some required functionality from the + EGL_KHR_fence_sync extension, similarly modified for 64-bit platforms. + +New Types + + /* + * EGLAttribKHR is a integer type used to pass arrays of attribute + * name/value pairs which may include pointer and handle attribute + * values. + */ + #include <khrplatform.h> + typedef intptr_t EGLAttribKHR; + + Event handles of type cl_event, defined in the OpenCL header files, may + be included in the attribute list passed to eglCreateSync64KHR. + +New Procedures and Functions + + EGLSyncKHR eglCreateSync64KHR( + EGLDisplay dpy, + EGLenum type, + const EGLAttribKHR *attrib_list); + +New Tokens + + Accepted as attribute names in the <attrib_list> argument + of eglCreateSync64KHR: + + EGL_CL_EVENT_HANDLE_KHR 0x309C + + Returned in <values> for eglGetSyncAttribKHR <attribute> + EGL_SYNC_TYPE_KHR: + + EGL_SYNC_CL_EVENT_KHR 0x30FE + + Returned in <values> for eglGetSyncAttribKHR <attribute> + EGL_SYNC_CONDITION_KHR: + + EGL_SYNC_CL_EVENT_COMPLETE_KHR 0x30FF + +Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors) + + Modify the language in section 3.8.1 (Sync Objects) starting at the + sixth paragraph, describing commands to create sync objects: + + "The commands + + EGLSyncKHR eglCreateSync64KHR( + EGLDisplay dpy, + EGLenum type, + const EGLAttribKHR *attrib_list); + + and + + EGLSyncKHR eglCreateSyncKHR( + EGLDisplay dpy, + EGLenum type, + const EGLint *attrib_list); + + create a sync object ... + + ... When a fence sync object is created, eglCreateSyncKHR and + eglCreateSync64KHR also insert a fence command into... " + + Add following the eigth paragraph (the paragraph beginning "<Fence sync + objects> are created..."): + + "A <CL 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_sharing + extension). Waiting on such a sync object is equivalent to waiting for + completion of the linked CL event object. + + CL event sync objects may only be created using the command + eglCreateSync64KHR, because they require an attribute which may not be + representable in the attrib_list argument of eglCreateSyncKHR." + + Add following the description of fence sync objects (prior to the + "Errors" section for eglCreateSyncKHR): + + "If <type> is EGL_SYNC_CL_EVENT_KHR, a CL event sync object is + created. In this case <attrib_list> must contain the attribute + EGL_CL_EVENT_HANDLE_KHR, set to a valid OpenCL event. Note that + EGL_CL_EVENT_HANDLE_KHR is not a queriable property of a sync + object. Attributes of the CL event sync objects are set as follows: + + Attribute Name Initial Attribute Value(s) + ------------- -------------------------- + EGL_SYNC_TYPE_KHR EGL_SYNC_CL_EVENT_KHR + EGL_SYNC_STATUS_KHR Depends on status of <event> + EGL_SYNC_CONDITION_KHR EGL_SYNC_CL_EVENT_COMPLETE_KHR + + 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_KHR. When the status + of <event> changes to CL_COMPLETE, the status of the linked sync + object will become EGL_SIGNALED_KHR. + + Creating a linked sync object places a reference on the linked + OpenCL event object. When the sync object is deleted, the reference + will be removed from the event object. + + However, 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." + + The command eglCreateSync64KHR must be used to create a CL event sync + object[fn1]. + + [fn1] If the implementation also supports the older EGL_KHR_cl_event + extension, then eglCreateSyncKHR may also be used to create a CL + event sync object. However, this use is not recommended because it + is not portable to platforms where OpenCL event handles are larger + than 32 bits." + + Modify the ninth and tenth paragraphs, starting "When the condition": + + "When the condition of the sync object is satisfied, the sync is + signaled by the associated client API context, causing any + eglClientWaitSyncKHR commands (see below) blocking on <sync> to unblock. + + The only condition supported for fence sync objects is + EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR, which is satisfied by completion + of the fence command corresponding to the sync object, and all preceding + commands in the associated client API context's command stream. The sync + object will not be signaled until all effects from these commands on the + client API's internal and framebuffer state are fully realized. No other + state is affected by execution of the fence command. + + Each client API which supports fence commands indicates this support + in the form of a client API extension. If the GL_OES_EGL_sync + extension is supported by OpenGL ES (either version 1.x or 2.0), a + fence sync object may be created when the currently bound API is + OpenGL ES. If the VG_KHR_EGL_sync extension is supported by OpenVG, + a fence sync object may be created when the currently bound API is + OpenVG. + + The only condition supported for CL event sync objects is + EGL_SYNC_CL_EVENT_COMPLETE_KHR, which is satisfied when the status of + the OpenCL event associated with the sync object changes to CL_COMPLETE." + + Add to the "Errors" section for eglCreateSyncKHR and eglCreateSync64KHR: + + "* If <type> is EGL_SYNC_CL_EVENT_KHR then + + ** If eglCreateSyncKHR was called, then EGL_NO_SYNC_KHR is returned and + an EGL_BAD_ATTRIBUTE error is generated. + + ** If eglCreateSync64KHR was called and EGL_CL_EVENT_HANDLE_KHR is not + specified in <attrib_list>, or its attribute value is not a valid + OpenCL event handle returned by a call to clEnqueueReleaseGLObjects + or clEnqueueReleaseEGLObjects, then EGL_NO_SYNC_KHR is returned and + an EGL_BAD_ATTRIBUTE error is generated." + + Replace the EGL_SYNC_CONDITION_KHR row of table 3.cc with: + + "Attribute Description Supported Sync Objects + ----------------- ----------------------- ---------------------- + EGL_SYNC_CONDITION_KHR Signaling condition EGL_SYNC_FENCE_KHR or + EGL_SYNC_CL_EVENT_KHR + + Table 3.cc Attributes Accepted by eglGetSyncAttribKHR Command" + + + Replace the second paragraph describing eglDestroySync with: + + "If any eglClientWaitSyncKHR commands are blocking on <sync> when + eglDestroySyncKHR is called, <sync> is flagged for deletion and will + be deleted when the associated fence command or CL event object has + completed, and <sync> is no longer blocking any eglClientWaitSyncKHR + command. Otherwise, the sync object is destroyed immediately." + +Sample Code + + None + +Conformance Tests + + None yet + +Issues + + Note that some issues from the EGL_KHR_cl_event and EGL_KHR_fence_sync + extensions also apply to this extension, which incorporates + functionality from both of those extensions while making it usable on a + 64-bit architecture. Issues specific to this extension are below. + + 1) Why does this extension exist? + + The existence of this extension is an unfortunate necessity. Khronos did + not define EGLint as a 64-bit type in the version of <khrplatform.h> we + provided, assuming that vendors on those platforms would do so. By the + time we discovered that not all vendors had done this, it was too late + to fix, because ABI considerations made it impossible for those vendors + to change to a 64-bit EGLint type. Our only option was to define new + extensions and commands using a new attribute type, EGLAttribKHR, which + is explicitly large enough to hold a pointer or handle. + + 2) What is the relationship of this extension to EGL_KHR_cl_event? + + RESOLVED: The only functional difference is that the new + eglCreateSync64KHR command must be used to create CL event sync objects. + This is necessary because some 64-bit platforms define EGLint as a + 32-bit type, making it impossible to pass an arbitrary OpenCL event + handle in the EGLint *attrib_list passed to eglCreateSyncKHR. + + 3) How are pointer- and handle-sized attributes represented? + + RESOLVED: Using the new type EGLAttribKHR, which is explicitly defined + as an integer type large enough to hold a pointer. + + EGLAttribKHR is defined as an alias of the ISO C intptr_t type, rather + than using one of the explicitly-sized types from khrplatform.h. + Requiring this means that khrplatform.h must make sure to include the + appropriate header file (probably <stdint.h>) and that a C compiler + supporting intptr_t must be used. In the past we were concerned about + older C/C++ compilers, but this seems an acceptable choice in 2013. + + We could choose to use intptr_t as the base type of attribute lists, + instead of the EGLAttribKHR alias. As Ian Romanick has pointed out + passionately in ARB discussions, modern C compilers are required to + support a well-defined set of scalar types. There is no requirement to + use API-specific scalar types when explicitly defining a C API. + + However, there is some value in semantically tagging parameters with EGL + types. Also, using 'intptr_t *attrib_list' would be cosmetically + objectionable due to mixing EGL* and C native scalar types in EGL APIs. + + We probably want to wait until there's an EGL API compatibility break - + a hypothetical "EGL 2.0" - before moving to native ISO C types in our + interfaces. + + 4) Why is the new fence sync creation function defined here, instead of + in a separate EGL_KHR_fence_sync2 extension? + + RESOLVED: eglCreateSync64KHR is defined here because this is the only + functionality requiring it, and we expect this extension to be a stopgap + for 64-bit platforms until the time that EGL 1.5 is defined. The EGL 1.5 + core will presumably include only the EGLAttribKHR-based version of this + command. + + If there are any new extensions using handle or pointer attributes in + the meantime, they should copy the EGLAttribKHR and eglCreateSync64KHR + language here as required. There is no harm in defining the same type or + command in multiple extensions, so long as the definitions are + compatible. + + 5) Why is the new command called eglCreateSync64KHR? + + UNRESOLVED: For consistency with OpenGL, which has '64'-suffixed + commands for representing 64-bit integers and arbitrary offsets into GPU + memory. If we ever support EGL on 128-bit platforms this would be a + silly naming convention, but that time is probably many decades away and + by then EGL 1.5 should be defined and widely supported. The name + eglCreateSync2KHR was originally suggested. + + 6) Why is there no command for querying EGLAttribKHR attributes from + sync objects? + + RESOLVED: Because the only sync attribute which requires the extra bits + in an EGLAttribKHR type is EGL_CL_EVENT_HANDLE_KHR, which is not + queryable. Sync attributes which are queryable will all fit into the + EGLint returned by eglGetSyncAttribKHR. + + NOTE: It's unfortunate that this name is used, since it uses the + "AttribKHR" name for command returning EGLints. In EGL 1.5 we should use + a different name for the query. + + 7) Does this extension replace EGL_KHR_fence_sync and EGL_KHR_cl_event? + + RESOLVED: It does not replace EGL_KHR_fence_sync, but extends it to + support creation of a new type of sync object, the CL event sync object. + + RESOLVED: It is intended to replace EGL_KHR_cl_event; this extension + must be used for OpenCL interop on 64-bit platforms, and we hope all + vendors will implement it even on 32-bit platforms, for maximum code + portability. + +Revision History + + Version 5, 20130/12/04 (Jon Leech) - minor cleanup for public release. + + Version 4, 20130/10/16 (Jon Leech) - add Dependencies and Overview text + noting that this extension obsoletes and should replace + EGL_KHR_cl_event. + + Version 3, 20130/10/15 (Jon Leech) - change type of EGLAttribKHR from + uintptr to intptr (Bug 11027). + + Version 2, 20130/10/12 (Jon Leech) - merge EGL_KHR_fence_sync2 with this + extension, change the naming scheme, define EGLAttribKHR as uintptr_t, + and add a new issues list. + + Version 1, 2010/10/02 (Tom Cooksey) - initial version based on + EGL_KHR_cl_event and adding 64-bit EGLAttrKHR variants. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_config_attribs.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_config_attribs.txt new file mode 100644 index 0000000..65634ca --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_config_attribs.txt @@ -0,0 +1,234 @@ +Name + + KHR_config_attribs + +Name Strings + + EGL_KHR_config_attribs + +Contributors + + Jon Leech + +Contacts + + Jon Leech (jon 'at' alumni.caltech.edu) + +Notice + + Copyright (c) 2006-2013 The Khronos Group Inc. Copyright terms at + http://www.khronos.org/registry/speccopyright.html + +Status + + Complete + +Version + + Version 5, April 5, 2007 + +Number + + EGL Extension #1 + +Dependencies + + Requires EGL 1.2 + + Some of the extended config attributes defined by this extension are + only relevant when specific client APIs are supported. + + This extension is written against the wording of the EGL 1.2 + Specification. It exists for backwards compatibility with + functionality introduced in EGL 1.3. + +Overview + + This extension adds new EGL config attributes and attribute bits + that express limitations of configs on a per-API basis, including + whether client APIs created with respect to a config are expected to + pass conformance, and which optional OpenVG color space and alpha + mask format attributes are valid at surface creation time. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + New EGLConfig bitmask attribute name: + + EGL_CONFORMANT_KHR 0x3042 + + Valid bitfields in the EGL_SURFACE_TYPE bitmask attribute + of EGLConfig: + + EGL_VG_COLORSPACE_LINEAR_BIT_KHR 0x0020 + EGL_VG_ALPHA_FORMAT_PRE_BIT_KHR 0x0040 + +Additions to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors) + + Add to table 3.1, "EGLConfig attributes": + + Attribute Type Notes + --------- ---- ----- + EGL_CONFORMANT_KHR bitmask whether contexts created with + this config are conformant + + Add to table 3.2, "Types of surfaces supported by an EGLConfig": + + EGL Token Name Description + -------------- ----------- + EGL_VG_COLORSPACE_LINEAR_BIT_KHR EGLConfig supports OpenVG rendering + in linear colorspace + EGL_VG_ALPHA_FORMAT_PRE_BIT_KHR EGLConfig supports OpenVG rendering + with premultiplied alpha + + Add following the second paragraph of "Other EGLConfig Attribute + Descriptions" in section 3.4 on p. 16: + + "If EGL_VG_COLORSPACE_LINEAR_BIT_KHR is set in EGL_SURFACE_TYPE, + then the EGL_COLORSPACE attribute may be set to + EGL_COLORSPACE_LINEAR when creating a window, pixmap, or pbuffer + surface (see section 3.5)." + + "If EGL_VG_ALPHA_FORMAT_PRE_BIT_KHR is set in EGL_SURFACE_TYPE, + then the EGL_ALPHA_FORMAT attribute may be set to + EGL_ALPHA_FORMAT_PRE when creating a window, pixmap, or pbuffer + surface (see section 3.5)." + + Add at the end of the fourth paragraph (description of + EGL_CONFIG_CAVEAT) on p. 17: + + "... required OpenGL ES conformance tests (note that + EGL_NON_CONFORMANT_CONFIG is obsolete, and the same information + can be obtained from the EGL_CONFORMANT_KHR attribute on a + per-client-API basis, not just for OpenGL ES." + + "EGL_CONFORMANT_KHR is a mask indicating if a client API context + created with respect to the corresponding EGLConfig will pass + the required conformance tests for that API. The valid bit + settings are the same as for EGL_RENDERABLE_TYPE, as defined in + table 3.3, but the presence or absence of each client API bit + determines whether the corresponding context will be conformant + or non-conformant(fn1)." + + "(fn1) most EGLConfigs should be conformant for all supported + client APIs. Conformance requirements limit the number of + non-conformant configs that an implementation can define." + + Add to the last paragraph of section 3.5.1 on p. 24 (describing + eglCreateWindowSurface): + + "If <config> does not support the colorspace or alpha format + attributes specified in <attrib_list> (e.g. if EGL_COLORSPACE is + specified as EGL_COLORSPACE_LINEAR but the EGL_SURFACE_TYPE + attribute of <config> does not include + EGL_VG_COLORSPACE_LINEAR_BIT_KHR, or if EGL_ALPHA_FORMAT is + specified as EGL_ALPHA_FORMAT_PRE but EGL_SURFACE_TYPE does not + include EGL_VG_ALPHA_FORMAT_PRE_BIT_KHR), an EGL_BAD_MATCH error + is generated." + + Add to the next-to-last paragraph of section 3.5.2 on p. 26 + (describing eglCreatePbufferSurface): + + "If <config> does not support the colorspace or alpha format + attributes specified in <attrib_list> (as defined for + eglCreateWindowSurface), an EGL_BAD_MATCH error is generated." + + Add to the last paragraph of section 3.5.4 on p. 29 (describing + eglCreatePixmapSurface): + + "If <config> does not support the colorspace or alpha format + attributes specified in <attrib_list> (as defined for + eglCreateWindowSurface), an EGL_BAD_MATCH error is generated." + +Issues + + 1) How should colorspace and alpha format restrictions be specified? + OpenVG implementations may not allow linear colorspace or + premultiplied alpha rendering to all configs they support. + + RESOLVED: To maximize compatibility with EGL 1.3, we continue to + specify the desired colorspace and alpha format at surface + creation time. However, surface creation may fail if if the + specified colorspace or alpha format are not supported. + + To allow apps to detect this situation, this extension adds + EGLConfig attributes specifying *if* linear colorspace and/or + premultiplied alpha formats are supported. If they are not + supported, surface creation with the corresponding attributes + set will fail with an EGL_BAD_MATCH error. + + 2) How should the colorspace and alpha format capabilities be + exposed in EGLConfigs? + + RESOLVED: as bitfields of the existing EGL_SURFACE_TYPE bitmask + attribute. + + A separate bitmask might be more orthogonal, but there are + plenty of unused bits in EGL_SURFACE_TYPE and this minimizes API + and programming complexity. + + 3) Are support for linear colorspace and and premultiplied alpha + formats orthogonal? + + RESOLVED: Yes, according to the OpenVG Working Group. If they + were not orthogonal, we could not specify them as independent + bitfields. + + 4) Should information about conformance be specified on a + per-client-API basis? + + RESOLVED: Yes. This is needed for conformance testing and cannot + be expressed by the EGL_CONFIG_CAVEAT attribute, which is OpenGL + ES-specific. + + 5) Should there also be a config attribute which specifies whether + EGL_RENDER_BUFFER will be respected? + + UNRESOLVED: it would be consistent to add this attribute. but + it's not clear if there's a requirement for doing so yet. + + 6) Does this extension introduce a regression against EGL 1.2? + + RESOLVED: Yes. This is unavoidable, since we're allowing failure + of surface creation that was required to succeed in the past. + However, implementations that could not support the required + colorspace or alpha mask format were effectively non-conformant + (e.g. broken) in any event. The new EGL_SURFACE_TYPE attributes + at least allow apps to know that their request will not be + satisfied. + +Dependencies on OpenGL ES + + If OpenGL ES is not supported, the EGL_OPENGL_ES_BIT in the + EGL_CONFORMANT_KHR is irrelevant. + +Dependencies on OpenVG + + If OpenVG is not supported, the EGL_OPENVG_BIT bit in + EGL_CONFORMANT_KHR, and the EGL_VG_COLORSPACE_LINEAR_BIT_KHR and + EGL_VG_ALPHA_FORMAT_PRE_BIT_KHR bits in EGL_SURFACE_TYPE, are + irrelevant. + +Revision History + + Version 5, 2007/04/05 - add enum values corresponding to EGL 1.3 + core features. + Version 4, 2006/10/24 - prefix the bitfield names with "VG" to + clarify that they only apply to OpenVG rendering to surfaces + (although the corresponding core EGL_COLORSPACE and + EGL_ALPHA_FORMAT attribute names do not currently include this + prefix). Use "KHR" suffix instead of "OES". + Version 3, 2006/10/15 - add new config attribute to express whether + configs are conformant on a per-API basis. Correct sRGB + terminology to linear (sRGB is the default, linear colorspace + rendering may not be supported). Change extension name + accordingly. + Version 2, 2006/09/26 - add _OES extension suffix to bitfield names. + Version 1, 2006/09/26 - first draft. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_create_context.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_create_context.txt new file mode 100644 index 0000000..8c992c6 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_create_context.txt @@ -0,0 +1,648 @@ +Name + + KHR_create_context + +Name Strings + + EGL_KHR_create_context + +Contact + + Jon Leech (jon 'at' alumni.caltech.edu) + +Notice + + Copyright (c) 2010-2013 The Khronos Group Inc. Copyright terms at + http://www.khronos.org/registry/speccopyright.html + +IP Status + + No known IP claims. + +Status + + Approved by the Khronos Board of Promoters on February 3, 2012 + Updated in version 14 to add ES3 context creation bit - see Issue 8 + +Version + + Version 16, 2015/01/15 + +Number + + EGL Extension #39 + +Dependencies + + EGL 1.4 is required. + + Some of the capabilities of these extensions are only available when + OpenGL and OpenGL ES contexts supporting specific versions, specific + profiles, or specific extensions can be created. All such restrictions + are documented in the body of this extension specification. + +Overview + + With the advent of new versions of OpenGL which deprecate features + and/or break backward compatibility with older versions, there is a need + and desire to indicate at context creation which interface will be used. + This extension adds a new context creation routine with attributes + specifying the OpenGL version, context properties, and profile requested + for the context. It also allows making an OpenGL 3.0 or later context + (or other client API context supporting the ability) current without + providing a default framebuffer. The new context creation attributes + are also defined to work for OpenGL ES context creation when that + makes sense, and the extension has been augmented to allow configs to + advertise support for creating OpenGL ES 3.0 contexts. + + +New Procedures and Functions + + None. + +New Tokens + + Accepted as an attribute name in the <*attrib_list> argument of + eglCreateContext: + + EGL_CONTEXT_MAJOR_VERSION_KHR 0x3098 + (this token is an alias for EGL_CONTEXT_CLIENT_VERSION) + EGL_CONTEXT_MINOR_VERSION_KHR 0x30FB + EGL_CONTEXT_FLAGS_KHR 0x30FC + EGL_CONTEXT_OPENGL_PROFILE_MASK_KHR 0x30FD + EGL_CONTEXT_OPENGL_RESET_NOTIFICATION_STRATEGY_KHR 0x31BD + + Accepted as a bitfield value in the EGL_RENDERABLE_TYPE config + attribute to eglChooseConfig: + + EGL_OPENGL_ES3_BIT_KHR 0x0040 + + Accepted as attribute values for + EGL_CONTEXT_OPENGL_RESET_NOTIFICATION_STRATEGY_KHR: + + EGL_NO_RESET_NOTIFICATION_KHR 0x31BE + EGL_LOSE_CONTEXT_ON_RESET_KHR 0x31BF + + Accepted as bits in the attribute value for EGL_CONTEXT_FLAGS_KHR in + <*attrib_list>: + + EGL_CONTEXT_OPENGL_DEBUG_BIT_KHR 0x00000001 + EGL_CONTEXT_OPENGL_FORWARD_COMPATIBLE_BIT_KHR 0x00000002 + EGL_CONTEXT_OPENGL_ROBUST_ACCESS_BIT_KHR 0x00000004 + + Accepted as bits in the attribute value for + EGL_CONTEXT_OPENGL_PROFILE_MASK_KHR in <*attrib_list>: + + EGL_CONTEXT_OPENGL_CORE_PROFILE_BIT_KHR 0x00000001 + EGL_CONTEXT_OPENGL_COMPATIBILITY_PROFILE_BIT_KHR 0x00000002 + +Additions to the OpenGL / WGL / GLX Specifications + + None. This specification is written for EGL. + +Additions to the EGL 1.4 Specification + + Add to table 3.3 "Types of client APIs supported by an EGLConfig" + + "EGL Token Name Client API and Version Supported + ---------------------- -------------------------------- + EGL_OPENGL_ES3_BIT_KHR OpenGL ES 3.x" + + Modify the last sentence of section 3.5.2 "Creating Off-Screen + Rendering Surfaces" + + "Finally, an EGL_BAD_ATTRIBUTE error is generated if ... <config> does + not support OpenGL ES rendering (e.g. the EGL_RENDERABLE_TYPE + attribute does not include at least one of EGL_OPENGL_ES_BIT, + EGL_OPENGL_ES2_BIT, or EGL_OPENGL_ES3_BIT_KHR." + + Modify section 3.7 "Rendering Contexts" in the paragraph near + the top of page 42: + + "Only one OpenGL or OpenGL ES context may be current to a particular + thread, even if the implementation supports OpenGL and one or more + versions of OpenGL ES in the same runtime [fn12]." + + Replace section 3.7.1 "Creating Rendering Contexts" from the + sixth paragraph through the end of the subsection with: + + "<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. Most attributes are only meaningful + for specific client APIs, and will generate an error when specified + to create for another client API context. + + OpenGL and OpenGL ES Context Versions + ------------------------------------- + + The values for attributes EGL_CONTEXT_MAJOR_VERSION_KHR and + EGL_CONTEXT_MINOR_VERSION_KHR specify the requested client API + version. They are only meaningful for OpenGL and OpenGL ES contexts, + and specifying them for other types of contexts will generate an + error. + + When the current rendering API is EGL_OPENGL_ES_API or + EGL_OPENGL_API, the values of EGL_CONTEXT_MAJOR_VERSION_KHR (the + <major version> and EGL_CONTEXT_MINOR_VERSION_KHR (the <minor + version>) request creation of an OpenGL ES or OpenGL context, + respectively, supporting the specified version (<major>.<minor>) of + that client API. + [fn: the EGL 1.4 token EGL_CONTEXT_CLIENT_VERSION is an alias for + EGL_CONTEXT_MAJOR_VERSION_KHR, and the tokens may be used + interchangeably.] + If successful, the context returned must be <backwards compatible> + with the requested version. Backwards compatibility is determined as + follows: + + If the current rendering API is EGL_OPENGL_ES_API, then: + + * If version 1.0 is requested, the context returned may implement + either OpenGL ES 1.0 or OpenGL ES 1.1. + + * If version 1.1 is requested, the context returned must implement + OpenGL ES 1.1. + + * If version 2.0, version 3.0, or a later version (when later + versions are defined by Khronos) is requested, the context + returned must implement the requested OpenGL ES version, or any + later version which is backwards compatible with the requested + version. + + If the current rendering API is EGL_OPENGL_API, then: + + * If a version less than or equal to OpenGL 3.0 is requested, the + context returned may implement any of the following versions: + + * Any version no less than that requested and no greater than + 3.0. + * Version 3.1, if the GL_ARB_compatibility extension is also + implemented. + * The compatibility profile of version 3.2 or greater. + + * If OpenGL 3.1 is requested, the context returned may implement + any of the following versions: + + * Version 3.1. The GL_ARB_compatibility extension may or may + not be implemented, as determined by the implementation. + * The core profile of version 3.2 or greater. + + * If OpenGL 3.2 or greater is requested, the context returned may + implement any of the following versions: + + * The requested profile (see + EGL_CONTEXT_OPENGL_PROFILE_MASK_KHR below) of the requested + version. + * The requested profile of any later version, so long as no + features have been removed from that later version and + profile. + + Typically, the implementation will return the most recent version of + OpenGL it supports which is backwards compatible with the requested + version. + + Querying the GL_VERSION string with glGetString in either OpenGL or + OpenGL ES (or the GL_MAJOR_VERSION and GL_MINOR_VERSION values with + glGetIntegerv, in an OpenGL 3.0 or later context) will return the + actual version supported by a context. + + The default values for EGL_CONTEXT_MAJOR_VERSION_KHR and + EGL_CONTEXT_MINOR_VERSION_KHR are 1 and 0 respectively. + + OpenGL Context Profiles + ----------------------- + + The value for attribute EGL_CONTEXT_OPENGL_PROFILE_MASK_KHR + specifies a <profile> of the OpenGL API. This attribute is only + meaningful for OpenGL contexts, and specifying it for other types of + contexts, including OpenGL ES contexts, will generate an error. + + When the current rendering API is EGL_OPENGL_API, the value of + EGL_CONTEXT_OPENGL_PROFILE_MASK_KHR requests an OpenGL context + supporting the corresponding profile. If the + EGL_CONTEXT_OPENGL_CORE_PROFILE_BIT_KHR bit is set in the attribute + value, then a context implementing the <core> profile of OpenGL is + returned. If the EGL_CONTEXT_OPENGL_COMPATIBILITY_PROFILE_BIT_KHR + bit is set, then a context implementing the <compatibility> profile + is returned. If the requested OpenGL version is less than 3.2, + EGL_CONTEXT_OPENGL_PROFILE_MASK_KHR is ignored and the functionality + of the context is determined solely by the requested version. + + Querying the value of GL_CONTEXT_PROFILE_MASK with glGetIntegerv + will return the profile mask used to create the context. This query + is only supported in an OpenGL 3.2 or later context. + + The default value for EGL_CONTEXT_OPENGL_PROFILE_MASK_KHR is + EGL_CONTEXT_OPENGL_CORE_PROFILE_BIT_KHR. All OpenGL 3.2 and later + implementations are required to implement the core profile, but + implementation of the compatibility profile is optional. + + If the core profile is requested, then the context returned cannot + implement functionality defined only by the compatibility profile. + + OpenGL and OpenGL ES Context Flags + ---------------------------------- + + The value for attribute EGL_CONTEXT_FLAGS_KHR specifies a set of flag + bits affecting the context. Flag bits are only meaningful when creating + certain types of contexts, as described for each bit below, and + specifying such a flag bit when creating another type of context will + generate an error. + + If the EGL_CONTEXT_OPENGL_DEBUG_BIT_KHR flag bit is set in + EGL_CONTEXT_FLAGS_KHR, then a <debug context> will be created. Debug + contexts are intended for use during application development, to + provide additional runtime checking, validation, and logging + functionality while possibly incurring performance penalties. The + additional functionality provided by debug contexts may vary + according to the implementation(fn). In some cases a debug context + may be identical to a non-debug context. This bit is supported for + OpenGL and OpenGL ES contexts. + [fn: Khronos is still defining the expected and required + features of debug contexts, so implementations are + currently free to implement "debug contexts" with little or + no debug functionality. However, OpenGL and OpenGL ES + implementations supporting the GL_KHR_debug extension + should enable it when this bit is set.] + [fn2: See issue 9 below for discussion of backwards + compatibility issues with the debug bit and OpenGL ES + contexts.] + + If the EGL_CONTEXT_OPENGL_FORWARD_COMPATIBLE_BIT_KHR flag bit is set + in EGL_CONTEXT_FLAGS_KHR, then a <forward-compatible> context will + be created. Forward-compatible contexts are defined only for OpenGL + versions 3.0 and later. They must not support functionality marked + as <deprecated> by that version of the API, while a + non-forward-compatible context must support all functionality in + that version, deprecated or not. This bit is supported for OpenGL + contexts, and requesting a forward-compatible context for OpenGL + versions less than 3.0 will generate an error. + + If the EGL_CONTEXT_OPENGL_ROBUST_ACCESS_BIT_KHR bit is set in + EGL_CONTEXT_FLAGS_KHR, then a context supporting <robust buffer + access> will be created. Robust buffer access is defined in the + GL_ARB_robustness extension specification, and the resulting context + must also support either the GL_ARB_robustness extension, or a + version of OpenGL incorporating equivalent functionality. This bit + is supported for OpenGL contexts. + + The default value of EGL_CONTEXT_FLAGS_KHR is zero. + + OpenGL Context Reset Notification + --------------------------------- + + The attribute name + EGL_CONTEXT_OPENGL_RESET_NOTIFICATION_STRATEGY_KHR specifies the + <reset notification behavior> of the rendering context. This + attribute is only meaningful for OpenGL contexts, and specifying it + for other types of contexts, including OpenGL ES contexts, will + generate an error. + + Reset notification behavior is defined in the GL_ARB_robustness + extension specification, and the resulting context must also support + either the GL_ARB_robustness extension, or a version of OpenGL or + incorporating equivalent functionality. The attribute value may be + either EGL_NO_RESET_NOTIFICATION_KHR or + EGL_LOSE_CONTEXT_ON_RESET_KHR, which respectively result in reset + notification behavior of GL_NO_RESET_NOTIFICATION_ARB and + GL_LOSE_CONTEXT_ON_RESET_ARB, as described by GL_ARB_robustness. The + default value for EGL_CONTEXT_OPENGL_RESET_NOTIFICATION_STRATEGY_KHR + is EGL_NO_RESET_NOTIFICATION_KHR. + + Errors + ------ + + On failure eglCreateContext returns EGL_NO_CONTEXT and generates an + EGL error with extended error information. Conditions that cause + failure include: + + * If an attribute is specified that is not meaningful for the + client API type determined by the current rendering API, an + EGL_BAD_ATTRIBUTE error is generated. + + * If the current rendering api is EGL_NONE, then an EGL_BAD_MATCH + error is generated (this situation can only arise in an + implementation which does not support OpenGL ES 1.x, and prior to + the first call to eglBindAPI). + + * If share_context is neither EGL_NO_CONTEXT nor a valid context + of the same client API type as the newly created context, then + an EGL_BAD_CONTEXT error is generated. + + * If <config> is not a valid EGLConfig, or does not support the + requested client API, then an EGL_BAD_CONFIG error is generated + (this includes requesting creation of an OpenGL ES 1.x, 2.0, or + 3.0 context when the EGL_RENDERABLE_TYPE attribute of <config> + does not contain EGL_OPENGL_ES_BIT, EGL_OPENGL_ES2_BIT, or + EGL_OPENGL_ES3_BIT_KHR respectively). + + * If <config> does not support a client API context compatible + with the requested API major and minor version, context flags, + and context reset notification behavior (for client API types + where these attributes are supported), then an EGL_BAD_MATCH + error is generated. + + * If an OpenGL context is requested, the requested version is + greater than 3.2, and the value for attribute + EGL_CONTEXT_OPENGL_PROFILE_MASK_KHR has no bits set; has any + bits set other than EGL_CONTEXT_OPENGL_CORE_PROFILE_BIT_KHR and + EGL_CONTEXT_OPENGL_COMPATIBILITY_PROFILE_BIT_KHR; has more than + one of these bits set; or if the implementation does not support + the requested profile, then an EGL_BAD_MATCH error is generated. + + * If an OpenGL or OpenGL ES context is requested and the server + context state for <share_context> exists in an address space + that cannot be shared with the newly created context, if + <share_context> was created on a different display than the one + referenced by <config>, if the reset notification behavior of + <share_context> and the newly created context are different, or + if the contexts are otherwise incompatible (for example, one + context being associated with a hardware device driver and the + other with a software renderer), then an EGL_BAD_MATCH error is + generated. + + * If the server does not have enough resources to allocate the new + context, then an EGL_BAD_ALLOC error is generated. + + * If an OpenGL context is requested and the values for attributes + EGL_CONTEXT_MAJOR_VERSION_KHR and EGL_CONTEXT_MINOR_VERSION_KHR, + when considered together with the value for attribute + EGL_CONTEXT_OPENGL_FORWARD_COMPATIBLE_BIT_KHR, specify an OpenGL + version and feature set that are not defined, than an + EGL_BAD_MATCH error is generated. + + The defined versions of OpenGL at the time of writing are OpenGL + 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 2.0, 2.1, 3.0, 3.1, 3.2, 4.0, 4.1, + 4.2, and 4.3. Feature deprecation was introduced with OpenGL + 3.0, so forward-compatible contexts may only be requested for + OpenGL 3.0 and above. Thus, examples of invalid combinations of + attributes include: + + - Major version < 1 or > 4 + - Major version == 1 and minor version < 0 or > 5 + - Major version == 2 and minor version < 0 or > 1 + - Major version == 3 and minor version < 0 or > 2 + - Major version == 4 and minor version < 0 or > 3 + - Forward-compatible flag set and major version < 3 + + Because the purpose of forward-compatible contexts is to allow + application development on a specific OpenGL version with the + knowledge that the app will run on a future version, context + creation will fail if + EGL_CONTEXT_OPENGL_FORWARD_COMPATIBLE_BIT_KHR is set and the + context version returned cannot implement exactly the requested + version. + + * If an OpenGL ES context is requested and the values for + attributes EGL_CONTEXT_MAJOR_VERSION_KHR and + EGL_CONTEXT_MINOR_VERSION_KHR specify an OpenGL ES version that + is not defined, than an EGL_BAD_MATCH error is generated. + + The defined versions of OpenGL ES at the time of writing are + OpenGL ES 1.0, 1.1, 2.0, and 3.0. Examples of invalid + combinations of attributes include: + + - Major version < 1 or > 3 + - Major version == 1 and minor version < 0 or > 1 + - Major version == 2 and minor version != 0 + - Major version == 3 and minor version != 0 + + * If an attribute name or attribute value in <attrib_list> is not + recognized (including undefined or unsupported bits in bitmask + attributes), then an EGL_BAD_ATTRIBUTE error is generated." + + In section 3.7.3, replace the following two error conditions in the + list of eglMakeCurrent errors: + + " * If <ctx> is not a valid context, an EGL_BAD_CONTEXT error is + generated. + * If either <draw> or <read> are not valid EGL surfaces, an + EGL_BAD_SURFACE error is generated." + + with the following error conditions: + + " * If <ctx> is not a valid context and is not EGL_NO_CONTEXT, an + EGL_BAD_CONTEXT error is generated. + * If either <draw> or <read> are not valid EGL surfaces and are + not EGL_NO_SURFACE, an EGL_BAD_SURFACE error is generated. + * If <ctx> is EGL_NO_CONTEXT and either <draw> or <read> are not + EGL_NO_SURFACE, an EGL_BAD_MATCH error is generated. + * If either of <draw> or <read> is a valid surface and the other + is EGL_NO_SURFACE, an EGL_BAD_MATCH error is generated. + * If <ctx> does not support being bound without read and draw + surfaces, and both <draw> and <read> are EGL_NO_SURFACE, an + EGL_BAD_MATCH error is generated." + + Replace the paragraph starting "If <ctx> is EGL_NO_CONTEXT and + <draw> and <read> are not EGL_NO_SURFACE..." with + + "If both <draw> and <read> are EGL_NO_SURFACE, and <ctx> is an OpenGL + context supporting version 3.0 or later of the OpenGL API, then no + error is generated and the context is made current without a + <default framebuffer>. The meaning of this is defined in chapter 4 + of the OpenGL 3.0 Specification." + + Append to the paragraph starting "The first time an OpenGL or OpenGL + ES context is made current..." with + + "If the first time <ctx> is made current, it is without a default + framebuffer (e.g. both <draw> and <read> are EGL_NO_SURFACE), then + the viewport and scissor regions are set as though + glViewport(0,0,0,0) and glScissor(0,0,0,0) were called." + + +Errors + + EGL errors for eglCreateContext as described in the body of the + specification. + + eglMakeCurrent error behavior is relaxed to allow making an OpenGL + 3.0 or later context current without a default read or draw + framebuffer. + +Conformance Tests + + TBD + +Sample Code + + TBD + +Issues + + Non-window-system dependent issues described in the + WGL_ARB_create_context extension specification in the OpenGL + Registry apply to EGL_KHR_create_context. + + 1) Do enumerant values need to be shared with the equivalent WGL / GLX + extensions? + + Mostly not. The only case where it's fairly important that the + values be identical is the EGL_CONTEXT_FLAGS_KHR attribute bitmask + values, which are also exposed through an OpenGL query. + + 2) Why are some attribute values named EGL_CONTEXT_OPENGL_*? + + It is possible that context flags and profiles will eventually be + defined for client APIs other than OpenGL. To allow for this + possibility, the names of the corresponding attribute values are + distinguished. For example, EGL_CONTEXT_FLAGS_KHR currently only has + flags defined for OpenGL context creation, and those flags are named + EGL_CONTEXT_OPENGL_*_BIT_KHR, but in time OpenVG context creation + might allow flags as well. Such flags would be named + EGL_CONTEXT_OPENVG_*_BIT_KHR. + + 3) Why does EGL_CONTEXT_MAJOR_VERSION_KHR have a distinct numeric token + value when it is functionally equivalent to + EGL_CONTEXT_CLIENT_VERSION? + + It no longer has a distinct token value; see issue 1. + + 4) How will future versions of OpenGL ES interact with this extension? + + Later context versions which are backwards compatibile with the + requested version can be returned, just as with OpenGL contexts. + + 5) What happens when requesting a context requiring OpenGL functionality + that cannot be supported by the underlying GL implementation, such as + requesting lost context reset notification and/or robust buffer access + when the implementation does not support the functionality defined by + GL_ARB_robustness? + + Context creation will fail and an EGL_BAD_MATCH error will be + generated. This case is included under the general language of the + fifth bullet point under "Errors" but this issue is added to for + clarity. + + 6) How is robust buffer access and reset notification supported under + OpenGL ES? + + RESOLVED: It is an error to request robust buffer access and/or reset + notification for OpenGL ES contexts. Exposing robust buffer access and + reset notification for OpenGL ES contexts may be defined in a future EGL + extension. + + 7) Future support for OpenGL ES context creation. + + If and when features available for OpenGL context creation are defined + for OpenGL ES context creation in the future, debug contexts, forward + compatible contexts, and robust buffer access contexts may be specified + using separate attributes rather than bitmasks. The reset notification + behavior attribute may be extended to cover OpenGL ES as well as OpenGL. + + 8) Why was the EGL_OPENGL_ES3_BIT_KHR added in version 13 of the + extension? Doesn't this break backwards compatibility with older + versions of the extension? + + Applications need the functionality to be confident that context + creation of an OpenGL ES 3.0 context will succeed (rather than trying + it with different configs until one that succeeds is found). + + If this bit is passed into eglChooseConfig and the implementation + supports only an older version of the extension, an EGL_BAD_ATTIBUTE + error should be generated. Since no matching configs will be found, a + robustly-written application will fail (or fall back to an ES 2.0 + rendering path) at this point. This is the same application behavior + that should result from not finding a matching config on an + implementation supporting version 13 of the extension, even though the + failure mode is different (EGL error vs. returning no matching + configs). The EGL Working Group considers this sufficiently benign + behavior, and the functionality important enough, to make the change. + + 9) Why was OpenGL ES support for EGL_CONTEXT_OPENGL_DEBUG_BIT_KHR added + in version 15 of the extension? Doesn't this break backwards + compatibility with older versions of the extension? + + Now that the GL_KHR_debug extension is ratified and available, + OpenGL ES implementers needed a way to enable debug functionality, + and wanted to use the same mechanism as OpenGL. There is no + discovery mechanism for this capability, so an application creating + a OpenGL ES context with the debug bit set and running against an + older EGL driver should generate an error. The OpenGL ES Working + Group considers this benign behavior. + + 10) Which error should be generated if robust buffer access or reset + notifications are requested under OpenGL ES? + + As per Issue 6, this extension does not support creating robust contexts + for OpenGL ES. This is only supported via the EGL_EXT_create_context_- + robustness extension. + + Attempting to use this extension to create robust OpenGL ES context + will generate an EGL_BAD_ATTRIBUTE error. This specific error is generated + because this extension does not define the EGL_CONTEXT_OPENGL_ROBUST_- + ACCESS_BIT_KHR and EGL_CONTEXT_OPENGL_RESET_NOTIFICATION_STRATEGY_KHR bits + for OpenGL ES contexts. Thus, use of these bits fall under condition + described by: "If an attribute is specified that is not meaningful for + the client API type.." in the above specification. + +Revision History + + Version 16, 2015/01/15 + - Add issue 10. + + Version 15, 2013/03/27 + - Add OpenGL ES support for debug contexts (Bug 10035). + + Version 14, 2012/09/19 + - Assign enum value to new bit and published updated extension. + + Version 13, 2012/07/29 + - Add EGL_OPENGL_ES3_BIT_KHR to table 3.3 and sections 3.5.2, 3.7, + and 3.7.1. Add issue 8 explaining the addition. + + Version 12, 2012/07/25 + - Explicitly describe new OpenGL 4.3 and OpenGL ES 3.0 versions. + This is not a behavior change (Khronos Bug 9136). + - Make spec consistent so that asking for a forward-compatible GL + context for versions less than 3.0 is an error (Bug 9314). + - Change nonexistent EGL_BAD_PROFILE_KHR error generated when + asking for an unsupported or nonexistent GL profile to an + EGL_BAD_MATCH error (Bug 9314). + - Fix typos in spec body for several new tokens of form + "EGL_CONTEXT_OPENGL_*" which were missing the "OPENGL_" part + (Bug 9314). + + Version 11, 2012/07/09 - change nonexistent EGL_BAD_VALUE error + to EGL_BAD_ATTRIBUTE (Khronos Bug 9269). + + Version 10, 2011/11/22 - fix typo. + + Version 9, 2011/11/09 - resolve issue 6 and add issue 7, limiting + various context creation attributes to apply only to OpenGL and not + to OpenGL ES. + + Version 8, 2011/10/20 - change spec body to match BAD_MATCH error + returned in issue 5 when specifying context version and attributes + that collectively cannot be satisfied. + + Version 7, 2011/10/19 - add issue 5 clarifying context creation + failures when requesting functionality that cannot be supported by a + GL or ES context, and issue 6 discussing the meaning of "equivalent + to GL_ARB_robustness". + + Version 6, 2011/10/19 - minor cleanup & clarification of OpenGL ES + version requests. + + Version 5, 2010/09/22 - add context reset notification strategy + attributes from GLX/WGL context creation extensions. + + Version 4, 2010/09/22 - fix typo. Assign enumerant values and update + issue 1 to match. Add caveat to errors section so that invalid + attribute values for EGL_CONTEXT_OPENGL_PROFILE_MASK_KHR only raise + errors when requesting an OpenGL context of version 3.2 or greater + (bug 6374). Add issue 4 and allow ES 2.0 context creation requests + to return later versions that are backwards-compatible (bug 6374). + + Version 3, 2010/07/21 - remove surfaceless bit in favor of separate + per-client-API extensions which promise that contexts of a given + client API type can be bound without surfaces on that display. Add + robust buffer access bit from equivalent WGL/GLX context creation + extensions. Rename EGL_CONTEXT_FLAGS_KHR so it's not specific to + OpenGL. + + Version 2, 2010/06/29 - add EGL_CONTEXT_OPENGL_SURFACELESS_BIT_KHR + context flag bit (bug 6082). + + Version 1, 2010/06/29 - Initial version based on equivalent + WGL_ARB_create_context and GLX_ARB_create_context extensions. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_create_context_no_error.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_create_context_no_error.txt new file mode 100644 index 0000000..499293c --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_create_context_no_error.txt @@ -0,0 +1,142 @@ +Name + + KHR_create_context_no_error + +Name Strings + + EGL_KHR_create_context_no_error + +Contributors + + Maurice Ribble + Dominik Witczak + Christophe Riccio + Piers Daniell + Jon Leech + James Jones + Daniel Kartch + Steve Hill + Jan-Harald Fredriksen + +Contact + + Maurice Ribble (mribble 'at' qti.qualcomm.com) + +Status + + Complete. + Approved by the Khronos Board of Promoters on May 8, 2015. + +Version + + Version 6, May 8, 2015 + +Number + + EGL Extension #91 + +Dependencies + + Requires EGL 1.4. + + Written against the EGL 1.4 specification. + + This spec interacts with GL_KHR_no_error (or equivalent) extension. + +Overview + + This extension allows the creation of an OpenGL or OpenGL ES context that + doesn't generate errors if the context supports a no error mode. The + implications of this feature are discussed in the GL_KHR_no_error + extension. + +New Procedures and Functions + + None + +New Tokens + + Accepted as an attribute name in the <*attrib_list> argument to + eglCreateContext: + + EGL_CONTEXT_OPENGL_NO_ERROR_KHR 0x31B3 + +Additions to the EGL 1.4 Specification + + Add the following to section 3.7.1 "Creating Rendering Contexts": + + EGL_CONTEXT_OPENGL_NO_ERROR_KHR indicates whether a faster and lower power + mode should be enabled for the OpenGL ES context. In this mode instead of + GL errors occurring as defined in the OpenGL ES spec those errors will + result in undefined behavior. The default value of + EGL_CONTEXT_OPENGL_NO_ERROR_KHR is EGL_FALSE. + +Errors + + BAD_MATCH is generated if the value of EGL_CONTEXT_OPENGL_NO_ERROR_KHR + used to create <share_context> does not match the value of + EGL_CONTEXT_OPENGL_NO_ERROR_KHR for the context being created. + + BAD_MATCH is generated if the EGL_CONTEXT_OPENGL_NO_ERROR_KHR is TRUE at + the same time as a debug or robustness context is specified. + +New State + + None + +Conformance Tests + + TBD + +Issues + + (1) How does this extension interact with debug and robust contexts? + + RESOLVED: We decided it is an error in EGL if these bits were set at the same + time. + + (2) Can a EGL_CONTEXT_OPENGL_NO_ERROR_KHR contexts share resources with + normal contexts? + + RESOLVED: To join a share group all the contexts in that share group must + have this set the same or creation of the context fails. + + (3) Can we also do this on GLX/WGL? + + RESOLVED: This is an EGL extension. GLX/WGL should be handled with separate + extensions. + + (4) Should this extension also expose a "no thread safety" mode? For example + to do the rendering on one thread but uploading data or compiling shaders + from others threads without having the cost of threaded safety kicking in + because none of these tasks overlap so we can handle with sync objects. + Compiling shaders, loading data and rendering are areas that removed + threading may help. + + RESOLVED: No, this should be done as a separate extension. + + (5) Should this be GL specific? + + RESOLVED: Yes, because other context creation tokens have been API specific. + This is also the safer path since it's unknown if other APIs might want to do + this slightly differently. + + (6) Should creating a context fail if the context created context does not + support a no error mode? + + RESOLVED: No. Expect context creation to succeed even if the implementation + can't honor the request for a no error context. This reduces the number of + reasons creating a context can fail and seems to be a more forward looking + resolution considering context flags allow GL apps to query what context + flags are set. + +Revision History + + Rev. Date Author Changes + ---- ------------ --------- ---------------------------------------- + 1 Jan 28, 2015 ribble Initial version + 2 Jan 29, 2015 ribble Added issues list + 3 Jan 30, 2015 ribble Split into separate GL and EGL extensions + 4 Feb 18, 2015 ribble Resolved issues and cleanup + 5 Feb 25, 2015 ribble Rename, better define errors and cleanup + 6 May 8, 2015 Jon Leech Assign enum value and release. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_debug.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_debug.txt new file mode 100644 index 0000000..e839a9e --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_debug.txt @@ -0,0 +1,573 @@ +Name + + KHR_debug + +Name Strings + + EGL_KHR_debug + +Contributors + + Jeff Vigil, Qualcomm + Brian Ellis, Qualcomm + (Original contributors of Gl_KHR_debug extension for OpenGL/GL_ES) + Mark Callow, HI + John Leech, Khronos + Ray Smith, ARM + Prabindh Sundareson, Texas Instruments + James Jones, NVIDIA + Jesse Hall, Google + +Contact + + Jeff Vigil (jvigil 'at' qualcomm.com) + +Notice + + Copyright (c) 2012-2015 The Khronos Group Inc. Copyright terms at + http://www.khronos.org/registry/speccopyright.html + +Status + + Complete. Approved by the EGL Working Group on 2015/04/24. + Approved by the Khronos Board of Promoters on 2015/06/26. + +Version + + Version 18, Modified Date: September 28, 2016 + +Number + + EGL Extension #92 + +Extension Type + + EGL client extension + +Dependencies + + Applicable to any version of EGL 1.x, but written in relationship + to EGL 1.5. + +Overview + + This extension allows EGL to notify applications when various events + occur that may be useful during application development and debugging. + + These events are represented in the form of debug messages with a + human-readable string representation. Examples of debug events include + errors due to incorrect use of the EGL API, warnings of undefined behavior, + and performance warnings. + + The "type" of the message roughly identifies the nature of the event that + caused the message. Examples include input errors, performance + information, or warnings about undefined behavior. + + Messages are communicated to the application through an application- + defined callback function that is called by the EGL implementation on + each debug message. The motivation for the callback routine is to free + application developers from actively having to query whether an EGL error, + or any other debuggable event has happened after each call to a EGL + function. With a callback, developers can keep their code free of debug + checks, set breakpoints in the callback function, and only have to react + to messages as they occur. The callback also offers much more information + than just an error code. + + To control the volume of debug output, types of messages can be enabled or + disabled. The mechanism is controlled by attributes passed to EGL. The + state of the message type control can be queried. + + Debug output can be enabled and disabled by changing the callback function. + NULL will disable the feature while a valid function pointer will enable + it. + + Finally, this extension defines a mechanism for EGL applications to + label their objects (contexts, surfaces, syncs, etc.) with a pointer + to an application provided structure. This pointer can be a descriptive + string, identifier or pointer to a structure. This enables the application + to associate the EGL object with application information. EGL will not + interpret this pointer as a string or any other meaning - just attach to + the object and pass back in the callback when that object is the primary + object of an event. + +IP Status + + No known IP claims. + +New Procedures and Functions + + EGLint eglDebugMessageControlKHR( + EGLDEBUGPROCKHR callback, + const EGLAttrib* attrib_list); + + EGLBoolean eglQueryDebugKHR( + EGLint attribute, + EGLAttrib* value); + + EGLInt eglLabelObjectKHR( + EGLDisplay display, + EGLenum objectType, + EGLObjectKHR object, + EGLLabelKHR label); + +New Types + + A general type to identify EGL objects, such as EGLSurface or EGLContext. + + typedef void* EGLObjectKHR; + + A label is a string, ID or pointer to a structure that the application + can attach to an EGL object. + + typedef void* EGLLabelKHR; + + The callback function that applications can define, and is accepted by + eglDebugMessageControlKHR, is defined as: + + typedef void (APIENTRY *EGLDEBUGPROCKHR)( + EGLenum error, + const char *command, + EGLint messageType, + EGLLabelKHR threadLabel, + EGLLabelKHR objectLabel, + const char* message); + +New Tokens + + Tokens accepted by the <objectType> parameter of function + eglLabelObjectKHR: + + EGL_OBJECT_THREAD_KHR 0x33B0 + EGL_OBJECT_DISPLAY_KHR 0x33B1 + EGL_OBJECT_CONTEXT_KHR 0x33B2 + EGL_OBJECT_SURFACE_KHR 0x33B3 + EGL_OBJECT_IMAGE_KHR 0x33B4 + EGL_OBJECT_SYNC_KHR 0x33B5 + EGL_OBJECT_STREAM_KHR 0x33B6 + + Tokens provided by the <messageType> parameter of EGLDEBUGPROCKHR + or the attributes input to eglControlDebugMessageKHR or attribute + of eglQueryDebugKHR: + + EGL_DEBUG_MSG_CRITICAL_KHR 0x33B9 + EGL_DEBUG_MSG_ERROR_KHR 0x33BA + EGL_DEBUG_MSG_WARN_KHR 0x33BB + EGL_DEBUG_MSG_INFO_KHR 0x33BC + + Tokens provided by the input attribute to eglQueryDebugKHR: + + EGL_DEBUG_CALLBACK_KHR 0x33B8 + +Additions to Chapter 3 of the EGL 1.5 Specification +(EGL Functions and Errors) + + Add new Section 3.13: + + "3.13 - Debug Output + + Application developers can obtain more information from EGL runtime in + the form of debug output. This information can include details about EGL + errors, undefined behavior, implementation-dependent performance warnings, + or other useful hints. + + This information is communicated through a stream of debug messages that + are generated as EGL commands are executed. The application can + receive these messages through a callback routine. + + Controls are provided for disabling classes of messages that the + application does not care about. + + Debug output functionality is controlled with: + + EGLint eglDebugMessageControlKHR( + EGLDEBUGPROCKHR callback, + const EGLAttrib* attrib_list); + + If the <callback> parameter is NULL, then no messages are sent to the + callback function and the debug message generation is disabled. If the + <callback> parameter is a pointer to a valid callback function, as defined + by EGLDEBUGPROCKHR, then messages will be sent to that callback function. + + The attribute list <attrib_list> contains a set of message type enums, + and each has a value of EGL_TRUE to enable that class of messages, + or value EGL_FALSE to disable that class of message. + + If the <attrib_list> contains an unknown attribute or value the function + will return a EGL_BAD_ATTRIBUTE error. + + If there is no error, then the function will set the updated callback, + set the updated message types and return EGL_SUCCESS. + + The messages types, their purpose and initial states are given in + table 13.1 below. The parameter <attrib_list> needs only contain the + attributes to change; an application can call eglDebugMessageControl more + than once with a valid callback, and change the message type states as + desired. + + When the callback is set to NULL; the attributes are reset to their + default values. + + Debug Output Message Type Informs about Initial/Default state + ------------------------- ------------- --------------------- + EGL_DEBUG_MSG_CRITICAL_KHR Internal EGL driver failures ENABLED + i.e. EGL_BAD_ALLOC, + EGL_CONTEXT_LOST + + EGL_DEBUG_MSG_ERROR_KHR Input and bad match errors ENABLED + i.e. EGL_BAD_CONTEXT, + EGL_BAD_PARAMETER... + + EGL_DEBUG_MSG_WARN_KHR Warnings, code is EGL_SUCCESS, DISABLED + but message indicates + deprecated or inefficient + operation. + + EGL_DEBUG_MSG_INFO_KHR Verbose operation DISABLED + Messages such as object + creation and destruction + or change in state. + + --------------------------------------------------------------------------- + Table 13.1: Types of debug output messages. Each debug message is associated + with one of these types that describes the nature or class of the message. + + 3.13.1 - Debug Message Callback + + Applications must provide a callback function for receiving debug messages + of the following type: + + typedef void (APIENTRY *EGLDEBUGPROCKHR)( + EGLenum error, + const char *command, + EGLint messageType, + EGLLabelKHR threadLabel, + EGLLabelKHR objectLabel, + const char* message); + + The function's prototype must follow the type definition of EGLDEBUGPROCKHR. + Only one debug callback can be in-use for the application, and + further calls overwrite the previous callback. Specifying NULL as the + value of <callback> clears the current callback and disables message + output. + + The callback will receive the following in its parameters: + + <error> will contain an EGL error code, or EGL_SUCCESS, as applicable. + + <command> will contain a pointer to a string. Example "eglBindApi". + + <messageType> will contain one of the debug message types listed in + table 13.1. + + <threadLabel> will contain the label attached to the current thread. + The <threadLabel> will be NULL if not set by the application. If the + message is from an internal thread, the label will be NULL. + + <objectLabel> will contain the label attached to the primary object + of the message; Labels will be NULL if not set by the application. + The primary object should be the object the function operates on, see + table 13.2 which provides the recommended mapping between functions and + their primary object. This <objectLabel> may be NULL even though the + application labeled the object. This is because it is possible an error + was raised while executing the command before the primary object was + validated, therefore its label cannot be included in the callback. + + <message> will contain a platform specific debug string message; + This string should provide added information to the application + developer regarding the condition that generated the message. + The format of a message is implementation-defined, although it should + represent a concise description of the event that caused the message + to be generated. Message strings can be NULL and should not be assumed + otherwise. + + EGL Command Primary object + ------------------------- ------------- + + eglBindAPI thread + eglBindTexImage surface + eglChooseConfig display + eglClientWaitSync sync + eglCopyBuffers surface + eglCreateContext display + eglCreateImage display + eglCreatePbufferFromClientBuffer display + eglCreatePbufferSurface display + eglCreatePixmapSurface display + eglCreatePlatformWindowSurface display + eglCreatePlatformPixmapSurface display + eglCreateSync display + eglCreateWindowSurface display + eglDestroyContext context + eglDestroyImage image + eglDestroySurface surface + eglDestroySync sync + eglGetConfigAttrib display + eglGetConfigs display + eglGetCurrentContext context + eglGetCurrentDisplay display + eglGetCurrentSurface surface + eglGetDisplay thread + eglGetError thread + eglGetPlatformDisplay thread + eglGetSyncAttrib sync + eglInitialize display + eglMakeCurrent context + eglQueryAPI context + eglQueryContext context + eglQueryString display + eglQuerySurface surface + eglReleaseTexImage surface + eglReleaseThread thread + eglSurfaceAttrib surface + eglSwapBuffers surface + eglSwapInterval surface + eglTerminate display + eglWaitClient context + eglWaitGL context + eglWaitNative thread + eglWaitSync sync + eglDebugMessageControlKHR -none- + eglQueryDebugKHR -none- + eglLabelObjectKHR labeled object + + --------------------------------------------------------------------------- + Table 13.2: Recommendation of primary object in a callback as result + of various EGL commands. + + If the application has specified a <callback> function for receiving debug + output, the implementation will call that function whenever any enabled + message is generated. A message must be posted for every error since + debug messages can be used as an alternative to eglGetError() for error + detection and handling. Specifying a callback function does not affect the + behavior of eglGetError; errors are reported through both mechanisms. + + Applications that specify a callback function must be aware of certain + special conditions when executing code inside a callback when it is + called by EGL. The memory for <message> is read-only, owned and managed + by EGL, and should only be considered valid for the duration of the + function call. Likewise the <command> string is read-only EGL managed + memory and should be considered valid only for the duration of the + callback. + + Setting the label for EGL objects is optional and only intended for + applications to correlate application structures with EGL objects. + All object labels are initially NULL. + + The behavior of calling any EGL operation, its client APIs, or window system + functions from within the callback function is undefined and may lead + to program termination. It should not be considered reentrant. + + Only one debug callback may be registered at a time; registering a new + callback will replace the previous callback. The callback is used by any + thread that calls EGL, so if the application calls into EGL concurrently + from multiple threads it must ensure the callback is thread-safe. + + EGL may employ internal threads to execute EGL commands. These threads can + post debug messages to the callback function. The labels for these + internal threads will be NULL. + + 3.13.2 Debug Labels: + + Debug labels provide a method for annotating any object (context, surface, + sync, etc.) with an application provided label. These labels may then be + used by the debug output or an external tool such as a debugger or profiler + to describe labeled objects. + + The command + + EGLint eglLabelObjectKHR( + EGLDisplay display, + EGLenum objectType, + EGLObjectKHR object, + EGLLabelKHR label); + + enables the application to attach a label to a specified object. + The <display>, <objectType>, and <object> identify the object to be + labeled. + + The <label> contains a pointer sized variable to attach to the + object. This label can be a integer identifier, string or pointer to a + application defined structure. EGL will not interpret this value; + it will merely provide it when the object is involved in a callback + message. The label for any object will initially be NULL until set by + the application. + + An EGL_BAD_PARAMETER error is returned by eglLabelObjectKHR if <objectType> + doesn't match one of the object type enums. An EGL_BAD_PARAMETER is also + returned if the <objectType> is not a supported type; such as no support + for streams. + + An EGL_BAD_PARAMETER error is returned by eglLabelObjectKHR if <object> is + invalid, unknown, NULL, or is not an object created with + EGLDisplay <display>. + + When the <objectType> is EGL_OBJECT_THREAD_KHR, the <object> parameter + will be ignored by EGL. The thread is implicitly the active thread. It is + recommended that the application pass a NULL for the <object> parameter in + this case. + + When the <objectType> is EGL_OBJECT_DISPLAY_KHR, the <object> parameter + must be the same as the <display> parameter - the Display to label. If + these do not match, in this case, a EGL_BAD_PARAMETER is generated. + + The <display> does not need to be initialized for <objectType> + EGL_OBJECT_THREAD_KHR, or EGL_OBJECT_DISPLAY_KHR; However for all other + types it must be initialized in order to validate the <object> for + attaching a label. + + If there is no error, then the function will set the label and return + EGL_SUCCESS. + + 3.13.3 Debug Queries: + + The command + + EGLBoolean eglQueryDebugKHR( + EGLint attribute, + EGLAttrib* value); + + enables the application to query the current value for the debug + attributes. On success the function returns EGL_TRUE. + + If <attribute> is a message type enum, the value returned will + be either EGL_TRUE or EGL_FALSE to indicate whether the specified types of + messages are enabled or disabled respectively. + + Querying for attribute EGL_DEBUG_CALLBACK_KHR will return the current + callback pointer. This feature is intended to enable layering of the + callback with helper libraries. + + Querying for an unknown attribute will result in an EGL_BAD_ATTRIBUTE error + and a return of EGL_FALSE. + +Usage Examples + + This example shows starting debug messaging and attaching string labels to + newly created objects. + + void MyCallBack(EGLenum error, + const char *command, + EGLint messageType, + EGLLabelKHR threadLabel, + EGLLabelKHR objectLabel, + const char* message) + { + printf("Error: %x, With command %s, Type: %d," + "Thread: %s, Object: %s, Message: %s.", + error, command, messageType, threadLabel, objectLabel, message); + } + + EGLint result; + + // DEBUG_MSG_ERROR and CRITICAL are enabled by default + EGLAttrib debugAttribs = {EGL_DEBUG_MSG_WARN_KHR, EGL_TRUE, EGL_NONE}; + // Start up debug messaging: + result = eglDebugMessageControl(MyCallBack, debugAttribs); + + // Label for the rendering thread. + EGLLabelKHR renderThreadLabel = (EGLLabelKHR)"Render thread"; + result = eglLabelObject(NULL, EGL_OBJECT_THREAD_KHR, NULL, renderThreadLabel); + + EGLDisplay dpy = eglGetDisplay(EGL_DEFAULT_DISPLAY); + EGLLabelKHR myDisplay = (EGLLabelKHR)"Default display"; + result = eglLabelObject(dpy, EGL_OBJECT_DISPLAY_KHR, dpy, myDisplay); + + eglInitialize(dpy); + + EGLLabelKHR renderContextLabel = (EGLLabelKHR)"Render context"; + EGLContext ctx = eglCreateContext(dpy, config, NULL, contextAttribs); + result = eglLabelObject(dpy, EGL_OBJECT_CONTEXT_KHR, ctx, renderContextLabel); + + +Issues + + 1. Why not use GL_KHR_debug? + + RESOLVED: Most EGL use and object creation happens before creating a + GL context. And since EGL operations are thread related - the debug + messages should be too. + + 2. Is the callback expected only to be called from the thread which it's + registered? + + RESOLVED: In most cases when an application thread calls an EGL function, + it is expected that EGL upon detecting an error will callback using that + application thread. However, EGL may have internal helper threads that + execute operations. These threads can callback but will have no + threadLabel. It is the responsibility of EGL to ensure that if these + threads are blocked in the application's callback by a breakpoint; that + EGL does not fail. Internal threads are an implementation detail and + are not required. + + +Revision History + + Revision 18, 2016-07-28 (Jeff Vigil) + - Clarify return values/error codes. + + Revision 17, 2015-09-23 (Jeff Vigil) + - Correct type name to "EGLDEBUGPROCKHR". Updated example code. + + Revision 16, 2015-04-15 (Jeff Vigil) + - Clarified that <objectLabel> maybe NULL in the callback, if an error + is raised before the primary object handle is validated. + + Revision 15, 2015-03-30 (Jeff Vigil) + - Further details to labeling of EGL_OBJECT_DISPLAY_KHR. + + Revision 14, 2015-03-27 (Jeff Vigil) + - Further clarification of returns and errors. Add further details to + labeling of EGL_OBJECT_THREAD_KHR and EGL_OBJECT_DISPLAY_KHR. + + Revision 13, 2015-03-26 (Jeff Vigil) + - Clarified returns and errors. + + Revision 12, 2015-03-24 (Jeff Vigil) + - Improve readability. Add assigned enum values. + + Revision 11, 2015-03-02 (Jeff Vigil) + - Clarify text regarding parameter attribute_list and its persistence. + + Revision 10, 2015-02-25 (Jeff Vigil) + - Clarify text regarding callback blocking. + - The implementation must provide errors and success in callbacks so + that the callback replaces the use of eglGetError. + - <command> strings are read-only EGL memory. + - Specify default values for attributes. + - Fix typos. + + Revision 9, 2015-02-03 (Jeff Vigil) + - Updated contributors. + - Add extension type. + - Add "KHR" to token and function names. + - Fix typos. + - Add query to get current callback pointer. + + Revision 8, 2014-12-03 (Jeff Vigil) + - Add table containing recommendation for primary object in the callback. + + Revision 7, 2014-10-21 (Jeff Vigil) + - Remove configs as a label-able object. + - Remove redundant text. + - Simplify to one callback per process, not per thread. + + Revision 6, 2014-10-17 (Jeff Vigil) + - Add issues. + - Address internal EGL threads posting messages. + + Revision 5, 2014-05-27 (Jeff Vigil) + - Add missing text for eglQueryDebug. + - Clarify threading model. + + Revision 4, 2014-04-14 (Jeff Vigil) + - Fix due to feedback from EGL WG face-to-face conference. + + Revision 3, 2014-04-10 (Jeff Vigil) + - Refinements. + + Revision 2, 2014-02-21 (Jeff Vigil) + - Simplify API. + + Revision 1, 2013-09-08 (Jeff Vigil) + - Work in progress for F2F, Based on GL_KHR_debug, replace GL with EGL + and remove GL spec specific text. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_display_reference.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_display_reference.txt new file mode 100644 index 0000000..e432ed9 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_display_reference.txt @@ -0,0 +1,242 @@ +Name + + KHR_display_reference + +Name Strings + + EGL_KHR_display_reference + +Contributors + + James Jones + Daniel Kartch + +Contacts + + James Jones, NVIDIA (jajones 'at' nvidia.com) + +Status + + Complete + Ratified by the Khronos Board of Promoters on March 31, 2017. + +Version + + Version 4 - March 15, 2018 + +Number + + EGL Extension #126 + +Extension Type + + EGL client extension + +Dependencies + + Written based on the wording of the EGL 1.5 specification. + + Requires EGL_EXT_platform_base or EGL 1.5 + + Interacts with EGL platform extensions. + + Interacts with the EGL_EXT_device_query extension. + +Overview + + The existing semantics of EGLDisplay object lifetimes work well for + applications in which one module manages all EGL usage, and in which + EGL displays are expected to remain available until application + termination once they are instantiated. However, EGL does not + provide reasonable semantics in the case where applications rely on + toolkit libraries which use EGL independently from the application + itself. + + This issue can be solved by adding a per-EGLDisplay reference + counter which is incremented by eglInitialize calls. Resource + destruction can then be deferred until a corresponding number of + eglTerminate calls is made. However, switching to this behavior + universally could cause backwards incompatibility problems with + existing applications that assume a single eglTerminate will + immediately free resources regardless of how many times the display + has been initialized. + + We therefore must support both behaviors. A new attribute specified + when the EGLDisplay is obtained will indicate whether or not + reference counting is enabled. If an application requests the + EGLDisplay multiple times with different values for this attribute, + two separate displays will be returned. The one potential drawaback + is that these displays will have independent resource spaces, so + objects allocated from one cannot be used by the other. However, the + goal here is to support modules that access EGL independently. In + such a use case, they are not likely to need to share resources with + another module, particularly one that uses a different method for + accessing the display. + +New Types + + None + +New Functions + + EGLBoolean eglQueryDisplayAttribKHR(EGLDisplay dpy, + EGLint name, + EGLAttrib *value); + +New Tokens + + Accepted as an attribute in the <attrib_list> parameter of + eglGetPlatformDisplay and the <name> parameter of + eglQueryDisplayAttribKHR: + + EGL_TRACK_REFERENCES_KHR 0x3352 + +In section "3.2 Initialization": + +Remove the sentence in the description of eglGetPlatformDisplay +indicating no valid attribute names are defined, and add the following: + + The EGL_TRACK_REFERENCES_KHR attribute may be set to EGL_TRUE or + EGL_FALSE to indicate whether or not an EGLDisplay that tracks + reference counts for eglInitialize and eglTerminate calls (as + described below) is desired. If not specified, the default is + platform dependent. Implementations are not required to support both + EGL_TRUE and EGL_FALSE for this attribute. If separate successful + calls are made to eglGetPlatformDisplay requesting default and non- + default behavior for reference counting, two independent EGLDisplays + will be returned. + +Also add to the Errors section: + + An EGL_BAD_ATTRIBUTE error is generated if the requested value for + EGL_TRACK_REFERENCES_KHR is not supported. + +Replace the first sentence of the second paragraph of the description of +eglInitialize with: + + When a previously uninitialized display is initialized, its + reference count will be set to one. Initializing an already- + initialized display is allowed, and will return EGL_TRUE and update + the EGL version numbers, but has no other effect except to increment + the display's reference count if its EGL_TRACK_REFERENCES_KHR + attribute is EGL_TRUE. + +Insert after the declaration of eglTerminate: + + If the specified display's EGL_TRACK_REFERENCES_KHR attribute is + EGL_FALSE, eglTerminate will immediately set its reference count + to zero. Otherwise, its reference count will be decremented if it + is above zero. When an initialized display's reference count reaches + zero, termination will occur. + +Replace the second sentence of the last paragraph with: + + All displays start out uninitialized with a reference count of zero. + +Add to the end of section "3.3 EGL Queries". + + To query non-string attributes of an initialized display, use: + + EGLBoolean eglQueryDisplayAttribKHR(EGLDisplay dpy, + EGLint name, + EGLAttrib *value); + + On success, EGL_TRUE is returned, and the value of the attribute + specified by <name> is returned in the space pointed to by <value>. + + 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. Currently, the only valid attribute name is + EGL_TRACK_REFERENCES_KHR. + +Interactions with EGL_KHR_platform_android: + + If eglGetPlatformDisplay() is called with <platform> set to + EGL_PLATFORM_ANDROID_KHR, the default value of + EGL_TRACK_REFERENCES_KHR is EGL_TRUE. + +Interactions with EGL_EXT_platform_device, EGL_KHR_platform_gbm, +EGL_KHR_platform_x11, and EGL_KHR_platform_wayland: + + If eglGetPlatformDisplay() is called with <platform> set to + EGL_PLATFORM_DEVICE_EXT, EGL_PLATFORM_GBM_KHR, EGL_PLATFORM_X11_KHR, + or EGL_PLATFORM_WAYLAND_KHR, the default value of + EGL_TRACK_REFERENCES_KHR is EGL_FALSE. + +Interactions with EGL_EXT_device_query: + + The eglQueryDisplayAttribKHR function defined here is equivalent to + eglQueryDisplayAttribEXT defined by EGL_EXT_device_query, and the + attribute names supported are a superset of those provided by both + extensions and any others which rely on them. + +Issues + + 1. What is the default value for EGL_TRACK_REFERENCES_KHR? + + RESOLUTION: For backwards compatibility reasons, the default + value is platform-specific. The Android platform has + historically implemented the behavior of + EGL_TRACK_REFERENCES_KHR = EGL_TRUE, while other platforms + defaulted to the opposite behavior. Application components + capable of supporting either behavior will be able to query + the value to determine how to proceed. + + 2. Should the value of EGL_TRACK_REFERENCES_KHR affect whether + eglGetPlatformDisplay returns a new display handle or an + existing one given otherwise identical parameters? + + RESOLUTION: Yes. For any given combination of platform display + handle and other attributes, calling eglGetPlatformDisplay + with different values for EGL_TRACK_REFERENCES_KHR will result + in two different EGLDisplay handles being returned. + + Resources created with respect to one of these EGLDisplays will + not be accessible to the other. This restriction is unlikely to + cause issues, because the reference counting is added primarily + to support independent toolkits. Application components which + independently initialize and terminate the display are not + likely to share resources, particularly if they use different + methods for that initialization. + + 3. Should the new display attribute be queryable? + + RESOLUTION: Yes. Not all implemenations will support both TRUE + and FALSE for this attribute. Application components capable of + supporting either value will allow the default to be chosen, and + then query the value to determine how to handle termination. + + 4. Should implementations which support this extension be required + to support both TRUE and FALSE for the attribute? + + RESOLUTION: No. Lack of refcounting in the core specification is + considered by many to be a flaw, and some implementations/platforms + will choose to always provide refcounting behavior. This technically + makes them non-compliant. The addition of this extension should allow + that deviation. + +Revision History + + #4 (March 15, 2018) Jon Leech + + - Change extension number from 118 to 126 to avoid an accidental + collision. + + #3 (January 12, 2017) Daniel Kartch + + - Change to KHR. + - Allocate enum value. + + #2 (November 15, 2016) Daniel Kartch + + - Full termination portion split off into separate extension + EGL_XXX_full_termination. + - Update reference counting to have separate EGLDisplays for + the same native display, one with reference counting and + one without. + - Add query function to determine attribute value. + + #1 (October 28, 2014) James Jones + + - Initial draft as EGL_XXX_display_reference diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_fence_sync.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_fence_sync.txt new file mode 100644 index 0000000..3cac80b --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_fence_sync.txt @@ -0,0 +1,562 @@ +Name + + KHR_fence_sync + +Name Strings + + EGL_KHR_fence_sync + GL_OES_EGL_sync + VG_KHR_EGL_sync + +Contributors + + Acorn Pooley + Gary King + Gregory Prisament + Jon Leech + +Contacts + + Acorn Pooley, NVIDIA Corporation (apooley 'at' nvidia.com) + Gary King, NVIDIA Corporation (gking 'at' nvidia.com) + Gregory Prisament, NVIDIA Corporation (gprisament 'at' nvidia.com) + Jon Leech (jon 'at' alumni.caltech.edu) + +Notice + + Copyright (c) 2006-2013 The Khronos Group Inc. Copyright terms at + http://www.khronos.org/registry/speccopyright.html + +Status + + Complete. Approved by the EGL Working Group on March 3, 2010. + Approved by the Khronos Board of Promoters on April 30, 2010. + +Version + + Version 24, January 31, 2014 + +Number + + EGL Extension #20 + OpenGL ES Extension #75 + OpenVG Extension #7 + +Dependencies + + Requires EGL 1.1 + + This extension is written against the wording of the EGL 1.2 + Specification. + +Overview + + This extension introduces the concept of "sync objects" into EGL. + Sync objects are a synchronization primitive, representing events + whose completion can be tested or waited upon. This extension + borrows heavily from the GL_ARB_sync extension and introduces a type + of sync object known as a "fence sync object" comparable to the + OpenGL fence sync object. The specification is designed to allow + additional types of sync objects to be easily introduced in later + extensions. + + Fence sync objects have corresponding fence commands, which are + inserted into a client API command stream at the time the fence sync + is created. A fence sync object is used to wait for completion of + the corresponding fence command. This allows applications to request + a partial Finish of an API command stream, wherein all commands + issued in a particular client API context will be forced to complete + before control is returned to the calling thread. + + This document describes three different extension strings + collectively. The "EGL_KHR_fence_sync" string indicates that fence + syncs and the corresponding interfaces (to create and place a fence, + destroy, query, and wait on) are supported. + + The remaining extensions list valid client APIs for fence syncs. The + "GL_OES_EGL_sync" string indicates that a fence sync object can be + created in association with a fence command placed in the command + stream of a bound OpenGL ES context. The "VG_KHR_EGL_sync" string + indicates the same thing for a bound OpenVG context. + +New Types + + /* + * EGLSyncKHR is an opaque handle to an EGL sync object + */ + typedef void* EGLSyncKHR; + + /* + * EGLTimeKHR is a 64-bit unsigned integer representing intervals + * in nanoseconds. + */ + #include <khrplatform.h> + typedef khronos_utime_nanoseconds_t EGLTimeKHR; + + +New Procedures and Functions + + EGLSyncKHR eglCreateSyncKHR( + EGLDisplay dpy, + EGLenum type, + const EGLint *attrib_list); + + EGLBoolean eglDestroySyncKHR( + EGLDisplay dpy, + EGLSyncKHR sync); + + EGLint eglClientWaitSyncKHR( + EGLDisplay dpy, + EGLSyncKHR sync, + EGLint flags, + EGLTimeKHR timeout); + + EGLBoolean eglGetSyncAttribKHR( + EGLDisplay dpy, + EGLSyncKHR sync, + EGLint attribute, + EGLint *value); + + +New Tokens + + Accepted by the <type> parameter of eglCreateSyncKHR, and returned + in <value> when eglGetSyncAttribKHR is called with <attribute> + EGL_SYNC_TYPE_KHR: + + EGL_SYNC_FENCE_KHR 0x30F9 + + Accepted by the <attribute> parameter of eglGetSyncAttribKHR: + + EGL_SYNC_TYPE_KHR 0x30F7 + EGL_SYNC_STATUS_KHR 0x30F1 + EGL_SYNC_CONDITION_KHR 0x30F8 + + Returned in <value> when eglGetSyncAttribKHR is called with + <attribute> EGL_SYNC_STATUS_KHR: + + EGL_SIGNALED_KHR 0x30F2 + EGL_UNSIGNALED_KHR 0x30F3 + + Returned in <value> when eglGetSyncAttribKHR is called with + <attribute> EGL_SYNC_CONDITION_KHR: + + EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR 0x30F0 + + Accepted in the <flags> parameter of eglClientWaitSyncKHR: + + EGL_SYNC_FLUSH_COMMANDS_BIT_KHR 0x0001 + + Accepted in the <timeout> parameter of eglClientWaitSyncKHR: + + EGL_FOREVER_KHR 0xFFFFFFFFFFFFFFFFull + + Returned by eglClientWaitSyncKHR: + + EGL_TIMEOUT_EXPIRED_KHR 0x30F5 + EGL_CONDITION_SATISFIED_KHR 0x30F6 + + Returned by eglCreateSyncKHR in the event of an error: + + EGL_NO_SYNC_KHR ((EGLSyncKHR)0) + +Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors) + + Add a new subsection at the end of Section 3.8, page 43 + (Synchronization Primitives) + + "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>. Initially, sync objects are unsignaled. EGL may be + asked to wait for a sync object to become signaled, or a sync + object's 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 + unsignaling the sync. + + 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. + + <Fence sync objects> are created in association with a <fence + command> in a client API. 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, and + may only change their status once, from the initial unsignaled + status to 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 / vgFinish. + + The command + + EGLSyncKHR eglCreateSyncKHR( + EGLDisplay dpy, + EGLenum type, + const EGLint *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 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. + + If <type> is EGL_SYNC_FENCE_KHR, a fence sync object is created. In + this case <attrib_list> must be NULL or empty (containing only + EGL_NONE). Attributes of the fence sync object are + set as follows: + + Attribute Name Initial Attribute Value(s) + --------------- -------------------------- + EGL_SYNC_TYPE_KHR EGL_SYNC_FENCE_KHR + EGL_SYNC_STATUS_KHR EGL_UNSIGNALED_KHR + EGL_SYNC_CONDITION_KHR EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR + + When a fence sync object is created, eglCreateSyncKHR also inserts a + fence command into the command stream of the bound client API's + current context (i.e., the context returned by + eglGetCurrentContext), and associates it with the newly created sync + object. + + When the condition of the sync object is satisfied by the fence + command, the sync is signaled by the associated client API context, + causing any eglClientWaitSyncKHR commands (see below) blocking on + <sync> to unblock. The only condition currently supported is + EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR, which is satisfied by + completion of the fence command corresponding to the sync object, + and all preceding commands in the associated client API context's + command stream. The sync object will not be signaled until all + effects from these commands on the client API's internal and + framebuffer state are fully realized. No other state is affected by + execution of the fence command. + + Each client API which supports fence commands indicates this support + in the form of a client API extension. If the GL_OES_EGL_sync + extension is supported by OpenGL ES (either version 1.x or 2.0), a + fence sync object may be created when the currently bound API is + OpenGL ES. If the VG_KHR_EGL_sync extension is supported by OpenVG, + a fence sync object may be created when the currently bound API is + OpenVG. + + Errors + ------ + + * If <dpy> is not the name of a valid, initialized EGLDisplay, + EGL_NO_SYNC_KHR is returned and an EGL_BAD_DISPLAY error is + generated. + * If <attrib_list> is neither NULL nor empty (containing only + EGL_NONE), EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE + error is generated. + * If <type> is not a supported type of sync object, + EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE error is + generated. + * If <type> is EGL_SYNC_FENCE_KHR and no context is current for + the bound API (i.e., eglGetCurrentContext returns + EGL_NO_CONTEXT), EGL_NO_SYNC_KHR is returned and an + EGL_BAD_MATCH error is generated. + * If <type> is EGL_SYNC_FENCE_KHR and <dpy> does not match the + EGLDisplay of the currently bound context for the currently + bound client API (the EGLDisplay returned by + eglGetCurrentDisplay()) then EGL_NO_SYNC_KHR is returned and an + EGL_BAD_MATCH error is generated. + * If <type> is EGL_SYNC_FENCE_KHR and the currently bound client + API does not support the client API extension indicating it can + place fence commands, then EGL_NO_SYNC_KHR is returned and an + EGL_BAD_MATCH error is generated. + + The command + + EGLint eglClientWaitSyncKHR( + EGLDisplay dpy, + EGLSyncKHR sync, + EGLint flags, + EGLTimeKHR timeout); + + blocks the calling thread until the specified sync object <sync> is + signaled, or until <timeout> nanoseconds have passed. + + More than one eglClientWaitSyncKHR may be outstanding on the same + <sync> at any given time. When there are multiple threads blocked on + the same <sync> and the sync object is signaled, all such threads + are released, but the order in which they are released is not + defined. + + If the value of <timeout> is zero, then eglClientWaitSyncKHR simply + tests the current status of <sync>. If the value of <timeout> is the + special value EGL_FOREVER_KHR, then eglClientWaitSyncKHR does not + time out. For all other values, <timeout> is adjusted to the closest + value allowed by the implementation-dependent timeout accuracy, + which may be substantially longer than one nanosecond. + + eglClientWaitSyncKHR returns one of three status values describing + the reason for returning. A return value of EGL_TIMEOUT_EXPIRED_KHR + indicates that the specified timeout period expired before <sync> + was signaled, or if <timeout> is zero, indicates that <sync> is + not signaled. A return value of EGL_CONDITION_SATISFIED_KHR + indicates that <sync> was signaled before the timeout expired, which + includes the case when <sync> was already signaled when + eglClientWaitSyncKHR was called. If an error occurs then an error is + generated and EGL_FALSE is returned. + + If the sync object being blocked upon will not be signaled in finite + time (for example, by an associated fence command issued previously, + but not yet flushed to the graphics pipeline), then + eglClientWaitSyncKHR may wait forever. To help prevent this behavior + (footnote1), if the EGL_SYNC_FLUSH_COMMANDS_BIT_KHR bit is set in + <flags>, and <sync> is unsignaled when eglClientWaitSyncKHR is + called, then the equivalent of Flush() will be performed for the + current API context (i.e., the context returned by + eglGetCurrentContext()) before blocking on <sync>. If no context is + current for the bound API, the EGL_SYNC_FLUSH_COMMANDS_BIT_KHR bit + is ignored. + + [footnote 1: The simple Flush behavior defined by + EGL_SYNC_FLUSH_COMMANDS_BIT_KHR will not help when waiting for a + fence command issued in a different context's command stream. + Applications which block on a fence sync object must take + additional steps to ensure that the context from which the + associated fence command was issued has flushed that command to + the graphics pipeline.] + + Errors + ------ + + * If <sync> is not a valid sync object for <dpy>, EGL_FALSE is + returned and an EGL_BAD_PARAMETER error is generated. + * If <dpy> does not match the EGLDisplay passed to + eglCreateSyncKHR when <sync> was created, the behaviour is + undefined. + + + The command + + EGLBoolean eglGetSyncAttribKHR( + EGLDisplay dpy, + EGLSyncKHR sync, + EGLint attribute, + EGLint *value); + + is used to query attributes of the sync object <sync>. Legal values + for <attribute> depend on the type of sync object, as shown in table + 3.cc. Assuming no errors are generated, EGL_TRUE is returned and the + value of the queried attribute is returned in <value>. + + Attribute Description Supported Sync Objects + ----------------- ----------------------- ---------------------- + EGL_SYNC_TYPE_KHR Type of the sync object All + EGL_SYNC_STATUS_KHR Status of the sync object All + EGL_SYNC_CONDITION_KHR Signaling condition EGL_SYNC_FENCE_KHR only + + Table 3.cc Attributes Accepted by eglGetSyncAttribKHR Command + + Errors + ------ + + * If <sync> is not a valid sync object for <dpy>, EGL_FALSE is + returned and an EGL_BAD_PARAMETER error is generated. + * If <dpy> does not match the display passed to eglCreateSyncKHR + when <sync> was created, the behaviour is undefined. + * If <attribute> is not one of the attributes in table 3.cc, + EGL_FALSE is returned and an EGL_BAD_ATTRIBUTE error is + generated. + * If <attribute> is not supported for the type of sync object + passed in <sync>, EGL_FALSE is returned and an EGL_BAD_MATCH + error is generated. + + If any error occurs, <*value> is not modified. + + The command + + EGLBoolean eglDestroySyncKHR( + EGLDisplay dpy, + EGLSyncKHR sync); + + is used to destroy an existing sync object. + + If any eglClientWaitSyncKHR commands are blocking on <sync> when + eglDestroySyncKHR is called, <sync> is flagged for deletion and will + be deleted when it is no longer associated with any fence command + and is no longer blocking any eglClientWaitSyncKHR command. + + If no errors are generated, EGL_TRUE is returned, and <sync> will no + longer be the handle of a valid sync object. + + Errors + ------ + + * If <sync> is not a valid sync object for <dpy>, EGL_FALSE is + returned and an EGL_BAD_PARAMETER error is generated. + * If <dpy> does not match the display passed to eglCreateSyncKHR + when <sync> was created, the behaviour is undefined. + +Issues + + Note about the Issues + --------------------- + The wording for this extension was originally written as a single + extension defining two types of sync object; a "reusable sync + object" and a "fence sync object". That extension was split to + produce standalone extensions for each type of sync object, and + references to the other type removed from the specification + language. This issues list has been simplied to remove references to + reusable sync objects but is otherwise very similar to the + EGL_KHR_reusable_sync extension issues list. + + 1. [REMOVED - found in the reusable_sync extension.] + + 2. [REMOVED - found in the reusable_sync extension.] + + 3. What does this extension provide that can not be accomplished + with the existing, more efficient eglWaitClient and eglWaitNative + API functions? + + RESPONSE: eglWaitClient and eglWaitNative may be implemented in + extremely lightweight manners, in some cases not blocking the + calling thread at all; however, they can not be used to synchronize + between client API contexts and native APIs executing in separate + threads (or simply between client API contexts executing in separate + threads), such as between a thread with an active OpenGL context and + a second thread performing video decode. + + 4. What does this extension provide that could not be accomplished + with native platform synchronization primitives and the existing + client API Finish commands? + + RESPONSE: This extension provides a lighter-weight mechanism for + synchronizing an application with client API command streams than + the all-or-nothing Finish commands, enabling applications to block + until a subset of issued client API commands have completed. + + 5. [REMOVED - found in the reusable_sync extension.] + + 6. Please provide a more detailed description of how + eglClientWaitSyncKHR behaves. + + RESOLVED: eglClientWaitSyncKHR blocks until the status of the sync + object transitions to the signaled state. Sync object status is + either signaled or unsignaled. More detailed rules describing + signalling follow (these may need to be imbedded into the actual + spec language): + + * A fence sync object has two possible status values: signaled or + unsignaled. + * When created, the status of the sync object is unsignaled. + * A fence command is inserted into a command stream. A fence sync + object is not. + * A fence command, once its condition has been met, will set its + associated sync object to the signaled state. The only condition + currently supported is EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR. + * A wait function, such as ClientWaitSyncKHR, waits on a fence + sync object, not on a fence command. + * A wait function called on a sync object in the unsignaled state + will block. It unblocks (note, not "returns to the application") + when the sync object transitions to the signaled state. + * A wait function called on a sync object in the signaled state + will return immediately. + + 7. [REMOVED - found in the reusable_sync extension.] + + 8. [REMOVED - found in the reusable_sync extension.] + + 9. Should eglDestroySyncKHR release all WaitSyncs placed on a fence + sync object? + + RESOLVED: No. (note that this behavior differs from reusable syncs.) + + Fence sync objects are intended to be signalled by the graphics + driver within a short period of time (typically less than 1 second + after creation) and so should not cause waiting threads to hang + forever. To reduce implementation complexity, fence sync objects are + defined to not release waiting threads; waiting threads are released + normally when their condition is satisfied or their timeout expires. + The handle to a fence sync object immediately becomes invalid + following a call to eglDestroySyncKHR. + +Revision History + +#24 (Jon Leech, January 31, 2014) + - Clarify return value of ClientWaitSyncKHR when called with <timeout> + of zero for an unsignaled <sync> (Bug 11576). +#23 (Jon Leech, April 23, 2013) + - Simplify issues list to remove issues specific to reusable sync + objects and general sync object design issues. +#22 (Jon Leech, June 15, 2010) + - Correct minor typos in GL/VG extension names. +#21 (Jon Leech, May 5, 2010) + - Correct minor typos, assign extension numbers for EGL, OpenGL ES, + and OpenVG, and publish in the registry, +#20 (Robert Palmer, July 14, 2009) + - Branch wording from draft KHR_sync specification. Remove ability + to create "reusable sync objects and all tokens/wording specific + to them. +#19 (Robert Palmer, July 22, 2009) + - Replace specific eglCreateSyncKHR error cases for bad <type> + argument with extensible catch-all case. +#18 (Robert Palmer, July 8, 2009) + - Issues 8 and 9 declared resolved in EGL meeting 2009-07-08 +#17 (Robert Palmer, July 8, 2009) + - Update eglDestroySyncKHR to special-case deletion of fence sync + objects. This is explained in issue 9. + - Corrected EGL_REUSABLE_SYNC_KHR -> EGL_SYNC_REUSABLE_KHR + - Define value for EGL_SYNC_REUSABLE_KHR + - Fix typo and whitespace +#16 (Jon Leech, July 7, 2009) + - Update description of new tokens to match changes to the + eglCreateSyncKHR entry point in revision 15. +#15 (Jon Leech, June 16, 2009) + - Define separate one-time fence sync and reusable sync extensions + and corresponding extension strings. Remove AUTO_RESET and + eglFenceKHR. Rename eglCreateFenceSyncKHR to eglCreateSyncKHR and + change initial status of reusable syncs to unsignaled. Clarify + which functions apply to which types of sync objects. Update + issues list. +#14 (Jon Leech, April 29, 2009) + - Clarify that all waiters are woken up on signalling a sync. + Remove tabs to cleanup some formatting issues. +#13 (Acorn Pooley, April 2, 2009) + - Renamed + GL_OES_egl_sync -> GL_OES_EGL_sync + VG_KHR_egl_sync -> VG_KHR_EGL_sync +#12 (Jon Leech, April 1, 2009) + - Changed sync flags type from EGLuint to EGLint and add issue 7. +#11 (Acorn Pooley, February 4, 2009) + - add error case to eglGetSyncAttribKHR. + - fix year on rev 8-10 (2008->2009) +#10 (Acorn Pooley, February 4, 2009) + - clarify some error message descriptions +#9 (Greg Prisament, January 15, 2009) + - Destroy now wakes up all waits (eglClientWaitSyncKHR) + - Add EGLDisplay <dpy> as first parameter to all commands + - Split into 3 extension strings, EGL_KHR_sync, GL_OES_egl_sync, + VG_KHR_egl_sync, all described in this document. + - Add attribute AUTO_RESET_KHR + - Time type uses the type from khrplatform.h + - Remove EGL_ALREADY_SIGNALLED +#8 (Jon Leech, November 11, 2009) + - Assign enum values +#7 (Acorn Pooley, October 30, 2008) + - Fix typos + - remove obsolete wording about Native sync objects (see issue 5) + - formatting: remove tabs, 80 columns +#6 (Acorn Pooley, October 27, 2008) + - Corrected 'enum' to 'EGLenum' in prototypes. +#5 (Jon Leech, September 9, 2008) + - Removed native sync support (eglCreateNativeSyncKHR and + EGL_SYNC_NATIVE_SYNC_KHR), and re-flowed spec to fit in 80 columns. +#4 (Jon Leech, November 20, 2007) + - Corrected 'enum' to 'EGLenum' in prototypes. +#3 (Jon Leech, April 5, 2007) + - Added draft Status and TBD Number +#2 (November 27, 2006) + - Changed OES token to KHR diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_get_all_proc_addresses.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_get_all_proc_addresses.txt new file mode 100644 index 0000000..f01c160 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_get_all_proc_addresses.txt @@ -0,0 +1,206 @@ +Names + + KHR_get_all_proc_addresses + KHR_client_get_all_proc_addresses + +Name Strings + + EGL_KHR_get_all_proc_addresses + EGL_KHR_client_get_all_proc_addresses + +Contributors + + Jon Leech + Marcus Lorentzon + Robert Palmer + Acorn Pooley + Greg Prisament + Chad Versace + +Contacts + + James Jones, NVIDIA (jajones 'at' nvidia.com) + +Notice + + Copyright (c) 2013 The Khronos Group Inc. Copyright terms at + http://www.khronos.org/registry/speccopyright.html + +Status + + Complete. Approved by the EGL Working Group on April 3, 2013. + Ratified by the Khronos Board of Promoters on July 19, 2013. + +Version + + Version 3 - July 31, 2013 + +Number + + EGL Extension #61 + +Extension Types + + EGL_KHR_get_all_proc_addresses is an EGL display extension + EGL_KHR_client_get_all_proc_addresses is an EGL client extension + +Dependencies + + EGL 1.2 is required. + + This extension is written based on the wording of the EGL 1.4 + specification. + + Interacts with EGL_EXT_client_extensions. + +Overview + + eglGetProcAddress is currently defined to not support the querying + of non-extension EGL or client API functions. Non-extension + functions are expected to be exposed as library symbols that can + be resolved statically at link time, or dynamically at run time + using OS-specific runtime linking mechanisms. + + With the addition of OpenGL and OpenGL ES 3 support to EGL, the + definition of a non-extension function becomes less clear. It is + common for one OpenGL library to implement many versions of + OpenGL. The suggested library name for OpenGL ES 3 is the same as + that of OpenGL ES 2. If OpenGL ES 3 applications linked + statically to OpenGL ES 3 functions are run on a system with only + OpenGL ES 2 support, they may fail to load. Similar problems + would be encountered by an application linking statically to + various OpenGL functions. + + To avoid requiring applications to fall back to OS-specific + dynamic linking mechanisms, this extension drops the requirement + that eglGetProcAddress return only non-extension functions. If + the extension string is present, applications can query all EGL + and client API functions using eglGetProcAddress. + + To allow users to query this extension before initializing a display, and + to also allow vendors to ship this extension without + EGL_EXT_client_extensions, two names are assigned to this extension: one + a display extension and the other a client extension. Identical + functionality is exposed by each name, but users query each name using + different methods. Users query EGL_KHR_get_all_proc_addresses in the + usual way; that is, by calling eglQueryString(dpy, EGL_EXTENSIONS) on an + initialized display. To query EGL_KHR_client_get_all_proc_addresses, + users must use a different method which is described below in the section + concerning EGL_EXT_client_extensions. + +New Types + + None + +New functions + + None + +New Tokens + + None + +Rename section "3.10 Obtaining Extension Function Pointers" to "3.10 +Obtaining Function Pointers", and replace its content with the +following: + + "The client API and EGL extensions and versions which are available to a + client may vary at runtime, depending on factors such as the rendering + path being used (hardware or software), resources available to the + implementation, or updated device drivers. Therefore, the address of + functions may be queried at runtime. The function + + void (*eglGetProcAddress(const char *procname))(void); + + returns the address of the function named by <procName>. <procName> must + be a NULL-terminated string. The pointer returned should be cast to a + function pointer matching the function's definition in the corresponding + API or extension specification. A return value of NULL indicates that + the specified function does not exist for the implementation. + + A non-NULL return value for eglGetProcAddress does not guarantee that a + function is actually supported at runtime. The client must also make a + corresponding query, such as glGetString(GL_EXTENSIONS) for OpenGL and + OpenGL ES extensions; vgGetString(VG_EXTENSIONS) for OpenVG extensions; + eglQueryString(dpy, EGL_EXTENSIONS) for EGL extensions; or query the + corresponding API's version for non-extension functions, to determine if + a function is supported by a particular client API context or display. + + Client API function pointers returned by eglGetProcAddress are + independent of the display and the currently bound client API context, + and may be used by any client API context which supports the function. + + eglGetProcAddress may be queried for all EGL and client API extension + and non-extension functions supported by the implementation (whether + those functions are supported by the current client API context or not). + + For functions that are queryable with eglGetProcAddress, implementations + may also choose to export those functions statically from the object + libraries implementing them. However, portable clients cannot rely on + this behavior." + +Interactions with EGL_EXT_client_extensions + + The EGL specification describes the behavior of eglGetProcAddress as + independent of any display. Therefore, this extension's functionality + falls under the classification 'client extension' rather than 'display + extension'. Accordingly, users may wish to query this extension before + initializing a display. + + If the EGL_EXT_client_extensions is supported, then users can query this + extension by checking for the name EGL_KHR_client_get_all_proc_addresses + in the extension string of EGL_NO_DISPLAY. + + The EGL implementation must expose the name + EGL_KHR_client_get_all_proc_addresses if and only if it exposes + EGL_KHR_get_all_proc_addresses and supports EGL_EXT_client_extensions. + This requirement eliminates the problematic situation where, if an EGL + implementation exposed only one name, then an EGL client would fail to + detect the extension if it queried only the other name. + + Despite having two names assigned to this extension, the restrictions + described in EGL_EXT_client_extensions still apply. As + EGL_KHR_client_get_all_proc_addresses is defined as a client extension, + its name can appear only in the extension string of EGL_NO_DISPLAY and + not in the extension string of any valid display. The converse applies + to EGL_KHR_get_all_proc_addresses, as it is defined as a display + extension. + +Issues + + 1. What should this spec be called? + + PROPOSED: KHR_get_all_proc_addresses + + 2. Should this extension be classified as a client extension, as defined + by EGL_EXT_client_extensions? + + DISCUSSION: Yes and no. + + Yes, because this extension exposes functionality that is solely + a property of the EGL library itself, independent of any display. + Such functionality falls under the classification of 'client + extension'. + + No, because classifying it as a client extension would create + a dependency on EGL_EXT_client_extensions, and there exists no + precedent for a KHR extension that depends on an EXT extension. + + RESOLUTION: Expose this extension under two names, one a client + extension and the other a display extension. + +Revision History + + #3 (July 31, 2013) Chad Versace + - Assign additional name, EGL_KHR_client_get_all_proc_addresses. + - Add section "Extension Types", section "Interactions with + EGL_EXT_client_extensions", and issue #2. + + #2 (March 6, 2013) Jon Leech + - Bring into sync with latest EGL 1.4 spec update and simplify + language describing which functions may be queried. Minor + formatting changes for greater consistency with other KHR + extension specs. + + #1 (February 4, 2013) James Jones + - Initial draft diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_gl_colorspace.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_gl_colorspace.txt new file mode 100644 index 0000000..e3fbc38 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_gl_colorspace.txt @@ -0,0 +1,197 @@ +Name + + KHR_gl_colorspace + +Name Strings + + EGL_KHR_gl_colorspace + +Contact + + Jon Leech (jon 'at' alumni.caltech.edu) + +IP Status + + No known IP claims. + +Status + + Complete. + Version 3 approved by the EGL Working Group on September 13, 2013. + Ratified by the Khronos Board of Promoters on December 13, 2013. + +Version + + Version 5, 2014/07/15 + +Number + + EGL Extension #66 + +Dependencies + + EGL 1.4 is required. + + Some of the capabilities of these extensions are only available via + OpenGL or OpenGL ES contexts supporting sRGB default framebuffers, + as defined below. + +Overview + + Applications may wish to use sRGB format default framebuffers to + more easily achieve sRGB rendering to display devices. This + extension allows creating EGLSurfaces which will be rendered to in + sRGB by OpenGL contexts supporting that capability. + +New Procedures and Functions + + None. + +New Tokens + + Accepted as an attribute name by eglCreateWindowSurface, + eglCreatePbufferSurface and eglCreatePixmapSurface + + EGL_GL_COLORSPACE_KHR 0x309D + + Accepted as attribute values for EGL_GL_COLORSPACE_KHR by + eglCreateWindowSurface, eglCreatePbufferSurface and + eglCreatePixmapSurface + + EGL_GL_COLORSPACE_SRGB_KHR 0x3089 + EGL_GL_COLORSPACE_LINEAR_KHR 0x308A + + (these enums are aliases of the corresponding VG colorspace + attribute values from EGL 1.3) + +Additions to the EGL 1.4 Specification + + Modify the 2nd paragraph on page 29 in section 3.5.1 "Creating + On-Screen Rendering Surfaces: + + "Note that the EGL_GL_COLORSPACE_KHR 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.3 and OpenGL ES 3.0 + specifications for more information." + + + Add preceding the 4th paragraph on this page: + + "EGL_GL_COLORSPACE_KHR specifies the color space used by OpenGL and + OpenGL ES when rendering to the surface[fn1]. If its value is + EGL_GL_COLORSPACE_SRGB_KHR, then a non-linear, perceptually uniform + color space is assumed, with a corresponding + GL_FRAMEBUFFER_ATTACHMENT_COLOR_ENCODING value of GL_SRGB. If its value + is EGL_GL_COLORSPACE_LINEAR_KHR, then a linear color space is assumed, + with a corresponding GL_FRAMEBUFFER_ATTACHMENT_COLOR_ENCODING value of + GL_LINEAR. The default value of EGL_GL_COLORSPACE_KHR is + EGL_GL_COLORSPACE_LINEAR_KHR. + + [fn1] 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) + Older versions not supporting sRGB rendering will ignore this + surface attribute. Applications using OpenGL must additionally + enable GL_FRAMEBUFFER_SRGB to perform sRGB rendering, even when an + sRGB surface is bound; this enable is not required (or supported) + for OpenGL ES." + + + Modify the 4th paragraph on page 30 in section 3.5.2, + "Creating Off-Screen Rendering Surfaces": + + "... Attributes that can be specified in <attrib_list> include ... + EGL_GL_COLORSPACE_KHR, EGL_VG_COLORSPACE, and EGL_VG_ALPHA_FORMAT." + + + Add preceding the second paragraph on page 31 in section 3.5.2: + + "EGL_GL_COLORSPACE_KHR has the same meaning and default values as when + used with eglCreateWindowSurface." + + + Modify the next to last paragraph on page 34 in section 3.5.4, + "Creating Native Pixmap Rendering Surfaces": + + "... Attributes that can be specified in <attrib_list> include + EGL_GL_COLORSPACE_KHR, EGL_VG_COLORSPACE, and EGL_VG_ALPHA_FORMAT." + + + Add preceding the second paragraph on page 35 in section 3.5.4: + + "EGL_GL_COLORSPACE_KHR has the same meaning and default values as when + used with eglCreateWindowSurface." + + + Add to table 3.5 on page 37: + + "Attribute Type Description + -------------------- ---- ----------- + EGL_GL_COLORSPACE_KHR enum Color space for OpenGL and OpenGL ES" + + +Errors + + New EGL errors as described in the body of the specification (to be + enumerated here in a later draft). + +Conformance Tests + + TBD + +Sample Code + + TBD + +Issues + + 1) How about premultiplied alpha? + + DISCUSSION: OpenGL doesn't expose this a property of the API, so there's + no point in exposing it through EGL as a hint to GL. Shaders deal with + premultiplied alpha. + + 2) Do we need to determine EGL_GL_COLORSPACE_KHR from client buffer + attributes in section 3.5.3? + + DISCUSSION: probably. Not done yet. + + 3) How should EGL_GL_COLORSPACE_SRGB_KHR be capitalized? + + DISCUSSION: Daniel prefers SRGB. The VG token uses sRGB which is a + rare case of an enum name containing a lower case letter. Currently + the spec uses SRGB. + + 4) Explain differences in surface creation semantics vs. + EGL_VG_COLORSPACE. + + DISCUSSION: The EGL 1.4 spec allows surface creation to fail with a + BAD_MATCH error when requesting an unsupported VG sRGB format. This + is relatively easy to detect since all OpenVG implementations must + support sRGB rendering to specified formats. It is trickier with + OpenGL and OpenGL ES for two reasons: + + - Some GL/ES contexts may support sRGB rendering while other + contexts in the same runtime may not. + - Some contexts may support a broader range of sRGB formats than + others. + + Possibly we should add EGL_GL_COLORSPACE_SRGB_BIT_KHR to + EGL_SURFACE_TYPE, but we've been deemphasizing EGLConfigs going + forward, and hopefully we can get away without doing this. + +Revision History + + Version 1, 2013/04/26 + - Initial draft based on proposal in bug 9995. + Version 2, 2013/04/26 + - GL ES doesn't require GL_FRAMEBUFFER_SRGB enable. + Version 3, 2013/05/15 + - Capitalize SRGB in token name, change reference from VG to GL/ES + in section 3.5.1, note that ES does not require FRAMEBUFFER_SRGB + enable, add issue 4, and fix typos (bug 9995). + Version 4, 2013/09/16 + - Assign enum values. + Version 5, 2014/07/15 + - Fix New Tokens section to include all relevant commands (Bug 12457). diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_gl_image.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_gl_image.txt new file mode 100644 index 0000000..ab7f253 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_gl_image.txt @@ -0,0 +1,432 @@ +Name + + KHR_gl_texture_2D_image + KHR_gl_texture_cubemap_image + KHR_gl_texture_3D_image + KHR_gl_renderbuffer_image + +Name Strings + + EGL_KHR_gl_texture_2D_image + EGL_KHR_gl_texture_cubemap_image + EGL_KHR_gl_texture_3D_image + EGL_KHR_gl_renderbuffer_image + +Contributors + + Aaftab Munshi + Barthold Lichtenbelt + Gary King + Jeff Juliano + Jon Leech + Jonathan Grant + Acorn Pooley + +Contacts + + Gary King, NVIDIA Corporation (gking 'at' nvidia.com) + +Notice + + Copyright (c) 2006-2013 The Khronos Group Inc. Copyright terms at + http://www.khronos.org/registry/speccopyright.html + +Status + + Complete. + Approved by the Khronos Board of Promoters on February 11, 2008. + +Version + + Version 13, October 9, 2013 + +Number + + EGL Extension #5 + +Dependencies + + All extensions require EGL 1.2 and the EGL_KHR_image extension + + These extensions are written against the wording of the EGL 1.2 + Specification. + + KHR_gl_texture_2D_image requires an OpenGL or OpenGL ES client API (any + version of either API). + + KHR_gl_texture_cubemap_image requires an OpenGL or OpenGL ES client API + supporting texture cube maps, either in the core API or via extensions. + + KHR_gl_texture_3D_image requires KHR_gl_texture_2D_image to be supported + by the EGL implementation. It also requires an OpenGL or OpenGL ES + client API supporting three-dimensional textures, either in the core API + or via extensions. + + KHR_gl_renderbuffer_image requires KHR_gl_texture_2D_image to be + supported by the EGL implementation. It also requires an OpenGL or + OpenGL ES client API supporting renderbuffers, either in the core API or + via extensions. + +Overview + + The extensions specified in this document provide a mechanism for + creating EGLImage objects from OpenGL and OpenGL ES (henceforth referred + to collectively as 'GL') API resources, including two- and three- + dimensional textures, cube maps and render buffers. For an overview of + EGLImage operation, please see the EGL_KHR_image specification. + + Due to the number of available extensions for the OpenGL ES 1.1 and + OpenGL ES 2.0 APIs, this document is organized as 4 separate extensions, + described collectively. These extensions are separated based on the + required underlying GL functionality (described in the dependencies + section). + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted in the <target> parameter of eglCreateImageKHR: + + EGL_GL_TEXTURE_2D_KHR 0x30B1 + + Accepted as an attribute in the <attr_list> parameter of + eglCreateImageKHR: + + EGL_GL_TEXTURE_LEVEL_KHR 0x30BC + + Added by KHR_gl_texture_cubemap_image: + + Accepted in the <target> parameter of eglCreateImageKHR: + + EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_X_KHR 0x30B3 + EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_X_KHR 0x30B4 + EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Y_KHR 0x30B5 + EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Y_KHR 0x30B6 + EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Z_KHR 0x30B7 + EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Z_KHR 0x30B8 + + Added by KHR_gl_texture_3D_image: + + Accepted in the <target> parameter of eglCreateImageKHR: + + EGL_GL_TEXTURE_3D_KHR 0x30B2 + + Accepted as an attribute in the <attr_list> parameter of + eglCreateImageKHR: + + EGL_GL_TEXTURE_ZOFFSET_KHR 0x30BD + + Added by KHR_gl_renderbuffer_image: + + Accepted in the <target> parameter of eglCreateImageKHR: + + EGL_GL_RENDERBUFFER_KHR 0x30B9 + + +Additions to the EGL Image (EGL_KHR_image) Specification: + + Add the following to Table aaa (Legal values for eglCreateImageKHR + <target> parameter), Section 2.5.1 (EGLImage Specification) + + +-------------------------------------+---------------------------------+ + | <target> | Notes | + +-------------------------------------+---------------------------------+ + | EGL_GL_TEXTURE_2D_KHR | Used for GL 2D texture images | + +-------------------------------------+---------------------------------+ + + If KHR_gl_texture_cubemap_image is supported: + + +-----------------------------------------+-----------------------------+ + | <target> | Notes | + +-----------------------------------------+-----------------------------+ + | EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_X_KHR | Used for the +X face of | + | | GL cubemap texture images | + +-----------------------------------------+-----------------------------+ + | EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_X_KHR | Used for the -X face of | + | | GL cubemap texture images | + +-----------------------------------------+-----------------------------+ + | EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Y_KHR | Used for the +Y face of | + | | GL cubemap texture images | + +-----------------------------------------+-----------------------------+ + | EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Y_KHR | Used for the -Y face of | + | | GL cubemap texture images | + +-----------------------------------------+-----------------------------+ + | EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Z_KHR | Used for the +Z face of | + | | GL cubemap texture images | + +-----------------------------------------+-----------------------------+ + | EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Z_KHR | Used for the -Z face of | + | | GL cubemap texture images | + +-----------------------------------------+-----------------------------+ + + If KHR_gl_texture_3D_image is supported: + + +-------------------------------------+---------------------------------+ + | <target> | Notes | + +-------------------------------------+---------------------------------+ + | EGL_GL_TEXTURE_3D_KHR | Used for GL 3D texture images | + +-------------------------------------+---------------------------------+ + + If KHR_gl_renderbuffer_image is supported: + + +-------------------------------------+---------------------------------+ + | <target> | Notes | + +-------------------------------------+---------------------------------+ + | EGL_GL_RENDERBUFFER_KHR | Used for GL renderbuffer images| + +-------------------------------------+---------------------------------+ + + Add the following to Table bbb (Legal attributes for eglCreateImageKHR + <attr_list> parameter), Section 2.5.1 (EGLImage Specification) + + +---------------------------+-------------------------------+----------------------------+---------+ + | | | Valid | Default | + | Attribute | Description | <target>s | Value | + +---------------------------+-------------------------------+----------------------------+---------+ + | EGL_GL_TEXTURE_LEVEL_KHR | Specifies the mipmap level | EGL_GL_TEXTURE_2D_KHR, | 0 | + | | used as the EGLImage source. | EGL_GL_TEXTURE_CUBE_MAP_*, | | + | | Must be part of the complete | EGL_GL_TEXTURE_3D_KHR | | + | | texture object <buffer> | | | + +---------------------------+-------------------------------+----------------------------+---------+ + + If KHR_gl_texture_3D_image is supported: + + +----------------------------+------------------------------+----------------------------+---------+ + | | | Valid | Default | + | Attribute | Description | <target>s | Value | + +----------------------------+------------------------------+----------------------------+---------+ + | EGL_GL_TEXTURE_ZOFFSET_KHR | Specifies the depth offset | EGL_GL_TEXTURE_3D_KHR | 0 | + | | of the image to use as the | | | + | | EGLImage source. Must be | | | + | | part of the complete texture| | | + | | object <buffer> | | | + +----------------------------+------------------------------+----------------------------+---------+ + + + Insert the following text after paragraph 3 ("If <target> is + NATIVE_PIXMAP_KHR...") of Section 2.5.1 (EGLImage Specification) + + "If <target> is EGL_GL_TEXTURE_2D_KHR, EGL_GL_TEXTURE_3D_KHR, + EGL_GL_RENDERBUFFER_KHR, + EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_X_KHR, + EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_X_KHR, + EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Y_KHR, + EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Y_KHR, + EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Z_KHR, or + EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Z_KHR, + <dpy> must be a valid EGLDisplay, + and <ctx> must be a valid GL API context on that display. + + If <target> is EGL_GL_TEXTURE_2D_KHR, <buffer> must be the name of a + nonzero, GL_TEXTURE_2D target texture object, cast into + the type EGLClientBuffer. <attr_list> should specify the mipmap level + which will be used as the EGLImage source (EGL_GL_TEXTURE_LEVEL_KHR); the + specified mipmap level must be part of <buffer>. If not specified, the + default value listed in Table bbb will be used, instead. Additional + values specified in <attr_list> are ignored. The texture must be complete + unless the mipmap level to be used is 0, the texture has mipmap level 0 + specified, and no other mipmap levels are specified. + + If <target> is one of the EGL_GL_TEXTURE_CUBE_MAP_* enumerants, <buffer> + must be the name of a cube-complete, nonzero, GL_TEXTURE_CUBE_MAP (or + equivalent in GL extensions) target texture object, cast into the type + EGLClientBuffer. <attr_list> should specify the mipmap level which will + be used as the EGLImage source (EGL_GL_TEXTURE_LEVEL_KHR); the specified + mipmap level must be part of <buffer>. If not specified, the default + value listed in Table bbb will be used, instead. Additional values + specified in <attr_list> are ignored. The texture must be cube-complete + unless the mipmap level to be used is 0, the texture has mipmap level 0 + specified for all faces, and no other mipmap levels are specified for any + faces. + + If <target> is EGL_GL_TEXTURE_3D_KHR, <buffer> must be the name of a + complete, nonzero, GL_TEXTURE_3D (or equivalent in GL extensions) target + texture object, cast + into the type EGLClientBuffer. <attr_list> should specify the mipmap + level (EGL_GL_TEXTURE_LEVEL_KHR) and z-offset (EGL_GL_TEXTURE_ZOFFSET_KHR) + which will be used as the EGLImage source; the specified mipmap level must + be part of <buffer>, and the specified z-offset must be smaller than the + depth of the specified mipmap level. If a value is not specified, the + default value listed in Table bbb will be used, instead. Additional + values specified in <attr_list> are ignored. The texture must be + complete unless the mipmap level to be used is 0, the texture has mipmap + level 0 specified, and no other mipmap levels are specified. + + If <target> is EGL_GL_RENDERBUFFER_KHR, <buffer> must be the name of a + complete, nonzero, non-multisampled GL_RENDERBUFFER (or equivalent in + extensions) target object, cast into the type EGLClientBuffer. Values + specified in <attr_list> are ignored." + + Add the following errors to the end of the list in Section 2.5.1 (EGLImage + Specification): + + " * If <target> is EGL_GL_TEXTURE_2D_KHR, EGL_GL_TEXTURE_CUBE_MAP_*_KHR, + EGL_GL_RENDERBUFFER_KHR or EGL_GL_TEXTURE_3D_KHR, and <dpy> is not a + valid EGLDisplay, the error EGL_BAD_DISPLAY is generated. + + * If <target> is EGL_GL_TEXTURE_2D_KHR, EGL_GL_TEXTURE_CUBE_MAP_*_KHR, + EGL_GL_RENDERBUFFER_KHR or EGL_GL_TEXTURE_3D_KHR, and <ctx> is not a + valid EGLContext, the error EGL_BAD_CONTEXT is generated. + + * If <target> is EGL_GL_TEXTURE_2D_KHR, EGL_GL_TEXTURE_CUBE_MAP_*_KHR, + EGL_GL_RENDERBUFFER_KHR or EGL_GL_TEXTURE_3D_KHR, and <ctx> is not a + valid GL context, or does not match the <dpy>, the error + EGL_BAD_MATCH is generated. + + * If <target> is EGL_GL_TEXTURE_2D_KHR, EGL_GL_TEXTURE_CUBE_MAP_*_KHR + or EGL_GL_TEXTURE_3D_KHR and <buffer> is not the name of a + texture object of type <target>, the error EGL_BAD_PARAMETER + is generated. + + * If <target> is EGL_GL_RENDERBUFFER_KHR and <buffer> is not the + name of a renderbuffer object, or if <buffer> is the name of a + multisampled renderbuffer object, the error EGL_BAD_PARAMETER is + generated. + + * If EGL_GL_TEXTURE_LEVEL_KHR is nonzero, <target> is + EGL_GL_TEXTURE_2D_KHR, EGL_GL_TEXTURE_CUBE_MAP_*_KHR or + EGL_GL_TEXTURE_3D_KHR, and <buffer> is not the name of a complete + GL texture object, the error EGL_BAD_PARAMETER is generated. + + * If EGL_GL_TEXTURE_LEVEL_KHR is 0, <target> is + EGL_GL_TEXTURE_2D_KHR, EGL_GL_TEXTURE_CUBE_MAP_*_KHR or + EGL_GL_TEXTURE_3D_KHR, <buffer> is the name of an incomplete GL + texture object, and any mipmap levels other than mipmap level 0 + are specified, the error EGL_BAD_PARAMETER is generated. + + * If EGL_GL_TEXTURE_LEVEL_KHR is 0, <target> is + EGL_GL_TEXTURE_2D_KHR or EGL_GL_TEXTURE_3D_KHR, <buffer> is not + the name of a complete GL texture object, and mipmap level 0 is + not specified, the error EGL_BAD_PARAMETER is generated. + + * If EGL_GL_TEXTURE_LEVEL_KHR is 0, <target> is + EGL_GL_TEXTURE_CUBE_MAP_*_KHR, <buffer> is not the name of a + complete GL texture object, and one or more faces do not have + mipmap level 0 specified, the error EGL_BAD_PARAMETER is + generated. + + * If <target> is EGL_GL_TEXTURE_2D_KHR, + EGL_GL_TEXTURE_CUBE_MAP_*_KHR, EGL_GL_RENDERBUFFER_KHR or + EGL_GL_TEXTURE_3D_KHR and <buffer> refers to the default GL + texture object (0) for the corresponding GL target, the error + EGL_BAD_PARAMETER is generated. + + * If <target> is EGL_GL_TEXTURE_2D_KHR, EGL_GL_TEXTURE_CUBE_MAP_*_KHR, + or EGL_GL_TEXTURE_3D_KHR, and the value specified in <attr_list> + for EGL_GL_TEXTURE_LEVEL_KHR is not a valid mipmap level for the + specified GL texture object <buffer>, the error EGL_BAD_MATCH is + generated. + + * If <target> is EGL_GL_TEXTURE_3D_KHR, and the value specified in + <attr_list> for EGL_GL_TEXTURE_ZOFFSET_KHR exceeds the depth + of the specified mipmap level-of-detail in <buffer>, the error + EGL_BAD_PARAMETER is generated." + + +Issues + + 1. What should happen if an application attempts to create an + EGLImage from a default OpenGL object (i.e., objects with + a name of 0)? + + SUGGESTION: Disallow this operation, and generate an error. + + 2. What happens when one of + glTexImage2D + glCopyTexImage2D + glCompressedTexImage2D + glTexImage3D + glCopyTexImage3D + glCompressedTexImage3D + is called on a texture which has a mipmap level which is an EGLImage + sibling? + + RESOLVED: the EGLImage sibling is orphaned. The mipmap level and the + EGLImage no longer have any connection. + + 3. What happens when one of + glTexSubImage2D + glCopyTexSubImage2D + glCompressedTexSubImage2D + glTexSubImage3D + glCopyTexSubImage3D + glCompressedTexSubImage3D + is called on a texture which has a mipmap level which is an EGLImage + sibling? + + RESOLVED: the EGLImage sibling is NOT orphaned. The mipmap level + remains an EGLImage sibling. + + 4. What happens when glGenerateMipmaps is called on a texture which has a + mipmap level which is an EGLImage sibling? + + RESOLVED: If the texture is already complete, then the EGLImage + sibling is not orphaned, and the mipmap level remains an EGLImage + sibling. However, if the texture was not complete then the + EGLImage sibling IS orphaned. This is because the implementation + will implicitly alter the structure of the mipmap levels. + + 5. What happens when the GL_GENERATE_MIPMAP bit causes a texture to be + respecified. + + RESOLVED: If the texture is already complete, then the EGLImage + sibling is not orphaned, and the mipmap level remains an EGLImage + sibling. However, if the texture was not complete then the + EGLImage sibling IS orphaned. This is because the implementation + will implicitly alter the structure of the mipmap levels. + + 6. Can an EGLImage be created from a multisampled GL image? + + RESOLVED: NO. Attempting to create an EGLImage from a multisampled + GL renderbuffer is now an error. Attempting to create from a + multisampled OpenGL texture image is not possible because none of + the multisampled <target>s are supported. + + 7. Are all types of two-dimensional GL images which might + be associated with EGLImages allowed? + + Not yet. We could add new variants of these extensions to support + other image types such as rectangular and 2D array slice textures, + but haven't yet seen a need to do so. + +Revision History + +#13 (Jon Leech, October 9, 2013) - Define interactions with and support for + OpenGL and OpenGL ES 3.0, in addition to OpenGL ES 1/2. Add issue 7 (Bug + 10728). +#12 (Jon Leech, September 16, 2013) - Add error when specifying a + renderbuffer <target> and passing a multisampled renderbuffer object. + Add issue 6 describing lack of support for multisampled EGLImages (Bug + 10728). +#11 (Jon Leech, June 26, 2013) - Add error when specifying a renderbuffer + <target> and not passing a renderbuffer object (Bug 10384). +#10 (Jon Leech, June 13, 2013) - Add a "Valid Targets" column to table bbb + for new attributes, matching proposed changes in EGL_KHR_image_base (Bug + 10151). +#9 (Jon Leech, March 28, 2012) + - Fix spelling of *CUBE_MAP* tokens (from CUBEMAP) to agree with + eglext.h. +#8 (Jon Leech, February 4, 2009) + - Change "non-default ... texture object" to "nonzero". +#7 (Bruce Merry, January 20, 2009) + - Minor wording improvements on issues 4 and 5. +#6 (Acorn Pooley, January 13, 2009) + - Modify completion requirement so textures with only mipmap level 0 can + be EGLImage source siblings. Add issues 2-5. +#5 (Jon Leech, October 8, 2008) + - Updated status (approved as part of OpenKODE 1.0) +#4 (Jon Leech, April 7, 2007) + - Assigned enumerant values + - Added OpenKODE 1.0 Provisional disclaimer +#3 (December 14, 2006) + - Changed requirement to egl 1.2 to include EGLClientBuffer type. + - formatting to keep within 80 columns + - added error condition descriptions for <dpy> and <ctx> + - changed error condition for EGL_GL_TEXTURE_ZOFFSET_KHR too big to + be EGL_BAD_PARAMETER +#2 (November 27, 2006) + - Changed OES token to KHR diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_image.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_image.txt new file mode 100644 index 0000000..430f537 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_image.txt @@ -0,0 +1,140 @@ +Name + + KHR_image + +Name Strings + + EGL_KHR_image + +Contributors + + Jeff Juliano + Gary King + Jon Leech + Jonathan Grant + Barthold Lichtenbelt + Aaftab Munshi + Acorn Pooley + Chris Wynn + +Contacts + + Jon Leech (jon 'at' alumni.caltech.edu) + Gary King, NVIDIA Corporation (gking 'at' nvidia.com) + +Notice + + Copyright (c) 2006-2013 The Khronos Group Inc. Copyright terms at + http://www.khronos.org/registry/speccopyright.html + +Status + + Complete. + Approved by the Khronos Board of Promoters on February 11, 2008. + + Rewritten in terms of split functionality in KHR_image_base and + KHR_image_pixmap, approved by the Khronos Technical Working Group + on November 19, 2008. + +Version + + Version 11, November 12, 2008 + +Number + + EGL Extension #3 + +Dependencies + + EGL 1.2 is required. + + An EGL client API, such as OpenGL ES or OpenVG, is required. + + The specifications of EGL_KHR_image_base and EGL_KHR_image_pixmap are + required to determine the specification of this extension, although + those extentions may not be supported. + + This extension is written against the wording of the EGL 1.2 + Specification. + +Overview + + This extension defines a new EGL resource type that is suitable for + sharing 2D arrays of image data between client APIs, the EGLImage, + and allows creating EGLImages from EGL native pixmaps. + +New Types + + As defined by EGL_KHR_image_base. + +New Procedures and Functions + + As defined by EGL_KHR_image_base. + +New Tokens + + As defined by EGL_KHR_image_base and EGL_KHR_image_pixmap, with the + exception that EGL_IMAGE_PRESERVED_KHR is not defined by this + extension. + +Additions to Chapter 2 of the EGL 1.2 Specification (EGL Operation) + + EGL_KHR_image is equivalent to the combination of the functionality + defined by EGL_KHR_image_base and EGL_KHR_image_pixmap, with the + exception that if EGL_KHR_image is supported and EGL_KHR_image_base + is not, the attribute EGL_IMAGE_PRESERVED_KHR is not accepted in + <attrib_list>, However, the default value of this attribute is still + EGL_FALSE. In this situation, image preservation is always disabled. + +Issues + + None (but see the issues lists for EGL_KHR_image_base and + EGL_KHR_image_pixmap). + +Revision History + +#11 (Jon Leech, November 12, 2008) + - Clarified image preservation behavior when using this extension. +#10 (Jon Leech, October 22, 2008) + - Update description of interactions with EGL_KHR_image_base now + that the default value of EGL_IMAGE_PRESERVED_KHR is always FALSE. +#9 (Jon Leech, October 21, 2008) + - Split functionality into new extensions EGL_KHR_image_base and + EGL_KHR_image_pixmap, and defined legacy non-preserved image behavior + when this extension is supported. +#8 (Jon Leech, October 8, 2008) + - Updated status (approved as part of OpenKODE 1.0) +#7 (Jon Leech, November 20, 2007) + - Corrected 'enum' to 'EGLenum' in prototypes. +#6 (Jon Leech, April 5, 2007) + - Assigned enumerant values + - Added OpenKODE 1.0 Provisional disclaimer +#5 (Jon Leech, February 26, 2007) + - Add eglCreateImageKHR error if native pixmaps are not supported by + EGL. +#4 (December 14, 2006) + - Replaced EGL_OUT_OF_MEMORY error with EGL_BAD_ALLOC + - add "egl" and "EGL" to names to be consistant with spec + - formatting to keep within 80 columns + - Changed requirement to egl 1.2 to include EGLClientBuffer type. + - clarified some unclear error cases + - added some new error cases related to <dpy> and <ctx> + - add <dpy> param to eglCreateImageKHR and eglDestroyImageKHR +#3 (November 27, 2006) + - Converted OES token to KHR token +#2 (October 20, 2006) + - Split out API-specific image source types (VG, GL, etc.) into + individual extensions. + - Merged CreateImage2DOES and CreateImage3DOES functions into + a single CreateImageOES function with an attribute-value list. + - Removed the minimum requirements section (2.5.3), since this + doesn't make sense without the client-API specific extensions. + The minimum requirements should be migrated to the client-API + specific extension specifications. + - Added EGL_NO_IMAGE_OES default object, used as return value for + CreateImage*OES functions in the event of error conditions. + - Reworded issue 5, to clarify that the buffer sub-object (i.e., + the unique resource specified by <ctx>, <target>, <buffer>, + and <attrib_list>) specified in CreateImage may not already be + an EGLImage sibling (either EGLImage source or EGLImage target). +#1 Original release diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_image_base.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_image_base.txt new file mode 100644 index 0000000..e6a7fb6 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_image_base.txt @@ -0,0 +1,755 @@ +Name + + KHR_image_base + +Name Strings + + EGL_KHR_image_base + +Contributors + + Jeff Juliano + Gary King + Jon Leech + Jonathan Grant + Barthold Lichtenbelt + Aaftab Munshi + Acorn Pooley + Chris Wynn + +Contacts + + Jon Leech (jon 'at' alumni.caltech.edu) + Gary King, NVIDIA Corporation (gking 'at' nvidia.com) + +Notice + + Copyright (c) 2008-2013 The Khronos Group Inc. Copyright terms at + http://www.khronos.org/registry/speccopyright.html + +Status + + Complete. Functionality approved (as part of KHR_image) by the + Khronos Board of Promoters on February 11, 2008. + + Split into KHR_image_base and KHR_image_pixmap approved by the + Khronos Technical Working Group on November 19, 2008. Update to + version 5 approved on December 10, 2008. + +Version + + Version 8, August 27, 2014 + +Number + + EGL Extension #8 + +Dependencies + + EGL 1.2 is required. + + An EGL client API, such as OpenGL ES or OpenVG, is required. + + This extension is written against the wording of the EGL 1.2 + Specification. + +Overview + + This extension defines a new EGL resource type that is suitable for + sharing 2D arrays of image data between client APIs, the EGLImage. + Although the intended purpose is sharing 2D image data, the + underlying interface makes no assumptions about the format or + purpose of the resource being shared, leaving those decisions to + the application and associated client APIs. + +Glossary + + EGLImage: An opaque handle to a shared resource created by EGL + client APIs, presumably a 2D array of image data + + EGLImage source: An object or sub-object originally created in + a client API (such as a mipmap level of a texture object + in OpenGL-ES, or a VGImage in OpenVG) which is used as + the <buffer> parameter in a call to eglCreateImageKHR. + + EGLImage target: An object created in a client API (such as a + texture object in OpenGL-ES or a VGImage in OpenVG) + from a previously-created EGLImage + + EGLImage sibling: The set of all EGLImage targets (in all + client API contexts) which are created from the + same EGLImage object, and the EGLImage source resouce + which was used to create that EGLImage. + + Orphaning: The process of respecifying and/or deleting an EGLImage + sibling resource (inside a client API context) which + does not result in deallocation of the memory associated + with the EGLImage or affect rendering results using other + EGLImage siblings. + + Referencing: The process of creating an EGLImage target resource + (inside a client API context) from an EGLImage. + + Respecification: When the size, format, or other attributes of an + EGLImage sibling are changed via client API calls such as + gl*TexImage*. Respecification usually will result in + orphaning the sibling. Note that changing the pixel values of + the sibling (e.g. by rendering to it or by calling + gl*TexSubImage*) does not constitute respecification. + +New Types + + /* + * EGLImageKHR is an object which can be used to create EGLImage + * target resources (inside client APIs). + */ + typedef void* EGLImageKHR; + +New Procedures and Functions + + EGLImageKHR eglCreateImageKHR( + EGLDisplay dpy, + EGLContext ctx, + EGLenum target, + EGLClientBuffer buffer, + const EGLint *attrib_list) + + EGLBoolean eglDestroyImageKHR( + EGLDisplay dpy, + EGLImageKHR image) + +New Tokens + + Returned by eglCreateImageKHR: + + EGL_NO_IMAGE_KHR ((EGLImageKHR)0) + + Accepted as an attribute in the <attrib_list> parameter of + eglCreateImageKHR: + + EGL_IMAGE_PRESERVED_KHR 0x30D2 + +Additions to Chapter 2 of the EGL 1.2 Specification (EGL Operation) + + Add a new section "EGLImages" after section 2.4: + + "2.5 EGLImages + + As described in section 2.4, EGL allows contexts of the same client + API type to share significant amounts of state (such as OpenGL-ES + texture objects and OpenVG paths); however, in some cases it may + be desirable to share state between client APIs - an example would be + using a previously-rendered OpenVG image as an OpenGL-ES texture + object. + + In order to facilitate these more complicated use-cases, EGL is capable + of creating EGL resources that can be shared between contexts of + different client APIs (called "EGLImages") from client API resources + such as texel arrays in OpenGL-ES texture objects or OpenVG VGImages + (collectively, the resources that are used to create EGLImages are + referred to as "EGLImage sources"). + + The EGL client APIs each provide mechanisms for creating appropriate + resource types (such as complete texture arrays or OpenVG VGImages) from + EGLImages through a API-specific mechanisms. Collectively, resources + which are created from EGLImages within client APIs are referred to as + "EGLImage targets." Each EGLImage may have multiple associated EGLImage + targets. Collectively, the EGLImage source and EGLImage targets + associated with an EGLImage object are referred to as "EGLImage + siblings." + + 2.5.1 EGLImage Specification + + The command + + EGLImageKHR eglCreateImageKHR( + EGLDisplay dpy, + EGLContext ctx, + EGLenum target, + EGLClientBuffer buffer, + const EGLint *attrib_list) + + is used to create an EGLImage from an existing image resource <buffer>. + <dpy> specifies the EGL display used for this operation. + <ctx> specifies the EGL client API context + used for this operation, or EGL_NO_CONTEXT if a client API context is not + required. <target> specifies the type of resource being used as the + EGLImage source (examples include two-dimensional textures in OpenGL ES + contexts and VGImage objects in OpenVG contexts). <buffer> is the name + (or handle) of a resource to be used as the EGLImage source, cast into the + type EGLClientBuffer. <attrib_list> is an list of attribute-value pairs + which is used to select sub-sections of <buffer> for use as the EGLImage + source, such as mipmap levels for OpenGL ES texture map resources, as well as + behavioral options, such as whether to preserve pixel data during creation. If + <attrib_list> is non-NULL, the last attribute specified in the list must + be EGL_NONE. + + The resource specified by <dpy>, <ctx>, <target>, <buffer>, and + <attrib_list> must not itself be an EGLImage sibling, or bound to an EGL + PBuffer resource (eglBindTexImage, eglCreatePbufferFromClientBuffer). + + Values accepted for <target> are listed in Table aaa, below(fn1). + (fn1) No values are defined by this extension. All functionality + to create EGLImages from other types of resources, such as + native pixmaps, GL textures, and VGImages, is layered in other + extensions. + + +-------------------------+--------------------------------------------+ + | <target> | Notes | + +-------------------------+--------------------------------------------+ + +-------------------------+--------------------------------------------+ + Table aaa. Legal values for eglCreateImageKHR <target> parameter + + Attribute names accepted in <attrib_list> are shown in Table bbb, + together with the <target> for which each attribute name is valid, and + the default value used for each attribute if it is not included in + <attrib_list>. + + +-------------------------+----------------------+-----------+---------------+ + | Attribute | Description | Valid | Default Value | + | | | <target>s | | + +-------------------------+----------------------+-----------+---------------+ + | EGL_NONE | Marks the end of the | All | N/A | + | | attribute-value list | | | + | EGL_IMAGE_PRESERVED_KHR | Whether to preserve | All | EGL_FALSE | + | | pixel data | | | + +-------------------------+----------------------+-----------+---------------+ + Table bbb. Legal attributes for eglCreateImageKHR <attrib_list> parameter + + This command returns an EGLImageKHR object corresponding to the image + data specified by <dpy>, <ctx>, <target>, <buffer> and <attrib_list> which + may be referenced by client API operations, or EGL_NO_IMAGE_KHR in the + event of an error. + + If the value of attribute EGL_IMAGE_PRESERVED_KHR is EGL_FALSE (the + default), then all pixel data values associated with <buffer> will be + undefined after eglCreateImageKHR returns. + + If the value of attribute EGL_IMAGE_PRESERVED_KHR is EGL_TRUE, then all + pixel data values associated with <buffer> are preserved. + + Errors + + If eglCreateImageKHR fails, EGL_NO_IMAGE_KHR will be returned, the + contents of <buffer> will be unaffected, and one of the following + errors will be generated: + + * If <dpy> is not the handle of a valid EGLDisplay object, the error + EGL_BAD_DISPLAY is generated. + + * If <ctx> is neither the handle of a valid EGLContext object on + <dpy> nor EGL_NO_CONTEXT, the error EGL_BAD_CONTEXT is + generated. + + * If <target> is not one of the values in Table aaa, the error + EGL_BAD_PARAMETER is generated. + + * If an attribute specified in <attrib_list> is not one of the + attributes listed in Table bbb, the error EGL_BAD_PARAMETER is + generated. + + * If an attribute specified in <attrib_list> is not a valid attribute + for <target>, as shown in Table bbb, the error EGL_BAD_MATCH is + generated. + + * If the resource specified by <dpy>, <ctx>, <target>, <buffer> and + <attrib_list> has an off-screen buffer bound to it (e.g., by a + previous call to eglBindTexImage), the error EGL_BAD_ACCESS is + generated. + + * If the resource specified by <dpy>, <ctx>, <target>, <buffer> and + <attrib_list> is bound to an off-screen buffer (e.g., by a previous + call to eglCreatePbufferFromClientBuffer), the error + EGL_BAD_ACCESS is generated. + + * If the resource specified by <dpy>, <ctx>, <target>, <buffer> and + <attrib_list> is itself an EGLImage sibling, the error + EGL_BAD_ACCESS is generated. + + * If insufficient memory is available to complete the specified + operation, the error EGL_BAD_ALLOC is generated. + + * If the call to eglCreateImageKHR fails for multiple reasons, the + generated error must be appropriate for one of the reasons, + although the specific error returned is undefined. + + * If the value specified in <attrib_list> for EGL_IMAGE_PRESERVED_KHR + is EGL_TRUE, and an EGLImageKHR handle cannot be created from the + specified resource such that the pixel data values in <buffer> are + preserved, the error EGL_BAD_ACCESS is generated. + + Note that the success or failure of eglCreateImageKHR should not affect + the ability to use <buffer> in its original API context (or context + share group) (although the pixel data values will be undefined if + EGL_IMAGE_PRESERVED_KHR is not EGL_TRUE). + + 2.5.2 Lifetime and Usage of EGLImages + + Once an EGLImage is created from an EGLImage source, the memory associated + with the EGLImage source will remain allocated (and all EGLImage siblings + in all client API contexts will be useable) as long as either of the + following conditions is true: + A) Any EGLImage siblings exist in any client API context + B) The EGLImage object exists inside EGL + + The semantics for specifying, deleting and using EGLImage siblings are + client API-specific, and are described in the appropriate API + specifications. + + If an application specifies an EGLImage sibling as the destination for + rendering and/or pixel download operations (e.g., as an OpenGL-ES + framebuffer object, glTexSubImage2D, etc.), the modified image results + will be observed by all EGLImage siblings in all client API contexts. + If multiple client API contexts access EGLImage sibling resources + simultaneously, with one or more context modifying the image data, + rendering results in all contexts accessing EGLImage siblings are + undefined. + + Respecification and/or deletion of any EGLImage sibling (i.e., both + EGLImage source and EGLImage target resources) inside a client API + context (e.g., by issuing a subsequent call to + gl{Copy,Compressed}TexImage, glDeleteTextures, with the EGLImage + sibling resource as the target of the operation) affects only that + client API context and other contexts within its share group. The + specific semantics for this behavior are defined by each client API, + and generally results in orphaning of the EGLImage, and may also + include allocation of additional memory for the respecified resource + and/or copying of the EGLImage pixel data. + + Operations inside EGL or any client API context which may affect the + lifetime of an EGLImage (or the memory allocated for the EGLImage), + such as respecifying and/or deleting an EGLImage sibling inside a + client API context, must be atomic. + + Applications may create client API resources from an EGLImageKHR using + client API extensions outside the scope of this document (such as + GL_OES_EGL_image, which creates OpenGL ES texture and renderbuffer + objects). If the EGLImageKHR used to create the client resource was + created with the EGL_IMAGE_PRESERVED_KHR attribute set to EGL_TRUE, then + the pixel data values associated with the image will be preserved after + creating the client resource; otherwise, the pixel data values will be + undefined. If the EGLImageKHR was created with the + EGL_IMAGE_PRESERVED_KHR attribute set to EGL_TRUE, and EGL is unable to + create the client resource without modifying the pixel values, then + creation will fail and the pixel data values will be preserved. + + The command + + EGLBoolean eglDestroyImageKHR( + EGLDisplay dpy, + EGLImageKHR image) + + is used to destroy the specified EGLImageKHR object <image>. Once + destroyed, <image> may not be used to create any additional EGLImage + target resources within any client API contexts, although existing + EGLImage siblings may continue to be used. EGL_TRUE is returned + if DestroyImageKHR succeeds, EGL_FALSE indicates failure. + + * If <dpy> is not the handle of a valid EGLDisplay object, the error + EGL_BAD_DISPLAY is generated. + + * If <image> is not a valid EGLImageKHR object created with respect + to <dpy>, the error EGL_BAD_PARAMETER is generated." + + Add a new error to the list at the bottom of Section 3.5.3 (Binding + Off-Screen Rendering Surfaces to Client Buffers): + + "* If the buffers contained in <buffer> consist of any EGLImage + siblings, an EGL_BAD_ACCESS error is generated." + +Issues + + 1. What resource types should be supported by this extension? + + RESOLVED: This specification is designed to support the + sharing of two-dimensional image resources between client APIs, + as these resources are a fundamental component of all modern + graphics APIs. + + Other resources types (e.g., buffer objects) will not be directly + supported by this specification, due to a variety of reasons: + + a. An absense of use cases for this functionality + b. Handling the semantics for some of these resources + (e.g., glMapBuffer) would significantly complicate + and delay this specification. + c. A desire to address the image-sharing use cases + as quickly as possible. + + Should additional resource-sharing functionality be desired + in the future, the framework provided by this specification + should be extendable to handle more general resource + sharing. + + 2. Should this specification address client API-specific resources + (OpenGL texture maps, OpenVG VGImages), or should that + functionality be provided by layered extensions? + + SUGGESTION: Use layered extensions, even for for sharing image + data with native rendering APIs (the EGL_KHR_image_pixmap + extension). + + There are two major arguments for using layered extensions: + + 1. The two client APIs which are defined at the time of this + specification (OpenVG, OpenGL ES) may not always be + deployed on a device; many devices may choose to implement + just one of these two APIs. However, even single-API + devices may benefit from the ability to share image data + with native rendering APIs (provided in this specification) + or with the OpenMAX API. + + 2. OpenGL ES defines a number of optional resource types + (cubemaps, renderbuffers, volumetric textures) which this + framework should support; however, implementations may not. + By layering each of these resource types in individual + extensions, implementations which are limited to just the + core OpenGL ES 1.1 (or OpenGL ES 2.0) features will not + need to add EGLImage enumerant support for unsupported + resource types. + + The original EGL_KHR_image extension included native pixmap + functionality. We have now split the abstract base functionality + (the egl{Create,Destroy}ImageKHR APIs) from the native pixmap + functionality, and redefined EGL_KHR_image as the combination of + EGL_KHR_image_base and EGL_KHR_image_pixmap. + + 3. Should attributes (width, height, format, etc.) for EGLImages + be queriable? + + SUGGESTION: No. Given the wealth of attributes that we would + need to specify all possible EGLImages (and possible + memory layout optimizations performed by implementations), we + can dramatically simplify the API without loss of key + functionality by making EGLImages opaque and allowing + implementations to make the correct decisions internally. + + 4. Should this specification allow the creation of EGLImages from + client API resources which are themselves EGLImage targets? + + RESOLVED: No. This can make memory garbage collection and + reference counting more difficult, with no practical benefit. + Instead, generate an error if an application attempts to + create an EGLImage from an EGLImage target resource. + + 5. Should this specification allow multiple EGLImages to be created + from the same EGLImage source resource? + + RESOLVED: No. The resource <buffer> specified to + eglCreateImageKHR may include multiple sub-objects; examples are + mipmapped images and cubemaps in the OpenGL-ES API. However, the + EGLImage source is defined as the specific sub-object that is defined + by: <ctx>, <target>, <buffer>, and <attrib_list>. This sub-object must + not be an EGLImage sibling (either EGLImage source or EGLImage target) + when eglCreateImageKHR is called; however, other sub-objects in + <buffer> may be EGLImage siblings. This allows applications to share + individual cubemap faces, or individual mipmap levels of detail across + all of the supported APIs. + + Note that the EGLImage source and any EGLImage target resources + will still be EGLImage siblings, even if the EGLImage object + is destroyed by a call to DestroyImageKHR. + + 6. If an EGLImage sibling is respecified (or deleted), what + should happen to the EGLImage and any other EGLImage + siblings? + + RESOLVED: The principle of least surprise would dictate that + respecification and/or deletion of a resource in one client API + should not adversely affect operation in other client APIs + (such as introducing errors). + + Applying this to EGLImages, respecification and/or deletion + of one EGLImage sibling should not respecify/delete other + EGLImage siblings. Each client API will be responsible for + defining appropriate semantics to meet this restriction; + however, example behaviors may include one or more of: + allocating additional memory for the respecified resource, + deleting the EGLImage sibling resource without deallocating + the associated memory ("orphaning") and/or copying the + existing EGLImage pixel data to an alternate memory location. + + The memory associated with EGLImage objects should remain + allocated as long as any EGLImage sibling resources exist + in any client API context. + + 7. Should this specification address synchronization issues + when multiple client API contexts simultaneously access EGLImage + sibling resources? + + RESOLVED: No. Including error-producing lock and synchronization + semantics would introduce additional (undesirable) validation + overhead in numerous common operations (e.g., glBindTexture, + glDrawArrays, etc.). Rather than burdening implementations (and + applications) with this overhead, a separate synchronization + mechanism should be exposed to applications. + + 8. Should eglCreatePbufferFromClientBuffer accept buffer parameters + which are EGLImage siblings? + + RESOLVED: No. Allowing this behavior creates very complex + circular dependency possibilities (CreateImage / DeriveImage / + CreatePbufferFromClientBuffer / BindTexImage / + CreateImage / ...) with no practical benefit. Therefore, + attempting to create a Pbuffer from a client buffer which + is an EGLImage sibling should generate an error. + + 9. Should CreateImage accept client buffers which are bound to + Pbuffers (through eglBindTexImage)? + + RESOLVED: No, for the same reasons listed in Issue 8. + + 10. Should implementations be allowed to modify the pixel data in the + EGLImage source buffers specified to eglCreateImageKHR? + + SUGGESTION: By allowing previously-existing image data to become + undefined after calls to eglCreateImageKHR, implementations are able + to perform any necessary reallocations required for cross-API + buffer compatibility (and/or performance), without requiring + copy-aside functionality. Because applications are able to + respecify the pixel data through mechanisms such as vgSubImage + and glTexSubImage, no use-cases are restricted by this. + + Therefore, the current suggestion is to allow implementations + to leave pixel data undefined after calls to eglCreateImageKHR + functions. The current spec revision has been written in + this way. + + 11. What is the correct mechanism for specifying the EGLImage source + resources used to create an EGLImage object? + + RESOLVED: Three different mechanisms were discussed while + defining this extension: + + A) Providing resource-specific creation functions, such as + eglCreateImage2DKHR, eglCreateImage3DKHR, etc. + + B) Providing a single creation function which returns a + "NULL" EGLImage object, and requiring client APIs to + define additional functions which would allow client API + resources to be "bound" to the EGLImage object. + + C) Provide a single resource creation function, and use + an attribute-value list with attributes specific to the + "target" image resource. + + Initial specifications were written using Option (A); however, + it was believed that this structure would result in an increase + in the number of entry points over time as additional client APIs + and client API resource targets were added. Furthermore, reuse + of these functions was resulting in cases where parameters were + required to have modal behavior: a 2D image creation function + was required to have a mipmap level of detail parameter for + OpenGL ES texture maps, but this same parameter would need to be + 0 for OpenVG. + + Option (B) provided some nice characteristics: as client APIs + continue to evolve, any extensions needed to allow EGLImage + creation could be isolated in the individual client API, rather + than necessitating an EGL extension. However, the creation of + "NULL" images created additional semantic complexity and error + conditions (e.g., attempting to derive an EGLImage target from a + "NULL" image), and every client API would need to provide a + function for every unique resource type; instead of one common + API function for pixmap, OpenGL 2D textures, and OpenVG VGImages, + three would be required. + + This specification is written using Option (C). There is a + single CreateImage function, with a <target> parameter defining + the EGLImage source type, and an attribute-value list allowing + for additional selection of resource sub-sections. This + maximizes entry-point reuse, and minimizes the number of + redundant parameters an application may be required to send. + This framework allows for layered extensions to be easily + written, so little churn is expected as client APIs evolve. + + 12. Should a context be explicitly provided to eglCreateImageKHR, + or should the context be deduced from the current thread's + bound API? + + SUGGESTION: For clarity (both in usage and spec language), the + context containing the EGLImage source should be provided by the + application, rather than inferring the context from EGL state. + + 13. Why does this extension define a new EGL object type, rather + than using the existing EGLSurface objects? + + RESOLVED: Although controversial, the creation of a new, + opaque image object type removes several fundamental problems + with the EGLSurface (and Pbuffer) API: + + 1) The tight compatibility requirements of EGLSurfaces + and EGLConfigs necessitated applications creating + (and calling MakeCurrent) for every unique pixel + format used during rendering. This has already caused + noticeable performance problems in OpenGL-ES (and + desktop OpenGL), and is the primary reason that + framebuffer objects were created. + + 2) Application use-cases are centered around sharing of + color image data, although unique "sundry" buffers + (such as depth, stencil and alpha mask) may be used + in each client API. + + 3) Extending the CreatePbuffer interface to support fully- + specifying all possible buffer attributes in all client + APIs will become unwieldy, particularly as new EGL + client APIs and pixel formats are introduced. + + The EGLImage proposal addresses all three of these restrictions: + + 1) is addressed by placing the burden of framebuffer management + inside the client API, and allowing EGLImages to be accessed + inside client APIs using an appropriate resource type (such + as OpenGL-ES renderbuffers). This follows the example provided + by the GL_OES_framebuffer_object specification. + + 2) is addressed by defining EGLImages to be "trivial" two- + dimensional arrays of pixel data. Implementations may choose + to support creation of EGLImages from any type of pixel data, + and the association of multiple EGLImages and/or sundry + buffers into a single framebuffer is the responsibility of the + application and client API, using a mechanism such as + GL_OES_framebuffer_object. + + 3) is addressed by defining EGLImages as opaque and + non-queriable. Although this introduces potential portability + problems (addressed separately in issue 15), it avoids the + ever-expanding problem of defining buffer compatibility as the + cartesian product of all possible buffer attributes. + + 14. Since referencing EGLImages is the responsibility of the client + API, and may fail for implementation-dependent reasons, + doesn't this result in a potential portability problem? + + UNRESOLVED: Yes, this portability problem (where referencing + succeeds on one platform but generates errors on a different + one) is very similar to the implementation-dependent + failure introduced in the EXT_framebuffer_object specification, + discussed (at length) in Issues (12), (37), (46), (48) and (61) + of that specification. Similar to that specification, this + specification should include some "minimum requirements" + language for EGLImage creation and referencing. + + Since there are numerous references to an upcoming + "format restriction" API in the EXT_framebuffer_object + specification, it may be valuable to wait until that API is + defined before attempting to define a similar API for + EGLImages. + + 15. Should creation of an EGLImage from an EGLImage source + introduce the possibility for errors in the EGLImage source's + owning context? + + RESOLVED: No; although image data may be undefined (issue 11), + the (successful or unsuccessful) creation of an EGLImage should + not introduce additional error conditions in the EGLImage + source's owning context. Text added to the end of section + 2.5.1 describing this. + + 16. Is it reasonable to require that when a preserved EGLImage is + used by layered extensions to create client API siblings of that + image, pixel data values are preserved? + + UNRESOLVED: There are at least two extensions that reference + EGLImages to create EGLImage targets, VG_KHR_EGL_image and + GL_OES_EGL_image. + + Each of these extensions makes provision for failing the creation of + the EGLImage target due to "an implementation-dependent reason". + This could include that the pixel data has been marked as preserved, + and that the implementation is not able to create the EGLImage + target without causing the pixel data of the original EGLImage + source <buffer> to become undefined. + + Issue 14 of EGL_KHR_image also discusses the consequences of failure + for implementation-dependent reasons. This implies that all + extensions for referencing an EGLImage need to make provision for + implementation-dependent failure. + + PROPOSED: Yes, this is reasonable. We should add "EGL_KHR_image_base + affects the behavior of this extension" sections to the ES and VG + extensions. Implementations can continue to export EGL_KHR_image if + they are unable to support preserved image functionality. + + 17. Do EGLImage Target creation extensions such as VG_KHR_EGL_image and + GL_OES_EGL_image also need to be extended? + + UNRESOLVED: The problem here is that both these extensions + explicitly state that pixel data becomes undefined when they + reference an EGLImage to create an EGLImage target. + + One solution would be to allow this extension to do the defining on + behalf of these extensions. For example, the VG_KHR_EGL_image + extension on its own leaves the status of the pixel data undefined, + but when VG_KHR_EGL_image is combined with this extension, then the + status becomes defined (by this extension). + + When combined with the reasons given in Issue 1, this means it is + possible to leave EGLImage Target creation extensions unchanged. + + PROPOSED: Yes, augment these extensions as described in issue 16. + + 18. Is it reasonable for developers to want to preserve pixel data upon + creation of EGLImage and EGLImage targets? + + RESOLVED: Yes. This is necessary for composition implementations + using EGLImages as an encapsulation mechanism for moving data + between producer application, composition API, and composition + implementation(s). + + 19. Should we really change the default value of EGL_IMAGE_PRESERVED_KHR + when EGL_KHR_image is supported? + + RESOLVED: No. This is a subtle and hard to diagnose source of + errors, and the only way to write a portable app would still be + to explicitly specify the attribute value. By making the default + value FALSE no matter which of the two extension(s) are + supported, compatibility with EGL_KHR_image is preserved, and + apps must explicitly ask for preservation if they need it. + + 20. Why is EGL_NO_DISPLAY not supported as the <dpy> argument for + creating and destroying images, unlike the original version of the + EGL_KHR_image specification? + + RESOLVED: There are no defined use cases for this at present, so + there is no way to legally pass in EGL_NO_DISPLAY. If in the future, + a layered extension allows creation of images not associated with + any display, this behavior can be reintroduced. + + +Revision History + +#8 (Jon Leech, August 27, 2014) + - Remove leftover comment saying that inapplicable attributes are + ignored (Bug 12585). + +#7 (Jon Leech, June 12, 2013) + - Add a column to table bbb specifying which <target>s attributes are + valid for, and a generic error if an attribute doesn't match <target> + (Bug 10151). + +#6 (Jon Leech, December 1, 2010) + - Clarify wording of EGL_BAD_CONTEXT error. + +#5 (Jon Leech, December 10, 2008) + - Change definition of EGL_NO_IMAGE_KHR to 0 (appropriately cast) + instead of a reference to an extern implementation-defined + variable. + +#4 (Jon Leech, November 25, 2008) + - Simplify error conditions for eglDestroyImage. + +#3 (Jon Leech, November 12, 2008) + - Added glossary entry for Respecification, updated description of + behavior with preserved images per suggestions from Acorn, and added + issue 20 regarding removal of EGL_NO_DISPLAY as a valid <dpy>. + +#2 (Jon Leech, October 22, 2008) + - Change default value of EGL_IMAGE_PRESERVED_KHR to EGL_FALSE. + Update issue 19. + +#1 (Jon Leech, October 21, 2008) + - Split abstract functionality from EGL_KHR_image into this extension, + and merged preserved image functionality from + EGL_SYMBIAN_image_preserved. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_image_pixmap.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_image_pixmap.txt new file mode 100644 index 0000000..d7f7920 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_image_pixmap.txt @@ -0,0 +1,158 @@ +Name + + KHR_image_pixmap + +Name Strings + + EGL_KHR_image_pixmap + +Contributors + + Jeff Juliano + Gary King + Jon Leech + Jonathan Grant + Barthold Lichtenbelt + Aaftab Munshi + Acorn Pooley + Chris Wynn + Ray Smith + +Contacts + + Jon Leech (jon 'at' alumni.caltech.edu) + Gary King, NVIDIA Corporation (gking 'at' nvidia.com) + +Notice + + Copyright (c) 2008-2013 The Khronos Group Inc. Copyright terms at + http://www.khronos.org/registry/speccopyright.html + +Status + + Complete. Functionality approved (as part of KHR_image) by the + Khronos Board of Promoters on February 11, 2008. + + Split into KHR_image_base and KHR_image_pixmap approved by the + Khronos Technical Working Group on November 19, 2008. + +Version + + Version 5, November 13, 2013 + +Number + + EGL Extension #9 + +Dependencies + + EGL 1.2 is required. + + EGL_KHR_image_base is required. + + The EGL implementation must define an EGLNativePixmapType (although it + is not required either to export any EGLConfigs supporting rendering to + native pixmaps, or to support eglCreatePixmapSurface). + + This extension is written against the wording of the EGL 1.4 + Specification. + +Overview + + This extension allows creating an EGLImage from a native pixmap + image. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted by the <target> parameter of eglCreateImageKHR: + + EGL_NATIVE_PIXMAP_KHR 0x30B0 + +Additions to Chapter 2 of the EGL 1.4 Specification (EGL Operation) + + Rename section 2.2.2.1 "Native Surface Coordinate Systems" to "Native + Surface and EGLImage Pixmap Coordinate Systems" and add to the end of + the section: + + "EGLImages created with target EGL_NATIVE_PIXMAP_KHR share the same + coordinate system as native pixmap surfaces. When that coordinate system + is inverted, client APIs must invert their <y> coordinate when accessing + such images as described above." + + 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_NATIVE_PIXMAP_KHR | Used for EGLNativePixmapType objects | + +-------------------------+--------------------------------------------+ + Table aaa. Legal values for eglCreateImageKHR <target> parameter + + ... + + If <target> is EGL_NATIVE_PIXMAP_KHR, <dpy> must be a valid display, <ctx> + must be EGL_NO_CONTEXT; <buffer> must be a handle to a valid + NativePixmapType object, cast into the type EGLClientBuffer; and + attributes other than EGL_IMAGE_PRESERVED_KHR are ignored." + + Add to the list of error conditions for eglCreateImageKHR: + + "* If <target> is EGL_NATIVE_PIXMAP_KHR and <buffer> is not a + valid native pixmap handle, or if <buffer> is a native pixmap + whose color buffer format is incompatible with the system's + EGLImage implementation, the error EGL_BAD_PARAMETER is + generated. + + * If <target> is EGL_NATIVE_PIXMAP_KHR, and <dpy> is not a valid + EGLDisplay object the error EGL_BAD_DISPLAY is generated. + + * If <target> is EGL_NATIVE_PIXMAP_KHR, and <ctx> is not EGL_NO_CONTEXT, + the error EGL_BAD_PARAMETER is generated. + + * If <target> is EGL_NATIVE_PIXMAP_KHR, and <buffer> is not a handle + to a valid NativePixmapType object, the error EGL_BAD_PARAMETER + is generated." + +Issues + + 1) Should this specification allow EGLImages to be created from native + pixmaps which already have a pixmap surface associated with them, and + vice versa? + + RESOLVED: Yes. There are practical usecases for this, and it is + already the application's responsibility to handle any format + mismatch or synchronization issues that this may allow. + +Revision History + +#5 (Jon Leech, November 13, 2013) + - Add Issue #1 regarding use cases for multiple EGL consumer/producers + of a native pixmap (Bug 7779). + +#4 (Jon Leech, October 16, 2013) + - Add language allowing native pixmap and client API image y coordinate + convention to differ. Re-base extension against EGL 1.4 (Bug 9701). + +#3 (Jon Leech, November 25, 2008) + - Remove dependency on EGLConfig in error conditions. + +#2 (Jon Leech, November 12, 2008) + - Clarified dependency on EGLNativePixmapType such that pixmap configs + and surfaces are not required. + +#1 (Jon Leech, October 21, 2008) + - Split native pixmap functionality from EGL_KHR_image into a layered + extension on EGL_KHR_image_base, and note interaction with the new + EGL_IMAGE_PRESERVED_KHR attribute. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_lock_surface.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_lock_surface.txt new file mode 100644 index 0000000..2cab89e --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_lock_surface.txt @@ -0,0 +1,727 @@ +Name + + KHR_lock_surface + +Name Strings + + EGL_KHR_lock_surface + +Contributors + + Gary King + Jon Leech + Marko Lukat + Tim Renouf + +Contacts + + Jon Leech (jon 'at' alumni.caltech.edu) + +Notice + + Copyright (c) 2006-2013 The Khronos Group Inc. Copyright terms at + http://www.khronos.org/registry/speccopyright.html + +Status + + This extension, as well as the layered EGL_KHR_lock_surface2, are + obsolete and have been replaced by EGL_KHR_lock_surface3. Khronos + recommends implementers who support this extension and lock_surface2 + also implement lock_surface3, and begin transitioning developers to + using that extension. See issue 17 for the reason. + + Complete. + Version 17 approved by the Khronos Board of Promoters on + February 11, 2008. + +Version + + Version 19, October 15, 2013 + +Number + + EGL Extension #2 + +Dependencies + + Requires EGL 1.0 + + This extension is written against the wording of the EGL 1.3 + Specification. + +Overview + + This extension allows mapping color buffers of EGL surfaces into the + client address space. This is useful primarily for software + rendering on low-end devices which do not support EGL client + rendering APIs, although it may be implemented efficiently on more + capable devices as well. + + There is a newer EGL_KHR_lock_surface2 extension which slightly + modifies and clarifies the semantics of this extension. Vendors + should refer to EGL_KHR_lock_surface2 before deciding to implement + only EGL_KHR_lock_surface. + +New Types + + None + +New Procedures and Functions + + EGLBoolean eglLockSurfaceKHR(EGLDisplay dpy, EGLSurface surface, + const EGLint *attrib_list); + EGLBoolean eglUnlockSurfaceKHR(EGLDisplay dpy, + EGLSurface surface); + +New Tokens + + Returned in the EGL_SURFACE_TYPE bitmask attribute of EGLConfigs: + + EGL_LOCK_SURFACE_BIT_KHR 0x0080 + EGL_OPTIMAL_FORMAT_BIT_KHR 0x0100 + + Accepted as an attribute name in the <attrib_list> argument of + eglChooseConfig, and the <attribute> argument of eglGetConfigAttrib: + + EGL_MATCH_FORMAT_KHR 0x3043 + + Accepted as attribute values for the EGL_MATCH_FORMAT_KHR attribute + of eglChooseConfig: + + EGL_FORMAT_RGB_565_EXACT_KHR 0x30C0 + EGL_FORMAT_RGB_565_KHR 0x30C1 + EGL_FORMAT_RGBA_8888_EXACT_KHR 0x30C2 + EGL_FORMAT_RGBA_8888_KHR 0x30C3 + + Accepted as attribute names in the <attrib_list> argument of + eglLockSurfaceKHR: + + EGL_MAP_PRESERVE_PIXELS_KHR 0x30C4 + EGL_LOCK_USAGE_HINT_KHR 0x30C5 + + Accepted as bit values in the EGL_LOCK_USAGE_HINT_KHR bitmask attribute + of eglLockSurfaceKHR: + + EGL_READ_SURFACE_BIT_KHR 0x0001 + EGL_WRITE_SURFACE_BIT_KHR 0x0002 + + Accepted by the <attribute> parameter of eglQuerySurface: + + EGL_BITMAP_POINTER_KHR 0x30C6 + EGL_BITMAP_PITCH_KHR 0x30C7 + EGL_BITMAP_ORIGIN_KHR 0x30C8 + EGL_BITMAP_PIXEL_RED_OFFSET_KHR 0x30C9 + EGL_BITMAP_PIXEL_GREEN_OFFSET_KHR 0x30CA + EGL_BITMAP_PIXEL_BLUE_OFFSET_KHR 0x30CB + EGL_BITMAP_PIXEL_ALPHA_OFFSET_KHR 0x30CC + EGL_BITMAP_PIXEL_LUMINANCE_OFFSET_KHR 0x30CD + + Returns in the *<value> parameter of eglQuerySurface when + <attribute> is EGL_BITMAP_ORIGIN_KHR: + + EGL_LOWER_LEFT_KHR 0x30CE + EGL_UPPER_LEFT_KHR 0x30CF + +Additions to Chapter 2 of the EGL 1.3 Specification (EGL Operation) + + Add to the end of section 2.2.2: + + Finally, some surfaces may be <locked>, which allows the + implementation to map buffers of that surface into client memory + for use by software renderers(fn). Locked surfaces cannot be + used for any other purpose. When a locked surface is <unlocked>, + any changes to the mapped buffer(s) are reflected in the actual + graphics or system memory containing the surface. + + [fn: on implementations not supporting mapping graphics + memory, or which do not wish to take the stability and + security risks that entail, mapping may be done using + copy-out and copy-in behavior.] + +Additions to Chapter 3 of the EGL 1.3 Specification (EGL Functions and Errors) + + Add to the description of the EGL_BAD_ACCESS error in section 3.1: + + "... or, a surface is locked)." + + Add to table 3.2 ("Types of surfaces supported by an EGLConfig") + + EGL Token Name Description + -------------------- ------------------------------------ + EGL_LOCK_SURFACE_BIT_KHR EGLConfig allows locking surfaces + EGL_OPTIMAL_FORMAT_BIT_KHR This format is considered optimal + (preferred) when locking / mapping / + unlocking is being done. + + Change the first paragraph under "Other EGLConfig Attribute + Descriptions" on p. 16: + + "EGL_SURFACE_TYPE is a mask indicating both the surface types + that can be created by the corresponding EGLConfig (the config + is said to <support> those surface types), and the optional + behaviors such surfaces may allow. The valid bit settings are + shown in Table 3.2." + + Add a new paragraph following the second paragraph of the same + section: + + "If EGL_LOCK_SURFACE_BIT_KHR is set in EGL_SURFACE_TYPE_KHR, then + a surface created from the EGLConfig may be locked, mapped into + client memory, and unlocked. Locking is described in section + 3.5.6. If EGL_OPTIMAL_FORMAT_BIT_KHR is set in + EGL_SURFACE_TYPE_KHR, then the surface is considered optimal (by + the implementation) from a performance standpoint when buffer + mapping is being done. + + Replace the second paragraph of section 3.3 "EGL Versioning": + + "The EGL_CLIENT_APIS string describes which client rendering APIs + are supported. It is zero-terminated and contains a + space-separated list of API names, which may include + ``OpenGL_ES'' if OpenGL ES is supported, and ``OpenVG'' if + OpenVG is supported. If no client APIs are supported, then the + empty string is returned." + + Insert a new paragraph and table in section 3.4.1 "Querying + Configurations", following the description of + EGL_MATCH_NATIVE_PIXMAP on page 21: + + "If EGL_MATCH_FORMAT_KHR is specified in <attrib_list>, it must + be followed by one of the attribute values EGL_DONT_CARE, + EGL_NONE, or one of the format tokens in table + [locksurf.format]. + + When EGL_MATCH_FORMAT_KHR has the value EGL_NONE, only configs + which cannot be locked or mapped will match. Such configs must + not have the EGL_LOCK_SURFACE_BIT_KHR set in EGL_SURFACE_TYPE. + + When EGL_MATCH_FORMAT_KHR has the value EGL_DONT_CARE, it is + ignored. + + When EGL_MATCH_FORMAT_KHR has one of the values in table + [locksurf.format], only EGLConfigs describing surfaces whose + color buffers have the specified format, when mapped with + eglLockSurface, will match this attribute. In this case, the + EGL_<component>_SIZE attributes of resulting configs must agree + with the specific component sizes specified by the format." + + Specific Format Name Description + -------------------- ----------- + EGL_FORMAT_RGB_565_EXACT_KHR RGB565 fields in order from MSB to LSB within a 16-bit integer + EGL_FORMAT_RGB_565_KHR RGB565 fields in implementation-chosen order within a 16-bit integer + EGL_FORMAT_RGBA_8888_EXACT_KHR RGBA8888 fields in B, G, R, A byte order in memory + EGL_FORMAT_RGBA_8888_KHR RGBA8888 fields in implementation-chosen order within a 32-bit integer + ------------------------------------------------------------------------------------------------------ + Table [locksurf.format]: Specific formats for mapped pixels. + + Add to table 3.4 ("Default values and match critera for EGLConfig + attributes") on page 22: + + Attribute Default Selection Sort Sort + Criteria Order Priority + -------------------- ------------- --------- ----- -------- + EGL_MATCH_FORMAT_KHR EGL_DONT_CARE Exact None - + + Add EGL_MATCH_FORMAT_KHR to the last paragraph in section 3.4.1 on + p. 23, describing attributes not used for sorting EGLConfigs. + + + Add a new section following the current section 3.5.5: + + "3.5.6 Locking and Mapping Rendering Surfaces + + A rendering surface may be <locked> by calling + + EGLBoolean eglLockSurfaceKHR(EGLDisplay dpy, + EGLSurface surface, + const EGLint *attrib_list); + + While a surface is locked, only two operations can be performed + on it. First, the color buffer of the surface may be <mapped>, + giving a pointer into client memory corresponding to the memory + of the mapped buffer, and attributes describing mapped buffers + may be queried. Second, the surface may be unlocked. Any + attempts to use a locked surface in other EGL APIs will fail and + generate an EGL_BAD_ACCESS error. + + <attrib_list> specifies additional parameters affecting the locking + operation. The list has the same structure as described for + eglChooseConfig. Attributes that may be defined are shown in table + [locksurf.attr], together with their default values if not specified + in <attrib_list>, and possible values which may be specified for + them in <attrib_list>. + + Attribute Name Type Default Value Possible Values + ----------------------- ------- ------------- ------------------------- + EGL_MAP_PRESERVE_PIXELS_KHR boolean EGL_FALSE EGL_TRUE / EGL_FALSE + EGL_LOCK_USAGE_HINT_KHR bitmask EGL_READ_SURFACE_BIT_KHR | Any combination of + EGL_WRITE_SURFACE_BIT_KHR EGL_READ_SURFACE_BIT_KHR + and EGL_WRITE_SURFACE_BIT_KHR + -------------------------------------------------------------- + Table [locksurf.attr]: eglLockSurfaceKHR attribute names, + default values, and possible values. + + On failure, the surface is unaffected and eglLockSurfaceKHR + returns EGL_FALSE. An EGL_BAD_ACCESS error is generated if any + of these condition, are true: + + * <surface> was created with an EGLConfig whose + EGL_SURFACE_TYPE attribute does not contain + EGL_LOCK_SURFACE_BIT_KHR. + * <surface> is already locked. + * Any client API is current to <surface>. + + An EGL_BAD_ATTRIBUTE error is generated if an attribute or + attribute value not described in table [locksurf.attr] is + specified. + + Mapping Buffers of a Locked Surface + ----------------------------------- + + The color buffer of a locked surface can be <mapped> by calling + eglQuerySurface (see section 3.5.7) with <attribute> + EGL_BITMAP_POINTER_KHR(fn). The query returns a pointer to a + buffer in client memory corresponding to the color buffer of + <surface>. In the case of a back-buffered surface, color buffer + refers to the back buffer + + [fn: "mapped" only means that the pointer returned is + intended to *correspond* to graphics memory. Implementation + are not required to return an actual pointer into graphics + memory, and often will not.] + + The contents of the mapped buffer are initially undefined(fn) + unless the EGL_MAP_PRESERVE_PIXELS_KHR attribute of + eglLockSurfaceKHR is set to EGL_TRUE, in which case the contents + of the buffer are taken from the contents of <surface>'s color + buffer. The default value of EGL_MAP_PRESERVE_PIXELS_KHR is + EGL_FALSE. + + [fn: In order to avoid pipeline stalls and readback delays on + accelerated implementations, we do not mandate that the + current contents of a color buffer appear when it's mapped + to client memory, unless the EGL_MAP_PRESERVE_PIXELS_KHR + flag is set. Applications using mapped buffers which are not + preserved must write to every pixel of the buffer before + unlocking the surface. This constraint is considered + acceptable for the intended usage scenario (full-frame + software renderers).] + + The EGL_LOCK_USAGE_HINT_KHR attribute of eglLockSurfaceKHR is a + bitmask describing the intended use of the mapped buffer. If the + mask contains EGL_READ_SURFACE_BIT_KHR, data will be read from + the mapped buffer. If the mask contains + EGL_WRITE_SURFACE_BIT_KHR, data will be written to the mapped + buffer. Implementations must support both reading and writing to + a mapped buffer regardless of the value of + EGL_LOCK_USAGE_HINT_KHR, but performance may be better if the + hint is consistent with the actual usage of the buffer. The + default value of EGL_LOCK_USAGE_HINT_KHR hints that both reads + and writes to the mapped buffer will be done. + + Other attributes of the mapped buffer describe the format of + pixels it contains, including its pitch (EGL_BITMAP_PITCH_KHR), + origin, pixel size, and the bit width and location of each color + component within a pixel. These attributes may be queried using + eglQuerySurface, and are described in more detail in section + 3.5.7. + + The EGL_BITMAP_POINTER_KHR and EGL_BITMAP_PITCH_KHR attributes + of a locked surface may change following successive calls to + eglLockSurfaceKHR(fn), so they must be queried each time a + buffer is mapped. Other attributes of a mapped buffer are + invariant and need be queried only once following surface + creation. + + [fn: The pointer and pitch of a mapped buffer may change due + to display mode changes, for example.] + + Mapping will not suceed if client memory to map the surface into + cannot be allocated. In this case, querying eglQuerySurface with + <attribute> EGL_BITMAP_POINTER_KHR will fail and generate an EGL + error. + + Unlocking Surfaces + ------------------ + + A rendering surface may be <unlocked> by calling + + EGLBoolean eglUnlockSurfaceKHR(EGLDisplay dpy, + EGLSurface surface); + + Any mapped buffers of <surface> become unmapped following + eglUnlockSurfaceKHR. Any changes made to mapped buffers of + <surface> which it was locked are reflected in the surface after + unlocking(fn). + + [fn: This language enables implementations to either map + video memory, or copy from a separate buffer in client + memory.] + + If <surface> was created with an EGLConfig whose + EGL_SURFACE_TYPE attribute contains EGL_OPTIMAL_FORMAT_BIT_KHR, + then the surface is considered optimal (by the implementation) + from a performance standpoint when buffer mapping is being + done(fn). + + [fn: This often means that the format of all mapped buffers + corresponds directly to the format of those buffers in + <surface>, so no format conversions are required during + unmapping. This results in a high-performance software + rendering path. But "optimal format" is really just a hint + from EGL that this config is preferred, whatever the actual + reason.] + + On failure, eglUnlockSurfaceKHR returns EGL_FALSE. An + EGL_BAD_ACCESS error is generated if any of these conditions are + true: + + * <surface> is already unlocked. + * A display mode change occurred while the surface was locked, + and the implementation was unable to reflect mapped buffer + state(fn). In this case, <surface> will still be unlocked. + However, the contents of the previously mapped buffers of + <surface> become undefined, rather than reflecting changes + made in the mapped buffers in client memory. + + [fn: Usually this may only occur with window surfaces which + have been mapped. EGL does not have an event mechanism to + indicate display mode changes. If such a mechanism exists + (using native platform events or the OpenKODE event system), + applications should respond to mode changes by regenerating + all visible window content, including re-doing any software + rendering overlapping the mode change.]" + + Add to table 3.5 ("Queryable surface attributes and types") + + Attribute Type Description + --------- ---- ----------- + EGL_BITMAP_POINTER_KHR pointer Address of a mapped color buffer (MCB). + EGL_BITMAP_PITCH_KHR integer Number of bytes between the start of + adjacent rows in an MCB. + EGL_BITMAP_ORIGIN_KHR enum Bitmap origin & direction + EGL_BITMAP_PIXEL_x_OFFSET_KHR integer Bit location of each color buffer + component within a pixel in an MCB. + + Add to the description of eglQuerySurface properties in section + 3.5.6 (renumbered to 3.5.7) on page 33: + + "Properties of a bitmap surface which may be queried include: + * EGL_BITMAP_POINTER_KHR, which maps the color buffer of a + locked surface and returns the address in client memory of + the mapped buffer. + * EGL_BITMAP_PITCH_KHR, which returns the number of bytes + between successive rows of a mapped buffer. + * EGL_BITMAP_ORIGIN_KHR, which describes the way in which a + mapped color buffer is displayed on the screen. Possible + values are either EGL_LOWER_LEFT_KHR or EGL_UPPER_LEFT_KHR, + indicating that the first pixel of the mapped buffer + corresponds to the lower left or upper left of a visible + window, respectively. + * EGL_BITMAP_PIXEL_<x>_OFFSET_KHR, which describes the bit + location of the least significant bit of each color + component of a pixel within a mapped buffer. <x> is one of + RED, GREEN, BLUE, ALPHA, or LUMINANCE. + + The offset for a color component should be treated as the + number of bits to left shift the component value to place it + within a 16- (for RGB565 formats) or 32-bit (for RGBA8888 + formats) integer containing the pixel(fn). If a color + component does not exist in the mapped buffer, then the bit + offset of that component is zero. + + In addition to these attributes, the number of bits for each + color component of a pixel within a mapped buffer is obtained by + querying the EGL_<x>_SIZE attribute of the EGLConfig used to + create the surface, where <x> is <x> is one of RED, GREEN, BLUE, + ALPHA, or LUMINANCE. The size of a pixel in the mapped buffer, + in bytes, can be determined by querying the EGL_BUFFER_SIZE + attribute of the EGLConfig, rounding up to the nearest multiple + of 8, and converting from bits to bytes. + + Querying EGL_BITMAP_POINTER_KHR and EGL_BITMAP_PITCH_KHR is only + allowed when <surface> is mapped (see section 3.5.6). Querying + either of these attributes for the first time after calling + eglLockSurfaceKHR causes the color buffer of the locked surface + to be mapped. Querying them again before unlocking the surface + will return the same values as the first time. However, after + calling eglUnlockSurfaceKHR, these properties become undefined. + After a second call to eglLockSurfaceKHR, these properties may + again be queried, but their values may have changed. + + Other properties of the mapped color buffer of a surface are + invariant, and need be queried only once following surface + creation. If <surface> was created with an EGLConfig whose + EGL_SURFACE_TYPE attribute does not contain + EGL_LOCK_SURFACE_BIT_KHR, queries of EGL_BITMAP_ORIGIN_KHR and + EGL_BITMAP_PIXEL_<x>_OFFSET_KHR return undefined values." + + Add to the description of eglQuerySurface errors in the last + paragraph of section 3.5.6 (renumbered to 3.5.7) on page 34: + + "... If <attribute> is either EGL_BITMAP_POINTER_KHR or + EGL_BITMAP_PITCH_KHR, and either <surface> is not locked using + eglLockSurfaceKHR, or <surface> is locked but mapping fails, + then an EGL_BAD_ACCESS error is generated." + +Issues + + 1) What is the rationale for this extension? + + Software renderers on low-end implementations need an efficient way + to draw pixel data to the screen. High-end implementations must + support the same interface for compatibility, while not compromising + the accelerability of OpenGL ES and OpenVG client APIs using + dedicated graphics hardware and memory. + + Using lock/unlock semantics enables low-end implementations to + expose pointers directly into display memory (as extremely dangerous + as that may be), while high-end implementations may choose to create + backing store in client memory when mapping a buffer, and copy it to + graphics memory when the surface is unlocked. Making the initial + contents of a mapped buffer undefined means that no readbacks from + graphics memory are required, avoiding pipeline stalls. + + This extension is not intended to support mixed-mode (client API and + software) rendering. Since mapped buffer contents are undefined, + unless the buffer is explicitly preserved (which may be unacceptably + expensive on many implementations), applications doing software + rendering must touch every pixel of mapped buffers at least once + before unlocking the surface. + + 2) Do we need to know if locked surfaces are "fast" or "native"? + + RESOLVED: Yes. This is indicated with the EGL_OPTIMAL_FORMAT_BIT_KHR + of EGL_SURFACE_TYPE. However, note that there is no way to guarantee + what "fast" or "no format conversions" really means; this is little + more than an implementation hint. + + 3) Should we be able to map buffers other than the color buffer? + + RESOLVED: Not initially. However, the <attrib_list> parameter of + eglLockSurfaceKHR supports this in the future. There is no <buffer> + attribute to eglQuerySurface, so such a layered extension would have + to either create a new naming convention (such as + EGL_BITMAP_{DEPTH,COLOR,STENCIL,ALPHA_MASK}_POINTER), or define an + extended query eglQuerySurfaceBuffer() which takes a <buffer> + parameter. It would also be tricky to support interleaved depth / + stencil formats. But the attribute list offers some future-proofing + at low cost. + + 4) What properties of mapped buffers can be queried? + + RESOLVED: A pointer to the buffer and its pitch, both of which may + change in successive lock/unlock cycles. These may be queried only + while the underlying surface is locked, and are undefined after + unlocking. The first query following locking is the point at which + actual buffer mapping must occur. + + RESOLVED: Additionally, the pixel size, origin, and color component + bitfield size and offset for each component, which are invariant + and may be queried at any time. + + 5) How are mode changes indicated? What happens to the mapped + buffer during a mode change? + + RESOLVED: UnlockSurfaceKHR fails and raises an error if a mode + change occurred while the surface was locked (although the surface + still ends up in the unlocked state - this is necessary since + there's no way to clear the error!). If a mode change occurs while a + buffer is mapped, the implementation must still allow the + application to access mapped buffer memory, even though the contents + of the mapped buffer may not be reflected in the changed window + after unmapping. + + Note: There's no convenient way to indicate mode changes while + a surface is unlocked, despite that being useful to tell apps they + have to redraw. The problem is that we don't have an event system, + and the power management functionality is overkill since the only + resources which are likely to be damaged by a mode change are + visible window contents. Fortunately, this problem is beyond the + scope of this extension. + + 6) Does locking a surface imply mapping its buffers? + + RESOLVED: No. Locking simply places the surface in that state and + prevents it from being made current / swapped / etc. Buffers are + mapped only when their pointers or pitch are queried using + eglQuerySurface. + + An interesting side effect of this resolution is that calling + eglLockSurfaceKHR immediately followed by eglUnlockSurfaceKHR DOES + NOT CHANGE THE CONTENTS OF BUFFERS, since none of them were mapped. + Likewise locking a surface, querying a buffer pointer or pitch, and + then unlocking it without changing the mapped buffer contents causes + the surface contents of the mapper buffer(s) to become undefined. + + At the Atlanta F2F, there was a suggestion that eglLockSurfaceKHR + should immediately map the color buffer and return a pointer to it, + on the basis that this would make it harder for applications to + mistakenly use an old buffer pointer from a previous mapping cycle. + At the same time, people working on more powerful GPUs wanted the + lock operation to be lightweight. These are not consistent goals and + we have thus far chosen to separate the lightweight locking, and + more expensive mapping operations. + + 7) Can buffer contents be preserved in mapping? + + RESOLVED: Yes. The default behavior is to discard / leave undefined + the mapped buffer contents, but the EGL_MAP_PRESERVE_PIXELS_KHR flag + may be specified to eglLockSurfaceKHR. + + 8) Should usage hints be provided during mapping? + + RESOLVED: Yes, they may be provided in the EGL_LOCK_USAGE_HINT_KHR + bitmask attribute to eglLockSurfaceKHR. Implementations are required + to behave correctly no matter the value of the flag vs. the + operations actually performed, so the hint may be ignored. + + 9) Should we be able to lock subrectangles of a surface? + + RESOLVED: No. However, the attribute list parameter of + eglLockSurfaceKHR allows a layered extension to implement this + behavior by specifying an origin and size to map within the buffer. + +10) Should the BITMAP_PIXEL_<component>_OFFSET attributes belong to the + surface, or the config? + + RESOLVED: Part of the surface. Configs supporting a specific format + are matched with config attribute EGL_MATCH_FORMAT_KHR, which + supports specific bit-exact formats such as + EGL_FORMAT_565_EXACT_KHR. + +11) Can the pixel size in a mapped buffer be derived from the + EGL_BUFFER_SIZE attribute of the config used to create it? + + RESOLVED: Yes. In principle, hardware using padding bytes in its + framebuffer storage could be a problem, and a separate + BITMAP_PIXEL_SIZE surface attribute would be needed. However, we + don't think implementations are likely to waste graphics memory and + bandwidth in this fashion. + +12) How are color component locations within a pixel described? + + RESOLVED: Each R, G, B, and A component has a queryable bit offset + within an integer. The size of the integer depends on the total size + of the pixel; for the 565 formats, the pixel is a 16-bit integer. + For the 8888 formats, the pixel is a 32-bit integer. + + We cannot describe component locations with byte locations, since + the 565 formats have components straddling byte boundaries. However, + this means that offsets for the RGBA8888_EXACT format are different + between little- and big-endian CPUs, since the desired format is B, + G, R, A components laid out as bytes in increasing memory order. + +13) Can mapped buffer contents be affected by other EGL operations? + + RESOLVED: No. A locked surface only allows two operations: + unlocking, and mapping. No other EGL operations can take place while + the surface is locked (if this were not the case, then + eglSwapBuffers might destroy the contents of a mapped buffer). + + It is possible that operations outside the scope of EGL could affect + a mapped color buffer. For example, if a surface's color buffer were + made up of an EGLImage, one of the EGL client APIs could draw to + that image while it was mapped. Responsibility for avoiding this + situation is in the hands of the client. + +14) Can EGL_MATCH_FORMAT_KHR be queried for a config? + + RESOLVED: Yes. Unlockable configs return EGL_NONE for this + attribute. + +15) Is a goal of this extension to support "mixed-mode" rendering (both + software and EGL client API rendering to the same surface)? + + RESOLVED: No. An implementation *can* choose to export configs + supporting creation of lockable surfaces which also support + rendering by OpenGL ES, OpenVG, or other client APIs (when the + surface is not locked). But there is nothing in the extension + requiring this, and the motivation for the extension is simply to + support software rendering. + +16) Can mapping a locked surface fail? + + RESOLVED: Yes, if memory can't be allocated in the client. This is + indicated by queries of EGL_BITMAP_POINTER_KHR and + EGL_BITMAP_PITCH_KHR failing and generating an EGL_BAD_ACCESS error. + +17) Why has this extension been obsoleted and replaced by + EGL_KHR_lock_surface3? + + RESOLVED: Starting with the December 4, 2013 release of EGL 1.4, EGLint + is defined to be the same size as the native platform "int" type. Handle + and pointer attribute values *cannot* be represented in attribute lists + on platforms where sizeof(handle/pointer) > sizeof(int). Existing + extensions which assume this functionality are being replaced with new + extensions specifying new entry points to work around this issue. See + the latest EGL 1.4 Specification for more details. + +Revision History + + Version 19, 2013/10/15 - Add issue 17 explaining that the bitmap pointer + cannot be safely queried using this extension on 64-bit platforms, + and suggest EGL_KHR_lock_surface3 instead. Change formal parameter + names from 'display' to 'dpy' to match other EGL APIs. + Version 18, 2010/03/23 - Added introductory remark referring to the + EGL_KHR_lock_surface2 extension. Clarified that it is the back + buffer of a back-buffered surface that is mapped. + Version 17, 2008/10/08 - Updated status (approved as part of + OpenKODE 1.0). + Version 16, 2008/01/24 - Add issue 16 noting that mapping can fail, + and a corresponding new error condition for eglQuerySurface. + Clean up the issues list. + Version 15, 2008/01/09 - Add issue 15 noting that supporting + mixed-mode rendering is not a goal or requirement of the + extension. + Version 14, 2007/11/07 - change ARGB_8888_EXACT back to + RGBA_8888_EXACT, since the offsets are now dependent on the + endianness of the CPU. Add issue 12 describing this, and clarify + that offsets are within a 16- or 32-bit integer depending on the + format. Added issue 13 clarifying that locked buffer contents + are not affected by eglSwapBuffers, because eglSwapBuffers + cannot be issued on a mapped surface. Allow querying + EGL_MATCH_FORMAT_KHR for a config, and added related issue 14. + Version 13, 2007/05/10 - change RGBA_8888_EXACT to ARGB_8888_EXACT + to match hardware layout. + Version 12, 2007/04/06 - clarify that when EGL_MATCH_FORMAT_KHR is + EGL_DONT_CARE, it does not affect component size of selected + configs. + Version 11, 2007/04/05 - add missing KHR suffix to some tokens. + Version 10, 2007/04/05 - assign enumerant values. Add OpenKODE 1.0 + Provisional disclaimer. + Version 9, 2007/03/26 - add format tokens to "New Tokens" + section. Correct description of RGBA format tokens. + Version 8, 2007/03/26 - add issue 11 noting theoretical possibility + of EGL_BUFFER_SIZE not directly corresponding to the mapped + pixel size. Add EGL_MATCH_FORMAT_KHR attribute to + eglChooseConfig, and 565 / 8888 formats for it. + Version 7, 2007/03/25 - note in issue 5 that access to a mapped + buffer must continue to work even after a mode change. Add KHR + suffix to new functions and tokens. Remove BITMAP_PIXEL_<x>_BITS + and BITMAP_PIXEL_SIZE tokens, which duplicate information in the + EGLConfig. Add issue 10 asking whether bitmap pixel offset + attributes belong to the config, or to the surface. + Version 6, 2007/02/26 - allow EGL_CLIENT_APIS string to be empty in + implementations supporting only this extension. + Version 5, 2007/02/05 - update contributor list. Changed bit offset + queries to return LSB offset, rather than MSB offset. + Version 4, 2007/02/02 - correct extension name. Change + name of FAST_UNLOCK_BIT_KHR to OPTIMAL_FORMAT_BIT_KHR. + Replace buffer_mask parameter of eglLockSurfaceKHR with an + attribute list. Add the EGL_MAP_PRESERVE_PIXELS_KHR and + EGL_LOCK_USAGE_HINT_KHR attributes per request from Gary. Add issues + 7, 8, and 9 describing these attributes and how to support + locking subrects in a layered extension, by extending the + attribute list. + Version 3, 2007/02/01 - the implementation once again controls the + mapped buffer memory. There is no longer a separate bitmap + surface type; any type surface may potentially be mapped, using + lock/unlock semantics. + Version 2, 2006/12/22 - simplify by only supporting drawing from + client memory to EGL surface color buffers. Specify use of + OpenGL DrawPixels terminology. Change name of the extension to + EGL_KHR_draw_pixels, since there is no longer any "bitmap + surface" involved. + Version 1, 2006/12/14 - write up as formal spec language for + external review. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_lock_surface2.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_lock_surface2.txt new file mode 100644 index 0000000..f7bae4d --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_lock_surface2.txt @@ -0,0 +1,1077 @@ +Name + + KHR_lock_surface2 + +Name Strings + + EGL_KHR_lock_surface2 + +Contributors + + Mark Callow + Gary King + Jon Leech + Marko Lukat + Alon Or-bach + Tim Renouf + +Contacts + + Jon Leech (jon 'at' alumni.caltech.edu) + +Notice + + Copyright (c) 2006-2013 The Khronos Group Inc. Copyright terms at + http://www.khronos.org/registry/speccopyright.html + +Status + + This extension is obsolete and has been replaced by + EGL_KHR_lock_surface3. Khronos recommends implementers who support this + extension also implement lock_surface3, and begin transitioning + developers to using that extension. See issue 21 for the reason. + + Complete. Version 2 approved by the Khronos Board of Promoters on + May 28, 2010. + Implemented by Antix Labs. + +Version + + Version 3, December 4, 2013 + +Number + + EGL Extension #16 + +Dependencies + + Requires EGL 1.0 and EGL_KHR_lock_surface version 18. + + This extension is written against the wording of the EGL 1.3 + and EGL 1.4 Specifications. Unless otherwise specified, each change + applies to both specifications. Unless otherwise specified, a page + number refers to the EGL 1.3 specification. + + This extension is written against the wording of EGL_KHR_lock_surface + version 18. + +Overview + + This extension slightly modifies and clarifies some semantic aspects + of the EGL_KHR_lock_surface extension, in a way that is backwards + compatible for applications. + + The extension is presented here as the full text of the + EGL_KHR_lock_surface extension (minus the Status, Version, Number and + Dependencies sections at the start) as modified by the changes made by + this EGL_KHR_lock_surface2 extension. A diff utility can be used between + EGL_KHR_lock_surface version 18 and this EGL_KHR_lock_surface2 extension + to show the exact changes. + + An application which needs to tell whether the implementation supports + EGL_KHR_lock_surface2, or just the original EGL_KHR_lock_surface, can + use eglQueryString with EGL_EXTENSIONS to query the list of + implemented extensions. + + The changes over EGL_KHR_lock_surface can be summarized as follows: + + * EGL_KHR_lock_surface had the EGL_MAP_PRESERVE_PIXELS_KHR attribute on + eglLockSurfaceKHR, but failed to point out how the surface attribute + EGL_SWAP_BEHAVIOR would interact with lock surface rendering. + EGL_KHR_lock_surface2 specifies that the locked buffer contains the + back buffer pixels if EGL_SWAP_BEHAVIOR is EGL_BUFFER_PRESERVED + _or_ if EGL_MAP_PRESERVE_PIXELS_KHR is EGL_TRUE, and provides a way to + set EGL_SWAP_BEHAVIOR on creation of a lockable window surface, + even if EGL_SWAP_BEHAVIOR is not otherwise modifiable. + EGL_SWAP_BEHAVIOR now defaults to EGL_BUFFER_PRESERVED for a + lockable surface. + + * EGL_KHR_lock_surface failed to specify its interaction with the + EGL requirement that a context be current at eglSwapBuffers; no + context is used for lock surface rendering. EGL_KHR_lock_surface2 + relaxes that requirement for a lockable window surface, in a way + that is anticipated to apply to all window surfaces in a future + version of EGL. + + * Wording in EGL_KHR_lock_surface could be read to imply that almost + all surface attributes are invariant for a lockable surface. + EGL_KHR_lock_surface2 clarifies the wording. + + * EGL_KHR_lock_surface2 clarifies what is returned when + the attribute EGL_MATCH_FORMAT_KHR is queried, especially when + one of the "inexact" formats was used to choose the config. + + * EGL_KHR_lock_surface did not specify when a surface could change size. + EGL_KHR_lock_surface2 specifies that a surface cannot change size + when it is locked. + + * EGL_KHR_lock_surface2 adds the config attribute + EGL_BITMAP_PIXEL_SIZE_KHR, to allow an application to dynamically + detect pixel layout for a format with a "hole", such as RGBU8888 + (where "U" means "unused"). + +New Tokens + + Accepted by the <attribute> parameter of eglQuerySurface: + + EGL_BITMAP_PIXEL_SIZE_KHR 0x3110 + +Full text of EGL_KHR_lock_surface plus EGL_KHR_lock_surface2: + +Overview + + This extension allows mapping color buffers of EGL surfaces into the + client address space. This is useful primarily for software + rendering on low-end devices which do not support EGL client + rendering APIs, although it may be implemented efficiently on more + capable devices as well. + +New Types + + None + +New Procedures and Functions + + EGLBoolean eglLockSurfaceKHR(EGLDisplay dpy, EGLSurface surface, + const EGLint *attrib_list); + EGLBoolean eglUnlockSurfaceKHR(EGLDisplay dpy, + EGLSurface surface); + +New Tokens + + Returned in the EGL_SURFACE_TYPE bitmask attribute of EGLConfigs: + + EGL_LOCK_SURFACE_BIT_KHR 0x0080 + EGL_OPTIMAL_FORMAT_BIT_KHR 0x0100 + + Accepted as an attribute name in the <attrib_list> argument of + eglChooseConfig, and the <attribute> argument of eglGetConfigAttrib: + + EGL_MATCH_FORMAT_KHR 0x3043 + + Accepted as attribute values for the EGL_MATCH_FORMAT_KHR attribute + of eglChooseConfig, and defined as possible values of that attribute + when querying it: + + EGL_FORMAT_RGB_565_EXACT_KHR 0x30C0 + EGL_FORMAT_RGBA_8888_EXACT_KHR 0x30C2 + + Accepted as attribute values for the EGL_MATCH_FORMAT_KHR attribute + of eglChooseConfig: + + EGL_FORMAT_RGB_565_KHR 0x30C1 + EGL_FORMAT_RGBA_8888_KHR 0x30C3 + + Accepted as attribute names in the <attrib_list> argument of + eglLockSurfaceKHR: + + EGL_MAP_PRESERVE_PIXELS_KHR 0x30C4 + EGL_LOCK_USAGE_HINT_KHR 0x30C5 + + Accepted as bit values in the EGL_LOCK_USAGE_HINT_KHR bitmask attribute + of eglLockSurfaceKHR: + + EGL_READ_SURFACE_BIT_KHR 0x0001 + EGL_WRITE_SURFACE_BIT_KHR 0x0002 + + Accepted by the <attribute> parameter of eglQuerySurface: + + EGL_BITMAP_POINTER_KHR 0x30C6 + EGL_BITMAP_PITCH_KHR 0x30C7 + EGL_BITMAP_ORIGIN_KHR 0x30C8 + EGL_BITMAP_PIXEL_RED_OFFSET_KHR 0x30C9 + EGL_BITMAP_PIXEL_GREEN_OFFSET_KHR 0x30CA + EGL_BITMAP_PIXEL_BLUE_OFFSET_KHR 0x30CB + EGL_BITMAP_PIXEL_ALPHA_OFFSET_KHR 0x30CC + EGL_BITMAP_PIXEL_LUMINANCE_OFFSET_KHR 0x30CD + EGL_BITMAP_PIXEL_SIZE_KHR 0x3110 + + Returns in the *<value> parameter of eglQuerySurface when + <attribute> is EGL_BITMAP_ORIGIN_KHR: + + EGL_LOWER_LEFT_KHR 0x30CE + EGL_UPPER_LEFT_KHR 0x30CF + +Additions to Chapter 2 of the EGL 1.3 Specification (EGL Operation) + + Add to the end of section 2.2.2: + + Finally, some surfaces may be <locked>, which allows the + implementation to map buffers of that surface into client memory + for use by software renderers(fn). Locked surfaces cannot be + used for any other purpose. When a locked surface is <unlocked>, + any changes to the mapped buffer(s) are reflected in the actual + graphics or system memory containing the surface. + + [fn: on implementations not supporting mapping graphics + memory, or which do not wish to take the stability and + security risks that entail, mapping may be done using + copy-out and copy-in behavior.] + +Additions to Chapter 3 of the EGL 1.3 Specification (EGL Functions and Errors) + + Add to the description of the EGL_BAD_ACCESS error in section 3.1: + + "... or, a surface is locked)." + + Add to table 3.2 ("Types of surfaces supported by an EGLConfig") + + EGL Token Name Description + -------------------- ------------------------------------ + EGL_LOCK_SURFACE_BIT_KHR EGLConfig allows locking surfaces + EGL_OPTIMAL_FORMAT_BIT_KHR This format is considered optimal + (preferred) when locking / mapping / + unlocking is being done. + + Change the first paragraph under "Other EGLConfig Attribute + Descriptions" on p. 16: + + "EGL_SURFACE_TYPE is a mask indicating both the surface types + that can be created by the corresponding EGLConfig (the config + is said to <support> those surface types), and the optional + behaviors such surfaces may allow. The valid bit settings are + shown in Table 3.2." + + Add a new paragraph following the second paragraph of the same + section: + + "If EGL_LOCK_SURFACE_BIT_KHR is set in EGL_SURFACE_TYPE, then + a surface created from the EGLConfig may be locked, mapped into + client memory, and unlocked. Locking is described in section + 3.5.6. If EGL_OPTIMAL_FORMAT_BIT_KHR is set in + EGL_SURFACE_TYPE, then the surface is considered optimal (by + the implementation) from a performance standpoint when buffer + mapping is being done." + + Replace the second paragraph of section 3.3 "EGL Versioning": + + "The EGL_CLIENT_APIS string describes which client rendering APIs + are supported. It is zero-terminated and contains a + space-separated list of API names, which may include + ``OpenGL_ES'' if OpenGL ES is supported, and ``OpenVG'' if + OpenVG is supported. If no client APIs are supported, then the + empty string is returned." + + Insert a new paragraph and table in section 3.4.1 "Querying + Configurations", following the description of + EGL_MATCH_NATIVE_PIXMAP on page 21: + + "If EGL_MATCH_FORMAT_KHR is specified in <attrib_list>, it must + be followed by one of the attribute values EGL_DONT_CARE, + EGL_NONE, or one of the format tokens in table + [locksurf.format]. + + When EGL_MATCH_FORMAT_KHR has the value EGL_NONE, only configs + which cannot be locked or mapped will match. Such configs must + not have the EGL_LOCK_SURFACE_BIT_KHR set in EGL_SURFACE_TYPE. + + When EGL_MATCH_FORMAT_KHR has the value EGL_DONT_CARE, it is + ignored. + + When EGL_MATCH_FORMAT_KHR has one of the values in table + [locksurf.format], only EGLConfigs describing surfaces whose + color buffers have the specified format, when mapped with + eglLockSurface, will match this attribute. In this case, the + EGL_<component>_SIZE attributes of resulting configs must agree + with the specific component sizes specified by the format." + + Specific Format Name Description + -------------------- ----------- + EGL_FORMAT_RGB_565_EXACT_KHR RGB565 fields in order from MSB to LSB within a 16-bit integer + EGL_FORMAT_RGB_565_KHR RGB565 fields in implementation-chosen order within a 16-bit integer + EGL_FORMAT_RGBA_8888_EXACT_KHR RGBA8888 fields in B, G, R, A byte order in memory + EGL_FORMAT_RGBA_8888_KHR RGBA8888 fields in implementation-chosen order within a 32-bit integer + ------------------------------------------------------------------------------------------------------ + Table [locksurf.format]: Specific formats for mapped pixels. + + Add to table 3.4 ("Default values and match critera for EGLConfig + attributes") on page 22: + + Attribute Default Selection Sort Sort + Criteria Order Priority + -------------------- ------------- --------- ----- -------- + EGL_MATCH_FORMAT_KHR EGL_DONT_CARE Exact None - + + Add EGL_MATCH_FORMAT_KHR to the last paragraph in section 3.4.1 on + p. 23, describing attributes not used for sorting EGLConfigs. + + Add a new paragraph to the end of section 3.4.3 "Querying Configuration + Attributes": + + "Querying the EGL_MATCH_FORMAT_KHR attribute results in EGL_NONE + for an EGLConfig that is not lockable, one of the "exact" formats + (EGL_FORMAT_RGB_565_EXACT_KHR, EGL_FORMAT_RGBA_8888_EXACT_KHR) + if the color buffer matches that format when mapped with + eglLockSurface, or for any other format a value that is not + EGL_NONE or EGL_DONT_CARE but is otherwise undefined. In particular, + the color buffer format matching one of the "inexact" formats + does not guarantee that that EGL_FORMAT_* value is returned." + + In section 3.5.1 "Creating On-Screen Rendering Surfaces", add the + following to the paragraph that lists the attributes that can be set + in attrib_list: + + "... and EGL_SWAP_BEHAVIOR." + + and add a new penultimate paragraph: + + "EGL_SWAP_BEHAVIOR specifies the initial value of the + EGL_SWAP_BEHAVIOR surface attribute (section 3.5.6), and is thus + either EGL_BUFFER_PRESERVED or EGL_BUFFER_DESTROYED. This setting + of EGL_SWAP_BEHAVIOR at surface creation time is supported only + for a lockable surface, i.e. where the EGLConfig has + EGL_LOCK_SURFACE_BIT_KHR set in EGL_SURFACE_TYPE." + + In EGL 1.4, also add the following text to that same paragraph: + + "For such a lockable surface, whether it is possible to change + the EGL_SWAP_BEHAVIOR attribute after surface creation is + determined by EGL_SWAP_BEHAVIOR_PRESERVED_BIT in the + EGL_SURFACE_TYPE EGLConfig attribute." + + Add a new section following the current section 3.5.5: + + "3.5.6 Locking and Mapping Rendering Surfaces + + A rendering surface may be <locked> by calling + + EGLBoolean eglLockSurfaceKHR(EGLDisplay dpy, + EGLSurface surface, + const EGLint *attrib_list); + + While a surface is locked, only two operations can be performed + on it. First, a surface attribute may be queried using + eglQuerySurface. This includes the case of querying + EGL_BITMAP_POINTER_KHR, which causes the surface to be + <mapped> (if not already mapped) and gives + a pointer into client memory corresponding to the memory + of the mapped buffer. Second, the surface may be unlocked. Any + attempts to use a locked surface in other EGL APIs will fail and + generate an EGL_BAD_ACCESS error. + + While a surface is locked, its dimensions (the values of the EGL_WIDTH + and EGL_HEIGHT surface attributes) do not change. They may change + at any other time, therefore an application must query these + attributes <after> the call to eglLockSurfaceKHR to ensure that it has + the correct size of the mapped buffer. + + <attrib_list> specifies additional parameters affecting the locking + operation. The list has the same structure as described for + eglChooseConfig. Attributes that may be defined are shown in table + [locksurf.attr], together with their default values if not specified + in <attrib_list>, and possible values which may be specified for + them in <attrib_list>. + + Attribute Name Type Default Value Possible Values + ----------------------- ------- ------------- ------------------------- + EGL_MAP_PRESERVE_PIXELS_KHR boolean EGL_FALSE EGL_TRUE / EGL_FALSE + EGL_LOCK_USAGE_HINT_KHR bitmask EGL_READ_SURFACE_BIT_KHR | Any combination of + EGL_WRITE_SURFACE_BIT_KHR EGL_READ_SURFACE_BIT_KHR + and EGL_WRITE_SURFACE_BIT_KHR + -------------------------------------------------------------- + Table [locksurf.attr]: eglLockSurfaceKHR attribute names, + default values, and possible values. + + On failure, the surface is unaffected and eglLockSurfaceKHR + returns EGL_FALSE. An EGL_BAD_ACCESS error is generated if any + of these condition, are true: + + * <surface> was created with an EGLConfig whose + EGL_SURFACE_TYPE attribute does not contain + EGL_LOCK_SURFACE_BIT_KHR. + * <surface> is already locked. + * Any client API is current to <surface>. + + An EGL_BAD_ATTRIBUTE error is generated if an attribute or + attribute value not described in table [locksurf.attr] is + specified. + + Mapping Buffers of a Locked Surface + ----------------------------------- + + The color buffer of a locked surface can be <mapped> by calling + eglQuerySurface (see section 3.5.7) with <attribute> + EGL_BITMAP_POINTER_KHR(fn). The query returns a pointer to a + buffer in client memory corresponding to the color buffer of + <surface>. In the case of a back-buffered surface, color buffer + refers to the back buffer. + + [fn: "mapped" only means that the pointer returned is + intended to *correspond* to graphics memory. Implementation + are not required to return an actual pointer into graphics + memory, and often will not.] + + + The contents of the mapped buffer are initially undefined(fn) + unless either the EGL_MAP_PRESERVE_PIXELS_KHR attribute of + eglLockSurfaceKHR is set to EGL_TRUE, or (for a window surface) + the EGL_SWAP_BEHAVIOR surface attribute is set to + EGL_BUFFER_PRESERVE, in which case the contents + of the buffer are taken from the contents of <surface>'s color + buffer. The default value of EGL_MAP_PRESERVE_PIXELS_KHR is + EGL_FALSE. + + [fn: In order to avoid pipeline stalls and readback delays on + accelerated implementations, we do not mandate that the + current contents of a color buffer appear when it's mapped + to client memory, unless the EGL_MAP_PRESERVE_PIXELS_KHR + flag is set or (for a window surface) EGL_SWAP_BEHAVIOR is + set to EGL_BUFFER_PRESERVE. Applications using mapped + buffers which are not + preserved must write to every pixel of the buffer before + unlocking the surface. This constraint is considered + acceptable for the intended usage scenario (full-frame + software renderers). Such an application may lock-render-unlock + multiple times per frame (i.e. per eglSwapBuffers) by setting + EGL_MAP_PRESERVE_PIXELS_KHR to EGL_TRUE for the second and + subsequent locks. + + Note that EGL_SWAP_BEHAVIOR also controls whether the color + buffer contents are preserved over a call to eglSwapBuffers.] + + The EGL_LOCK_USAGE_HINT_KHR attribute of eglLockSurfaceKHR is a + bitmask describing the intended use of the mapped buffer. If the + mask contains EGL_READ_SURFACE_BIT_KHR, data will be read from + the mapped buffer. If the mask contains + EGL_WRITE_SURFACE_BIT_KHR, data will be written to the mapped + buffer. Implementations must support both reading and writing to + a mapped buffer regardless of the value of + EGL_LOCK_USAGE_HINT_KHR, but performance may be better if the + hint is consistent with the actual usage of the buffer. The + default value of EGL_LOCK_USAGE_HINT_KHR hints that both reads + and writes to the mapped buffer will be done. + + Other attributes of the mapped buffer describe the format of + pixels it contains, including its pitch (EGL_BITMAP_PITCH_KHR), + origin (EGL_BITMAP_ORIGIN_KHR), and the bit location of each color + component within a pixel (EGL_BITMAP_PIXEL_x_OFFSET_KHR). These + attributes may be queried using eglQuerySurface, and are described + in more detail in section 3.5.7. + + The EGL_BITMAP_POINTER_KHR and EGL_BITMAP_PITCH_KHR attributes + of a locked surface may change following successive calls to + eglLockSurfaceKHR(fn), so they must be queried each time a + buffer is mapped. Other attributes of a mapped buffer (listed in + the paragraph above) are invariant and need be queried only once + following surface creation. + + [fn: The pointer and pitch of a mapped buffer may change due + to display mode changes, for example.] + + Mapping will not suceed if client memory to map the surface into + cannot be allocated. In this case, querying eglQuerySurface with + <attribute> EGL_BITMAP_POINTER_KHR will fail and generate an EGL + error. + + Unlocking Surfaces + ------------------ + + A rendering surface may be <unlocked> by calling + + EGLBoolean eglUnlockSurfaceKHR(EGLDisplay dpy, + EGLSurface surface); + + Any mapped buffers of <surface> become unmapped following + eglUnlockSurfaceKHR. Any changes made to mapped buffers of + <surface> which it was locked are reflected in the surface after + unlocking(fn). + + [fn: This language enables implementations to either map + video memory, or copy from a separate buffer in client + memory.] + + If <surface> was created with an EGLConfig whose + EGL_SURFACE_TYPE attribute contains EGL_OPTIMAL_FORMAT_BIT_KHR, + then the surface is considered optimal (by the implementation) + from a performance standpoint when buffer mapping is being + done(fn). + + [fn: This often means that the format of all mapped buffers + corresponds directly to the format of those buffers in + <surface>, so no format conversions are required during + unmapping. This results in a high-performance software + rendering path. But "optimal format" is really just a hint + from EGL that this config is preferred, whatever the actual + reason.] + + On failure, eglUnlockSurfaceKHR returns EGL_FALSE. An + EGL_BAD_ACCESS error is generated if any of these conditions are + true: + + * <surface> is already unlocked. + * A display mode change occurred while the surface was locked, + and the implementation was unable to reflect mapped buffer + state(fn). In this case, <surface> will still be unlocked. + However, the contents of the previously mapped buffers of + <surface> become undefined, rather than reflecting changes + made in the mapped buffers in client memory. + + [fn: Usually this may only occur with window surfaces which + have been mapped. EGL does not have an event mechanism to + indicate display mode changes. If such a mechanism exists + (using native platform events or the OpenKODE event system), + applications should respond to mode changes by regenerating + all visible window content, including re-doing any software + rendering overlapping the mode change.]" + + Add to table 3.5 ("Queryable surface attributes and types") + + Attribute Type Description + --------- ---- ----------- + EGL_BITMAP_POINTER_KHR pointer Address of a mapped color buffer (MCB). + EGL_BITMAP_PITCH_KHR integer Number of bytes between the start of + adjacent rows in an MCB. + EGL_BITMAP_ORIGIN_KHR enum Bitmap origin & direction + EGL_BITMAP_PIXEL_x_OFFSET_KHR integer Bit location of each color buffer + component within a pixel in an MCB. + EGL_BITMAP_PIXEL_SIZE_KHR integer Bits per pixel + + In EGL 1.4 only, in the description of eglSurfaceAttrib properties + that can be set in section 3.5.6 (renumbered to 3.5.7), on page 35, + add to the first paragraph describing EGL_SWAP_BEHAVIOR: + + "The value of EGL_SWAP_BEHAVIOR also affects the semantics of + eglLockSurfaceKHR for a lockable window surface. See section 3.5.6." + + In EGL 1.4 only, in the description of eglSurfaceAttrib properties + that can be set in section 3.5.6 (renumbered to 3.5.7), on page 35, + change the paragraph concerning the initial value of EGL_SWAP_BEHAVIOR + to: + + "The initial value of EGL_SWAP_BEHAVIOR is chosen by the + implementation, except for a lockable window surface (i.e. where the + EGLConfig has both EGL_LOCK_SURFACE_BIT_KHR and EGL_WINDOW_BIT set in + EGL_SURFACE_TYPE), where the default is EGL_BUFFER_PRESERVED, but it + may be overridden by specifying EGL_SWAP_BEHAVIOR to + eglCreateWindowSurface." + + In EGL 1.3 only, in the description of eglQuerySurface properties + that can be queried in section 3.5.6 (renumbered to 3.5.7), on page 33, + add to the paragraph describing EGL_SWAP_BEHAVIOR: + + "The value of EGL_SWAP_BEHAVIOR also affects the semantics of + eglLockSurfaceKHR for a lockable window surface. See section 3.5.6. + For a lockable window surface (one whose EGLConfig has both + EGL_LOCK_SURFACE_BIT_KHR and EGL_WINDOW_BIT set in EGL_SURFACE_TYPE), + the value of this attribute may be set in the eglCreateWindowSurface + call, and if not set there defaults to EGL_BUFFER_PRESERVED. See + section 3.5.1. The default for a non-lockable surface is chosen by the + implementation." + + Add to the description of eglQuerySurface properties in section + 3.5.6 (renumbered to 3.5.7) on page 33: + + "Properties of a bitmap surface which may be queried include: + * EGL_BITMAP_POINTER_KHR, which maps the color buffer of a + locked surface and returns the address in client memory of + the mapped buffer. + * EGL_BITMAP_PITCH_KHR, which returns the number of bytes + between successive rows of a mapped buffer. + * EGL_BITMAP_ORIGIN_KHR, which describes the way in which a + mapped color buffer is displayed on the screen. Possible + values are either EGL_LOWER_LEFT_KHR or EGL_UPPER_LEFT_KHR, + indicating that the first pixel of the mapped buffer + corresponds to the lower left or upper left of a visible + window, respectively. + * EGL_BITMAP_PIXEL_<x>_OFFSET_KHR, which describes the bit + location of the least significant bit of each color + component of a pixel within a mapped buffer. <x> is one of + RED, GREEN, BLUE, ALPHA, or LUMINANCE. + + The offset for a color component should be treated as the + number of bits to left shift the component value to place it + within a n-bit + integer containing the pixel, where n is the number of bits + per pixel. If a color + component does not exist in the mapped buffer, then the bit + offset of that component is zero. If a color component + does exist but not in a single contiguous range of bits, + then the value of the attribute is EGL_UNKNOWN. + + * EGL_BITMAP_PIXEL_SIZE_KHR, which returns the number of bits + per pixel, assumed to be least significant leftmost if there + are multiple pixels per byte. The attribute takes the value + EGL_UNKNOWN if this assumption is not true, or if pixels are not + laid out left to right in memory (for example pairs of 16-bit + pixels are swapped in memory). + + In addition to these attributes, the number of bits for each + color component of a pixel within a mapped buffer is obtained by + querying the EGL_<x>_SIZE attribute of the EGLConfig used to + create the surface, where <x> is <x> is one of RED, GREEN, BLUE, + ALPHA, or LUMINANCE. + + Querying EGL_BITMAP_POINTER_KHR and EGL_BITMAP_PITCH_KHR is only + allowed when <surface> is mapped (see section 3.5.6). Querying + either of these attributes for the first time after calling + eglLockSurfaceKHR causes the color buffer of the locked surface + to be mapped. Querying them again before unlocking the surface + will return the same values as the first time. However, after + calling eglUnlockSurfaceKHR, these properties become undefined. + After a second call to eglLockSurfaceKHR, these properties may + again be queried, but their values may have changed. + + Other properties of the mapped color buffer of a surface + (in the list above) are + invariant, and need be queried only once following surface + creation. If <surface> was created with an EGLConfig whose + EGL_SURFACE_TYPE attribute does not contain + EGL_LOCK_SURFACE_BIT_KHR, queries of EGL_BITMAP_ORIGIN_KHR, + EGL_BITMAP_PIXEL_<x>_OFFSET_KHR and EGL_BITMAP_PIXEL_SIZE_KHR + return undefined values." + + Add to the description of eglQuerySurface errors in the last + paragraph of section 3.5.6 (renumbered to 3.5.7) on page 34: + + "... If <attribute> is either EGL_BITMAP_POINTER_KHR or + EGL_BITMAP_PITCH_KHR, and either <surface> is not locked using + eglLockSurfaceKHR, or <surface> is locked but mapping fails, + then an EGL_BAD_ACCESS error is generated." + + In section 3.9.3 Posting Semantics on page 46, append to the first + paragraph: + + "This restriction does not apply to lockable surfaces; for such + a surface, eglSwapBuffers and eglCopyBuffers may be called for + a surface not bound to any client API context(fn). + + [fn: Normally this would only be done when using methods other + than client API rendering to specify the color buffer contents, + such as software rendering to a locked surface.]" + + and replace the second paragraph ("If <dpy> and <surface> ... not be + executed until posting is completed.") with: + + "If <surface> is bound to a current client API context for the calling + thread, eglSwapBuffers and eglCopyBuffers perform an implicit flush + operation on the context (glFlush for an OpenGL or OpenGL ES context, + vgFlush for an OpenVG context). Subsequent client API commands can be + issued immediately, but will not be executed until posting is + completed. + + If <surface> is current to a client API context in any thread other + than the calling thread, eglSwapBuffers and eglCopyBuffers will fail. + + and append the following sentence to the eglSwapInterval paragraph: + + "The swap interval has no effect on an eglSwapBuffers for a surface + not bound to a current client API context." + + In 3.9.4 Posting Errors, change the sentence "If <surface> is not bound + to the calling thread's current context, an EGL_BAD_SURFACE error is + generated." to: + + "If <surface> is bound to a current context in a thread other + than the calling thread, an EGL_BAD_SURFACE error is generated." + + +Issues + + 1) What is the rationale for this extension? + + Software renderers on low-end implementations need an efficient way + to draw pixel data to the screen. High-end implementations must + support the same interface for compatibility, while not compromising + the accelerability of OpenGL ES and OpenVG client APIs using + dedicated graphics hardware and memory. + + Using lock/unlock semantics enables low-end implementations to + expose pointers directly into display memory (as extremely dangerous + as that may be), while high-end implementations may choose to create + backing store in client memory when mapping a buffer, and copy it to + graphics memory when the surface is unlocked. Making the initial + contents of a mapped buffer undefined means that no readbacks from + graphics memory are required, avoiding pipeline stalls. + + This extension is not intended to support mixed-mode (client API and + software) rendering. Since mapped buffer contents are undefined, + unless the buffer is explicitly preserved (which may be unacceptably + expensive on many implementations), applications doing software + rendering must touch every pixel of mapped buffers at least once + before unlocking the surface. + + 2) Do we need to know if locked surfaces are "fast" or "native"? + + RESOLVED: Yes. This is indicated with the EGL_OPTIMAL_FORMAT_BIT_KHR + of EGL_SURFACE_TYPE. However, note that there is no way to guarantee + what "fast" or "no format conversions" really means; this is little + more than an implementation hint. + + 3) Should we be able to map buffers other than the color buffer? + + RESOLVED: Not initially. However, the <attrib_list> parameter of + eglLockSurfaceKHR supports this in the future. There is no <buffer> + attribute to eglQuerySurface, so such a layered extension would have + to either create a new naming convention (such as + EGL_BITMAP_{DEPTH,COLOR,STENCIL,ALPHA_MASK}_POINTER), or define an + extended query eglQuerySurfaceBuffer() which takes a <buffer> + parameter. It would also be tricky to support interleaved depth / + stencil formats. But the attribute list offers some future-proofing + at low cost. + + 4) What properties of mapped buffers can be queried? + + RESOLVED: A pointer to the buffer and its pitch, both of which may + change in successive lock/unlock cycles. These may be queried only + while the underlying surface is locked, and are undefined after + unlocking. The first query following locking is the point at which + actual buffer mapping must occur. + + RESOLVED: Additionally, the pixel size, origin, and color component + bitfield size and offset for each component, which are invariant + and may be queried at any time. + + 5) How are mode changes indicated? What happens to the mapped + buffer during a mode change? + + RESOLVED: UnlockSurfaceKHR fails and raises an error if a mode + change occurred while the surface was locked (although the surface + still ends up in the unlocked state - this is necessary since + there's no way to clear the error!). If a mode change occurs while a + buffer is mapped, the implementation must still allow the + application to access mapped buffer memory, even though the contents + of the mapped buffer may not be reflected in the changed window + after unmapping. + + Note: There's no convenient way to indicate mode changes while + a surface is unlocked, despite that being useful to tell apps they + have to redraw. The problem is that we don't have an event system, + and the power management functionality is overkill since the only + resources which are likely to be damaged by a mode change are + visible window contents. Fortunately, this problem is beyond the + scope of this extension. + + 6) Does locking a surface imply mapping its buffers? + + RESOLVED: No. Locking simply places the surface in that state and + prevents it from being made current / swapped / etc. Buffers are + mapped only when their pointers or pitch are queried using + eglQuerySurface. + + An interesting side effect of this resolution is that calling + eglLockSurfaceKHR immediately followed by eglUnlockSurfaceKHR DOES + NOT CHANGE THE CONTENTS OF BUFFERS, since none of them were mapped. + Likewise locking a surface, querying a buffer pointer or pitch, and + then unlocking it without changing the mapped buffer contents causes + the surface contents of the mapper buffer(s) to become undefined. + + At the Atlanta F2F, there was a suggestion that eglLockSurfaceKHR + should immediately map the color buffer and return a pointer to it, + on the basis that this would make it harder for applications to + mistakenly use an old buffer pointer from a previous mapping cycle. + At the same time, people working on more powerful GPUs wanted the + lock operation to be lightweight. These are not consistent goals and + we have thus far chosen to separate the lightweight locking, and + more expensive mapping operations. + + 7) Can buffer contents be preserved in mapping? + + RESOLVED: Yes. The default behavior is to discard / leave undefined + the mapped buffer contents, but the EGL_MAP_PRESERVE_PIXELS_KHR flag + may be specified to eglLockSurfaceKHR. + + 8) Should usage hints be provided during mapping? + + RESOLVED: Yes, they may be provided in the EGL_LOCK_USAGE_HINT_KHR + bitmask attribute to eglLockSurfaceKHR. Implementations are required + to behave correctly no matter the value of the flag vs. the + operations actually performed, so the hint may be ignored. + + 9) Should we be able to lock subrectangles of a surface? + + RESOLVED: No. However, the attribute list parameter of + eglLockSurfaceKHR allows a layered extension to implement this + behavior by specifying an origin and size to map within the buffer. + +10) Should the BITMAP_PIXEL_<component>_OFFSET attributes belong to the + surface, or the config? + + RESOLVED: Part of the surface. Configs supporting a specific format + are matched with config attribute EGL_MATCH_FORMAT_KHR, which + supports specific bit-exact formats such as + EGL_FORMAT_565_EXACT_KHR. + +11) Can the pixel size in a mapped buffer be derived from the + EGL_BUFFER_SIZE attribute of the config used to create it? + + RESOLVED: Yes. In principle, hardware using padding bytes in its + framebuffer storage could be a problem, and a separate + BITMAP_PIXEL_SIZE surface attribute would be needed. However, we + don't think implementations are likely to waste graphics memory and + bandwidth in this fashion. + +12) How are color component locations within a pixel described? + + RESOLVED: Each R, G, B, and A component has a queryable bit offset + within an integer. The size of the integer depends on the total size + of the pixel; for the 565 formats, the pixel is a 16-bit integer. + For the 8888 formats, the pixel is a 32-bit integer. + + We cannot describe component locations with byte locations, since + the 565 formats have components straddling byte boundaries. However, + this means that offsets for the RGBA8888_EXACT format are different + between little- and big-endian CPUs, since the desired format is B, + G, R, A components laid out as bytes in increasing memory order. + +13) Can mapped buffer contents be affected by other EGL operations? + + RESOLVED: No. A locked surface only allows two operations: + unlocking, and mapping. No other EGL operations can take place while + the surface is locked (if this were not the case, then + eglSwapBuffers might destroy the contents of a mapped buffer). + + It is possible that operations outside the scope of EGL could affect + a mapped color buffer. For example, if a surface's color buffer were + made up of an EGLImage, one of the EGL client APIs could draw to + that image while it was mapped. Responsibility for avoiding this + situation is in the hands of the client. + +14) Can EGL_MATCH_FORMAT_KHR be queried for a config? + + RESOLVED: Yes. Unlockable configs return EGL_NONE for this + attribute. + + For a config whose format matches one of the EGL_FORMAT_*_EXACT_KHR + definitions, that value is returned. + + For a config whose format does not match one of the + EGL_FORMAT_*_EXACT_KHR definitions, but it does match one of the + inexact definitions, we do not want to specify that it returns that + value, since that precludes it returning an exact format if one were + to be defined in a future extension, or a future version of this + extension. + + Therefore, for a config whose format does not match a defined + "exact" format, the attribute returns a value other than the defined + "exact" formats and EGL_NONE and EGL_DONT_CARE. + +15) Is a goal of this extension to support "mixed-mode" rendering (both + software and EGL client API rendering to the same surface)? + + RESOLVED: No. An implementation *can* choose to export configs + supporting creation of lockable surfaces which also support + rendering by OpenGL ES, OpenVG, or other client APIs (when the + surface is not locked). But there is nothing in the extension + requiring this, and the motivation for the extension is simply to + support software rendering. + +16) Can mapping a locked surface fail? + + RESOLVED: Yes, if memory can't be allocated in the client. This is + indicated by queries of EGL_BITMAP_POINTER_KHR and + EGL_BITMAP_PITCH_KHR failing and generating an EGL_BAD_ACCESS error. + +17) How does the application specify that it would like the pixels in the + mapped buffer to be preserved from the state at the last unlock? + [Bug 4410] + + There are actually two items that need to be configurable: + + a. Whether eglSwapBuffers preserves the color buffer. + + b. Whether eglLockSurfaceKHR puts the color buffer pixels into the + locked buffer. + + An implementation may use two different render paths depending on whether + the application is full frame rendering or incrementally rendering, where + the full frame rendering path may involve less copying than the + incrementally rendering path. The implementation needs to know in advance + which path to use; finding out from EGL_MAP_PRESERVE_PIXELS_KHR on + eglLockSurfaceKHR whether that lock should have the color buffer pixels + from the last eglUnlockSurfaceKHR in the last frame is too late. + + This need to know in advance only applies to (a). + + Note that the original EGL_KHR_lock_surface extension failed to state + that EGL_SWAP_BEHAVIOR needed to be set to EGL_BUFFER_PRESERVED for + incremental rendering. + + RESOLVED: EGL_MAP_PRESERVE_PIXELS_KHR continues to control (b), as in the + original EGL_KHR_lock_surface extension. EGL_SWAP_BEHAVIOR continues + to control (a), as in unextended EGL. It is possible to set + EGL_SWAP_BEHAVIOR in eglCreateWindowSurface, even on EGL versions + before 1.4, and even if the config does not have + EGL_SWAP_BEHAVIOR_PRESERVED_BIT set in EGL_SURFACE_TYPE. + + For a lockable window surface, EGL_SWAP_BEHAVIOR needs to default to + EGL_BUFFER_PRESERVED, and having EGL_SWAP_BEHAVIOR set to + EGL_BUFFER_PRESERVED needs to override EGL_MAP_PRESERVE_PIXELS_KHR. This is for + compatibility with version 1 of this extension, which had EGL_SWAP_BEHAVIOR + as the sole means of controlling (a) and (b). + + This resolution is backward compatible with the original + EGL_KHR_lock_surface extension as it now defaults to preserving pixels, + and thus has that default for an old application that does not know about + setting EGL_SWAP_BEHAVIOR=EGL_BUFFER_DESTROYED to optimize full frame + rendering. The downside is a possible performance reduction of an old + application that does not want pixels preserved, until it is appropriately + modified and recompiled. + +18) When can a lockable surface change size? [Bug 4522] + + RESOLVED: The surface cannot change size while it is locked. For any + window size change during that time, EGL defers the corresponding + surface size change until some time after the unlock. + The implication is that an application must get the surface size + _after_locking, otherwise the size may have changed in between the + attribute query and the lock. + + As part of this change, using eglQuerySurface on any surface attribute + while the surface is locked has been allowed. + +19) Should we provide for more than one pixel per byte, or a format with + a "hole", or a byte-swapped 16-bit format? [Bug 4513] + + For the use case where the application uses EGL_FORMAT_* to + determine the pixel format, this is not an issue. For the use case + where the application is written to cope with any format by reading + the EGL_BITMAP_* attributes and adjusting its rendering at runtime, + this is an issue. + + RESOLVED: We add a new attribute EGL_BITMAP_PIXEL_SIZE_KHR which gives + the pixel size in bits. + The use of this attribute assumes that multiple pixels packed into + a byte are arranged least significant on the left, and that pixels + are arranged leftmost first in memory. If either of these assumptions + is false, then EGL_BITMAP_PIXEL_SIZE_KHR is EGL_UNKNOWN to indicate + that an application attempting to use these attributes to adjust its + rendering code will not work. + + We also define that any of the EGL_BITMAP_PIXEL_x_OFFSET_KHR attributes + have a value of EGL_UNKNOWN if the corresponding color component is not + a contiguous bit range. + +20) EGL states that surface must be bound to the thread's current context + when posting, but there is no current context when using lock surface. + eglSwapInterval is also related to the context. [Bug 5923] + + RESOLVED: The posting restrictions are relaxed, so it is allowed to + post for a surface not bound to any client API context. In this case + no eglSwapInterval setting affects an eglSwapBuffers. This relaxation + only applies to a lockable surface so that this extension continues + to be implementable as a middleware layer on top of a "real" EGL. + The relaxation applies to a surface that is both lockable and client + API renderable; the implicit flush in a post only occurs when the surface + is bound to a current API context. Posting a surface bound to a different + thread's current API context is still disallowed. + +21) Why has this extension been obsoleted and replaced by + EGL_KHR_lock_surface3? + + RESOLVED: Starting with the December 4, 2013 release of EGL 1.4, EGLint + is defined to be the same size as the native platform "int" type. Handle + and pointer attribute values *cannot* be represented in attribute lists + on platforms where sizeof(handle/pointer) > sizeof(int). Existing + extensions which assume this functionality are being replaced with new + extensions specifying new entry points to work around this issue. See + the latest EGL 1.4 Specification for more details. + + +Revision History + + Version 3, 2013/12/04 - Add issue 21 explaining that the bitmap pointer + cannot be safely queried using this extension on 64-bit platforms, + and suggesting EGL_KHR_lock_surface3 instead. Change formal + parameter names from 'display' to 'dpy' to match other EGL APIs. + Version 2, 2010/03/10 + Allocated extension number 16. + [Bug 6089] Clarified that it is the back buffer of a back-buffered + surface that is mapped. + [Bug 4410] Issue 17: Reinstate EGL_MAP_PRESERVE_PIXELS_KHR attribute on + eglLockSurfaceKHR as the means of configuring whether a locked + buffer contains pixel data from the color buffer, as in + EGL_KHR_lock_surface, but, for a lockable window surface, + make EGL_SWAP_BEHAVIOR=EGL_BUFFER_PRESERVED override the effect + of that attribute. Tidy wording so that behavior, and that the + default of EGL_SWAP_BEHAVIOR must be EGL_BUFFER_PRESERVED, only + applies to lockable window surfaces, not lockable pbuffer or + pixmap surfaces. + [Bug 5923] Issue 20: A config that is lockable and renderable by + an EGL client API is now allowed. Posting restrictions are relaxed + to allow posting for a lockable surface not bound to any client + API context. + [Bug 5143] Fixed typos EGL_SURFACE_TYPE_KHR. Added summary of + changes over EGL_KHR_lock_surface. + Version 1, 2010/01/19 + [Bug 4410] Issue 17: Change to use EGL_SWAP_BEHAVIOR as the + primary means of determining whether the application wants pixels + preserved between lock/unlock cycles. + Allowed setting of EGL_SWAP_BEHAVIOR in + eglCreateWindowSurface for a lockable surface. Made the + default EGL_BUFFER_PRESERVED on a lockable surface to maintain + compatibility with the original lock surface extension. + [Bug 3192] Wording clarification to avoid accidentally suggesting + that almost all surface attributes are invariant. + [Bug 4518] Issue 14: Clarify the returned value when + EGL_MATCH_FORMAT_KHR is queried. + [Bug 4522] Issue 18: Clarify that a locked surface cannot change + size. + [Bug 4513] Issue 19: Added EGL_BITMAP_PIXEL_SIZE_KHR. + [Bug 5923] Issue 20: Must be no current context when posting + a lockable surface. In that case any eglSwapInterval setting + is ignored. Disallowed a config that is lockable and renderable + by an EGL client API. + +Revision History of original EGL_KHR_lock_surface extension + + Version 18, 2010/03/23 - Added introductory remark referring to the + EGL_KHR_lock_surface2 extension. + Version 17, 2008/10/08 - Updated status (approved as part of + OpenKODE 1.0). + Version 16, 2008/01/24 - Add issue 16 noting that mapping can fail, + and a corresponding new error condition for eglQuerySurface. + Clean up the issues list. + Version 15, 2008/01/09 - Add issue 15 noting that supporting + mixed-mode rendering is not a goal or requirement of the + extension. + Version 14, 2007/11/07 - change ARGB_8888_EXACT back to + RGBA_8888_EXACT, since the offsets are now dependent on the + endianness of the CPU. Add issue 12 describing this, and clarify + that offsets are within a 16- or 32-bit integer depending on the + format. Added issue 13 clarifying that locked buffer contents + are not affected by eglSwapBuffers, because eglSwapBuffers + cannot be issued on a mapped surface. Allow querying + EGL_MATCH_FORMAT_KHR for a config, and added related issue 14. + Version 13, 2007/05/10 - change RGBA_8888_EXACT to ARGB_8888_EXACT + to match hardware layout. + Version 12, 2007/04/06 - clarify that when EGL_MATCH_FORMAT_KHR is + EGL_DONT_CARE, it does not affect component size of selected + configs. + Version 11, 2007/04/05 - add missing KHR suffix to some tokens. + Version 10, 2007/04/05 - assign enumerant values. Add OpenKODE 1.0 + Provisional disclaimer. + Version 9, 2007/03/26 - add format tokens to "New Tokens" + section. Correct description of RGBA format tokens. + Version 8, 2007/03/26 - add issue 11 noting theoretical possibility + of EGL_BUFFER_SIZE not directly corresponding to the mapped + pixel size. Add EGL_MATCH_FORMAT_KHR attribute to + eglChooseConfig, and 565 / 8888 formats for it. + Version 7, 2007/03/25 - note in issue 5 that access to a mapped + buffer must continue to work even after a mode change. Add KHR + suffix to new functions and tokens. Remove BITMAP_PIXEL_<x>_BITS + and BITMAP_PIXEL_SIZE tokens, which duplicate information in the + EGLConfig. Add issue 10 asking whether bitmap pixel offset + attributes belong to the config, or to the surface. + Version 6, 2007/02/26 - allow EGL_CLIENT_APIS string to be empty in + implementations supporting only this extension. + Version 5, 2007/02/05 - update contributor list. Changed bit offset + queries to return LSB offset, rather than MSB offset. + Version 4, 2007/02/02 - correct extension name. Change + name of FAST_UNLOCK_BIT_KHR to OPTIMAL_FORMAT_BIT_KHR. + Replace buffer_mask parameter of eglLockSurfaceKHR with an + attribute list. Add the EGL_MAP_PRESERVE_PIXELS_KHR and + EGL_LOCK_USAGE_HINT_KHR attributes per request from Gary. Add issues + 7, 8, and 9 describing these attributes and how to support + locking subrects in a layered extension, by extending the + attribute list. + Version 3, 2007/02/01 - the implementation once again controls the + mapped buffer memory. There is no longer a separate bitmap + surface type; any type surface may potentially be mapped, using + lock/unlock semantics. + Version 2, 2006/12/22 - simplify by only supporting drawing from + client memory to EGL surface color buffers. Specify use of + OpenGL DrawPixels terminology. Change name of the extension to + EGL_KHR_draw_pixels, since there is no longer any "bitmap + surface" involved. + Version 1, 2006/12/14 - write up as formal spec language for + external review. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_lock_surface3.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_lock_surface3.txt new file mode 100644 index 0000000..f85935c --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_lock_surface3.txt @@ -0,0 +1,679 @@ +Name + + KHR_lock_surface3 + +Name Strings + + EGL_KHR_lock_surface3 + +Contributors + + Mark Callow + Gary King + Jon Leech + Marko Lukat + Alon Or-bach + Tim Renouf + +Contacts + + Jon Leech (jon 'at' alumni.caltech.edu) + +Notice + + Copyright (c) 2006-2013 The Khronos Group Inc. Copyright terms at + http://www.khronos.org/registry/speccopyright.html + +Status + + Complete. + Approved by the EGL Working Group on December 4, 2013. + +Version + + Version 4, 2014/09/17 + +Number + + EGL Extension #64 + +Dependencies + + EGL 1.4 is required. + + This extension is based on the EGL_KHR_lock_surface2 extension and + almost all language is copied from that extension. However, it is + standalone extension. The specification language has been re-based + against the EGL 1.4 Specification. + + Khronos recommends obsoleting and replacing implementations of + EGL_KHR_lock_surface2 and EGL_KHR_lock_surface with this extension as + soon as possible. + +Overview + + This extension allows mapping color buffers of EGL surfaces into the + client address space. This is useful primarily for software + rendering on low-end devices which do not support EGL client + rendering APIs, although it may be implemented efficiently on more + capable devices as well. + + This extension is functionally identical to EGL_KHR_lock_surface2, but + is intended to replace that extension. It defines a new EGL type, + EGLAttribKHR, which is an integer type guaranteed to be large enough to + hold a pointer. A new surface query, eglQuerySurface64KHR, is defined to + query surface attributes which may not fit in than EGLint, such as a + mapped surface pointer. + + The changes over EGL_KHR_lock_surface2 include: + + * EGL_KHR_lock_surface3 defines the type EGLAttribKHR and the + command eglQuerySurface64KHR. + * eglQuerySurface64KHR must be used to query the + EGL_BITMAP_POINTER_KHR property of surfaces. + +New Types + + /* + * EGLAttribKHR is a integer type used to pass arrays of attribute + * name/value pairs which may include pointer and handle attribute + * values. + */ + #include <khrplatform.h> + typedef intptr_t EGLAttribKHR; + +New Procedures and Functions + + EGLBoolean eglLockSurfaceKHR(EGLDisplay dpy, EGLSurface surface, + const EGLint *attrib_list); + EGLBoolean eglUnlockSurfaceKHR(EGLDisplay dpy, + EGLSurface surface); + EGLBoolean eglQuerySurface64KHR(EGLDisplay dpy, + EGLSurface surface, + EGLint attribute, + EGLAttribKHR *value); + +New Tokens + + Returned in the EGL_SURFACE_TYPE bitmask attribute of EGLConfigs: + + EGL_LOCK_SURFACE_BIT_KHR 0x0080 + EGL_OPTIMAL_FORMAT_BIT_KHR 0x0100 + + Accepted as an attribute name in the <attrib_list> argument of + eglChooseConfig, and the <attribute> argument of eglGetConfigAttrib: + + EGL_MATCH_FORMAT_KHR 0x3043 + + Accepted as attribute values for the EGL_MATCH_FORMAT_KHR attribute + of eglChooseConfig, and defined as possible values of that attribute + when querying it: + + EGL_FORMAT_RGB_565_EXACT_KHR 0x30C0 + EGL_FORMAT_RGBA_8888_EXACT_KHR 0x30C2 + + Accepted as attribute values for the EGL_MATCH_FORMAT_KHR attribute + of eglChooseConfig: + + EGL_FORMAT_RGB_565_KHR 0x30C1 + EGL_FORMAT_RGBA_8888_KHR 0x30C3 + + Accepted as attribute names in the <attrib_list> argument of + eglLockSurfaceKHR: + + EGL_MAP_PRESERVE_PIXELS_KHR 0x30C4 + EGL_LOCK_USAGE_HINT_KHR 0x30C5 + + Accepted as bit values in the EGL_LOCK_USAGE_HINT_KHR bitmask attribute + of eglLockSurfaceKHR: + + EGL_READ_SURFACE_BIT_KHR 0x0001 + EGL_WRITE_SURFACE_BIT_KHR 0x0002 + + Accepted by the <attribute> parameter of eglQuerySurface and + eglQuerySurface64KHR: + + EGL_BITMAP_PITCH_KHR 0x30C7 + EGL_BITMAP_ORIGIN_KHR 0x30C8 + EGL_BITMAP_PIXEL_RED_OFFSET_KHR 0x30C9 + EGL_BITMAP_PIXEL_GREEN_OFFSET_KHR 0x30CA + EGL_BITMAP_PIXEL_BLUE_OFFSET_KHR 0x30CB + EGL_BITMAP_PIXEL_ALPHA_OFFSET_KHR 0x30CC + EGL_BITMAP_PIXEL_LUMINANCE_OFFSET_KHR 0x30CD + EGL_BITMAP_PIXEL_SIZE_KHR 0x3110 + + Accepted by the <attribute> parameter of eglQuerySurface64KHR: + EGL_BITMAP_POINTER_KHR 0x30C6 + + Returns in the *<value> parameter of eglQuerySurface when + <attribute> is EGL_BITMAP_ORIGIN_KHR: + + EGL_LOWER_LEFT_KHR 0x30CE + EGL_UPPER_LEFT_KHR 0x30CF + +Additions to Chapter 2 of the EGL 1.4 Specification (EGL Operation) + + Add to the end of section 2.2.2: + + Finally, some surfaces may be <locked>, which allows the + implementation to map buffers of that surface into client memory + for use by software renderers(fn). Locked surfaces cannot be + used for any other purpose. When a locked surface is <unlocked>, + any changes to the mapped buffer(s) are reflected in the actual + graphics or system memory containing the surface. + + [fn: on implementations not supporting mapping graphics + memory, or which do not wish to take the stability and + security risks that entail, mapping may be done using + copy-out and copy-in behavior.] + +Additions to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors) + + Add to the description of the EGL_BAD_ACCESS error in section 3.1: + + "... (for example, a context is bound in another thread, or a + surface is locked). Any command accessing ..." + + Add to table 3.2 ("Types of surfaces supported by an EGLConfig") + + EGL Token Name Description + -------------------- ------------------------------------ + EGL_LOCK_SURFACE_BIT_KHR EGLConfig allows locking surfaces + EGL_OPTIMAL_FORMAT_BIT_KHR This format is considered optimal + (preferred) when locking / mapping / + unlocking is being done. + + Change the first paragraph under "Other EGLConfig Attribute + Descriptions" on p. 16: + + "EGL_SURFACE_TYPE is a mask indicating both the surface types + that can be created by the corresponding EGLConfig (the config + is said to <support> those surface types), and the optional + behaviors such surfaces may allow. The valid bit settings are + shown in Table 3.2." + + Add a new paragraph following the second paragraph of the same + section: + + "If EGL_LOCK_SURFACE_BIT_KHR is set in EGL_SURFACE_TYPE, then + a surface created from the EGLConfig may be locked, mapped into + client memory, and unlocked. Locking is described in section + 3.5.5ls. If EGL_OPTIMAL_FORMAT_BIT_KHR is set in + EGL_SURFACE_TYPE, then the surface is considered optimal (by + the implementation) from a performance standpoint when buffer + mapping is being done." + + Replace the second paragraph of section 3.3 "EGL Versioning": + + "The EGL_CLIENT_APIS string describes which client rendering APIs are + supported. It is zero-terminated and contains a space-separated list + of API names, which must include at least one of ``OpenGL'', + ``OpenGL_ES'', or OpenGL ES. If no client APIs are supported, then + the empty string is returned." + + Insert a new paragraph and table in section 3.4.1.1 "Querying + Configurations", following the description of + EGL_MATCH_NATIVE_PIXMAP on page 24: + + "If EGL_MATCH_FORMAT_KHR is specified in <attrib_list>, it must + be followed by one of the attribute values EGL_DONT_CARE, + EGL_NONE, or one of the format tokens in table + [locksurf.format]. + + When EGL_MATCH_FORMAT_KHR has the value EGL_NONE, only configs + which cannot be locked or mapped will match. Such configs must + not have the EGL_LOCK_SURFACE_BIT_KHR set in EGL_SURFACE_TYPE. + + When EGL_MATCH_FORMAT_KHR has the value EGL_DONT_CARE, it is + ignored. + + When EGL_MATCH_FORMAT_KHR has one of the values in table + [locksurf.format], only EGLConfigs describing surfaces whose + color buffers have the specified format, when mapped with + eglLockSurface, will match this attribute. In this case, the + EGL_<component>_SIZE attributes of resulting configs must agree + with the specific component sizes specified by the format." + + Specific Format Name Description + -------------------- ----------- + EGL_FORMAT_RGB_565_EXACT_KHR RGB565 fields in order from MSB to LSB within a 16-bit integer + EGL_FORMAT_RGB_565_KHR RGB565 fields in implementation-chosen order within a 16-bit integer + EGL_FORMAT_RGBA_8888_EXACT_KHR RGBA8888 fields in B, G, R, A byte order in memory + EGL_FORMAT_RGBA_8888_KHR RGBA8888 fields in implementation-chosen order within a 32-bit integer + ------------------------------------------------------------------------------------------------------ + Table [locksurf.format]: Specific formats for mapped pixels. + + Add to table 3.4 ("Default values and match critera for EGLConfig + attributes") on page 25: + + Attribute Default Selection Sort Sort + Criteria Order Priority + -------------------- ------------- --------- ----- -------- + EGL_MATCH_FORMAT_KHR EGL_DONT_CARE Exact None - + + Add EGL_MATCH_FORMAT_KHR to the last paragraph in section 3.4.1 on + p. 26, describing attributes not used for sorting EGLConfigs. + + Add a new paragraph to the end of section 3.4.3 "Querying Configuration + Attributes": + + "Querying the EGL_MATCH_FORMAT_KHR attribute results in EGL_NONE + for an EGLConfig that is not lockable, one of the "exact" formats + (EGL_FORMAT_RGB_565_EXACT_KHR, EGL_FORMAT_RGBA_8888_EXACT_KHR) + if the color buffer matches that format when mapped with + eglLockSurface, or for any other format a value that is not + EGL_NONE or EGL_DONT_CARE but is otherwise undefined. In particular, + the color buffer format matching one of the "inexact" formats + does not guarantee that that EGL_FORMAT_* value is returned." + + In section 3.5.1 "Creating On-Screen Rendering Surfaces", add to the + second paragraph on p. 28 listing attributes that can be set in + attrib_list: + + "<attrib_list> specifies a list of attributes ... and + EGL_SWAP_BEHAVIOR." + + and add preceding the paragraph starting "EGL_VG_COLORSPACE specifies + ..." on p. 28: + + "EGL_SWAP_BEHAVIOR specifies the initial value of the + EGL_SWAP_BEHAVIOR surface attribute (section 3.5.6), and is thus + either EGL_BUFFER_PRESERVED or EGL_BUFFER_DESTROYED. This setting + of EGL_SWAP_BEHAVIOR at surface creation time is supported only + for a lockable surface, i.e. where the EGLConfig has + EGL_LOCK_SURFACE_BIT_KHR set in EGL_SURFACE_TYPE. + + "For such a lockable surface, whether it is possible to change + the EGL_SWAP_BEHAVIOR attribute after surface creation is + determined by EGL_SWAP_BEHAVIOR_PRESERVED_BIT in the + EGL_SURFACE_TYPE EGLConfig attribute." + + Add a new section following the current section 3.5.5: + + "3.5.5ls Locking and Mapping Rendering Surfaces + + A rendering surface may be <locked> by calling + + EGLBoolean eglLockSurfaceKHR(EGLDisplay dpy, + EGLSurface surface, + const EGLint *attrib_list); + + While a surface is locked, only two operations can be performed + on it. First, a surface attribute may be queried using + the query commands in section 3.5.6. This includes the case of + querying EGL_BITMAP_POINTER_KHR, which causes the surface to be + <mapped> (if not already mapped) and gives a pointer into client + memory corresponding to the memory of the mapped buffer. Second, + the surface may be unlocked. Any attempts to use a locked surface + in other EGL APIs will fail and generate an EGL_BAD_ACCESS error. + + While a surface is locked, its dimensions (the values of the EGL_WIDTH + and EGL_HEIGHT surface attributes) do not change. They may change + at any other time, therefore an application must query these + attributes <after> the call to eglLockSurfaceKHR to ensure that it has + the correct size of the mapped buffer. + + <attrib_list> specifies additional parameters affecting the locking + operation. The list has the same structure as described for + eglChooseConfig. Attributes that may be defined are shown in table + [locksurf.attr], together with their default values if not specified + in <attrib_list>, and possible values which may be specified for + them in <attrib_list>. + + Attribute Name Type Default Value Possible Values + ----------------------- ------- ------------- ------------------------- + EGL_MAP_PRESERVE_PIXELS_KHR boolean EGL_FALSE EGL_TRUE / EGL_FALSE + EGL_LOCK_USAGE_HINT_KHR bitmask EGL_READ_SURFACE_BIT_KHR | Any combination of + EGL_WRITE_SURFACE_BIT_KHR EGL_READ_SURFACE_BIT_KHR + and EGL_WRITE_SURFACE_BIT_KHR + -------------------------------------------------------------- + Table [locksurf.attr]: eglLockSurfaceKHR attribute names, + default values, and possible values. + + On failure, the surface is unaffected and eglLockSurfaceKHR + returns EGL_FALSE. An EGL_BAD_ACCESS error is generated if any + of these condition, are true: + + * <surface> was created with an EGLConfig whose + EGL_SURFACE_TYPE attribute does not contain + EGL_LOCK_SURFACE_BIT_KHR. + * <surface> is already locked. + * Any client API is current to <surface>. + + An EGL_BAD_ATTRIBUTE error is generated if an attribute or + attribute value not described in table [locksurf.attr] is + specified. + + Mapping Buffers of a Locked Surface + ----------------------------------- + + The color buffer of a locked surface can be <mapped> by calling + eglQuerySurface64KHR (see section 3.5.6) with <attribute> + EGL_BITMAP_POINTER_KHR(fn). The query returns a pointer to a + buffer in client memory corresponding to the color buffer of + <surface>. In the case of a back-buffered surface, color buffer + refers to the back buffer. + + [fn: "mapped" only means that the pointer returned is + intended to *correspond* to graphics memory. Implementation + are not required to return an actual pointer into graphics + memory, and often will not.] + + + The contents of the mapped buffer are initially undefined(fn) + unless either the EGL_MAP_PRESERVE_PIXELS_KHR attribute of + eglLockSurfaceKHR is set to EGL_TRUE, or (for a window surface) + the EGL_SWAP_BEHAVIOR surface attribute is set to + EGL_BUFFER_PRESERVE, in which case the contents + of the buffer are taken from the contents of <surface>'s color + buffer. The default value of EGL_MAP_PRESERVE_PIXELS_KHR is + EGL_FALSE. + + [fn: In order to avoid pipeline stalls and readback delays on + accelerated implementations, we do not mandate that the + current contents of a color buffer appear when it's mapped + to client memory, unless the EGL_MAP_PRESERVE_PIXELS_KHR + flag is set or (for a window surface) EGL_SWAP_BEHAVIOR is + set to EGL_BUFFER_PRESERVE. Applications using mapped + buffers which are not + preserved must write to every pixel of the buffer before + unlocking the surface. This constraint is considered + acceptable for the intended usage scenario (full-frame + software renderers). Such an application may lock-render-unlock + multiple times per frame (i.e. per eglSwapBuffers) by setting + EGL_MAP_PRESERVE_PIXELS_KHR to EGL_TRUE for the second and + subsequent locks. + + Note that EGL_SWAP_BEHAVIOR also controls whether the color + buffer contents are preserved over a call to eglSwapBuffers.] + + The EGL_LOCK_USAGE_HINT_KHR attribute of eglLockSurfaceKHR is a + bitmask describing the intended use of the mapped buffer. If the + mask contains EGL_READ_SURFACE_BIT_KHR, data will be read from + the mapped buffer. If the mask contains + EGL_WRITE_SURFACE_BIT_KHR, data will be written to the mapped + buffer. Implementations must support both reading and writing to + a mapped buffer regardless of the value of + EGL_LOCK_USAGE_HINT_KHR, but performance may be better if the + hint is consistent with the actual usage of the buffer. The + default value of EGL_LOCK_USAGE_HINT_KHR hints that both reads + and writes to the mapped buffer will be done. + + Other attributes of the mapped buffer describe the format of + pixels it contains, including its pitch (EGL_BITMAP_PITCH_KHR), + origin (EGL_BITMAP_ORIGIN_KHR), and the bit location of each color + component within a pixel (EGL_BITMAP_PIXEL_x_OFFSET_KHR). These + attributes may be queried using eglQuerySurface, and are described + in more detail in section 3.5.6. + + The EGL_BITMAP_POINTER_KHR and EGL_BITMAP_PITCH_KHR attributes + of a locked surface may change following successive calls to + eglLockSurfaceKHR(fn), so they must be queried each time a + buffer is mapped. Other attributes of a mapped buffer (listed in + the paragraph above) are invariant and need be queried only once + following surface creation. + + [fn: The pointer and pitch of a mapped buffer may change due + to display mode changes, for example.] + + Mapping will not suceed if client memory to map the surface into + cannot be allocated. In this case, calling eglQuerySurface64KHR + with <attribute> EGL_BITMAP_POINTER_KHR will fail and generate an + EGL error. + + Unlocking Surfaces + ------------------ + + A rendering surface may be <unlocked> by calling + + EGLBoolean eglUnlockSurfaceKHR(EGLDisplay dpy, + EGLSurface surface); + + Any mapped buffers of <surface> become unmapped following + eglUnlockSurfaceKHR. Any changes made to mapped buffers of + <surface> which it was locked are reflected in the surface after + unlocking(fn). + + [fn: This language enables implementations to either map + video memory, or copy from a separate buffer in client + memory.] + + If <surface> was created with an EGLConfig whose + EGL_SURFACE_TYPE attribute contains EGL_OPTIMAL_FORMAT_BIT_KHR, + then the surface is considered optimal (by the implementation) + from a performance standpoint when buffer mapping is being + done(fn). + + [fn: This often means that the format of all mapped buffers + corresponds directly to the format of those buffers in + <surface>, so no format conversions are required during + unmapping. This results in a high-performance software + rendering path. But "optimal format" is really just a hint + from EGL that this config is preferred, whatever the actual + reason.] + + On failure, eglUnlockSurfaceKHR returns EGL_FALSE. An + EGL_BAD_ACCESS error is generated if any of these conditions are + true: + + * <surface> is already unlocked. + * A display mode change occurred while the surface was locked, + and the implementation was unable to reflect mapped buffer + state(fn). In this case, <surface> will still be unlocked. + However, the contents of the previously mapped buffers of + <surface> become undefined, rather than reflecting changes + made in the mapped buffers in client memory. + + [fn: Usually this may only occur with window surfaces which + have been mapped. EGL does not have an event mechanism to + indicate display mode changes. If such a mechanism exists + (using native platform events or the OpenKODE event system), + applications should respond to mode changes by regenerating + all visible window content, including re-doing any software + rendering overlapping the mode change.]" + + Modify table 3.5 ("Queryable surface attributes and types") + to add a new column "64-bit". Add new entries to table 3.5: + + Attribute Type Description 64-bit + --------- ------- -------------------------- --------- + EGL_BITMAP_POINTER_KHR pointer Address of a mapped color [checked] + buffer (MCB). + EGL_BITMAP_PITCH_KHR integer Number of bytes between - + the start of adjacent rows + in an MCB. + EGL_BITMAP_ORIGIN_KHR enum Bitmap origin & direction - + EGL_BITMAP_PIXEL_x_- integer Bit location of each color - + OFFSET_KHR buffer component within a + pixel in an MCB. + EGL_BITMAP_PIXEL_- integer Bits per pixel - + SIZE_KHR + + All previously existing entries in table 3.5 are given a "-" entry in + the new "64-bit" column. + + In the description of eglSurfaceAttrib properties that can be set in + section 3.5.6, add to the description of EGL_SWAP_BEHAVIOR: + + "It <attribute> is EGL_SWAP_BEHAVIOR ... The value of + EGL_SWAP_BEHAVIOR also affects the semantics of eglLockSurfaceKHR + for a lockable window surface. See section 3.5.6." + + And modify the paragraph descirbing the initial value of + EGL_SWAP_BEHAVIOR: + + "The initial value of EGL_SWAP_BEHAVIOR is chosen by the + implementation, except for a lockable window surface (i.e. where the + EGLConfig has both EGL_LOCK_SURFACE_BIT_KHR and EGL_WINDOW_BIT set in + EGL_SURFACE_TYPE). For a lockable window surface the default is + EGL_BUFFER_PRESERVED, but it may be overridden by specifying + EGL_SWAP_BEHAVIOR to eglCreateWindowSurface." + + Add the prototype of the new surface query function immediately + following the prototype for eglQuerySurface on p. 37: + + EGLBoolean eglQuerySurface64KHR(EGLDisplay dpy, + EGLSurface surface, + EGLint attribute, + EGLAttribKHR *value) + + Modify the following paragraph: + + "eglQuerySurface and eglQuerySurface64KHR return in <value> the + value of <attribute> for <surface>. <attribute> must be set to one + of the attributes in table 3.5. Attributes whose ``64-bit'' entry + is checked in table 3.5 may only be queried with + eglQuerySurface64KHR." + + Add to the description of eglQuerySurface properties on p. 38: + + "Properties of a bitmap surface which may be queried include: + * EGL_BITMAP_POINTER_KHR, which maps the color buffer of a + locked surface and returns the address in client memory of + the mapped buffer. + * EGL_BITMAP_PITCH_KHR, which returns the number of bytes + between successive rows of a mapped buffer. + * EGL_BITMAP_ORIGIN_KHR, which describes the way in which a + mapped color buffer is displayed on the screen. Possible + values are either EGL_LOWER_LEFT_KHR or EGL_UPPER_LEFT_KHR, + indicating that the first pixel of the mapped buffer + corresponds to the lower left or upper left of a visible + window, respectively. + * EGL_BITMAP_PIXEL_<x>_OFFSET_KHR, which describes the bit + location of the least significant bit of each color + component of a pixel within a mapped buffer. <x> is one of + RED, GREEN, BLUE, ALPHA, or LUMINANCE. + + The offset for a color component should be treated as the + number of bits to left shift the component value to place it + within a n-bit + integer containing the pixel, where n is the number of bits + per pixel. If a color + component does not exist in the mapped buffer, then the bit + offset of that component is zero. If a color component + does exist but not in a single contiguous range of bits, + then the value of the attribute is EGL_UNKNOWN. + + * EGL_BITMAP_PIXEL_SIZE_KHR, which returns the number of bits + per pixel, assumed to be least significant leftmost if there + are multiple pixels per byte. The attribute takes the value + EGL_UNKNOWN if this assumption is not true, or if pixels are not + laid out left to right in memory (for example pairs of 16-bit + pixels are swapped in memory). + + In addition to these attributes, the number of bits for each + color component of a pixel within a mapped buffer is obtained by + querying the EGL_<x>_SIZE attribute of the EGLConfig used to + create the surface, where <x> is <x> is one of RED, GREEN, BLUE, + ALPHA, or LUMINANCE. + + Querying EGL_BITMAP_POINTER_KHR and EGL_BITMAP_PITCH_KHR is only + allowed when <surface> is mapped (see section 3.5.5ls). Querying + either of these attributes for the first time after calling + eglLockSurfaceKHR causes the color buffer of the locked surface + to be mapped. Querying them again before unlocking the surface + will return the same values as the first time. However, after + calling eglUnlockSurfaceKHR, these properties become undefined. + After a second call to eglLockSurfaceKHR, these properties may + again be queried, but their values may have changed. + + Other properties of the mapped color buffer of a surface + (in the list above) are + invariant, and need be queried only once following surface + creation. If <surface> was created with an EGLConfig whose + EGL_SURFACE_TYPE attribute does not contain + EGL_LOCK_SURFACE_BIT_KHR, queries of EGL_BITMAP_ORIGIN_KHR, + EGL_BITMAP_PIXEL_<x>_OFFSET_KHR and EGL_BITMAP_PIXEL_SIZE_KHR + return undefined values." + + Add to the description of eglQuerySurface errors in the last + paragraph of section 3.5.6: + + "eglQuerySurface and eglQuerySurface64KHR return EGL_FALSE on + failure ... If <attribute> is one of the attributes whose + ``64-bit'' entry is checked in table 3.5, then an + EGL_BAD_ATTRIBUTE error is generated if eglQuerySurface is called; + only eglQuerySurface64KHR is allowed for such attributes. If + <attribute> is either EGL_BITMAP_POINTER_KHR or + EGL_BITMAP_PITCH_KHR, and either <surface> is not locked using + eglLockSurfaceKHR, or <surface> is locked but mapping fails, then + an EGL_BAD_ACCESS error is generated. " + + In section 3.9.3 Posting Semantics on page 53, append to the first + paragraph: + + "<surface> must be bound to the calling thread's current context + ... This restriction does not apply to lockable surfaces; for such + a surface, eglSwapBuffers and eglCopyBuffers may be called for a + surface not bound to any client API context(fn). + + [fn: Normally this would only be done when using methods other + than client API rendering to specify the color buffer contents, + such as software rendering to a locked surface.]" + + Replace the second paragraph ("If <dpy> and <surface> ... not be + executed until posting is completed.") with: + + "If <surface> is bound to a current client API context for the calling + thread, eglSwapBuffers and eglCopyBuffers perform an implicit flush + operation on the context (glFlush for an OpenGL or OpenGL ES context, + vgFlush for an OpenVG context). Subsequent client API commands can be + issued immediately, but will not be executed until posting is + completed. + + If <surface> is current to a client API context in any thread other + than the calling thread, eglSwapBuffers and eglCopyBuffers will fail. + + Append following the prototype for eglSwapInterval: + + "specifies the minimum number of video frame periods ... The swap + interval has no effect on eglSwapBuffers for a surface not bound + to a current client API context." + + In 3.9.4 Posting Errors, change the first paragraph: + + "eglSwapBuffers and eglCopyBuffers return EGL_FALSE on failure. If + <surface> is not a valid EGL surface, an EGL_BAD_SURFACE error is + generated. If <surface> is bound to a current context in a thread + other than the calling thread, an EGL_BAD_SURFACE error is + generated." If <target> is not a valid native pixmap handle ..." + +Sample Code + + None + +Conformance Tests + + None yet + +Issues + + The issues lists of EGL_KHR_lock_surface and EGL_KHR_lock_surface2 also + apply to this extension. In addition, issues related only to the reason + for defining the EGLAttribKHR and interfaces using that type may be + found in issues 1-3 of the EGL_KHR_cl_event2 extension specification. + + 1) Is this extension backwards-compatible with EGL_KHR_lock_surface2? + + RESOLVED: No. Querying the bitmap pointer must be done with the new + command eglQuerySurface64KHR when using this extension, to guide + developers down the right path even when writing 32-bit code. + + However, if both lock_surface2 and this extension are supported, it is + possible to query the bitmap pointer using older calls, with the risk + that executing such code on a 64-bit platform will probably fail. + +Revision History + + Version 4, 2014/09/17 (Jon Leech) - Fix bogus return type for + eglQuerySurface64KHR in New Functions section. + + Version 3, 20130/12/04 (Jon Leech) - Minor cleanup for public release. + Change formal parameter names from 'display' to 'dpy' to match other EGL + APIs. + + Version 2, 20130/10/16 (Jon Leech) - add Dependencies and Overview text + noting that this extension obsoletes and should replace + EGL_KHR_lock_surface2 and EGL_KHR_lock_surface. + + Version 1, 2013/10/15 - Branched from approved EGL_KHR_lock_surface2. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_mutable_render_buffer.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_mutable_render_buffer.txt new file mode 100644 index 0000000..9b72af4 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_mutable_render_buffer.txt @@ -0,0 +1,325 @@ +Name + + KHR_mutable_render_buffer + +Name Strings + + EGL_KHR_mutable_render_buffer + +Contributors + + Alon Or-bach + John Carmack + Cass Everitt + Michael Gold + James Jones + Jesse Hall + Ray Smith + +Contact + + Alon Or-bach, Samsung Electronics (alon.orbach 'at' samsung.com) + +IP Status + + No known claims. + +Notice + + Copyright (c) 2016 The Khronos Group Inc. Copyright terms at + http://www.khronos.org/registry/speccopyright.html + +Status + + Approved by the EGL Working Group on January 28, 2016 + Ratified by the Khronos Board of Promoters on March 11, 2016 + +Version + + Version 12, January 29, 2016 + +Number + + EGL Extension #96 + +Extension Type + + EGL display extension + +Dependencies + + EGL 1.2 or later is required. + + Written based on the EGL 1.5 specification (August 27, 2014). + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted as a new value for the EGL_SURFACE_TYPE EGLConfig attribute: + + EGL_MUTABLE_RENDER_BUFFER_BIT_KHR 0x00001000 + +Overview + + The aim of this extension is to allow toggling of front-buffer rendering + for window surfaces after their initial creation. + + This allows for implementations to switch between back-buffered and single- + buffered rendering without requiring re-creation of the surface. It is not + expected for toggling to be a frequent event. + + This extension does not guarantee when rendering results appear on-screen. + To avoid incorrect results, applications will need to use mechanisms not + included in this extension to synchronize rendering with the display. This + functionality is not covered by this extension, and vendors are encouraged + to provide guidelines on how this is achieved on their implementation. + +Add to the list of supported tokens for EGL_SURFACE_TYPE in section 3.4 +"Configuration Management", page 23: + + If EGL_MUTABLE_RENDER_BUFFER_BIT_KHR is set in EGL_SURFACE_TYPE, then the + EGL_RENDER_BUFFER attribute of a surface can be toggled between front + buffer and back buffer rendering using eglSurfaceAttrib (see section + 3.5.6). + +Add to the list of supported tokens for eglSurfaceAttrib in section 3.5.6 +"Surface Attributes", page 43: + + If attribute is EGL_RENDER_BUFFER, then value specifies whether to render + to a back buffer by specifying EGL_BACK_BUFFER, or directly to the front + buffer by specifying EGL_SINGLE_BUFFER. The change to which buffer is + rendered to takes effect at the subsequent eglSwapBuffers call, as + described in section 3.10.1.2, and changes are considered pending up until + that point. + + If attribute is EGL_RENDER_BUFFER, and the EGL_SURFACE_TYPE attribute of + the EGLConfig used to create surface does not contain + EGL_MUTABLE_RENDER_BUFFER_BIT_KHR, or the windowing system is unable to + support the requested rendering mode, an EGL_BAD_MATCH error is generated + and the EGL_RENDER_BUFFER state is left unchanged. + +Modify the following sentence in section 3.5.6 "Surface Attributes", page 45: + + Querying EGL_RENDER_BUFFER returns the buffer which client API rendering + is requested to use. For a window surface, this is the attribute value + specified when the surface was created or last set via eglSurfaceAttrib. + +Modify the third bullet describing eglQueryContext in section 3.7.4, page 63: + + If the context is bound to a window surface, then either EGL_BACK_BUFFER + or EGL_SINGLE_BUFFER may be returned. The value returned depends on + both the buffer requested by the setting of the EGL_RENDER_BUFFER property + of the surface (which may be queried by calling eglQuerySurface - see + section 3.5.6), and on the client API (not all client APIs support + single-buffer rendering to window surfaces). Some client APIs allow control + of whether rendering goes to the front or back buffer for back buffered + surfaces. This client API-specific choice is not reflected in the returned + value, which only describes the buffer that will be rendered to by default + if not overridden by the client API. If the EGL_RENDER_BUFFER attribute of + a surface is changed by calling eglSurfaceAttrib, the value returned by + eglQueryContext will change once eglSwapBuffers is called, as described in + section 3.10.1.2. + +Modify the following sentence in section 3.10.1 "Posting to a Window", page 79: + + If surface is a single-buffered window, pixmap, or pbuffer surface for which + there is a pending change to the EGL_RENDER_BUFFER attribute, eglSwapBuffers + performs an implicit flush operation on the context and effects the + attribute change. If surface is a single-buffered window, pixmap, or pbuffer + surface for which there is no pending change to the EGL_RENDER_BUFFER + attribute, eglSwapBuffers has no effect. + +Add a new section 3.10.1.2 "Handling of render buffer attribute changes" + + If there is a pending change to the EGL_RENDER_BUFFER attribute of a + surface, as described in section 3.5.6, the change to which buffer is + rendered to takes effect at the subsequent eglSwapBuffers call. + + When switching to single-buffered from back-buffered rendering and the + surface's EGL_SWAP_BEHAVIOR attribute is set to EGL_BUFFER_DESTROYED, the + back buffers are considered to be undefined after calling eglSurfaceAttrib. + Only draw calls after this eglSurfaceAttrib call are guaranteed to affect + the back buffer content. If it is set to EGL_BUFFER_PRESERVED, the back + buffer contents are unaffected. At the next eglSwapBuffers call, the back + buffer is posted as the front buffer. After this, any draw calls take + effect on the front buffer. + + When switching to back-buffered from single-buffered rendering, any draw + calls up until the next eglSwapBuffers call continues to affect the front + buffer, and this initial eglSwapBuffers call does not affect the window + content. The back buffer is considered to be undefined at this point, no + matter what the EGL_SWAP_BEHAVIOR attribute of the surface is set to. Once + the pending change has taken place during this initial eglSwapBuffers call, + further rendering affects the back buffer. + + If the EGL_RENDER_BUFFER attribute is changed twice or more in succession + without new content rendered to the surface as described above, undefined + content may appear on-screen. + + +Issues + + 1) When should the switch between rendering modes occur? + + RESOLVED: The switch should take effect after the subsequent eglSwapBuffers + call. The operation of the subsequent eglSwapBuffers call is according to + the current state (i.e the state before the eglSurfaceAttrib call), not the + pending state. + + When switching to EGL_SINGLE_BUFFER, the current state is EGL_BACK_BUFFER + and therefore eglSwapBuffers posts the current back buffer. After this any + rendering takes effect on the front buffer. + + When switching to EGL_BACK_BUFFER, the current state is EGL_SINGLE_BUFFER + and therefore eglSwapBuffers only flushes the current context. After this + any rendering takes effect on the back buffer. + + 2) If this extension is advertised, should all surface configurations with + EGL_WINDOW_BIT in EGL_SURFACE_TYPE be required to support it? + + RESOLVED: No. Add a config bit to indicate support for EGL_RENDER_BUFFER + toggling. If toggle performed when not supported, EGL_BAD_MATCH error is + generated. + + 3) How often do we expect the switch between single and back buffering to + occur? + + RESOLVED: It is not expected for the toggle to be a frequent call. For + example, we expect it to be called once when enabling a VR accessory and + once when disabling it. + + 4) Do we need to reword section 3.7.4 (page 63)? + + RESOLVED: Yes. Modified to explain how some client APIs can still override + the behavior and what value eglQueryContext is expected to return for + EGL_RENDER_BUFFER. + + 5) Why not enable this via the client API, like OpenGL does via glDrawBuffer? + + RESOLVED: This would not be possible on some platforms, where the swap chain + is controlled via EGL. + + 6) Is this extension a client or display extension? + + RESOLVED: This is a display extension. + + 7) What state are back buffers after switching between single and back buffered + rendering? + + RESOLVED: This is as set out in section 3.10.1.2. + + 8) What guarantees of an onscreen update does this extension make? + + RESOLVED: This extension does not make any additional guarantees to the + equivalent behavior of a window surface with EGL_RENDER_BUFFER set to the + same value at creation of the surface. When a surface is single-buffered, + any API call which is specified to explicitly or implicitly flush is + expected to affect the on-screen content in finite time, but no timing + guarantees are provided. + + It is recommended that if ancillary buffers are not required, they are + invalidated before flushing to reduce unnecessary memory transfers on some + implementations (e.g. by calling glInvalidateFramebuffer for OpenGL ES). + + 9) Should an implicit flush occur when eglSwapBuffers is called on a + single-buffered surface? + + RESOLVED: Only when there is a pending EGL_RENDER_BUFFER change which will + be affected by this eglSwapBuffers call. Contexts must be flushed when + changing render targets. + + 10) How does toggling EGL_RENDER_BUFFER affect client APIs? + + RESOLVED: Changing the value of EGL_RENDER_BUFFER should result in the same + behavior in client APIs as binding a window surface with that mode to the + current context. For example, in OpenGL, it is akin to switching from a + drawable with a back buffer and front buffer to a drawable with only a + front buffer, or vice versa. + + Note the effect of such an operation on the draw buffer and framebuffer + completeness, if applicable, is client API specific. OpenGL ES applications + will see no change and will be able to continue rendering without updating + the draw buffer, as OpenGL ES exposes only one renderable surface, + regardless of single or back-buffered drawables. OpenGL applications should + update the current draw buffer using glDrawBuffers() or similar commands to + ensure rendering targets the correct buffer after toggling + EGL_RENDER_BUFFER. + + 11) How should interaction between multiple window surfaces be handled? + + RESOLVED: This is left to platform vendors to define. Implementations may + choose to restrict use of front buffer rendering to forbid interaction + between multiple windows, or provide a buffer that is read by the display + or compositing hardware but not the final composited results to prevent + security concerns or undefined content. + + 12) How should the name of the extension be? + + RESOLVED: EGL_KHR_mutable_render_buffer + + +Revision History + +#12 (Jon Leech, January 29, 2016) + - Assign enumerant value + - Update Status block + +#11 (Alon Or-bach, January 28, 2016) + - Updated issue 1 to be consistent with new resolution to issue 9 + - Marked issues 7, 8 and 10 as resolved + +#10 (Alon Or-bach, January 28, 2016) + - Renamed extension to EGL_KHR_mutable_render_buffer, resolving issue 12 + - Updates issue 7 resolution to just refer to spec + - Cleaned up section 3.10.1.2 wording + - Added wording to overview on lack of guarantee of rendering results + +#9 (Alon Or-bach, January 22, 2016) + - Marked issues 1, 9 and 11 as resolved + - Updated issue 4 to reflect previously agreed wording for section 3.7.4 + - Updated issue 8 to indicate no new flush guarantees made by this extension + - New proposed resolution to issue 7 and modified section 3.10.1.2 to vary + whether back buffer content are undefined based on swap behavior + - Updated issue 10 with wording to explain differing client API behaviors + - Added error condition for windowing systems unable to support a requested + rendering mode in section 3.5.6 + - New proposed resolution to issue 12 for extension naming + - Minor updates to wording (attribute instead of mode, overview phrasing) + +#8 (Ray Smith, January 5, 2016) + - Revert issue 1 resolution to that in revision 6, adding wording to section + 3.10.1 to make eglSwapBuffers effect pending state changes even for single + buffered surfaces. + +#7 (Alon Or-bach, December 17, 2015) + - New proposed resolution to issue 1 (explicit flush as update boundary), + updating the wording of 3.5.6, 3.7.4 3.10.1.2 to reflect this + - Added new issue 11 to reflect concerns about interactions between multiple + windows + - Added new issue 12 to determine extension name + +#6 (Alon Or-bach, November 11, 2015) + - Resolved issue 6 and proposed resolution to issue 4 (section 3.7.4) + - Added new issue 10 with proposed resolution + +#5 (Alon Or-bach, May 12, 2015) + - Updated section 3.10.1.2, changed resolution to issue 9 + +#4 (Alon Or-bach, April 15, 2015) + - Added issue 9 and a typo fix + +#3 (Alon Or-bach, April 09, 2015) + - Added issue 7 and 8, wording on what content expected during mode switch + +#2 (Alon Or-bach, March 09, 2015) + - Cleanup, rename to XXX_set_render_buffer_mode + +#1 (Alon Or-bach, March 04, 2015) + - Initial draft diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_no_config_context.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_no_config_context.txt new file mode 100644 index 0000000..4493b20 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_no_config_context.txt @@ -0,0 +1,261 @@ +Name + + KHR_no_config_context + +Name Strings + + EGL_KHR_no_config_context + +Contributors + + Etay Meiri + Alon Or-bach + Jeff Vigil + Ray Smith + Michael Gold + James Jones + Daniel Kartch + Adam Jackson + Jon Leech + +Contact + + Etay Meiri (etay.meiri 'at' intel.com) + +IP Status + + No known IP claims. + +Status + + Approved by the EGL Working Group on April 27, 2016 + + Approved by the Khronos Board of Promoters on July 22, 2016 + +Version + + Version 9, 2016/09/08 + +Number + + EGL Extension #101 + +Extension Type + + EGL display extension + +Dependencies + + EGL 1.4 is required. This extension is written against the EGL 1.5 + Specification of August 27, 2014. + + Some of the capabilities of these extensions are only available when + creating OpenGL or OpenGL ES contexts supporting specific versions or + capabilities. All such restrictions are documented in the body of this + extension specification. + +Overview + + Modern GPUs allow contexts to render to almost any combination of + supported color and auxiliary buffer formats. Traditionally EGL context + creation is done with respect to an EGLConfig specifying buffer formats, + and constrains contexts to only work with surfaces created with a + "compatible" config. + + This extension allows creation of GL & ES contexts without specifying an + EGLConfig. + +New Procedures and Functions + + None. + +New Tokens + + Accepted as the <config> parameter of eglCreateContext: + + EGL_NO_CONFIG_KHR ((EGLConfig)0) + +Additions to the EGL 1.5 Specification + + Modify the 3rd paragraph of section 2.2 "Rendering Contexts and + Drawing Surfaces": + + "Surfaces and contexts are both created with respect to an EGLConfig. + The EGLConfig describes the depth of the color buffer components and + the types, quantities and sizes of the ancillary buffers (i.e., the + depth, multisample, and stencil buffers). It is also possible to + create a context without using an EGLConfig, by specifying relevant + parameters at creation time (see sections 3.5 and 3.7, respectively)." + + Modify the sixth paragraph of section 2.2: + + "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 context and surface are compatible if they were + created with respect to the same EGLDisplay, and if either of the + following sets of conditions apply: + + * The context was created without an EGLConfig. Such contexts match + any valid EGLSurface. + + or, + + * The context and surface support the same type of color buffer + (RGB or luminance). + + * They have color buffers and ancillary buffers of the same depth. + + ... replicate remainder of this bullet point ... + + As long as the compatibility constraint and the address space ..." + + Insert a new paragraph after paragraph 3 in section 3.7.1 "Creating + Rendering Contexts" on p. 51: + + "<config> specifies an EGLConfig defining properties of the context. If + <config> is EGL_NO_CONFIG_KHR, the resulting context is said to be + created <without reference to an EGLConfig>. In this case, the context + must pass the required conformance tests for that client API and must + support being made current without a rendering surface. Such support is + guaranteed for OpenGL ES 2.0 implementations supporting the + GL_OES_surfaceless_context extension, OpenGL ES 3.0 and later versions + of OpenGL ES, and OpenGL 3.0 and later versions of OpenGL. Support for + other versions and other client APIs is implementation dependent." + + Replace the EGL_BAD_CONFIG error for eglCreateContext on p. 56, and add + a new errors: + + "* An EGL_BAD_CONFIG error is generated if <config> is neither + EGL_NO_CONFIG_KHR nor a valid <config>. + + * An EGL_BAD_MATCH error is generated if <config> is EGL_NO_CONFIG_KHR, + and the requested client API type and version do not support being + made current without a rendering surface. + + * An EGL_BAD_MATCH error is generated if <config> is EGL_NO_CONFIG_KHR, + and the implementation does not support the requested client API and + version." + + Modify the first error for eglMakeCurrent in the list on p. 58: + + "* An EGL_BAD_MATCH error is generated if <draw> or <read> are not + compatible with <ctx>, as described in section 2.2." + + Modify the description of eglQueryContext in section 3.7.4 on p. 63: + + "Querying EGL_CONFIG_ID returns the ID of the EGLConfig with respect + to which the context was created, or zero if created without + respect to an EGLConfig." + +Errors + + As described in the body of the extension above. + +Conformance Tests + + None + +Sample Code + + None + +Dependencies On EGL 1.4 + + If implemented on EGL 1.4, interactions with EGL 1.5-specific features + are removed. + +Issues + + 1) Should non-conformant no-config contexts be allowed to be created? + + RESOLVED: No. We are not encouraging non-conformant contexts. + + 2) Are no-config contexts constrained to those GL & ES implementations + which can support them? + + RESOLVED: Yes. ES2 + OES_surfaceless_context, ES 3.0, and GL 3.0 all + support binding a surface without a context. This implies that they + don't need to know surface attributes at context creation time. + + 3) For an OpenGL or OpenGL ES context created with no config, what is the + initial state of GL_DRAW_BUFFER and GL_READ_BUFFER for the default + framebuffer? + + RESOLVED: This is an implementation detail rather than a spec issue. + glReadBuffer/glDrawBuffer have undefined results if called without a + current context. The GL_DRAW_BUFFER and GL_READ_BUFFER are set on the + first eglMakeCurrent call and can be updated in glReadBuffer and + glDrawBuffers calls after that. Therefore, the attribute value with + which the context is created is irrelevant from the point of view of the + spec and is left up to the implementation. + + 4) Can eglMakeCurrent alter the GL_DRAW_BUFFER and GL_READ_BUFFER state of + the default framebuffer? + + RESOLVED: Yes, but only on the first call to eglMakeCurrent. The two + relevant excerpts from the OpenGL 3.2 Core Profile Specification. + From Section 4.2.1 Selecting a Buffer for Writing: + + For the default framebuffer, in the initial state the draw buffer + for fragment color zero is BACK if there is a back buffer; FRONT if + there is no back buffer; and NONE if no default framebuffer is + associated with the context. + + From 4.3.3 Pixel Draw/Read State: + + For the default framebuffer, in the initial state the read buffer is + BACK if there is a back buffer; FRONT if there is no back buffer; + and NONE if no default framebuffer is associated with the context. + + Based on the above excerpts on the first call to eglMakeCurrent the + GL_DRAW_BUFFER and GL_READ_BUFFER are set to: GL_NONE if the surface is + NULL, GL_BACK if the surface is double buffered, GL_FRONT if the surface + is single buffered. Following calls to glReadBuffer and glDrawBuffers + change the GL_DRAW_BUFFER and GL_READ_BUFFER attributes and these values + persist even when the application change the current context. + + 5) Should we add an eglCreateGenericContext which is the same as + eglCreateContext but without the config parameter? + + RESOLVED: No. + + 6) Can no-config contexts share state with contexts that has a config? + + RESOLVED: Yes. This extension implies that the dependency of the context + on the config is quite minimal so no restriction w.r.t sharing should be + enforced. + + 7) What surface types can be made current with a no-config context? + + RESOLVED: any surface type supported by the implementation can be made + current with a no-config context. + +Revision History + + Version 9. 2016/09/08 (Jon Leech) - Modify cast of EGL_NO_CONFIG_KHR to + (EGLConfig) per bug 15473. + + Version 8. 2016/08/09 (Jon Leech) - Assign extension number, reflow + text, and publish. + + Version 7. 2016/05/09 - Recorded vote at working group and sent to + Promoters for ratification. + + Version 6. 2016/04/27 - Updated issue #6. Added an EGL_BAD_MATCH case to + eglCreateContext. + + Version 5. 2016/04/20 - White space cleanup. Added extension type. + Cleaned up issues #1, #2, #4 and #6. + + Version 4. 2016/03/24 - Added a list of contributers. Fixed resolution + of issue #3 and #4. + + Version 3. 2016/03/10 - removed restriction to window surfaces only. + Removed comment on EGL_RENDERABLE_TYPE. Resolved issues 3 and 4. Added + issue 7. + + Version 2, 2016/03/09 - querying EGL_CONFIG_ID on a context created + without a config returns zero. Contexts created without a config can + share state with contexts which were created with a config. + + Version 1, 2016/01/27 - branch from draft EGL_KHR_no_config specification. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_partial_update.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_partial_update.txt new file mode 100644 index 0000000..bd7cf47 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_partial_update.txt @@ -0,0 +1,501 @@ +Name + + KHR_partial_update + +Name Strings + + EGL_KHR_partial_update + +Contributors + + Ray Smith + Tom Cooksey + James Jones + Chad Versace + Jesse Hall + +Contact + + Ray Smith, ARM (Raymond.Smith 'at' arm.com) + +IP Status + + No known claims. + +Notice + + Copyright (c) 2014 The Khronos Group Inc. Copyright terms at + http://www.khronos.org/registry/speccopyright.html + +Status + + Complete. + Approved by the EGL Working Group on September 17, 2014. + Approved by the Khronos Board of Promoters on November 7, 2014. + +Version + + Version 12, September 12, 2014 + +Number + + EGL Extension #83 + +Extension Type + + EGL display extension + +Dependencies + + EGL 1.4 or later is required. + + Written based on the EGL 1.5 specification (March 12, 2014). + + The behavior of part of this extension is different depending on whether the + EGL_EXT_buffer_age extension is also present. + + This extension trivially interacts with EGL_KHR_swap_buffers_with_damage and + EGL_EXT_swap_buffers_with_damage. This extension is worded against the KHR + version, but the interactions with the EXT version are identical. + +New Procedures and Functions + + + EGLBoolean eglSetDamageRegionKHR(EGLDisplay dpy, + EGLSurface surface, + EGLint *rects, + EGLint n_rects); + +New Tokens + + Accepted in the <attribute> parameter of eglQuerySurface: + + EGL_BUFFER_AGE_KHR 0x313D + +Overview + + The aim of this extension is to allow efficient partial updates for postable + surfaces. It allows implementations to completely avoid processing areas of + the surface which have not changed between frames, allowing increased + efficiency. + + It does so by providing information and guarantees about the content of the + current back buffer which allow the application to "repair" only areas that + have become out of date since the particular back buffer was last used. + + The information provided is in the form of the "age" of the buffer, that is, + how many frames ago it was last used as the back buffer for the surface. If + the application tracks what changes it has made to the surface since this + back buffer was last used, it can bring the entire back buffer up to date by + only re-rendering the areas it knows to be out of date. + + Use of this extension provides a more efficient alternative to + EGL_BUFFER_PRESERVED swap behaviour. EGL_BUFFER_PRESERVED typically implies + an expensive full-frame copy at the beginning of the frame, as well as a + dependency on the previous frame. Usage of this extension avoids both and + requires only the necessary updates to a back buffer to be made. + +Terminology + + This extension and the EGL_KHR_swap_buffers_with_damage extension both use + the word "damage" for subtly but significantly different purposes: + + "Surface damage" is what the EGL_KHR_swap_buffers_with_damage extension + is concerned with. This is the area of the *surface* that changes between + frames for that surface. It concerns the differences between two buffers - + the current back buffer and the current front buffer. It is useful only to + the consumer. + + "Buffer damage" is what the EGL_KHR_partial_update extension is concerned + with. This is the area of a particular buffer that has changed since that + same buffer was last used. As it only concerns changes to a single buffer, + there is no dependency on the next or previous frames or any other buffer. + It therefore cannot be used to infer anything about changes to the surface, + which requires linking one frame or buffer to another. Buffer damage is + therefore only useful to the producer. + + Following are examples of the two different damage types. Note that the + final surface content is the same in both cases, but the damaged areas + differ according to the type of damage being discussed. + +Surface damage example (EGL_KHR_swap_buffers_with_damage) + + The surface damage for frame n is the difference between frame n and frame + (n-1), and represents the area that a compositor must recompose. + + Frame 0 Frame 1 Frame 2 Frame 3 Frame 4 + +---------+ +---------+ +---------+ +---------+ +---------+ + | | |#########| |#########| |#########| |#########| + | | | | |#########| |#########| |#########| Final surface + | | | | | | |#########| |#########| content + | | | | | | | | |#########| + +---------+ +---------+ +---------+ +---------+ +---------+ + + +---------+ +---------+ +---------+ +---------+ +---------+ + |@@@@@@@@@| |@@@@@@@@@| | | | | | | + |@@@@@@@@@| | | |@@@@@@@@@| | | | | Surface damage + |@@@@@@@@@| | | | | |@@@@@@@@@| | | + |@@@@@@@@@| | | | | | | |@@@@@@@@@| + +---------+ +---------+ +---------+ +---------+ +---------+ + +Buffer damage example (EGL_KHR_partial_update) + + The buffer damage for a frame is the area changed since that same buffer was + last used. If the buffer has not been used before, the buffer damage is the + entire area of the buffer. + + The buffer marked with an 'X' in the top left corner is the buffer that is + being used for that frame. This is the buffer to which the buffer age and + the buffer damage relate. + + Note that this example shows a double buffered surface - the actual number + of buffers could be different and variable throughout the lifetime of the + surface. The age *must* therefore be queried for every frame. + + Frame 0 Frame 1 Frame 2 Frame 3 Frame 4 + +---------+ +---------+ +---------+ +---------+ +---------+ + | | |#########| |#########| |#########| |#########| + | | | | |#########| |#########| |#########| Final surface + | | | | | | |#########| |#########| content + | | | | | | | | |#########| + +---------+ +---------+ +---------+ +---------+ +---------+ + + X---------+ +---------+ X---------+ +---------+ X---------+ + | | | | |#########| |#########| |#########| + | | | | |#########| |#########| |#########| Buffer 1 content + | | | | | | | | |#########| + | | | | | | | | |#########| + +---------+ +---------+ +---------+ +---------+ +---------+ + + X---------+ +---------+ X---------+ +---------+ + |#########| |#########| |#########| |#########| + | | | | |#########| |#########| Buffer 2 content + | | | | |#########| |#########| + | | | | | | | | + +---------+ +---------+ +---------+ +---------+ + + 0 0 2 2 2 Buffer age + + +---------+ +---------+ +---------+ +---------+ +---------+ + |@@@@@@@@@| |@@@@@@@@@| |@@@@@@@@@| | | | | + |@@@@@@@@@| |@@@@@@@@@| |@@@@@@@@@| |@@@@@@@@@| | | Buffer damage + |@@@@@@@@@| |@@@@@@@@@| | | |@@@@@@@@@| |@@@@@@@@@| + |@@@@@@@@@| |@@@@@@@@@| | | | | |@@@@@@@@@| + +---------+ +---------+ +---------+ +---------+ +---------+ + + +Add a new section entitled "Partial updates to postable surfaces" to section +3.5: + + The "damage region" defines the area of the buffer to which all rendering + commands must be restricted. It applies only for surfaces which can be + posted, as described in section 3.10, and only when the swap behavior is + EGL_BUFFER_DESTROYED. + + The contents of the buffer outside of the damage region may always be relied + upon to contain the same content as the last time they were defined for the + current back buffer. See section 3.5.6 for how to query when the current + back buffer was last used, and therefore what those contents are. + + If EGL_EXT_buffer_age is supported, the contents of the buffer inside the + damage region may also be relied upon to contain the same content as the + last time they were defined for the current back buffer. If + EGL_EXT_buffer_age is not supported, the contents of the buffer inside the + damage region are always undefined after calling eglSwapBuffers. + + Setting the damage region appropriately can be used to efficiently update + only the necessary areas inbetween frames. + + After posting the back buffer, the damage region is set to the full + dimensions of the surface. The damage region can only be changed by the + application before any client API commands that draw to the surface have + been made. After this, the damage region is frozen until the back buffer is + posted again. + + Use the command + EGLBoolean eglSetDamageRegionKHR( + EGLDisplay dpy, + EGLSurface surface, + EGLint *rects, + EGLint n_rects) + + to set the damage region. + + The damage region for <surface> is set to the area described by <n_rects> and + <rects> if all of the following conditions are met: + + * <surface> is the current draw surface of the calling thread + * <surface> is a postable surface + * There have been no client API commands which result with rendering to + <surface> since eglSwapBuffers was last called with <surface>, or since + <surface> was created in case eglSwapBuffers has not yet been called with + <surface>. + * The surface's swap behavior is EGL_BUFFER_DESTROYED + + <n_rects> specifies the number of rectangles comprising the damage region. + <rects> is a pointer to a list of values describing the rectangles. The list + should consist of <n_rects> groups of four values, with each group + representing a single rectangle in surface coordinates in the form {x, y, + width, height}. Coordinates are specified relative to the lower left corner + of the surface. It is not necessary to avoid overlaps of the specified + rectangles. Rectangles that lie (partially) outside of the current surface + dimensions (as queryable via the EGL_WIDTH and EGL_HEIGHT attributes) will + be clamped to the current surface dimensions. + + If <n_rects> is zero, <rects> is ignored and the damage region is set to the + full dimensions of the surface. + + If <n_rects> is not zero but the rectangles in <rects> describe a region of + zero area after clamping, the damage region is set to the empty region. + + If <rects> contains more than (4 * <n_rects>) values, the remaining values + are ignored. If <rects> contains fewer than (4 * <n_rects>) values, the + behavior is undefined, up to and including program termination. + + At all times, any client API rendering which falls outside of the damage + region results in undefined framebuffer contents for the entire framebuffer. + It is the client's responsibility to ensure that rendering is confined to + the current damage area. + + If any client API commands resulting in rendering to <surface> have been + issued since eglSwapBuffers was last called with <surface>, or since the + surface was created in case eglSwapBuffers has not yet been called on it, + attempting to set the damage region will result in undefined framebuffer + contents for the entire framebuffer. + + Errors + ------ + eglSetDamageRegionKHR returns EGL_FALSE on failure: + * If <surface> is not a postable surface, an EGL_BAD_MATCH error is + generated + * If <surface> is not the current draw surface for the calling thread, an + EGL_BAD_MATCH error is generated + * If the value of EGL_SWAP_BEHAVIOR for <surface> is not + EGL_BUFFER_DESTROYED, an EGL_BAD_MATCH error is generated + * If eglSetDamageRegionKHR has already been called on <surface> since the + most recent frame boundary, an EGL_BAD_ACCESS error is generated + * If the EGL_BUFFER_AGE_KHR attribute of <surface> has not been queried + since the most recent frame boundary, an EGL_BAD_ACCESS error is generated + +Add before the final paragraph in section 3.5.6 "Surface Attributes": + + Querying EGL_BUFFER_AGE_KHR returns the age of the color contents of the + current back buffer as the number of frames elapsed since it was most + recently defined. Under certain conditions described below, applications + can, in conjunction with the surface's damage region (see section 3.5.1), + use this age to safely rely on the contents of old back buffers to reduce + the amount of redrawing they do each frame. + + To query the age of a surface, it must be the current draw surface for the + calling thread. + + Function name + -------------------- + eglSwapBuffers + eglSwapBuffersWithDamageKHR + + 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 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 usually 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. + + Where specified in terms of the current damage region (see section 3.5.6), + the relevant part of a buffer's content is considered defined when the + buffer's age is a value greater than 0. + + Frame boundaries are the only events that can set a buffer's age to a + positive value. Once EGL_BUFFER_AGE_KHR 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 the X11 platform. + + EGL_BUFFER_AGE_KHR 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 to the list of errors for eglQuerySurface at the end of section 3.5.6 +"Surface Attributes": + + If <attribute> is EGL_BUFFER_AGE_KHR and <surface> is not the current draw + surface for the calling thread, an EGL_BAD_SURFACE error is generated. + +Add to the end of section 3.10.1.1 "Native Window Resizing": + + If eglSetDamageRegionKHR has been called with anything other than zero for + <n_rects>, a surface resize will cause the damage region to become + undefined. This will effectively cause the entire framebuffer content to + become undefined until the next frame. + +Dependencies on EGL_KHR_swap_buffers_with_damage + + If EGL_KHR_swap_buffers_with_damage is not supported, all references to + eglSwapBuffersWithDamageKHR are removed. + +Issues + + 1) What should happen if the client renders outside of the damage area? + + RESOLVED: The entire framebuffer content will be undefined. + + DISCUSSION: The definedness of different parts of the buffer varies across + implementations, making it hard to define, and providing any more specific + information may encourage improper and non-portable use of this extension. + + 2) How does this interact with EGL_EXT_buffer_age? + + RESOLVED: The initial content of the damage area differs depending on + whether EGL_EXT_buffer_age is present or not, making this extension fully + backwards compatible with EGL_EXT_buffer_age, while not depending on it. + + 3) How does this interact with EGL_KHR_swap_buffers_with_damage? + + RESOLVED: It does not interact materially with + EGL_KHR_swap_buffers_with_damage, except for the trivial interaction with + eglSwapBuffersWithDamageKHR being a frame boundary function if the extension + is also supported. + + DISCUSSION: This extension only provides a way to efficiently update the + back buffer for a surface. It does not have any effect on the subsequent + posting of that buffer. For maximum efficiency, applications should use both + EGL_KHR_partial_update and EGL_KHR_swap_buffers_with_damage simultaneously. + + 4) How does this interact with EGL_BUFFER_PRESERVED? + + RESOLVED: It is an error to call eglSetDamageRegionKHR with a surface with + EGL_BUFFER_PRESERVED swap behavior. However, it is not an error to query the + age of the buffer in this case. + + DISCUSSION: A layered extension will be proposed to guarantee that the age + of a buffer is always 1 after the first frame for a surface. This will + provide similar (but not identical) semantics to EGL_BUFFER_PRESERVED for + applications that need it. + + 5) How does surface resizing affect the damage region? + + RESOLVED: The damage region becomes undefined if a surface resize occurs + after it has been set to anything except the full buffer. Because rendering + outside the damage area results in undefined framebuffer contents, this + effectively means that the entire framebuffer content becomes undefined + until the next frame. + + 6) What happens if the damage region is set after any client rendering + commands? + + OPTION 1: An error is returned. Detecting this condition is non-trivial in + some implementations. + + OPTION 2: The entire framebuffer contents become undefined. + + RESOLVED: Option 2. + + 7) Should the entire region be provided in advance of any rendering, or should + each region be supplied immediately before the rendering commands for that + region, and multiple regions can be defined per frame? + + RESOLVED: The entire region must be provided in advance of any rendering. + + 8) What should be the behavior if eglSetDamageRegionKHR is called multiple + times before the first rendering command? + + RESOLVED: This is an error. The entire region must be provided during a + single call, with no overwrite or modify behavior needed. + + 9) Is it allowed to set the damage region when the buffer age has not been + queried? + + RESOLVED: This is an error. This could only make sense when the damage + region is the entire buffer, which it is initially anyway. Otherwise the + undamaged area needs to be defined to an age that the application doesn't + know about. It's not clear that this would ever be useful to the + application, because it can't know at this point which areas it needs to + update. + +10) What is the behavior if, after clamping, the damage region is empty? + + RESOLVED: The damage region is set to empty. + + +Revision History + + Version 1, 28/01/2014 + - Initial draft + Version 2, 05/02/2014 + - Removed clip behavior, replaced with undefined framebuffer contents if + client renders outside of given damage region + - Renamed to EGL_KHR_partial_update from EGL_KHR_frame_clip + - Added detailed parameter descriptions and error conditions + - Added dependency on GL_XXX_damage_region + - Defined interactions with EGL_EXT_buffer_age + Version 3, 04/03/2014 + - Removed dependency on GL_XXX_damage_region + - Changed error on defining damage region after drawcalls to be undefined + rendering results instead + - Redefined interactions with EGL_EXT_buffer_age to allow both to exist + Version 4, 20/03/2014 + - Modified language to allow use with EGLStream producer surfaces + - Clarified that surface must be the current *draw* surface + - Changed n_rects=0 behavior to set the damage region to the entire surface + - Clarified that rendering outside the damage region results in the entire + framebuffer becoming undefined + Version 5, 20/03/2014 + - Updated to be based on EGL 1.5 spec + Version 6, 23/04/2014 + -Added the pixel ownership logic from EGL_EXT_buffer_age + -Ported over the detailed description of buffer age from EGL_EXT_buffer_age + -Added a "New Functions" and "New Tokens" section. + -Added dependencies on EGL_EXT_swap_buffers_with_damage + Version 7, 20/05/2014 + - Removing a couple of now-obsolete sentences + - An age of 1 *usually* means the previous swap was implemented as a copy. + - Reworded "For the purposes of buffer age tracking..." to reference the + conditions under which the different parts of the buffer are actually + defined, which depend on the damage region + Version 8, 20/05/2014 + - Added issues list + Version 9, 12/08/2014 + - Removed outdated modification to "Posting to a Window" + - Changed names and order of rects/n_rects to match + EGL_EXT_swap_buffers_with_damage + - Resolved issue 3 on EGL_EXT_swap_buffers_with_damage interactions + - Resolved issue 4 on EGL_BUFFER_PRESERVED swap behavior + - Resolved issue 5 on surface resize behavior + - Resolved issue 7 on multiple calls to eglSetDamageRegionKHR + - Added issue 8 and suggested resolution + - Added issue 9 and suggested resolution + - Added issue 10 and suggested resolution + Version 10, 19/08/2014 + - Added section on terminology and damage types + Version 11, 10/09/2014 + - Resolved outstanding issues + Version 12, 12/09/2014 + - Added the restriction that you can only query the age of a surface while + it is the current draw surface. + Version 13, 18/09/2015 + - Marked as a Display extension + - Changed remaining references to EGL_EXT_swap_buffers_with_damage to + EGL_KHR_swap_buffers_with_damage diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_platform_android.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_platform_android.txt new file mode 100644 index 0000000..6568b64 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_platform_android.txt @@ -0,0 +1,102 @@ +Name + + KHR_platform_android + +Name Strings + + EGL_KHR_platform_android + +Contributors + + Jesse Hall <jessehall 'at' google.com> + The contributors to the EGL_KHR_platform_gbm extension, which this + extension was based on. + +Contacts + + Jesse Hall <jessehall 'at' google.com> + +Status + + Complete. + Approved by the EGL Working Group on January 31, 2014. + Ratified by the Khronos Board of Promoters on March 14, 2014. + +Version + + Version 1, 2014/01/27 + +Number + + EGL Extension #68 + +Extension Type + + EGL client extension + +Dependencies + + EGL 1.5 is required. + + This extension is written against the EGL 1.5 Specification (draft + 20140122). + +Overview + + This extension defines how to create EGL resources from native Android + resources using the EGL 1.5 platform functionality. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted as the <platform> argument of eglGetPlatformDisplay: + + EGL_PLATFORM_ANDROID_KHR 0x3141 + +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 for the Android device, call eglGetPlatformDisplay + with <platform> set to EGL_PLATFORM_ANDROID_KHR and with <native_display> + set to EGL_DEFAULT_DISPLAY. + + For each EGLConfig that belongs to the Android platform, the + EGL_NATIVE_VISUAL_ID attribute is an Android window format, such as + WINDOW_FORMAT_RGBA_8888. + + To obtain a rendering surface from an Android native window, call + eglCreatePlatformWindowSurface with a <dpy> that belongs to the Android + platform and a <native_window> that points to a ANativeWindow. + + It is not valid to call eglCreatePlatformPixmapSurface with a <dpy> that + belongs to the Android platform. Any such call fails and generates + an EGL_BAD_PARAMETER error. + +Issues + + 1. Should this extension even exist? Android devices only support one + window system. + + RESOLUTION: Yes. Although the Android Open Source Project master branch + only supports one window system, customized versions of Android could + extend that to support other window systems. More importantly, having a + platform extension allows EGL 1.5 applications to use the platform and + non-platform Get*Display and Create*WindowSurface calls interchangeably. As a user of the API it would be confusing if that didn't work. + +Revision History + + Version 1, 2014/01/27 (Jesse Hall) + - Initial draft. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_platform_gbm.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_platform_gbm.txt new file mode 100644 index 0000000..a4c04e0 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_platform_gbm.txt @@ -0,0 +1,295 @@ +Name + + KHR_platform_gbm + +Name Strings + + EGL_KHR_platform_gbm + +Contributors + + Chad Versace <chad.versace@intel.com> + Jon Leech (oddhack 'at' sonic.net) + Kristian Høgsberg <krh@bitplanet.org> + +Contacts + + Chad Versace <chad.versace@intel.com> + +Status + + Complete. + Approved by the EGL Working Group on January 31, 2014. + Ratified by the Khronos Board of Promoters on March 14, 2014. + +Version + + Version 3, 2016/01/04 + +Number + + EGL Extension #69 + +Extension Type + + EGL client extension + +Dependencies + + EGL 1.5 is required. + + This extension is written against the EGL 1.5 Specification (draft + 20140122). + +Overview + + This extension defines how to create EGL resources from native GBM + resources using the EGL 1.5 platform functionality (GBM is a Generic + Buffer Manager for Linux). + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted as the <platform> argument of eglGetPlatformDisplay: + + EGL_PLATFORM_GBM_KHR 0x31D7 + +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 from an GBM device, call eglGetPlatformDisplay with + <platform> set to EGL_PLATFORM_GBM_KHR. The <native_display> parameter + specifies the GBM device to use and must either point to a `struct + gbm_device` or be EGL_DEFAULT_DISPLAY. If <native_display> is + EGL_DEFAULT_DISPLAY, then the resultant EGLDisplay will be backed by some + implementation-chosen GBM device. + + For each EGLConfig that belongs to the GBM platform, the + EGL_NATIVE_VISUAL_ID attribute is a GBM color format, such as + GBM_FORMAT_XRGB8888. + + To obtain a rendering surface from a GBM surface, call + eglCreatePlatformWindowSurface with a <dpy> that belongs to the GBM + platform and a <native_window> that points to a `struct gbm_surface`. If + <native_window> was created without the GBM_BO_USE_RENDERING flag, or if + the color format of <native_window> differs from the EGL_NATIVE_VISUAL_ID + of <config>, then the function fails and generates EGL_BAD_MATCH. + + It is not valid to call eglCreatePlatformPixmapSurface with a <dpy> that + belongs to the GBM platform. Any such call fails and generates + an EGL_BAD_PARAMETER error. + +Issues + + 1. Should this extension permit EGL_DEFAULT_DISPLAY as input to + eglGetPlatformDisplay? + + RESOLUTION: Yes. When given EGL_DEFAULT_DISPLAY, eglGetPlatformDisplay + returns an EGLDisplay backed by an implementation-chosen GBM device. + +Example Code + + // This example program creates an EGL surface from a GBM surface. + // + // If the macro EGL_KHR_platform_gbm 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 -lgbm -lEGL`. + + #include <stdlib.h> + #include <string.h> + + #include <sys/types.h> + #include <sys/stat.h> + #include <fcntl.h> + + #include <EGL/egl.h> + #include <gbm.h> + + struct my_display { + struct gbm_device *gbm; + EGLDisplay egl; + }; + + struct my_config { + struct my_display dpy; + EGLConfig egl; + }; + + struct my_window { + struct my_config config; + struct gbm_surface *gbm; + EGLSurface egl; + }; + + static void + check_extensions(void) + { + #ifdef EGL_KHR_platform_gbm + const char *client_extensions = eglQueryString(EGL_NO_DISPLAY, EGL_EXTENSIONS); + + if (!client_extensions) { + // No client extensions string available + abort(); + } + if (!strstr(client_extensions, "EGL_KHR_platform_gbm")) { + abort(); + } + #endif + } + + static struct my_display + get_display(void) + { + struct my_display dpy; + + int fd = open("/dev/dri/card0", O_RDWR | FD_CLOEXEC); + if (fd < 0) { + abort(); + } + + dpy.gbm = gbm_create_device(fd); + if (!dpy.gbm) { + abort(); + } + + + #ifdef EGL_KHR_platform_gbm + dpy.egl = eglGetPlatformDisplay(EGL_PLATFORM_GBM_KHR, dpy.gbm, NULL); + #else + dpy.egl = eglGetDisplay(dpy.gbm); + #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_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_NONE, + }; + + EGLint num_configs; + if (!eglGetConfigs(dpy.egl, NULL, 0, &num_configs)) { + abort(); + } + + EGLConfig *configs = malloc(num_configs * sizeof(EGLConfig)); + if (!eglChooseConfig(dpy.egl, egl_config_attribs, + configs, num_configs, &num_configs)) { + abort(); + } + if (num_configs == 0) { + abort(); + } + + // Find a config whose native visual ID is the desired GBM format. + for (int i = 0; i < num_configs; ++i) { + EGLint gbm_format; + + if (!eglGetConfigAttrib(dpy.egl, configs[i], + EGL_NATIVE_VISUAL_ID, &gbm_format)) { + abort(); + } + + if (gbm_format == GBM_FORMAT_XRGB8888) { + config.egl = configs[i]; + free(configs); + return config; + } + } + + // Failed to find a config with matching GBM format. + abort(); + } + + static struct my_window + get_window(struct my_config config) + { + struct my_window window = { + .config = config, + }; + + window.gbm = gbm_surface_create(config.dpy.gbm, + 256, 256, + GBM_FORMAT_XRGB8888, + GBM_BO_USE_RENDERING); + if (!window.gbm) { + abort(); + } + + #ifdef EGL_KHR_platform_gbm + window.egl = eglCreatePlatformWindowSurface(config.dpy.egl, + config.egl, + window.gbm, + NULL); + #else + window.egl = eglCreateWindowSurface(config.dpy.egl, + config.egl, + window.gbm, + NULL); + #endif + + if (window.egl == EGL_NO_SURFACE) { + abort(); + } + + return window; + } + + 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); + + return 0; + } + +Revision History + + Version 3, 2016-01-04 (Jon Leech) + - Free config memory allocated in sample code (Public Bug 1445). + + Version 2, 2014/02/12 (Chad Versace) + - Change resolution of issue #1 from "no" to "yes". Now + eglGetPlatformDisplay accepts EGL_DEFAULT_DISPLAY for GBM. + + Version 1, 2014/01/22 (Jon Leech) + - Promote EGL_MESA_platform_gbm to KHR to go with EGL 1.5. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_platform_wayland.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_platform_wayland.txt new file mode 100644 index 0000000..d7315b3 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_platform_wayland.txt @@ -0,0 +1,122 @@ +Name + + KHR_platform_wayland + +Name Strings + + EGL_KHR_platform_wayland + +Contributors + + Chad Versace <chad.versace@intel.com> + Jon Leech (oddhack 'at' sonic.net) + +Contacts + + Chad Versace <chad.versace@intel.com> + +Status + + Complete. + Approved by the EGL Working Group on January 31, 2014. + Ratified by the Khronos Board of Promoters on March 14, 2014. + +Version + + Version 2, 2014/02/18 + +Number + + EGL Extension #70 + +Extension Type + + EGL client extension + +Dependencies + + EGL 1.5 is required. + + This extension is written against the EGL 1.5 Specification (draft + 20140122). + + The behavior of part of this extension is different depending on whether + the EGL_EXT_buffer_age extension is also present. + +Overview + + This extension defines how to create EGL resources from native Wayland + resources using the EGL 1.5 platform functionality. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted as the <platform> argument of eglGetPlatformDisplay: + + EGL_PLATFORM_WAYLAND_KHR 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 + eglGetPlatformDisplay with <platform> set to EGL_PLATFORM_WAYLAND_KHR. 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 + eglCreatePlatformWindowSurface 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 eglCreatePlatformPixmapSurface with a <dpy> that + belongs to Wayland. Any such call fails and generates an + EGL_BAD_PARAMETER error. + + Rendering to the obtained EGLSurface or querying it with EGL_BUFFER_AGE_KHR + will lock its back buffer preventing it from being dropped or resized, + until the next buffer swap. The rationale behind this behavior is to keep + operations result accurate until the next swap. + +Issues + + 1. Should this extension permit EGL_DEFAULT_DISPLAY as input to + eglGetPlatformDisplay()? + + RESOLUTION: Yes. When given EGL_DEFAULT_DISPLAY, eglGetPlatformDisplay + returns a display backed by the default Wayland display. + + 2. Should this extension support creation of EGLPixmap resources from + Wayland pixmaps? + + RESOLVED. No. Wayland has no pixmap type. + +Revision History + Version 3, 2022/07/14 (Kirill Chibisov) + - Clarify EGLSurface back buffer locking behavior with regards to + rendering and surface querying operations. + - Add dependency on EGL_EXT_buffer_age. + + Version 2, 2014/02/18 (Chad Versace) + - Change resolution of issue #1 from "no" to "yes". Now + eglGetPlatformDisplay accepts EGL_DEFAULT_DISPLAY for Wayland. + - Explain in more detail how EGL connects to the default Wayland + display. + + Version 1, 2014/01/22 (Jon Leech) + - Promote EGL_EXT_platform_wayland to KHR to go with EGL 1.5. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_platform_x11.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_platform_x11.txt new file mode 100644 index 0000000..2c44141 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_platform_x11.txt @@ -0,0 +1,378 @@ +Name + + KHR_platform_x11 + +Name Strings + + EGL_KHR_platform_x11 + +Contributors + + Chad Versace <chad.versace@intel.com> + James Jones <jajones@nvidia.com> + Jon Leech (oddhack 'at' sonic.net) + +Contacts + + Chad Versace <chad.versace@intel.com> + +Status + + Complete. + Approved by the EGL Working Group on January 31, 2014. + Ratified by the Khronos Board of Promoters on March 14, 2014. + +Version + + Version 3, 2014/02/18 + +Number + + EGL Extension #71 + +Extension Type + + EGL client extension + +Dependencies + + EGL 1.5 is required. + + This extension is written against the EGL 1.5 Specification (draft + 20140122). + +Overview + + This extension defines how to create EGL resources from native X11 + resources using the EGL 1.5 platform functionality. + + This extension only defines 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 eglGetPlatformDisplay: + + EGL_PLATFORM_X11_KHR 0x31D5 + + Accepted as an attribute name in the <attrib_list> argument of + eglGetPlatformDisplay: + + EGL_PLATFORM_X11_SCREEN_KHR 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 eglGetPlatformDisplay + with <platform> set to EGL_PLATFORM_X11_KHR. The <native_display> parameter + specifies the X11 display connection to use, and must either point to + a valid X11 `Display` 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 as described in the manual page for XOpenDisplay(3). The value of + attribute EGL_PLATFORM_X11_SCREEN_KHR 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 + eglCreatePlatformWindowSurface 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 + eglCreatePlatformPixmapSurface 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 + eglGetPlatformDisplay()? + + RESOLVED. Yes. When given EGL_DEFAULT_DISPLAY, eglGetPlatformDisplay + returns an EGLDisplay backed by the default X11 display. + + 2. When given EGL_DEFAULT_DISPLAY, does eglGetPlatformDisplay reuse an + existing X11 display connection or create a new one? + + RESOLVED. eglGetPlatformDisplay 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_KHR_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_KHR_PLATFORM_X11 + const char *client_extensions = eglQueryString(EGL_NO_DISPLAY, EGL_EXTENSIONS); + + if (!client_extensions) { + // No client extensions string available + abort(); + } + if (!strstr(client_extensions, "EGL_KHR_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_KHR_PLATFORM_X11 + dpy.egl = eglGetPlatformDisplay(EGL_PLATFORM_X11_KHR, 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_KHR_PLATFORM_X11 + window.egl = eglCreatePlatformWindowSurface(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_KHR_PLATFORM_X11 + pixmap.egl = eglCreatePlatformPixmapSurface(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 3, 2014/02/18 (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 2, 2014/02/11 (Chad Versace) + - Fix 2nd argument to XCreatePixmap in example code. + + Version 1, 2014/01/22 (Jon Leech) + - Promote EGL_EXT_platform_x11 to KHR to go with EGL 1.5. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_reusable_sync.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_reusable_sync.txt new file mode 100644 index 0000000..df49175 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_reusable_sync.txt @@ -0,0 +1,575 @@ +Name + + KHR_reusable_sync + +Name Strings + + EGL_KHR_reusable_sync + +Contributors + + Acorn Pooley + Gary King + Gregory Prisament + Jon Leech + Robert Palmer + +Contacts + + Acorn Pooley, NVIDIA Corporation (apooley 'at' nvidia.com) + Gary King, NVIDIA Corporation (gking 'at' nvidia.com) + Gregory Prisament, NVIDIA Corporation (gprisament 'at' nvidia.com) + Jon Leech (jon 'at' alumni.caltech.edu) + Robert Palmer (robert.palmer 'at' nokia.com) + +Notice + + Copyright (c) 2006-2013 The Khronos Group Inc. Copyright terms at + http://www.khronos.org/registry/speccopyright.html + +Status + + Complete. + Approved by the Khronos Board of Promoters on August 28, 2009. + +Version + + Version 22, January 31, 2014 + +Number + + EGL Extension #6 + +Dependencies + + Requires EGL 1.1 + + This extension is written against the wording of the EGL 1.2 + Specification. + +Overview + + This extension introduces the concept of "sync objects" into EGL. + Sync objects are a synchronization primitive, representing events + whose completion can be tested or waited upon. This extension + borrows from the GL_ARB_sync extension but introduces a type of sync + object known as "reusable sync object" comparable to an OS + semaphore. The specification is designed to allow additional types of + sync objects to be easily introduced in later extensions. + + Reusable sync objects may be used to synchronize activity between + threads or between client APIs. Synchronization is accomplished by + explicitly changing the status of a reusable object using EGL API + commands. + +New Types + + /* + * EGLSyncKHR is an opaque handle to an EGL sync object + */ + typedef void* EGLSyncKHR; + + /* + * EGLTimeKHR is a 64-bit unsigned integer representing intervals + * in nanoseconds. + */ + #include <khrplatform.h> + typedef khronos_utime_nanoseconds_t EGLTimeKHR; + + +New Procedures and Functions + + EGLSyncKHR eglCreateSyncKHR( + EGLDisplay dpy, + EGLenum type, + const EGLint *attrib_list); + + EGLBoolean eglDestroySyncKHR( + EGLDisplay dpy, + EGLSyncKHR sync); + + EGLint eglClientWaitSyncKHR( + EGLDisplay dpy, + EGLSyncKHR sync, + EGLint flags, + EGLTimeKHR timeout); + + EGLBoolean eglSignalSyncKHR( + EGLDisplay dpy, + EGLSyncKHR sync, + EGLenum mode); + + EGLBoolean eglGetSyncAttribKHR( + EGLDisplay dpy, + EGLSyncKHR sync, + EGLint attribute, + EGLint *value); + + +New Tokens + + Accepted by the <type> parameter of eglCreateSyncKHR, and returned + in <value> when eglGetSyncAttribKHR is called with <attribute> + EGL_SYNC_TYPE_KHR: + + EGL_SYNC_REUSABLE_KHR 0x30FA + + Accepted by the <attribute> parameter of eglGetSyncAttribKHR: + + EGL_SYNC_TYPE_KHR 0x30F7 + EGL_SYNC_STATUS_KHR 0x30F1 + + Accepted by the <mode> parameter of eglSignalSyncKHR and returned in + <value> when eglGetSyncAttribKHR is called with <attribute> + EGL_SYNC_STATUS_KHR: + + EGL_SIGNALED_KHR 0x30F2 + EGL_UNSIGNALED_KHR 0x30F3 + + Accepted in the <flags> parameter of eglClientWaitSyncKHR: + + EGL_SYNC_FLUSH_COMMANDS_BIT_KHR 0x0001 + + Accepted in the <timeout> parameter of eglClientWaitSyncKHR: + + EGL_FOREVER_KHR 0xFFFFFFFFFFFFFFFFull + + Returned by eglClientWaitSyncKHR: + + EGL_TIMEOUT_EXPIRED_KHR 0x30F5 + EGL_CONDITION_SATISFIED_KHR 0x30F6 + + Returned by eglCreateSyncKHR in the event of an error: + + EGL_NO_SYNC_KHR ((EGLSyncKHR)0) + +Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors) + + Add a new subsection at the end of Section 3.8, page 43 + (Synchronization Primitives) + + "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>. Initially, sync objects are unsignaled. EGL may be + asked to wait for a sync object to become signaled, or a sync + object's 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 + unsignaling the sync. + + 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. + + <Reusable sync objects> are created in the unsignaled state, and may + be signaled and/or unsignaled repeatedly. Every transition of a + reusable sync object's status from unsignaled to signaled will + release any threads waiting on that sync object. + + The command + + EGLSyncKHR eglCreateSyncKHR( + EGLDisplay dpy, + EGLenum type, + const EGLint *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 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. + + If <type> is EGL_SYNC_REUSABLE_KHR, a reusable sync object is + created. In this case <attrib_list> must be NULL or empty + (containing only EGL_NONE). Attributes of the reusable sync object + are set as follows: + + Attribute Name Initial Attribute Value(s) + --------------- -------------------------- + EGL_SYNC_TYPE_KHR EGL_SYNC_REUSABLE_KHR + EGL_SYNC_STATUS_KHR EGL_UNSIGNALED_KHR + + Errors + ------ + + * If <dpy> is not the name of a valid, initialized EGLDisplay, + EGL_NO_SYNC_KHR is returned and an EGL_BAD_DISPLAY error is + generated. + * If <attrib_list> is neither NULL nor empty (containing only + EGL_NONE), EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE + error is generated. + * If <type> is not a supported type of sync object, + EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE error is + generated. + + The command + + EGLint eglClientWaitSyncKHR( + EGLDisplay dpy, + EGLSyncKHR sync, + EGLint flags, + EGLTimeKHR timeout); + + blocks the calling thread until the specified sync object <sync> is + signaled, or until <timeout> nanoseconds have passed. + + More than one eglClientWaitSyncKHR may be outstanding on the same + <sync> at any given time. When there are multiple threads blocked on + the same <sync> and the sync object is signaled, all such threads + are released, but the order in which they are released is not + defined. + + If the value of <timeout> is zero, then eglClientWaitSyncKHR simply + tests the current status of <sync>. If the value of <timeout> is the + special value EGL_FOREVER_KHR, then eglClientWaitSyncKHR does not + time out. For all other values, <timeout> is adjusted to the closest + value allowed by the implementation-dependent timeout accuracy, + which may be substantially longer than one nanosecond. + + eglClientWaitSyncKHR returns one of three status values describing + the reason for returning. A return value of EGL_TIMEOUT_EXPIRED_KHR + indicates that the specified timeout period expired before <sync> + was signaled, or if <timeout> is zero, indicates that <sync> is + not signaled. A return value of EGL_CONDITION_SATISFIED_KHR + indicates that <sync> was signaled before the timeout expired, which + includes the case when <sync> was already signaled when + eglClientWaitSyncKHR was called. If an error occurs then an error is + generated and EGL_FALSE is returned. + + If the EGL_SYNC_FLUSH_COMMANDS_BIT_KHR bit is set in + <flags>, and <sync> is unsignaled when eglClientWaitSyncKHR is + called, then the equivalent of Flush() will be performed for the + current API context (i.e., the context returned by + eglGetCurrentContext()) before blocking on <sync>. If no context is + current for the bound API, the EGL_SYNC_FLUSH_COMMANDS_BIT_KHR bit + is ignored. + + If a sync object is destroyed while an eglClientWaitSyncKHR is + blocking on that object, eglClientWaitSyncKHR will unblock and + return immediately, just as if the sync object had been signaled + prior to being destroyed. + + Errors + ------ + + * If <sync> is not a valid sync object for <dpy>, EGL_FALSE is + returned and an EGL_BAD_PARAMETER error is generated. + * If <dpy> does not match the EGLDisplay passed to + eglCreateSyncKHR when <sync> was created, the behaviour is + undefined. + + + The command + + EGLBoolean eglSignalSyncKHR( + EGLDisplay dpy, + EGLSyncKHR sync, + EGLenum mode); + + signals or unsignals the reusable sync object <sync> by changing its + status to <mode>, which must be one of the values in table 3.bb. If + as a result of calling eglSignalSyncKHR the status of <sync> + transitions from unsignaled to signaled, any eglClientWaitSyncKHR + commands blocking on <sync> will unblock. + + Assuming no errors are generated, EGL_TRUE is returned. + + Mode Effect + ------------------ ------------- + EGL_SIGNALED_KHR Set the status of <sync> to signaled + EGL_UNSIGNALED_KHR Set the status of <sync> to unsignaled + + Table 3.bb Modes Accepted by eglSignalSyncKHR Command + + Errors + ------ + + * If <sync> is not a valid sync object for <dpy>, EGL_FALSE is + returned and an EGL_BAD_PARAMETER error is generated. + * If the type of <sync> is not EGL_SYNC_REUSABLE_KHR, EGL_FALSE is + returned and an EGL_BAD_MATCH error is generated. + * If <dpy> does not match the EGLDisplay passed to + eglCreateSyncKHR when <sync> was created, the behaviour is + undefined. + + + The command + + EGLBoolean eglGetSyncAttribKHR( + EGLDisplay dpy, + EGLSyncKHR sync, + EGLint attribute, + EGLint *value); + + is used to query attributes of the sync object <sync>. Legal values + for <attribute> depend on the type of sync object, as shown in table + 3.cc. Assuming no errors are generated, EGL_TRUE is returned and the + value of the queried attribute is returned in <value>. + + Attribute Description Supported Sync Objects + ----------------- ----------------------- ---------------------- + EGL_SYNC_TYPE_KHR Type of the sync object All + EGL_SYNC_STATUS_KHR Status of the sync object All + + Table 3.cc Attributes Accepted by eglGetSyncAttribKHR Command + + Errors + ------ + + * If <sync> is not a valid sync object for <dpy>, EGL_FALSE is + returned and an EGL_BAD_PARAMETER error is generated. + * If <dpy> does not match the display passed to eglCreateSyncKHR + when <sync> was created, the behaviour is undefined. + * If <attribute> is not one of the attributes in table 3.cc, + EGL_FALSE is returned and an EGL_BAD_ATTRIBUTE error is + generated. + * If <attribute> is not supported for the type of sync object + passed in <sync>, EGL_FALSE is returned and an EGL_BAD_MATCH + error is generated. + + If any error occurs, <*value> is not modified. + + The command + + EGLBoolean eglDestroySyncKHR( + EGLDisplay dpy, + EGLSyncKHR sync); + + is used to destroy an existing sync object. If any + eglClientWaitSyncKHR commands are blocking on <sync> when + eglDestroySyncKHR is called, they will be woken up, as if <sync> + were signaled. + + If no errors are generated, EGL_TRUE is returned, and <sync> will no + longer be the handle of a valid sync object. + + Errors + ------ + + * If <sync> is not a valid sync object for <dpy>, EGL_FALSE is + returned and an EGL_BAD_PARAMETER error is generated. + * If <dpy> does not match the display passed to eglCreateSyncKHR + when <sync> was created, the behaviour is undefined." + +Issues + + Note about the Issues + --------------------- + The wording for this extension was originally written as a single + extension defining two types of sync object; a "reusable sync + object" and a "fence sync object". That extension was split to + produce standalone extensions for each type of sync object, and + references to the other type removed from the specification + language. This issues list has been simplied to remove references to + fence sync objects but is otherwise very similar to the + EGL_KHR_fence_sync extension issues list. + + 1. Explain the key choices made in this extension. + + RESPONSE: This extension has been written to enable adoption to be + as wide as possible, and to behave as similarly as possible to + synchronization primitives available in desktop OpenGL (e.g., + NV_fence, ARB_sync). + + In the interest of enabling widespread adoption, this extension + (following the ARB_sync model) has foregone the inclusion of + synchronization primitives and synchronization tests which may be + performed entirely inside client API command streams, instead + performing synchronization tests (eglClientWaitSyncKHR) inside the + application & host CPU. + + In the interest of maintaining similarity with previous + synchronization primitives, this extension attempts to copy the + ARB_sync specification wherever possible (both functionally and + stylistically), only making changes where needed to operate inside + EGL (rather than a client API context) and match EGL naming + conventions. + + 2. Why place this behavior in EGL, rather than in the client APIs? + + RESPONSE: Ultimately, synchronization between multiple asynchronous + client API contexts (potentially executing in different threads) is + a problem which affects or will affect all EGL client APIs. Rather + than creating separate synchronization primitives in each of the + client APIs (and then wrapping them in an EGL container), in the + interest of developer simplicity & consistency this behavior is + being placed inside EGL. + + 3. What does this extension provide that can not be accomplished + with the existing, more efficient eglWaitClient and eglWaitNative + API functions? + + RESPONSE: eglWaitClient and eglWaitNative may be implemented in + extremely lightweight manners, in some cases not blocking the + calling thread at all; however, they can not be used to synchronize + between client API contexts and native APIs executing in separate + threads (or simply between client API contexts executing in separate + threads), such as between a thread with an active OpenGL context and + a second thread performing video decode. + + 4. [REMOVED - found in the fence_sync extension.] + + 5. Should integration with native platform synchronization objects + be included in this extension, or reserved for future + (platform-specific) extensions? + + RESOLVED: Integration with native platform synchronization objects + should not be part of this extension, but can be added as future + layered extensions if needed. These layered extensions can be + platform-specific, or perhaps OpenKODE based. + + Originally, this extension included the ability to create native + platform synchronization objects from EGLSync objects. This feature + was removed for a few reasons: + + i) The proposed mechanism suggested mapping EGLSync objects to + pthread conditional variables on platforms with pthread support. + However, pthread conditional variables require an associated + mutex and there was no mechanism to relay this associated mutex + to the application. + + ii) On certain platforms support for converting to native + platform synchronization objects adds great complexity to the + implementation. + + iii) Now that OpenKODE is more mature, it would be better to + allow conversion from EGLSyncKHR objects to OpenKODE + synchronization primitives rather than platform-specific ones. + We suggest that this functionality, if needed, be added as a + layered extension instead of being included here. This way, + EGL_KHR_sync remains minimal and easy to implement on a variety + of platforms. + + 6. Please provide a more detailed description of how + eglClientWaitSyncKHR behaves. + + RESOLVED: eglClientWaitSyncKHR blocks until the status of the sync + object transitions to the signaled state. Sync object status is + either signaled or unsignaled. More detailed rules describing + signalling follow (these may need to be imbedded into the actual + spec language): + + * A reusable sync object has two possible status values: signaled + or unsignaled. + * When created, the status of the sync object is unsignaled by + default. + * A reusable sync can be set to signaled or unsignaled + status using eglSignalSyncKHR. + * A wait function called on a sync object in the unsignaled state + will block. It unblocks (note, not "returns to the application") + when the sync object transitions to the signaled state. + * A wait function called on a sync object in the signaled state + will return immediately. + + 7. Should the 'flags' argument to eglClientWaitSyncKHR be + EGLint or EGLuint? + + RESOLVED: EGLint, setting a precedent for explicit bitmask types + in EGL going forward. We don't have an EGLuint type and it is + overkill for this purposes when other bitmasks (surface type + and api type) are already using EGLint attribute fields. + + 8. Can multiple WaitSyncs be placed on the same sync object? + + RESOLVED: Yes. This has been allowed all along but we now state it + more clearly in the spec language. However, there is some concern + that this is hard to implement and of limited use, and we might + remove this capability before approving the extension. + + One way to do this while allowing multiple waiters at some future + point is to expose it through the API to developers as either a sync + attribute allowing multiple waits (default not allowing it), or a + parameter to WaitSync, which initially must be something like + EGL_SINGLE_WAIT_ONLY. + + 9. Should eglDestroySyncKHR release all WaitSyncs placed on a + reusable sync object? + + RESOLVED: Yes. It is safest to release all threads waiting on a + reusable object when the sync object is deleted so that waiting + threads do not wait forever. + +Revision History + +#22 (Jon Leech, January 31, 2014) + - Clarify return value of ClientWaitSyncKHR when called with <timeout> + of zero for an unsignaled <sync> (Bug 11576). +#21 (Jon Leech, April 23, 2013) + - Simplify issues list to remove issues specific to fence sync + objects. +#20 (Jon Leech, September 8, 2009) + - Change status to complete and note approval by the Promoters. + Minor formatting changes. +#19 (Robert Palmer, July 14, 2009) + - Branch wording from draft KHR_sync specification. Remove ability + to create "fence sync objects and all tokens/wording specific to + them. +#18 (Robert Palmer, July 8, 2009) + - Issues 8 and 9 declared resolved in EGL meeting 2009-07-08 +#17 (Robert Palmer, July 8, 2009) + - Update eglDestroySyncKHR to special-case deletion of fence sync + objects. This is explained in issue 9. + - Corrected EGL_REUSABLE_SYNC_KHR -> EGL_SYNC_REUSABLE_KHR + - Define value for EGL_SYNC_REUSABLE_KHR + - Fix typo and whitespace +#16 (Jon Leech, July 7, 2009) + - Update description of new tokens to match changes to the + eglCreateSyncKHR entry point in revision 15. +#15 (Jon Leech, June 16, 2009) + - Define separate one-time fence sync and reusable sync extensions + and corresponding extension strings. Remove AUTO_RESET and + eglFenceKHR. Rename eglCreateFenceSyncKHR to eglCreateSyncKHR and + change initial status of reusable syncs to unsignaled. Clarify + which functions apply to which types of sync objects. Update + issues list. +#14 (Jon Leech, April 29, 2009) + - Clarify that all waiters are woken up on signalling a sync. + Remove tabs to cleanup some formatting issues. +#13 (Acorn Pooley, April 2, 2009) + - Renamed + GL_OES_egl_sync -> GL_OES_EGL_sync + VG_KHR_egl_sync -> VG_KHR_EGL_sync +#12 (Jon Leech, April 1, 2009) + - Changed sync flags type from EGLuint to EGLint and add issue 7. +#11 (Acorn Pooley, February 4, 2009) + - add error case to eglGetSyncAttribKHR. + - fix year on rev 8-10 (2008->2009) +#10 (Acorn Pooley, February 4, 2009) + - clarify some error message descriptions +#9 (Greg Prisament, January 15, 2009) + - Destroy now wakes up all waits (eglClientWaitSyncKHR) + - Add EGLDisplay <dpy> as first parameter to all commands + - Split into 3 extension strings, EGL_KHR_sync, GL_OES_egl_sync, + VG_KHR_egl_sync, all described in this document. + - Add attribute AUTO_RESET_KHR + - Time type uses the type from khrplatform.h + - Remove EGL_ALREADY_SIGNALLED +#8 (Jon Leech, November 11, 2009) + - Assign enum values +#7 (Acorn Pooley, October 30, 2008) + - Fix typos + - remove obsolete wording about Native sync objects (see issue 5) + - formatting: remove tabs, 80 columns +#6 (Acorn Pooley, October 27, 2008) + - Corrected 'enum' to 'EGLenum' in prototypes. +#5 (Jon Leech, September 9, 2008) + - Removed native sync support (eglCreateNativeSyncKHR and + EGL_SYNC_NATIVE_SYNC_KHR), and re-flowed spec to fit in 80 columns. +#4 (Jon Leech, November 20, 2007) + - Corrected 'enum' to 'EGLenum' in prototypes. +#3 (Jon Leech, April 5, 2007) + - Added draft Status and TBD Number +#2 (November 27, 2006) + - Changed OES token to KHR diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_stream.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_stream.txt new file mode 100644 index 0000000..34ebc13 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_stream.txt @@ -0,0 +1,1091 @@ +Name + + KHR_stream + KHR_stream_attrib + +Name Strings + + EGL_KHR_stream + EGL_KHR_stream_attrib + +Contributors + + Marcus Lorentzon + Acorn Pooley + Robert Palmer + Greg Prisament + Daniel Kartch + Miguel A. Vico Moya + +Contacts + + Acorn Pooley, NVIDIA (apooley 'at' nvidia.com) + Marcus Lorentzon, ST-Ericsson AB (marcus.xm.lorentzon 'at' stericsson.com) + Daniel Kartch, NVIDIA (dkartch 'at' nvidia.com) + +Notice + + Copyright (c) 2009-2016 The Khronos Group Inc. Copyright terms at + http://www.khronos.org/registry/speccopyright.html + +Status + + Complete. + Approved by the Khronos Board of Promoters on December 2, 2011. + +Version + + Version 27 - May 23, 2016 + +Number + + EGL Extension #32 + +Dependencies + + EGL_KHR_stream requires EGL 1.2. + + EGL_KHR_stream_attrib requires EGL_KHR_stream and EGL 1.5. + + EGL_KHR_stream_attrib interacts with + EGL_KHR_stream_consumer_gltexture. + + This extension is written based on the wording of the EGL 1.2 + specification. + +Overview + + This extension defines a new object, the EGLStream, that can be + used to efficiently transfer a sequence of image frames from one + API to another. The EGLStream has mechanisms that can help keep + audio data synchronized to video data. + + Each EGLStream is associated with a "producer" that generates + image frames and inserts them into the EGLStream. The producer is + responsible for inserting each image frame into the EGLStream at + the correct time so that the consumer can display the image frame + for the appropriate period of time. + + Each EGLStream is also associated with a "consumer" that + retrieves image frames from the EGLStream. The consumer is + responsible for noticing that an image frame is available and + displaying it (or otherwise consuming it). The consumer is also + responsible for indicating the latency when that is possible (the + latency is the time that elapses between the time it is retrieved + from the EGLStream until the time it is displayed to the user). + + Some APIs are stream oriented (examples: OpenMAX IL, OpenMAX AL). + These APIs may be connected directly to an EGLStream as a producer + or consumer. Once a stream oriented producer is "connected" to an + EGLStream and "started" it may insert image frames into the + EGLStream automatically with no further interaction from the + application. Likewise, once a stream oriented consumer is + "connected" to an EGLStream and "started" it may retrieve image + frames from the EGLStream automatically with no further interaction + from the application. + + Some APIs are rendering oriented and require interaction with the + application during the rendering of each frame (examples: OpenGL, + OpenGL ES, OpenVG). These APIs will not automatically insert or + retrieve image frames into/from the EGLStream. Instead the + application must take explicit action to cause a rendering + oriented producer to insert an image frame or to cause a rendering + oriented consumer to retrieve an image frame. + + The EGLStream conceptually operates as a mailbox. When the + producer has a new image frame it empties the mailbox (discards + the old contents) and inserts the new image frame into the + mailbox. The consumer retrieves the image frame from the mailbox + and examines it. When the consumer is finished examining the + image frame it is either placed back in the mailbox (if the + mailbox is empty) or discarded (if the mailbox is not empty). + + Timing is mainly controlled by the producer. The consumer + operated with a fixed latency that it indicates to the producer + through the EGL_CONSUMER_LATENCY_USEC_KHR attribute. The consumer + is expected to notice when a new image frame is available in the + EGLStream, retrieve it, and display it to the user in the time + indicated by EGL_CONSUMER_LATENCY_USEC_KHR. The producer controls + when the image frame will be displayed by inserting it into the + stream at time + T - EGL_CONSUMER_LATENCY_USEC_KHR + where T is the time that the image frame is intended to appear to + the user. + + This extension does not cover the details of how a producer or a + consumer works or is "connected" to an EGLStream. Different kinds + of producers and consumers work differently and are described in + additional extension specifications. (Examples of producer + specifications: + EGL_KHR_stream_producer_eglsurface + EGL_KHR_stream_producer_aldatalocator + OpenMAX_AL_EGLStream_DataLocator + Example of consumer extension specification: + EGL_KHR_stream_consumer_gltexture + ) + + +Glossary + + EGLStream + An EGL object that transfers a sequence of image frames from one + API to another (e.g. video frames from OpenMAX AL to OpenGL ES). + + Image frame + A single image in a sequence of images. The sequence may be + frames of video data decoded from a video file, images output by a + camera sensor, surfaces rendered using OpenGL ES commands, or + generated in some other manner. An image frame has a period of + time during which it is intended to be displayed on the screen + (starting with the "Image Frame Display Time" and ending with the + "Image Frame Display Time" of the next image frame in the + sequence). + + Image Frame Insertion Time + The point in time when the producer inserts the image frame into + the EGLStream. This is the "Image Frame Intended Display Time" + minus the "Consumer Latency". + + Image Frame Intended Display Time + The point in time when the user should first see the image frame + on the display screen. + + Image Frame Actual Display Time + The point in time when the user actually first sees the image frame + on the display screen. + + Consumer Latency + The elapsed time between an image frame's "Image Frame Insertion + Time" and its "Image Frame Actual Display Time". The consumer is + responsible for predicting this and indicating its value to the + EGLStream. The producer is responsible for using this value to + calculate the "Image Frame Insertion Time" for each image frame. + The application has access to this value through the + EGL_CONSUMER_LATENCY_USEC attribute. + + Producer + The entity that inserts image frames into the EGLStream. The + producer is responsible for timing: it must insert image frames at + a point in time equal to the "Image Frame Intended Display Time" + minus the "Consumer Latency". + + Consumer + The entity that retrieves image frames from the EGLStream. When + the image frames are to be displayed to the user the consumer is + responsible for calculating the "Consumer Latency" and reporting + it to the EGLSteam. + + State (stream state) + At any given time an EGLStream is in one of several states. See + section "3.10.4.3 EGL_STREAM_STATE_KHR Attribute" in this + extension for a description of the states and what transitions + occur between them. + +New Types + + This is the type of a handle that represents an EGLStream object. + + typedef void* EGLStreamKHR; + + This is a 64 bit unsigned integer. + + typedef khronos_uint64_t EGLuint64KHR; + +New functions defined by EGL_KHR_stream + + EGLStreamKHR eglCreateStreamKHR( + EGLDisplay dpy, + const EGLint *attrib_list); + + EGLBoolean eglDestroyStreamKHR( + EGLDisplay dpy, + EGLStreamKHR stream); + + EGLBoolean eglStreamAttribKHR( + EGLDisplay dpy, + EGLStreamKHR stream, + EGLenum attribute, + EGLint value); + + EGLBoolean eglQueryStreamKHR( + EGLDisplay dpy, + EGLStreamKHR stream, + EGLenum attribute, + EGLint *value); + + EGLBoolean eglQueryStreamu64KHR( + EGLDisplay dpy, + EGLStreamKHR stream, + EGLenum attribute, + EGLuint64KHR *value); + +New functions defined by EGL_KHR_stream_attrib + + EGLStreamKHR eglCreateStreamAttribKHR( + EGLDisplay dpy, + const EGLAttrib *attrib_list); + + EGLBoolean eglSetStreamAttribKHR( + EGLDisplay dpy, + EGLStreamKHR stream, + EGLenum attribute, + EGLAttrib value); + + EGLBoolean eglQueryStreamAttribKHR( + EGLDisplay dpy, + EGLStreamKHR stream, + EGLenum attribute, + EGLAttrib *value); + + EGLBoolean eglStreamConsumerAcquireAttribKHR( + EGLDisplay dpy, + EGLStreamKHR stream + const EGLAttrib *attrib_list); + + EGLBoolean eglStreamConsumerReleaseAttribKHR( + EGLDisplay dpy, + EGLStreamKHR stream, + const EGLAttrib *attrib_list); + +New Tokens + + This value is returned from eglCreateStreamKHR in the case of an + error. It is an error to attempt to use this value as a parameter + to any EGL or client API function. + + EGL_NO_STREAM_KHR ((EGLStreamKHR)0) + + This enum is accepted as an attribute in the <attrib_list> parameter + of eglCreateStreamKHR and as the <attribute> parameter of + eglStreamAttribKHR, eglSetStreamAttribKHR, eglQueryStreamKHR and + eglQueryStreamAttribKHR. + + EGL_CONSUMER_LATENCY_USEC_KHR 0x3210 + + These enums are accepted as the <attribute> parameter of + eglQueryStreamu64KHR. + + EGL_PRODUCER_FRAME_KHR 0x3212 + EGL_CONSUMER_FRAME_KHR 0x3213 + + This enum is accepted as the <attribute> parameter of + eglQueryStreamKHR and eglQueryStreamAttribKHR. + + EGL_STREAM_STATE_KHR 0x3214 + + Returned in the <value> parameter of eglQueryStreamKHR or + eglQueryStreamAttribKHR when <attribute> is EGL_STREAM_STATE. + + EGL_STREAM_STATE_CREATED_KHR 0x3215 + EGL_STREAM_STATE_CONNECTING_KHR 0x3216 + EGL_STREAM_STATE_EMPTY_KHR 0x3217 + EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR 0x3218 + EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR 0x3219 + EGL_STREAM_STATE_DISCONNECTED_KHR 0x321A + + These errors may be generated by EGLStream calls. + + EGL_BAD_STREAM_KHR 0x321B + EGL_BAD_STATE_KHR 0x321C + +Add a new section "2.5 Streams" after section "2.4 Shared State" + + EGL allows efficient interoperation between APIs through the + EGLStream object. An EGLStream represents a sequence of image + frames. + + Each EGLStream is associated with a producer that generates image + frames and inserts them into the EGLStream. Each EGLStream is + also associated with a consumer that retrieves image frames from + the EGLStream. + +Add a new section "3.10 EGLStreams" after section "3.9 Posting the +Color Buffer" + + 3.10 EGLStreams + + EGL provides functions to create and destroy EGLStreams, for + querying and setting attributes of EGLStreams, and for connecting + EGLStreams to producers and consumers. + + Each EGLStream may be connected to only one producer and one + consumer. Once an EGLStream is connected to a consumer, it will + be connected to that consumer until the EGLStream is destroyed. + Likewise, once an EGLStream is connected to a producer it will be + connected to that producer until the EGLStream is destroyed. + Further semantics are described for each type of consumer and + producer that can be connected. + +Add subsection 3.10.1 to section "3.10 EGLStreams" + + 3.10.1 Creating an EGLStream + + Call + + EGLStreamKHR eglCreateStreamKHR( + EGLDisplay dpy, + const EGLint *attrib_list); + + to create a new EGLStream. <dpy> specifies the EGLDisplay used for + this operation. The function returns a handle to the created + EGLStream. + + The EGLStream cannot be used until it has been connected to a + consumer and then to a producer (refer to section "3.10.2 + Connecting an EGLStream to a consumer" and section "3.10.3 + Connecting an EGLStream to a producer"). It must be connected to + a consumer before being connected to a producer. + + There is no way for the application to query the size, + colorformat, or number of buffers used in the EGLStream (although + these attributes may be available from the producer's API or the + consumer's API depending on what type of producer/consumer is + connected to the EGLStream). + + The parameter <attrib_list> contains a list of attributes and + values to set for the EGLStream. Attributes not in the list are + set to default values. EGLStream attributes are described in + section "3.10.4 EGLStream Attributes". + + If an error occurs eglCreateStreamKHR will return + EGL_NO_STREAM_KHR and generate an error. + + - EGL_BAD_ATTRIBUTE is generated if any of the parameters in + attrib_list is not a valid EGLStream attribute. + + - EGL_BAD_ACCESS is generated if any of the parameters in + attrib_list is read only. + + - EGL_BAD_PARAMETER is generated if any of the values in + attrib_list is outside the valid range for the attribute. + + - EGL_BAD_ALLOC is generated if not enough resources are + available to create the EGLStream. + + - EGL_BAD_DISPLAY is generated if <dpy> is not a valid, + initialized EGLDisplay. + +If EGL_KHR_stream_attrib is present, add to the end of this section + + Streams may also be created by calling + + EGLStreamKHR eglCreateStreamAttribKHR( + EGLDisplay dpy, + const EGLAttrib *attrib_list); + + This is equivalent to eglCreateStreamKHR, but allows pointer + and handle attributes to be provided on 64-bit systems. + +Add section 3.10.2 to section "3.10 EGLStreams" + + 3.10.2 Connecting an EGLStream to a consumer. + + Before using an EGLStream it must be connected to a consumer. + + Refer to sections 3.10.2.1 and following for different ways to + connect a consumer to an EGLStream. + + Once an EGLStream is connected to a consumer it will remain + connected to the same consumer until the EGLStream is destroyed. + + If the consumer is destroyed then the EGLStream's state will + become EGL_STREAM_STATE_DISCONNECTED_KHR. + + Any attempt to connect an EGLStream which is not in state + EGL_STREAM_STATE_CREATED_KHR will fail and generate an + EGL_BAD_STATE_KHR error. + + When an EGLStream is connected to a consumer its state becomes + EGL_STREAM_STATE_CONNECTING_KHR. + + 3.10.2.1 No way to connect consumer to EGLStream + + EGL does not currently define any mechanisms to connect a consumer + to an EGLStream. These will be added via additional extensions. + + (Example: See extension specification + EGL_KHR_stream_consumer_gltexture) + +If EGL_KHR_stream_attrib is present, add to the end of this section + + 3.10.2.2 Acquiring and releasing consumer frames + + Methods for acquiring frames from a stream and releasing them back + to a stream are dependent on the type of consumer. Some consumers + support calling + + EGLBoolean eglStreamConsumerAcquireAttribKHR( + EGLDisplay dpy, + EGLStreamKHR stream + const EGLAttrib *attrib_list); + + to acquire the next available frame in <stream> and + + EGLBoolean eglStreamConsumerReleaseAttribKHR( + EGLDisplay dpy, + EGLStreamKHR stream, + const EGLAttrib *attrib_list); + + to release a frame back to the stream. + + Not all consumers are required to support either or both of these + functions. Where supported, the specific behavior is defined by the + consumer type, and may be affected by the contents of <attrib_list>. + <attrib_list> must either be NULL or a pointer to a list of + name/value pairs terminated by EGL_NONE. Valid attributes are + listed in tables 3.10.2.1 and 3.10.2.2. + + Attribute Type Section + ------------------------ ---------- ------- + Currently no acquire attributes are defined + + Table 3.10.2.1 EGLStream Consumer Acquire Attributes + + Attribute Type Section + ------------------------ ---------- ------- + Currently no release attributes are defined + + Table 3.10.2.2 EGLStream Consumer Release Attributes + + If no new image frame is available in the stream, + eglStreamConsumerAcquireAtrribKHR may block, retrieve an old frame, + or return an error, as defined by the type of consumer. If one or + more image frames are already acquired by the consumer when + eglStreamConsumerAcquireAttribKHR is called, the behavior is + determined by the type of consumer. + + If successful, eglStreamConsumerAcquireAttribKHR returns EGL_TRUE + and an image frame from <stream> will be bound into the address + space of the consumer as defined for its type. + + On failure, the function returns EGL_FALSE and generates an error. + Additionally, image objects in the consumer's address space may + become invalid, as determined by the consumer type. + + - EGL_BAD_ACCESS is generated if the consumer of <stream> does + not support acquiring frames through + eglStreamConsumerAcquireAttribKHR. + + - EGL_BAD_STATE_KHR is no frame is available for acquisition + after any timeout determined by the consumer. + + - EGL_BAD_ATTRIBUTE is generated if an attribute name in + <attrib_list> is not recognized or is not supported by the + consumer. + + - EGL_BAD_STREAM_KHR is generated if <stream> is not a valid + EGLStream created for <dpy>. + + - EGL_BAD_DISPLAY is generated if <dpy> is not a valid + EGLDisplay. + + - EGL_NOT_INITIALIZED is generated if <dpy> is not initialized. + + Calling eglStreamConsumerReleaseAttribKHR will release a frame held + by the consumer back to the stream. If more than one frame is held + by the consumer, the frame returned is determined by the consumer + type and the contents of <attrib_list>. If no frames are currently + held, the behavior is determined by the consumer type. Once + returned, the consumer may no longer access the contents of the + frame, and attempts to do so will result in errors as determined by + the consumer type. Upon success, eglStreamConsumerReleaseAttribKHR + returns EGL_TRUE. + + If eglStreamConsumerReleaseAttribKHR fails, EGL_FALSE is returned + and an error is generated. + + - EGL_BAD_ACCESS is generated if the consumer of <stream> does + not support releasing frames through + eglStreamConsumerReleaseAttribKHR. + + - EGL_BAD_STATE_KHR is generated if <stream> is not in state + EGL_STREAM_STATE_EMPTY_KHR, + EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR or + EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR. + + - EGL_BAD_ATTRIBUTE is generated if an attribute name in + <attrib_list> is not recognized or is not supported by the + consumer. + + - EGL_BAD_STREAM_KHR is generated if <stream> is not a valid + EGLStream created for <dpy>. + + - EGL_BAD_DISPLAY is generated if <dpy> is not a valid + EGLDisplay. + + - EGL_NOT_INITIALIZED is generated if <dpy> is not initialized. + +If EGL_KHR_stream_consumer_gltexture is present in addition to +EGL_KHR_stream_attrib, the eglStreamConsumerAcquireKHR function is +equivalent to eglStreamConsumerAcquireAttribKHR with <attrib_list> set +to NULL, the eglStreamConsumerReleaseKHR function is equivalent to +eglStreamConsumerReleaseAttribKHR with <attrib_list> set to NULL, and +the definitions provided for those functions define their behavior for +a GL texture consumer. + +Add section 3.10.3 to section "3.10 EGLStreams" + + 3.10.3 Connecting an EGLStream to a producer. + + Before using an EGLStream it must be connected to a producer. The + EGLStream must be connected to a consumer before it may be + connected to a producer. + + The size and colorformat of the images in the EGLStream are + determined by the EGL implementation based on the requirements of + the producer and the consumer. The EGL implementation may + determine these at the time the producer is connected to the + EGLStream, at the time that the first image frame is inserted into + the EGLStream, or any time in between (this is left up to the + implementation). + + It is the responsibility of the producer to convert the images to + a form that the consumer can consume. The producer may negotiate + with the consumer as to what formats and sizes the consumer is + able to consume, but this negotiation (whether it occurs and how + it works) is an implementation detail. If the producer is unable + to convert the images to a form that the consumer can consume then + the attempt to connect the producer to the EGLStream will fail and + generate an EGL_BAD_MATCH error. + + Refer to sections 3.10.3.1 and following for different ways to + connect a producer to an EGLStream. + + Once an EGLStream is connected to a producer it will remain + connected to the same producer until the EGLStream is destroyed. + If the producer is destroyed then the EGLStream's state will + become EGL_STREAM_STATE_DISCONNECTED_KHR (refer to "3.10.4.3 + EGL_STREAM_STATE_KHR Attribute"). + + Any attempt to connect an EGLStream which is not in state + EGL_STREAM_STATE_CONNECTING_KHR will fail and generate an + EGL_BAD_STATE_KHR error. + + When an EGLStream is connected to a producer its state becomes + EGL_STREAM_STATE_EMPTY_KHR. At this point the producer may begin + inserting image frames and the consumer may begin consuming image + frames, so the state may immediately change to + EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR and/or + EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR. + + 3.10.3.1 No way to connect producer to EGLStream + + EGL does not currently define any mechanisms to connect a producer + to an EGLStream. These will be added via additional extensions. + + (For example see extension specifications + EGL_KHR_stream_producer_eglsurface + EGL_KHR_stream_producer_aldatalocator + OpenMAX_AL_EGLStream_DataLocator + .) + +Add section 3.10.4 to section "3.10 EGLStreams" + + 3.10.4 EGLStream Attributes + + Each EGLStream contains a set of attributes and values as + described in table 3.10.4.4. Each attribute has a type and a + value and is either read-only (ro), read/write (rw) or initialize + only (io - meaning it may be set in the attrib_list but not + changed once the EGLStream is created). + + Attribute Read/Write Type Section + -------------------------- ---------- ------ -------- + EGL_STREAM_STATE_KHR ro EGLint 3.10.4.3 + EGL_PRODUCER_FRAME_KHR ro EGLuint64KHR 3.10.4.4 + EGL_CONSUMER_FRAME_KHR ro EGLuint64KHR 3.10.4.5 + EGL_CONSUMER_LATENCY_USEC_KHR rw EGLint 3.10.4.6 + + Table 3.10.4.4 EGLStream Attributes + + 3.10.4.1 Setting EGLStream Attributes + + Call + + EGLBoolean eglStreamAttribKHR( + EGLDisplay dpy, + EGLStreamKHR stream, + EGLint attribute, + EGLint value); + + to set the value of an attribute for an EGLStream. The <value> is + the new value for <attribute>. Only read/write (rw) attributes + with type EGLint may be set with eglStreamAttribKHR (see "Table + 3.10.4.4 EGLStream Attributes"). + + If an error occurs, EGL_FALSE is returned and an error is + generated. + + - EGL_BAD_STATE_KHR is generated if <stream> is in + EGL_STREAM_STATE_DISCONNECTED_KHR state. + + - EGL_BAD_ATTRIBUTE is generated if <attribute> is not a valid + EGLStream attribute. + + - EGL_BAD_ACCESS is generated if <attribute> is read only. + + - EGL_BAD_PARAMETER is generated if value is outside the valid + range for <attribute>. + + - EGL_BAD_STREAM_KHR is generated if <stream> is not a valid + EGLStream created for <dpy>. + + - EGL_BAD_DISPLAY is generated if <dpy> is not a valid, + initialized EGLDisplay. + + 3.10.4.2 Querying EGLStream Attributes + + Call + + EGLBoolean eglQueryStreamKHR( + EGLDisplay dpy, + EGLStreamKHR stream, + EGLint attribute, + EGLint *value); + + to query the value of an EGLStream's attribute with type EGLint + and call + + EGLBoolean eglQueryStreamu64KHR( + EGLDisplay dpy, + EGLStreamKHR stream, + EGLenum attribute, + EGLuint64KHR *value); + + to query the value of an EGLStream's attribute with type + EGLuint64KHR. + + If an error occurs EGL_FALSE is returned and an error is + generated. + + - EGL_BAD_STREAM_KHR is generated if <stream> is not a valid + EGLStream created for <dpy>. + + - EGL_BAD_ATTRIBUTE is generated by eglQueryStreamKHR if + <attribute> is not a valid EGLStream attribute with type + EGLint. + + - EGL_BAD_ATTRIBUTE is generated by eglQueryStreamu64KHR if + <attribute> is not a valid EGLStream attribute with type + EGLuint64KHR. + + 3.10.4.3 EGL_STREAM_STATE_KHR Attribute + + The EGL_STREAM_STATE_KHR attribute is read only. It indicates the + state of the EGLStream. The EGLStream may be in one of the + following states: + + - EGL_STREAM_STATE_CREATED_KHR - The EGLStream has been created + but not yet connected to a producer or a consumer. + + - EGL_STREAM_STATE_CONNECTING_KHR - The EGLStream has been + connected to a consumer but not yet connected to a producer. + + - EGL_STREAM_STATE_EMPTY_KHR - the EGLStream has been connected + to a consumer and a producer, but the producer has not yet + inserted any image frames. + + - EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR - the producer has + inserted at least one image frame that the consumer has not + yet retrieved. + + - EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR - the producer has + inserted at least one image frame, and the consumer has + already retrieved the most recently inserted image frame. + + - EGL_STREAM_STATE_DISCONNECTED_KHR - either the producer or the + consumer (or both) are no longer connected to the EGLStream + (e.g. because they have been destroyed). Once the + EGLStream is in this state it will remain in this state + until the EGLStream is destroyed. In this state only + eglQueryStreamKHR and eglDestroyStreamKHR are valid + operations. + + Only the following state transitions may occur: + + -> EGL_STREAM_STATE_CREATED_KHR + A new EGLStream is created in this state. + + EGL_STREAM_STATE_CREATED_KHR -> + EGL_STREAM_STATE_CONNECTING_KHR + Occurs when a consumer is connected to the EGLStream. + + EGL_STREAM_STATE_CONNECTING_KHR -> + EGL_STREAM_STATE_EMPTY_KHR + Occurs when a producer is connected to the EGLStream. + + EGL_STREAM_STATE_EMPTY_KHR -> + EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR + Occurs the first time the producer inserts an image frame. + + EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR -> + EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR + Occurs when the consumer begins examining a newly inserted + image frame. + + EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR -> + EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR + Occurs when the producer inserts a new image frame. + + * -> + EGL_STREAM_STATE_DISCONNECTED_KHR + Occurs when the producer or consumer is destroyed or is + otherwise unable to function normally. + + + 3.10.4.4 EGL_PRODUCER_FRAME_KHR Attribute + + The EGL_PRODUCER_FRAME_KHR attribute indicates how many image + frames have been inserted into the EGLStream by the producer. + This is also known as the "frame number" of the most recently + inserted frame (where the first frame inserted has a frame number + of 1). When EGL_STREAM_STATE_KHR is EGL_STREAM_STATE_CREATED_KHR, + EGL_STREAM_STATE_CONNECTING_KHR, or EGL_STREAM_STATE_EMPTY_KHR + then this value is 0. This value will wrap back to 0 after + about 10 million millennia. + + 3.10.4.4 EGL_CONSUMER_FRAME_KHR Attribute + + The EGL_CONSUMER_FRAME_KHR attribute indicates the frame number of + the image frame that the consumer most recently retrieved. This is + the value that EGL_PRODUCER_FRAME_KHR contained just after this + image frame was inserted into the EGLStream. + + 3.10.4.5 EGL_CONSUMER_LATENCY_USEC_KHR Attribute + + This attribute indicates the number of microseconds that elapse (on + average) from the time that an image frame is inserted into the + EGLStream by the producer until the image frame is visible to the + user. + + It is the responsibility of the consumer to set this value. Some + types of consumers may simply set this value to zero or an + implementation constant value. Other consumers may adjust this + value dynamically as conditions change. + + It is the responsibility of the producer to use this information to + insert image frames into the EGLStream at an appropriate time. + The producer should insert each image frame into the stream at the + time that frame should appear to the user MINUS the + EGL_CONSUMER_LATENCY_USEC_KHR value. Some types of producers may + ignore this value. + + The application may modify this value to adjust the timing of the + stream (e.g. to make video frames coincide with an audio track + under direction from a user). However the value set by the + application may be overridden by some consumers that dynamically + adjust the value. This will be noted in the description of + consumers which do this. + +If EGL_KHR_stream_attrib is present, add to the end of section "3.10.4.1 +Setting EGLStream Attributes" + + Attributes may also be set by calling + + EGLBoolean eglSetStreamAttribKHR( + EGLDisplay dpy, + EGLStreamKHR stream, + EGLenum attribute, + EGLAttrib value); + + This is equivalent to eglStreamAttribKHR, but allows attributes + with pointer and handle types, in addition to EGLint. + +If EGL_KHR_stream_attrib is present, add to the end of section "3.10.4.2 +Querying EGLStream Attributes" + + Attributes may also be queried by calling + + EGLBoolean eglQueryStreamAttribKHR( + EGLDisplay dpy, + EGLStreamKHR stream, + EGLenum attribute, + EGLAttrib *value); + + This is equivalent to eglQueryStreamKHR, but allows attributes with + pointer and handle types, in addition to EGLint. + +Add sections 3.10.5 and 3.10.6 to section "3.10 EGLStreams" + + 3.10.5 EGLStream operation + + 3.10.5.1 EGLStream operation in mailbox mode + + The EGLStream conceptually operates as a mailbox. + + When the producer has a new image frame it empties the mailbox and + inserts the new image frame into the mailbox. If the image frame + is intended to be displayed at time T then the producer must + insert it into the EGLStream at time + T - EGL_CONSUMER_LATENCY_USEC_KHR + + The consumer retrieves the image frame from the mailbox and + examines it. When the consumer is finished examining the image + frame it is either placed back in the mailbox (if the mailbox is + empty) or discarded (if the mailbox is not empty). + + This operation implies 2 things: + + - If the consumer consumes frames slower than the producer + inserts frames, then some frames may be lost (never seen by + the consumer). + + - If the consumer consumes frames faster than the producer + inserts frames, then the consumer may see some frames more + than once. + + Some details of EGLStream operation are dependent on the type of + producer and consumer that are connected to it. Refer to the + documentation for the producer and consumer for more details + (section 3.10.2.* and 3.10.3.*). + + + 3.10.6 Destroying an EGLStream + + Call + + EGLBoolean eglDestroyStreamKHR( + EGLDisplay dpy, + EGLStreamKHR stream); + + to mark an EGLStream for deletion. After this call returns the + <stream> will no longer be a valid stream handle. The resources + associated with the EGLStream may not be deleted until the + producer and consumer have released their references to the + resources (if any). Exactly how this is done is dependent on the + type of consumer and producer that is connected to the EGLStream. + + If an error occurs, EGL_FALSE is returned and an error is + generated. + + - EGL_BAD_STREAM_KHR is generated if <stream> is not a valid + EGLStream created for <dpy>. + + +Issues + 1. Are EGL_WIDTH and EGL_HEIGHT parameters needed? + + RESOLVED: No. The width and height of images managed by the + stream are determined by the producer. No application access + to the size is currently required. + + 2. Is EGL_BUFFER_SHOW_ALL_KHR required, or should the stream always + act as EGL_BUFFER_REPLACE_KHR? + + RESOLVED: this has been removed. The old + EGL_BUFFER_SHOW_ALL_KHR behavior is described in a separate + extension: EGL_KHR_stream_fifo + + 3. What are the exact semantics of the producer? + + RESOLVED: The exact semantics vary depending on the type of + producer. Refer to the extension that defines the type of + producer for more information. + + In general, the producer is responsible for inserting image + frames into the EGLStream at the correct time. The correct + time depends on how the image frames are being created and on + the value of EGL_CONSUMER_LATENCY_USEC_KHR. + + 4. What are the exact semantics of the consumer? + + RESOLVED: The exact semantics vary depending on the type of + consumer. Refer to the extension that defines the type of + consumer for more information. + + In general, the consumer is responsible for retrieving image + frames from the EGLStream when they become available. The + consumer is also responsible for setting the + EGL_CONSUMER_LATENCY_USEC_KHR when that is possible. + + 5. When will the EGLStream resources be deleted? + + RESOLVED: this depends on the type of consumer and producer. + Refer to the description of the consumer and producer (e.g. in + the extension that describes them). + + 6. How does A/V sync work? + + RESOLVED: The producer is responsible for A/V sync, but the + consumer needs to help. The consumer indicates the latency + (the average time that it takes the consumer to retrieve an + image from the EGLStream and place it on the display screen) + by setting the EGL_CONSUMER_LATENCY_USEC_KHR. The producer + uses knowledge about the audio stream to determine the correct + time to display an image frame, and inserts the image frame at + that time MINUS the EGL_CONSUMER_LATENCY_USEC_KHR. + + 7. What if the consumer cannot determine the latency? + + RESOLVED: If the consumer does not set the + EGL_CONSUMER_LATENCY_USEC_KHR attribute then its default value + will be used. This default value is implementation defined + and may be zero. See the description of the specific type of + consumer you are using (e.g. the extension that defines it) + for more details related to that consumer. + + 8. What colorformats are supported by EGLStream + + RESOLVED: No specific formats are required, but it is expected + that this work with the main YUV formats supported by the + platform's video HW and the main RGB(A) formats supported by + the platform's OpenGL (ES) hardware. It is the responsibility + of the producer to negotiate a format that will work with the + consumer. If the internal formats supported by the producer + do not coincide with the internal formats supported by the + consumer then the producer may choose to convert to a format + that the consumer understands, or it may choose to fail and + generate an error when an attempt is made to connect it to the + EGLStream. Exactly which it does for which formats is further + discussed in the producer endpoint documentation (refer to the + extension that describes the producer endpoint). + + 9. Is any EGLImage extension required by this extension? + + RESOLVED: No. This extension may be implemented using some of + the same code that is used to implement EGLImages, but there + is no dependency on EGLImages. + + 10. Why describe the "io" attribute type if no attributes use it. + + RESOLVED: Future extensions will add attributes of "io" type + (initialize only - meaning they can be set in the attribute + list when creating the EGLStream, but not modified once the + EGLStream is created). Rather than requiring each such + extension to describe the "io" type (and possibly getting + slightly different definitions or types in different + extensions) the "io" type is defined here so that other + extensions can easily use it. This helps layered + extensions to all use the same language. + + +Revision History + + #27 (May 23, 2016) Daniel Kartch + - For compatibility with EGL 1.5 and support of 64-bit + platforms, add EGL_KHR_stream_attrib extension with variants + of original functions that accept attributes of type + EGLAttrib. + - Corrected line length violations. + + #26 (July 12, 2012) Acorn Pooley + - Fix error in description of consumer latency. + + #25 (October 12, 2011) Acorn Pooley + - Add issue 10 + + #24 (October 11, 2011) Acorn Pooley + - add error condition to eglDestroyStreamKHR + + #23 (October 5, 2011) Acorn Pooley + - refer to related EGL_KHR_... extension specs rather than + EGL_NV_... ones. + + #22 (September 27, 2011) Acorn Pooley + - Fix enum value for EGL_STREAM_STATE_KHR (bug 8064) + + #21 (September 27, 2011) Acorn Pooley + - Assign enum values (bug 8064) + + #20 (September 23, 2011) Acorn Pooley + - Rename EGL_NO_IMAGE_STREAM_KHR to EGL_NO_STREAM_KHR + + #19 (Aug 3, 2011) Acorn Pooley + - fix some error conditions + + #18 (Aug 2, 2011) Acorn Pooley + - Add eglQueryStreamu64KHR + - add EGLuint64KHR + - make EGL_PRODUCER_FRAME_KHR and EGL_CONSUMER_FRAME_KHR 64 + bit. + + #17 (Aug 2, 2011) Acorn Pooley + - fix grammar + + #16 (July 6, 2011) Acorn Pooley + - rename from EGL_KHR_image_stream to EGL_KHR_stream + + #15 (June 29, 2011) Acorn Pooley + - major re-write + - remove EGL_SWAP_MODE_KHR and EGL_BUFFER_SHOW_ALL_KHR + - add new functions: + eglStreamAttribKHR + eglQueryStreamKHR + - add new attributes: + EGL_CONSUMER_LATENCY_USEC_KHR + EGL_PRODUCER_FRAME_KHR + EGL_CONSUMER_FRAME_KHR + EGL_STREAM_STATE_KHR + - add concept of EGL_STREAM_STATE_KHR + - add new error: + EGL_BAD_STATE_KHR + - add more thorough overview section + - add description of buffering + - place the functions in section 3 of the spec (were in + section 2) + - mention some of the consumer and producer specs that may be + needed to make use of this extension. + - remove very old issues that no longer make any sense + - add new issues and resolutions + + #14 (June 4, 2010) Greg Prisament + - fix minor typo + + #13 (June 2, 2010) Marcus Lorentzon + - add EGL enum values + + #12 (May 21, 2010) Marcus Lorentzon + - add clarifications on swap modes + + #11 (April 13, 2010) Marcus Lorentzon + - fix tyops + - make eglDestroyStream return EGLBoolean, not void + + #10 (March 17, 2010) Marcus Lorentzon + - fix typo + - remove obsolete text + - update issue 2 resolution + + #9 (December 15, 2009) Marcus Lorentzon + - move EGL_IMAGE_USE_* attributes to the endpoint extension + - resolved issue 5 + + #8 (December 6, 2009) Marcus Lorentzon + - remove EGL_INIT_COLOR_KHR + - relax the definition of the Producer to allow not only video + frames to be generated + - clean up the language of recently produced, supplied, pending + images + + #7 (October 19, 2009) Acorn Pooley + - Update based on comments from Robert and Bruce + - remove mention of OpenWF + - make EGL_BUFFER_REPLACE_KHR be the default EGL_SWAP_MODE_KHR + - add issue 5 + - remove EGLAPI and EGLAPIENTRY + + #6 (September 16, 2009) Acorn Pooley + - remove EGL_WIDTH and EGL_HEIGHT parameters + - add issue 4 + - clarify swap modes + - other clarifications and simplifications + + #5 (July 2, 2009) Acorn Pooley + - remove reference to no-longer-existing <images> parameter. + - mention dependancy on EGL_KHR_image_uses extension. + - add description of EGL_IMAGE_USE_AS_* enums. + + #4 (June 3, 2009) Acorn Pooley + - Fix typos: change old EGLImageStream occurances to EGLStream + + #3 (April 22, 2009) Marcus Lorentzon + - Updated revide comments + - Removed external image support + + #2 (March 30, 2009) Marcus Lorentzon + - Replaced image surface with image stream + + #1 (February 21, 2009) Marcus Lorentzon + - Initial draft + +# vim:ai:ts=4:sts=4:expandtab:textwidth=70 diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_stream_consumer_gltexture.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_stream_consumer_gltexture.txt new file mode 100644 index 0000000..e29551a --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_stream_consumer_gltexture.txt @@ -0,0 +1,402 @@ +Name + + KHR_stream_consumer_gltexture + +Name Strings + + EGL_KHR_stream_consumer_gltexture + +Contributors + + Acorn Pooley + Jamie Gennis + Marcus Lorentzon + +Contacts + + Acorn Pooley, NVIDIA (apooley 'at' nvidia.com) + +Notice + + Copyright (c) 2011-2013 The Khronos Group Inc. Copyright terms at + http://www.khronos.org/registry/speccopyright.html + +Status + + Complete. + Approved by the Khronos Board of Promoters on December 2, 2011. + +Version + + Version 11, June 18, 2012 + +Number + + EGL Extension #33 + +Dependencies + + Requires EGL 1.2. + Requires OpenGL ES 1.1 or OpenGL ES 2.0. + + Requires the EGL_KHR_stream extension. + Requires the GL_NV_EGL_stream_consumer_external extension. + +Overview + + This extension allows an OpenGL(ES) texture to be connected to an + EGLStream as its consumer. Image frames from the EGLStream can be + 'latched' into the texture as the contents of the texture. This + is equivalent to copying the image into the texture, but on most + implementations a copy is not needed so this is faster. + +New Procedures and Functions + + EGLBoolean eglStreamConsumerGLTextureExternalKHR( + EGLDisplay dpy, + EGLStreamKHR stream) + + EGLBoolean eglStreamConsumerAcquireKHR( + EGLDisplay dpy, + EGLStreamKHR stream); + + EGLBoolean eglStreamConsumerReleaseKHR( + EGLDisplay dpy, + EGLStreamKHR stream); + +New Tokens + + Accepted as an attribute in the <attrib_list> parameter of + eglCreateStreamKHR and as the <attribute> parameter of + eglStreamAttribKHR and eglQueryStreamKHR + + EGL_CONSUMER_ACQUIRE_TIMEOUT_USEC_KHR 0x321E + +Replace section "3.10.2.1 No way to connect consumer to EGLStream" in +the EGL_KHR_stream extension with this: + + 3.10.2.1 GL Texture External consumer + + Call + + EGLBoolean eglStreamConsumerGLTextureExternalKHR( + EGLDisplay dpy, + EGLStreamKHR stream) + + to connect the texture object currently bound to the active + texture unit's GL_TEXTURE_EXTERNAL_OES texture target in the + OpenGL or OpenGL ES context current to the calling thread as the + consumer of <stream>. + + (Note: Before this can succeed a GL_TEXTURE_EXTERNAL_OES texture + must be bound to the active texture unit of the GL context current + to the calling thread. To create a GL_TEXTURE_EXTERNAL_OES + texture and bind it to the current context, call glBindTexture() + with <target> set to GL_TEXTURE_EXTERNAL_OES and <texture> set to + the name of the GL_TEXTURE_EXTERNAL_OES (which may or may not have + previously been created). This is described in the + GL_NV_EGL_stream_consumer_external extension.) + + On failure EGL_FALSE is returned and an error is generated. + + - EGL_BAD_STATE_KHR is generated if <stream> is not in state + EGL_STREAM_STATE_CREATED_KHR. + + - EGL_BAD_ACCESS is generated if there is no GL context + current to the calling thread. + + - EGL_BAD_ACCESS is generated unless a nonzero texture object + name is bound to the GL_TEXTURE_EXTERNAL_OES texture target + of the GL context current to the calling thread. + + - EGL_BAD_STREAM_KHR is generated if <stream> is not a valid + EGLStreamKHR created for <dpy>. + + - EGL_BAD_DISPLAY is generated if <dpy> is not a valid, + initialized EGLDisplay. + + + On success the texture is connected to the <stream>, <stream> is + placed in the EGL_STREAM_STATE_CONNECTING_KHR state, and EGL_TRUE is + returned. + + If the texture is later deleted, connected to a different + EGLStream, or connected to an EGLImage, then <stream> will be + placed into the EGL_STREAM_STATE_DISCONNECTED_KHR state. + + If the <stream> is later destroyed then the texture will be + "incomplete" until it is connected to a new EGLStream, connected + to a new EGLImage, or deleted. + + + Call + + EGLBoolean eglStreamConsumerAcquireKHR( + EGLDisplay dpy, + EGLStreamKHR stream); + + to "latch" the most recent image frame from <stream> into the + texture that is the consumer of <stream>. The GLES context + containing the texture must be bound to the current thread. If + the GLES texture is also used in shared contexts current to other + threads then the texture must be re-bound in those contexts to + guarantee the new texture is used. + + eglStreamConsumerAcquireKHR will block until either the timeout + specified by EGL_CONSUMER_ACQUIRE_TIMEOUT_USEC_KHR expires, or the + value of EGL_BAD_STATE_KHR is neither EGL_STREAM_STATE_EMPTY_KHR nor + EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR (whichever comes first). + + Blocking effectively waits until a new image frame (that has never + been consumed) is available in the EGLStream. By default the + timeout is zero and the function does not block. + + eglStreamConsumerAcquireKHR returns EGL_TRUE if an image frame was + successfully latched into the texture object. + + If the producer has not inserted any new image frames since the + last call to eglStreamConsumerAcquireKHR then + eglStreamConsumerAcquireKHR will "latch" the same image frame it + latched last time eglStreamConsumerAcquireKHR was called. If the + producer has inserted one new image frame since the last call to + eglStreamConsumerAcquireKHR then eglStreamConsumerAcquireKHR will + "latch" the newly inserted image frame. If the producer has + inserted more than one new image frame since the last call to + eglStreamConsumerAcquireKHR then all but the most recently + inserted image frames are discarded and the + eglStreamConsumerAcquireKHR will "latch" the most recently + inserted image frame. + + The application can use the value of EGL_CONSUMER_FRAME_KHR to + identify which image frame was actually latched. + + On failure the texture becomes "incomplete", eglStreamConsumerAcquireKHR + returns EGL_FALSE, and an error is generated. + + - EGL_BAD_STATE_KHR is generated if <stream> is not in state + EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR or + EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR. + + - EGL_BAD_ACCESS is generated if there is no GL context + current to the calling thread, or if the GL context current + to the calling thread does not contain a texture that is + connected as the consumer of the EGLStream. + + - EGL_BAD_STREAM_KHR is generated if <stream> is not a valid + EGLStream created for <dpy>. + + - EGL_BAD_DISPLAY is generated if <dpy> is not a valid, + initialized EGLDisplay. + + + After using the texture call + + EGLBoolean eglStreamConsumerReleaseKHR( + EGLDisplay dpy, + EGLStreamKHR stream); + + to release the image frame back to the stream. + eglStreamConsumerReleaseKHR() will prevent the EGLStream and + producer from re-using and/or modifying the image frame until all + preceding GL commands that use the image frame as a texture have + completed. If eglStreamConsumerAcquireKHR() is called twice on the + same EGLStream without an intervening call to + eglStreamConsumerReleaseKHR() then eglStreamConsumerReleaseKHR() is + implicitly called at the start of eglStreamConsumerAcquireKHR(). + + After successfully calling eglStreamConsumerReleaseKHR the texture + becomes "incomplete". + + If eglStreamConsumerReleaseKHR is called twice without a successful + intervening call to eglStreamConsumerAcquireKHR, or called with no + previous call to eglStreamConsumerAcquireKHR, then the call does + nothing and the texture remains in "incomplete" state. This is + not an error. + + If eglStreamConsumerReleaseKHR fails EGL_FALSE is returned and an error is + generated. + + - EGL_BAD_STATE_KHR is generated if <stream> is not in state + EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR or + EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR. + + - EGL_BAD_ACCESS is generated if there is no GL context + current to the calling thread, or if the GL context current + to the calling thread does not contain the texture to which + the EGLStream is connected. + + - EGL_BAD_STREAM_KHR is generated if <stream> is not a valid + EGLStream created for <dpy>. + + - EGL_BAD_DISPLAY is generated if <dpy> is not a valid, + initialized EGLDisplay. + + + The application should estimate the time that will elapse from the + time a new frame becomes available (i.e. the state becomes + EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR) and the time the frame + is presented to the user. The application should set this as the + value of the EGL_CONSUMER_LATENCY_USEC attribute by calling + eglStreamAttribKHR(). The value will depend on the complexity of + the scene being rendered and the platform that the app is running + on. It may be difficult to estimate except by experimentation on + a specific platform. The default value is implementation + dependent and may be a good enough estimate for some situations. + If the estimate changes over time the application may modify the + value of EGL_CONSUMER_LATENCY_USEC. + + If the EGLStream is deleted while an image frame is acquired (i.e. + after calling eglStreamConsumerAcquireKHR and before calling + eglStreamConsumerReleaseKHR) then the EGLStream resources will not + be freed until the acquired image frame is released. However it + is an error to call eglStreamConsumerReleaseKHR after deleting the + EGLStream because <stream> is no longer a valid handle. In this + situation the image can be released (and the EGLStream resources + freed) by doing any one of + - deleting the GL_TEXTURE_EXTERNAL (call glDeleteTextures) + - connecting the GL_TEXTURE_EXTERNAL to another EGLStream + (call eglStreamConsumerGLTextureExternalKHR) + - connecting the GL_TEXTURE_EXTERNAL to an EGLImage (if the + GL_OES_EGL_image_external extension is supported, call + glEGLImageTargetTexture2DOES) + +Add a new subsection 3.10.4.6 at the end of section "3.10.4 EGLStream +Attributes" in the EGL_KHR_stream extension spec: + + 3.10.4.6 EGL_CONSUMER_ACQUIRE_TIMEOUT_USEC_KHR Attribute + + This attribute is read/write. The default value is 0. It + indicates the maximum amount of time (in microseconds) that + eglStreamConsumerAcquireKHR should block. If 0 (the default) it + will not block at all. If negative it will block indefinitely. + +Issues + 1. How to notify the app when a new image is available + - callback? + - pro: easy to use + - con: introduces extra threads into EGL which does not define such + behavior now - would have to define a lot of semantics (e.g. what + can you call from the callback?) + - EGL_KHR_reusable_sync signaled? + - this is how EGL_KHR_stream_consumer_endpoint does it + - pro: simpler to specify + - pro: easy to use if that is all you are waiting for + - con: difficult to wait on this AND other events simultaneously? + - blocking call to eglStreamConsumerAcquireKHR? + + RESOLVED: Use the EGL_CONSUMER_ACQUIRE_TIMEOUT_USEC_KHR to make + eglStreamConsumerAcquireKHR blocking if desired. Additional + mechanisms can be added as layered extensions. + + 2. What to call this extension? + EGL_NV_stream_consumer_gltexture + EGL_EXT_stream_consumer_gltexture + EGL_KHR_stream_consumer_gltexture + EGL_KHR_stream_consumer_gltexture_external + + RESOLVED: EGL_KHR_stream_consumer_gltexture + + 3. Should it be possible to connect an EGLStream to this consumer + (texture), and then later reconnect the same stream to a different + consumer? + + RESOLVED: no + + There may be reasons to allow this later, but for the time being + there is no use for this. Adding this functionality can be + considered in the future with a layered extension. + + 4. Do we need both this extension and + GL_NV_EGL_stream_consumer_external? Should we just have one + extension that takes the place of both? If so should it be an + EGL or a GL extension? + + UNRESOLVED + + SUGGESTION: need both + + See issue 1 in GL_NV_EGL_stream_consumer_external.txt + + 5. What happens if the EGLStream is deleted while the consumer + has an image acquired? + + This case is a problem because after the EGLStream is deleted + the EGLStreamKHR handle is no longer valid, which means + eglStreamConsumerReleaseKHR cannot be called (because it would + return EGL_BAD_STREAM). + + Possible resolutions: + + A) Do not allow the EGLStream to be deleted while an image is + acquired. + + B) Allow the EGLStream to be deleted. Allow the EGLStreamKHR + handle to be used in a call to eglStreamConsumerReleaseKHR() + after it has been deleted. + + C) Allow the EGLStream to be deleted. It is an error to call + eglStreamConsumerReleaseKHR() after the stream is deleted. To + release the image the app must + - delete the GL_TEXTURE_EXTERNAL texture object + or - connect another EGLStream to the GL_TEXTURE_EXTERNAL + texture object + or - connect an EGLImage to the GL_TEXTURE_EXTERNAL + texture object + + D) Make the call to EGLStream implicitly call + eglStreamConsumerReleaseKHR if an image is acquired. This + requires the GL context is current to the thread that deletes + the EGLStream. + + E) Make the call to EGLStream implicitly call + eglStreamConsumerReleaseKHR if an image is acquired, and state + that this has to work even if the GL context is current to a + different thread or not current to any thread. + + Pros/cons: + - B violates EGL object handle lifetime policies + - E is hard/impossible to implement on some systems + - D makes deletion fail for complicated reasons + - A makes deletion fail for less complicated reasons + + RESOLVED: option C + +Revision History + + #11 (June 18. 2012) Acorn Pooley + - Replace EGLStream with EGLStreamKHR in function prototypes. + + #10 (October 12, 2011) Acorn Pooley + - Fix confusing error in eglStreamConsumerAcquireKHR description. + + #9 (October 4, 2011) Acorn Pooley + - Convert from an NV extension to a KHR extension + + #8 (September 30, 2011) Acorn Pooley + - Add issue 5 and clarify EGLStream deletion while image is + acquired. + + #7 (September 27, 2011) Acorn Pooley + - Assign enum values (bug 8064) + + #6 (Aug 3, 2011) Acorn Pooley + - rename GL_OES_EGL_stream_external to + GL_NV_EGL_stream_consumer_external + + #5 (Aug 2, 2011) Acorn Pooley + - Add dependency on GL_OES_EGL_stream_external + + #4 (Aug 2, 2011) Acorn Pooley + - Fix spelling and grammar + + #3 (July 6, 2011) Acorn Pooley + - Rename EGL_KHR_image_stream to EGL_KHR_stream + + #2 (June 29, 2011) Acorn Pooley + - change how texture is connected to stream to match + EGL_KHR_stream spec. + - Add EGL_CONSUMER_ACQUIRE_TIMEOUT_USEC_NV + + #1 (April 20, 2011) Acorn Pooley + - initial draft +# vim:ai:ts=4:sts=4:expandtab:textwidth=70 diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_stream_cross_process_fd.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_stream_cross_process_fd.txt new file mode 100644 index 0000000..ecfefd6 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_stream_cross_process_fd.txt @@ -0,0 +1,560 @@ +Name + + KHR_stream_cross_process_fd + +Name Strings + + EGL_KHR_stream_cross_process_fd + +Contributors + + Acorn Pooley + Ian Stewart + +Contacts + + Acorn Pooley, NVIDIA (apooley 'at' nvidia.com) + +Notice + + Copyright (c) 2011-2013 The Khronos Group Inc. Copyright terms at + http://www.khronos.org/registry/speccopyright.html + +Status + + Complete. + Approved by the EGL Working Group on June 6, 2012. + Approved by the Khronos Board of Promoters on July 27, 2012. + +Version + + Version 8 - June 5, 2012 + +Number + + EGL Extension #41 + +Dependencies + + Requires EGL 1.2. + Requires EGL_KHR_stream + + This extension is written based on the wording of the EGL 1.2 + specification. + + This extension interacts with the following extensions if they are + also present: + EGL_KHR_stream_producer_eglsurface + EGL_KHR_stream_consumer_gltexture + EGL_KHR_stream_producer_aldatalocator + EGL_KHR_stream_fifo + +Overview + + This extension allows an EGLStreamKHR object handle to be + duplicated into another process so that the EGLStream producer can + be in one process while the EGLStream consumer can be in another + process. + + Duplicating the EGLStreamKHR object handle into another process is + peformed in 3 steps + + 1) Get a file descriptor associated with the EGLStream. + 2) Duplicate the file descriptor into another process. + 3) Create an EGLStreamKHR from the duplicated file descriptor in + the other process. + + The file descriptor is obtained by calling + eglGetStreamFileDescriptorKHR(). + + Duplicating the file descriptor into another process is outside + the scope of this extension. See issue #1 for an example of how + to do this on a Linux system. + + The EGLStreamKHR object handle is created in the second process by + passing the file descriptor to the + eglCreateStreamFromFileDescriptorKHR() function. This must be + done while the EGLStream is in the EGL_STREAM_STATE_CREATED_KHR + state. + + Once the EGLStreamKHR object handle is created in the second + process, it refers to the same EGLStream as the EGLStreamKHR + object handle in the original process. A consumer can be + associated with the EGLStream from either process. A producer can + be associated with the EGLStream from either process. + +New Types + + Represents a native OS file descriptor. + + typedef int EGLNativeFileDescriptorKHR + +New Procedures and Functions + + EGLNativeFileDescriptorKHR eglGetStreamFileDescriptorKHR( + EGLDisplay dpy, + EGLStreamKHR stream); + + EGLStreamKHR eglCreateStreamFromFileDescriptorKHR( + EGLDisplay dpy, + EGLNativeFileDescriptorKHR file_descriptor); + +New Tokens + + Returned from eglGetStreamFileDescriptorKHR on error. + + #define EGL_NO_FILE_DESCRIPTOR_KHR ((EGLNativeFileDescriptorKHR)(-1)) + +Add a new section just after section "3.10.1 Creating an EGLStream" in +the EGL_KHR_stream extension + + 3.10.1.1 Duplicating an EGLStream from a file descriptor + + Call + + EGLNativeFileDescriptorKHR eglGetStreamFileDescriptorKHR( + EGLDisplay dpy, + EGLStreamKHR stream); + + to create a file descriptor that refers to the EGLStream. + <stream> must be an EGLStream in the EGL_STREAM_STATE_CREATED_KHR + state. eglGetStreamFileDescriptorKHR may be called at most once + for any <stream>. + + On success a file descriptor is returned which can be used + to create a duplicate EGLStreamKHR handle which refers to the same + underlying EGLStream as <stream>. This file descriptor and file + descriptors duplicated from it should only be used in a call to + eglCreateStreamFromFileDescriptorKHR() and/or a call to close(). + In particular reads, writes, and other operations on the file + descriptor result in undefined behavior. + + On failure the functions returns EGL_NO_FILE_DESCRIPTOR_KHR and + generates an error + + - 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 handle created for <dpy>. + + - EGL_BAD_STATE_KHR is generated if <stream> is not in the + EGL_STREAM_STATE_CREATED_KHR state or if + eglGetStreamFileDescriptorKHR() has previously been called + on this <stream>. + + - EGL_BAD_STATE_KHR is generated if <stream> was not created + by eglCreateStreamKHR (e.g. if it was created by + eglCreateStreamFromFileDescriptorKHR). + + The file descriptor returned by eglGetStreamFileDescriptorKHR can + be duplicated into a different process address space using system + specific mechanisms outside the scope of this specification. (For + example, on a Linux system it can be sent over a UNIX domain + socket using sendmsg/recvmsg.) + + Call + + EGLStreamKHR eglCreateStreamFromFileDescriptorKHR( + EGLDisplay dpy, + EGLNativeFileDescriptorKHR file_descriptor); + + to create an EGLStreamKHR handle. <file_descriptor> must be a + file descriptor returned by eglGetStreamFileDescriptorKHR or a + file descriptor duplicated from such a file descriptor (possibly + in a different process). The EGLStream must be in the + EGL_STREAM_STATE_CREATED_KHR or EGL_STREAM_STATE_CONNECTING_KHR + state. + + On success an EGLStreamKHR handle is returned. This EGLStreamKHR + handle refers to the same EGLStream which was used to create the + <file_descriptor> or the file descriptor from which + <file_descriptor> was duplicated. + + After the file descriptor is passed to + eglCreateStreamFromFileDescriptorKHR it may no longer be used to + create a new EGLStream. + + On failure EGL_NO_STREAM_KHR is returned and an error is + generated. + + - EGL_BAD_DISPLAY is generated if <dpy> is not a valid + initialized EGLDisplay + + - EGL_BAD_ATTRIBUTE is generated if <file_descriptor> is + EGL_NO_FILE_DESCRIPTOR_KHR. + + - EGL_BAD_ATTRIBUTE is generated if <file_descriptor> is + not an open file descriptor referring to an EGLStream + created on the same Native Display as <dpy>. + + - EGL_BAD_ATTRIBUTE is generated if <file_descriptor> has + already been used to create a stream handle via a previous + call to eglCreateStreamFromFileDescriptorKHR. + + - EGL_BAD_STATE_KHR is generated if <stream> is not in the + EGL_STREAM_STATE_CREATED_KHR or + EGL_STREAM_STATE_CONNECTING_KHR state. + + The application should close the file descriptor and any file + descriptors duplicated from it once + eglCreateStreamFromFileDescriptorKHR has returned. Open file + descriptors will consume resources until they are closed or until + all processes that hold them open have terminated. Closing the + file descriptors after calling + eglCreateStreamFromFileDescriptorKHR will not affect the + associated EGLStream. If an application calls + eglGetStreamFileDescriptorKHR and then determines that the file + descriptor and/or the EGLStream is no longer needed then it may + (and should) close the file descriptor and destroy the EGLStream + (this is not considered an error). + + If a process which has successfully connected a consumer or + producer to the EGLStream terminates (normally or abnormally) then + the EGLStream state becomes EGL_STREAM_STATE_DISCONNECTED_KHR. + + If a process has created an EGLStreamKHR handle either with + eglCreateStreamKHR or eglCreateStreamFromFileDescriptorKHR but has + not connected a producer or consumer to the stream, and this + process terminates (normally or abnormally) then this has no + effect on the EGLStream. + +Interactions with the EGL_KHR_stream_producer_eglsurface extension. + + The eglCreateStreamProducerSurfaceKHR() function can be called + from either the process that created the original EGLStreamKHR, or + from the process which called eglCreateStreamFromFileDescriptorKHR. + +Interactions with the EGL_KHR_stream_consumer_gltexture extension. + + The eglStreamConsumerGLTextureExternalKHR() function can be called + from either the process that created the original EGLStreamKHR, or + from the process which called + eglCreateStreamFromFileDescriptorKHR. The + eglStreamConsumerAcquireKHR() and eglStreamConsumerReleaseKHR() + functions must be called from the same process that calls + eglStreamConsumerGLTextureExternalKHR() (or else they will fail + and generate an EGL_BAD_ACCESS error). + +Interactions with the EGL_KHR_stream_producer_aldatalocator extension. + + The CreateMediaPlayer() method can be called from either the + process that created the original EGLStreamKHR, or from the + process which called eglCreateStreamFromFileDescriptorKHR. + +Interactions with the EGL_KHR_stream_fifo extension. + + The queries for EGL_STREAM_FIFO_LENGTH_KHR, + EGL_STREAM_TIME_NOW_KHR, EGL_STREAM_TIME_CONSUMER_KHR, and + EGL_STREAM_TIME_PRODUCER_KHR can be made from either process. The + time values returned by the EGL_STREAM_TIME_NOW_KHR query will be + consistent between the two processes (i.e. if queried at the same + time from both processes, the same value (plus or minus some + margin of error) will be returned). + +Interactions with the EGL_NV_stream_cross_process_fd extension. + + These extensions may both exist on the same implementation and + are functionally equivalent. Mixing and matching file descriptors + from one extension with functions from the other is allowed. + +Interactions with the EGL_NV_stream_sync extension. + + The eglCreateStreamSyncNV() function may only be called from a + process which has successfully connected a consumer to the + EGLStream. Otherwise eglCreateStreamSyncNV generates a + EGL_BAD_ACCESS error. + +Issues + 1. How does the application transfer the file descriptor to + another process? + + RESOLVED: This is outside the scope of this extension. The + application can use existing operating system mechanisms for + duplicating the file descriptor into another process. For + example on Linux a file descriptor can be sent over a UNIX + domain socket using the following code (call send_fd() to + send the file descriptor, and receive_fd() in the other + process to receive the file descriptor). (The following code + is placed into the public domain by its author, Acorn Pooley) + + #include <stdio.h> + #include <stdlib.h> + #include <unistd.h> + #include <sys/types.h> + #include <sys/socket.h> + #include <sys/un.h> + + #define FATAL_ERROR() exit(1) + #define SOCKET_NAME "/tmp/example_socket" + + /* Send <fd_to_send> (a file descriptor) to another process */ + /* over a unix domain socket named <socket_name>. */ + /* <socket_name> can be any nonexistant filename. */ + void send_fd(const char *socket_name, int fd_to_send) + { + int sock_fd; + struct sockaddr_un sock_addr; + struct msghdr msg; + struct iovec iov[1]; + char ctrl_buf[CMSG_SPACE(sizeof(int))]; + struct cmsghdr *cmsg = NULL; + + sock_fd = socket(PF_UNIX, SOCK_STREAM, 0); + if (sock_fd < 0) FATAL_ERROR(); + + memset(&sock_addr, 0, sizeof(struct sockaddr_un)); + sock_addr.sun_family = AF_UNIX; + strncpy(sock_addr.sun_path, + socket_name, + sizeof(sock_addr.sun_path)-1); + + while (connect(sock_fd, + (const struct sockaddr*)&sock_addr, + sizeof(struct sockaddr_un))) { + printf("Waiting for reciever\n"); + sleep(1); + } + + memset(&msg, 0, sizeof(msg)); + + iov[0].iov_len = 1; // must send at least 1 byte + iov[0].iov_base = "x"; // any byte value (value ignored) + msg.msg_iov = iov; + msg.msg_iovlen = 1; + + memset(ctrl_buf, 0, sizeof(ctrl_buf)); + msg.msg_control = ctrl_buf; + msg.msg_controllen = sizeof(ctrl_buf); + + cmsg = CMSG_FIRSTHDR(&msg); + cmsg->cmsg_level = SOL_SOCKET; + cmsg->cmsg_type = SCM_RIGHTS; + cmsg->cmsg_len = CMSG_LEN(sizeof(int)); + *((int *) CMSG_DATA(cmsg)) = fd_to_send; + + msg.msg_controllen = cmsg->cmsg_len; + + if (sendmsg(sock_fd, &msg, 0) <= 0) FATAL_ERROR(); + + close(sock_fd); + } + + /* Listen on a unix domain socket named <socket_name> and */ + /* receive a file descriptor from another process. */ + /* Returns the file descriptor. Note: the integer value */ + /* of the file descriptor may be different from the */ + /* integer value in the other process, but the file */ + /* descriptors in each process will refer to the same file */ + /* object in the kernel. */ + int receive_fd(const char *socket_name) + { + int listen_fd; + struct sockaddr_un sock_addr; + int connect_fd; + struct sockaddr_un connect_addr; + socklen_t connect_addr_len = 0; + struct msghdr msg; + struct iovec iov[1]; + char msg_buf[1]; + char ctrl_buf[CMSG_SPACE(sizeof(int))]; + struct cmsghdr *cmsg; + + listen_fd = socket(PF_UNIX, SOCK_STREAM, 0); + if (listen_fd < 0) FATAL_ERROR(); + + unlink(socket_name); + + memset(&sock_addr, 0, sizeof(struct sockaddr_un)); + sock_addr.sun_family = AF_UNIX; + strncpy(sock_addr.sun_path, + socket_name, + sizeof(sock_addr.sun_path)-1); + + if (bind(listen_fd, + (const struct sockaddr*)&sock_addr, + sizeof(struct sockaddr_un))) + FATAL_ERROR(); + + if (listen(listen_fd, 1)) FATAL_ERROR(); + + connect_fd = accept( + listen_fd, + (struct sockaddr *)&connect_addr, + &connect_addr_len); + close(listen_fd); + unlink(socket_name); + if (connect_fd < 0) FATAL_ERROR(); + + memset(&msg, 0, sizeof(msg)); + + iov[0].iov_base = msg_buf; + iov[0].iov_len = sizeof(msg_buf); + msg.msg_iov = iov; + msg.msg_iovlen = 1; + + msg.msg_control = ctrl_buf; + msg.msg_controllen = sizeof(ctrl_buf); + + if (recvmsg(connect_fd, &msg, 0) <= 0) FATAL_ERROR(); + + cmsg = CMSG_FIRSTHDR(&msg); + if (!cmsg) FATAL_ERROR(); + if (cmsg->cmsg_level != SOL_SOCKET) FATAL_ERROR(); + if (cmsg->cmsg_type != SCM_RIGHTS) FATAL_ERROR(); + + return *(int *) CMSG_DATA(cmsg); + } + + 2. Does this extension work with all consumers and all producers? + + RESOLVED: This extension is compatible with + EGL_KHR_stream_producer_eglsurface + EGL_KHR_stream_consumer_gltexture + EGL_KHR_stream_producer_aldatalocator + EGL_KHR_stream_fifo + as described in the Interactions sections. Whether an + EGLStream that has been duplicated into another process will + work with other types of consumers and producers should be + mentioned in the description of those consumers and producers. + + 3. Does EGL create a file descriptor for every EGLStream when the + EGLStream is created, or is the file descriptor be created + when eglGetStreamFileDescriptorKHR is called? + + RESOLVED: This is implementation dependent. However, + recommended behavior is to create the file descriptor when + eglGetStreamFileDescriptorKHR is called. This avoids + polluting the file descriptor namespace (which may have a + limited size on some systems) with descriptors for EGLStreams + which will only be used inside a single process. The + eglGetStreamFileDescriptorKHR function will fail and generate + an EGL_BAD_ALLOC error if it is unable to allocate a file + descriptor for the EGLStream. + + 4. Should the EGLStream be created from the file descriptor with + the existing eglCreateStreamKHR function or with a new + function dedicated to that purpose? + + The advantage of creating a new function is that a new + parameter can be added with a specific type. This is not + really necessary for this extension since a file descriptor is + a small integer which can fit into the EGLint in the + eglCreateStreamKHR attrib_list. However, other similar + extensions may be invented that use other types of handles + (not file descriptors) which may not fit into an EGLint. + Creating a dedicated function allows these other extensions to + use a similar function. + + RESOLVED: Use a different function. + + 5. How does this extension interact with the + EGL_NV_stream_cross_process_fd extension? + + RESOLVED: These extensions may both exist on the same + implementation and are functionally equivalent. Mixing and + matching file descriptors from one extension with functions + from the other is allowed. + + 6. Who should close the file descriptors and when? + + There is no way for the EGL implementation to safely close all + the file descriptors associated with an EGLStream because some + of them may have been created using OS specific duping + mechanisms. Also, the app may need to close a descriptor if + it runs into an error before it is able to call + eglCreateStreamFromFileDescriptorKHR. Therefore the + application will need to close at least some of the created + file descriptors. To make things simple and clear it is + therefore left up to the app to close all the file + descriptors. The app is not *required* to do this, but not + doing so will "leak" file descriptors which will consume + resources until the process terminates. + + Allowing the app to close all file descriptors as soon as + eglCreateStreamFromFileDescriptorKHR returns simplifies the + app (no need to keep track of open file descriptors). + + RESOLVED: Application is responsible for closing all file + descriptors. They can be safely closed as soon as + eglCreateStreamFromFileDescriptorKHR returns. + + 7. What happens when an invalid file descriptor is passed to + eglCreateStreamFromFileDescriptorKHR()? + + RESOLVED: The implementation must detect this and generate an + error. If the file descriptor refers to a file then the + implementation may not modify the file, change the seek + location, or otherwise modify the file descriptor. + + 8. What happens if one process hangs or crashes? + + RESOLVED: If either the consumer's or producer's process + terminates (normally or abnormally) the EGL implementation + must notice this and place the EGLStream in + EGL_STREAM_STATE_DISCONNECTED_KHR state. If the consumer is + blocked in a eglStreamConsumerAcquireKHR() call, the call will + generate an EGL_BAD_STATE_KHR message and return EGL_FALSE. + If the consumer process has created a reusable sync object with + eglCreateStreamSyncNV() and is blocking in a + eglClientWaitSyncKHR() call, the call will block until the + timeout runs out. + + If the producer process "hangs" (e.g. enters an infinite loop, + blocks in a kernel call, etc) then the consumer process will + continue to function. The consumer will continue to use the + last frame that the producer produced. If the producer has + not yet produced a frame then the EGLStream will be in + EGL_STREAM_STATE_EMPTY_KHR state and no frame will be + available. The consumer process can block in some situations: + - If a EGL_CONSUMER_ACQUIRE_TIMEOUT_USEC_KHR is set then + eglStreamConsumerAcquireKHR() will block until the + timeout runs out (or indefinitely if timeout is + negative). + - eglClientWaitSyncKHR() will block until the timeout runs + out. + + If the consumer process "hangs" then the producer process will + continue to function. If the EGLStream has had + EGL_STREAM_FIFO_LENGTH_KHR set to a nonzero value then the + producer will block indefinitely when it fills the fifo and + tries to insert another frame. Otherwise the producer will + not block (as new frames are inserted into the EGLStream old + ones will be discarded). + +Revision History + + #8 (June 5, 2012) Acorn Pooley + - rename from XXX to KHR + + #7 (June 5, 2012) Acorn Pooley + - Add issue 8. + - Better define EGLStream behavior when a process terminates. + - Add Interactions with the EGL_NV_stream_sync extension. + + #6 (April 20, 2012) Ian Stewart + - Fix extension/function names in interactions + - Removed references to NV_stream_sync. + - Changed interactions with NV_stream_cross_process_fd such + that they are interchangeable. + + #5 (April 18, 2012) Acorn Pooley + - Add issue 7 + - define errors generated when passing invalid file descriptors + + #4 (January 29, 2012) Acorn Pooley + - Fork EGL_XXX_stream_cross_process_fd.txt from + EGL_NV_stream_cross_process_fd.txt to make changes suggested + by working group. + - add issues 4, 5, and 6. + + #3 (January 6, 2012) Acorn Pooley + - fix typos (EGLImage -> EGLStream) + + #2 (December 7, 2011) Acorn Pooley + - Upload to Khronos for review + + #1 (September 27, 2011) Acorn Pooley + - Initial draft + +# vim:ai:ts=4:sts=4:expandtab:textwidth=70 diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_stream_fifo.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_stream_fifo.txt new file mode 100644 index 0000000..3d9d985 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_stream_fifo.txt @@ -0,0 +1,433 @@ +Name + + KHR_stream_fifo + +Name Strings + + EGL_KHR_stream_fifo + +Contributors + + Acorn Pooley + +Contacts + + Acorn Pooley, NVIDIA (apooley 'at' nvidia.com) + +Notice + + Copyright (c) 2011-2013 The Khronos Group Inc. Copyright terms at + http://www.khronos.org/registry/speccopyright.html + +Status + + Complete. + Approved by the Khronos Board of Promoters on December 2, 2011. + +Version + + Version 6, October 12, 2011 + +Number + + EGL Extension #36 + +Dependencies + + Requires EGL 1.2. + Requires the EGL_KHR_stream extension. + + This extension is written based on the wording of the EGL 1.2 + specification. + + The EGL_KHR_stream_producer_eglsurface and + EGL_NV_stream_producer_eglsurface extensions affect the wording of + this extension. + + The EGL_KHR_stream_producer_aldatalocator and + EGL_NV_stream_producer_aldatalocator extensions affect the wording + of this extension. + + The EGL_KHR_stream_consumer_gltexture and + EGL_NV_stream_consumer_gltexture extensions affect the wording + of this extension. + +Overview + + This extension allows an EGLStream to operate as a fifo rather + than as a mailbox. + + The EGL_KHR_stream extension defines the EGLStream object. + The EGLStream object works like a 1 entry mailbox, allowing the + consumer to consume the frame that the producer most recently + inserted. If the consumer requests image frames faster than the + producer creates them then it gets the most recent one over and + over until a new one is inserted. If the producer inserts frames + faster than the consumer can consume them then the extra frames + are discarded. The producer is never stalled. + + This extension allows an EGLStream to be placed into fifo mode. + In fifo mode no images are discarded. If the producer attempts to + insert a frame and the fifo is full then the producer will stall + until there is room in the fifo. When the consumer retrieves an + image frame from the EGLStream it will see the image frame that + immediately follows the image frame that it last retrieved (unless + no such frame has been inserted yet in which case it retrieves the + same image frame that it retrieved last time). + + Timing of the EGLStream in mailbox mode, as described by the + EGL_KHR_stream extension, is the responsibility of the + producer (with help from the consumer in the form of the + EGL_CONSUMER_LATENCY_USEC_KHR hint). + + In contrast, timing of an EGLStream in fifo mode is the + responsibility of the consumer. Each image frame in the fifo has + an associated timestamp set by the producer. The consumer can use + this timestamp to determine when the image frame is intended to be + displayed to the user. + + +New Types + + This type represents an absolute time in nanoseconds. + + typedef khronos_utime_nanoseconds_t EGLTimeKHR + +New functions + + EGLBoolean eglQueryStreamTimeKHR( + EGLDisplay dpy, + EGLStreamKHR stream, + EGLenum attribute, + EGLTimeKHR *value); + +New Tokens + + Accepted as an attribute in the <attrib_list> parameter of + eglCreateStreamKHR and as the <attribute> parameter of + eglQueryStreamKHR. + + EGL_STREAM_FIFO_LENGTH_KHR 0x31FC + + These enums are accepted the <attribute> parameter of + eglQueryStreamTimeKHR. + + EGL_STREAM_TIME_NOW_KHR 0x31FD + EGL_STREAM_TIME_CONSUMER_KHR 0x31FE + EGL_STREAM_TIME_PRODUCER_KHR 0x31FF + +Add 4 new entries to "Table 3.10.4.4 EGLStream Attributes" in the +EGL_KHR_stream extension spec: + + Attribute Read/Write Type Section + -------------------------- ---------- ---------- -------- + EGL_STREAM_FIFO_LENGTH_KHR io EGLint 3.10.4.xx + EGL_STREAM_TIME_NOW_KHR ro EGLTimeKHR 3.10.4.xx + EGL_STREAM_TIME_CONSUMER_KHR ro EGLTimeKHR 3.10.4.xx + EGL_STREAM_TIME_PRODUCER_KHR ro EGLTimeKHR 3.10.4.xx + +Add a new paragraph to the end of section "3.10.4.2 Querying EGLStream +Attributes" in the EGL_KHR_stream extension. + + Call + + EGLBoolean eglQueryStreamTimeKHR( + EGLDisplay dpy, + EGLStreamKHR stream, + EGLenum attribute, + EGLTimeKHR *value); + + to query <attribute> from <stream> for attributes whose type is + EGLTimeKHR. + + If an error occurs EGL_FALSE is returned and an error is + generated. + + - EGL_BAD_STREAM_KHR is generated if <stream> is not a valid + EGLStream created for <dpy>. + + - EGL_BAD_ATTRIBUTE is generated if <attribute> is not a valid + EGLStream attribute with type EGLTimeKHR. + + +Add new sections 3.1.4.xx at the end of section "3.10.4 EGLStream +Attributes" in the EGL_KHR_stream extension. + + 3.1.4.x EGL_STREAM_FIFO_LENGTH_KHR Attribute + + The EGL_STREAM_FIFO_LENGTH_KHR may be set in the <attrib_list> + parameter of eglCreateStreamKHR(), but is read-only once the + stream is created. It can be queried with eglQueryStreamKHR(). + Its default value is 0. Setting it to a value less than 0 + generates an EGL_BAD_PARAMETER error. + + When EGL_STREAM_FIFO_LENGTH_KHR is 0 the EGLStream operates in + mailbox mode as described in section "3.10.5.1 EGLStream operation + in mailbox mode" + + When EGL_STREAM_FIFO_LENGTH_KHR is greater than 0 then the + EGLStream operates in fifo mode as described in section "3.10.5.2 + EGLStream operation in fifo mode". + + In fifo mode the EGLStream contains up to N image frames, where N + is the value of the EGL_STREAM_FIFO_LENGTH_KHR attribute. + + The value of EGL_STREAM_FIFO_LENGTH_KHR is independent from the + number of internal buffers used by the producer. The producer may + require some number of internal buffers, but those are in addition + to the fifo buffers described by EGL_STREAM_FIFO_LENGTH_KHR. + + 3.1.4.x+1 EGL_STREAM_TIME_NOW_KHR Attribute + + This indicates the current time. It is measured as the number of + nanoseconds since some arbitrary event (e.g. the last time the + system rebooted). + + 3.1.4.x+2 EGL_STREAM_TIME_CONSUMER_KHR Attribute + + This indicates the timestamp of the image frame that the consumer + most recently consumed (i.e. frame number EGL_CONSUMER_FRAME_KHR). + The frame should first be displayed to the user when + EGL_STREAM_TIME_NOW_KHR matches this value. + + In mailbox mode the timestamp for an image frame is always equal + to the time that the producer inserted the image frame into the + EGLStream, minus the value of EGL_CONSUMER_LATENCY_USEC_KHR. + + In fifo mode the timestamp for an image frame is set by the + producer when it is inserted into the EGLStream. + + The timestamp uses the same time units as EGL_STREAM_TIME_NOW_KHR. + + 3.1.4.x+3 EGL_STREAM_TIME_PRODUCER_KHR Attribute + + This indicates the timestamp of the image frame that the producer + most recently inserted into the EGLStream (i.e. frame number + EGL_PRODUCER_FRAME_KHR). + + +Modify the first sentence of section "3.10.5.1 EGLStream operation in +mailbox mode" in the EGL_KHR_stream extension to: + + When the EGL_STREAM_FIFO_LENGTH_KHR attribute is 0 + then the EGLStream conceptually operates as a mailbox. + + +Add a new section after section "3.10.5.1 EGLStream operation in +mailbox mode" in the EGL_KHR_stream extension. + + 3.10.5.2 EGLStream operation in fifo mode + + When the EGL_STREAM_FIFO_LENGTH_KHR attribute is greater than 0 + then the EGLStream operates in fifo mode. The length of the fifo + is the value of the EGL_STREAM_FIFO_LENGTH_KHR attribute. + + In fifo mode the EGLStream conceptually operates as a fifo. + + When the consumer wants to consume a new image frame, behavior + depends on the state of the EGLStream. If the state is + EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR then the fifo is not + empty and the image frame to consume is removed from the tail of + the fifo. If the state is + EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR then the fifo is empty + and the consumer consumes the same frame that it most recently + consumed. Otherwise there are no image frames available to + consume (behavior in this case is described in the documentation + for each type of consumer - see section "3.10.2 Connecting an + EGLStream to a consumer"). + + If the fifo is empty when the consumer is finished consuming an + image frame then the consumer holds on to the image frame in case + it needs to be consumed again later (this happens if the consumer + wants to consume another image frame before the producer has + inserted a new image frame into the fifo). In this case the state + of the EGLStream will be EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR + until the producer inserts a new image frame (or until the state + becomes EGL_STREAM_STATE_DISCONNECTED_KHR). + + The producer inserts image frames at the head of the fifo. If the + fifo is full (already contains <L> image frames, where <L> is the + value of the EGL_STREAM_FIFO_LENGTH_KHR attribute) then producer + is stalled until the fifo is no longer full. When the fifo is not + empty the EGLStream state is + EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR. + + This operation implies: + + - Frames are never discarded until the consumer has examined + them. + + - If the consumer consumes frames slower than the producer + inserts frames, then the producer will stall. + + - If the consumer consumes frames faster than the producer + inserts frames, then the consumer may see some frames more + than once. + + - The consumer can see each frame exactly once if it always + waits until the stream is in the + EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR state before + retrieving an image from the stream. + + In mailbox mode the producer is responsible for timing. In fifo + mode the consumer is responsible for timing. + + In fifo mode the producer marks each image frame with a timestamp. + The timestamp indicates at what time the image frame should first + be visible to the user. Exactly how a producer sets the timestamp + is described in the documentation for each type of producer. If + the value of an image frame's timestamp is T then the producer + must insert that image frame *before* time + T - EGL_CONSUMER_LATENCY_USEC_KHR + Image frames must be inserted in increasing timestamp order. + + The consumer is responsible for presenting each image frame to the + user at the time indicated by its timestamp. The consumer should + indicate its minimum latency to the producer by setting the + EGL_CONSUMER_LATENCY_USEC_KHR attribute. + + +If the EGL_KHR_stream_producer_eglsurface or +EGL_NV_stream_producer_eglsurface extension is present then add a +paragraph to the end of section "3.10.3.1 Stream Surface Producer" +from that extension: + + If <stream>'s EGL_STREAM_FIFO_LENGTH_KHR value is nonzero then + <stream> operates in fifo mode. Each time the EGLSurface is + passed to eglSwapBuffers() an image frame is inserted into the + fifo. The eglSwapBuffers call sets the timestamp of the image + frame to the time that eglSwapBuffers was called PLUS the value of + the EGL_CONSUMER_LATENCY_USEC_KHR attribute. + +If the EGL_KHR_stream_producer_eglsurface or +EGL_NV_stream_producer_eglsurface extension is present then add a +paragraph to section "3.9.x Posting to a Stream" +from that extension, between the 2nd paragraph (which begins "If +<surface> is the producer of an EGLStream...") and the 3rd paragraph +(which begins "When eglSwapBuffers returns the contents..."): + + If the value of the EGL_STREAM_FIFO_LENGTH_KHR attribute, <L> is + greater than zero, and there are already <L> image frames in the + EGLStream fifo, then the eglSwapBuffers function blocks (does not + return and does not insert the new image frame) until there is + room in the EGLStream fifo (i.e. there are less than <L> image + frames in the fifo). + +If the EGL_KHR_stream_producer_aldatalocator or +EGL_NV_stream_producer_aldatalocator extension is present then replace +the 2nd to last paragraph (the one that starts "The OpenMAX AL object +will use the value of...") of section "3.10.3.1 OpenMAX AL Stream +Producer" from that extension with the following 2 paragraphs: + + If <stream>'s EGL_STREAM_FIFO_LENGTH_KHR value is zero then the + stream operates in mailbox mode. The OpenMAX AL object will use + the value of the EGL_CONSUMER_LATENCY_USEC_KHR attribute of + <stream> to determine when to insert each image frame. If the + EGL_CONSUMER_LATENCY_USEC_KHR attribute is modified (by the + consumer and/or by the application) then then OpenMAX AL object + will adjust its timing within 500 milliseconds of the change. If + an image frame is intended to appear to the user at time T (e.g. + so that it is synchronized with audio) then the OpenMAX AL object + must insert the image frame at time + T - EGL_CONSUMER_LATENCY_USEC_KHR + and set the image frame's timestamp to T. + + If the <stream>'s EGL_STREAM_FIFO_LENGTH_KHR value is nonzero then + <stream> operates in fifo mode. If an image frame is intended to + appear to the user at time T then the OpenMAX AL object will + insert the image frame into the fifo before time + T - EGL_CONSUMER_LATENCY_USEC_KHR + and set the image frame's timestamp to T. + +If the EGL_KHR_stream_consumer_gltexture or +EGL_NV_stream_consumer_gltexture extension is present then replace the +3rd to last paragraph (the one that starts "If the producer has not +inserted any new image frames...") of section "3.10.2.1 GL Texture +External consumer" from that extension with the following 2 +paragraphs: + + When <stream>'s EGL_STREAM_FIFO_LENGTH_KHR value is zero then the + stream operates in mailbox mode. If the producer has not inserted + any new image frames since the last call to + eglStreamConsumerAcquireNV then eglStreamConsumerAcquireNV will + "latch" the same image frame it latched last time + eglStreamConsumerAcquireNV was called. If the producer has + inserted one new image frame since the last call to + eglStreamConsumerAcquireNV then the eglStreamConsumerAcquireNV + will "latch" the newly inserted image frame. If the producer has + inserted more than one new image frame since the last call to + eglStreamConsumerAcquireNV then all but the most recently inserted + image frames are discarded and the producer will "latch" the most + recently inserted image frame. + + When <stream>'s EGL_STREAM_FIFO_LENGTH_KHR value is nonzero then + <stream> operates in fifo mode. Each call to + eglStreamConsumerAcquireNV "latches" the next image frame in the + fifo into the OpenGL texture, removing that image frame from the + fifo. If there are no new image frames in the fifo then + eglStreamConsumerAcquireNV will "latch" the same image frame it + latched last time eglStreamConsumerAcquireNV was called. + + +Issues + 1. Is this extension useful? + + RESOLVED: Yes. Browser vendors and others have expressed + interest. + + 2. Why not include this functionality in the base EGL_KHR_stream + extension? + + RESOLVED: Including it there was confusing. Several + developers interested in EGLStream have thought at first that + they want to use EGLStreams in fifo mode. Later after + thinking about it they realize standard mode (non-fifo or + "mailbox" mode) is more useful. + + Mailbox mode is easier to use and is less confusing for + aldatalocator-producer, gltexture-consumer usecase which was + the primary usecase for the extension at the time it was + devised. + + Trying to describe both mailbox mode and fifo mode in + the same extension made the extension complicated. It was + confusing when the timestamps were useful (only in fifo mode). + It was confusing how the EGL_CONSUMER_LATENCY_USEC_KHR + attribute worked in different modes. + + these problems the fifo functionality was split into this + separate extension. This also allows existing consumer and + producer extensions to be defined in terms of mailbox mode, + simplifying them and making them easier to understand. Then + interactions with fifo mode can be described separately. + + Also, the fifo mode is more complicated to use and implement than + the mailbox mode. It was thought that there might be problems + with the fifo mode that could lead to a new extension + replacing the fifo mode extension. By keeping the fifo mode + functionality segregated into its own extension this would be + easier to accomplish. + +Revision History + + #6 (October 12, 2011) Acorn Pooley + - Clarify fifo mode operation. (Does not change behavior.) + + + #5 (October 11, 2011) Acorn Pooley + - Resolve issue 1 + - fix typos + - add issue 2 + + #4 (September 27, 2011) Acorn Pooley + - Assign enum values (bug 8064) + + #3 (July 6, 2011) Acorn Pooley + - Rename EGL_KHR_image_stream to EGL_KHR_stream + + #2 (version #2 skipped) + + #1 (July 1, 2011) Acorn Pooley + - Initial draft + +# vim:ai:ts=4:sts=4:expandtab:textwidth=70 diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_stream_producer_aldatalocator.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_stream_producer_aldatalocator.txt new file mode 100644 index 0000000..28f8963 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_stream_producer_aldatalocator.txt @@ -0,0 +1,178 @@ +Name + + KHR_stream_producer_aldatalocator + +Name Strings + + EGL_KHR_stream_producer_aldatalocator + +Contributors + + Acorn Pooley + +Contacts + + Acorn Pooley, NVIDIA (apooley 'at' nvidia.com) + +Notice + + Copyright (c) 2011-2013 The Khronos Group Inc. Copyright terms at + http://www.khronos.org/registry/speccopyright.html + +Status + + Complete. + Approved by the Khronos Board of Promoters on December 2, 2011. + +Version + + Version 4, October 4, 2011 + +Number + + EGL Extension #35 + +Dependencies + + Requires EGL 1.2 or later. + Requires OpenMAX AL 1.1 or later. + + Requires the EGL_KHR_stream extension. + Requires the OpenMAX_AL_EGLStream_DataLocator extension. + +Overview + + This extension (in conjunction with the + OpenMAX_AL_EGLStream_DataLocator extension to OpenMAX AL) + allows an OpenMAX AL MediaPlayer object to be connected as the + producer of an EGLStream. + + After the EGLStream is created and connected to a consumer, the + OpenMAX AL MediaPlayer object is created by calling <pEngine>'s + CreateMediaPlayer() method. The <pImageVideoSnk> argument points + to an XADataLocator_EGLStream containing the EGLStreamKHR handle + of the stream. The CreateMediaPlayer() method creates a + MediaPlayer object and connects it as the producer of the + EGLStream. (Note that the pFormat member of the XADataSink + structure is ignored in this case and may be NULL.) + + Once connected the MediaPlayer inserts image frames into the + EGLStream. + +Replace section "3.10.3.1 No way to connect producer to EGLStream" in +the EGL_KHR_stream extension with this: + + 3.10.3.1 OpenMAX AL Stream Producer + + An OpenMAX AL MediaPlayer object can act as a producer for an + EGLStream. First create the EGLStream and connect a consumer to + it so that the EGLStream is in EGL_STREAM_STATE_CONNECTING_KHR + state. + + At this point the application can create an OpenMAX AL MediaPlayer + object as described in the OpenMAX AL specification and the + OpenMAX_AL_EGLStream_DataLocator extension. The application + should create an XADataSink structure with pLocator pointing to an + XADataLocator_EGLStream structure referencing the EGLStream (in + the pEGLStream member) and the EGLDisplay used to create the + EGLStream (in the pEGLDisplay member). The pFormat field of the + XADataSink is ignored and should be NULL. This XADataSink + structure is passed as the <pImageVideoSnk> argument to + <pEngine>'s CreateMediaPlayer() method. + + If the OpenMAX AL implementation is unable to convert image frames + to a format usable by <stream>'s consumer then CreateMediaPlayer + will fail with a XA_RESULT_CONTENT_UNSUPPORTED error. + + After CreateMediaPlayer() has returned successfully, <stream>'s + state will be one of + - EGL_STREAM_STATE_EMPTY_KHR + - EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR + - EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR + and the OpenMAX AL MediaPlayer object returned in <pPlayer> will + be connected as the producer of <stream>. If the MediaPlayer + object is destroyed then <stream>'s state will become + EGL_STREAM_STATE_DISCONNECTED_KHR. + + Image and video frame data generated by the OpenMAX AL object (as + described in the OpenMAX AL spec) are inserted into <stream> (as + described in section "3.10.5 EGLStream operation" of the + EGL_KHR_stream extension). + + The OpenMAX AL object will use the value of the + EGL_CONSUMER_LATENCY_USEC_KHR attribute of <stream> to determine + when to insert each image frame. If the + EGL_CONSUMER_LATENCY_USEC_KHR attribute is modified (by the + consumer and/or by the application) then OpenMAX AL object + will adjust its timing within 500 milliseconds of the change. If + an image frame is intended to appear to the user at time T (e.g. + so that it is synchronized with audio) then the OpenMAX AL object + must insert the image frame at time + T - EGL_CONSUMER_LATENCY_USEC_KHR + +Issues + 1. How many image frame buffers should be used? + + RESOLVED: This is left up to the OpenMAX AL implementation. + + 2. How is the image frame size determined? + + Could also expose EGL_WIDTH and EGL_HEIGHT in the attrib_list + as a hint (or as a requirement) as to what size should be + used. However, a MediaPlayer object typically knows what size + to decode based on the source of the data. So this is + probably not necessary. If needed it can be added with a + layered extension. + + RESOLVED: Leave this up to the OpenMAX AL MediaPlayer object. + + 3. What image frame format should be used? + + RESOLVED: This is a negotiation between the consumer and + producer, but ultimately the producer must convert to the + format that the consumer requests, or fail if that is not + possible. + + Details of any such communication is implementation dependent + and outside the scope of this specification. + + 4. Should this extension create an XADataSink structure rather + than making the application create its own as described in + OpenMAX_AL_EGLStream_DataLocator? + + RESOLVED: NO no need to do this. + + 5. (This issue no longer applies) + Should this extension allow the application to ignore the + XADataSink structure returned by eglStreamProducerALDataSource + and instead use its own? + + RESOLVED: This issue no longer applies + + 6. (This issue no longer applies) + Should eglStreamProducerALDataSource check that <ppDataSink> + is not NULL and that <ppDataSink> points to a pointer that is + NULL? + + RESOLVED: This issue no longer applies + + +Revision History + + #4 (October 4, 2011) Acorn Pooley + - Convert from an NV extension to a KHR extension + + #3 (September 23, 2011) Acorn Pooley + - Eliminate the eglStreamProducerALDataSource function. + - Rename AL0124b_EGLImageStream_DataLocator_Nokia to + OpenMAX_AL_EGLStream_DataLocator and point to new link. + - Resolve issue 2 + + #2 (July 6, 2011) Acorn Pooley + - remove the creation of the XADataSink by + eglStreamProducerALDataSource() + + #1 (June 30, 2011) Acorn Pooley + - initial draft + +# vim:ai:ts=4:sts=4:expandtab:textwidth=70 diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_stream_producer_eglsurface.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_stream_producer_eglsurface.txt new file mode 100644 index 0000000..321ff7a --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_stream_producer_eglsurface.txt @@ -0,0 +1,386 @@ +Name + + KHR_stream_producer_eglsurface + +Name Strings + + EGL_KHR_stream_producer_eglsurface + +Contributors + + Acorn Pooley + Jamie Gennis + Marcus Lorentzon + +Contacts + + Acorn Pooley, NVIDIA (apooley 'at' nvidia.com) + +Notice + + Copyright (c) 2011-2013 The Khronos Group Inc. Copyright terms at + http://www.khronos.org/registry/speccopyright.html + +Status + + Complete. + Approved by the Khronos Board of Promoters on December 2, 2011. + +Version + + Version 11, June 18, 2012 + +Number + + EGL Extension #34 + +Dependencies + + Requires EGL 1.2. + Requires OpenGL ES 1.1 or OpenGL ES 2.0. + + Requires the EGL_KHR_stream extension. + +Overview + + This extension allows an EGLSurface to be created as a producer of + images to an EGLStream. Each call to eglSwapBuffers posts a new + image frame into the EGLStream. + +New Procedures and Functions + + EGLSurface eglCreateStreamProducerSurfaceKHR( + EGLDisplay dpy, + EGLConfig config, + EGLStreamKHR stream, + const EGLint *attrib_list) + +New Tokens + + Bit that can appear in the EGL_SURFACE_TYPE of an EGLConfig: + + EGL_STREAM_BIT_KHR 0x0800 + + + + +Add a row to "Table 3.2: Types of surfaces supported by an EGLConfig" +in the EGL spec, right after the EGL_PBUFFER_BIT row: + + EGL Token Name Description + -------------- -------------------------- + EGL_STREAM_BIT_KHR EGLConfig supports streams + + +In the second paragraph of section "Other EGLConfig Attribute +Description" in the EGL spec, replace + EGL_WINDOW_BIT | EGL_PIXMAP_BIT | EGL_PBUFFER_BIT +with + EGL_WINDOW_BIT | EGL_PIXMAP_BIT | EGL_PBUFFER_BIT | EGL_STREAM_BIT_KHR +and replace + "...cannot be used to create a pbuffer or pixmap." +with + "...cannot be used to create a pbuffer, pixmap, or stream." + + +Replace section "3.10.3.1 No way to connect producer to EGLStream" in +the EGL_KHR_stream extension with this: + + 3.10.3.1 Stream Surface Producer + + Call + + EGLSurface eglCreateStreamProducerSurfaceKHR( + EGLDisplay dpy, + EGLConfig config, + EGLStreamKHR stream, + const EGLint *attrib_list) + + to create an EGLSurface and connect it as the producer of + <stream>. + + <attrib_list> specifies a list of attributes for <stream>. The + list has the same structure as described for eglChooseConfig. The + attributes EGL_WIDTH and EGL_HEIGHT must both be specified in the + <attrib_list>. + + EGL_WIDTH and EGL_HEIGHT indicate the width and height + (respectively) of the images that makes up the stream. + + The EGLSurface producer inserts an image frame into <stream> once + for each time it is passed to eglSwapBuffers(). The image frame + is inserted after the GL has finished previous rendering commands. + Refer to section "3.10.5 EGLStream operation" in the + EGL_KHR_stream extension specification for operation of the + EGLStream when an image frame is inserted into it. + + If <stream> is not in the EGL_STREAM_STATE_EMPTY_KHR, + EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR, or + EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR when passed to + eglSwapBuffers(), then eglSwapBuffers will return EGL_FALSE and + generate an EGL_BAD_CURRENT_SURFACE error. + + If the application would like to have the results of rendering + appear on the screen at a particular time then it must query the + value of EGL_CONSUMER_LATENCY_USEC_KHR after calling + eglCreateStreamProducerSurfaceKHR. This is the estimated time that + will elapse between the time the image frame is inserted into the + EGLStream and the time that the image frame will appear to the + user. + + The image frame is not inserted into the EGLStream until the GL + has finished rendering it. Therefore predicting exactly when the + image frame will be inserted into the stream is nontrivial. + + If it is critical that this frame of data reach the screen at a + particular point in time, then the application can + - render the frame (using GL/GLES commands) + - call glFinish (or use other synchronization techniques to + ensure rendering has completed). + - wait until the time that the frame should appear to the user + MINUS the value of EGL_CONSUMER_LATENCY_USEC_KHR. + - call eglSwapBuffers + This will allow the image frame to be inserted into the EGLStream + at the correct time ("Image Frame Intended Display Time" minus + "Consumer Latency") so that it will be displayed ("Image Frame + Actual Display Time" as close as possible to the desired time. + + However, this will cause the GPU to operate in lockstep with the + CPU which can cause poor performance. In most cases it will be + more important for the image frame to appear to the user "as soon + as possible" rather than at a specific point in time. So in most + cases the application can ignore the value of + EGL_CONSUMER_LATENCY_USEC_KHR, not call glFinish, and not wait + before calling eglSwapBuffers. + + On failure eglCreateStreamProducerSurfaceKHR returns EGL_NO_SURFACE + and generates an error. + + - EGL_BAD_PARAMETER if EGL_WIDTH is not specified or is specified + with a value less than 1. + + - EGL_BAD_PARAMETER if EGL_HEIGHT is not specified or is specified + with a value less than 1. + + - EGL_BAD_STATE_KHR is generated if <stream> is not in state + EGL_STREAM_STATE_CONNECTING_KHR. + + - EGL_BAD_MATCH is generated if <config> does not have the + EGL_STREAM_BIT_KHR set in EGL_SURFACE_TYPE. + + - EGL_BAD_MATCH is generated if the implementation is not able to + convert color buffers described by <config> into image frames + that are acceptable by the consumer that is connected to + <stream>. + + - EGL_BAD_STREAM_KHR is generated if <stream> is not a valid + EGLStream created for <dpy>. + + - EGL_BAD_DISPLAY is generated if <dpy> is not a valid, + initialized EGLDisplay. + +Add a section preceding "3.9.3 Posting Semantics" in the EGL +specification: + + 3.9.x Posting to a Stream + + To post the color buffer to an EGLStream with an EGLSurface + producer, call + + EGLBoolean eglSwapBuffers( + EGLDisplay dpy, + EGLSurface surface); + + If <surface> is the producer of an EGLStream then the + contents of the color buffer are inserted as a new image frame + into the EGLStream. + + When eglSwapBuffers returns the contents of the color buffer will + have been inserted into the EGLStream as described in section + "3.10.5 EGLStream operation" in the EGL_KHR_stream extension + specification, and the EGL_PRODUCER_FRAME_KHR attribute and + EGL_STREAM_STATE_KHR attribute values will reflect this. + + The contents of the color buffer and all ancillary buffers are + always undefined after calling eglSwapBuffers. + + eglSwapBuffers is never synchronized to a video frame when + <surface> is the producer for an EGLStream (it is as if the + swapinterval (set by eglSwapInterval, see below section "3.9.3 + Posting Semantics") is 0). + + It is implementation dependent whether eglSwapBuffers actually + waits for rendering to the color buffer to complete before + returning, but except for timing it must appear to the application + that all rendering to the EGLSurface (e.g. all previous gl + commands) completed before the image frame was inserted into the + EGLStream and eglSwapBuffers returned (as described below in + section "3.9.3 Posting Semantics"). + + +Add to section "3.9.4 Posting Errors" in the EGL specification a new +sentence as the 2nd to last sentence in the first paragraph: + + If eglSwapBuffers is called and the EGLStream associated with + surface is no longer valid, an EGL_BAD_STREAM_KHR error is + generated. + + +Issues + 1. How many image frame buffers should be used? + + DISCUSSION: + - leave up to implementation? + - leave up to producer? + - need hints from consumer? + - In practice 1, 2, and 3 buffers mean different semantics + which are visible to both the producer and consumer. Each + may be useful. I cannot think of a use for more than 3 + buffers for EGL_KHR_stream_surface. (For a video producer + more than 3 often does make sense, but that is a different + extension.) + + One possibility: expose EGL_BUFFER_COUNT_KHR to application. + + It probably does not make sense to ever use more or less than + 3 buffers. One that is the EGLSurface back buffer. One that + is waiting for the consumer to acquire. And one that the + consumer has acquired and is actively consuming. + + RESOLVED: remove the EGL_BUFFER_COUNT_KHR parameter and always + use 3 buffers. This attribute can be added back with a + layered extension later if needed. + + 2. How is the resolution (width/height) of image frames set? + + RESOLVED: The width and height are set with the required + EGL_WIDTH and EGL_HEIGHT attributes. These do not change for + the life of <stream>. + + 3. How is the image format, zbuffering, etc set? + + RESOLVED: These are all determined by the <config>. These do + not change for the life of <stream>. + + 4. How does eglSwapBuffers act if there are already image frames + in the EGLStream when it is called. + + RESOLVED: Frames are inserted into the EGLStream as described + in section "3.10.5 EGLStream operation" in the EGL_KHR_stream + extension specification. In particular: + + If the value of EGL_STREAM_FIFO_LENGTH_KHR is 0 or if the + EGL_KHR_stream_fifo extension is not supported then the + new frame replaces any frames that already exist in the + EGLStream. If the consumer is already consuming a frame + then it continues to consume that same frame, but the next + time the consumer begins to consume a frame (e.g. the + next time eglStreamConsumerAcquireKHR() is called for a + gltexture consumer) the newly rendered image frame will be + consumed. (This is the standard behavior for ANY producer + when EGL_STREAM_FIFO_LENGTH_KHR is 0, described as "mailbox + mode"). + + If the EGL_KHR_stream_fifo extension is supported and the + value of EGL_STREAM_FIFO_LENGTH_KHR is greater than 0 then + the newly rendered frame will be inserted into the + EGLStream. If the EGLStream is full (already contains + EGL_STREAM_FIFO_LENGTH_KHR frames) then eglSwapBuffers + will block until there is room in the fifo. Note that + this can deadlock if the consumer is running in the same + thread as the producer since the consumer will never be + able to consume a frame if the thread is blocked waiting + for room in the fifo. This fifo-related behavior is + described in the EGL_KHR_stream_fifo specification (this + behavior is not specific to this producer; it works the + same for all producers and all consumers). + + All rendering commands must complete before the color + buffer is inserted into the EGLStream, or at least this is how + the behavior must appear to the application. + + To be precise: when eglSwapBuffers returns the rendering + commands may or may not actually be complete, but the + following must all be true: + - The EGL_PRODUCER_FRAME_KHR value reflects the frame that + was just swapped by eglSwapBuffers + - The EGL_STREAM_STATE_KHR indicates that the image frame + is available (i.e. its value is + EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR) + - In mailbox mode if the consumer consumes a new frame it + will get this new frame (not an older frame). (For + example, with a EGL_NV_stream_consumer_gltexture + consumer, a call to eglStreamConsumerAcquireKHR() will + latch this new frame.) + - In fifo mode (see EGL_KHR_stream_fifo extension) if the + consumer consumes a new frame and all previous frames + have been consumed it will get this new frame (not an + older frame). (For example, with a + EGL_NV_stream_consumer_gltexture consumer, a call to + eglStreamConsumerAcquireKHR() will latch this new + frame.) + - If a consumer consumes the swapped frame, all GL (and + other API) commands called prior to eglSwapBuffers + will take effect on the image frame before the + consumer consumes it. In other words, the consumer + will never consume a partially rendered frame. (For + example, with EGL_NV_stream_consumer_gltexture + consumer, if the app does this: + eglSwapBuffers() // swap the producer EGLSurface + eglStreamConsumerAcquireKHR() // acquire the swapped image + glDrawArrays() // draw something using the texture + then the texture used in the glDrawArrays() command + will contain the image rendered by all gl (and/or + other API) commands preceding the eglSwapBuffers call + as if the app had called glFinish and/or eglWaitClient + just before calling eglSwapBuffers (but note that this + is implicit in eglSwapBuffers; the app does NOT need + to actually call glFinish or any other synchronization + functions in order to get this effect, and in fact + explicitly calling glFinish and/or eglWaitClient there + may significantly and negatively affect performance).) + +Revision History + + #11 (June 18. 2012) Acorn Pooley + - Replace EGLStream with EGLStreamKHR in function prototypes. + + #10 (June 15, 2012) Acorn Pooley + - Fix eglCreateStreamProducerSurfaceKHR name (was missing KHR) + + #9 (October 17, 2011) Acorn Pooley + - Clarify issue 4 + + #8 (October 12, 2011) Acorn Pooley + - remove interactions with EGL_KHR_stream_fifo extension (they + are already decribed in that extension). + + #7 (October 11, 2011) Acorn Pooley + - Add issue 4 + - add changes to section 3.9 of the EGL spec to clarify + eglSwapBuffer behavior + + #6 (October 4, 2011) Acorn Pooley + - Convert from an NV extension to a KHR extension + + #5 (September 30, 2011) Acorn Pooley + - Remove EGL_BUFFER_COUNT_NV (0x321D) attribute and resolve issue 1. + + #4 (September 27, 2011) Acorn Pooley + - Assign enum values (bug 8064) + + #3 (July 6, 2011) Acorn Pooley + - Rename EGL_KHR_image_stream to EGL_KHR_stream + + #2 (June 30, 2011) Acorn Pooley + - remove dependence on EGLImage + - clarify overview + - remove glossary (it can be seen in EGL_KHR_stream ext) + - Add EGL_STREAM_BIT + - clarify description + - describe attribute + + #1 (April 20, 2011) Acorn Pooley + - initial draft + +# vim:ai:ts=4:sts=4:expandtab:textwidth=70 diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_surfaceless_context.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_surfaceless_context.txt new file mode 100644 index 0000000..4e8751b --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_surfaceless_context.txt @@ -0,0 +1,174 @@ +Name + + KHR_surfaceless_context + +Name Strings + + EGL_KHR_surfaceless_context + +Contributors + + Acorn Pooley + Jon Leech + Kristian Hoegsberg + Steven Holte + +Contact + + Acorn Pooley: apooley at nvidia dot com + +Notice + + Copyright (c) 2010-2013 The Khronos Group Inc. Copyright terms at + http://www.khronos.org/registry/speccopyright.html + +Status + + Complete. + Approved by the EGL Working Group on June 6, 2012. + Approved by the Khronos Board of Promoters on July 27, 2012. + +Version + + Version 4, 2012/05/03 + +Number + + EGL Extension #40 + +Dependencies + + EGL 1.0 is required. + + The functionality of this extension is not supported by client OpenGL ES + contexts unless the GL_OES_surfaceless_context extension is supported by + those contexts. + + Written against wording of EGL 1.4 specification. + +Overview + + These extensions allows an application to make a context current by + passing EGL_NO_SURFACE for the write and read surface in the + call to eglMakeCurrent. The motivation is that applications that only + want to render to client API targets (such as OpenGL framebuffer + objects) should not need to create a throw-away EGL surface just to get + a current context. + + The state of an OpenGL ES context with no default framebuffer provided + by EGL is the same as a context with an incomplete framebuffer object + bound. + +New Procedures and Functions + + None + +New Tokens + + None + +Additions to the EGL Specification section "3.7.3 Binding Contexts and +Drawables" + + Replace the following two error conditions in the + list of eglMakeCurrent errors: + + " * If <ctx> is not a valid context, an EGL_BAD_CONTEXT error is + generated. + * If either <draw> or <read> are not valid EGL surfaces, an + EGL_BAD_SURFACE error is generated." + + with the following error conditions: + + " * If <ctx> is not a valid context and is not EGL_NO_CONTEXT, an + EGL_BAD_CONTEXT error is generated. + * If either <draw> or <read> are not valid EGL surfaces and are + not EGL_NO_SURFACE, an EGL_BAD_SURFACE error is generated. + * If <ctx> is EGL_NO_CONTEXT and either <draw> or <read> are not + EGL_NO_SURFACE, an EGL_BAD_MATCH error is generated. + * If either of <draw> or <read> is a valid surface and the other + is EGL_NO_SURFACE, an EGL_BAD_MATCH error is generated. + * If <ctx> does not support being bound without read and draw + surfaces, and both <draw> and <read> are EGL_NO_SURFACE, an + EGL_BAD_MATCH error is generated." + + Replace the paragraph starting "If <ctx> is EGL_NO_CONTEXT and + <draw> and <read> are not EGL_NO_SURFACE..." with + + "If both <draw> and <read> are EGL_NO_SURFACE, and <ctx> is a context + which supports being bound without read and draw surfaces, then no error + is generated and the context is made current without a + <default framebuffer>. The meaning of this is defined by the API of the + supporting context. (See chapter 4 of the OpenGL 3.0 Specification, and + the GL_OES_surfaceless_context OpenGL ES extension.)" + + Append to the paragraph starting "The first time an OpenGL or OpenGL + ES context is made current..." with + + "If the first time <ctx> is made current, it is without a default + framebuffer (e.g. both <draw> and <read> are EGL_NO_SURFACE), then + the viewport and scissor regions are set as though + glViewport(0,0,0,0) and glScissor(0,0,0,0) were called." + +Interactions with other extensions + + The semantics of having a current context with no surface for OpenGL ES + 1.x and OpenGL ES 2.x are specified by the GL_OES_surfaceless_context + extension. + +Issues + + 1) Do we need a mechanism to indicate which contexts may be bound with + <read> and <draw> set to NULL? Or is it ok to require that if this + extension is supported then any context of the particular API may be + made current with no surfaces? + + RESOLVED. Because multiple API implementations may be available as + contexts we cannot guarantee that all OpenGL ES 1.x or OpenGL ES 2.x + contexts will support GL_OES_surfaceless_context. If the user attempts + to call eglMakeCurrent with EGL_NO_SURFACE on a context which does not + support it, this simply results in EGL_BAD_MATCH. + + 2) Do we need to include all of the relevant "default framebuffer" language + from the OpenGL specification to properly specify OpenGL ES behavior + with no default framebuffer bound? + + RESOLVED. Yes, the behaviour of the GLES contexts when no default + framebuffer is associated with the context has been moved to the OpenGL + ES extension OES_surfaceless_context. + + 3) Since these EGL extensions also modify OpenGL ES behavior and introduce + a new error condition, do we want corresponding OpenGL ES extension + strings as well? + + RESOLVED. Yes, see GL_OES_surfaceless_context extension. + + 4) How does this document interact with EGL_KHR_create_context and OpenGL + contexts? + + RESOLVED. Some language defining the error conditions of eglMakeCurrent + have been imported from the draft specification of EGL_KHR_create_context + and the definitions of the behaviour of the GLES contexts without a + default framebuffer have been moved to GL_OES_surfaceless_context. Any + further interactions are left to the create_context extension to define + when it is completed. + +Revision History + + Version 5, 2014/01/07 (Jon Leech) - Correct references to + EXT_surfaceless_context with GL_OES_surfaceless_context. + + Version 4, 2012/02/27 (Steven Holte) - Add language for error conditions + from EGL_KHR_create_context, and resolutions of issues. Combined API + specific extensions into a single extension. + + Version 3, 2010/08/19 (Kristian Hoegsberg) - Move default framebuffer + language to new GLES extension (GL_OES_surfaceless_context) and make + this extension depend on that. + + Version 2, 2010/08/03 (Jon Leech) - add default framebuffer language to + the OpenGL ES Specifications, including changes to initial GL state and + the FRAMEBUFFER_UNDEFINED incompleteness status when no default + framebuffer is bound. + + Version 1, 2010/07/09 (Acorn Pooley) - Initial draft. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_swap_buffers_with_damage.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_swap_buffers_with_damage.txt new file mode 100644 index 0000000..310dc39 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_swap_buffers_with_damage.txt @@ -0,0 +1,449 @@ +Name + + KHR_swap_buffers_with_damage + +Name Strings + + EGL_KHR_swap_buffers_with_damage + +Contributors + + Robert Bragg + Tapani Pälli + Kristian Høgsberg + Benjamin Franzke + Ian Stewart + James Jones + Ray Smith + +Contact + + Robert Bragg, Intel (robert.bragg 'at' intel.com) + +IP Status + + No known claims. + +Notice + + Copyright (c) 2014 The Khronos Group Inc. Copyright terms at + http://www.khronos.org/registry/speccopyright.html + +Status + + Complete. + Approved by the EGL Working Group on September 17, 2014. + Approved by the Khronos Board of Promoters on November 7, 2014. + +Version + + Version 13, February 20, 2020 + +Number + + EGL Extension #84 + +Extension Type + + EGL display extension + +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. + +Terminology + + This extension and the EGL_KHR_partial_update extension both use the word + "damage" for subtly but significantly different purposes: + + "Surface damage" is what the EGL_KHR_swap_buffers_with_damage extension + is concerned with. This is the area of the *surface* that changes between + frames for that surface. It concerns the differences between two buffers - + the current back buffer and the current front buffer. It is useful only to + the consumer. + + "Buffer damage" is what the EGL_KHR_partial_update extension is concerned + with. This is the area of a particular buffer that has changed since that + same buffer was last used. As it only concerns changes to a single buffer, + there is no dependency on the next or previous frames or any other buffer. + It therefore cannot be used to infer anything about changes to the surface, + which requires linking one frame or buffer to another. Buffer damage is + therefore only useful to the producer. + + Following are examples of the two different damage types. Note that the + final surface content is the same in both cases, but the damaged areas + differ according to the type of damage being discussed. + +Surface damage example (EGL_KHR_swap_buffers_with_damage) + + The surface damage for frame n is the difference between frame n and frame + (n-1), and represents the area that a compositor must recompose. + + Frame 0 Frame 1 Frame 2 Frame 3 Frame 4 + +---------+ +---------+ +---------+ +---------+ +---------+ + | | |#########| |#########| |#########| |#########| + | | | | |#########| |#########| |#########| Final surface + | | | | | | |#########| |#########| content + | | | | | | | | |#########| + +---------+ +---------+ +---------+ +---------+ +---------+ + + +---------+ +---------+ +---------+ +---------+ +---------+ + |@@@@@@@@@| |@@@@@@@@@| | | | | | | + |@@@@@@@@@| | | |@@@@@@@@@| | | | | Surface damage + |@@@@@@@@@| | | | | |@@@@@@@@@| | | + |@@@@@@@@@| | | | | | | |@@@@@@@@@| + +---------+ +---------+ +---------+ +---------+ +---------+ + +Buffer damage example (EGL_KHR_partial_update) + + The buffer damage for a frame is the area changed since that same buffer was + last used. If the buffer has not been used before, the buffer damage is the + entire area of the buffer. + + The buffer marked with an 'X' in the top left corner is the buffer that is + being used for that frame. This is the buffer to which the buffer age and + the buffer damage relate. + + Note that this example shows a double buffered surface - the actual number + of buffers could be different and variable throughout the lifetime of the + surface. The age *must* therefore be queried for every frame. + + Frame 0 Frame 1 Frame 2 Frame 3 Frame 4 + +---------+ +---------+ +---------+ +---------+ +---------+ + | | |#########| |#########| |#########| |#########| + | | | | |#########| |#########| |#########| Final surface + | | | | | | |#########| |#########| content + | | | | | | | | |#########| + +---------+ +---------+ +---------+ +---------+ +---------+ + + X---------+ +---------+ X---------+ +---------+ X---------+ + | | | | |#########| |#########| |#########| + | | | | |#########| |#########| |#########| Buffer 1 content + | | | | | | | | |#########| + | | | | | | | | |#########| + +---------+ +---------+ +---------+ +---------+ +---------+ + + X---------+ +---------+ X---------+ +---------+ + |#########| |#########| |#########| |#########| + | | | | |#########| |#########| Buffer 2 content + | | | | |#########| |#########| + | | | | | | | | + +---------+ +---------+ +---------+ +---------+ + + 0 0 2 2 2 Buffer age + + +---------+ +---------+ +---------+ +---------+ +---------+ + |@@@@@@@@@| |@@@@@@@@@| |@@@@@@@@@| | | | | + |@@@@@@@@@| |@@@@@@@@@| |@@@@@@@@@| |@@@@@@@@@| | | Buffer damage + |@@@@@@@@@| |@@@@@@@@@| | | |@@@@@@@@@| |@@@@@@@@@| + |@@@@@@@@@| |@@@@@@@@@| | | | | |@@@@@@@@@| + +---------+ +---------+ +---------+ +---------+ +---------+ + + +New Procedures and Functions + + EGLBoolean eglSwapBuffersWithDamageKHR ( + 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 eglSwapBuffersWithDamageKHR ( + 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 eglSwapBuffersWithDamageKHR 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 + eglSwapBuffersWithDamageKHR 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, + eglSwapBuffersWithDamageKHR, 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 eglSwapBuffersWithDamageKHR, 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 eglSwapBuffersWithDamageKHR 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, eglSwapBuffersWithDamageKHR, and + eglCopyBuffers return EGL_FALSE on failure." + + Paragraph 1, seventh sentence: + + "If eglSwapBuffers or eglSwapBuffersWithDamageKHR are called + and the native window associated with <surface> is no longer + valid, an EGL_BAD_NATIVE_WINDOW error is generated. If + eglSwapBuffersWithDamageKHR 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 eglSwapBuffersWithDamageKHR 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, 19/08/2014 + - Draft for promoting to KHR + - Added section on terminology and damage types + Version 11, 10/09/2014 + - Marked as display extension + Version 12, 11/05/2014 + - Change copyright to Khronos after signoff from Intel. + Version 13, 20/02/2020, Jon Leech + - Constify rects parameter (EGL-Registry issue 98). diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_vg_parent_image.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_vg_parent_image.txt new file mode 100644 index 0000000..719bb11 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_vg_parent_image.txt @@ -0,0 +1,138 @@ +Name + + KHR_vg_parent_image + +Name Strings + + EGL_KHR_vg_parent_image + +Contributors + + Ignacio Llamas + Gary King + Chris Wynn + +Contacts + + Gary King, NVIDIA Corporation (gking 'at' nvidia.com) + +Notice + + Copyright (c) 2006-2013 The Khronos Group Inc. Copyright terms at + http://www.khronos.org/registry/speccopyright.html + +Status + + Complete. + Approved by the Khronos Board of Promoters on February 11, 2008. + +Version + + Version 5, October 8, 2008 + +Number + + EGL Extension #4 + +Dependencies + + This extension requires EGL 1.2 and the EGL_KHR_image extension, + and an OpenVG implementation + + This specification is written against the wording of the EGL Image + (EGL_KHR_image) specification. + +Overview + + This extension provides a mechanism for creating EGLImage objects + from OpenVG VGImage API resources. For an overview of EGLImage + operation, please see the EGL_KHR_image specification. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + EGL_VG_PARENT_IMAGE_KHR 0x30BA + + +Additions to the EGL Image (EGL_KHR_image) Specification: + + Add the following to Table aaa (Legal values for CreateImageKHR + <target> parameter), Section 2.5.1 (EGLImage Specification) + + +--------------------------+--------------------------------------------+ + | <target> | Notes | + +--------------------------+--------------------------------------------+ + | EGL_VG_PARENT_IMAGE_KHR | Used for OpenVG VGImage objects | + +--------------------------+--------------------------------------------+ + + Insert the following text after paragraph 3 ("If <target> is + NATIVE_PIXMAP_KHR...") of Section 2.5.1 (EGLImage Specification): + + "If <target> is EGL_VG_PARENT_IMAGE_KHR, <dpy> must be a valid EGLDisplay, + <ctx> must be a valid OpenVG API context on that display, and <buffer> + must be a handle of a VGImage object valid in the specified context, cast + into the type EGLClientBuffer. Furthermore, the specified VGImage + <buffer> must not be a child image (i.e. the value returned by + vgGetParent(<buffer>) must be <buffer>). If the specified VGImage + <buffer> has any child images (i.e., vgChildImage has been previously + called with the parent parameter set to <buffer>), all child images will + be treated as EGLImage siblings after CreateImageKHR returns. Any values + specified in <attr_list> are ignored." + + Add the following errors to the end of the list in Section 2.5.1 (EGLImage + Specification): + + " * If <target> is EGL_VG_PARENT_IMAGE_KHR, and <dpy> is not a + valid EGLDisplay, the error EGL_BAD_DISPLAY is generated. + + * If <target> is EGL_VG_PARENT_IMAGE_KHR and <ctx> is not a + valid EGLContext, the error EGL_BAD_CONTEXT is generated. + + * If <target> is EGL_VG_PARENT_IMAGE_KHR and <ctx> is not a valid + OpenVG context, the error EGL_BAD_MATCH is returned. + + * If <target> is EGL_VG_PARENT_IMAGE_KHR and <buffer> is not a handle + to a VGImage object in the specified API context <ctx>, the error + EGL_BAD_PARAMETER is generated. + + * If <target> is EGL_VG_PARENT_IMAGE_KHR, and the VGImage specified by + <buffer> is a child image (i.e., vgGetParent(<buffer>) returns + a different handle), the error EGL_BAD_ACCESS is generated." + +Issues + + 1. Should this specification allow the creation of EGLImages + from OpenVG child images? + + RESOLVED: No. It is believed that properly addressing the + interaction of hardware restrictions (e.g., memory alignment), + arbitrary image subrectangles, scissor rectangles and viewport + rectangles may create an undue burden on implementers. In the + interest of providing a useful spec in a timely fashion, this + functionality has been disallowed, with the possibility of + providing it (if necessary) through a future layered extension. + + This restriction is shared with eglCreatePbufferFromClientBuffer; + however, this specification allows EGL Images to be created + from VGImages which have child images, functionality not + previously available. + +Revision History + +#5 (Jon Leech, October 8, 2008) + - Updated status (approved as part of OpenKODE 1.0) +#4 (Jon Leech, April 5, 2007) + - Assigned enumerant values + - Added OpenKODE 1.0 Provisional disclaimer +#3 (December 14, 2006) + - Changed requirement to egl 1.2 to include EGLClientBuffer type. + - added error condition descriptions for <dpy> and <ctx> +#2 (November 27, 2006) + - Changed OES token to KHR diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_wait_sync.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_wait_sync.txt new file mode 100644 index 0000000..aeef96c --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_wait_sync.txt @@ -0,0 +1,278 @@ +Name + + KHR_wait_sync + +Name Strings + + EGL_KHR_wait_sync + +Contributors + + Jon Leech + Tom Cooksey + Alon Or-bach + +Contacts + + Jon Leech (jon 'at' alumni.caltech.edu) + +Notice + + Copyright (c) 2012-2014 The Khronos Group Inc. Copyright terms at + http://www.khronos.org/registry/speccopyright.html + +Status + + Complete. + Approved by the Khronos Board of Promoters on October 26, 2012. + +Version + + Version 7, March 12, 2014 + +Number + + EGL Extension #43 + +Dependencies + + EGL 1.1 is required. + + EGL_KHR_fence_sync is required. + + EGL_KHR_reusable_sync is affected by this extension. + + This extension is written against the wording of the EGL 1.4 + Specification. + +Overview + + This extension adds the ability to wait for signaling of sync objects + in the server for a client API context, rather than in the application + thread bound to that context. This form of wait does not necessarily + block the application thread which issued the wait (unlike + eglClientWaitSyncKHR), so the application may continue to issue commands + to the client API context or perform other work in parallel, leading to + increased performance. The best performance is likely to be achieved by + implementations which can perform this new wait operation in GPU + hardware, although this is not required. + +New Types + + None + +New Procedures and Functions + + EGLint eglWaitSyncKHR( + EGLDisplay dpy, + EGLSyncKHR sync, + EGLint flags) + +New Tokens + + None + +Changes to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors) + + Add to section 3.8.1 "Sync Objects" (as already modified + by EGL_KHR_fence_sync and/or EGL_KHR_reusable_sync): + + Following the description of eglClientWaitSyncKHR, add: + + "The command + + EGLint eglWaitSyncKHR(EGLDisplay dpy, + EGLSyncKHR sync, + EGLint flags) + + is similar to eglClientWaitSyncKHR, but instead of blocking and not + returning to the application until <sync> is signaled, eglWaitSyncKHR + returns immediately. On success, EGL_TRUE is returned, and the server + for the client API context [fn1] will block until <sync> is signaled + [fn2]. + [fn1 - the server may choose to wait either in the CPU executing + server-side code, or in the GPU hardware if it supports this + operation.] + [fn2 - eglWaitSyncKHR allows applications to continue to queue + commands from the application in anticipation of the sync being + signaled, potentially increasing parallelism between application, + client API server code, and the GPU. The server only blocks + execution of commands for the specific context on which + eglWaitSyncKHR was issued; other contexts implemented by the same + server are not affected.] + + <sync> has the same meaning as for eglClientWaitSyncKHR. + + <flags> must be 0. + + Errors + ------ + eglWaitSyncKHR returns EGL_FALSE on failure and generates an error as + specified below, but does not cause the server for the client API + context to block. + + * If the current context for the currently bound client API does not + support the client API extension indicating it can perform server + waits, an EGL_BAD_MATCH error is generated. + * If no context is current for the currently bound client API (i.e., + eglGetCurrentContext returns EGL_NO_CONTEXT), an EGL_BAD_MATCH error + is generated. + * If <dpy> does not match the EGLDisplay passed to eglCreateSyncKHR + when <sync> was created, the behavior is undefined. + * If <sync> is not a valid sync object for <dpy>, an EGL_BAD_PARAMETER + error is generated. + * If <flags> is not 0, an EGL_BAD_PARAMETER error is generated. + + Each client API which supports eglWaitSyncKHR indicates this support in + the form of a client API extension. If the GL_OES_EGL_sync extension is + supported by any version of OpenGL ES, a server wait may be performed + when the currently bound API is OpenGL ES. If the VG_KHR_EGL_sync + extension is supported by OpenVG, a server wait may be performed when + the currently bound API is OpenVG." + + Add new subsubsection following eglWaitSyncKHR: + + "Multiple Waiters + ---------------- + + It is possible for the application thread calling a client API to be + blocked on a sync object in a eglClientWaitSyncKHR command, the server + for that client API context to be blocked as the result of a previous + eglWaitSyncKHR command, and for additional eglWaitSyncKHR commands to be + queued in the server, all for a single sync object. When the sync object + is signaled in this situation, the client will be unblocked, the server + will be unblocked, and all such queued eglWaitSyncKHR commands will + continue immediately when they are reached. + + Sync objects may be waited on or signaled from multiple contexts of + different client API types in multiple threads simultaneously, although + some client APIs may not support eglWaitSyncKHR. This support is + determined by client API-specific extensions." + + Additions to the EGL_KHR_reusable_sync extension, modifying the description + of eglSignalSyncKHR to include both client and server syncs: + + "... If as a result of calling eglSignalSyncKHR the status of <sync> + transitions from unsignaled to signaled, any eglClientWaitSyncKHR + * or eglWaitSyncKHR * + commands blocking on <sync> will unblock. ..." + + Additions to the EGL_KHR_reusable_sync extension, modifying the description + of eglDestroySyncKHR to include both client and server syncs: + + "... If any eglClientWaitSyncKHR + * or eglWaitSyncKHR * + commands are blocking on <sync> when eglDestroySyncKHR is called, they + will be woken up, as if <sync> were signaled." + + + Additions to the EGL_KHR_fence_sync extension, modifying the description + of eglCreateSyncKHR to include both client and server syncs: + + "... causing any eglClientWaitSyncKHR + * or eglWaitSyncKHR * + commands (see below) blocking on <sync> to unblock ..." + + Additions to the EGL_KHR_fence_sync extension, modifying the description + of eglDestroySyncKHR to include both client and server syncs: + + "... If any eglClientWaitSyncKHR + * or eglWaitSyncKHR * + commands are blocking on <sync> when eglDestroySyncKHR is called, <sync> + is flagged for deletion and will be deleted when it is no longer + associated with any fence command and is no longer blocking any + eglClientWaitSyncKHR or eglWaitSyncKHR commands." + + +Issues + + 1. Explain the key choices made in this extension. + + RESPONSE: This extension has been written to behave as similarly as + possible to the glWaitSync functionality available in desktop OpenGL. + Server waits are functionality which was only available in GL syncs + until now. + + In the interest of maintaining similarity with OpenGL sync objects, this + extension attempts to copy the glWaitSync functionality of OpenGL + wherever possible (both functionally and stylistically), only making + changes where needed to operate inside EGL (rather than a client API + context) and match EGL naming conventions. + + 2. Must all EGL client APIs support server waits? + + PROPOSED: Only if the client APIs also support fence syncs, which also + interacts with the server for that client API. The same client API + extensions defining fence sync support (GL_OES_EGL_sync and + VG_KHR_EGL_sync) are used here to indicate server wait ability for those + client APIs. + + Reusable syncs in EGL_KHR_reusable_sync do not have this dependency, + because it is (at least in principle) possible for eglClientWaitSyncKHR + to be performed entirely within the EGL implementation. However, + eglWaitSyncKHR requires cooperation of the client API, whether fence + syncs or reusable syncs are being waited upon. + + It would be possible to completely decouple fence syncs and the ability + to do server waits, but this would require new client API extensions. + + 3. What is the relationship between EGL sync objects and OpenGL / OpenGL + ES sync objects? + + RESPONSE: There is no direct relationship. GL and ES servers may not + even implement sync objects as defined by some versions of those APIs. + However, EGL sync objects are intended to be functionally equivalent to + GL sync objects, and the language describing them is drawn from the GL + specifications. Implementations supporting both forms of sync object + will probably use the same implementation internally. + + 4. Should eglWaitSyncKHR take a timeout as a parameter as its equivalent + in OpenGL / OpenGL ES and eglWaitClientKHR does? + + PROPOSED: No. A timeout is of limited use to a well-behaved application. + If a timeout was added, the result of it expiring is likely to be a + corrupted output. Adding a timeout would likely necessitate a way to + query if the wait completed because the condition was signaled or + because of a timeout. There doesn't seem to be an obvious, elegant API + mechanism to do that. If a timeout is needed in the future, it can be + added via an additional extension with a new entry-point. + + 5. What happens if an application issues a server-side wait on a fence + which never gets signaled? + + RESPONSE: Further rendering in the context which issued the server-side + wait will not progress. Any additional behavior is undefined and is + likely to be different depending on a particular implementation. Could + be handled in the same way as an extremely long-running GLSL shader. + + 6. Does this extension affect the destruction behavior? + + RESOLVED: No. The behavior of eglDestroySyncKHR is determined by the type + of sync object, and is not affected by this extension. + +Revision History + +#7 (Alon Or-bach, March 12, 2014) + - Clarified that eglDestroySyncKHR behavior is set in + EGL_KHR_fence_sync / EGL_KHR_reusable_sync and is not modified by this + extension (bug 11458). +#6 (Jon Leech, January 24, 2013) + - eglWaitSyncKHR causes a server wait in OpenGL ES when GL_OES_EGL_sync + is supported, not a client wait as formerly specified (Bug 9493). +#5 (Jon Leech, October 31, 2012) + - Change return type of eglWaitSyncKHR in spec body to EGLint to match + New Functions section, and rearrange description of return type and + errors section for clarity. +#4 (Tom Cooksey, August 16, 2012) + - Removed timeout parameter and text relating to it. Add issue 4 + discussing timeout parameter. Add issue 5 explaining the behavior of + waiting on a never-signaled fence. Minor corrections to use US English. +#3 (Jon Leech, June 26, 2012) + - Fix typos (bug 9137). +#2 (Jon Leech, June 20, 2012) + - Clarifications and language cleanup (Bug 9137). Some paragraph + reflowing. Note that eglWaitSyncKHR only blocks the server for the + specific context on which the wait was issued. Add issue 3 discussing + relationship to GL/ES sync objects. +#1 (Jon Leech, June 6, 2012) + - Initial draft branched from GL 4.x API spec language. |