diff options
Diffstat (limited to 'engine-ocean/External/glew/auto/EGL-Registry/extensions')
139 files changed, 35181 insertions, 0 deletions
diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANDROID/EGL_ANDROID_GLES_layers.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANDROID/EGL_ANDROID_GLES_layers.txt new file mode 100644 index 0000000..eb2a7d9 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANDROID/EGL_ANDROID_GLES_layers.txt @@ -0,0 +1,64 @@ +Name + + ANDROID_GLES_layers + +Name Strings + + EGL_ANDROID_GLES_layers + +Contributors + + Cody Northrop + +Contact + + Cody Northrop, Google LLC (cnorthrop 'at' google.com) + +Status + + Draft + +Version + + Version 1, March 3, 2019 + +Number + + EGL Extension #132 + +Extension Type + + EGL client extension + +Dependencies + + Requires EGL 1.5 or EGL_EXT_client_extensions + +Overview + + This extension indicates the EGL loader supports GLES layering on Android. + It does not add any requirements to drivers or hardware. + + See frameworks/native/opengl/libs/EGL/GLES_layers.md in Android for + more information. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + None + +Issues + + None + +Revision History + +#1 (Cody Northrop, March 3, 2019) + - Initial draft. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANDROID/EGL_ANDROID_blob_cache.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANDROID/EGL_ANDROID_blob_cache.txt new file mode 100644 index 0000000..e984694 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANDROID/EGL_ANDROID_blob_cache.txt @@ -0,0 +1,211 @@ +Name + + ANDROID_blob_cache + +Name Strings + + EGL_ANDROID_blob_cache + +Contributors + + Jamie Gennis + +Contact + + Jamie Gennis, Google Inc. (jgennis 'at' google.com) + +Status + + Complete + +Version + + Version 3, December 13, 2012 + +Number + + EGL Extension #48 + +Dependencies + + Requires EGL 1.0 + + This extension is written against the wording of the EGL 1.4 Specification + +Overview + + Shader compilation and optimization has been a troublesome aspect of OpenGL + programming for a long time. It can consume seconds of CPU cycles during + application start-up. Additionally, state-based re-compiles done + internally by the drivers add an unpredictable element to application + performance tuning, often leading to occasional pauses in otherwise smooth + animations. + + This extension provides a mechanism through which client API + implementations may cache shader binaries after they are compiled. It may + then retrieve those cached shaders during subsequent executions of the same + program. The management of the cache is handled by the application (or + middleware), allowing it to be tuned to a particular platform or + environment. + + While the focus of this extension is on providing a persistent cache for + shader binaries, it may also be useful for caching other data. This is + perfectly acceptable, but the guarantees provided (or lack thereof) were + designed around the shader use case. + + Note that although this extension is written as if the application + implements the caching functionality, on the Android OS it is implemented + as part of the Android EGL module. This extension is not exposed to + applications on Android, but will be used automatically in every + application that uses EGL if it is supported by the underlying + device-specific EGL implementation. + +New Types + + /* + * EGLsizeiANDROID is a signed integer type for representing the size of a + * memory buffer. + */ + #include <khrplatform.h> + typedef khronos_ssize_t EGLsizeiANDROID; + + /* + * EGLSetBlobFunc is a pointer to an application-provided function that a + * client API implementation may use to insert a key/value pair into the + * cache. + */ + typedef void (*EGLSetBlobFuncANDROID) (const void* key, + EGLsizeiANDROID keySize, const void* value, EGLsizeiANDROID valueSize) + + /* + * EGLGetBlobFunc is a pointer to an application-provided function that a + * client API implementation may use to retrieve a cached value from the + * cache. + */ + typedef EGLsizeiANDROID (*EGLGetBlobFuncANDROID) (const void* key, + EGLsizeiANDROID keySize, void* value, EGLsizeiANDROID valueSize) + +New Procedures and Functions + + void eglSetBlobCacheFuncsANDROID(EGLDisplay dpy, + EGLSetBlobFuncANDROID set, + EGLGetBlobFuncANDROID get); + +New Tokens + + None. + +Changes to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors) + + Add a new subsection after Section 3.8, page 50 + (Synchronization Primitives) + + "3.9 Persistent Caching + + In order to facilitate persistent caching of internal client API state that + is slow to compute or collect, the application may specify callback + function pointers through which the client APIs can request data be cached + and retrieved. The command + + void eglSetBlobCacheFuncsANDROID(EGLDisplay dpy, + EGLSetBlobFuncANDROID set, EGLGetBlobFuncANDROID get); + + sets the callback function pointers that client APIs associated with + display <dpy> can use to interact with caching functionality provided by + the application. <set> points to a function that inserts a new value into + the cache and associates it with the given key. <get> points to a function + that retrieves from the cache the value associated with a given key. The + semantics of these callback functions are described in Section 3.9.1 (Cache + Operations). + + Cache functions may only be specified once during the lifetime of an + EGLDisplay. The <set> and <get> functions may be called at any time and + from any thread from the time at which eglSetBlobCacheFuncsANDROID is + called until the time that the last resource associated with <dpy> is + deleted and <dpy> itself is terminated. Concurrent calls to these + functions from different threads is also allowed. + + If eglSetBlobCacheFuncsANDROID generates an error then all client APIs must + behave as though eglSetBlobCacheFuncsANDROID was not called for the display + <dpy>. If <set> or <get> is NULL then an EGL_BAD_PARAMETER error is + generated. If a successful eglSetBlobCacheFuncsANDROID call was already + made for <dpy> and the display has not since been terminated then an + EGL_BAD_PARAMETER error is generated. + + 3.9.1 Cache Operations + + To insert a new binary value into the cache and associate it with a given + key, a client API implementation can call the application-provided callback + function + + void (*set) (const void* key, EGLsizeiANDROID keySize, + const void* value, EGLsizeiANDROID valueSize) + + <key> and <value> are pointers to the beginning of the key and value, + respectively, that are to be inserted. <keySize> and <valueSize> specify + the size in bytes of the data pointed to by <key> and <value>, + respectively. + + No guarantees are made as to whether a given key/value pair is present in + the cache after the set call. If a different value has been associated + with the given key in the past then it is undefined which value, if any, is + associated with the key after the set call. Note that while there are no + guarantees, the cache implementation should attempt to cache the most + recently set value for a given key. + + To retrieve the binary value associated with a given key from the cache, a + client API implementation can call the application-provided callback + function + + EGLsizeiANDROID (*get) (const void* key, EGLsizeiANDROID keySize, + void* value, EGLsizeiANDROID valueSize) + + <key> is a pointer to the beginning of the key. <keySize> specifies the + size in bytes of the binary key pointed to by <key>. If the cache contains + a value associated with the given key then the size of that binary value in + bytes is returned. Otherwise 0 is returned. + + If the cache contains a value for the given key and its size in bytes is + less than or equal to <valueSize> then the value is written to the memory + pointed to by <value>. Otherwise nothing is written to the memory pointed + to by <value>. + +Issues + + 1. How should errors be handled in the callback functions? + + RESOLVED: No guarantees are made about the presence of values in the cache, + so there should not be a need to return error information to the client API + implementation. The cache implementation can simply drop a value if it + encounters an error during the 'set' callback. Similarly, it can simply + return 0 if it encouters an error in a 'get' callback. + + 2. When a client API driver gets updated, that may need to invalidate + previously cached entries. How can the driver handle this situation? + + RESPONSE: There are a number of ways the driver can handle this situation. + The recommended way is to include the driver version in all cache keys. + That way each driver version will use a set of cache keys that are unique + to that version, and conflicts should never occur. Updating the driver + could then leave a number of values in the cache that will never be + requested again. If needed, the cache implementation can handle those + values in some way, but the driver does not need to take any special + action. + + 3. How much data can be stored in the cache? + + RESPONSE: This is entirely dependent upon the cache implementation. + Presumably it will be tuned to store enough data to be useful, but not + enough to become problematic. :) + +Revision History + +#3 (Jon Leech, December 13, 2012) + - Fix typo in New Functions section & assign extension #. + +#2 (Jamie Gennis, April 25, 2011) + - Swapped the order of the size and pointer arguments to the get and set + functions. + +#1 (Jamie Gennis, April 22, 2011) + - Initial draft. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANDROID/EGL_ANDROID_create_native_client_buffer.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANDROID/EGL_ANDROID_create_native_client_buffer.txt new file mode 100644 index 0000000..3e0c4a9 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANDROID/EGL_ANDROID_create_native_client_buffer.txt @@ -0,0 +1,197 @@ +Name + + ANDROID_create_native_client_buffer + +Name Strings + + EGL_ANDROID_create_native_client_buffer + +Contributors + + Craig Donner + +Contact + + Craig Donner, Google Inc. (cdonner 'at' google.com) + +Status + + Draft + +Version + + Version 1, January 19, 2016 + +Number + + EGL Extension #99 + +Dependencies + + Requires EGL 1.2. + + EGL_ANDROID_image_native_buffer and EGL_KHR_image_base are required. + + This extension is written against the wording of the EGL 1.2 + Specification as modified by EGL_KHR_image_base and + EGL_ANDROID_image_native_buffer. + +Overview + + This extension allows creating an EGLClientBuffer backed by an Android + window buffer (struct ANativeWindowBuffer) which can be later used to + create an EGLImage. + +New Types + + None. + +New Procedures and Functions + + EGLClientBuffer eglCreateNativeClientBufferANDROID( + const EGLint *attrib_list) + +New Tokens + + EGL_NATIVE_BUFFER_USAGE_ANDROID 0x3143 + EGL_NATIVE_BUFFER_USAGE_PROTECTED_BIT_ANDROID 0x00000001 + EGL_NATIVE_BUFFER_USAGE_RENDERBUFFER_BIT_ANDROID 0x00000002 + EGL_NATIVE_BUFFER_USAGE_TEXTURE_BIT_ANDROID 0x00000004 + +Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors) + + Add the following to section 2.5.1 "EGLImage Specification" (as modified by + the EGL_KHR_image_base and EGL_ANDROID_image_native_buffer specifications), + below the description of eglCreateImageKHR: + + "The command + + EGLClientBuffer eglCreateNativeClientBufferANDROID( + const EGLint *attrib_list) + + may be used to create an EGLClientBuffer backed by an ANativeWindowBuffer + struct. EGL implementations must guarantee that the lifetime of the + returned EGLClientBuffer is at least as long as the EGLImage(s) it is bound + to, following the lifetime semantics described below in section 2.5.2; the + EGLClientBuffer must be destroyed no earlier than when all of its associated + EGLImages are destroyed by eglDestroyImageKHR. <attrib_list> is a list of + attribute-value pairs which is used to specify the dimensions, format, and + usage of the underlying buffer structure. If <attrib_list> is non-NULL, the + last attribute specified in the list must be EGL_NONE. + + Attribute names accepted in <attrib_list> are shown in Table aaa, + 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 | Default Value | + | | | | + +---------------------------------+----------------------+---------------+ + | EGL_NONE | Marks the end of the | N/A | + | | attribute-value list | | + | EGL_WIDTH | The width of the | 0 | + | | buffer data | | + | EGL_HEIGHT | The height of the | 0 | + | | buffer data | | + | EGL_RED_SIZE | The bits of Red in | 0 | + | | the color buffer | | + | EGL_GREEN_SIZE | The bits of Green in | 0 | + | | the color buffer | | + | EGL_BLUE_SIZE | The bits of Blue in | 0 | + | | the color buffer | | + | EGL_ALPHA_SIZE | The bits of Alpha in | 0 | + | | the color buffer | | + | | buffer data | | + | EGL_NATIVE_BUFFER_USAGE_ANDROID | The usage bits of | 0 | + | | the buffer data | | + +---------------------------------+----------------------+---------------+ + Table aaa. Legal attributes for eglCreateNativeClientBufferANDROID + <attrib_list> parameter. + + The maximum width and height may depend on the amount of available memory, + which may also depend on the format and usage flags. The values of + EGL_RED_SIZE, EGL_GREEN_SIZE, and EGL_BLUE_SIZE must be non-zero and + correspond to a valid pixel format for the implementation. If EGL_ALPHA_SIZE + is non-zero then the combination of all four sizes must correspond to a + valid pixel format for the implementation. The + EGL_NATIVE_BUFFER_USAGE_ANDROID flag may include any of the following bits: + + EGL_NATIVE_BUFFER_USAGE_PROTECTED_BIT_ANDROID: Indicates that the + created buffer must have a hardware-protected path to external display + sink. If a hardware-protected path is not available, then either don't + composite only this buffer (preferred) to the external sink, or (less + desirable) do not route the entire composition to the external sink. + + EGL_NATIVE_BUFFER_USAGE_RENDERBUFFER_BIT_ANDROID: The buffer will be + used to create a renderbuffer. This flag must not be set if + EGL_NATIVE_BUFFER_USAGE_TEXTURE_BIT_ANDROID is set. + + EGL_NATIVE_BUFFER_USAGE_TEXTURE_BIT_ANDROID: The buffer will be used to + create a texture. This flag must not be set if + EGL_NATIVE_BUFFER_USAGE_RENDERBUFFER_BIT_ANDROID is set. + + Errors + + If eglCreateNativeClientBufferANDROID fails, NULL will be returned, no + memory will be allocated, and one of the following errors will be + generated: + + * If the value of EGL_WIDTH or EGL_HEIGHT is not positive, the error + EGL_BAD_PARAMETER is generated. + + * If the combination of the values of EGL_RED_SIZE, EGL_GREEN_SIZE, + EGL_BLUE_SIZE, and EGL_ALPHA_SIZE is not a valid pixel format for the + EGL implementation, the error EGL_BAD_PARAMETER is generated. + + * If the value of EGL_NATIVE_BUFFER_ANDROID is not a valid combination + of gralloc usage flags for the EGL implementation, or is incompatible + with the value of EGL_FORMAT, the error EGL_BAD_PARAMETER is + Generated. + + * If both the EGL_NATIVE_BUFFER_USAGE_RENDERBUFFER_BIT_ANDROID and + EGL_NATIVE_BUFFER_USAGE_TEXTURE_BIT_ANDROID are set in the value of + EGL_NATIVE_BUFFER_USAGE_ANDROID, the error EGL_BAD_PARAMETER is + Generated." + +Issues + + 1. Should this extension define what combinations of formats and usage flags + EGL implementations are required to support? + + RESOLVED: Partially. + + The set of valid color combinations is implementation-specific and may + depend on additional EGL extensions, but generally RGB565 and RGBA888 should + be supported. The particular valid combinations for a given Android version + and implementation should be documented by that version. + + 2. Should there be an eglDestroyNativeClientBufferANDROID to destroy the + client buffers created by this extension? + + RESOLVED: No. + + A destroy function would add several complications: + + a) ANativeWindowBuffer is a reference counted object, may be used + outside of EGL. + b) The same buffer may back multiple EGLImages, though this usage may + result in undefined behavior. + c) The interactions between the lifetimes of EGLImages and their + EGLClientBuffers would become needlessly complex. + + Because ANativeWindowBuffer is a reference counted object, implementations + of this extension should ensure the buffer has a lifetime at least as long + as a generated EGLImage (via EGL_ANDROID_image_native_buffer). The simplest + method is to increment the reference count of the buffer in + eglCreateImagKHR, and then decrement it in eglDestroyImageKHR. This should + ensure proper lifetime semantics. + +Revision History + +#2 (Craig Donner, April 15, 2016) + - Set color formats and usage bits explicitly using additional attributes, + and add value for new token EGL_NATIVE_BUFFER_USAGE_ANDROID. + +#1 (Craig Donner, January 19, 2016) + - Initial draft. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANDROID/EGL_ANDROID_framebuffer_target.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANDROID/EGL_ANDROID_framebuffer_target.txt new file mode 100644 index 0000000..a15dfa8 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANDROID/EGL_ANDROID_framebuffer_target.txt @@ -0,0 +1,102 @@ +Name + + ANDROID_framebuffer_target + +Name Strings + + EGL_ANDROID_framebuffer_target + +Contributors + + Jamie Gennis + +Contact + + Jamie Gennis, Google Inc. (jgennis 'at' google.com) + +Status + + Complete + +Version + + Version 1, September 20, 2012 + +Number + + EGL Extension #47 + +Dependencies + + Requires EGL 1.0 + + This extension is written against the wording of the EGL 1.4 Specification + +Overview + + Android supports a number of different ANativeWindow implementations that + can be used to create an EGLSurface. One implementation, which is used to + send the result of performing window composition to a display, may have + some device-specific restrictions. Because of this, some EGLConfigs may + be incompatible with these ANativeWindows. This extension introduces a + new boolean EGLConfig attribute that indicates whether the EGLConfig + supports rendering to an ANativeWindow for which the buffers are passed to + the HWComposer HAL as a framebuffer target layer. + +New Types + + None. + +New Procedures and Functions + + None. + +New Tokens + + Accepted by the <attribute> parameter of eglGetConfigAttrib and + the <attrib_list> parameter of eglChooseConfig: + + EGL_FRAMEBUFFER_TARGET_ANDROID 0x3147 + +Changes to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors) + + Section 3.4, Configuration Management, add a row to Table 3.1. + + Attribute Type Notes + ------------------------------ ------- --------------------------- + EGL_FRAMEBUFFER_TARGET_ANDROID boolean whether use as a HWComposer + framebuffer target layer is + supported + + Section 3.4, Configuration Management, add a row to Table 3.4. + + Attribute Default Selection Sort Sort + Criteria Order Priority + ------------------------------ ------------- --------- ----- -------- + EGL_FRAMEBUFFER_TARGET_ANDROID EGL_DONT_CARE Exact None + + Section 3.4, Configuration Management, add a paragraph at the end of the + subsection titled Other EGLConfig Attribute Descriptions. + + EGL_FRAMEBUFFER_TARGET_ANDROID is a boolean indicating whether the + config may be used to create an EGLSurface from an ANativeWindow for + which the buffers are to be passed to HWComposer as a framebuffer + target layer. + + Section 3.4.1, Querying Configurations, change the last paragraph as follow + + EGLConfigs are not sorted with respect to the parameters + EGL_BIND_TO_TEXTURE_RGB, EGL_BIND_TO_TEXTURE_RGBA, EGL_CONFORMANT, + EGL_LEVEL, EGL_NATIVE_RENDERABLE, EGL_MAX_SWAP_INTERVAL, + EGL_MIN_SWAP_INTERVAL, EGL_RENDERABLE_TYPE, EGL_SURFACE_TYPE, + EGL_TRANSPARENT_TYPE, EGL_TRANSPARENT_RED_VALUE, + EGL_TRANSPARENT_GREEN_VALUE, EGL_TRANSPARENT_BLUE_VALUE, and + EGL_RECORDABLE_ANDROID. + +Issues + + +Revision History + +#1 (Jamie Gennis, September 20, 2012) + - Initial draft. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANDROID/EGL_ANDROID_front_buffer_auto_refresh.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANDROID/EGL_ANDROID_front_buffer_auto_refresh.txt new file mode 100644 index 0000000..4c0e64c --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANDROID/EGL_ANDROID_front_buffer_auto_refresh.txt @@ -0,0 +1,70 @@ +Name + + ANDROID_front_buffer_auto_refresh + +Name Strings + + EGL_ANDROID_front_buffer_auto_refresh + +Contributors + + Pablo Ceballos + +Contact + + Pablo Ceballos, Google Inc. (pceballos 'at' google.com) + +Status + + Draft + +Version + + Version 1, February 3, 2016 + +Number + + EGL Extension #XXX + +Dependencies + + Requires EGL 1.2 + + This extension is written against the wording of the EGL 1.5 Specification + +Overview + + This extension is intended for latency-sensitive applications that are doing + front-buffer rendering. It allows them to indicate to the Android compositor + that it should perform composition every time the display refreshes. This + removes the overhead of having to notify the compositor that the window + surface has been updated, but it comes at the cost of doing potentially + unneeded composition work if the window surface has not been updated. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + EGL_FRONT_BUFFER_AUTO_REFRESH_ANDROID 0x314C + +Add to the list of supported tokens for eglSurfaceAttrib in section 3.5.6 +"Surface Attributes", page 43: + + If attribute is EGL_ANDROID_front_buffer_auto_refresh, then value specifies + whether to enable or disable auto-refresh in the Android compositor when + doing front-buffer rendering. + +Issues + + None + +Revision History + +#1 (Pablo Ceballos, February 3, 2016) + - Initial draft. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANDROID/EGL_ANDROID_get_frame_timestamps.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANDROID/EGL_ANDROID_get_frame_timestamps.txt new file mode 100644 index 0000000..bf8d149 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANDROID/EGL_ANDROID_get_frame_timestamps.txt @@ -0,0 +1,259 @@ +Name + + ANDROID_get_frame_timestamps + +Name Strings + + EGL_ANDROID_get_frame_timestamps + +Contributors + + Brian Anderson + Dan Stoza + Pablo Ceballos + Jesse Hall + Fabien Sanglard + +Contact + + Brian Anderson, Google Inc. (brianderson 'at' google.com) + Dan Stoza, Google Inc. (stoza 'at' google.com) + Pablo Ceballos, Google Inc. (pceballos 'at' google.com) + Jesse Hall, Google Inc. (jessehall 'at' google.com) + Fabien Sanglard, Google Inc. (sanglardf 'at' google.com) + +Status + + Draft + +Version + + Version 8, April 11, 2017 + +Number + + EGL Extension #122 + +Dependencies + + Requires EGL 1.2 + + This extension is written against the wording of the EGL 1.5 Specification + +Overview + + This extension allows querying various timestamps related to the composition + and display of window surfaces. + + Some examples of how this might be used: + - The display present time can be used to calculate end-to-end latency + of the entire graphics pipeline. + - The queue time and rendering complete time can be used to determine + how long the application's rendering took to complete. Likewise, the + composition start time and finish time can be used to determine how + long the compositor's rendering work took. In combination these can be + used to help determine if the system is GPU or CPU bound. + +New Types + + /* + * EGLnsecsANDROID is a signed integer type for representing a time in + * nanoseconds. + */ + #include <khrplatform.h> + typedef khronos_stime_nanoseconds_t EGLnsecsANDROID; + +New Procedures and Functions + + EGLBoolean eglGetNextFrameIdANDROID(EGLDisplay dpy, EGLSurface surface, + EGLuint64KHR *frameId); + + EGLBoolean eglGetCompositorTimingANDROID(EGLDisplay dpy, + EGLSurface surface, EGLint numTimestamps, + const EGLint *names, EGLnsecsANDROID *values); + + EGLBoolean eglGetFrameTimestampsANDROID(EGLDisplay dpy, EGLSurface surface, + EGLuint64KHR frameId, EGLint numTimestamps, + const EGLint *timestamps, EGLnsecsANDROID *values); + + EGLBoolean eglGetFrameTimestampSupportedANDROID(EGLDisplay dpy, + EGLSurface surface, EGLint timestamp); + +New Tokens + + EGL_TIMESTAMPS_ANDROID 0x3430 + EGL_COMPOSITE_DEADLINE_ANDROID 0x3431 + EGL_COMPOSITE_INTERVAL_ANDROID 0x3432 + EGL_COMPOSITE_TO_PRESENT_LATENCY_ANDROID 0x3433 + EGL_REQUESTED_PRESENT_TIME_ANDROID 0x3434 + EGL_RENDERING_COMPLETE_TIME_ANDROID 0x3435 + EGL_COMPOSITION_LATCH_TIME_ANDROID 0x3436 + EGL_FIRST_COMPOSITION_START_TIME_ANDROID 0x3437 + EGL_LAST_COMPOSITION_START_TIME_ANDROID 0x3438 + EGL_FIRST_COMPOSITION_GPU_FINISHED_TIME_ANDROID 0x3439 + EGL_DISPLAY_PRESENT_TIME_ANDROID 0x343A + EGL_DEQUEUE_READY_TIME_ANDROID 0x343B + EGL_READS_DONE_TIME_ANDROID 0x343C + EGL_TIMESTAMP_PENDING_ANDROID -2 + EGL_TIMESTAMP_INVALID_ANDROID -1 + +Add to the list of supported tokens for eglSurfaceAttrib in section 3.5.6 +"Surface Attributes", page 43: + + If attribute is EGL_TIMESTAMPS_ANDROID, then values specifies whether to + enable/disable timestamp collection for this surface. A value of EGL_TRUE + enables timestamp collection, while a value of EGL_FALSE disables it. The + initial value is false. If surface is not a window surface this has no + effect. +Changes to Chapter 3 of the EGL 1.5 Specification (EGL Functions and Errors) + + Add a new subsection under Section 3, + + "3.13 Composition and Display Timestamps + + The function + + EGLBoolean eglGetNextFrameIdANDROID(EGLDisplay dpy, EGLSurface surface, + EGLuint64KHR *frameId); + + Returns an identifier for the next frame to be swapped. The identifier can + be used to correlate a particular eglSwapBuffers with its timestamps in + eglGetFrameTimestampsANDROID. If any error is generated, the function will + return EGL_FALSE. + + The function + + EGLBoolean eglGetCompositorTimingANDROID(EGLDisplay dpy, + EGLSurface surface, EGLint numTimestamps, + const EGLint *names, EGLnsecsANDROID *values); + + allows querying anticipated timestamps and durations related to the + composition and display of a window surface. The values are not associated + with a particular frame and can be retrieved before the first swap. + + The eglGetCompositorTimingANDROID function takes an array of names to + query and returns their values in the corresponding indices of the values + array. The possible names that can be queried are: + - EGL_COMPOSITE_DEADLINE_ANDROID - The timestamp of the next time the + compositor will begin composition. This is effectively the deadline + for when the compositor must receive a newly queued frame. + - EGL_COMPOSITE_INTERVAL_ANDROID - The time delta between subsequent + composition events. + - EGL_COMPOSITE_TO_PRESENT_LATENCY_ANDROID - The time delta between + the start of composition and the expected present time of that + composition. This can be used to estimate the latency of the + actual present time. + + The function + + EGLBoolean eglGetFrameTimestampsANDROID(EGLDisplay dpy, + EGLSurface surface, EGLuint64KHR frameId, EGLint numTimestamps, + const EGLint *timestamps, EGLnsecsANDROID *values); + + allows querying various timestamps related to the composition and display + of specific frames of a window surface. + + The frameId indicates which frame to query. The implementation maintains a + limited history of timestamp data. If a query is made for a frame whose + timestamp history no longer exists then EGL_BAD_ACCESS is generated. If + timestamp collection has not been enabled for the surface then + EGL_BAD_SURFACE is generated. Timestamps for events that might still occur + will have the value EGL_TIMESTAMP_PENDING_ANDROID. Timestamps for events + that did not occur will have the value EGL_TIMESTAMP_INVALID_ANDROID. + Otherwise, the timestamp will be valid and indicate the event has occured. + Timestamp queries that are not supported will generate an EGL_BAD_PARAMETER + error. If any error is generated the function will return EGL_FALSE. + + The application can poll for the timestamp of particular events by calling + eglGetFrameTimestamps over and over without needing to call any other EGL + function between calls. This is true even for the most recently swapped + frame. eglGetFrameTimestamps is thread safe and can be called from a + different thread than the swapping thread. + + The eglGetFrameTimestampsANDROID function takes an array of timestamps to + query and returns timestamps in the corresponding indices of the values + array. The possible timestamps that can be queried are: + - EGL_REQUESTED_PRESENT_TIME_ANDROID - The time the application + requested this frame be presented. See EGL_ANDROID_presentation_time. + If the application does not request a presentation time explicitly, + this will correspond to buffer's queue time. + - EGL_RENDERING_COMPLETE_TIME_ANDROID - The time when all of the + application's rendering to the surface was completed. + - EGL_COMPOSITION_LATCH_TIME_ANDROID - The time when the compositor + selected this frame as the one to use for the next composition. The + latch is the earliest indication that the frame was submitted in time + to be composited. + - EGL_FIRST_COMPOSITION_START_TIME_ANDROID - The first time at which + the compositor began preparing composition for this frame. + - EGL_LAST_COMPOSITION_START_TIME_ANDROID - The last time at which the + compositor began preparing composition for this frame. If this frame + is composited only once, it will have the same value as + EGL_FIRST_COMPOSITION_START_TIME_ANDROID. If the value is not equal, + that indicates the subsequent frame was not submitted in time to be + latched by the compositor. Note: The value may not be updated for + every display refresh if the compositor becomes idle. + - EGL_FIRST_COMPOSITION_GPU_FINISHED_TIME_ANDROID - The time at which + the compositor's rendering work for this frame finished. This will be + zero if composition was handled by the display and the compositor + didn't do any rendering. + - EGL_DISPLAY_PRESENT_TIME_ANDROID - The time at which this frame + started to scan out to the physical display. + - EGL_DEQUEUE_READY_TIME_ANDROID - The time when the buffer became + available for reuse as a buffer the client can target without + blocking. This is generally the point when all read commands of the + buffer have been submitted, but not necessarily completed. + - EGL_READS_DONE_TIME_ANDROID - The time at which all reads for the + purpose of display/composition were completed for this frame. + + Not all implementations may support all of the above timestamp queries. The + functions + + EGLBoolean eglGetCompositorTimingSupportedANDROID(EGLDisplay dpy, + EGLSurface surface, EGLint name); + + and + + EGLBoolean eglGetFrameTimestampSupportedANDROID(EGLDisplay dpy, + EGLSurface surface, EGLint timestamp); + + allows querying which values are supported by the implementations of + eglGetCompositorTimingANDROID and eglGetFrameTimestampSupportedANDROID + respectively." + +Issues + + None + +Revision History + +#9 (Chris Forbes, June 11, 2019) + - Fix eglGetFrameTimestampSupportedANDROID function name in extension + spec to match reality + +#8 (Brian Anderson, April 11, 2017) + - Use reserved enumerant values. + +#7 (Brian Anderson, March 21, 2017) + - Differentiate between pending events and events that did not occur. + +#6 (Brian Anderson, March 16, 2017) + - Remove DISPLAY_RETIRE_TIME_ANDROID. + +#5 (Brian Anderson, January 13, 2017) + - Add eglGetCompositorTimingANDROID. + +#4 (Brian Anderson, January 10, 2017) + - Use an absolute frameId rather than a relative framesAgo. + +#3 (Brian Anderson, November 30, 2016) + - Add EGL_COMPOSITION_LATCH_TIME_ANDROID, + EGL_LAST_COMPOSITION_START_TIME_ANDROID, and + EGL_DEQUEUE_READY_TIME_ANDROID. + +#2 (Brian Anderson, July 22, 2016) + - Replace EGL_QUEUE_TIME_ANDROID with EGL_REQUESTED_PRESENT_TIME_ANDROID. + - Add DISPLAY_PRESENT_TIME_ANDROID. + +#1 (Pablo Ceballos, May 31, 2016) + - Initial draft. + diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANDROID/EGL_ANDROID_get_native_client_buffer.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANDROID/EGL_ANDROID_get_native_client_buffer.txt new file mode 100644 index 0000000..285bba4 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANDROID/EGL_ANDROID_get_native_client_buffer.txt @@ -0,0 +1,102 @@ +Name + + ANDROID_get_native_client_buffer + +Name Strings + + EGL_ANDROID_get_native_client_buffer + +Contributors + + Craig Donner + +Contact + + Craig Donner, Google Inc. (cdonner 'at' google.com) + +Status + + Complete + +Version + + Version 3, October 11, 2017 + +Number + + EGL Extension #123 + +Dependencies + + Requires EGL 1.2. + + EGL_ANDROID_image_native_buffer and EGL_KHR_image_base are required. + + This extension is written against the wording of the EGL 1.2 + Specification as modified by EGL_KHR_image_base and + EGL_ANDROID_image_native_buffer. + +Overview + + This extension allows creating an EGLClientBuffer from an Android + AHardwareBuffer object which can be later used to create an EGLImage. + +New Types + + struct AHardwareBuffer + +New Procedures and Functions + + EGLClientBuffer eglGetNativeClientBufferANDROID(const struct AHardwareBuffer *buffer) + +New Tokens + + None + +Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors) + + Add the following to section 2.5.1 "EGLImage Specification" (as modified by + the EGL_KHR_image_base and EGL_ANDROID_image_native_buffer specifications), + below the description of eglCreateImageKHR: + + "The command + + EGLClientBuffer eglGetNativeClientBufferANDROID( + const struct AHardwareBuffer *buffer) + + may be used to create an EGLClientBuffer from an AHardwareBuffer object. + EGL implementations must guarantee that the lifetime of the returned + EGLClientBuffer is at least as long as the EGLImage(s) it is bound to, + following the lifetime semantics described below in section 2.5.2; the + EGLClientBuffer must be destroyed no earlier than when all of its associated + EGLImages are destroyed by eglDestroyImageKHR. + + Errors + + If eglGetNativeClientBufferANDROID fails, NULL will be returned, no + memory will be allocated, and the following error will be generated: + + * If the value of buffer is NULL, the error EGL_BAD_PARAMETER is + generated. + +Issues + + 1. Should this extension define what particular AHardwareBuffer formats EGL + implementations are required to support? + + RESOLVED: No. + + The set of valid formats is implementation-specific and may depend on + additional EGL extensions. The particular valid combinations for a given + Android version and implementation should be documented by that version. + +Revision History + +#3 (Jesse Hall, October 11, 2017) + - Assigned extension number, fixed minor issues for publication + +#2 (Craig Donner, February 17, 2017) + - Fix typographical errors. + +#1 (Craig Donner, January 27, 2017) + - Initial draft. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANDROID/EGL_ANDROID_image_native_buffer.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANDROID/EGL_ANDROID_image_native_buffer.txt new file mode 100644 index 0000000..7392d4f --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANDROID/EGL_ANDROID_image_native_buffer.txt @@ -0,0 +1,108 @@ +Name + + ANDROID_image_native_buffer + +Name Strings + + EGL_ANDROID_image_native_buffer + +Contributors + + Mathias Agopian + Jamie Gennis + Jesse Hall + +Contact + + Jesse Hall, Google Inc. (jessehall 'at' google.com) + +Status + + Complete + +Version + + Version 1, November 28, 2012 + +Number + + EGL Extension #49 + +Dependencies + + EGL 1.2 is required. + + EGL_KHR_image_base is required. + + This extension is written against the wording of the EGL 1.2 + Specification. + +Overview + + This extension enables using an Android window buffer (struct + ANativeWindowBuffer) as an EGLImage source. + +New Types + + None. + +New Procedures and Functions + + None. + +New Tokens + + Accepted by the <target> parameter of eglCreateImageKHR: + + EGL_NATIVE_BUFFER_ANDROID 0x3140 + +Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors) + + 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_BUFFER_ANDROID | Used for ANativeWindowBuffer objects | + +----------------------------+-----------------------------------------+ + Table aaa. Legal values for eglCreateImageKHR <target> parameter + + ... + + If <target> is EGL_NATIVE_BUFFER_ANDROID, <dpy> must be a valid display, + <ctx> must be EGL_NO_CONTEXT, <buffer> must be a pointer to a valid + ANativeWindowBuffer 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_BUFFER_ANDROID and <buffer> is not a + pointer to a valid ANativeWindowBuffer, the error EGL_BAD_PARAMETER + is generated. + + * If <target> is EGL_NATIVE_BUFFER_ANDROID and <ctx> is not + EGL_NO_CONTEXT, the error EGL_BAD_CONTEXT is generated. + + * If <target> is EGL_NATIVE_BUFFER_ANDROID and <buffer> was created + with properties (format, usage, dimensions, etc.) not supported by + the EGL implementation, the error EGL_BAD_PARAMETER is generated." + +Issues + + 1. Should this extension define what combinations of ANativeWindowBuffer + properties implementations are required to support? + + RESOLVED: No. + + The requirements have evolved over time and will continue to change with + future Android releases. The minimum requirements for a given Android + version should be documented by that version. + +Revision History + +#1 (Jesse Hall, November 28, 2012) + - Initial draft. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANDROID/EGL_ANDROID_native_fence_sync.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANDROID/EGL_ANDROID_native_fence_sync.txt new file mode 100644 index 0000000..d72edd7 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANDROID/EGL_ANDROID_native_fence_sync.txt @@ -0,0 +1,281 @@ +Name + + ANDROID_native_fence_sync + +Name Strings + + EGL_ANDROID_native_fence_sync + +Contributors + + Jamie Gennis + +Contact + + Jamie Gennis, Google Inc. (jgennis 'at' google.com) + +Status + + Complete + +Version + + Version 3, September 4, 2012 + +Number + + EGL Extension #50 + +Dependencies + + Requires EGL 1.1 + + This extension is written against the wording of the EGL 1.2 Specification + + EGL_KHR_fence_sync is required. + +Overview + + This extension enables the creation of EGL fence sync objects that are + associated with a native synchronization fence object that is referenced + using a file descriptor. These EGL fence sync objects have nearly + identical semantics to those defined by the KHR_fence_sync extension, + except that they have an additional attribute storing the file descriptor + referring to the native fence object. + + This extension assumes the existence of a native fence synchronization + object that behaves similarly to an EGL fence sync object. These native + objects must have a signal status like that of an EGLSyncKHR object that + indicates whether the fence has ever been signaled. Once signaled the + native object's signal status may not change again. + +New Types + + None. + +New Procedures and Functions + + EGLint eglDupNativeFenceFDANDROID( + EGLDisplay dpy, + EGLSyncKHR); + +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_NATIVE_FENCE_ANDROID 0x3144 + + Accepted by the <attrib_list> parameter of eglCreateSyncKHR: + + EGL_SYNC_NATIVE_FENCE_FD_ANDROID 0x3145 + + Accepted by the <attrib_list> parameter of eglCreateSyncKHR, and returned + by eglDupNativeFenceFDANDROID in the event of an error: + + EGL_NO_NATIVE_FENCE_FD_ANDROID -1 + + Returned in <value> when eglGetSyncAttribKHR is called with <attribute> + EGL_SYNC_CONDITION_KHR: + + EGL_SYNC_NATIVE_FENCE_SIGNALED_ANDROID 0x3146 + +Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors) + + Add the following after the sixth paragraph of Section 3.8.1 (Sync + Objects), added by KHR_fence_sync + + "If <type> is EGL_SYNC_NATIVE_FENCE_ANDROID, an EGL native fence sync + object is created. In this case the EGL_SYNC_NATIVE_FENCE_FD_ANDROID + attribute may optionally be specified. If this attribute is specified, it + must be set to either a file descriptor that refers to a native fence + object or to the value EGL_NO_NATIVE_FENCE_FD_ANDROID. + + The default values for the EGL native fence sync object attributes are as + follows: + + Attribute Name Initial Attribute Value(s) + --------------- -------------------------- + EGL_SYNC_TYPE_KHR EGL_SYNC_NATIVE_FENCE_ANDROID + EGL_SYNC_STATUS_KHR EGL_UNSIGNALED_KHR + EGL_SYNC_CONDITION_KHR EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR + EGL_SYNC_NATIVE_FENCE_FD_ANDROID EGL_NO_NATIVE_FENCE_FD_ANDROID + + If the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute is not + EGL_NO_NATIVE_FENCE_FD_ANDROID then the EGL_SYNC_CONDITION_KHR attribute is + set to EGL_SYNC_NATIVE_FENCE_SIGNALED_ANDROID and the EGL_SYNC_STATUS_KHR + attribute is set to reflect the signal status of the native fence object. + Additionally, the EGL implementation assumes ownership of the file + descriptor, so the caller must not use it after calling eglCreateSyncKHR." + + Modify Section 3.8.1 (Sync Objects), added by KHR_fence_sync, starting at + the seventh paragraph + + "When a fence sync object is created or when an EGL native fence sync + object is created with the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute set + to EGL_NO_NATIVE_FENCE_FD_ANDROID, 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. + + After associating the fence command with an EGL native fence sync object, + the next Flush() operation performed by the current client API causes a + new native fence object to be created, and the + EGL_SYNC_NATIVE_FENCE_ANDROID attribute of the EGL native fence object is + set to a file descriptor that refers to the new native fence object. This + new native fence object is signaled when the EGL native fence sync object + is signaled. + + 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. + If the sync object is an EGL native fence sync object then the native + fence object is also signaled when the condition is satisfied. The + EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR condition 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. + + The EGL_SYNC_NATIVE_FENCE_SIGNALED_ANDROID condition is satisfied by the + signaling of the native fence object referred to by the + EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute. When this happens any + eglClientWaitSyncKHR commands blocking on <sync> unblock." + + Modify the list of eglCreateSyncKHR errors in Section 3.8.1 (Sync Objects), + added by KHR_fence_sync + + "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 <type> is EGL_SYNC_FENCE_KHR and <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 EGL_SYNC_NATIVE_FENCE_ANDROID and <attrib_list> contains + an attribute other than EGL_SYNC_NATIVE_FENCE_FD_ANDROID, + 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 or EGL_SYNC_NATIVE_FENCE_ANDROID 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 or EGL_SYNC_NATIVE_FENCE_ANDROID 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 or EGL_SYNC_NATIVE_FENCE_ANDROID 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." + + Modify table 3.cc in Section 3.8.1 (Sync Objects), added by KHR_fence_sync + + " + 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 and + EGL_SYNC_NATIVE_FENCE_ANDROID only + " + + Modify the second paragraph description of eglDestroySyncKHR in Section + 3.8.1 (Sync Objects), added by KHR_fence_sync + + "If no errors are generated, EGL_TRUE is returned, and <sync> will no + longer be the handle of a valid sync object. Additionally, if <sync> is an + EGL native fence sync object and the EGL_SYNC_NATIVE_FENCE_FD_ANDROID + attribute is not EGL_NO_NATIVE_FENCE_FD_ANDROID then that file descriptor + is closed." + + Add the following after the last paragraph of Section 3.8.1 (Sync + Objects), added by KHR_fence_sync + + The command + + EGLint eglDupNativeFenceFDANDROID( + EGLDisplay dpy, + EGLSyncKHR sync); + + duplicates the file descriptor stored in the + EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute of an EGL native fence sync + object and returns the new file descriptor. + + Errors + ------ + + * If <sync> is not a valid sync object for <dpy>, + EGL_NO_NATIVE_FENCE_FD_ANDROID is returned and an EGL_BAD_PARAMETER + error is generated. + * If the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute of <sync> is + EGL_NO_NATIVE_FENCE_FD_ANDROID, EGL_NO_NATIVE_FENCE_FD_ANDROID 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 + + 1. Should EGLSyncKHR objects that wrap native fence objects use the + EGL_SYNC_FENCE_KHR type? + + RESOLVED: A new sync object type will be added. + + We don't want to require all EGL fence sync objects to wrap native fence + objects, so we need some way to tell the EGL implementation at sync object + creation whether the sync object should support querying the native fence + FD attribute. We could do this with either a new sync object type or with a + boolean attribute. It might be nice to pick up future signaling conditions + that might be added for fence sync objects, but there may be things that + get added that don't make sense in the context of native fence objects. + + 2. Who is responsible for dup'ing the native fence file descriptors? + + RESOLVED: Whenever a file descriptor is passed into or returned from an + EGL call in this extension, ownership of that file descriptor is + transfered. The recipient of the file descriptor must close it when it is + no longer needed, and the provider of the file descriptor must dup it + before providing it if they require continued use of the native fence. + + 3. Can the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute be queried? + + RESOLVED: No. + + Returning the file descriptor owned by the EGL implementation would + violate the file descriptor ownership rule described in issue #2. Having + eglGetSyncAttribKHR return a different (dup'd) file descriptor each time + it's called seems wrong, so a new function was added to explicitly dup the + file descriptor. + + That said, the attribute is useful both as a way to pass an existing file + descriptor to eglCreateSyncKHR and as a way to describe the subsequent + behavior of EGL native fence sync objects, so it is left as an attribute + for which the value cannot be queried. + +Revision History + +#3 (Jamie Gennis, September 4, 2012) + - Reworded the extension to refer to "native fence" objects rather than + "Android fence" objects. + - Added a paragraph to the overview that describes assumptions about the + native fence sync objects. + +#2 (Jamie Gennis, July 23, 2012) + - Changed the file descriptor ownership transferring behavior. + - Added the eglDupAndroidFenceFDANDROID function. + - Removed EGL_SYNC_NATIVE_FENCE_FD_ANDROID from the table of gettable + attributes. + - Added language specifying that a native Android fence is created at the + flush following the creation of an EGL Android fence sync object that is + not passed an existing native fence. + +#1 (Jamie Gennis, May 29, 2012) + - Initial draft. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANDROID/EGL_ANDROID_presentation_time.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANDROID/EGL_ANDROID_presentation_time.txt new file mode 100644 index 0000000..ac1f45e --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANDROID/EGL_ANDROID_presentation_time.txt @@ -0,0 +1,140 @@ +Name + + ANDROID_presentation_time + +Name Strings + + EGL_ANDROID_presentation_time + +Contributors + + Jamie Gennis + Andy McFadden + Jesse Hall + +Contact + + Jamie Gennis, Google Inc. (jgennis 'at' google.com) + +Status + + Draft + +Version + + Version 4, June 6, 2016 + +Number + + EGL Extension #98 + +Dependencies + + Requires EGL 1.1 + + This extension is written against the wording of the EGL 1.4 Specification + +Overview + + Often when rendering a sequence of images, there is some time at which each + image is intended to be presented to the viewer. This extension allows + this desired presentation time to be specified for each frame rendered to + an EGLSurface, allowing the native window system to use it. + +New Types + + /* + * EGLnsecsANDROID is a signed integer type for representing a time in + * nanoseconds. + */ + #include <khrplatform.h> + typedef khronos_stime_nanoseconds_t EGLnsecsANDROID; + + +New Procedures and Functions + + EGLBoolean eglPresentationTimeANDROID( + EGLDisplay dpy, + EGLSurface surface, + EGLnsecsANDROID time); + +New Tokens + + None. + +Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors) + + Add a new subsection before Section 3.9.4, page 53 (Posting Errors) + + "3.9.4 Presentation Time + + The function + + EGLBoolean eglPresentationTimeANDROID(EGLDisplay dpy, EGLSurface + surface, EGLnsecsANDROID time); + + specifies the time at which the current color buffer of <surface> should be + presented to the viewer. The <time> parameter should be a time in + nanoseconds, but the exact meaning of the time depends on the native + window system's use of the presentation time. In situations where + an absolute time is needed such as displaying the color buffer on a + display device, the time should correspond to the system monotonic up-time + clock. For situations in which an absolute time is not needed such as + using the color buffer for video encoding, the presentation time of the + first frame may be arbitrarily chosen and those of subsequent frames + chosen relative to that of the first frame. + + The presentation time may be set multiple times, with each call to + eglPresentationTimeANDROID overriding prior calls. Setting the + presentation time alone does not cause the color buffer to be made + visible, but if the color buffer is subsequently posted to a native window + or copied to a native pixmap then the presentation time of the surface at + that time may be passed along for the native window system to use. + + If the surface presentation time is successfully set, EGL_TRUE is + returned. Otherwise EGL_FALSE is returned and an appropriate error is + set. If <dpy> is not the name of a valid, initialized EGLDisplay, an + EGL_BAD_DISPLAY error is generated. If <surface> is not a valid EGLSurface + then an EGL_BAD_SURFACE error is generated. + +Issues + + 1. How is the presentation time used? + + RESOLVED: The uses of the presentation time are intentionally not specified + in this extension. Some possible uses include Audio/Video synchronization, + video frame timestamps for video encoding, display latency metrics, and + display latency control. + + 2. How can the current value of the clock that should be used for the + presentation time when an absolute time is needed be queried on Android? + + RESOLVED: The current clock value can be queried from the Java + System.nanoTime() method, or from the native clock_gettime function by + passing CLOCK_MONOTONIC as the clock identifier. + + 3. Should the presentation time be state which is used by eglSwapBuffers, + or should it be a new parameter to an extended variant of eglSwapBuffers? + + RESOLVED: The presentation time should be new state which is used by + the existing eglSwapBuffers call. Adding new state composes better with + other (hypothetical) extensions that also modify the behavior of + eglSwapBuffers. + +Revision History + +#4 (Jon Leech, June 6, 2016) + - Clean up for publication. Make prototype parameter name 'surface' + match the spec body. + +#3 (Jesse Hall, June 26, 2013) + - Enumerated errors generated by eglPresentationTimeANDROID. + - Added Issue #3 with resolution. + +#2 (Jamie Gennis, April 1, 2013) + - Clarified how uses that either do or do not need an absolute time should + be handled. + - Specified the eglPresentationTimeANDROID return value. + +#1 (Jamie Gennis, January 8, 2013) + - Initial draft. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANDROID/EGL_ANDROID_recordable.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANDROID/EGL_ANDROID_recordable.txt new file mode 100644 index 0000000..d21094e --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANDROID/EGL_ANDROID_recordable.txt @@ -0,0 +1,140 @@ +Name + + ANDROID_recordable + +Name Strings + + EGL_ANDROID_recordable + +Contributors + + Jamie Gennis + +Contact + + Jamie Gennis, Google Inc. (jgennis 'at' google.com) + +Status + + Complete + +Version + + Version 2, July 15, 2011 + +Number + + EGL Extension #51 + +Dependencies + + Requires EGL 1.0 + + This extension is written against the wording of the EGL 1.4 Specification + +Overview + + Android supports a number of different ANativeWindow implementations that + can be used to create an EGLSurface. One implementation, which records the + rendered image as a video each time eglSwapBuffers gets called, may have + some device-specific restrictions. Because of this, some EGLConfigs may be + incompatible with these ANativeWindows. This extension introduces a new + boolean EGLConfig attribute that indicates whether the EGLConfig supports + rendering to an ANativeWindow that records images to a video. + +New Types + + None. + +New Procedures and Functions + + None. + +New Tokens + + Accepted by the <attribute> parameter of eglGetConfigAttrib and + the <attrib_list> parameter of eglChooseConfig: + + EGL_RECORDABLE_ANDROID 0x3142 + +Changes to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors) + + Section 3.4, Configuration Management, add a row to Table 3.1. + + Attribute Type Notes + ---------------------- ------- -------------------------- + EGL_RECORDABLE_ANDROID boolean whether video recording is + supported + + Section 3.4, Configuration Management, add a row to Table 3.4. + + Attribute Default Selection Sort Sort + Criteria Order Priority + ---------------------- ------------- --------- ----- -------- + EGL_RECORDABLE_ANDROID EGL_DONT_CARE Exact None + + Section 3.4, Configuration Management, add a paragraph at the end of the + subsection titled Other EGLConfig Attribute Descriptions. + + EGL_RECORDABLE_ANDROID is a boolean indicating whether the config may + be used to create an EGLSurface from an ANativeWindow that is a video + recorder as indicated by the NATIVE_WINDOW_IS_VIDEO_RECORDER query on + the ANativeWindow. + + Section 3.4.1, Querying Configurations, change the last paragraph as follow + + EGLConfigs are not sorted with respect to the parameters + EGL_BIND_TO_TEXTURE_RGB, EGL_BIND_TO_TEXTURE_RGBA, EGL_CONFORMANT, + EGL_LEVEL, EGL_NATIVE_RENDERABLE, EGL_MAX_SWAP_INTERVAL, + EGL_MIN_SWAP_INTERVAL, EGL_RENDERABLE_TYPE, EGL_SURFACE_TYPE, + EGL_TRANSPARENT_TYPE, EGL_TRANSPARENT_RED_VALUE, + EGL_TRANSPARENT_GREEN_VALUE, EGL_TRANSPARENT_BLUE_VALUE, and + EGL_RECORDABLE_ANDROID. + +Issues + + 1. Should this functionality be exposed as a new attribute or as a bit in + the EGL_SURFACE_TYPE bitfield? + + RESOLVED: It should be a new attribute. It does not make sense to use up a + bit in the limit-size bitfield for a platform-specific extension. + + 2. How should the new attribute affect the sorting of EGLConfigs? + + RESOLVED: It should not affect sorting. Some implementations may not have + any drawback associated with using a recordable EGLConfig. Such + implementations should not have to double-up some of their configs to one + sort earlier than . Implementations that do have drawbacks can use the + existing caveat mechanism to report this drawback to the client. + + 3. How is this extension expected to be implemented? + + RESPONSE: There are two basic approaches to implementing this extension + that were considered during its design. In both cases it is assumed that a + color space conversion must be performed at some point because most video + encoding formats use a YUV color space. The two approaches are + distinguished by the point at which this color space conversion is + performed. + + One approach involves performing the color space conversion as part of the + eglSwapBuffers call before queuing the rendered image to the ANativeWindow. + In this case, the VisualID of the EGLConfig would correspond to a YUV + Android HAL pixel format from which the video encoder can read. The + EGLConfig would likely have the EGL_SLOW_CONFIG caveat because using that + config to render normal window contents would result in an RGB -> YUV color + space conversion when rendering the frame as well as a YUV -> RGB + conversion when compositing the window. + + The other approach involves performing the color space conversion in the + video encoder. In this case, the VisualID of the EGLConfig would + correspond to an RGB HAL pixel format from which the video encoder can + read. The EGLConfig would likely not need to have any caveat set, as using + this config for normal window rendering would not have any added cost. + +Revision History + +#2 (Jamie Gennis, July 15, 2011) + - Added issue 3. + +#1 (Jamie Gennis, July 8, 2011) + - Initial draft. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANGLE/EGL_ANGLE_d3d_share_handle_client_buffer.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANGLE/EGL_ANGLE_d3d_share_handle_client_buffer.txt new file mode 100644 index 0000000..b205883 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANGLE/EGL_ANGLE_d3d_share_handle_client_buffer.txt @@ -0,0 +1,98 @@ +Name + + ANGLE_d3d_share_handle_client_buffer + +Name Strings + + EGL_ANGLE_d3d_share_handle_client_buffer + +Contributors + + John Bauman + Alastair Patrick + Daniel Koch + +Contacts + + John Bauman, Google Inc. (jbauman 'at' chromium.org) + +Status + + Complete + Implemented (ANGLE r650) + +Version + + Version 3, May 12, 2011 + +Number + + EGL Extension #38 + +Dependencies + + Requires the EGL_ANGLE_surface_d3d_texture_2d_share_handle extension. + + This extension is written against the wording of the EGL 1.4 + Specification. + +Overview + + This extension allows creating EGL surfaces from handles to textures + shared from the Direct3D API or from + EGL_ANGLE_surface_texture_2d_share_handle. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted in the <buftype> parameter of eglCreatePbufferFromClientBuffer: + + EGL_D3D_TEXTURE_2D_SHARE_HANDLE_ANGLE 0x3200 + +Additions to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors) + + Replace the last sentence of paragraph 1 of Section 3.5.3 with the + following text. + "Currently, the only client API resources which may be bound in this + fashion are OpenVG VGImage objects and Direct3D share handles." + + Replace the last sentence of paragraph 2 ("To bind a client API...") of + Section 3.5.3 with the following text. + "When <buftype> is EGL_OPENVG_IMAGE, the width and height of the pbuffer + are determined by the width and height of <buffer>. When <buftype> is + EGL_D3D_TEXTURE_2D_SHARE_HANDLE_ANGLE, the width and height are specified + using EGL_WIDTH and EGL_HEIGHT, or else they default to zero. The width + and height must match the dimensions of the texture which the share handle + was created from or else an EGL_BAD_ALLOC error is generated." + + Replace the third paragraph of Section 3.5.3 with the following text. + "<buftype> specifies the type of buffer to be bound. The only allowed values + of <buftype> are EGL_OPENVG_IMAGE and + EGL_D3D_TEXTURE_2D_SHARE_HANDLE_ANGLE". + + Append the following text to the fourth paragraph of Section 3.5.3. + "When <buftype> is EGL_D3D_TEXTURE_2D_SHARE_HANDLE_ANGLE, <buffer> must be + a valid D3D share handle, cast into the type EGLClientBuffer. The handle + may be obtained from the Direct3D9Ex CreateTexture function, from DXGI's + GetSharedHandle method on an ID3D10Texture2D, or from the + EGL_ANGLE_surface_d3d_texture_2d_share_handle extension." + +Issues + +Revision History + + Version 3, 2011/05/12 + - publish + + Version 2, 2011/05/03 + - specify EGL_D3D_TEXTURE_2D_SHARE_HANDLE + - specify error if dimensions don't match + + Version 1, 2011/04/12 - first draft. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANGLE/EGL_ANGLE_device_d3d.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANGLE/EGL_ANGLE_device_d3d.txt new file mode 100644 index 0000000..8e606cd --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANGLE/EGL_ANGLE_device_d3d.txt @@ -0,0 +1,93 @@ +Name + + ANGLE_device_d3d + +Name Strings + + EGL_ANGLE_device_d3d + +Contributors + + Jamie Madill (jmadill 'at' google.com) + +Contact + + Jamie Madill (jmadill 'at' google.com) + +Status + + Complete. + +Version + + Version 1, Mar 25, 2015 + +Number + + EGL Extension #90 + +Extension Type + + EGL device extension + +Dependencies + + This extension is written against the language of EGL 1.5 as + modified by EGL_EXT_device_query. + + EGL_EXT_device_query is required. + +Overview + + ANGLE has the ability to run GPU commands on a native D3D device. + This extension defines a mapping from an EGL device to a D3D + device, after it's queried from an EGL display. + +IP Status + + No known claims. + +New Types + + None. + +New Procedures and Functions + + None. + +New Tokens + + Accepted as a queried <attribute> in eglQueryDeviceAttribEXT: + + EGL_D3D9_DEVICE_ANGLE 0x33A0 + EGL_D3D11_DEVICE_ANGLE 0x33A1 + +Add a new section 2.1.3 (D3D Devices) after 2.1.2 (Devices) + + Somewhat analogous to an EGL device, a D3D device establishes a + namespace for D3D operations. In the D3D APIs, such devices are + represented by pointers. For more details, see the D3D + documentation. + +Changes to section 3.2 (Devices) + + Replace the paragraph immediately following the prototype for + eglQueryDeviceAttribEXT: + + <attribute> may be either EGL_D3D9_DEVICE_ANGLE or EGL_D3D11_DEVICE_ANGLE. + On success, EGL_TRUE is returned, and a valid D3D9 or D3D11 device pointer + corresponding to the EGL device is returned in <value>. This handle + is compatible with D3D API functions. If the EGL device is not currently + associated with a D3D9 device and <attribute> is EGL_D3D9_DEVICE_ANGLE, + or if the EGL device is not currently associated with a D3D11 device and + <attribute> is EGL_D3D11_DEVICE_ANGLE, EGL_BAD_ATTRIBUTE is returned, + and <value> is left unchanged. + +Issues + + None + +Revision History + + Version 1, Mar 25, 2015 (Jamie Madill) + - Initial Draft diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANGLE/EGL_ANGLE_query_surface_pointer.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANGLE/EGL_ANGLE_query_surface_pointer.txt new file mode 100644 index 0000000..75126fc --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANGLE/EGL_ANGLE_query_surface_pointer.txt @@ -0,0 +1,88 @@ +Name + + ANGLE_query_surface_pointer + +Name Strings + + EGL_ANGLE_query_surface_pointer + +Contributors + + Vladimir Vukicevic + Daniel Koch + +Contacts + + Vladimir Vukicevic (vladimir 'at' pobox.com) + +Status + + Complete + Implemented (ANGLE r558) + +Version + + Version 3, February 11, 2011 + +Number + + EGL Extension #28 + +Dependencies + + This extension is written against the wording of the EGL 1.4 + Specification. + +Overview + + This extension allows querying pointer-sized surface attributes, + thus avoiding problems with coercing 64-bit pointers into a 32-bit + integer. + +New Types + + None + +New Procedures and Functions + + EGLBoolean eglQuerySurfacePointerANGLE( + EGLDisplay dpy, + EGLSurface surface, + EGLint attribute, + void **value); + +New Tokens + + None + +Additions to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors) + + Add to the end of the paragraph starting with "To query an + attribute associated with an EGLSurface" in section 3.5.6, + "Surface Attributes": + + "If the attribute type in table 3.5 is 'pointer', then + eglQuerySurface returns EGL_FALSE and an EGL_BAD_PARAMETER error + is generated. To query pointer attributes, call: + + EGLBoolean eglQuerySurfacePointerANGLE( + EGLDisplay dpy, + EGLSurface surface, + EGLint attribute, + void **value); + + eglQuerySurfacePointerANGLE behaves identically to eglQuerySurface, + except that only attributes of type 'pointer' can be queried. + If an attribute queried via eglQuerySurfacePointerANGLE is not + of type 'pointer', then eglQuerySurfacePointer returns EGL_FALSE + and an EGL_BAD_PARAMETER error is generated." + +Issues + +Revision History + + Version 3, 2011/02/11 - publish + + Version 2, 2010/12/21 - fix typos. + + Version 1, 2010/12/07 - first draft. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANGLE/EGL_ANGLE_surface_d3d_texture_2d_share_handle.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANGLE/EGL_ANGLE_surface_d3d_texture_2d_share_handle.txt new file mode 100644 index 0000000..917e445 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANGLE/EGL_ANGLE_surface_d3d_texture_2d_share_handle.txt @@ -0,0 +1,95 @@ +Name + + ANGLE_surface_d3d_texture_2d_share_handle + +Name Strings + + EGL_ANGLE_surface_d3d_texture_2d_share_handle + +Contributors + + Vladimir Vukicevic + Daniel Koch + +Contacts + + Vladimir Vukicevic (vladimir 'at' pobox.com) + +Status + + Complete + Implemented (ANGLE r558) + +Version + + Version 2, December 21, 2010 + +Number + + EGL Extension #29 + +Dependencies + + Requires the EGL_ANGLE_query_surface_pointer extension. + + This extension is written against the wording of the EGL 1.4 + Specification. + +Overview + + Some EGL implementations generate EGLSurface handles that are + backed by Direct3D 2D textures. For such surfaces, a D3D share + handle can be generated, allowing access to the same surface + from the Direct3D API. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted in the <attribute> parameter of eglQuerySurfacePointerANGLE: + + EGL_D3D_TEXTURE_2D_SHARE_HANDLE_ANGLE 0x3200 + +Additions to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors) + + Add to table 3.5, "Queryable surface attributes and types": + + Attribute Type Description + --------- ---- ----------- + EGL_D3D_TEXTURE_2D_SHARE_HANDLE_ANGLE pointer Direct3D share handle + + Add before the last paragraph in section 3.5, "Surface attributes": + + "Querying EGL_D3D_TEXTURE_2D_SHARE_HANDLE_ANGLE returns a Direct3D + share handle, or NULL if a share handle for the surface is not + available. The share handle must be queried using + eglQuerySurfaceAttribPointerANGLE. Before using a Direct3D surface + created with this share handle, ensure that all rendering + to the EGLSurface with EGL client APIs has completed. + + The Direct3D share handle may be passed as the pSharedHandle + parameter of the Direct3D9Ex CreateTexture function, or via the + Direct3D10 OpenSharedResource function. If used with Direct3D 9, + the level argument to CreateTexture must be 1, and the dimensions + must match the dimensions of the EGL surface. If used with + Direct3D 10, OpenSharedResource should be called with the + ID3D10Texture2D uuid to obtain an ID3D10Texture2D object. + +Issues + +Revision History + + Version 3, 2011/02/11 - publish + + Version 2, 2010/12/21 + - renamed token to EGL_D3D_TEXTURE_2D_SHARE_HANDLE_ANGLE (adding "2D") + - renamed extension to ANGLE_surface_d3d_texture_2d_share_handle + - added language about supported usage of the shared handle from D3D + + Version 1, 2010/12/07 - first draft. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANGLE/EGL_ANGLE_sync_control_rate.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANGLE/EGL_ANGLE_sync_control_rate.txt new file mode 100644 index 0000000..4259145 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANGLE/EGL_ANGLE_sync_control_rate.txt @@ -0,0 +1,99 @@ +Name + + ANGLE_sync_control_rate + +Name Strings + + EGL_ANGLE_sync_control_rate + +Contact + + Jonah Ryan-Davis, Google (jonahr 'at' google.com) + +Status + + Draft. + +Version + + Version 1, 2020-03-24 + + Based on GLX_OML_sync_control Revision 6.0 + Related to EGL_CHROMIUM_sync_control Revision 2.0 + +Number + + 142 + +Dependencies + + The extension is written against the EGL 1.2 Specification, although it + should work on other versions of these specifications. + +Overview + + This extension provides counters which let applications know about the + timing of the last vertical retrace. By looking at the system clock, as + well as the refresh rate of the monitor, this should enable applications + to predict the position of future retraces so as to schedule an optimal + workload. + + This extension incorporates the use of a counter that provides the + necessary synchronization. The graphics Media Stream Counter (or + graphics MSC) is a counter that is unique to the graphics subsystem + and increments for each vertical retrace that occurs. + + By querying the MSC rate for a given surface, the application can + accurately predict the timing for the next vertical retraces and schedule + rendering accordingly. + +Issues + + None. + +IP Status + + No known issues. + +New Procedures and Functions + + Bool eglGetMscRateANGLE(EGLDisplay* dpy, + EGLSurface surface, + int32_t* numerator, + int32_t* denominator) + +New Tokens + + None + +Additions to the EGL 1.3 Specification + + The graphics MSC value is incremented once for each screen refresh. + For a non-interlaced display, this means that the graphics MSC value + is incremented for each frame. For an interlaced display, it means + that it will be incremented for each field. For a multi-monitor + system, the monitor used to determine MSC is the one where the surface + is located. If the surface spans multiple monitors, the monitor used + to determine MSC is the one with the biggest coverage in pixels. + + eglGetMscRateANGLE returns the rate at which the MSC will be incremented + for the display associated with <dpy> and <surface>. The rate is expressed + in Hertz as <numerator> / <denominator>. If the MSC rate in Hertz is an + integer, then <denominator> will be 1 and <numerator> will be + the MSC rate. + +Errors + + The function eglGetMscRateANGLE returns FALSE on failure. + If <dpy> is not a valid EGLDisplay, EGL_BAD_DISPLAY is generated. + If <surface> is not a valid EGLSurface, EGL_BAD_SURFACE is generated. + If there is no current EGLContext, EGL_BAD_CONTEXT is generated. + +New Implementation Dependent State + + None + +Revision History + + Version 1, 2020-03-24 (Jonah Ryan-Davis) + - Initial draft, based on GLX_OML_sync_control revision 6.0. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANGLE/EGL_ANGLE_window_fixed_size.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANGLE/EGL_ANGLE_window_fixed_size.txt new file mode 100644 index 0000000..6e60e86 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ANGLE/EGL_ANGLE_window_fixed_size.txt @@ -0,0 +1,136 @@ +Name + + ANGLE_window_fixed_size + +Name Strings + + EGL_ANGLE_window_fixed_size + +Contributors + + John Bauman + Shannon Woods + +Contacts + + John Bauman, Google Inc. (jbauman 'at' google.com) + +Status + + Complete + +Version + + Version 4, February 24, 2014 + +Number + + EGL Extension #85 + +Dependencies + + This extension is written against the wording of the EGL 1.4 + Specification. + +Overview + + This extension allows creating a window surface with a fixed size that is + specified when it is created. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted by the <attribute> parameter of eglQuerySurface and by the + <attrib_list> parameter of eglCreateWindowSurface: + + EGL_FIXED_SIZE_ANGLE 0x3201 + +Additions to Chapter 3 of the EGL 1.4 Specification: + + Modify the third paragraph of Section 3.5.1 (Creating On-Screen Rendering Surfaces) + + "<attrib_list> specifies a list of attributes for the window. The list has + the same structure as described for eglChooseConfig. Attributes that can + be specified in <attrib_list> include EGL_RENDER_BUFFER, + EGL_VG_COLORSPACE, EGL_VG_ALPHA_FORMAT, EGL_FIXED_SIZE_ANGLE, EGL_WIDTH, + and EGL_HEIGHT." + + Add before the last paragraph of Section 3.5.1 + + "EGL_FIXED_SIZE_ANGLE specifies whether the surface must be resized by the + implementation when the native window is resized. The default value is + EGL_FALSE. Its value can be EGL_TRUE, in which case the size must be + specified when the window is created, or EGL_FALSE, in which case the size + is taken from the native window. Its default value is EGL_FALSE. + + If the value of EGL_FIXED_SIZE_ANGLE is EGL_TRUE, the window surface's + size in pixels is specified by the EGL_WIDTH and EGL_HEIGHT attributes, + and will not change throughout the lifetime of the surface. If its value + is EGL_FALSE, then the values of EGL_WIDTH and EGL_HEIGHT are ignored and + the window surface must be resized by the implementation subsequent to the + native window being resized, and prior to copying its contents to the + native window (e.g. in eglSwapBuffers, as described in section 3.9.1.1). + The default values for EGL_WIDTH and EGL_HEIGHT are zero. If the value + specified for either of EGL_WIDTH or EGL_HEIGHT is less than zero then an + EGL_BAD_PARAMETER error is generated." + + Add the following entry to Table 3.5 + (Queryable surface attributes and types) + + Attribute Type Description + -------------------- ------- --------------------------------------------- + EGL_FIXED_SIZE_ANGLE boolean Surface will not be resized with a native + window + + Replace the last paragraph on page 37 in Section 3.5.6 (Surface Attributes) + + "Querying EGL_WIDTH and EGL_HEIGHT returns respectively the width and + height, in pixels, of the surface. For a pixmap surface or window surface + with EGL_FIXED_SIZE_ANGLE set to EGL_FALSE, these values are initially + equal to the width and height of the native window or pixmap with respect + to which the surface was created. If the native window is resized and the + corresponding window surface is not fixed size, the corresponding window + surface will eventually be resized by the implementation to match (as + discussed in section 3.9.1). If there is a discrepancy because EGL has not + yet resized the window surface, the size returned by eglQuerySurface will + always be that of the EGL surface, not the corresponding native window." + + Add the following paragraph to Section 3.5.6 (Surface Attributes) + + "Querying EGL_FIXED_SIZE_ANGLE returns EGL_FALSE if the surface will be + resized to match a native window, and EGL_TRUE if the surface cannot be + resized." + + Alter the beginning of the first paragraph of Section 3.9.1.1 (Native + Window Resizing) + + "If <surface> does not have EGL_FIXED_SIZE_ANGLE set and the native window + corresponding to <surface> has been resized prior to the swap, <surface> + must be resized to match." + +Issues + + 1. Should there be a way to resize a window surface that had its size + specified initially. + + RESOLVED: No. Surfaces that have their sizes specified initially must have + EGL_FIXED_SIZE_ANGLE set and can never be resized. + +Revision History + + Version 4, 2014/02/24 - formatting changes. + + Version 3, 2014/02/12 - ignore EGL_WIDTH and EGL_HEIGHT if + EGL_FIXED_SIZE_ANGLE is EGL_FALSE + + Version 2, 2014/02/07 - rename to EGL_ANGLE_window_fixed_size, and add an + EGL_FIXED_SIZE_ANGLE token. + + Version 1, 2014/02/05 - first draft. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/ARM/EGL_ARM_image_format.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ARM/EGL_ARM_image_format.txt new file mode 100644 index 0000000..c1a40ec --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ARM/EGL_ARM_image_format.txt @@ -0,0 +1,126 @@ +Name + + ARM_image_format + +Name Strings + + EGL_ARM_image_format + +Contributors + + Jan-Harald Fredriksen + +Contact + + Jan-Harald Fredriksen (jan-harald.fredriksen 'at' arm.com) + +IP Status + + No known IP claims. + +Status + + Complete + +Version + + Version 1 - February 18, 2020 + +Number + + 138 + +Dependencies + + This extension is written against the wording of the EGL 1.4 + specification. + + This extension reuses tokens from EGL_EXT_pixel_format_float. + +Overview + + When an EGLImage is created from an existing image resource the + implementation will deduce the format of the image data from that + resource. In some cases, however, the implementation may not know how to + map the existing image resource to a known format. This extension extends + the list of attributes accepted by eglCreateImageKHR such that applications + can tell the implementation how to interpret the data. + +New Procedures and Functions + + None. + +New Tokens + + Accepted as an attribute name in the <attrib_list> argument of + eglCreateImageKHR: + EGL_COLOR_COMPONENT_TYPE_EXT 0x3339 + + Accepted as attribute values for the EGL_COLOR_COMPONENT_TYPE_EXT attribute + of eglCreateImageKHR: + + EGL_COLOR_COMPONENT_TYPE_FIXED_EXT 0x333A + EGL_COLOR_COMPONENT_TYPE_FLOAT_EXT 0x333B + EGL_COLOR_COMPONENT_TYPE_UNSIGNED_INTEGER_ARM 0x3287 + EGL_COLOR_COMPONENT_TYPE_INTEGER_ARM 0x3288 + EGL_RED_SIZE 0x3024 + EGL_GREEN_SIZE 0x3023 + EGL_BLUE_SIZE 0x3022 + EGL_ALPHA_SIZE 0x3021 + +Modifications to the EGL 1.4 Specification + + Add the following rows to Table 3.xx: Legal attributes for + eglCreateImageKHR <attrib_list> parameter: + + +------------------------------+------------------------------+-----------+---------------+ + | Attribute | Description | Valid | Default Value | + | | | <target>s | | + +------------------------------+------------------------------+-----------+---------------+ + | EGL_COLOR_COMPONENT_TYPE_EXT | Specifies the component | All | NA | + | | type the EGLImage source | | | + | | is interpreted as | | | + | EGL_RED_SIZE | Specifies the red component | All | NA | + | | size the EGLImage source | | | + | | is interpreted as | | | + | EGL_GREEN_SIZE | Specifies the green component| All | NA | + | | size the EGLImage source | | | + | | is interpreted as | | | + | EGL_BLUE_SIZE | Specifies the blue component | All | NA | + | | size the EGLImage source | | | + | | is interpreted as | | | + | EGL_ALPHA_SIZE | Specifies the alpha component| All | NA | + | | size the EGLImage source | | | + | | is interpreted as | | | + +------------------------------+------------------------------+-----------+---------------+ + + If <attrib_list> specifies values for EGL_COLOR_COMPONENT_TYPE_EXT, + EGL_RED_SIZE, EGL_GREEN_SIZE, EGL_BLUE_SIZE, or EGL_ALPHA_SIZE, the + implementation will treat these as hints for how to interpret the contents + of <buffer>. + + EGL_COLOR_COMPONENT_TYPE_EXT indicates the component type of <buffer> and + must be either EGL_COLOR_COMPONENT_TYPE_FIXED_EXT for fixed-point, + EGL_COLOR_COMPONENT_TYPE_FLOAT_EXT for floating-point, + EGL_COLOR_COMPONENT_TYPE_UNSIGNED_INTEGER_ARM for unsigned integer, or + EGL_COLOR_COMPONENT_TYPE_INTEGER_ARM for integer components. + +Add to the list of error conditions for eglCreateImageKHR: + + * If the implementation is unable to interpret the contents <buffer> + according to the component types and sizes in <attrib_list>, then a + EGL_BAD_MATCH error is generated. + +Issues + + 1. Should there be a way to specify the component order? + + Resolved. No, the component order is interpreted to be R, G, B, A, + with R mapping to component 0. If the application needs a different + component order it can use swizzle in the client API side or in the + shader. + +Revision History + + Version 1, 2020/02/18 + - Internal revisions diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/ARM/EGL_ARM_implicit_external_sync.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ARM/EGL_ARM_implicit_external_sync.txt new file mode 100644 index 0000000..bce6a74 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ARM/EGL_ARM_implicit_external_sync.txt @@ -0,0 +1,219 @@ +Name + + ARM_implicit_external_sync + +Name Strings + + EGL_ARM_implicit_external_sync + +Contributors + + David Garbett + Ray Smith + +Contacts + + David Garbett, ARM Ltd. (david 'dot' garbett 'at' arm 'dot' com) + +Status + + Draft + +Version + + Version 1, September 8, 2014 + +Number + + EGL Extension #103 + +Dependencies + + Requires EGL 1.1. + + This extension is written against the wording of the EGL 1.2 Specification. + + EGL_KHR_fence_sync is required. + +Overview + + This extension extends the "fence sync objects" defined in + EGL_KHR_fence_sync. It allows the condition that triggers the associated + fence command in the client API command stream to be explicitly specified on + fence object creation. It introduces a new condition that can be used to + ensure ordering between operations on buffers that may be accessed + externally to the client API, when those operations use an implicit + synchronization mechanism. Such a fence object will be signaled when all + prior commands affecting such buffers are guaranteed to be executed before + such external commands. + + Applications have limited control over when a native buffer is read or + written by the GPU when imported as an EGLImageKHR or via + eglCreatePixmapSurface, which is controlled by the EGL and client API + implementations. While eglWaitClient or a client call such as glFinish + could be called, this forces all rendering to complete, which can result in + CPU/GPU serialization. Note this isn't an issue for window surfaces, where + eglSwapBuffers ensures the rendering occurs in the correct order for the + platform. + + Some platforms have an implicit synchronization mechanism associated with + native resources, such as buffers. This means that accesses to the buffer + have an implicit ordering imposed on them, without involvement from the + application. However, this requires that an application that has imported + an affected buffer into EGL has a mechanism to flush any drawing operations + in flight such that they are waiting on the synchronization mechanism. + Otherwise the application cannot guarantee that subsequent operations (such + as displaying a rendered buffer) will occur after the commands performed by + the client API (such as rendering the buffer). + + The mechanism to wait for the synchronization mechanism should not require + the application to wait for all rendering to complete, so that it can + continue preparing further commands asynchronously to the queued commands. + This extension provides this functionality using the new condition type for + fence sync objects, so the application only waits for the external + synchronization. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted as a value of the EGL_SYNC_CONDITION_KHR attribute passed in the + <attrib_list> list to eglCreateSyncKHR when <type> is EGL_FENCE_SYNC_KHR, + and can populate <*value> when eglGetSyncAttribKHR is called with + <attribute> set to EGL_SYNC_CONDITION_KHR: + + EGL_SYNC_PRIOR_COMMANDS_IMPLICIT_EXTERNAL_ARM 0x328A + +Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors) + + Add the following after the fifth paragraph of Section 3.8.1 (Sync Objects), + added by KHR_fence_sync: + + "Typically client APIs are considered to execute commands in a linear queue, + where a prior command is executed and completes before a later command is + started. By default fence sync objects adhere to this model - a fence is + signaled once prior commands have completed. However on some platforms a + command in a client API may transition through multiple states before it + completes, which may impact other components of the system. Therefore the + condition that all prior commands must meet before the fence is triggered is + configurable." + + Replace the sixth paragraph of Section 3.8.1 (Sync Objects), added by + KHR_fence_sync: + + "If, <type> is EGL_SYNC_FENCE_KHR, a fence sync object is created. In this + case <attrib_list> can be NULL or empty, or can specify the + EGL_SYNC_CONDITION_KHR attribute. Attributes of the fence sync object have + the following default values:" + + Replace the eighth paragraph of Section 3.8.1 (Sync Objects), added by + KHR_fence_sync: + + "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 + condition is specified by the EGL_SYNC_CONDITION_KHR attribute passed to + eglCreateSyncKHR. + + If the condition is specified as EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR, the + fence sync object 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. + + If the condition is specified as + EGL_SYNC_PRIOR_COMMANDS_IMPLICIT_EXTERNAL_ARM, the fence sync object is + satisfied by the completion of the fence command corresponding to the sync + object, and the <submission> of all preceding commands in the associated + client API context's command stream. <Submission> defines the point in time + when a command has been queued on any implicit synchronization mechanisms + present on the platform which apply to any of the resources used by the + command. This enforces an ordering, as defined by the synchronization + mechanism, between the command and any other operations that also respect + the synchronization mechanism(s)." + + Replace the second entry in the list of eglCreateSyncKHR errors in Section + 3.8.1 (Sync Objects), added by KHR_fence_sync: + + " * If <type> is EGL_SYNC_FENCE_KHR and <attrib_list> contains an attribute + other than EGL_SYNC_CONDITION_KHR, EGL_NO_SYNC_KHR is returned and an + EGL_BAD_ATTRIBUTE error is generated. + * If <type> is EGL_SYNC_FENCE_KHR and the value specified for + EGL_SYNC_CONDITION_KHR is not EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR or + EGL_SYNC_PRIOR_COMMANDS_SUBMITTED_ARM, EGL_NO_SYNC_KHR is returned and + an EGL_BAD_ATTRIBUTE error is generated." + +Issues + + 1. Could glFlush guarantee commands are submitted, making this extension + unnecessary? + + RESOLVED: The Open GL ES 3.1 specification defines glFlush() as causing "all + previously issued GL commands to complete in finite time". There is no + requirement for the execution of commands to reach any specific point before + it returns - a valid implementation of glFlush() could spawn a new thread + that sleeps for a minute before submitting the pending commands. While an + implementation could decide to ensure all commands are submitted within + glFlush(), it could not be assumed to be the case across all + implementations. + + In addition, there may be scenarios when submitting commands within + glFlush() is harmful. Waiting for command submission may have a performance + impact on some implementations that perform processing of commands + asynchronously. In addition such a change may restrict what is possible in + the future. For example if user events were introduced into OpenGL ES they + have the potential of introducing deadlocks if submission in glFlush() is + guaranteed. + + 2. Should a new entry point be defined that flushes commands synchronously, + instead of the new fence type as defined by this extension? + + RESOLVED: While a synchronous "flush and submit" entrypoint would meet the + requirements for this extension, there may be a small benefit in enabling + the application to continue processing between flushing and waiting for + submission. In addition, the semantics of the existing EGL_KHR_fence_sync + extension closely match what is required for this extension, so defining + the new functionality in terms of fences may enable simpler implementations. + + 3. Should OpenGL ES 3 glFenceSync be extended in preference to + eglCreateSyncKHR? + + RESOLVED: Some platforms are yet to move to a OpenGL ES 3 implementation, or + may be unwilling to expose OpenGL ES 3 entrypoints to applications. As + EGL_KHR_fence_sync is older than OpenGL ES 3, and is comparatively a small + change, it has a better chance of adoption in a platform. + + In addition this extension is based on the idea that there are + platform-specific ways to interact with the client API command stream. As + this is platform-specific, and does not fit with the existing model + typically used by client APIs (such as Open GL ES) it is better placed in + EGL. + + Finally extending EGL has the advantage that the extension applies to all + client APIs. + + 4. Should a new <type> parameter be defined, instead of extending the + EGL_FENCE_SYNC_KHR fence sync objects defined by EGL_KHR_fence_sync? + + RESOLVED: Whether the new functionality is defined as an extension to the + existing fence sync objects, or whether they are defined as a new type of + sync object, we must acknowledge that the model of a client API processing + commands serially (with prior commands completing before later commands are + executed) is too simplistic for some platforms. + + Extending the existing fence sync objects allows us to use the existing + concept of conditions that trigger the fences. It also allows the maximum + amount of reuse of existing functionality, potentially simplifying the + implementation and the use of the extension by applications. + +Revision History +#1 (David Garbett, September 8, 2014) + - Initial draft. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/ARM/EGL_ARM_pixmap_multisample_discard.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ARM/EGL_ARM_pixmap_multisample_discard.txt new file mode 100644 index 0000000..847a749 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/ARM/EGL_ARM_pixmap_multisample_discard.txt @@ -0,0 +1,185 @@ +Name + + ARM_pixmap_multisample_discard + +Name Strings + + EGL_ARM_pixmap_multisample_discard + +Contributors + + Arne Bergene Fossaa + Tom Cooksey + Endre Sund + David Garbett + +Contacts + + Tom Cooksey (tom 'dot' cooksey 'at' arm 'dot' com) + +Status + + Complete. + +Version + + Version 1, March 5, 2013 + +Number + + EGL Extension #54 + +Dependencies + + EGL 1.0 is required. + + This extension is written against the wording of the EGL 1.4 Specification. + +Overview + + ARM_pixmap_multisample_discard adds an attribute to eglCreatePixmapSurface + that allows the client API implementation to resolve a multisampled pixmap + surface, therefore allowing the multisample buffer to be discarded. + + Some GPU architectures - such as tile-based renderers - are capable of + performing multisampled rendering by storing multisample data in internal + high-speed memory and downsampling the data when writing out to external + memory after rendering has finished. Since per-sample data is never written + out to external memory, this approach saves bandwidth and storage space. In + this case multisample data gets discarded, however this is acceptable in + most cases. + + The extension provides the EGL_DISCARD_SAMPLES_ARM attribute that allows + for implicit resolution when rendering to a pixmap surface. This complements + the OpenGL ES EXT_multisampled_render_to_texture extension which provides + similar functionality for rendering to an OpenGL ES texture. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted as an attribute name in the <attrib_list> argument of + eglCreatePixmapSurface and by the <attribute> parameter of eglQuerySurface: + + EGL_DISCARD_SAMPLES_ARM 0x3286 + +Changes to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors) + + Modify the second paragraph under "The Multisample Buffer" of Section 3.4, + page 18 (Configuration Management) + + "Operations such as posting a surface with eglSwapBuffers (see section + 3.9.1, copying a surface with eglCopyBuffers (see section 3.9.2), reading + from the color buffer using client API commands, binding a client API + context to a surface (see section 3.7.3), and flushing to a pixmap surface + created with the EGL_DISCARD_SAMPLES_ARM attribute enabled (see + section 3.5.4) may cause resolution of the multisample buffer to the color + buffer." + + Modify the fifth paragraph under "The Multisample Buffer" of Section 3.4, + page 18 (Configuration Management) + + "There are no single-sample depth or stencil buffers for a multisample + EGLConfig, or with a pixmap surface created with the + EGL_DISCARD_SAMPLES_ARM attribute (see section 3.5.4). The only depth and + stencil buffers are those in the multisample buffer. If the color samples + in the multisample buffer store fewer bits than are stored in the color + buffers, this fact will not be reported accurately. Presumably a + compression scheme is being employed, and is expected to maintain an + aggregate resolution equal to that of the color buffers." + + Modify the fifth paragraph of Section 3.5.4, page 34 (Creating Native + Pixmap Rendering Surfaces) + + "attrib list specifies a list of attributes for the pixmap. The list has the + same structure as described for eglChooseConfig. Attributes that can be + specified in attrib list include EGL_VG_COLORSPACE, EGL_VG_ALPHA_FORMAT and + EGL_DISCARD_SAMPLES_ARM." + + Add the following between paragraphs eight and nine of Section 3.5.4, + page 34 (Creating Native Pixmap Rendering Surfaces) + + "EGL_DISCARD_SAMPLES_ARM specifies whether the client API implementation is + allowed to implicitly resolve the multisample buffer. On some GPU + architectures - such as tile-based renderers - an implicit resolve can avoid + writing the multisample buffer back to external memory as the multisample + data is stored in internal high-speed memory. + + The implicit resolve can occur when the client API uses the pixmap as the + source or destination of any operation, when flushing to the pixmap or when + the client API unbinds (or breaks) the pixmap. When these operations occur + is dependent on the client API implementation. They can occur as an explicit + part of client API functions (such as glFinish, glReadPixels and + glCopyTexImage) or they can occur implicitly. + + Further rendering causes the implementation to read the surface buffer and + any ancillary buffers back in as single-sampled data. + Therefore use of this attribute may result in lower quality images. + + Valid values are EGL_TRUE, in which case the multisample buffer can be + discarded, or EGL_FALSE, in which case the multisample buffer is preserved. + The default value is EGL_FALSE. + + Note that the multisample buffer may be discarded during eglMakeCurrent + regardless of the value of the EGL_DISCARD_SAMPLES_ARM attribute (see + section 3.7.3)." + + Modify the ninth paragraph of Section 3.5.4, page 34 (Creating Native + Pixmap Rendering Surfaces) + + "On failure eglCreatePixmapSurface returns EGL_NO_SURFACE. If the attributes + of pixmap do not correspond to config, then an EGL_BAD_MATCH error is + generated. If config does not support rendering to pixmaps (the + EGL_SURFACE_TYPE attribute does not contain EGL_PIXMAP_BIT), an + EGL_BAD_MATCH error is generated. If config does not support the colorspace + or alpha format attributes specified in attriblist (as defined for + eglCreateWindowSurface), an EGL_BAD_MATCH error is generated. If config does + not specify non-zero EGL_SAMPLES and EGL_SAMPLE_BUFFERS and the + EGL_DISCARD_SAMPLES_ARM attribute is set to EGL_TRUE, then an EGL_BAD_MATCH + error is generated. If config is not a valid EGLConfig, an EGL_BAD_CONFIG + error is generated. If pixmap is not a valid native pixmap handle, then an + EGL_BAD_NATIVE_PIXMAP error should be generated. If there is already an + EGLSurface associated with pixmap (as a result of a previous + eglCreatePixmapSurface call), then a EGL_BAD_ALLOC error is generated. + Finally, if the implementation cannot allocate resources for the new EGL + pixmap, an EGL_BAD_ALLOC error is generated." + + + Add the following entry to Table 3.5, page 36 + (Queryable surface attributes and types) + + Attribute Type Description + ------------------------- ------- --------------------------------------- + EGL_DISCARD_SAMPLES_ARM boolean Multisample resolve when flushing to + surface + + Add the following paragraph before the last paragraph of Section 3.5.7, + page 38 (Surface Attributes) + + "Querying EGL_DISCARD_SAMPLES_ARM returns whether a multisample resolve + is forced on every flush to the surface (see section 3.5.4). This will only + return EGL_TRUE for pixmap surfaces created with the EGL_DISCARD_SAMPLES_ARM + attribute set to EGL_TRUE. EGL_FALSE will be returned for window and + pbuffer surfaces." + +Issues + + 1. Should eglSurfaceAttrib accept EGL_DISCARD_SAMPLES_ARM? + RESOLVED: No. The attribute should be decided at surface creation time. + + 2. Should eglCreateWindowSurface or eglCreatePbufferSurface accept + EGL_DISCARD_SAMPLES_ARM? + RESOLVED: No. While the attribute could equally apply to window and + pbuffer surfaces, no use case has been identified to justify the + additional maintenance this would require. + +Revision History + + Version 1, 2013/03/05 - Original release. + diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_bind_to_front.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_bind_to_front.txt new file mode 100644 index 0000000..e83f9c9 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_bind_to_front.txt @@ -0,0 +1,108 @@ +Name + + EXT_bind_to_front + +Name Strings + + EGL_EXT_bind_to_front + + +Contributors + + Daniel Herring + +Contacts + + Daniel Herring, Core Avionics & Industrial Inc., daniel dot herring at ch1group dot com + +Status + + Complete + +Version + + Version 1.0, February 21, 2017 + +Number + + EGL Extension #121 + +Dependencies + + Requires EGL 1.2. + +Overview + + This extension allows for using double buffered Pbuffers for rendering to textures, by + allowing a new enumeration to be used in eglBindTexImage. EGL_FRONT_BUFFER_EXT is used + to denote reading the textures data from the front buffer of a double buffered Pbuffer. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + EGL_FRONT_BUFFER_EXT 0x3464 + +Modify Section 3.6.1 of the EGL 1.2 Specification, paragraph 1 + Add EGL_FRONT_BUFFER_EXT to list of acceptable values for buffer attribute. + +Modify Section 3.6.2 of the EGL 1.2 Specification, paragraph 5 + Add EGL_FRONT_BUFFER_EXT to list of acceptable values for buffer attribute. + +Modify Section 3.5.2 of the EGL 1.2 Specification, paragraph 4 + Add EGL_RENDER_BUFFER to list of attributes which can be accepted in attrib_list. + +Add to Section 3.5.2 of the EGL 1.2 Specification + EGL_RENDER_BUFFER specifies the number of color buffers which should be useable by the + client API rendering to the Pbuffer. If its value is EGL_SINGLE_BUFFER, then there is + one color buffer the client APIs will render to directly. If its value is EGL_BACK_BUFFER, + then there are at least two color buffers the client API can render to. eglSwapBuffers + is used to switch which color buffer is currently being rendered to. By default, all + client APIs should render into the back buffer. The default value of EGL_RENDER_BUFFER + is EGL_SINGLE_BUFFER. + +Modify Section 2.2.2 of the EGL 1.2 Specification, paragraph 2 + Pbuffer surfaces have a back buffer but no associated window, so the back buffer + need not be copied. + Change to: + Pbuffer surfaces have no associated window, and include a back buffer, used by + default, for rendering to by the client API. Pbuffers may have a front buffer + used during render to texture operations to provide a read only texture which may + be used while the back buffer is being rendered to. + +Modify Section 3.5.6 + Querying EGL RENDER BUFFER returns the buffer which client API rendering + is requested to use. For a window surface, this is the same attribute value + specified when the surface was created. For a Pbuffer surface, it is always + EGL BACK BUFFER. For a pixmap surface, it is always EGL SINGLE BUFFER. To + determine the actual buffer being rendered to by a context, call eglQueryContext + (see section 3.7.4). + + Change to: + Querying EGL RENDER BUFFER returns the buffer which client API rendering + is requested to use. For a window surface or Pbuffer surface, this is the + same attribute value specified when the surface was created. For a pixmap + surface, it is always EGL SINGLE BUFFER. To determine the actual buffer being + rendered to by a context, call eglQueryContext (see section 3.7.4). + +Revision History + Version 1.0, 21/02/2017 - Initial Version + +Question: + What if the implementation already uses double buffering for single buffered PBuffers? + Such as when an implementation must insert a resolve to a texture instead of being + able to use the same memory. +Answer: + EGL_BACK_BUFFER would still refer to the resolved buffer. But in the case of the a + double buffer EGL_FRONT_BUFFER should be used to reference the resolved buffer instead + of EGL_BACK_BUFFER as in this case the user has specified 2 buffers and knows they want + the resolved buffer. + In the double buffer case where only a back draw and a front resolved buffer is used + the implementation may not support EGL_BACK_BUFFER and should generate an EGL_BAD_ + PARAMETER error when not supporting EGL_BACK_BUFFER texture binding. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_buffer_age.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_buffer_age.txt new file mode 100644 index 0000000..5e46fa9 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_buffer_age.txt @@ -0,0 +1,329 @@ +Name + + EXT_buffer_age + +Name Strings + + EGL_EXT_buffer_age + +Notice + + Copyright 2011,2012 Intel Cooperation + +IP Status + + No known IP claims. + +Contributors + + Robert Bragg + Neil Roberts + Tapani Pälli + Kristian Høgsberg + Acorn Pooley + James Jones + +Contacts + + Robert Bragg, Intel (robert.bragg 'at' intel.com) + +Status + + Complete. + +Version + + 12 - June 13, 2013 + +Number + + EGL Extension #52 + +Dependencies + + Requires EGL 1.4 + + This extension is written against the wording of the EGL 1.4 + Specification. + +Overview + + The aim of this extension is to expose enough information to + applications about how the driver manages the set of front and + back buffers associated with a given surface to allow applications + to re-use the contents of old frames and minimize how much must be + redrawn for the next frame. + + There are lots of different ways for a driver to manage these + buffers, from double buffering, different styles of triple + buffering and even n-buffering or simply single buffer rendering. + We also need to consider that power management events or memory + pressure events might also result in some of the buffers not + currently in-use being freed. + + This extension lets applications query the age of the back buffer + contents for an EGL surface as the number of frames elapsed since + the contents were most recently defined. The back buffer can + either be reported as invalid (has an age of 0) or it may be + reported to contain the contents from n frames prior to the + current frame. + + Once the application has queried the buffer age, the age of + contents remains valid until the end of the frame for all pixels + that continue to pass the pixel ownership test. + + For many use-cases this extension can provide an efficient + alternative to using the EGL_BUFFER_PRESERVED swap behaviour. The + EGL_BUFFER_PRESERVED swap behaviour adds a direct dependency for + any frame n on frame n - 1 which can affect the pipelining of + multiple frames but also implies a costly copy-back of data to + initialize the back-buffer at the start of each frame. + + For example if you consider a double buffered application drawing + a small spinning icon, but everything else in the scene is static. + If we know that 2 buffers are continuously being recycled each + time eglSwapBuffers is called then even though 100s of frames may + need to be drawn to animate the icon it can be seen that the two + buffers are remaining unchanged except within the bounds of the + icon. In this scenario ideally the application would simply + perform an incremental update of the old buffer instead of + redundantly redrawing all the static parts of the scene. The + problem up until now though has been that EGL doesn't report how + buffers may be recycled so it wasn't safe for applications to try + and reuse their contents. Now applications can keep track of all + the regions that have changed over the last n frames and by + knowing the age of the buffer they know how to efficiently repair + buffers that are re-cycled instead of redrawing the entire scene. + +New Procedures and Functions + + None + +New Tokens + + EGL_BUFFER_AGE_EXT 0x313D + +Additions to Section 2.2 of the EGL 1.4 Specification (Rendering +Contexts and drawing surfaces) + + Add the following text to a new subsection titled "Pixel + Ownership Test" after the subsection titled "Interaction With + Native Rendering": + + A fragment produced by a client api through rasterization + with windows coordinates (x, y) only modifies the pixel in the + rendering surface at that location if it passes the pixel + ownership test defined by the native window system. + + The pixel ownership test determines if the pixel at location + (x, y) in a rendering surface is currently owned by the client + api (more precisely, by this its context). If it is not, the + native window system decides the fate of the incoming + fragment. Possible results are that the fragment is discarded + or that some subset of the subsequent per-fragment operations + are applied to the fragment. This test allows the window + system to control the client api behavior, for instance, when + a window surface is obscured. + + The pixel ownership test can only fail for window surfaces, + not for pixmap surfaces or pbuffer surfaces. + + Most native window systems will be able to guarantee that no + fragment will ever fail the pixel ownership test, but a + notable exception to this is the X11 window system where, + depending on the driver, the pixel ownership test may fail + when portions of a window are obscured. + +Additions to Section 3.5 of the EGL 1.4 Specification (Rendering Surfaces) + + Add the following to the table of "Queryable surface attributes + and types": + + +----------------------+---------+-----------------------------+ + | Attribute | Type | Description | + +----------------------+---------+-----------------------------+ + | EGL_BUFFER_AGE_EXT | Integer | Age of back-buffer contents | + +----------------------+---------+-----------------------------+ + Table aaa: Queryable surface attributes and types. + + + Add the following text to the subsection titled "Surface + Attributes" in the description for eglQuerySurface + + Querying EGL_BUFFER_AGE_EXT returns the age of the color + contents of the current back-buffer as the number of frames + elapsed since it was most recently defined. Applications can, + under certain conditions described below, use this age to + safely rely on the contents of old back- buffers to + potentially reduce the amount of redrawing they do each frame. + A frame is the period between calls to any of the functions in + table 3.X, hereafter referred to as "frame boundaries." + + Function name + -------------------- + eglSwapBuffers + + Table 3.X, Frame Boundary Functions + + Buffers' ages are initialized to 0 at buffer creation time. + When a frame boundary is reached, the following occurs before + any exchanging or copying of color buffers: + + * The current back buffer's age is set to 1. + * Any other color buffers' ages are incremented by 1 if + their age was previously greater than 0. + + For the purposes of buffer age tracking, a buffer's content + is considered defined when its age is a value greater than 0. + + For example, with a double buffered surface and an + implementation that swaps via buffer exchanges, the age would + usually be 2. With a triple buffered surface the age would + usually be 3. An age of 1 means the previous swap was + implemented as a copy. An age of 0 means the buffer has only + just been initialized and the contents are undefined. Single + buffered surfaces have no frame boundaries and therefore + always have an age of 0. + + Frame boundaries are the only events that can set a buffer's + age to a positive value. Once EGL_BUFFER_AGE_EXT has been + queried then it can be assumed that the age will remain valid + until the next frame boundary. EGL implementations are + permitted, but not required, to reset the buffer age in + response to pixel ownership test changes for any pixels within + the drawable, or if new pixels are added to or removed from + the drawable, i.e., the drawable is resized. A reset of this + nature does not affect the age of content for pixels that pass + the pixel ownership test before and after the event that + caused the reset. In other words, applications can assume + that no event will invalidate the content of pixels that + continuously pass the pixel ownership test between when the + buffer age was queried and the following frame boundary. + + It is up to applications to track pixel ownership using data + collected from relevant window system events, such as + configuration and expose events on X11. + + If the EGL implementation decides to free un-used back-buffers + when the system is under memory pressure or in response to + power-management events then EGL will return an age of 0 when + it allocates a new buffer at the start of a new frame. + + If the EGL_BUFFER_PRESERVED swap behaviour is in use then + it can be assumed that the age will always be 1. It is + recommended where possible though that the + EGL_BUFFER_PRESERVED swap behaviour not be used since it can + have severe performance consequences. Keeping track of the + buffer age and the regions that have changed over the last 2 + or 3 frames instead can often replace the need for using + EGL_BUFFER_PRESERVED. + + EGL_BUFFER_AGE_EXT state is a property of the EGL surface that + owns the buffers and lives in the address space of the + application. That is, if an EGL surface has been created from + a native window or pixmap that may be shared between + processes, the buffer age is not guaranteed to be synchronized + across the processes. Binding and unbinding a surface to and + from one or more contexts in the same address space will not + affect the ages of any buffers in that surface. + + Add the following text to last paragraph of the subsection titled + "Surface Attributes" in the description for eglQuerySurface + errors. + + If querying EGL_BUFFER_AGE_EXT and <surface> is not bound as + the draw surface to the calling threads current context + an EGL_BAD_SURFACE error is generated. + +Dependencies on OpenGL ES + + None + +Dependencies on OpenVG + + None + +Issues + + 1) What are the semantics if EGL_BUFFER_PRESERVED is in use + + RESOLVED: The age will always be 1 in this case. More + clarification about this was added along with the + recommendation to use the buffer age to reuse buffers instead + of EGL_BUFFER_PRESERVED when possible to avoid the + in-efficiencies of introducing a dependency for each frame on + the previous frame. + + 2) How can an application know that all pixels of a re-usable + buffer were originally owned by the current context? + + RESOLVED: It is up to the application to track pixel ownership + using existing window system specific events, such as X11 + expose or configure notify events. + + 3) What are the semantics if the buffer age attribute is queried for + a surface that isn't bound to the calling thread's context as the + draw surface? + + RESOLVED: we report an EGL_BAD_SURFACE error as is similarly + done when calling eglSwapBuffers for such a surface. + + 4) What is the buffer age of a single buffered surface? + + RESOLVED: 0. This falls out implicitly from the buffer age + calculations, which dictate that a buffer's age starts at 0, + and is only incremented by frame boundaries. Since frame + boundary functions do not affect single buffered surfaces, + their age will always be 0. + + 5) What guarantees are provided after querying the buffer age? + + RESOLVED: The buffer age of pixels which continue to pass the + pixel ownership test must remain valid until the next frame + boundary otherwise applications can't be absolutely sure of + the consistency of their rendered content. Implementations + may reset the queryable age of the buffer when pixel ownership + changes occur. This is further clarified in section 3.5 + +Revision History + + Version 1, 25/07/2011 + - First draft + Version 2, 03/08/2011 + - Clarified semantics for using EGL_BUFFER_PRESERVED + Version 3, 01/09/2011 + - Fixed a prototype inconsistency + Version 4, 03/11/2011 + - Split out the buffer age parts from EGL_INTEL_start_frame + Version 5, 20/03/2012 + - Document that once the age is queried it remains valid until + the end of the frame so we can remove the need for a separate + EGL_EXT_start_frame extension. + Version 6, 20/03/2012 + - Clarify that only buffers who's contents were fully owned by + the context are tracked. + Version 7, 20/03/2012 + - Document that an error will be generated if querying the age + for a surface not bound to the current context. + Version 8, 25/08/2012 + - Update in line with changes made to the GLX_EXT_buffer_age draft spec + including more relaxed pixel ownership requirements and explicit + clarification of the buffer age calculation. + Version 9 20/09/2012 + - Update in line with changes made to the EGL_EXT_buffer age + draft space + Version 10 29/11/2012 + - Add pixel ownership test section and other minor + clarifications + Version 11 13/12/2012 + - Allocated enumerant and marked complete. + Version 12, 13/06/2013, Chad Versace <chad.versace@intel.com> + - Remove the "all rights reserved" clause from the copyright notice. The + removal does not change the copyright notice's semantics, since the + clause is already implied by any unadorned copyright notice. But, the + removal does diminish the likelihood of unwarranted caution in readers + of the spec. + - Add "IP Status" section to explicitly state that this extension has no + knonw IP claims. + Version 13, 14/10/2021, Guanzhong Chen + - Fix an incorrect token name diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_client_extensions.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_client_extensions.txt new file mode 100644 index 0000000..8e24447 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_client_extensions.txt @@ -0,0 +1,408 @@ +Name + + EXT_client_extensions + +Name Strings + + EGL_EXT_client_extensions + +Contributors + + Chad Versace <chad.versace@intel.com> + Ian Romanick <ian.d.romanick@intel.com> + Jakob Bornecrantz <jakob@vmware.com> + James Jones <jajones@nvidia.com> + +Contacts + + Chad Versace <chad.versace@intel.com> + +Status + + Complete + +Version + + Version 11, 2013.10.10 + +Number + + EGL Extension #58 + +Extension Type + + EGL client extension + +Dependencies + + Requires EGL 1.4. + + This extension is written against the wording of the EGL 1.4 + Specification. + +Overview + + This extension introduces the concept of *extension type*, requires that + each EGL extension belong to exactly one type, and defines two types: + display and client. It also provides a method to query, without + initializing a display, the set of supported client extensions. + + A display extension adds functionality to an individual EGLDisplay. This + type of extension has always existed but, until EGL_EXT_client_extensions, + lacked an identifying name. + + A client extension adds functionality that is independent of any display. + In other words, it adds functionality to the EGL client library itself. This + is a new type of extension defined by EGL_EXT_client_extensions. + EGL_EXT_client_extensions is itself a client extension. + + We suggest that each future extension clearly state its type by including + the following toplevel section in its extension specification, preceding the + Dependencies section. For client extensions, this suggestion is + a requirement. + + Extension Type + + <Either "EGL display extension" or "EGL client extension" or + a future extension type.> + + By cleanly separating display extensions from client extensions, + EGL_EXT_client_extensions solves a bootstrap problem for future EGL + extensions that will modify display initialization. To query for such + extensions without EGL_EXT_client_extensions, an EGL client would need to + initialize a throw-away EGLDisplay solely to query its extension string. + Initialization of the throw-away display may have undesired side-effects + (discussed in the issues section below) for EGL clients that wish to use the + new methods of display initialization. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + None + +Additions to the EGL 1.4 Specification: + + + Add the following section to Chapter 2 "EGL Operation": + + "2.n Extensions + + EGL implementations may expose additional functionality beyond that + described by this specification. Additional functionality may include new + functions, new enumerant values, and extended behavior for existing + functions. Implementations advertise such extensions to EGL by exposing + *extension strings*, which are queryable with eglQueryString. + + Each EGL extension belongs to exactly one of the following types: + + Display Extensions + A *display extension* adds functionality to an individual + EGLDisplay. Different instances of EGLDisplay may support different + sets of display extensions. + + Client Extensions + A *client extension* adds functionality that is independent of any + display. In other words, it adds functionality to the EGL client + library itself. In a given process, there exists exactly one set, + possibly empty, of supported client extensions. When the client + extension string is first queried, that set becomes immutable." + + Replace the paragraph in section 3.3 "EGL Versioning" that begins "The + EGL_EXTENSIONS string" with the following text: + + "The EGL_EXTENSIONS string describes which set of EGL extensions are + supported. The string is zero-terminated and contains a space-separated + list of extension names; extension names themselves do not contain spaces. + If there are no extensions to EGL, then the empty string is returned. + + If <dpy> is EGL_NO_DISPLAY, then the EGL_EXTENSIONS string describes the set + of supported client extensions. If <dpy> is a valid, initialized display, + then the EGL_EXTENSIONS string describes the set of display extensions + supported by the given display. The set of supported client extensions is + disjoint from the set of extensions supported by any given display [fn]. + + [fn] This is a consequence of the requirement in Section 2.n Extensions that + each extension belong to exactly one extension type." + + Replace the last paragraph of section 3.3 "EGL Versioning" with: + + "On failure, NULL is returned. An EGL_BAD_DISPLAY error is generated if + <dpy> is not a valid display, unless <dpy> is EGL_NO_DISPLAY and <name> is + EGL_EXTENSIONS. An EGL_NOT_INITIALIZED error is generated if <dpy> is + a valid but uninitialized display. An EGL_BAD_PARAMETER error is generated + if <name> is not one of the values described above." + +Conformance Tests + + 1. Before any call to eglGetDisplay, call `eglQueryString(EGL_NO_DISPLAY, + EGL_EXTENSIONS)`. Verify that either + + a. The call returns NULL and generates EGL_BAD_DISPLAY. + b. The call returns an extension string that contains, at a minimum, + this extension and generates no error. + + 2. Obtain a display with eglGetDisplay but do not initialize it. Verity + that passing the uninitialized display to `eglQueryString(dpy, + EGL_EXTENSIONS)` returns NULL and generates EGL_NOT_INITIALIZED. + + 3. Obtain a list of display extensions by calling `eglQueryString(dpy, + EGL_EXTENSIONS)` on an initialized display. Obtain the list of client + extensions by calling `eglQueryString(EGL_NO_DISPLAY, EGL_EXTENSIONS)`. + If both calls succeed, verify the two lists are disjoint. + +Issues + + 1. How should clients detect if this extension is supported? + + RESOLVED: If an EGL implementation supports this extension, then + `eglQueryString(EGL_NO_DISPLAY, EGL_EXTENSIONS)` returns + a well-formed extension string and generates no error. Otherwise, it + returns NULL and generates EGL_BAD_DISPLAY. + + 2. On EGL platforms that define EGL_NO_DISPLAY as NULL, does not calling + `eglQueryString(EGL_NO_DISPLAY, EGL_EXTENSIONS)` risk a null pointer + dereference? Therefore, how is it possible on such platforms for + a client to safely detect if this extension is supported? + + RESOLVED: According to the EGL 1.4 specification, calling + `eglQueryString(EGL_NO_DISPLAY, name)` returns NULL and generates + EGL_BAD_DISPLAY. No null pointer dereference occurs even if the + platform defines EGL_NO_DISPLAY as NULL. + + 3. What existing extensions should returned by + `eglQueryString(EGL_NO_DISPLAY, EGL_EXTENSIONS)`? + + RESOLVED: Possibly EGL_NV_system_time. + + 4. What should be the relationship between the extension string of + EGL_NO_DISPLAY and the extension string of a valid display? That is, + should the former be a subset of the latter? Should the two be + disjoint? Should the relationship remain undefined? + + Another phrasing of this issue is: When, if ever, should client + extensions appear in a display's extension string? + + RESOLVED: The extension string of EGL_NO_DISPLAY must be disjoint + from the extension string of any valid display. That is, EGL_NO_DISPLAY + must advertise only client extensions, and valid displays must not + advertise client extensions. By defining a clear relationship between + the two types of extension strings, we enforce consistent behavior among + implementations, thus preventing possible confusion from application + developers. + + DISCUSSION: This resolution has special implications for systems where + libEGL is a vendor-independent library that loads and then dispatches + to the appropriate vendor-provided EGL library. The resolution requires + that client extensions, as well the construction of extension strings, + be at least partially implemented in the vendor-independent library. + + The alternative resolution of mandating the 'superset' relation (that + is, that the extension string of a valid display must be a superset of + that of EGL_NO_DISPLAY) was rejected due to potential confusion on + behalf of the application developer as well as the driver implementer. + What follows is an example of each. + + a) Suppose an EGL implementation supported creation of + a software-renderer EGLDisplay through a client extension named + EGL_XYZ_platform_software_renderer. If the 'superset' relation were + mandated, then each display, whether it were hardware-accelerated or + software-only, would advertise the EGL_XYZ_platform_software_renderer + extension string. This would likely confuse application developers. + + b) If the 'superset' relation were mandated, then the possibility + exists that a vendor would ship a hybrid extension that is both + a client extension and a display extension. Such a hybrid extension + poses subtle difficulties for systems where libEGL is + a vendor-independent library that dispatches to the appropriate + vendor-provided EGL driver. On such a system, the extension's hybrid + nature may require that each vendor-provided EGL driver support the + extension before the vendor-independent EGL library could safely + expose the extension. By choosing the 'disjoint' relation rather + than 'superset', we prevent this problematic situation from + occuring. + + 5. Should client extension specifications explicitly state they are + returned in the extension string of EGL_NO_DISPLAY? + + RESOLVED: Yes. Enforce this by requiring that client extension + specifications contain the toplevel section "Extension Type". + + 6. As explained in the overview section, this "extension solves + a bootstrap problem for future EGL extensions that modify display + initialization". What solutions to the bootstrap problem were + considered? Why was EGL_EXT_client_extensions chosen as the best + solution? + + DISCUSSION: First let's discuss the exact nature of the bootstrap + problem and of the future EGL extensions that modify display + initialization. + + Mesa's EGL implementation supports multiple native platforms (such as + Wayland, GBM, and X11) at runtime, and we expect that more + implementations will do so in the future. The EGL API is deficient for + such implementations because it does not yet provide a way for clients + to query the set of supported native platforms. Also, EGL provides no + way for clients to specify to which platform the native display belongs + during display initialization. (That is, eglGetDisplay has a native + display parameter, but no parameter specifying the native platform). + + Future EGL extensions, currently under progress, will solve these + deficiencies in the EGL API by (1) adding a variant of eglGetDisplay + that allows specification of the platform to which the native display + belongs and (2) by advertising the set of native platforms supported by + the implementation. + + However, there exists a bootstrap problem here. To query if a given + native platform is supported, the EGL client must initialize an + EGLDisplay to query its extension string. But, not yet knowing which + native platforms the EGL implementation supports, the client cannot + safely pass any native display to eglGetDisplay, and therefore cannot + obtain an extension string. + + The following solutions to this bootstrap problem have been considered. + For conciseness, let's refer to the future EGL extensions that modify + display initialization as "client extensions". + + 1. PROPOSED SOLUTION: To determine if an EGL implementation supports + a given client extension, require that the EGL client call + eglGetProcAddress on some function defined by the extension. If + eglGetProcAddress returns non-null, then the implementation + supports the extension. + + ANALYSIS: The EGL 1.4 spec permits eglGetProcAddress to return + non-null for unrecognized function names. Therefore, this + solution's method may produce false positives on some + implementations. + + Also, this solution does not permit detection of client extensions + that add no new functions. + + 2. PROPOSED SOLUTION: To determine if an EGL implementation supports + a given client extension, the EGL client should examine the + extension string of EGL_DEFAULT_DISPLAY. Querying + EGL_DEFAULT_DISPLAY is a failsafe mechanism by which the EGL + client can obtain an extension string, because EGL_DEFAULT_DISPLAY + is a valid input to eglGetDisplay regardless of which platforms + the EGL implementation supports. + + ANALYSIS: This solution is awkward. It requires that the client + initialize a throw-away EGLDisplay solely to query its extension + string, even though the desired extension is not a property of any + display but of the EGL library itself. + + This solution also has a subtle fatal problem. It is not backwards + compatible with Mesa. As of 2013-06-07, Mesa's EGL implementation + stores at runtime a user-chosen native platform in global + write-once state. Calling eglGetDisplay is one action that + results in writing to that state. Therefore, if a client process + running on such a problematic version of Mesa initialized + EGL_DEFAULT_DISPLAY solely to detect some client extension, then + the client process would be confined for its lifetime to use only + that platform to which EGL_DEFAULT_DISPLAY belongs. This + confinement may be fatal if the process had wanted to use + a different platform. + + 3. PROPOSED SOLUTION: Abandon the concept of client extensions. + Instead, in implementations that support multiple window systems + at runtime, eglGetDisplay should autodetect the platform to which + the native display belongs. A suitable error should be generated + if an unsupported native display is passed to eglGetDisplay. + + ANALYSIS: For some native platforms, the display type is opaque + with no defined ABI. (For example, in libX11 the 'Display' type is + an opaque typedef). There exists no method by which eglGetDisplay + could reliably detect that the given native display belongs to + such a platform. + + This solution also has a subtle fatal problem. The client + extensions will likely specify that an EGL client may create EGL + resources from multiple platforms in the same process. But, Mesa's + global write-once state, mentioned above, prevents using multiple + platforms in one process. Therefore, under this proposed solution + and on a system where a problematic version of Mesa is installed, + the client would be unable to detect if EGL supported multiple + platforms per process without committing to the platform to which + the first initialized display belonged. + + 4. ACCEPTED SOLUTION: Allow the EGL client to query the extension + string of EGL_NO_DISPLAY, which would contain the client + extensions. + + ANALYSIS: This solution does not require the initialization of + a throw-away EGLDisplay, nor does it require that native display + types have a fixed ABI. + + This is the solution described by this extension specification, + EGL_EXT_client_extensions. + +Revision History + + Version 11, 2013.10.10 (Chad Versace) + - Fix conformance test #3. It should require that the display extension + list be disjoint to rather than a superset of the client extension + list. (The 'superset' requirement was changed pre-publication to + 'disjoint' in version 8). + + Version 10, 2013.07.03 (Chad Versace) + - Version 9 and 10 are identical due to a versioning error. + + Version 9, 2013.07.03 (Chad Versace) + - Define the concept of *extension type*, require require that each EGL + extension belong to exactly one type, and define two types: display + and client. + - Suggest new section "Extension Type" for future extension + specifications. + - Add new section 2.n Extensions. + - Simplify modifications to section 3.3 by using the new extension type + terminology. + + Version 8, 2013.07.01 (Chad Versace) + - Change resolution of Issue 4 from the 'superset' relation to the + 'disjoint' relation, according to discussion with Jakob Bornecrantz. + Acked by James Jones. + + Version 7, 2013.06.10 (Chad Versace) + - Fix typos. + s/unitialized/uninitialized/ + s/EGL_NO_EXTENSIONS/EGL_EXTENSIONS/ + + Version 6, 2013.06.07 (Chad Versace) + - Remove the Motivation section, merging its content into the Overview + section and Issue 6. + + Version 5, 2013.06.07 (Chad Versace) + - Resolve issue 3 regarding classifying currently published extensions + as client extensions. + - Resolve issue 4 regarding the relationship among client and display + extension strings. + - Add and resolve issue 5, requiring client extension specifications + to contain language about the EGL_NO_DISPLAY extension string. + + Version 4, 2013.05.14 (Chad Versace) + - Add issue 4. + + Version 3, 2013.03.24 (Chad Versace) + - Fix conformance test condition 1.b. The returned extension string + should list, at a minimum, this extension. [Found by Ian Romanick]. + - Add section "Movivation". [Requested by Ian Romanick]. + + Version 2, 2013.03.06 (Chad Versace) + - Remove enum EGL_CLIENT_EXTENSIONS_EXT. Reuse EGL_EXTENSIONS for that + purpose. + - To obtain client extensions, require the eglQueryString be called + with dpy=EGL_NO_DISPLAY rather than dpy=NULL. [Suggested by James + Jones]. + - Add descriptions of conformance tests. [Suggested by Ian Romanick]. + - Add sections "Overview" and "Issues". + + Version 1, 2013.03.06 (Chad Versace) + - First draft + +# vim: filetype=text expandtab autoindent shiftwidth=4 textwidth=80: diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_client_sync.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_client_sync.txt new file mode 100644 index 0000000..1868feb --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_client_sync.txt @@ -0,0 +1,146 @@ +Name + + EXT_client_sync + +Name Strings + + EGL_EXT_client_sync + +Contributors + + Daniel Kartch + +Contacts + + Daniel Kartch, NVIDIA Corporation (dkartch 'at' nvidia.com) + +Status + + Complete + +Version + + Version 2, April 20, 2018 + +Number + + EGL Extension #129 + +Extension type + + EGL display extension + +Dependencies + + Requires EGL_EXT_sync_reuse + +Overview + + The EGL_KHR_reusable_sync extension defines an EGL_SYNC_REUSABLE_KHR + EGLSync type which is signaled and unsignaled by client events. The + EGL_EXT_sync_reuse extension allows all EGLSyncs to become reusable. + The signaling behavior associated with EGL_SYNC_REUSABLE_KHR is + still desirable, but the name becomes misleading if all EGLSyncs can + be reused. This extension defines an EGLSync type with equivalent + behavior, separating the signaling mechanism from the reusability. + +New Procedures and Functions + + EGLBoolean eglClientSignalSyncEXT( + EGLDisplay dpy, + EGLSync sync, + const EGLAttrib *attrib_list); + +New Types + + None + +New Tokens + + Accepted by the <type> parameter of eglCreateSync, and returned + in <value> when eglGetSyncAttrib is called with <attribute> + EGL_SYNC_TYPE: + + EGL_SYNC_CLIENT_EXT 0x3364 + + Returned in <value> when eglGetSyncAttrib is called with attribute + EGL_SYNC_CONDITION: + + EGL_SYNC_CLIENT_SIGNAL_EXT 0x3365 + +Add to the list of sync object decriptions in 3.8.1 Sync Objects + + A <client sync object> reflects the readiness of some client-side + state. Sync objects of this type are not visible to API contexts and + may not be used with eglWaitSync. They may be waited for with + eglClientWaitSync or polled with eglGetSyncAttrib as other sync + types. + +Add to the end of 3.8.1 Sync Objects + + The command + + EGLBoolean eglClientSignalSyncEXT(EGLDisplay dpy, EGLSync sync, + const EGLAttrib *attrib_list); + + may be called to switch sync objects which support it to the + signaled state. Currently only sync objects with type + EGL_SYNC_CLIENT_EXT provide this support. The attribute list may be + used to provide additional information to the signaling operation, + as defined for the sync type. + + Errors + + eglClientSignalSyncEXT returns EGL_FALSE on failure, and has no + effect on <sync>. + If <dpy> is not the name of a valid, initialized EGLDisplay, an + EGL_BAD_DISPLAY error is generated. + If <sync> is not a valid sync object associated with <dpy>, an + EGL_BAD_PARAMETER error is generated. + If <attrib_list> contains an attribute name not defined for the + type of <sync>, an EGL_BAD_ATTRIBUTE error is generated. + If <sync>'s type does not support this direct signaling, an + EGL_BAD_ACCESS error is generated. + +Insert new subsection in 3.8.1 Sync Objects + + 3.8.1.x Creating and Signaling Client Sync Objects + + If type is EGL_SYNC_CLIENT_EXT, a client sync object is created. The + EGL_SYNC_STATUS attribute may be specified as either EGL_UNSIGNALED + or EGL_SIGNALED, and will default to EGL_UNSIGNALED. No other + attributes may be specified for a client sync object. The value of + EGL_SYNC_CONDITION will be set to EGL_SYNC_CLIENT_SIGNAL_EXT. + + A client sync object in the unsignaled state will switch to the + signaled state when eglClientSignalSyncEXT is called. No attributes + are supported for signaling a sync object of this type. Signaling a + client sync object which is already in the signaled state will have + no effect. + + A client sync object which is in the signaled state may be switched + back to the unsignaled state with eglUnsignalSyncEXT. No attributes + are supported for unsignaling a sync object of this type. + +Add to the error list for eglWaitSync in 3.8.1.3 Waiting for Sync +Objects + + If <sync> is of type EGL_SYNC_CLIENT_EXT, an EGL_BAD_ACCESS error is + generated. + +Issues + + None + +Revision History + + #2 (April 20, 2018) Daniel Kartch + - Renamed to EXT + - Fixed missing attrib_list in New Functions section + - Eliminated condition as an allowed attribute at creation. This + is inconsistent with other sync extensions, and there is no + need to make it configurable at this time. Future extensions + can make the condition configurable if desired. + + #1 (Feburary 22, 2018) Daniel Kartch + - Initial draft as XXX diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_compositor.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_compositor.txt new file mode 100644 index 0000000..6e98428 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_compositor.txt @@ -0,0 +1,400 @@ +Name + + EXT_compositor + +Name Strings + + EGL_EXT_compositor + +Contributors + + Marc Moody + Daniel Herring + +Contacts + + Marc Moody, Boeing Inc., marc dot d dot moody at boeing dot com + Daniel Herring, Core Avionics & Industrial Inc., daniel dot herring at ch1group dot com + +Status + + Complete + +Version + Version 1.0, February 3, 2017 + +Number + + EGL Extension #116 + +Dependencies + + Requires EGL 1.0. + + This extension is written against the wording of the EGL 1.4 + Specification - April 6, 2011, but may be implemented against earlier + versions. + +Overview + + This extension allows for the composition of multiple windows within + a multi-partition EGL system. The extension allows a primary EGLContext and + window to be created for each display. All other windows are created using + non-displayable surfaces. A handle to each off-screen window is provided + to the primary EGLContext to allow the composition of all non-displayable windows + on a single display. + + For each display, there is one EGLContext which has access to create on screen + windows, this is call the primary context for this display. All other EGLContexts + are referred to as secondary contexts. + + This extension requires a multi-partition EGL driver to support asynchronous + rendering of off screen surfaces. + + Information assurance is provided by preventing context and surface creation by + unregistered contexts and by preventing the non-primary contexts and surfaces + from rendering to the display. + +New Types + + None + +New Procedures and Functions + + EGLBoolean eglCompositorSetContextListEXT (const EGLint *external_ref_ids, + EGLint num_entries); + + EGLBoolean eglCompositorSetContextAttributesEXT (EGLint external_ref_id, + const EGLint *context_attributes, + EGLint num_entries); + + EGLBoolean eglCompositorSetWindowListEXT (EGLint external_ref_id, + const EGLint *external_win_ids, + EGLint num_entries); + + EGLBoolean eglCompositorSetWindowAttributesEXT (EGLint external_win_id, + const EGLint *window_attributes, + EGLint num_entries); + + EGLBoolean eglCompositorBindTexWindowEXT (EGLint external_win_id); + + EGLBoolean eglCompositorSetSizeEXT (EGLint external_win_id, + EGLint width, EGLint height); + + EGLBoolean eglCompositorSwapPolicyEXT (EGLint external_win_id, + EGLint policy); + + +New Tokens + + New attributes accepted by the <attrib_list> argument of + eglCreateContext: + + EGL_PRIMARY_COMPOSITOR_CONTEXT_EXT 0x3460 + + New attributes accepted by the <attrib_list> argument of + eglCreateContext and eglCreateWindowSurface: + + EGL_EXTERNAL_REF_ID_EXT 0x3461 + + New attributes accepted by the <policy> argument of + eglCompositorSwapPolicyHint: + + EGL_COMPOSITOR_DROP_NEWEST_FRAME_EXT 0x3462 + + EGL_COMPOSITOR_KEEP_NEWEST_FRAME_EXT 0x3463 + +Modify Section 3.7.1 of the EGL 1.4 Specification, paragraph 2 + (Creating Rendering Contexts) on pg. 43 + From: + If eglCreateContext succeeds, it initializes the context to the initial state defined + for the current rendering API, and returns a handle to it. The context can be + used to render to any compatible EGLSurface. + + To: + If eglCreateContext succeeds, it initializes the context to the initial state defined + for the current rendering API, and returns a handle to it. The context can be + used to render to any compatible off-screen rendering surface (Sections 3.5.2 + and 3.5.4). A secondary context can be used to render to compatible window surfaces + which have been associated with the context using eglCompositorSetWindowListEXT. A + non-secondary context can be used to render to any compatible EGLSurface. + +Modify Section 3.7.1 of EGL 1.4 Specification, paragraph 5 + (Creating Rendering Contexts) on pg. 43 + From: + attrib_list specifies a list of attributes for the context. The list has the same + structure as described for eglChooseConfig. The only attribute that can be specified + in attrib_list is EGL_CONTEXT_CLIENT_VERSION, and this attribute may only + be specified when creating a OpenGL ES context (e.g. when the current rendering + API is EGL_OPENGL_ES_API). + + To: + attrib_list specifies a list of attributes for the context. The list has the same + structure as described for eglChooseConfig. The attributes that can be specified + in attrib_list are EGL_CONTEXT_CLIENT_VERSION, EGL_PRIMARY_COMPOSITOR_CONTEXT_EXT, + EGL_EXTERNAL_REF_ID_EXT. + +Modify Section 3.7.1 of EGL 1.4 Specification, paragraph 7 + (Creating Rendering Contexts) on pg. 43 + From: + EGL_CONTEXT_CLIENT_VERSION determines which version of an OpenGL + ES context to create. An attribute value of 1 specifies creation of an OpenGL ES + 1.x context. An attribute value of 2 specifies creation of an OpenGL ES 2.x context. + The default value for EGL_CONTEXT_CLIENT_VERSION is 1. + + To: + EGL_CONTEXT_CLIENT_VERSION determines which version of an OpenGL + ES context to create. An attribute value of 1 specifies creation of an OpenGL ES + 1.x context. An attribute value of 2 specifies creation of an OpenGL ES 2.x context. + The default value for EGL_CONTEXT_CLIENT_VERSION is 1. EGL_CONTEXT_CLIENT_VERSION + may only be specified when creating a OpenGL ES context (e.g. when the current + rendering API is EGL_OPENGL_ES_API). + +Additions to Section 3.7.1 of the EGL 1.4 Specification (Creating Rendering Contexts). + + The first call to eglCreateContext with EGL_PRIMARY_COMPOSITOR_CONTEXT_EXT + set as EGL_TRUE in the <attrib-list> returns an EGLContext handle which will + act as the primary context for the specified EGLDisplay. This shall be the + only context on this EGLDisplay which is able to be bound to an on-screen window + on the EGLDisplay. Subsequent calls to eglCreateContext, for the same display, + in any address space with EGL_PRIMIARY_COMPOSITOR_CONTEXT_EXT set as EGL_TRUE + shall return EGL_NO_CONTEXT. + Subsequent calls, in any address space for the same display, to eglCreateContext + which do not use EGL_PRIMARY_COMPOSITOR_CONTEXT_EXT should use the the attribute + EGL_EXTERNAL_REF_ID_EXT and an external reference identifier to create a valid + EGLContext. + Subsequent calls, in any address space for the same display, to eglCreateContext + which do not use EGL_PRIMARY_COMPOSITOR_CONTEXT_EXT and do not use + EGL_EXTERNAL_REF_ID_EXT shall not create a context and shall return + EGL_NO_CONTEXT and set the error EGL_BAD_ACCESS. + + EGL_PRIMARY_COMPOSITOR_CONTEXT_EXT notifies EGL that this context is the only + context allowed to render to a on screen window surface for this display. This + attribute is followed in the attribute list by either EGL_TRUE or EGL_FALSE. + EGL_EXTERNAL_REF_ID_EXT is followed by an external reference identifier which + associates this context with the list of allowed contexts set by + eglCompositorSetContextListEXT. If the reference identifier has already been + used to initiate another call to eglCreateContext in any address space, this + call shall fail and set the error EGL_BAD_ATTRIBUTE. IF the external reference + identifier is not a valid identifier the error EGL_BAD_ATTRIBUTE shall be set + and the call shall fail. If this attribute is set and the primary context has + not yet been created then the error EGL_BAD_MATCH and the call shall fail. + + Only when the attributes specified via attrib_list and those specified for this + context using eglCompositorSetContextAttributesEXT are compatible will the + context be successfully created. + +Modify the list of parameters supported by eglCreateWindowSurface in section 3.5.1 + (Creating On-Screen Rendering Surfaces) on p. 27: + + An external window identifier (EGLuint external_win_id) is associated with + each off screen window. EGLNativeWindowType shall be EGLint and the + external window identifier shall be used as the value for the <win> parameter. + EGL_EXTERNAL_REF_ID_EXT with the context external reference id shall be in the + attrib_list. If the external window identifier and the external reference identifier + do not match a pair set using eglCompositorSetWindowListEXT window creation shall + fail. + +Add the function: + + EGLBoolean eglCompositorSetContextListEXT(const EGLint *external_ref_ids, + EGLint num_entries); + + This function is called by the primary context to establish the set of + all allowable secondary contexts by defining the set of external reference + identifiers. Secondary contexts shall identify their external reference + identifier by setting the EGL_EXTERNAL_REF_ID_EXT attribute when calling + eglCreateContext. + Calls to this function when the primary context for the display is not active, + shall return EGL_FALSE and do nothing. When this function is successful it + shall return EGL_TRUE and associate the list of external reference identifiers + with the active display. + This function shall only be called once per primary context. Subsequent calls + shall return EGL_FALSE and do nothing. + + external_ref_ids shall be an array of user generated integers greater than 1. + num_entries shall specify the number of external_ref_ids. + +Add the function: + + EGLBoolean eglCompositorSetContextAttributesEXT (EGLint external_ref_id, + const EGLint *context_attributes, + EGLint num_entries); + + This function is called by the primary context to establish a list of compatible + context attributes. + Calls to this function when the primary context for the display is not active + shall return EGL_FALSE and do nothing. When the function is successful it shall + return EGL_TRUE and associate the given attributes to the subsequent + eglCreateContext call using the given external reference id. + The list of acceptable context_attributes is the same as the list for + eglCreateContext. Only when this list of attributes is compatible with those + used during context creation will the secondary context be created. + This function shall only be called once per secondary context, and must be called + before the secondary context is able to be created. Subsequent calls shall + return EGL_FALSE and do nothing. + + num_entries shall specify the number of attributes in the list. This number + shall prevent accessing memory outside the attribute list, even if EGL_NONE is + not yet found in the list. If EGL_NONE is found sooner than this number of + attributes list parsing shall stop. + +Add the function: + + EGLBoolean eglCompositorSetWindowListEXT (EGLint external_ref_id, + const EGLint *external_win_ids, + EGLint num_entries); + + This function is called by the primary context to establish the set of + all allowable windows associated with a specific secondary context by defining + the set of external window identifiers. Window surface creation within secondary + contexts use the external window identifier as the native window handle parameter + of eglCreateWindowSurface and supply an external reference id as a window creation + attribute. + Calls to this function when the primary context for the display is not active, + shall return EGL_FALSE and do nothing. When this function is successful it + shall return EGL_TRUE and associate the list of external window identifiers + with the specified secondary context (external_ref_ids). + + external_win_ids shall be an array of user generated integers greater than 1. + external window identifiers are unique within the primary EGLContext. Any + external window identifier may be associated with multiple secondary contexts + however only the first context which calls eglCreateWindowSurface shall + successfully create a window surface for the given window. + num_entries shall specify the number of external_ref_ids. + +Add the function: + + EGLBoolean eglCompositorSetWindowAttributesEXT (EGLint external_win_id, + const EGLint *window_attributes, + EGLint num_entries); + + This function is called by the primary context to set window specific attributes + for the specified external window id. + + The list of valid attributes are: EGL_WIDTH, EGL_HEIGHT, EGL_VERTICAL_RESOLUTION, + EGL_HORIZONRAL_RESOLUTION, EGL_PIXEL_ASPECT_RATIO. + EGL_WIDTH and EGL_HEIGHT shall set the maximum width and height the secondary + context is able to create a window surface with. + EGL_VERTICAL_RESOLUTION, EGL_HORIZONTAL_RESOLUTION, and EGL_PIXEL_ASPECT_RATIO + shall set the values of these used by the secondary context. + Calls to this function when the primary context for the display is not active, + shall return EGL_FALSE and do nothing. When this function is successful it + shall return EGL_TRUE and associate the list of attributes with the off screen + window ID (external_win_id). + This function shall only be called once per window, and must be called before + the secondary context is able to create the window surface. Subsequent calls + shall return EGL_FALSE and do nothing. + + num_entries shall specify the number of attributes in the list. This number + shall prevent accessing memory outside the attribute list, even if EGL_NONE is + not yet found in the list. If EGL_NONE is found sooner than this number of + attributes list parsing shall stop. + +Add the function: + + EGLBoolean eglCompositorBindTexWindowEXT (EGLint external_win_id); + + This function is similar to eglBindTexImage in that it binds the windows + color buffers to a texture object which can then be composited on the native + window by the primary context. This function shall only be callable within + the primary context while there is a texture object actively bound by the + native rendering API. The function shall return EGL_TRUE if the window is + successfully bound to the active texture object. The function shall return + EGL_FALSE if binding fails, the context is not the primary context, or the + external_win_id is not a valid external window reference as set using + eglCompositorSetWindowListEXT. + +Add the function: + + EGLBoolean eglCompositorSetSizeEXT(EGLint external_win_id, + EGLint width, EGLint height); + + This function shall be called by the primary context to set the width and + height of the window. This function returns EGL_FALSE when called by a context + other than the primary context. This function will also return EGL_FALSE if + the new width and height are larger than the maximums set by + eglCompositorSetWindowAttributesEXT. Upon successful window resizing the function + shall return EGL_TRUE. + Secondary contexts may use EGL to query the windows width and height at runtime + to detect window resize events. The window buffer resizing shall be applied + to the newly active buffer after the secondary context calls eglSwapBuffers. + This will leave an average of 2 buffers which will have to be scaled by the + native rendering API to the new resolution. + +Add the function: + + EGLBoolean eglCompositorSwapPolicyEXT(EGLint external_win_id, + EGLint policy); + + This function shall be called by the primary context to specify the handling + of buffer swaps of the context specified by external_ref_id. + + When the policy is set to EGL_COMPOSITOR_DROP_NEWEST_FRAME_EXT, and the + secondary context completes a frame by calling eglSwapbuffers, and the + primary context is actively reading from the front buffer associated with + the external window ID, then the just completed frame is dropped, no buffer + swap occurs, and eglSwapBuffers will return EGL_TRUE. + If EGL_COMPOSITOR_KEEP_NEWEST_FRAME_EXT is specified and the primary context + is actively reading from the front buffer associated with the external window + ID then the secondary context's call to eglSwapBuffers will return EGL_FALSE. + eglSwapBuffers will continue to return EGL_FALSE as long as the primary context + is actively reading from the front buffer. Once the primary context finishes + reading from the front buffer the next call to eglSwapBuffers will + return EGL_TRUE. It is up to the application to decide if it will wait until + eglSwapBuffers returns EGL_TRUE before rendering again. If the secondary + context continues to render after eglSwapBuffers returns EGL_FALSE then it will + be as if the swap policy was EGL_COMPOSITOR_DROP_NEWEST_FRAME_EXT. + + +Revision History + Version 0.1, 30/08/2014 - first draft. + Version 0.2, 24/09/2014 second draft. + Version 0.3, 21/12/2016 + Khronos vendor extension clean-up. + Version 0.4, 05/01/2016 + - Change from context and display limitation to context and window limitations + - Added additional functions related to external window ids contexts. + Version 1.0, 03/02/2017 + - Fixed misc issues related to parameter names and types. + +Question: How are external reference and window IDs assigned and managed? Are they + reserved somehow within a new EGL C header file? +Answer: External IDs are assigned from the software component with the primary + context during an EGL initialization stage using eglCompositorSet*ListEXT. + The secondary contexts are provided the appropriate external reference ID + during end system integration. It is recommended that these values be able + to be set via a configuration parameter to the application, to ease + integration of multiple programs. + +Question: What happens when the secondary contexts render faster than the + primary context? +Answer: This is based on the swap policy set by the compositor, and the rate + difference between the render and the compositor. Secondary contexts + will be notified by EGL_FALSE being returned if the windows front buffer + is currently being read by the compositor. However, if the compositor is + not currently reading the front buffer the swap will succeed and the + secondary contexts latest rendered frame will now be in the front buffer + to be composited. + +Question: What happens when the primary context renders faster than the + secondary context(s)? +Answer: The contents of the windows front buffer will be repeated. + +Question: Does this infer any Z-ordering for the off-screen surfaces? +Answer: No, the Z-order is applied by the compositor when doing the final on + screen rendering of the off-screen surfaces. Or may be set if a Z-ordering + extension is applied to the attribute list of the window using + eglCompositorSetWindowAttributesEXT + +Comments: + +The driver should also have to have enough protection in it to prevent a random +software component from passing random buffer handles to the driver to prevent +access to other software components. + +The driver may force use of double buffering event if the window surface was created +using an EGL_RENDER_BUFFER attribute set to EGL_SINGLE_BUFFER. + +If EGL_PRIMARY_COMPOSITOR_CONTEXT_EXT is not used to create a context for a specified +display then EGL will act as though this extension is not enabled. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_config_select_group.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_config_select_group.txt new file mode 100644 index 0000000..9721195 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_config_select_group.txt @@ -0,0 +1,111 @@ +Name + + EGL_EXT_config_select_group + +Name Strings + + EGL_EXT_config_select_group + +Contributors + + Hal Gentz <zegentzy@protonmail.com> + Adam Jackson <ajax@redhat.com> + Robert Mader <robert.mader@posteo.de> + +Contacts + + Hal Gentz <zegentzy@protonmail.com> + +Status + + Draft + +Version + + Version 4, 2021-06-24 + +Number + + EGL Extension #145 + +Extension Type + + EGL client extension + +Dependencies + + This extension is written against the wording of the 2014.08.27 revision + of the EGL 1.5 Specification. + +Overview + + This extension provides a mechanism to lower the config selection priority + of the configs returned by eglChooseConfig. A new config attribute is + introduced, providing a way for the implementation to group configs into + different config selection categories. The config selection priorities of + all the configs in one category may be higher or lower than the ones in + other categories. The config selection priorities in one category follow + the rules of eglChooseConfig. See also GLX_SGIX_visual_select_group. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted as a new EGLConfig attribute: + + EGL_CONFIG_SELECT_GROUP_EXT 0x34C0 + +Additions to the EGL 1.5 Specification + + In section 3.4 "Configuration Management", under the "Buffer Descriptions + and Attributes" heading, append to table 3.1 the following: + + "EGL_CONFIG_SELECT_GROUP_EXT | integer | the config select group" + + In section 3.4 "Configuration Management", under the "Other EGLConfig + Attribute Descriptions" heading, append to the end the following: + + "The attribute EGL_CONFIG_SELECT_GROUP_EXT is used to specify the config + selection category of the config. Configs in the i-th category have a higher + config selection priority than those found in the (i+1)-th category. + + "The attribute EGL_CONFIG_SELECT_GROUP_EXT is used by the implementation to + override the default sorting rules, by collecting configurations into + groups. It is not accepted by the <attrib_list> parameter of + eglChooseConfig, but it is accepted as the <attribute> in + eglGetConfigAtrrib." + + In section 3.4 "Configuration Management", under the "Sorting of EGLConfigs" + heading, append to table 3.4 the following: + + "EGL_CONFIG_SELECT_GROUP_EXT | 0 | Ignore | Smaller | 0" + + In section 3.4 "Configuration Management", under the "Sorting of EGLConfigs" + heading, append before the list entry which starts with "1. Special: by + EGL_CONFIG_CAVEAT" the following entry: + + "0. Smaller EGL_CONFIG_SELECT_GROUP_EXT." + +Issues + + None + +Revision History + + Version 4, 2021-06-24 (Robert Mader) + - Moved to EXT, changed enum value to 0x34C0. + + Version 3, 2020-04-06 (Robert Mader) + - Changed enum value to 0x31DF, added contributors. + + Version 2, 2019-07-11 (Hal Gentz) + - Resolved issues pointed out by Adam Jackson. + + Version 1, 2019-06-21 (Hal Gentz) + - Initial draft diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_create_context_robustness.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_create_context_robustness.txt new file mode 100644 index 0000000..a78f878 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_create_context_robustness.txt @@ -0,0 +1,169 @@ +Name + + EXT_create_context_robustness + +Name Strings + + EGL_EXT_create_context_robustness + +Contributors + + Daniel Koch, TransGaming + Contributors to EGL_KHR_create_context + +Contact + + Greg Roth (groth 'at' nvidia.com) + +Status + + Complete. + +Version + + Version 3, 2011/10/31 + +Number + + EGL Extension #37 + +Dependencies + + Requires EGL 1.4 + + Written against the EGL 1.4 specification. + + An OpenGL implementation supporting GL_ARB_robustness, an OpenGL ES + implementation supporting GL_EXT_robustness, or an implementation + supporting equivalent functionality is required. + +Overview + + This extension allows creating an OpenGL or OpenGL ES context + supporting robust buffer access behavior and a specified graphics + reset notification behavior. + +New Procedures and Functions + + None + +New Tokens + + Accepted as an attribute name in the <*attrib_list> argument to + eglCreateContext: + + EGL_CONTEXT_OPENGL_ROBUST_ACCESS_EXT 0x30BF + EGL_CONTEXT_OPENGL_RESET_NOTIFICATION_STRATEGY_EXT 0x3138 + + Accepted as an attribute value for EGL_CONTEXT_RESET_NOTIFICATION_- + STRATEGY_EXT in the <*attrib_list> argument to eglCreateContext: + + EGL_NO_RESET_NOTIFICATION_EXT 0x31BE + EGL_LOSE_CONTEXT_ON_RESET_EXT 0x31BF + +Additions to the EGL 1.4 Specification + + Replace section 3.7.1 "Creating Rendering Contexts" from the + fifth paragraph through the seventh paragraph: + + <attrib_list> specifies a list of attributes for the context. The + list has the same structure as described for eglChooseConfig. If an + attribute is not specified in <attrib_list>, then the default value + specified below is used instead. <attrib_list> may be NULL or empty + (first attribute is EGL_NONE), in which case attributes assume their + default values as described below. Most attributes are only meaningful + for specific client APIs, and will generate an EGL_BAD_ATTRIBUTE + error when specified to create for another client API context. + + Context Versions + ---------------- + + EGL_CONTEXT_CLIENT_VERSION determines which version of an OpenGL ES + context to create. This attribute may only be specified when creating + an OpenGL ES context (e.g. when the current rendering API is + EGL_OPENGL_ES_API). An attribute value of 1 specifies creation of an + OpenGL ES 1.x context. An attribute value of 2 specifies creation of an + Open GL ES 2.x context. The default value for EGL_CONTEXT_CLIENT_VERSION + is 1. + + Context Robust Access + ------------- + + EGL_CONTEXT_OPENGL_ROBUST_ACCESS_EXT indicates whether <robust buffer + access> should be enabled for the OpenGL ES context. Robust buffer + access is defined in the GL_EXT_robustness extension specification, + and the resulting context must support GL_EXT_robustness and robust + buffer access as described therein. The default value of + EGL_CONTEXT_OPENGL_ROBUST_ACCESS_EXT is EGL_FALSE. + + Context Reset Notification + -------------------------- + + The attribute name EGL_CONTEXT_OPENGL_RESET_NOTIFICATION_STRATEGY_- + EXT specifies the <reset notification behavior> of the rendering + context. This attribute is only meaningful for OpenGL ES contexts, + and specifying it for other types of contexts will generate an + EGL_BAD_ATTRIBUTE error. + + Reset notification behavior is defined in the GL_EXT_robustness + extension for OpenGL ES, and the resulting context must support + GL_EXT_robustness and the specified reset strategy. The attribute + value may be either EGL_NO_RESET_NOTIFICATION_EXT or EGL_LOSE_- + CONTEXT_ON_RESET_EXT, which respectively result in disabling + delivery of reset notifications or the loss of all context state + upon reset notification as described by the GL_EXT_robustness. The + default value for EGL_CONTEXT_OPENGL_RESET_NOTIFICATION_STRATEGY_EXT + is EGL_NO_RESET_NOTIFICATION_EXT. + + Add to the eglCreateContext context creation errors: + + * If <config> does not support a client API context compatible + with the requested context flags and context reset notification + behavior (for client API types where these attributes are + supported), then an EGL_BAD_CONFIG error is generated. + + * If the reset notification behavior of <share_context> and the + newly created context are different then an EGL_BAD_MATCH error is + generated. + + +Errors + + EGL_BAD_CONFIG is generated if EGL_CONTEXT_OPENGL_ROBUST_ACCESS_- + EXT is set to EGL_TRUE and no GL context supporting the GL_EXT_- + robustness extension and robust access as described therein can be + created. + + EGL_BAD_CONFIG is generated if no GL context supporting the + GL_EXT_robustness extension and the specified reset notification + behavior (the value of attribute EGL_CONTEXT_RESET_NOTIFICATION_- + STRATEGY_EXT) can be created. + + BAD_MATCH is generated if the reset notification behavior of + <share_context> does not match the reset notification behavior of + the context being created. + +New State + + None + +Conformance Tests + + TBD + +Sample Code + + TBD + +Issues + + None + +Revision History + + Rev. Date Author Changes + ---- ------------ --------- ---------------------------------------- + 3 31 Oct 2011 groth Reverted to attribute for robust access. Now it's a + companion to rather than subset of KHR_create_context + 2 11 Oct 2011 groth Merged ANGLE and NV extensions. + 1 15 July 2011 groth Initial version diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_base.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_base.txt new file mode 100644 index 0000000..aece774 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_base.txt @@ -0,0 +1,243 @@ +Name + + EXT_device_base + +Name Strings + + EGL_EXT_device_base + +Contributors + + James Jones + Daniel Kartch + Jamie Madill + +Contacts + + James Jones, NVIDIA (jajones 'at' nvidia.com) + +Status + + Complete + + Rewritten in terms of split functionality in EXT_dispay_device and + EXT_device_enumeration. + +Version + + Version 9 - March 24th, 2015 + +Number + + EGL Extension #72 + +Extension Type + + EGL client extension + +Dependencies + + Written against the wording of EGL 1.5. + + The specifications of EGL_EXT_device_query and + EGL_EXT_device_enumeration are required to determine the + specification of this extension, although those extensions may not + be supported. + +Overview + + Increasingly, EGL and its client APIs are being used in place of + "native" rendering APIs to implement the basic graphics + functionality of native windowing systems. This creates demand + for a method to initialize EGL displays and surfaces directly on + top of native GPU or device objects rather than native window + system objects. The mechanics of enumerating the underlying + native devices and constructing EGL displays and surfaces from + them have been solved in various platform and implementation- + specific ways. The EGL device family of extensions offers a + standardized framework for bootstrapping EGL without the use of + any underlying "native" APIs or functionality. + + This extension defines the first step of this bootstrapping + process: Device enumeration. + +New Types + + As defined by EGL_EXT_device_query. + +New Functions + + As defined by EGL_EXT_device_query and EGL_EXT_device_enumeration. + +New Tokens + + As defined by EGL_EXT_device_query. + +Add to section "3.2 Devices" + + "EGL_EXT_device_base is equivalent to the combination of the + functionality defined by EGL_EXT_device_query and + EGL_EXT_device_enumeration." + +Issues + + 1. Should there be a mechanism (such as an attribute list) to + filter devices in eglQueryDevicesEXT()? + + RESOLVED: No. This could develop too much complexity, like + the EGLConfig mechanism. Instead, force applications to query + all devices and implement any desired filtering themselves. + + 2. Should there be an eglSetDeviceAttribEXT()? + + RESOLVED: No. Device properties are immutable. + + 3. Should a device file descriptor attribute be included in the + base specification? + + RESOLVED: No. It seems like an arbitrary attribute to include + in the base extension. Other extensions can easily be added + if this or other device attributes are needed. + + 4. Should EGLDeviceEXT handles be opaque pointers or 32-bit + values? + + RESOLVED: Opaque pointers. The trend seems to be to use + opaque pointers for object handles, and opaque pointers allow + more implementation flexibility than 32-bit values. + Additionally, the introduction of the EGLAttrib type allows + inclusion of pointer-sized types in attribute lists, which was + the only major advantage of 32-bit types. + + 5. Should eglQueryDisplayAttribEXT be defined as part of this + extension? + + RESOLVED: Yes. There are no other known uses for this + function, so it should be defined here. If other uses are + found, future extension specifications can reference this + extension or retroactively move it to a separate extension. + + 6. How should bonded GPU configurations, such as SLI or Crossfire + be enumerated? What about other hybrid rendering solutions? + + RESOLVED: Bonded GPUs should appear as one device in this API, + since the client APIs generally treat them as one device. + Further queries can be added to distinguish the lower-level + hardware within these bonded devices. + + Hybrid GPUs, which behave independently but are switched + between in a manner transparent to the user, should be + enumerated separately. This extension is intended to be used + at a level of the software stack below this type of automatic + switching or output sharing. + + 7. Should this extension require all displays to have an + associated, queryable device handle? + + RESOLVED: Yes. This allows creating new namespace containers + that all displays can be grouped in to and allows existing + applications with display-based initialization code to easily + add device-level functionality. Future extensions are + expected to expose methods to correlate EGL devices and native + devices, and to use devices as namespaces for future objects + and operations, such as cross-display EGL streams. + + 8. Are device handles returned by EGL valid in other processes? + + RESOLVED: No. Another level of indirection is required to + correlate two EGL devices in separate processes. + + 9. Is a general display pointer query mechanism needed, or should + an eglGetDevice call be added to query a display's associated + device? + + RESOLVED: A general mechanism is better. It may have other + uses in the future. + + 10. Should a new type of extension be introduced to query device- + specific extensions? + + RESOLVED: Yes. Without this mechanism, it is likely that most + device extensions would require a separate mechanism to + determine which devices actually support them. Further, + requiring all device-level extensions to be listed as client + extensions forces them to be implemented in the EGL client + library, or "ICD". This is unfortunate since vendors will + likely wish to expose vendor-specific device extensions. + + These advantages were weighed against the one known + disadvantage of a separate extension type: Increasing the + complexity of this extension and the EGL extension mechanism + in general. + + 11. Is eglQueryDeviceStringEXT necessary, or should the device + extension string be queried using eglQueryDeviceAttribEXT? + + RESOLVED: Using a separate query seems more consistent with + how the current extension strings are queried. + + 12. Should this extension contain both device enumeration and + the ability to query the device backing an EGLDisplay? + + RESOLVED: This extension initially included both of these + abilities. To allow simpler implementations to add only the + ability to query the device of an existing EGLDisplay, this + extension was split into two separate extensions: + + EGL_EXT_device_query + EGL_EXT_device_enumeration + + The presence of this extension now only indicates support + for both of the above extensions. + +Revision History: + + #9 (March 24th, 2015) James Jones + - Split the extension into two child extensions: + EGL_EXT_device_query + EGL_EXT_device_enumeration + + #8 (May 16th, 2014) James Jones + - Marked the extension complete. + - Marked all issues resolved. + + #7 (April 8th, 2014) James Jones + - Renamed eglGetDisplayAttribEXT back to + eglQueryDisplayAttribEXT. + - Update wording based on the EGL 1.5 specification. + - Use EGLAttrib instead of EGLAttribEXT. + - Assigned values to tokens. + + #6 (November 6th, 2013) James Jones + - Added EGL_BAD_DEVICE_EXT error code. + - Renamed some functions for consistency with the core spec + + #5 (November 6th, 2013) James Jones + - Specified this is a client extension + - Renamed eglQueryDisplayPointerEXT eglGetDisplayAttribEXT + and modified it to use the new EGLAttribEXT type rather than + a void pointer + - Introduced the "device" extension type. + - Added eglQueryDeviceStringEXT to query device extension + strings + - Removed issues 5, 10, and 12 as they are no longer relevant + - Added issues 10 and 11. + + #4 (May 14th, 2013) James Jones + - Merged in EGL_EXT_display_attributes + - Changed eglGetDisplayPointerEXT to eglQueryDisplayPointerEXT + - Remove eglGetDisplayAttribEXT since it has no known use case + + #3 (April 23rd, 2013) James Jones + - Include EGL_NO_DEVICE_EXT + - Added issues 8 and 9 + + #2 (April 18th, 2013) James Jones + - Reworded issue 3 and flipped the resolution + - Added issues 5, 6, and 7 + - Filled in the actual spec language modifications + - Renamed from EGL_EXT_device to EGL_EXT_device_base + - Fixed some typos + + #1 (April 16th, 2013) James Jones + - Initial Draft diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_drm.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_drm.txt new file mode 100644 index 0000000..fa125fc --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_drm.txt @@ -0,0 +1,223 @@ +Name + + EXT_device_drm + EXT_output_drm + +Name Strings + + EGL_EXT_device_drm + EGL_EXT_output_drm + +Contributors + + Daniel Kartch + James Jones + Christopher James Halse Rogers + +Contacts + + Daniel Kartch, NVIDIA (dkartch 'at' nvidia.com) + +Status + + Complete + +Version + + Version 5 - December 28th, 2015 + +Number + + EGL Extension #79 + +Extension Type + + EGL device extension for EGL_EXT_device_drm + + EGL display extension for EGL_EXT_output_drm + +Dependencies + + EGL_EXT_device_drm requires EGL_EXT_device_base. + + EGL_EXT_device_drm interacts with EGL_EXT_platform_device + + EGL_EXT_device_drm requires a DRM driver. + + EGL_EXT_output_drm requires EGL_EXT_output_base. + + EGL_EXT_output_drm requires a DRM driver which supports KMS. + + An EGLDisplay supporting EGL_EXT_output_drm must be associated + with an EGLDevice supporting EGL_EXT_device_drm. + +Overview + + Increasingly, EGL and its client APIs are being used in place of + "native" rendering APIs to implement the basic graphics + functionality of native windowing systems. This creates demand + for a method to initialize EGL displays and surfaces directly on + top of native GPU or device objects rather than native window + system objects. The mechanics of enumerating the underlying + native devices and constructing EGL displays and surfaces from + them have been solved in various platform and implementation- + specific ways. The EGL device family of extensions offers a + standardized framework for bootstrapping EGL without the use of + any underlying "native" APIs or functionality. + + These extensions define how to map device and output handles between + EGL and DRM/KMS. An EGL implementation which provides these + extensions must have access to sufficient knowledge of the DRM + implementation to be able to perform these mappings. No requirements + are imposed on how this information is obtained, nor does this + support have any implications for how EGL devices and outputs are + implemented. Among the possibilities, support may be implemented in + a generic fashion by layering on top of DRM, or EGL and DRM backends + may be provided by the same vendor and share privileged lower level + resources. An implementation which supports these extensions may + support other low level device interfaces, such as OpenWF Display, + as well. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Added by EXT_device_drm: + + Accepted as the <name> parameter of eglQueryDeviceStringEXT + + EGL_DRM_DEVICE_FILE_EXT 0x3233 + + If EGL_EXT_platform_device is present, the following is accepted + in the <attrib_list> of eglGetPlatformDisplayEXT(). + + EGL_DRM_MASTER_FD_EXT 0x333C + + Added by EXT_output_drm: + + Accepted in the <attrib_list> of eglGetOutputLayersEXT and as + the <attribute> parameter of eglQueryOutputLayerAttribEXT + + EGL_DRM_CRTC_EXT 0x3234 + EGL_DRM_PLANE_EXT 0x3235 + + Accepted in the <attrib_list> of eglGetOutputPortsEXT and as + the <attribute> parameter of eglQueryOutputPortAttribEXT + + EGL_DRM_CONNECTOR_EXT 0x3236 + +New Behavior for EXT_device_drm + + EGLDeviceEXTs may be mapped to DRM device files. + + To obtain a DRM device file for an EGLDeviceEXT, call + eglQueryDeviceStringEXT with <name> set to EGL_DRM_DEVICE_FILE_EXT. + The function will return a pointer to a string containing the name + of the device file (e.g. "/dev/dri/cardN"). + +If EGL_EXT_platform_device is present, replace the last sentence of the +third paragraph in section 3.2 "Initialization" with the following: + + When <platform> is EGL_PLATFORM_DEVICE_EXT, the only valid attribute + name is EGL_DRM_MASTER_FD_EXT. If specified, the value must be a file + descriptor with DRM master permissions on the DRM device associated + with the specified EGLDevice, as determined by EGL_DRM_DEVICE_FILE_EXT. + If the file descriptor does not refer to the correct DRM device or + does not have master permissions, the behavior is undefined. Calls to + eglGetPlatformDeviceEXT() with the same values for <platform> and + <native_display> but distinct EGL_DRM_MASTER_FD_EXT values will return + separate EGLDisplays. + + If EGL requires the use of the DRM file descriptor beyond the duration + of the call to eglGetPlatformDispay(), it will duplicate it. If no + file descriptor is specified and EGL requires one, it will attempt to + open the device itself. Applications should only need to specify a + file descriptor in situations where EGL may fail to open a file + descriptor itself, generally due to lack of permissions, or when EGL + will fail to acquire DRM master permissions due to conflicts with an + existing DRM client. DRM master permissions are only required when EGL + must modify output attributes. This extension does not define any + situations in which output attributes will be modified. + +New Behavior for EXT_output_drm + + KMS CRTC, plane, and connector IDs may be used to restrict EGL + output handle searches and may be queried from EGL output handles. + + Add to Table 3.10.3.1 in EGL_EXT_output_base: + + Attribute Type Access + --------------------- ------- ------ + EGL_DRM_CRTC_EXT integer S|R + EGL_DRM_PLANE_EXT integer S|R + + Add to Table 3.10.3.2 in EGL_EXT_output_base: + + Attribute Type Access + --------------------- ------- ------ + EGL_DRM_CONNECTOR_EXT integer S|R + + Add to description of eglOutputLayerAttribEXT: + + If <layer> corresponds to a KMS CRTC and <attribute> is + EGL_DRM_PLANE_EXT, or if <layer> corresponds to a KMS plane and + <attribute> is EGL_DRM_CRTC_EXT, an EGL_BAD_MATCH error is + generated. + +Issues + + 1) Should different values of EGL_DRM_MASTER_FD_EXT result in separate + EGLDisplays? + + RESOLVED: Yes. Consider an application made up of two independent + modules running in two independently scheduled threads. Each + module calls eglGetPlatformDisplayEXT(): + + int fd = open("/dev/dri/card0", O_RDWR); + int attr1[] = { EGL_DRM_MASTER_FD_EXT, fd }; + dpy1 = eglGetPlatformDisplayEXT(EGL_PLATFORM_DEVICE_EXT, + eglDev, + attr1); + + ... + + dpy2 = eglGetPlatformDisplayEXT(EGL_PLATFORM_DEVICE_EXT, + eglDev, + NULL); + + Presumably, if dpy1 == dpy2, they would both be using the same DRM + fd for output operations internally. That would mean display + attribute updates would likely fail if dpy2 happened to be created + before dpy1. This would be painful to debug. If dpy2 != dpy1, + failure for dpy2 would be consistent and obvious. The application + author would be required to work out a scheme to share the master + FD between modules before creating EGL displays. + +Revision History: + + #5 (December 28th, 2015) James Jones + - Added EGL_DRM_MASTER_FD_EXT and associated + language. + - Added issue 1. + + #4 (August 22nd, 2014) James Jones + - Marked complete. + - Listed Daniel as the contact. + + #3 (June 5th, 2014) Daniel Kartch + - Assigned enumerated values for constants. + + #2 (May 28th, 2014) Daniel Kartch + - Simplified description of new behavior based on refinements + to EGL_EXT_output_base. + + #1 (January 31st, 2014) Daniel Kartch + - Initial draft, representing a signficant reworking of + functionality previously proposed in + EGL_EXT_native_device_drm. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_drm_render_node.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_drm_render_node.txt new file mode 100644 index 0000000..4c08844 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_drm_render_node.txt @@ -0,0 +1,106 @@ +Name + + EXT_device_drm_render_node + +Name Strings + + EXT_device_drm_render_node + +Contributors + + James Jones + Simon Ser + Daniel Stone + +Contacts + + James Jones, NVIDIA (jajones 'at' nvidia.com) + +Status + + Draft + +Version + + Version 1 - June 4th, 2021 + +Number + + EGL Extension #144 + +Extension Type + + EGL device extension + +Dependencies + + Written based on the wording of the EGL 1.5 specification. + + EGL_EXT_device_query is required. + + EGL_EXT_device_drm interacts with this extension. + +Overview + + The EGL_EXT_device_drm extension provided a method for applications + to query the DRM device node file associated with a given + EGLDeviceEXT object. However, it was not clear whether it referred to + the primary or render device node. This extension adds an enum to + refer explicitly to the render device node and defines the existing + EGL_DRM_DEVICE_FILE_EXT as explicitly refering to the primary device + node. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted as the <name> parameter of eglQueryDeviceStringEXT + + EGL_DRM_RENDER_NODE_FILE_EXT 0x3377 + +Changes to section 3.2 (Devices) + + Add the following paragraph to the description of + eglQueryDeviceStringEXT: + + "To obtain a DRM device file for the render node associated with an + EGLDeviceEXT, call eglQueryDeviceStringEXT with <name> set to + EGL_DRM_RENDER_NODE_FILE_EXT. The function will return a pointer to + a string containing the name of the device file (e.g. + "/dev/dri/renderDN"), or NULL if the device has no associated DRM + render node." + + If EGL_EXT_device_drm is present, append the following to the + paragraph in the same section describing EGL_DRM_DEVICE_FILE_EXT: + + "If the EGL_EXT_device_drm_render_node extension is supported, the + value returned will refer to a primary device node, and will be NULL + if the device has no associated DRM primary node. If + EGL_EXT_device_drm_render_node is not supported, the value returned + will refer to a primary device node if there exists one associated + with the device. Otherwise, it will refer to a render device node if + there exists one associated with the device. If neither exists, NULL + is returned." + +Issues + + 1) Should this extension clarify that EGL_DRM_DEVICE_FILE_EXT refers + only to primary device nodes? + + RESOLVED: Yes, but only when this extension is supported. Existing + implementations return render node paths for that string when no + suitable primary node is available. + +Revision History: + + #2 (June 8th, 2021) James Jones + - Added issue #1 and related spec changes. + + #1 (June 4th, 2021) James Jones + - Initial draft. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_enumeration.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_enumeration.txt new file mode 100644 index 0000000..c7920eb --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_enumeration.txt @@ -0,0 +1,111 @@ +Name + + EXT_device_enumeration + +Name Strings + + EGL_EXT_device_enumeration + +Contributors + + James Jones + Jamie Madill + +Contacts + + James Jones, NVIDIA (jajones 'at' nvidia.com) + +Status + + Complete. + +Version + + Version 1 - March 24th, 2015 + +Number + + EGL Extension #88 + +Extension Type + + EGL client extension + +Dependencies + + Written against the wording of EGL 1.5. + + Requires EGL 1.5 or an earlier verison of EGL with the + EGL_EXT_client_extensions extension. + + Requires the EGL_EXT_device_query extension. + +Overview + + Increasingly, EGL and its client APIs are being used in place of + "native" rendering APIs to implement the basic graphics + functionality of native windowing systems. This creates demand + for a method to initialize EGL displays and surfaces directly on + top of native GPU or device objects rather than native window + system objects. The mechanics of enumerating the underlying + native devices and constructing EGL displays and surfaces from + them have been solved in various platform and implementation- + specific ways. The EGL device family of extensions offers a + standardized framework for bootstrapping EGL without the use of + any underlying "native" APIs or functionality. + + The original EGL_EXT_device_base extension combined the conceptually + separate operations of querying the underlying device used by a + given EGLDisplay and enumerating devices from scratch. It was later + identified that the former is useful even in EGL implementations + that have no need or ability to allow enumerating all the devices + available on a system. To accommodate this, the extension was + split in two. + +New Types + + None + +New Functions + + EGLBoolean eglQueryDevicesEXT(EGLint max_devices, + EGLDeviceEXT *devices, + EGLint *num_devices); + +Add the following at the beginning of section "3.2 Devices" + + "EGL devices can be enumerated before EGL is initialized. Use: + + EGLBoolean eglQueryDevicesEXT(EGLint max_devices, + EGLDeviceEXT *devices, + EGLint *num_devices); + + "to obtain a list of all supported devices in the system. On + success, EGL_TRUE is returned, and <num_devices> devices are + stored in the array pointed to by <devices>. <num_devices> will + be less than or equal to <max_devices>. If <devices> is NULL, + then <max_devices> will be ignored, no devices will be returned in + <devices>, and <num_devices> will be set to the number of + supported devices in the system. All implementations must support + at least one device. + + "On failure, EGL_FALSE is returned. An EGL_BAD_PARAMETER error is + generated if <max_devices> is less than or equal to zero unless + <devices> is NULL, or if <num_devices> is NULL." + +Remove the following paragraph from section "3.4 Display Attributes" + + "Because the EGLDeviceEXT is a property of <dpy>, any use of an + associated EGLDeviceEXT after <dpy> has been terminated gives + undefined results. Querying an EGL_DEVICE_EXT from <dpy> after a + call to eglTerminate() (and subsequent re-initialization) may + return a different value." + +Issues + + None + +Revision History: + + #1 (March 24th, 2015) James Jones + - Initial branch from EGL_EXT_device_base version #8 diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_openwf.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_openwf.txt new file mode 100644 index 0000000..2fb4d3b --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_openwf.txt @@ -0,0 +1,230 @@ +Name + + EXT_device_openwf + EXT_output_openwf + +Name Strings + + EGL_EXT_device_openwf + EGL_EXT_output_openwf + +Contributors + + Daniel Kartch + James Jones + Christopher James Halse Rogers + +Contacts + + Daniel Kartch, NVIDIA (dkartch 'at' nvidia.com) + +Status + + Complete + +Version + + Version 5 - January 21, 2016 + +Number + + EGL Extension #80 + +Extension Type + + EGL device extension for EGL_EXT_device_openwf + + EGL display extension for EGL_EXT_output_openwf + +Dependencies + + EGL_EXT_device_openwf requires EGL_EXT_device_base. + + EGL_EXT_output_openwf requires EGL_EXT_output_base. + + Both require OpenWF Display + + EGL_EXT_device_openwf interacts with EGL_EXT_platform_device + + An EGLDisplay supporting EGL_EXT_output_openwf must be associated + with an EGLDevice supporting EGL_EXT_device_openwf. + +Overview + + Increasingly, EGL and its client APIs are being used in place of + "native" rendering APIs to implement the basic graphics + functionality of native windowing systems. This creates demand + for a method to initialize EGL displays and surfaces directly on + top of native GPU or device objects rather than native window + system objects. The mechanics of enumerating the underlying + native devices and constructing EGL displays and surfaces from + them have been solved in various platform and implementation- + specific ways. The EGL device family of extensions offers a + standardized framework for bootstrapping EGL without the use of + any underlying "native" APIs or functionality. + + These extensions define how to map device and output handles between + EGL and OpenWF Display. An EGL implementation which provides these + extensions must have access to sufficient knowledge of the OpenWF + implementation to be able to perform these mappings. No requirements + are imposed on how this information is obtained, nor does this + support have any implications for how EGL devices and outputs are + implemented. An implementation which supports these extensions may + support other low level device interfaces, such as DRM/KMS, as well. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Added by EXT_device_openwf: + + Accepted as the <attribute> parameter of eglQueryDeviceAttribEXT + + EGL_OPENWF_DEVICE_ID_EXT 0x3237 + + If EGL_EXT_platform_device is present, the following is accepted + in the <attrib_list> of eglGetPlatformDisplayEXT(). + + EGL_OPENWF_DEVICE_EXT 0x333D + + Added by EXT_output_openwf: + + Accepted in the <attrib_list> of eglGetOutputLayersEXT and as + the <attribute> parameter of eglQueryOutputLayerAttribEXT + + EGL_OPENWF_PIPELINE_ID_EXT 0x3238 + + Accepted in the <attrib_list> of eglGetOutputPortsEXT and as + the <attribute> parameter of eglQueryOutputPortAttribEXT + + EGL_OPENWF_PORT_ID_EXT 0x3239 + +New Behavior for EXT_device_openwf + + EGLDeviceEXTs may be mapped to OpenWF Display devices. + + To obtain a WFD_DEVICE_ID for an EGLDeviceEXT, call + eglQueryDeviceAtribEXT with <attribute> set to + EGL_OPENWF_DEVICE_ID_EXT. + +If EGL_EXT_platform_device is present, replace the last sentence of the +third paragraph in section 3.2 "Initialization" with the following: + + When <platform> is EGL_PLATFORM_DEVICE_EXT, the only valid attribute + name is EGL_OPENWF_DEVICE_EXT. If specified, the value must be a + WFDDevice created with the device ID returned by querying + EGL_OPENWF_DEVICE_ID_EXT from the specified EGLDevice. If the device + handle does not refer to the correct OpenWF device the behavior is + undefined. Calls to eglGetPlatformDeviceEXT() with the same values + for <platform> and <native_display> but distinct EGL_OPENWF_DEVICE_EXT + values will return separate EGLDisplays. + + EGL may require the use of the OpenWF device beyond the duration of + the call to eglGetPlatformDisplayEXT(). The application must ensure + the device handle remains valid for the lifetime of the display + returned. If no OpenWF device handle is specified and EGL requires + one, it will attempt to create the device itself. Applications + should only need to specify an OpenWF device in situations where EGL + may fail to create one itself due to an existing instance of the same + underlying device in the process. + +New Behavior for EXT_output_openwf + + OpenWF pipeline and port IDs may be used to restrict EGL output + handle searches and may be queried from EGL output handles. + + Add to Table 3.10.3.1 in EGL_EXT_output_base: + + Attribute Type Access + -------------------------- ------- ------ + EGL_OPENWF_PIPELINE_ID_EXT integer S|R + + Add to Table 3.10.3.2 in EGL_EXT_output_base: + + Attribute Type Access + -------------------------- ------- ------ + EGL_OPENWF_PORT_ID_EXT integer S|R + +Issues + + 1. Although the overview says that we do not impose any + restrictions on how the features are implemented, restrictions + in the OpenWF specification combined with the chosen interface + here do implicitly impose limitations. Specifically, the + wfdCreate* functions can only be called once to obtain OpenWF + handles. This means that an EGLDevice/Output implementation + cannot be layered on top of OpenWF without preventing the + application from calling these functions. So we must assume that + the implementation instead has some backdoor into OpenWF to + obtain the object IDs. Possible resolutions include: + a) Keep the access model as is. This assumption is a reasonable + one. + b) Flip the requirement. The EGL device/output implementation + should always create the OpenWF handles itself. We can add + queries so that the application can get these handles from + EGL. + c) Generalize this extension to support both models. The + application would have to first query EGL to determine + whether or not it owns the handles, and then be prepared to + either query them from EGL or create them itself. + d) Require the application to provide its OpenWF device handle + if it has one. + + RESOLVED: (d), though implementations are free to use (a) when + possible. + + 2. Should different values of EGL_OPENWF_DEVICE_EXT result in separate + EGLDisplays? + + RESOLVED: Yes. Consider an application made up of two independent + modules running in two independently scheduled threads. Each + module calls eglGetPlatformDisplayEXT(): + + WFDDevice wfdDev = wfdCreateDevice(WFD_DEFAULT_DEVICE_ID, NULL); + int attr1[] = { EGL_OPENWF_DEVICE_EXT, wfdDev }; + dpy1 = eglGetPlatformDisplayEXT(EGL_PLATFORM_DEVICE_EXT, + eglDev, + attr1); + + ... + + dpy2 = eglGetPlatformDisplayEXT(EGL_PLATFORM_DEVICE_EXT, + eglDev, + NULL); + + Presumably, if dpy1 == dpy2, they would both be using the same + WFDDevice for output operations internally. That would mean + output operations would likely fail if dpy2 happened to be created + before dpy1. This would be painful to debug. If dpy2 != dpy1, + failure for dpy2 would be consistent and obvious. The application + author would be required to work out a scheme to share the WFDDevice + between modules before creating EGL displays. + +Revision History: + + #5 (January 21st, 2016) James Jones + - Add EGL_OPENWF_DEVICE_EXT to resolve issue 1. + - Added possible solution (d) to issue 1, and resolve to use it. + - Added issue 2. + + #4 (August 22nd, 2014) James Jones + - Marked complete. + - Listed Daniel as the contact. + + #3 (June 5th, 2014) Daniel Kartch + - Assign enumerated values for constants. + + #2 (May 28th, 2014) Daniel Kartch + - Simplified description of new behavior based on refinements + to EGL_EXT_output_base. + + #1 (January 31st, 2014) Daniel Kartch + - Initial draft, representing a signficant reworking of + functionality previously proposed in + EGL_EXT_native_device_openwf. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_persistent_id.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_persistent_id.txt new file mode 100644 index 0000000..081a6d1 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_persistent_id.txt @@ -0,0 +1,202 @@ +Name + + EXT_device_persistent_id + +Name Strings + + EGL_EXT_device_persistent_id + +Contributors + + Kyle Brenneman, NVIDIA (kbrenneman 'at' nvidia.com) + +Contact + + Kyle Brenneman, NVIDIA (kbrenneman 'at' nvidia.com) + +Version + + Version 1 - April 19, 2021 + +Number + + EGL Extension #142 + +Extension Type + + EGL device extension + +Dependencies + + Written based on the wording of the EGL 1.5 specification. + + EGL_EXT_device_query is required. + +Overview + + Applications can query a list of EGLDeviceEXT handles, but those + handles are only valid within the process that queried them. An + application has no way, for example, to record its selection and + select the same device when run again later. + + This extension provides a vendor name and a set of UUID's, which + provide a unique, persistent identifier for EGLDeviceEXT handles. + This allows applications to find the EGLDeviceEXT for the same + device across multiple processes, and across multiple APIs. + +New Procedures and Functions + + EGLBoolean eglQueryDeviceBinaryEXT(EGLDeviceEXT device, + EGLint name, + EGLint max_size, + void *value, + EGLint *size); + +New Tokens + + Accepted by the <name> parameter of eglQueryDeviceStringEXT: + + EGL_DRIVER_NAME_EXT 0x335E + + Accepted by the <name> parameter of eglQueryDeviceBinaryEXT: + + EGL_DEVICE_UUID_EXT 0x335C + EGL_DRIVER_UUID_EXT 0x335D + +Changes to section 3.2 (Devices) + + Add the following paragraph to the description of + eglQueryDeviceStringEXT: + + EGL_DRIVER_NAME_EXT returns a string which identifies the driver + that controls the device. This string remains persistent across + multiple versions of a driver, and an application can use strcmp(3) + to compare the strings for equality. Otherwise, the contents are + implementation-defined. + + + Add to the end of section 3.2: + + To query a binary attribute for a device, use: + + EGLBoolean eglQueryDeviceBinaryEXT(EGLDeviceEXT device, + EGLint name, + EGLint max_size, + void *value, + EGLint *size); + + On success, EGL_TRUE is returned. If <value> is NULL, then + <max_size> is ignored, and the size of the attribute in bytes is + returned in <size>. + + On failure, EGL_FALSE is returned. An EGL_BAD_ATTRIBUTE error is + generated if <name> is not a valid attribute. An EGL_BAD_DEVICE_EXT + error is generated if <device> is not a valid EGLDeviceEXT. + + If <value> is not NULL, then the attribute value is returned in + <value>. At most <max_size> bytes are written. <size> returns the + number of bytes that were actually written. + + Note that the EGL_DEVICE_UUID_EXT and EGL_DRIVER_UUID_EXT attributes + are always 16-byte values, and so the application can simply use a + 16-byte buffer without needing to query the size beforehand. Future + extensions may add variable-length attributes. + + + EGL_DEVICE_UUID_EXT is a UUID that identifies a physical device, + returned as a 16-byte binary value. The device UUID uniquely + identifies a physical device, and is persistent across reboots, + processes, APIs, and (to the extent possible) driver versions. + + EGL_DEVICE_UUID_EXT may or may not be persistent across changes in + hardware configuration. Similarly, it is not guaranteed to be unique + or persistent across different (physical or virtual) computers. + + Note that EGL_DEVICE_UUID_EXT alone is not guaranteed to be unique + across all EGLDeviceEXT handles. If an EGL implementation supports + multiple drivers, and two drivers can use the same physical device, + then there will be a separate EGLDeviceEXT handle from each driver. + Both EGLDeviceEXT handles may use the same device UUID. + + In that case, an application must use EGL_DRIVER_NAME_EXT or + EGL_DRIVER_UUID_EXT to distinguish between the two EGLDeviceEXT + handles. + + + EGL_DRIVER_UUID_EXT is a UUID that identifies a driver build + in use for a device. The driver UUID is persistent across reboots, + processes, and APIs, but is not persistent across driver versions. + +Issues + + 1. Should we use UUID's or strings to identify devices? + + RESOLVED: Use UUID's for devices, plus a vendor name string to + disambiguate devices that are supported by multiple drivers. + + A device UUID and driver UUID allow an application to correlate + an EGLDeviceEXT with the same device in other APIs, such as a + VkPhysicalDevice in Vulkan. + + A UUID does not impose any additional requirements on an EGL + implementation compared to a string: If an EGL implementation + could generate a string identifier, then the implementation can + simply hash that string to generate a UUID value. + + 2. Can two EGLDeviceEXT handles have the same EGL_DEVICE_UUID_EXT? + + RESOLVED: Yes, if they correspond to the same physical device. + + The semantics of the device and driver UUID's are inherited from + Vulkan, which only requires that a device UUID be unique to a + physical device, not unique across VkPhysicalDevice handles. + + 3. Do we need the EGL_DRIVER_NAME_EXT string? + + RESOLVED: Yes, because the EGL_DEVICE_UUID_EXT alone is not + unique, and EGL_DRIVER_UUID_EXT is not persistent. + + A (EGL_DRIVER_NAME_EXT, EGL_DEVICE_UUID_EXT) pair provides a + unique, persistent identifier. + + In addition, on systems that use libglvnd, applications could + use EGL_DRIVER_NAME_EXT to match the vendor names from + GLX_EXT_libglvnd. + + 4. What happens if an application stores a device UUID, and the + hardware configuration or driver version changes? + + RESOLVED: The device UUID may become invalid, and the + application should select a new device. + + If a device is removed from a system, then there will be no + EGLDeviceEXT handle for it, and thus no device UUID for it. + + Similarly, if a device is moved within a system (e.g., plugged + into a different PCI slot), then a driver may not be able to + identify it as the same device, and so the device might get a + different UUID. + + While not a requirement, drivers should still try to keep device + UUID's persistent whenever possible, to avoid invalidating + config files. Similarly, if a device is removed or replaced, + then a driver should try to ensure that the same device UUID + does not refer to a different device. + + As an example, a driver could derive a UUID based on a PCI + vendor and device number, plus the PCI domain, bus, slot, and + function numbers: + + * The PCI device number ensures that replacing a GPU with a + different model in the same PCI slot produces a different + device UUID string. + * Using the PCI bus numbers ensures that two identical + GPU's in the same system have unique UUID's. + * The whole tuple can easily stay persistent across driver + versions. + +Revision History + + #1 (April 19, 2021) Kyle Brenneman + + - Initial draft diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_query.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_query.txt new file mode 100644 index 0000000..b976aa9 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_query.txt @@ -0,0 +1,188 @@ +Name + + EXT_device_query + +Name Strings + + EGL_EXT_device_query + +Contributors + + James Jones, NVIDIA (jajones 'at' nvidia.com) + Jamie Madill, Google (jmadill 'at' google.com) + +Contacts + + Jamie Madill, Google (jmadill 'at' google.com) + +Status + + Complete. + +Version + + Version 1 - Mar 25rd, 2015 + +Number + + EGL Extension #89 + +Extension Type + + EGL client extension + +Dependencies + + Written against the wording of EGL 1.5. + + Requires EGL 1.5 or an earlier verison of EGL with the + EGL_EXT_client_extensions extension. + +Overview + + Increasingly, EGL and its client APIs are being used in place of + "native" rendering APIs to implement the basic graphics + functionality of native windowing systems. This creates demand + for a method to access native GPU or device objects directly + rather than calling EGL or GL entry points. + + This extension defines the method for an application to query + native device objects from an EGL Display. + +New Types + + This is the type of a handle that represents an EGLDeviceEXT + object. + + typedef void* EGLDeviceEXT; + + If EGL 1.5 is not supported, the following type is added, as + defined in the EGL 1.5 specification: + + typedef intptr_t EGLAttrib; + +New Functions + + EGLBoolean eglQueryDeviceAttribEXT(EGLDeviceEXT device, + EGLint attribute, + EGLAttrib *value); + + const char *eglQueryDeviceStringEXT(EGLDeviceEXT device, + EGLint name); + + EGLBoolean eglQueryDisplayAttribEXT(EGLDisplay dpy, + EGLint attribute, + EGLAttrib *value); + +New Tokens + + Functions with a return type of EGLDeviceEXT will return this + value on failure: + + EGL_NO_DEVICE_EXT ((EGLDeviceEXT)0) + + This error value will be generated by functions that take an + EGLDeviceEXT object as a parameter: + + EGL_BAD_DEVICE_EXT 0x322B + + Accepted by the <attribute> parameter of + eglQueryDisplayAttribEXT: + + EGL_DEVICE_EXT 0x322C + +Add a new section "2.1.2 Devices" after "2.1.1 Scalar Types" + + All EGL operations occur on an EGLDeviceEXT. However, devices + themselves expose no functionality. They are simple abstract + objects that exist only for the sake of enumeration and + defining a namespace. + +Modify the last sentence of section "2.1.3" Displays" to read: + + Besides devices, objects are always specified by the combination + of an EGLDisplay parameter with a parameter representing the + handle of the object. + +Add a new extension type to the list in section "2.8 Extensions" + + Device Extensions + A *device extension* adds functionality to an individual + EGLDeviceEXT. Different instances of EGLDeviceEXT may support + different sets of device extensions + +Add a new error to section "3.1 Errors" + + EGL_BAD_DEVICE_EXT + An EGLDeviceEXT argument does not refer to a valid + EGLDeviceEXT. Any command taking an EGLDeviceEXT parameter + may generate this error. + +Add a section "3.2 Devices" after "3.1 Errors" + + To query the properties of a device, use: + + EGLBoolean eglQueryDeviceAttribEXT(EGLDeviceEXT device, + EGLint attribute, + EGLAttrib *value); + + On success, EGL_TRUE is returned and the requested attribute value + is returned in <value>. Currently there are no valid values of + <attribute> defined. + + On failure, EGL_FALSE is returned. An EGL_BAD_ATTRIBUTE error is + generated if <attribute> is not a valid attribute. An + EGL_BAD_DEVICE_EXT error is generated if <device> is not a valid + EGLDeviceEXT. + + const char *eglQueryDeviceStringEXT(EGLDeviceEXT device, + EGLint name); + + returns a pointer to a static, zero-terminated string describing + some aspect of the specified EGLDeviceEXT. <name> must be + EGL_EXTENSIONS. + + The EGL_EXTENSIONS string describes which device extensions are + supported by <device>. The string is of the same format specified + for display and client extension strings in section 3.4. Note that + device extensions are properties of the device, and are distinct + from other extension strings. + + On failure, NULL is returned. An EGL_BAD_DEVICE_EXT error is + generated if <device> is not a valid EGLDeviceEXT. An + EGL_BAD_PARAMETER error is generated if <name> is not one of the + values described above. + +Add a section "3.4 Display Attributes" after "3.3 EGL Versioning" + + To query attributes of an initialized display, use: + + EGLBoolean eglQueryDisplayAttribEXT(EGLDisplay dpy, + EGLint name, + EGLAttrib *value); + + On success, EGL_TRUE is returned. If <name> is EGL_DEVICE_EXT, + the EGLDeviceEXT associated with <dpy> is returned in <value>. + All displays have an associated EGLDeviceEXT, regardless of how + they were created. A successful query of EGL_DEVICE_EXT will + never return EGL_NO_DEVICE_EXT. + + On failure, EGL_FALSE is returned. An EGL_NOT_INITIALIZED error + is generated if EGL is not initialized for <dpy>. An + EGL_BAD_ATTRIBUTE error is generated if <name> is not a valid + value. + + Because the EGLDeviceEXT is a property of <dpy>, any use of an + associated EGLDeviceEXT after <dpy> has been terminated gives + undefined results. Querying an EGL_DEVICE_EXT from <dpy> after a + call to eglTerminate() (and subsequent re-initialization) may + return a different value. + +Issues + + None. + +Revision History: + + #1 (Mar 25rd, 2015) Jamie Madill + - Initial Draft based on EGL_EXT_device_base diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_query_name.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_query_name.txt new file mode 100644 index 0000000..bb2be91 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_device_query_name.txt @@ -0,0 +1,104 @@ +Name + + EXT_device_query_name + +Name Strings + + EGL_EXT_device_query_name + +Contributors + + Kyle Brenneman, NVIDIA (kbrenneman 'at' nvidia.com) + Daniel Kartch, NVIDIA (dkartch 'at' nvidia.com) + +Contact + + Kyle Brenneman, NVIDIA (kbrenneman 'at' nvidia.com) + +Status + + Complete + +Version + + Version 1 - June 12, 2020 + +Number + + EGL Extension #140 + +Extension Type + + EGL device extension + +Dependencies + + Written based on the wording of the EGL 1.5 specification. + + EGL_EXT_device_query is required. + +Overview + + The EGL_EXT_device_enumeration and EGL_EXT_device_query extensions + provide a list of devices and a list of extensions, but lacks a way + to find a name for a device that an application can present to a + user. + + This extension adds two new strings that an application can query to + find human-readable names. + +New Types + + None + +New Functions + + None + +New Tokens + + Accepted by the <name> parameter of eglQueryDeviceStringEXT: + + EGL_RENDERER_EXT 0x335F + +New Device Queries + + eglQueryDeviceStringEXT accepts two new attributes. + + EGL_VENDOR and EGL_RENDERER_EXT return a human-readable name for the + vendor and device, respectively. + + The format of the EGL_VENDOR and EGL_RENDERER strings is + implementation-dependent. + + The EGL_VENDOR string for an EGLDeviceEXT is not required to match + the EGL_VENDOR string for an EGLDisplay or the GL_VENDOR string for + a context. Similarly, the EGL_RENDERER string is not required to + match the GL_RENDERER string for a context. + +Issues + + 1. Do we need a device query, instead of just creating an + EGLDisplay and calling eglQueryString? + + RESOLVED: Yes, a device-level query is useful, because some + devices might not be usable with EGL_EXT_platform_device. This + is especially true on systems where different devices are + handled by different drivers. + + 2. If an application creates an EGLDisplay from an EGLDevice, + are the EGL_VENDOR strings required to match? + + RESOLVED: No. Some implementations might not load a driver until + eglInitialize, and so might have a different or more specific + EGL_VENDOR string associated with an EGLDisplay than with an + EGLDeviceEXT. In addition, an implementation might select a + driver to use based on other parameters in + eglGetPlatformDisplay. + +Revision History + + #1 (June 12, 2020) Kyle Brenneman + + - Initial draft + diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_explicit_device.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_explicit_device.txt new file mode 100644 index 0000000..2ba8834 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_explicit_device.txt @@ -0,0 +1,136 @@ +Name + + EXT_explicit_device + +Name Strings + + EGL_EXT_explicit_device + +Contributors + + Adam Jackson + Nicolai Haehnle + Daniel Stone + Kyle Brenneman + +Contacts + + Adam Jackson <ajax@redhat.com> + +Status + + Complete + +Version + + Version 3, 2022-04-21 + +Number + + EGL Extension #148 + +Extension Type + + EGL client extension + +Dependencies + + Requires EGL_EXT_platform_base and EGL_EXT_device_enumeration. + + EGL_EXT_platform_device trivially interacts with this extension. + + This extension is written against the EGL 1.5 Specification. + +Overview + + A system may support rendering with multiple devices for the same + windowing system. In that case, an EGL implementation must select a + default device based on the native display. + + This extension allows an application to explicitly request a device + to use for rendering instead of the implementation's default. + + This differs from EGL_EXT_platform_device in that + EGL_EXT_platform_device uses an EGLDeviceEXT instead of a native + display. Thus, EGL_EXT_platform_device allows offscreen rendering + to a pbuffer or FBO, but it does not require or use a windowing + system, and thus does not allow pixmap or window surfaces. + + Using EGL_EXT_explicit_device with EGL_MESA_platform_surfaceless is + functionally identical to EGL_EXT_platform_device. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + None + +Additions to the EGL Specification + + None + +New Behavior + + If EGL_DEVICE_EXT is specified as an attribute for + eglGetPlatformDisplay, the value of the attribute is interpreted as + an EGLDeviceEXT as returned by eglQueryDevicesEXT. + + If the EGL_DEVICE_EXT attribute is EGL_NO_DEVICE_EXT, then the + implementation will select a device automatically, as it would + normally. + + If the EGL_DEVICE_EXT attribute is not EGL_NO_DEVICE_EXT, then the + implementation will use the specified device for rendering. If the + EGL_DEVICE_EXT attribute does not name a valid EGLDeviceEXT, then + EGL_BAD_DEVICE_EXT is generated. + + An implementation might not support all devices for all native + displays. If the device and native display are not compatible for + any reason, then EGL_BAD_MATCH is generated. + + If EGL_EXT_platform_device is supported, passing EGL_DEVICE_EXT as an + attribute to eglGetPlatformDisplay(EGL_PLATFORM_DEVICE_EXT) generates + EGL_BAD_ATTRIBUTE. + +Issues + + 1. Should we have a separate function to query whether a device is + compatible with a native display? + + RESOLVED: No. A separate query might require duplicating a lot of + the work that eglGetPlatformDisplay and eglInitialize would do, + which could be very slow. + + 2. If an implementation can't support a device with a particular + native display, then should it fail in eglGetPlatformDisplay, or + can it defer any compatibility checks until eglInitialize? + + RESOLVED: eglGetPlatformDisplay must check for compatibility and + should fail if the device and native display are not supported. + + Without a separate function to check for compatibility, the only + way for an application to know which devices can work with a + native display is to try to use each device and see if it gets an + error. If the error is in eglInitialize, then an application + would have to create (and leak) a bunch of EGLDisplay handles + that it never intends to use. + +Revision History + + Version 3, 2022-04-21 (Kyle Brenneman) + - Require eglGetPlatformDisplay (instead of eglInitialize) check + whether the device is supported with the native display. + + Version 2, 2017-08-08 (Adam Jackson) + - Renamed from MESA_platform_device to EXT_explicit_device + - Make it an error to use this new attribute in conjunction with + EGL_EXT_platform_device + + Version 1, 2017-07-14 (Adam Jackson) + - Initial version diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_gl_colorspace_bt2020_linear.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_gl_colorspace_bt2020_linear.txt new file mode 100644 index 0000000..37eb6ba --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_gl_colorspace_bt2020_linear.txt @@ -0,0 +1,175 @@ +Name + + EXT_gl_colorspace_bt2020 + +Name Strings + + EGL_EXT_gl_colorspace_bt2020_linear + EGL_EXT_gl_colorspace_bt2020_pq + +Contributors + + Tom Cooksey + Andrew Garrard + Jesse Hall + Mathias Heyer + Lauri Hyvarinen + Adam Jackson + James Jones + Daniel Koch + Jeff Leger + Weiwan Liu + Jeff Vigil + +Contact + + Weiwan Liu (weiwliu 'at' nvidia.com) + +IP Status + + No known IP claims. + +Status + + Complete + +Version + + Version 7 - Nov 22, 2016 + +Number + + EGL Extension #107 + +Dependencies + + These extensions are written against the wording of the EGL 1.5 + specification (August 27, 2014). + + These extensions require EGL_KHR_gl_colorspace. + +Overview + + Applications may wish to take advantage of a larger color gamut in the + BT.2020 (ITU-R Recommendation BT.2020) color space. These extensions allow + applications to do so by communicating to the platform the color space the + framebuffer data is in, i.e. BT.2020 color space, as well as the encoding + of the framebuffer data, which can be either linear or PQ (Dolby Perceptual + Quantizer - SMPTE ST 2084) encoding. Applications are expected to prepare + the framebuffer data properly. + +New Procedures and Functions + + None. + +New Tokens + + Accepted as attribute values for EGL_GL_COLORSPACE by + eglCreateWindowSurface, eglCreatePbufferSurface and eglCreatePixmapSurface: + + [[ If EGL_EXT_gl_colorspace_bt2020_linear is supported ]] + + EGL_GL_COLORSPACE_BT2020_LINEAR_EXT 0x333F + + [[ If EGL_EXT_gl_colorspace_bt2020_pq is supported ]] + + EGL_GL_COLORSPACE_BT2020_PQ_EXT 0x3340 + +Modifications to the EGL 1.5 Specification + + Insert below text in the 3rd paragraph on page 33 in 3.5.1 "Creating On- + Screen Rendering Surfaces, before "The default value of EGL_GL_COLORSPACE + is EGL_GL_COLORSPACE_LINEAR.": + + [[ If EGL_EXT_gl_colorspace_bt2020_linear is supported ]] + + If its value is EGL_GL_COLORSPACE_BT2020_LINEAR_EXT, then a linear BT.2020 + color space is assumed, with a corresponding GL_FRAMEBUFFER_ATTACHMENT_- + COLOR_ENCODING value of GL_LINEAR. + + [[ If EGL_EXT_gl_colorspace_bt2020_pq is supported ]] + + If its value is EGL_GL_COLORSPACE_BT2020_PQ_EXT, then a non-linear, PQ + encoded BT.2020 color space is assumed, with a corresponding GL_FRAMEBUFFER- + _ATTACHMENT_COLOR_ENCODING value of GL_LINEAR, as neither OpenGL nor OpenGL + ES supports PQ framebuffers. Applications utilizing this option need to + ensure that PQ encoding is performed on the application side. + + Modify the 4th paragraph on the same page: + + Note that the EGL_GL_COLORSPACE_SRGB attribute is used only by OpenGL and + OpenGL ES contexts supporting sRGB framebuffers. EGL itself does not + distinguish multiple colorspace models. Refer to the "sRGB Conversion" + sections of the OpenGL 4.4 and OpenGL ES 3.0 specifications for more + information. + + Add a paragraph after the 4th paragraph above: + + [[ If EGL_EXT_gl_colorspace_bt2020_linear is supported ]] + + When using a floating-point EGL surface with EGL_GL_COLORSPACE_BT2020_- + LINEAR_EXT, the output values in the display-referred range of [0.0, 1.0] + correspond to a luminance range of 0 to 80 nits, which is the same luminance + range for sRGB. To achieve a larger dynamic range of 0 to 10000 nits, which + is the same range for PQ, the display-referred output values can go beyond + 1.0 and to a range of [0.0, 125.0], where 0.0 corresponds to 0 nit and 125.0 + corresponds to 10000 nits. + + [[ If EGL_EXT_gl_colorspace_bt2020_pq is supported ]] + + When using a floating-point EGL surface with EGL_GL_COLORSPACE_BT2020_PQ_- + EXT, to achieve the luminance range of 0 to 10000 nits (candela per square + meter) as defined by the SMPTE 2084 standard, applications can output values + in a display-referred range of [0.0, 1.0], where 0.0 corresponds to 0 nit + and 1.0 corresponds to 10000 nits. + +Errors + + Modify below error in the "Errors" section on page 34: + + "If config does not support the OpenVG colorspace or alpha format at- + tributes specified in attrib list (as defined for eglCreatePlatformWindow- + Surface), an EGL_BAD_MATCH error is generated." + + To include OpenGL colorspace as well: + + "If config does not support the OpenGL colorspace, the OpenVG colorspace or + alpha format attributes specified in attrib list (as defined for eglCreate- + PlatformWindowSurface), an EGL_BAD_MATCH error is generated." + +Issues + + 1. When creating an EGL surface, what happens when the specified colorspace + is not compatible with or supported by the EGLConfig? + + RESOLVED: There is currently no way to query the compatibility of a + EGLConfig and colorspace pair. So the only option is to define an error + case similar to that of OpenVG colorspace, i.e. if config does not + support the colorspace specified in attrib list (as defined for egl- + CreateWindowSurface, eglCreatePbufferSurface and eglCreatePixmapSurface), + an EGL_BAD_MATCH error is generated. + +Revision History + + Version 1, 2016/04/27 + - Internal revisions + + Version 2, 2016/05/20 + - Rename to EXT + + Version 3, 2016/05/25 + - Add issues + + Version 4, 2016/06/06 + - Split up the extension and put each colorspace option into an individual + extension + + Version 5, 2016/06/17 + - Correct the meaning of the data from scene-referred to display-referred + + Version 6, 2016/10/27 + - Mark issue #1 as "RESOLVED" and add an error case + + Version 7, 2016/11/22 + - Change status to complete + diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_gl_colorspace_display_p3.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_gl_colorspace_display_p3.txt new file mode 100644 index 0000000..32e7ebc --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_gl_colorspace_display_p3.txt @@ -0,0 +1,137 @@ +Name + + EXT_gl_colorspace_display_p3 + +Name Strings + + EGL_EXT_gl_colorspace_display_p3_linear + EGL_EXT_gl_colorspace_display_p3 + +Contributors + + Courtney Goeltzenleuchter + Jesse Hall + +Contact + + Courtney Goeltzenleuchter (courtneygo 'at' google.com) + +IP Status + + No known IP claims. + +Status + + Draft + +Version + + Version 2 - Oct 4, 2018 + +Number + + EGL Extension #118 + +Extension Type + + EGL display extension + +Dependencies + + These extensions are written against the wording of the EGL 1.5 + specification (August 27, 2014). + + These extensions require EGL_KHR_gl_colorspace. + +Overview + + Applications that want to use the Display-P3 color space (DCI-P3 primaries + and linear or sRGB-like transfer function) can use this extension to + communicate to the platform that framebuffer contents represent colors in + the Display-P3 color space. + The application is responsible for producing appropriate framebuffer + contents, but will typically use built-in sRGB encoding in OpenGL and OpenGL + ES to accomplish this. + +New Procedures and Functions + + None. + +New Tokens + + Accepted as attribute values for EGL_GL_COLORSPACE by + eglCreateWindowSurface, eglCreatePbufferSurface and eglCreatePixmapSurface: + + [[ If EGL_EXT_gl_colorspace_display_p3_linear is supported ]] + + EGL_GL_COLORSPACE_DISPLAY_P3_LINEAR_EXT 0x3362 + + [[ If EGL_EXT_gl_colorspace_display_p3 is supported ]] + + EGL_GL_COLORSPACE_DISPLAY_P3_EXT 0x3363 + +Modifications to the EGL 1.5 Specification + + Insert below text in the 3rd paragraph on page 33 in 3.5.1 "Creating On- + Screen Rendering Surfaces, before "The default value of EGL_GL_COLORSPACE + is EGL_GL_COLORSPACE_LINEAR.": + + [[ If EGL_EXT_gl_colorspace_display_p3_linear is supported ]] + + If its value is EGL_GL_COLORSPACE_DISPLAY_P3_LINEAR_EXT, then a linear + Display-P3 color space is assumed, with a corresponding + GL_FRAMEBUFFER_ATTACHMENT_COLOR_ENCODING value of GL_LINEAR. + + [[ If EGL_EXT_gl_colorspace_display_p3 is supported ]] + + If its value is EGL_GL_COLORSPACE_DISPLAY_P3_EXT, then a non-linear, sRGB + encoded Display-P3 color space is assumed, with a corresponding GL_FRAME- + BUFFER_ATTACHMENT_COLOR_ENCODING value of GL_SRGB. + Only OpenGL and OpenGL ES contexts which support sRGB rendering must + respect requests for EGL_GL_COLORSPACE_SRGB_KHR, and only to sRGB + formats supported by the context (normally just SRGB8). + + Modify the 4th paragraph on the same page: + + Note that the EGL_GL_COLORSPACE_SRGB attribute is used only by OpenGL and + OpenGL ES contexts supporting sRGB framebuffers. EGL itself does not + distinguish multiple colorspace models. Refer to the "sRGB Conversion" + sections of the OpenGL 4.4 and OpenGL ES 3.0 specifications for more + information. + +Errors + + Modify below error in the "Errors" section on page 34: + + "If config does not support the OpenVG colorspace or alpha format at- + tributes specified in attrib list (as defined for eglCreatePlatformWindow- + Surface), an EGL_BAD_MATCH error is generated." + + To include OpenGL colorspace as well: + + "If config does not support the OpenGL colorspace, the OpenVG colorspace or + alpha format attributes specified in attrib list (as defined for eglCreate- + PlatformWindowSurface), an EGL_BAD_MATCH error is generated." + +Issues + + 1. Removed section talking about HDR features, e.g. luminance > 80nits. + Do we want to keep that here in anticipation of HDR support in the future? + + 2. When creating an EGL surface, what happens when the specified colorspace + is not compatible with or supported by the EGLConfig? + + RESOLVED: There is currently no way to query the compatibility of a + EGLConfig and colorspace pair. So the only option is to define an error + case similar to that of OpenVG colorspace, i.e. if config does not + support the colorspace specified in attrib list (as defined for egl- + CreateWindowSurface, eglCreatePbufferSurface and eglCreatePixmapSurface), + an EGL_BAD_MATCH error is generated. + +Revision History + + Version 1, 2017/03/22 + - Internal revisions + + Version 2, 2018/10/04 + - Fix typo to correct extension reference diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_gl_colorspace_display_p3_passthrough.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_gl_colorspace_display_p3_passthrough.txt new file mode 100644 index 0000000..f0223a6 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_gl_colorspace_display_p3_passthrough.txt @@ -0,0 +1,139 @@ +Name + + EXT_gl_colorspace_display_p3_passthrough + +Name Strings + + EGL_EXT_gl_colorspace_display_p3_passthrough + +Contributors + + Chris Forbes + Courtney Goeltzenleuchter + +Contact + + Courtney Goeltzenleuchter (courtneygo 'at' google.com) + +IP Status + + No known IP claims. + +Status + + Draft + +Version + + Version 1 - Dec 4, 2018 + +Number + + EGL Extension #130 + +Extension Type + + EGL display extension + +Dependencies + + This extension is written against the wording of the EGL 1.5 + specification (August 27, 2014). + + This extension requires EGL_KHR_gl_colorspace. + +Overview + + Applications that want to use the Display-P3 color space (DCI-P3 primaries + with sRGB-like transfer function) can use this extension to + communicate to the platform that framebuffer contents represent colors in + the non-linear Display-P3 color space. + The application is responsible for producing appropriate framebuffer + contents. An application would want to use this extension rather than + EGL_EXT_gl_colorspace_display_p3 if they apply the sRGB transfer function + themselves and do not need the HW to do it. + +New Procedures and Functions + + None. + +New Tokens + + Accepted as attribute values for EGL_GL_COLORSPACE by + eglCreateWindowSurface, eglCreatePbufferSurface and eglCreatePixmapSurface: + + [[ If EGL_EXT_gl_colorspace_display_p3_linear is supported ]] + + EGL_GL_COLORSPACE_DISPLAY_P3_PASSTHROUGH_EXT 0x3490 + +Modifications to the EGL 1.5 Specification + + Insert below text in the 3rd paragraph on page 33 in 3.5.1 "Creating On- + Screen Rendering Surfaces, before "The default value of EGL_GL_COLORSPACE + is EGL_GL_COLORSPACE_LINEAR.": + + [[ If EGL_EXT_gl_colorspace_display_p3_passthrough is supported ]] + + If its value is EGL_GL_COLORSPACE_DISPLAY_P3_PASSTHROUGH_EXT, then a + non-linear, sRGB encoded Display-P3 color space is assumed, with a + corresponding GL_FRAMEBUFFER_ATTACHMENT_COLOR_ENCODING value of GL_LINEAR. + The application is responsible for applying the appropriate transfer + function when writing and reading pixels. + + Insert below text after the 4th paragraph on the same page: + + Note that the EGL_GL_COLORSPACE_DISPLAY_P3_PASSTHROUGH_EXT attribute + indicates that a colorspace of Display P3 will be communicated to the + Window system. While EGL itself is color space agnostic, the surface + will eventually be presented to a display device with specific color + reproduction characteristics. If any color space transformations are + necessary before an image can be displayed, the color space of the + presented image must be known to the window system. + +Errors + + Modify below error in the "Errors" section on page 34: + + "If config does not support the OpenVG colorspace or alpha format at- + tributes specified in attrib list (as defined for eglCreatePlatformWindow- + Surface), an EGL_BAD_MATCH error is generated." + + To include OpenGL colorspace as well: + + "If config does not support the OpenGL colorspace, the OpenVG colorspace or + alpha format attributes specified in attrib list (as defined for eglCreate- + PlatformWindowSurface), an EGL_BAD_MATCH error is generated." + +Issues + + 1. When creating an EGL surface, what happens when the specified colorspace + is not compatible with or supported by the EGLConfig? + + RESOLVED: There is currently no way to query the compatibility of a + EGLConfig and colorspace pair. So the only option is to define an error + case similar to that of OpenVG colorspace, i.e. if config does not + support the colorspace specified in attrib list (as defined for egl- + CreateWindowSurface, eglCreatePbufferSurface and eglCreatePixmapSurface), + an EGL_BAD_MATCH error is generated. + + 2. Why the new enum instead of DISPLAY_P3_EXT + EXT_srgb_write_control? + + RESOLVED: + We want to rely on "surface state" rather than a "context state", e.g. + EXT_srgb_write_control is global where we only want behavior to apply to + specific surface. + + 3. Should sRGB framebuffer support affect the pixel path? + + RESOLVED: No. + + sRGB rendering is defined by GL/GLES. Specifically, glReadPixels and + other pixel paths operations are not affected by sRGB rendering. But + glBlitFramebuffer is. Though, of course, if this extension were to + apply it would be a no-op. + +Revision History + + Version 1, 2018/12/04 + - Internal revisions + diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_gl_colorspace_scrgb.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_gl_colorspace_scrgb.txt new file mode 100644 index 0000000..708fb17 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_gl_colorspace_scrgb.txt @@ -0,0 +1,130 @@ +Name + + EXT_gl_colorspace_scrgb + +Name Strings + + EGL_EXT_gl_colorspace_scrgb + +Contributors + + Courtney Goeltzenleuchter + Lauri Hyvarinen + Weiwan Liu + Arun Swain + +Contact + + Courtney Goeltzenleuchter (courtneygo 'at' google.com) + +IP Status + + No known IP claims. + +Status + + Draft + +Version + + Version 2 - August 25, 2017 + +Number + + EGL Extension #119 + +Dependencies + + This extension is written against the wording of the EGL 1.5 specification + (August 27, 2014). + + This extension requires EGL_KHR_gl_colorspace and EGL_EXT_pixel_format_- + float, and interacts with EGL_EXT_surface_SMPTE2086_metadata. This extension + is closely related to EGL_EXT_gl_colorspace_scrgb_linear. + +Overview + + This extension provides an extended sRGB (also called scRGB) color + space option for applications to choose from when creating an EGLSurface. + This extension defines the non-linear display referred scRGB color space. + It has the same white point and color primaries as sRGB, and thus is + backward-compatible with sRGB. Refer to the IEC 61966-2-2:2003 standard + for details on scRGB color space. + + This extension chooses to use floating-point formats for scRGB color space. + For each color channel, the floating-point values of 0.0 and 1.0 still + correspond to sRGB chromaticities and luminance levels. However, scRGB + space allows for color values beyond the range of [0.0, 1.0], and can thus + achieve a larger color volume than that of sRGB. As it is display referred, + scRGB space makes assumptions of how the floating-point color values should + map to luminance levels by the underlying display pipeline. The expected + mapping is such that a color value of (1.0, 1.0, 1.0) corresponds to a + luminance level of 80 nits on a standardized studio monitor. As the color + value per channel goes beyond 1.0 and up to ~7.83, the corresponding + luminance levels also increase to a maximum of 10000 nits. + + The application is responsible for applying the extended sRGB transfer + function to color values written to or read from a surface with a + colorspace of EGL_EXT_gl_colorspace_scrgb. + +New Procedures and Functions + + None. + +New Tokens + + Accepted as attribute values for EGL_GL_COLORSPACE by + eglCreateWindowSurface, eglCreatePbufferSurface and eglCreatePixmapSurface: + + EGL_GL_COLORSPACE_SCRGB_EXT 0x3351 + +Modifications to the EGL 1.5 Specification + + Insert below text in the 3rd paragraph on page 33 in 3.5.1 "Creating On- + Screen Rendering Surfaces", before "The default value of EGL_GL_COLORSPACE + is EGL_GL_COLORSPACE_LINEAR.": + + [[ If EGL_EXT_gl_colorspace_scrgb is supported ]] + + If its value is EGL_GL_COLORSPACE_SCRGB_EXT, then a non-linear scRGB + color space is assumed. with a corresponding GL_FRAMEBUFFER_ATTACHMENT_- + COLOR_ENCODING value of GL_LINEAR as neither OpenGL nor OpenGL ES + supports framebuffers using an scRGB transfer function. + The application is responsible for applying the appropriate extended + sRGB transfer function when reading or writing to this buffer. + scRGB is defined to use the same primaries and white-point as sRGB. + See IEC 61966-2-2:2003 for details. + + Add two paragraphs after the 4th paragraph above: + + When using a floating-point EGL surface with EGL_GL_COLORSPACE_SCRGB_EXT, + the display-referred values in the range of (0.0, 0.0, 0.0) to + (1.0, 1.0, 1.0) correspond to a luminance range of 0 to 80 nits, which is + the same luminance range for sRGB. To achieve a larger dynamic range of up + to 10000 nits, the output values can go beyond 1.0 and to a range of + [0.0, ~7.83] for each channel. + + The effective color gamut and luminance range of the content that extend + beyond those of sRGB may be described via EGL_EXT_surface_SMPTE2086_metadata. + It is highly recommended to supply such metadata, so the display pipeline + may use this information to transform the the colors in a manner that + attempts to preserve the creative intent of the color data. + + In the "Errors" section on page 34 in 3.5.1 "Creating On Screen Rendering + Surfaces", change the 3rd error definition to: + + * If config does not support the OpenGL colorspace, the OpenVG colorspace or + alpha format attributes specified in attrib list (as defined for + eglCreatePlatformWindowSurface), an EGL_BAD_MATCH error is generated. + +Issues + + * Clarifications on the scRGB colorspace extensions + +Revision History + + Version 1, 2017/06/21 + - Initial draft + + Version 2, 2017/08/25 + - Clarify definition of color space diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_gl_colorspace_scrgb_linear.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_gl_colorspace_scrgb_linear.txt new file mode 100644 index 0000000..084f4a0 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_gl_colorspace_scrgb_linear.txt @@ -0,0 +1,127 @@ +Name + + EXT_gl_colorspace_scrgb_linear + +Name Strings + + EGL_EXT_gl_colorspace_scrgb_linear + +Contributors + + Courtney Goeltzenleuchter + Lauri Hyvarinen + Weiwan Liu + Arun Swain + +Contact + + Weiwan Liu (weiwliu 'at' nvidia.com) + +IP Status + + No known IP claims. + +Status + + Complete + +Version + + Version 4 - August 25, 2017 + +Number + + EGL Extension #108 + +Dependencies + + This extension is written against the wording of the EGL 1.5 specification + (August 27, 2014). + + This extension requires EGL_KHR_gl_colorspace and EGL_EXT_pixel_format_- + float, and interacts with EGL_EXT_surface_SMPTE2086_metadata. This extension + is closely related to the EGL_EXT_gl_colorspace_scrgb. + +Overview + + This extension provides an extended sRGB (also called scRGB) color + space option for applications to choose from when creating an EGLSurface. + This extension defines the linear display referred scRGB color space. + It has the same white point and color primaries as sRGB, and thus is + backward-compatible with sRGB. Refer to the IEC 61966-2-2:2003 standard + for details on scRGB color space. + + This extension chooses to use floating-point formats for scRGB color space. + For each color channel, the floating-point values of 0.0 and 1.0 still + correspond to sRGB chromaticities and luminance levels. However, scRGB + space allows for color values beyond the range of [0.0, 1.0], and can thus + achieve a larger color volume than that of sRGB. As it is display referred, + scRGB space makes assumptions of how the floating-point color values should + map to luminance levels by the underlying display pipeline. The expected + mapping is such that a color value of (1.0, 1.0, 1.0) corresponds to a + luminance level of 80 nits on a standardized studio monitor. As the color + value per channel goes beyond 1.0 and up to 125.0, the corresponding + luminance levels also increase linearly to a maximum of 10000 nits. + +New Procedures and Functions + + None. + +New Tokens + + Accepted as attribute values for EGL_GL_COLORSPACE by + eglCreateWindowSurface, eglCreatePbufferSurface and eglCreatePixmapSurface: + + EGL_GL_COLORSPACE_SCRGB_LINEAR_EXT 0x3350 + +Modifications to the EGL 1.5 Specification + + Insert below text in the 3rd paragraph on page 33 in 3.5.1 "Creating On- + Screen Rendering Surfaces", before "The default value of EGL_GL_COLORSPACE + is EGL_GL_COLORSPACE_LINEAR.": + + If its value is EGL_GL_COLORSPACE_SCRGB_LINEAR_EXT, then a linear scRGB + color space is assumed, with a corresponding GL_FRAMEBUFFER_ATTACHMENT_- + COLOR_ENCODING value of GL_LINEAR. scRGB is defined to use the same + primaries and white-point as sRGB. See IEC 61966-2-2:2003 for details. + + Add two paragraphs after the 4th paragraph above: + + When using a floating-point EGL surface with EGL_GL_COLORSPACE_SCRGB_- + LINEAR_EXT, the display-referred values in the range of (0.0, 0.0, 0.0) to + (1.0, 1.0, 1.0) correspond to a luminance range of 0 to 80 nits, which is + the same luminance range for sRGB. To achieve a larger dynamic range of up + to 10000 nits, the output values can go beyond 1.0 and to a range of + [0.0, 125.0] for each channel. + + The effective color gamut and luminance range of the content that extend + beyond those of sRGB may be described via EGL_EXT_surface_SMPTE2086_metadata. + It is highly recommended to supply such metadata, so the display pipeline + may use this information to transform the colors in a manner that + attempts to preserve the creative intent of the color data. + + In the "Errors" section on page 34 in 3.5.1 "Creating On Screen Rendering + Surfaces", change the 3rd error definition to: + + * If config does not support the OpenGL colorspace, the OpenVG colorspace or + alpha format attributes specified in attrib list (as defined for + eglCreatePlatformWindowSurface), an EGL_BAD_MATCH error is generated. + +Issues + + * Clarifications on the scRGB colorspace extensions + +Revision History + + Version 1, 2016/10/21 + - Initial draft + + Version 2, 2016/11/18 + - Add reference to IEC 61966-2-2:2003 standard and minor wording changes + + Version 3, 2016/11/22 + - Change status to complete + + Version 4, 2017/08/25 + - Clarifications on the definition of scRGB colorspace + diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_image_dma_buf_import.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_image_dma_buf_import.txt new file mode 100644 index 0000000..17350d7 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_image_dma_buf_import.txt @@ -0,0 +1,428 @@ +Name + + EXT_image_dma_buf_import + +Name Strings + + EGL_EXT_image_dma_buf_import + +Contributors + + Jesse Barker + Rob Clark + Tom Cooksey + +Contacts + + Jesse Barker (jesse 'dot' barker 'at' linaro 'dot' org) + Tom Cooksey (tom 'dot' cooksey 'at' arm 'dot' com) + +Status + + Complete. + +Version + + Version 7, December 13, 2013 + +Number + + EGL Extension #53 + +Dependencies + + EGL 1.2 is required. + + EGL_KHR_image_base is required. + + The EGL implementation must be running on a Linux kernel supporting the + dma_buf buffer sharing mechanism. + + This extension is written against the wording of the EGL 1.2 Specification. + +Overview + + This extension allows creating an EGLImage from a Linux dma_buf file + descriptor or multiple file descriptors in the case of multi-plane YUV + images. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted by the <target> parameter of eglCreateImageKHR: + + EGL_LINUX_DMA_BUF_EXT 0x3270 + + Accepted as an attribute in the <attrib_list> parameter of + eglCreateImageKHR: + + EGL_LINUX_DRM_FOURCC_EXT 0x3271 + EGL_DMA_BUF_PLANE0_FD_EXT 0x3272 + EGL_DMA_BUF_PLANE0_OFFSET_EXT 0x3273 + EGL_DMA_BUF_PLANE0_PITCH_EXT 0x3274 + EGL_DMA_BUF_PLANE1_FD_EXT 0x3275 + EGL_DMA_BUF_PLANE1_OFFSET_EXT 0x3276 + EGL_DMA_BUF_PLANE1_PITCH_EXT 0x3277 + EGL_DMA_BUF_PLANE2_FD_EXT 0x3278 + EGL_DMA_BUF_PLANE2_OFFSET_EXT 0x3279 + EGL_DMA_BUF_PLANE2_PITCH_EXT 0x327A + EGL_YUV_COLOR_SPACE_HINT_EXT 0x327B + EGL_SAMPLE_RANGE_HINT_EXT 0x327C + EGL_YUV_CHROMA_HORIZONTAL_SITING_HINT_EXT 0x327D + EGL_YUV_CHROMA_VERTICAL_SITING_HINT_EXT 0x327E + + Accepted as the value for the EGL_YUV_COLOR_SPACE_HINT_EXT attribute: + + EGL_ITU_REC601_EXT 0x327F + EGL_ITU_REC709_EXT 0x3280 + EGL_ITU_REC2020_EXT 0x3281 + + Accepted as the value for the EGL_SAMPLE_RANGE_HINT_EXT attribute: + + EGL_YUV_FULL_RANGE_EXT 0x3282 + EGL_YUV_NARROW_RANGE_EXT 0x3283 + + Accepted as the value for the EGL_YUV_CHROMA_HORIZONTAL_SITING_HINT_EXT & + EGL_YUV_CHROMA_VERTICAL_SITING_HINT_EXT attributes: + + EGL_YUV_CHROMA_SITING_0_EXT 0x3284 + EGL_YUV_CHROMA_SITING_0_5_EXT 0x3285 + + +Additions to Chapter 2 of the EGL 1.2 Specification (EGL Operation) + + Add to section 2.5.1 "EGLImage Specification" (as defined by the + EGL_KHR_image_base specification), in the description of + eglCreateImageKHR: + + "Values accepted for <target> are listed in Table aaa, below. + + +-------------------------+--------------------------------------------+ + | <target> | Notes | + +-------------------------+--------------------------------------------+ + | EGL_LINUX_DMA_BUF_EXT | Used for EGLImages imported from Linux | + | | dma_buf file descriptors | + +-------------------------+--------------------------------------------+ + Table aaa. Legal values for eglCreateImageKHR <target> parameter + + ... + + If <target> is EGL_LINUX_DMA_BUF_EXT, <dpy> must be a valid display, <ctx> + must be EGL_NO_CONTEXT, and <buffer> must be NULL, cast into the type + EGLClientBuffer. The details of the image is specified by the attributes + passed into eglCreateImageKHR. Required attributes and their values are as + follows: + + * EGL_WIDTH & EGL_HEIGHT: The logical dimensions of the buffer in pixels + + * EGL_LINUX_DRM_FOURCC_EXT: The pixel format of the buffer, as specified + by drm_fourcc.h and used as the pixel_format parameter of the + drm_mode_fb_cmd2 ioctl. + + * EGL_DMA_BUF_PLANE0_FD_EXT: The dma_buf file descriptor of plane 0 of + the image. + + * EGL_DMA_BUF_PLANE0_OFFSET_EXT: The offset from the start of the + dma_buf of the first sample in plane 0, in bytes. + + * EGL_DMA_BUF_PLANE0_PITCH_EXT: The number of bytes between the start of + subsequent rows of samples in plane 0. May have special meaning for + non-linear formats. + + For images in an RGB color-space or those using a single-plane YUV format, + only the first plane's file descriptor, offset & pitch should be specified. + For semi-planar YUV formats, that first plane (plane 0) holds only the luma + samples and chroma samples are stored interleaved in a second plane (plane + 1). For fully planar YUV formats, the first plane (plane 0) continues to + hold the luma samples however the chroma samples are stored seperately in + two additional planes (plane 1 & plane 2). If present, planes 1 & 2 are + specified by the following attributes, which have the same meanings as + defined above for plane 0: + + * EGL_DMA_BUF_PLANE1_FD_EXT + * EGL_DMA_BUF_PLANE1_OFFSET_EXT + * EGL_DMA_BUF_PLANE1_PITCH_EXT + * EGL_DMA_BUF_PLANE2_FD_EXT + * EGL_DMA_BUF_PLANE2_OFFSET_EXT + * EGL_DMA_BUF_PLANE2_PITCH_EXT + + The ordering of samples within a plane is taken from the drm_fourcc + pixel_format specified for EGL_LINUX_DRM_FOURCC_EXT. For example, if + EGL_LINUX_DRM_FOURCC_EXT is set to DRM_FORMAT_NV12, the chroma plane + specified by EGL_DMA_BUF_PLANE1* contains samples in the order V, U, + whereas if EGL_LINUX_DRM_FOURCC_EXT is DRM_FORMAT_NV21, the order is U, + V. Similarly, the ordering of planes for fully-planar formats is also taken + from the pixel_format specified as EGL_LINUX_DRM_FOURCC_EXT. For example, + if EGL_LINUX_DRM_FOURCC_EXT is set to DRM_FORMAT_YUV410, the luma plane is + specified by EGL_DMA_BUF_PLANE0*, the plane containing U-samples is + specified by EGL_DMA_BUF_PLANE1* and the plane containing the V-samples is + specified by EGL_DMA_BUF_PLANE2*, whereas if EGL_LINUX_DRM_FOURCC_EXT is + set to DRM_FORMAT_YVU410, plane 1 contains the V-samples and plane 2 + contains the U-samples. + + In addition to the above required attributes, the application may also + provide hints as to how the data should be interpreted by the GL. If any of + these hints are not specified, the GL will guess based on the pixel format + passed as the EGL_LINUX_DRM_FOURCC_EXT attribute or may fall-back to some + default value. Not all GLs will be able to support all combinations of + these hints and are free to use whatever settings they choose to achieve + the closest possible match. + + * EGL_YUV_COLOR_SPACE_HINT_EXT: The color-space the data is in. Only + relevant for images in a YUV format, ignored when specified for an + image in an RGB format. Accepted values are: + EGL_ITU_REC601_EXT, EGL_ITU_REC709_EXT & EGL_ITU_REC2020_EXT. + + * EGL_YUV_CHROMA_HORIZONTAL_SITING_HINT_EXT & + EGL_YUV_CHROMA_VERTICAL_SITING_HINT_EXT: Where chroma samples are + sited relative to luma samples when the image is in a sub-sampled + format. When the image is not using chroma sub-sampling, the luma and + chroma samples are assumed to be co-sited. Siting is split into the + vertical and horizontal and is in a fixed range. A siting of zero + means the first luma sample is taken from the same position in that + dimension as the chroma sample. This is best illustrated in the + diagram below: + + (0.5, 0.5) (0.0, 0.5) (0.0, 0.0) + + + + + + + + + * + * + + x x x x + + + + + + + + + + + + + + + + + + + + + + + * + * + + x x x x + + + + + + + + + + + + + + + Luma samples (+), Chroma samples (x) Chrome & Luma samples (*) + + Note this attribute is ignored for RGB images and non sub-sampled + YUV images. Accepted values are: EGL_YUV_CHROMA_SITING_0_EXT (0.0) + & EGL_YUV_CHROMA_SITING_0_5_EXT (0.5) + + * EGL_SAMPLE_RANGE_HINT_EXT: The numerical range of samples. Only + relevant for images in a YUV format, ignored when specified for + images in an RGB format. Accepted values are: EGL_YUV_FULL_RANGE_EXT + (0-256) & EGL_YUV_NARROW_RANGE_EXT (16-235). + + + If eglCreateImageKHR is successful for a EGL_LINUX_DMA_BUF_EXT target, the + EGL will take a reference to the dma_buf(s) which it will release at any + time while the EGLDisplay is initialized. It is the responsibility of the + application to close the dma_buf file descriptors." + + + Add to the list of error conditions for eglCreateImageKHR: + + "* If <target> is EGL_LINUX_DMA_BUF_EXT and <buffer> is not NULL, the + error EGL_BAD_PARAMETER is generated. + + * If <target> is EGL_LINUX_DMA_BUF_EXT, and the list of attributes is + incomplete, EGL_BAD_PARAMETER is generated. + + * If <target> is EGL_LINUX_DMA_BUF_EXT, and the EGL_LINUX_DRM_FOURCC_EXT + attribute is set to a format not supported by the EGL, EGL_BAD_MATCH + is generated. + + * If <target> is EGL_LINUX_DMA_BUF_EXT, and the EGL_LINUX_DRM_FOURCC_EXT + attribute indicates a single-plane format, EGL_BAD_ATTRIBUTE is + generated if any of the EGL_DMA_BUF_PLANE1_* or EGL_DMA_BUF_PLANE2_* + attributes are specified. + + * If <target> is EGL_LINUX_DMA_BUF_EXT and the value specified for + EGL_YUV_COLOR_SPACE_HINT_EXT is not EGL_ITU_REC601_EXT, + EGL_ITU_REC709_EXT or EGL_ITU_REC2020_EXT, EGL_BAD_ATTRIBUTE is + generated. + + * If <target> is EGL_LINUX_DMA_BUF_EXT and the value specified for + EGL_SAMPLE_RANGE_HINT_EXT is not EGL_YUV_FULL_RANGE_EXT or + EGL_YUV_NARROW_RANGE_EXT, EGL_BAD_ATTRIBUTE is generated. + + * If <target> is EGL_LINUX_DMA_BUF_EXT and the value specified for + EGL_YUV_CHROMA_HORIZONTAL_SITING_HINT_EXT or + EGL_YUV_CHROMA_VERTICAL_SITING_HINT_EXT is not + EGL_YUV_CHROMA_SITING_0_EXT or EGL_YUV_CHROMA_SITING_0_5_EXT, + EGL_BAD_ATTRIBUTE is generated. + + * If <target> is EGL_LINUX_DMA_BUF_EXT and one or more of the values + specified for a plane's pitch or offset isn't supported by EGL, + EGL_BAD_ACCESS is generated. + + +Issues + + 1. Should this be a KHR or EXT extension? + + ANSWER: EXT. Khronos EGL working group not keen on this extension as it is + seen as contradicting the EGLStream direction the specification is going in. + The working group recommends creating additional specs to allow an EGLStream + producer/consumer connected to v4l2/DRM or any other Linux interface. + + 2. Should this be a generic any platform extension, or a Linux-only + extension which explicitly states the handles are dma_buf fds? + + ANSWER: There's currently no intention to port this extension to any OS not + based on the Linux kernel. Consequently, this spec can be explicitly written + against Linux and the dma_buf API. + + 3. Does ownership of the file descriptor pass to the EGL library? + + ANSWER: No, EGL does not take ownership of the file descriptors. It is the + responsibility of the application to close the file descriptors on success + and failure. + + 4. How are the different YUV color spaces handled (BT.709/BT.601)? + + ANSWER: The pixel formats defined in drm_fourcc.h only specify how the data + is laid out in memory. It does not define how that data should be + interpreted. Added a new EGL_YUV_COLOR_SPACE_HINT_EXT attribute to allow the + application to specify which color space the data is in to allow the GL to + choose an appropriate set of co-efficients if it needs to convert that data + to RGB for example. + + 5. What chroma-siting is used for sub-sampled YUV formats? + + ANSWER: The chroma siting is not specified by either the v4l2 or DRM APIs. + This is similar to the color-space issue (4) in that the chroma siting + doesn't affect how the data is stored in memory. However, the GL will need + to know the siting in order to filter the image correctly. While the visual + impact of getting the siting wrong is minor, provision should be made to + allow an application to specify the siting if desired. Added additional + EGL_YUV_CHROMA_HORIZONTAL_SITING_HINT_EXT & + EGL_YUV_CHROMA_VERTICAL_SITING_HINT_EXT attributes to allow the siting to + be specified using a set of pre-defined values (0 or 0.5). + + 6. How can an application query which formats the EGL implementation + supports? + + PROPOSAL: Don't provide a query mechanism but instead add an error condition + that EGL_BAD_MATCH is raised if the EGL implementation doesn't support that + particular format. + + 7. Which image formats should be supported and how is format specified? + + Seem to be two options 1) specify a new enum in this specification and + enumerate all possible formats. 2) Use an existing enum already in Linux, + either v4l2_mbus_pixelcode and/or those formats listed in drm_fourcc.h? + + ANSWER: Go for option 2) and just use values defined in drm_fourcc.h. + + 8. How can AYUV images be handled? + + ANSWER: At least on fourcc.org and in drm_fourcc.h, there only seems to be + a single AYUV format and that is a packed format, so everything, including + the alpha component would be in the first plane. + + 9. How can you import interlaced images? + + ANSWER: Interlaced frames are usually stored with the top & bottom fields + interleaved in a single buffer. As the fields would need to be displayed as + at different times, the application would create two EGLImages from the same + buffer, one for the top field and another for the bottom. Both EGLImages + would set the pitch to 2x the buffer width and the second EGLImage would use + a suitable offset to indicate it started on the second line of the buffer. + This should work regardless of whether the data is packed in a single plane, + semi-planar or multi-planar. + + If each interlaced field is stored in a separate buffer then it should be + trivial to create two EGLImages, one for each field's buffer. + + 10. How are semi-planar/planar formats handled that have a different + width/height for Y' and CbCr such as YUV420? + + ANSWER: The spec says EGL_WIDTH & EGL_HEIGHT specify the *logical* width and + height of the buffer in pixels. For pixel formats with sub-sampled Chroma + values, it should be trivial for the EGL implementation to calculate the + width/height of the Chroma sample buffers using the logical width & height + and by inspecting the pixel format passed as the EGL_LINUX_DRM_FOURCC_EXT + attribute. I.e. If the pixel format says it's YUV420, the Chroma buffer's + width = EGL_WIDTH/2 & height =EGL_HEIGHT/2. + + 11. How are Bayer formats handled? + + ANSWER: As of Linux 2.6.34, drm_fourcc.h does not include any Bayer formats. + However, future kernel versions may add such formats in which case they + would be handled in the same way as any other format. + + 12. Should the spec support buffers which have samples in a "narrow range"? + + Content sampled from older analogue sources typically don't use the full + (0-256) range of the data type storing the sample and instead use a narrow + (16-235) range to allow some headroom & toeroom in the signals to avoid + clipping signals which overshoot slightly during processing. This is + sometimes known as signals using "studio swing". + + ANSWER: Add a new attribute to define if the samples use a narrow 16-235 + range or the full 0-256 range. + + 13. Specifying the color space and range seems cumbersome, why not just + allow the application to specify the full YUV->RGB color conversion matrix? + + ANSWER: Some hardware may not be able to use an arbitrary conversion matrix + and needs to select an appropriate pre-defined matrix based on the color + space and the sample range. + + 14. How do you handle EGL implementations which have restrictions on pitch + and/or offset? + + ANSWER: Buffers being imported using dma_buf pretty much have to be + allocated by a kernel-space driver. As such, it is expected that a system + integrator would make sure all devices which allocate buffers suitable for + exporting make sure they use a pitch supported by all possible importers. + However, it is still possible eglCreateImageKHR can fail due to an + unsupported pitch. Added a new error to the list indicating this. + + 15. Should this specification also describe how to export an existing + EGLImage as a dma_buf file descriptor? + + ANSWER: No. Importing and exporting buffers are two separate operations and + importing an existing dma_buf fd into an EGLImage is useful functionality in + itself. Agree that exporting an EGLImage as a dma_buf fd is useful, E.g. it + could be used by an OpenMAX IL implementation's OMX_UseEGLImage function to + give access to the buffer backing an EGLImage to video hardware. However, + exporting can be split into a separate extension specification. + + +Revision History + +#7 (Kristian H. Kristensen, December 13, 2017) + - Clarify plane ordering to match Linux FOURCC conventions (Bug 16017). + +#6 (David Garbett, December 05, 2013) + - Application now retains ownership of dma_buf file descriptors. + +#5 (Tom Cooksey, February 19, 2013) + - Assigned enum values + - Moved out of drafts + +#4 (Tom Cooksey, October 04, 2012) + - Fixed issue numbering! + - Added issues 8 - 15. + - Promoted proposal for Issue 3 to be the answer. + - Added an additional attribute to allow an application to specify the color + space as a hint which should address issue 4. + - Added an additional attribute to allow an application to specify the chroma + siting as a hint which should address issue 5. + - Added an additional attribute to allow an application to specify the sample + range as a hint which should address the new issue 12. + - Added language to end of error section clarifying who owns the fd passed + to eglCreateImageKHR if an error is generated. + +#3 (Tom Cooksey, August 16, 2012) + - Changed name from EGL_EXT_image_external and re-written language to + explicitly state this for use with Linux & dma_buf. + - Added a list of issues, including some still open ones. + +#2 (Jesse Barker, May 30, 2012) + - Revision to split eglCreateImageKHR functionality from export + Functionality. + - Update definition of EGLNativeBufferType to be a struct containing a list + of handles to support multi-buffer/multi-planar formats. + +#1 (Jesse Barker, March 20, 2012) + - Initial draft. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_image_dma_buf_import_modifiers.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_image_dma_buf_import_modifiers.txt new file mode 100644 index 0000000..41b91c0 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_image_dma_buf_import_modifiers.txt @@ -0,0 +1,244 @@ +Name + + EXT_image_dma_buf_import_modifiers + +Name Strings + + EGL_EXT_image_dma_buf_import_modifiers + +Contributors + + Pekka Paalanen, Collabora Ltd. + Louis-Francis Ratté-Boulianne + Daniel Stone, Collabora Ltd. + Kristian Høgsberg + +Contacts + + Pekka Paalanen (pq 'at' collabora 'dot' com) + Daniel Stone (daniels 'at' collabora 'dot' com) + +Status + + Complete + +Version + + Version 5, March 12, 2019 + +Number + + EGL Extension #105 + +Dependencies + + EGL 1.2 is required. + + EGL_KHR_image_base is required. + EGL_EXT_image_dma_buf_import is required. + + The EGL implementation must be running on a Linux kernel supporting the + dma_buf buffer sharing mechanism. + + This extension is written against the wording of the EGL 1.2 Specification. + + In order to support imports for the GL_TEXTURE_EXTERNAL_OES target, a + compatible OpenGL ES implementation supporting GL_OES_EGL_image_external + must be present. + +Overview + + This extension builds on EGL_EXT_image_dma_buf_import, in order to support + format modifiers used for tiling, compression, and additional non-linear + modes. It also adds support for a fourth auxiliary plane, and queries for + the implementation-supported types. + +New Types + + None + +New Procedures and Functions + + EGLBoolean eglQueryDmaBufFormatsEXT( + EGLDisplay dpy, + EGLint max_formats, + EGLint *formats, + EGLint *num_formats) + + + EGLBoolean eglQueryDmaBufModifiersEXT( + EGLDisplay dpy, + EGLint format, + EGLint max_modifiers, + EGLuint64KHR *modifiers, + EGLBoolean *external_only, + EGLint *num_modifiers) + +New Tokens + + Accepted as an attribute in the <attrib_list> parameter of + eglCreateImageKHR: + + EGL_DMA_BUF_PLANE0_MODIFIER_LO_EXT 0x3443 + EGL_DMA_BUF_PLANE0_MODIFIER_HI_EXT 0x3444 + EGL_DMA_BUF_PLANE1_MODIFIER_LO_EXT 0x3445 + EGL_DMA_BUF_PLANE1_MODIFIER_HI_EXT 0x3446 + EGL_DMA_BUF_PLANE2_MODIFIER_LO_EXT 0x3447 + EGL_DMA_BUF_PLANE2_MODIFIER_HI_EXT 0x3448 + EGL_DMA_BUF_PLANE3_FD_EXT 0x3440 + EGL_DMA_BUF_PLANE3_OFFSET_EXT 0x3441 + EGL_DMA_BUF_PLANE3_PITCH_EXT 0x3442 + EGL_DMA_BUF_PLANE3_MODIFIER_LO_EXT 0x3449 + EGL_DMA_BUF_PLANE3_MODIFIER_HI_EXT 0x344A + +New Types + + This extension uses the 64-bit unsigned integer type EGLuint64KHR + first introduced by the EGL_KHR_stream extension, but does not + depend on that extension. The typedef may be reproduced separately + for this extension, if not already present in eglext.h. + + typedef khronos_uint64_t EGLuint64KHR; + + +Additions to Chapter 2 of the EGL 1.2 Specification (EGL Operation) + + Add to section 2.5.1 "EGLImage Specification" (as defined by the + EGL_KHR_image_base specification), in the description of + eglCreateImageKHR: + + If <target> is EGL_LINUX_DMA_BUF_EXT, both or neither of the following + attribute values may be given. These attribute values together form an + unsigned 64-bit value called a format modifier. Format modifiers are + specified by drm_fourcc.h and used as the modifier parameter of the + drm_mode_fb_cmd2 ioctl. If neither of the two attributes are given, or + if the modifier is explicitly declared to be DRM_FORMAT_MOD_INVALID, the + effective format modifier is implementation-defined. The two attributes + are: + + * EGL_DMA_BUF_PLANE0_MODIFIER_LO_EXT: The lowest 32 bits of the + 64-bit format modifier. + + * EGL_DMA_BUF_PLANE0_MODIFIER_HI_EXT: The highest 32 bits of the + 64-bit format modifier. + + For semi-planar and planar YUV formats, or other formats which require + multiple memory planes, planes 1, 2 and 3 are specified by the following + attributes, which have the same meanings as defined above for plane 0: + + * EGL_DMA_BUF_PLANE1_MODIFIER_LO_EXT + * EGL_DMA_BUF_PLANE1_MODIFIER_HI_EXT + * EGL_DMA_BUF_PLANE2_MODIFIER_LO_EXT + * EGL_DMA_BUF_PLANE2_MODIFIER_HI_EXT + * EGL_DMA_BUF_PLANE3_FD_EXT + * EGL_DMA_BUF_PLANE3_OFFSET_EXT + * EGL_DMA_BUF_PLANE3_PITCH_EXT + * EGL_DMA_BUF_PLANE3_MODIFIER_LO_EXT + * EGL_DMA_BUF_PLANE3_MODIFIER_HI_EXT + + Modifiers may modify any attribute of a buffer import, including but not + limited to adding extra planes to a format which otherwise does not have + those planes. As an example, a modifier may add a plane for an external + compression buffer to a single-plane format. The exact meaning and effect + of any modifier is canonically defined by drm_fourcc.h, not as part of this + extension. + + Implementations are required to validate the full combination of base + format and per-plane modifiers, and reject any combination which is not + explicitly supported. + + Add to the list of error conditions for eglCreateImageKHR: + + * If <target> is EGL_LINUX_DMA_BUF_EXT, and the list of attributes + contains EGL_DMA_BUF_PLANE0_MODIFIER_LO_EXT but not + EGL_DMA_BUF_PLANE0_MODIFIER_HI_EXT or vice versa, EGL_BAD_PARAMETER + is generated. This applies similarly for planes 1, 2, and 3 also. + + Add section 2.5.3 "EGLImage dma_buf formats and modifiers" + + The command + + EGLBoolean eglQueryDmaBufFormatsEXT( + EGLDisplay dpy, + EGLint max_formats, + EGLint *formats, + EGLint *num_formats) + + is used to query the dma_buf formats supported by <dpy>. Each format is + returned using its FourCC format as defined in the drm_fourcc.h header file. + EGL_TRUE is returned if QueryDmaBufFormatsEXT succeeds, EGL_FALSE indicates + failure to query. + + * If <dpy> is not the handle of a valid EGLDisplay object, the error + EGL_BAD_DISPLAY is generated. + + * If <max_formats> is 0, no formats are returned, but the total number + of formats is returned in <num_formats>, and no error is generated. + + * If <max_formats> has a negative value, the error EGL_BAD_PARAMETER + is generated. + + * If <max_formats> is a positive integer but <formats> is NULL, the error + EGL_BAD_PARAMETER is generated. + + The command + + EGLBoolean eglQueryDmaBufModifiersEXT( + EGLDisplay dpy, + EGLint format, + EGLint max_modifiers, + EGLuint64KHR *modifiers, + EGLBoolean *external_only, + EGLint *num_modifiers) + + is used to query the dma_buf format modifiers supported by <dpy> for the + given format. The format must be one of those returned by the + eglQueryDmaBufFormatsEXT command. The returned modifiers should be + defined in the canonical drm_fourcc.h header file. If the user also + passes an array for <external_only>, this will be populated with whether + the requested format and modifier combination is only supported for use + with the GL_TEXTURE_EXTERNAL_OES texture target. If <dpy> cannot support + any context with GL_OES_EGL_image_external, the array will be populated with + EGL_FALSE. EGL_TRUE is returned if QueryDmaBufModifiersEXT succeeds, + EGL_FALSE indicates failure. + + * If <dpy> is not the handle of a valid EGLDisplay object, the error + EGL_BAD_DISPLAY is generated. + + * If <max_modifiers> is 0, no modifiers are returned, but the total + number of modifiers is returned in <num_modifiers>, and no error is + generated. + + * If <max_modifiers> has a negative value, the error EGL_BAD_PARAMETER + is generated. + + * If <max_modifiers> is a positive integer but <modifiers> is NULL, the + error EGL_BAD_PARAMETER is generated. + + * If <format> is not one of the formats advertised by + QueryDmaBufFormatsEXT for the same <dpy>, the error EGL_BAD_PARAMETER + is generated. + + +Revision History + +#5 (Daniel Stone, March 12, 2019) + - Correct description of behaviour when a modifier is not explicitly given; + zero is not correct as it is an explicit modifier itself (linear). + +#4 (Daniel Stone, October 20, 2016) + - Switch to EGLuint64KHR for modifier types. + +#3 (Daniel Stone, October 20, 2016) + - Clarify that the effect that modifiers can have. + - Disambiguate references to displays. + - Explicitly refer to max_formats/max_modifiers behaviour when zero. + +#2 (Daniel Stone, September 29, 2016) + - Add missing tokens for plane 3 FD/offset/pitch. + - Fix description. + - Allow max_formats/max_modifiers to be zero, to get the counter. + - Add external_only to modifiers query. + +#1 (Pekka Paalanen, October 14, 2015) + - Initial draft. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_image_gl_colorspace.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_image_gl_colorspace.txt new file mode 100644 index 0000000..ab53660 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_image_gl_colorspace.txt @@ -0,0 +1,136 @@ +Name + + EXT_image_gl_colorspace + +Name Strings + + EGL_EXT_image_gl_colorspace + +Contributors + + Jesse Hall, Google + Philip Rideout, Google + Mohan Maiya, Qualcomm + Jan-Harald Fredriksen, ARM + +Contact + + Krzysztof Kosiński, Google (krzysio 'at' google.com) + +Status + + Complete + +Version + + Version 9, February 26, 2018 + +Number + + EGL Extension #125 + +Dependencies + + Written against the EGL 1.5 specification. + + Can be supported on EGL 1.4 provided that EGL_KHR_gl_colorspace is + implemented, as well as either EGL_KHR_image or EGL_KHR_image_base. + + Interacts with the GL_OES_EGL_image_external specification. + +Overview + + This extension relaxes the restriction that only the eglCreate*Surface + functions can accept the EGL_GL_COLORSPACE attribute. With this change, + eglCreateImage can also accept this attribute. + +New Tokens + + EGL_GL_COLORSPACE_DEFAULT_EXT 0x314D + +New Procedures and Functions + + None. + +Additions to the EGL 1.5 Specification + + Add to table 3.11 on page 75: + + "Attribute Type Description + -------------------- ---- ----------- + EGL_GL_COLORSPACE enum Color space for OpenGL and OpenGL ES" + + + Add the following paragraph to the end of section 3.9, "EGLImage + Specification and Management" on page 77: + + "EGL_GL_COLORSPACE specifies the color space used by OpenGL and OpenGL + ES when rendering to the image, or sampling from the image. It has the + same meaning as when used with eglCreatePlatformWindowSurface, with the + exception that its default value is EGL_GL_COLORSPACE_DEFAULT_EXT. This + means that the color space should not be overriden. For example, if an + image is created from an existing OpenGL texture, then + GL_COLORSPACE_DEFAULT_EXT means that the original color space should be + preserved." + + + Add the following paragraphs to the "Errors" subsection in section 3.9 + on page 76: + + "If EGL_GL_COLORSPACE is not one of the legal values, the error + EGL_BAD_PARAMETER is generated." + + "If ctx specifies a GL context that does not support creating an EGLImage + with the given value for EGL_GL_COLORSPACE, EGL_BAD_MATCH error is + generated." + + +Interaction with OES_EGL_image_external: + + The first sentence in the second to last paragraph in section 3.7.14 + should be changed from: + + "Sampling an external texture will return an RGBA vector in the same + colorspace as the source image." + + to: + + "Sampling an external texture will return an RGBA vector in the same color + space as the source image, unless the image's EGL_GL_COLORSPACE attribute + results in sRGB encoding as described in EGL_EXT_image_gl_colorspace." + + The three parenthetical sentences in this same paragraph should be + simplified since they partially conflict with existing language in the + ES30 specification. Change them from: + + "(But these RGB values will be in the same colorspace as the + original image. Colorspace here includes the linear or non-linear + encoding of the samples. For example, if the original image is in the + sRGB color space then the RGB value returned by the sampler will also + be sRGB, and if the original image is stored in ITU-R Rec. 601 YV12 + then the RGB value returned by the sampler will be an RGB value in the + ITU-R Rec. 601 colorspace.)" + + to: + + "(For example, if the original image is stored in ITU-R Rec. 601 YV12 + then the RGB value returned by the sampler will be an RGB value in the + ITU-R Rec. 601 colorspace.)" + + +Issues + +Revision History + + Rev. Date Author Changes + ---- -------- -------- ----------------------------------------- + 1 11/22/17 philip Initial draft + 2 12/8/17 philip Add note about OES_EGL_image_external + 3 12/11/17 philip Changed from KHR to EXT. + 4 12/15/17 philip Add diffs against the EGL 1.5 specification. + 5 12/20/17 philip Add EGL_GL_COLORSPACE_DEFAULT_EXT. + 6 1/2/18 philip Updated changes to OES_EGL_image_external. + 7 1/2/18 philip Tweaked the changes to OES_EGL_image_external. + 8 2/2/18 philip Add value for EGL_GL_COLORSPACE_DEFAULT_EXT. + 9 2/26/18 krzysio Update contact information, finalize. + 9 4/20/18 krzysio Fix stray reference to KHR. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_image_implicit_sync_control.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_image_implicit_sync_control.txt new file mode 100644 index 0000000..5660e0a --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_image_implicit_sync_control.txt @@ -0,0 +1,131 @@ +Name + + EXT_image_implicit_sync_control + +Name Strings + + EGL_EXT_image_implicit_sync_control + +Contributors + + Daniel Stone, Collabora Ltd. + +Contacts + + Daniel Stone (daniels 'at' collabora 'dot' com) + +Status + + Complete + +Version + + Version 2, March 16, 2020 + +Number + + EGL Extension #120 + +Dependencies + + EGL 1.2 is required. + + EGL_KHR_image_base and EGL_EXT_image_dma_buf_import are required. + + The EGL implementation must be running on a Linux kernel supporting implicit + synchronization, as the usage is defined in the + EGL_ARM_implicit_external_sync extension, but does not require that extension. + + This extension is written against the wording of the EGL 1.2 Specification. + +Overview + + This extension allows a client to selectively use implicit or explicit + synchronization mechanisms when addressing externally-imported EGLImages. + A new token is added to EGLImage creation which allows the client to select + whether a platform's implicit synchronization will be in use for a buffer + imported into EGLImage. + + Heterogeneous systems (supporting multiple APIs, mixed legacy/updated + clients, etc) already supporting implicit synchronization, may not be able + to change to explict synchronization in a single switch. This extension + allows synchronization to be controlled on a per-buffer basis, so explicit + synchronization can be enabled for a complete pipeline which supports it, + or implicit synchronization used otherwise. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted as an attribute in the <attrib_list> parameter of + eglCreateImageKHR: + + EGL_IMPORT_SYNC_TYPE_EXT 0x3470 + + Accepted as the value for the EGL_IMPORT_SYNC_TYPE_EXT attribute: + + EGL_IMPORT_IMPLICIT_SYNC_EXT 0x3471 + EGL_IMPORT_EXPLICIT_SYNC_EXT 0x3472 + +New Types + + None. + +Additions to Chapter 2 of the EGL 1.2 Specification (EGL Operation) + + Add to section 2.5.1 "EGLImage Specification" (as defined by the + EGL_KHR_image_base specification), in the description of + eglCreateImageKHR: + + Add the following to Table bbb (Legal attributes for eglCreateImageKHR + <attr_list> parameter), Section 2.5.1 (EGLImage Specification) + + +-----------------------------+-------------------------+---------------------------+---------------+ + | Attribute | Description | Valid <target>s | Default Value | + +-----------------------------+-------------------------+---------------------------+---------------+ + | EGL_IMPORT_SYNC_TYPE_EXT | The type of | EGL_LINUX_DMA_BUF_EXT | EGL_IMPORT_ | + | | synchronization to | | IMPLICT_SYNC_ | + | | apply to previously | | EXT | + | | submitted rendering on | | | + | | the platform buffer | | | + +-----------------------------+-------------------------+---------------------------+---------------+ + Table bbb. Legal attributes for eglCreateImageKHR <attrib_list> parameter + + ... + + + Add to section 2.5.1 "EGLImage Specification" (as defined by the + EGL_KHR_image_base specification), in the description of + eglCreateImageKHR: + + The behaviour of the imported buffer with regard to commands previously + submitted (including via other APIs and from other clients) is controlled + by the EGL_IMPORT_SYNC_TYPE_EXT attribute. If the default value of + implicit synchronization is used, the platform may synchronize any access + to the imported buffer, against accesses previously made (including by + other clients or APIs) to that same buffer. If explicit synchronization + is specified, the platform will not synchronize access to that buffer + against other accesses; the client must use another synchronization + mechanism if it wishes to order its accesses with respect to others. + + Add to the list of error conditions for eglCreateImageKHR: + + * If <attrib_list> contains the EGL_IMPORT_SYNC_TYPE_EXT name, but the + value is not one of EGL_IMPORT_IMPLICIT_SYNC_EXT or + EGL_IMPORT_EXPLICIT_SYNC_EXT, EGL_BAD_ATTRIBUTE is generated. + + +Revision History + +#1 (Daniel Stone, May 15, 2017) + - Initial revision. + +#2 (Eric Engestrom, March 16, 2020) + - Change "bad attribute value" error from EGL_BAD_PARAMETER to + EGL_BAD_ATTRIBUTE to follow the EGL convention. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_multiview_window.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_multiview_window.txt new file mode 100644 index 0000000..9cf0ff6 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_multiview_window.txt @@ -0,0 +1,126 @@ +Name + + EXT_multiview_window + +Name Strings + + EGL_EXT_multiview_window + +Contributors + + Acorn Pooley + Greg Roth + +Contacts + + Greg Roth (groth 'at' nvidia.com) + +Status + + Complete + +Version + + Version 3, Sept 03, 2011 + +Number + + EGL Extension #42 + +Dependencies + + Requires EGL 1.4 + + Written against the EGL 1.4 specification. + +Overview + + Adds support for creating an onscreen EGLSurface containing + multiple color buffers. + + EXT_multi_draw_buffers can be used with this extension to + render and display multiple color buffers to a supported + device. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted as an attribute in the <attrib_list> parameter of + CreateWindowSurface: + + EGL_MULTIVIEW_VIEW_COUNT_EXT 0x3134 + +Additions to Chapter 3 of the EGL 1.2 Specification: + + Additions to section 3.5.1 (Creating On-Screen Rendering Surfaces) + + Alter the end of the second paragraph: + + Attributes that can be specified in <attrib_list> include + EGL_RENDER_BUFFER, EGL_VG_COLORSPACE, EGL_VG_ALPHA_FORMAT, and + EGL_MULTIVIEW_VIEW_COUNT_EXT. + + Add before the last paragraph of section 3.5.1: + + EGL_MULTIVIEW_VIEW_COUNT_EXT specifies how many multiview color + buffers should be created for the surface. Each color buffer has + the same properties as the primary color buffer as specified by + window and surface attributes. The default value of + EGL_MULTIVIEW_VIEW_COUNT_EXT is one. + + EGL may not be able to create as many multiview color buffers as + EGL_MULTIVIEW_VIEW_COUNT_EXT specifies. To determine the number + of multiview color buffers created by a context, call + eglQueryContext (see section 3.7.4). + + Add to the last paragraph of section 3.5.1: + + If the value specified for EGL_MULTIVIEW_VIEW_COUNT_EXT is less + than one, an EGL_BAD_PARAMETER error is generated. If the value + specified for EGL_MULTIVIEW_VIEW_COUNT_EXT is greater than one + and the <config> does not support multiple multiview color + buffers, an EGL_BAD_MATCH error is generated. + + Additions to section 3.5.6 (Surface Attributes) + + Add to table 3.5, "Queryable surface attributes and types" + + Attribute Type Description + --------- ---- ----------- + EGL_MULTIVIEW_VIEW_COUNT_EXT integer Requested multiview + color buffers + + Add before the last paragraph describing eglQuerySurface: + + Querying EGL_MULTIVIEW_VIEW_COUNT_EXT for a window surface + returns the number of multiview color buffers requested. For a + pbuffer or pixmap surface, the contents of <value> are not + modified. To determine the actual number of multiview color + buffers created by a context, call eglQueryContext (see + section 3.7.4). + + + Additions to section 3.7.4 (Context Queries) + + Add before the last paragraph describing eglQueryContext: + + Querying EGL_MULTIVIEW_VIEW_COUNT_EXT returns the number of + multiview color buffers created. The value returned depends on + properties of both the context, and the surface to which the + context is bound. + +Issues + + None + +Revision History + Version 3, 03 Sept 2011 EXTify add support for multiple or single depth buffer. + Version 2, 02 Aug 2011 Responses to feedback. + Version 1, 14 April 2011 First draft. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_output_base.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_output_base.txt new file mode 100644 index 0000000..1cbd112 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_output_base.txt @@ -0,0 +1,564 @@ +Name + + EXT_output_base + +Name Strings + + EGL_EXT_output_base + +Contributors + + Daniel Kartch + James Jones + Christopher James Halse Rogers + +Contacts + + Daniel Kartch, NVIDIA (dkartch 'at' nvidia.com) + +Status + + Complete + +Version + + Version 9 - August 22, 2014 + +Number + + EGL Extension #78 + +Extension Type + + EGL display extension + +Dependencies + + Written against the wording of EGL 1.5, plus the EGL_EXT_device_base + specification. + + Requires EGL_EXT_device_base + +Overview + + Increasingly, EGL and its client APIs are being used in place of + "native" rendering APIs to implement the basic graphics + functionality of native windowing systems. This creates demand + for a method to initialize EGL displays and surfaces directly on + top of native GPU or device objects rather than native window + system objects. The mechanics of enumerating the underlying + native devices and constructing EGL displays and surfaces from + them have been solved in various platform and implementation- + specific ways. The EGL device family of extensions offers a + standardized framework for bootstrapping EGL without the use of + any underlying "native" APIs or functionality. + + This extension defines new EGL resource types for referencing + display control hardware associated with an EGL device. Its purpose + is to allow rendering to be directed to a screen in the absence of + (or bypassing) a window system. Because the use models for these + resources are potentially diverse, only the objects themselves and + basic functions to acquire and query them are defined here. More + detailed functions and enumerants required to operate on outputs + are provided by separate extensions. + +New Types + + A handle representing a portion of display control hardware which + accepts a single image as input and processes it for output on a + display device: + + typedef void* EGLOutputLayerEXT; + + A handle representing a portion of display control hardware which + transmits a signal to a display device: + + typedef void* EGLOutputPortEXT; + +New Functions + + EGLBoolean eglGetOutputLayersEXT( + EGLDisplay dpy, + const EGLAttrib *attrib_list, + EGLOutputLayerEXT *layers, + EGLint max_layers, + EGLint *num_layers); + + EGLBoolean eglGetOutputPortsEXT( + EGLDisplay dpy, + const EGLAttrib *attrib_list, + EGLOutputPortEXT *ports, + EGLint max_ports, + EGLint *num_ports); + + EGLBoolean eglOutputLayerAttribEXT( + EGLDisplay dpy, + EGLOutputLayerEXT layer, + EGLint attribute, + EGLAttrib value); + + EGLBoolean eglQueryOutputLayerAttribEXT( + EGLDisplay dpy, + EGLOutputLayerEXT layer, + EGLint attribute, + EGLAttrib *value); + + const char* eglQueryOutputLayerStringEXT( + EGLDisplay dpy, + EGLOutputLayerEXT layer, + EGLint name); + + EGLBoolean eglOutputPortAttribEXT( + EGLDisplay dpy, + EGLOutputPortEXT port, + EGLint attribute, + EGLAttrib value); + + EGLBoolean eglQueryOutputPortAttribEXT( + EGLDisplay dpy, + EGLOutputPortEXT port, + EGLint attribute, + EGLAttrib *value); + + const char* eglQueryOutputPortStringEXT( + EGLDisplay dpy, + EGLOutputPortEXT port, + EGLint name); + +New Tokens + + Functions with a return type of EGLOutputLayerEXT will return this + value on failure: + + EGL_NO_OUTPUT_LAYER_EXT ((EGLOutputLayerEXT)0) + + Functions with a return type of EGLOutputPortEXT will return this + value on failure: + + EGL_NO_OUTPUT_PORT_EXT ((EGLOutputPortEXT)0) + + Functions which fail due to a bad EGLOutputLayerEXT handle will set + this error code: + + EGL_BAD_OUTPUT_LAYER_EXT 0x322D + + Functions which fail due to a bad EGLOutputPortEXT handle will set + this error code: + + EGL_BAD_OUTPUT_PORT_EXT 0x322E + + Functions which set or query the swap interval use this attribute + name: + + EGL_SWAP_INTERVAL_EXT 0x322F + +Add a new section "2.1.4 Outputs" after "2.1.3 Displays": + + An EGLDisplay may have zero or more associated EGLOutputLayerEXT + and EGLOutputPortEXT objects. These represent, respectively, the + inputs and outputs of display control hardware. + + An EGLOutputLayerEXT is an abstract handle representing an element + of display control hardware which receives image data and processes + it for display. This processing is hardware-dependent, and may + include, but is not limited to, color space transformation, scaling + and rotation, and composition/blending with images from other + EGLOutputLayerEXTs. + + An EGLOutputPortEXT is an abstract handle representing an element of + display control hardware which sends a signal to drive a display + screen. In general, this signal is the result of the processing of + one or more EGLOutputLayerEXTs. + +Add new entries to section "3.1 Errors": + + EGL_BAD_OUTPUT_LAYER_EXT + An EGLOutputLayerEXT argument does not name a valid + EGLOutputLayerEXT. Any command taking an EGLOutputLayerEXT + parameter may generate this error. + + EGL_BAD_OUTPUT_PORT_EXT + An EGLOutputPortEXT argument does not name a valid + EGLOutputPortEXT. Any command taking an EGLOutputPortEXT + parameter may generate this error. + +Add a new section "3.10 Device Outputs" after "3.9 Posting the Color Buffer": + + 3.10 Device Outputs + + A simple platform running a custom software suite may not require a + formal window system. Instead, individual applications or a + compositor may send rendering results directly to display control + hardware, represented by EGLOutputLayerEXT and EGLOutputPortEXT + handles. + + As with other EGL resources, EGLOutputLayerEXT and EGLOutputPortEXT + handles are owned by an EGLDisplay, but not all EGLDisplays are + required to support these objects. In general, they will only be + available for EGLDisplays obtained from platforms which allow direct + manipulation of display devices. + + 3.10.1 Acquiring Outputs + + To obtain EGLOutputLayerEXT handles associated with a display which + match a list of attributes, use + + EGLBoolean eglGetOutputLayersEXT( + EGLDisplay dpy, + const EGLAttrib *attrib_list, + EGLOutputLayerEXT *layers, + EGLint max_layers, + EGLint *num_layers) + + On success, EGL_TRUE is returned. If <layers> is NULL, <max_layers> + is ignored and the number of output layers which match <attrib_list> + is returned in <num_layers>. Otherwise, up to <max_layers> matching + layers will be returned in <layers> and <num_layers> will be set to + the number of layer handles returned. The states of the output + layers are not altered by this query, and output layer handles can + be retrieved by multiple calls to this function. + + <attrib_list> may be NULL or a list of name/value pairs terminated + by EGL_NONE. If no attributes are provided, all output layers + associated with <dpy> will match. Otherwise, only those layers + matching all attributes provided in the list will be returned, + unless the value specified is EGL_DONT_CARE. If there are no + matching layers but all parameters are otherwise valid, success is + returned but num_layers is set to 0. + + On failure, EGL_FALSE will be returned and the memory referenced by + <layers> and <num_layers> will be unaffected. If <dpy> is not a + valid, initialized EGLDisplay, an EGL_BAD_DISPLAY error is + generated. If any name in <attrib_list> is not a valid layer + attribute name defined in Table 3.10.3.1, an EGL_BAD_ATTRIBUTE error + is generated. If any name in <attrib_list> does not allow search + access, an EGL_BAD_ACCESS error is generated. + + To obtain EGLOutputPortEXT handles associated with a display which + match a list of attributes, use + + EGLBoolean eglGetOutputPortsEXT( + EGLDisplay dpy, + const EGLAttrib *attrib_list, + EGLOutputPortEXT *ports, + EGLint max_ports, + EGLint *num_ports) + + On success, EGL_TRUE is returned. If <ports> is NULL, <max_ports> is + ignored and the number of output ports which match <attrib_list> is + returned in <num_ports>. Otherwise, up to <max_ports> matching + layers will be returned in <ports> and <num_ports> will be set to + the number of port handles returned. The states of the output ports + are not altered by this query, and output port handles can be + retrieved by multiple calls to this function. + + <attrib_list> may be NULL or a list of name/value pairs terminated + by EGL_NONE. If no attributes are provided, all output ports + associated with <dpy> will match. Otherwise, only those ports + matching all attributes provided in the list will be returned, + unless the value specified is EGL_DONT_CARE. If there are no + matching ports but all parameters are otherwise valid, success is + returned but num_ports is set to 0. + + On failure, EGL_FALSE will be returned and the memory referenced by + <ports> and <num_ports> will be unaffected. If <dpy> is not a valid, + initialized EGLDisplay, an EGL_BAD_DISPLAY error is generated. If + any name in <attrib_list> is not a valid port attribute name defined + in Table 3.10.3.2, an EGL_BAD_ATTRIBUTE error is generated. If any + name in <attrib_list> does not allow search access, an + EGL_BAD_ACCESS error is generated. + + 3.10.2 Lifetime of Output Handles + + An initialized EGLDisplay has a fixed set of output layer and port + resources available. Implementations may defer creation of handles + and allocation of data structions for these objects until they are + first requested. However, once acquired, they remain valid as long + as the EGLDisplay is not terminated. + + 3.10.3 Output Attributes + + Valid attributes associated with output layers and ports are listed + in Tables 3.10.3.1 and 3.10.3.2, respectively. Additional attributes + may be defined by other extensions. The Access columns contain one + or more of the letters "S", "R", and W". A value of "S" indicates + the attribute may be used to restrict the search when obtaining a + list of output handles. A value of "R" indicates the value may be + queried from an output handle. A value of "W" indicates the value + may be modified using an output handle. + + Attribute Type Access + --------------------- ------- ------ + EGL_SWAP_INTERVAL_EXT integer R|W + EGL_MIN_SWAP_INTERVAL integer R + EGL_MAX_SWAP_INTERVAL integer R + + Table 3.10.3.1 Output layer attributes + + Attribute Type Access + --------------------- ------- ------ + [no attributes supported] + + Table 3.10.3.2 Output port attributes + + 3.10.3.1 Querying Output Attributes + + To query attributes of an EGLOutputLayerEXT, use + + EGLBoolean eglQueryOutputLayerAttribEXT( + EGLDisplay dpy, + EGLOutputLayerEXT layer, + EGLint attribute, + EGLAttrib *value) + + On success, this function returns EGL_TRUE and stores the value of + <attribute> in <value>. + + On failure, EGL_FALSE is returned. If <dpy> is not a valid, + initialized EGLDisplay, an EGL_BAD_DISPLAY error is generated. If + <layer> is not a valid EGLOutputLayerEXT associated with <dpy>, an + EGL_BAD_OUTPUT_LAYER_EXT error is generated. If <attribute> is not a + valid layer attribute name defined in Table 3.10.3.1, an + EGL_BAD_ATTRIBUTE error is generated. If <attribute> has string + type or does not allow read access, an EGL_BAD_ACCESS error is + generated. + + To query string properties of an EGLOutputLayerEXT, use + + const char* eglQueryOutputLayerStringEXT( + EGLDisplay dpy, + EGLOutputLayerEXT layer, + EGLint attribute) + + On success, this function returns a zero-terminated string + containing the value associated with <name>. + + On failure, NULL is returned. If <dpy> is not a valid, initialized + EGLDisplay, an EGL_BAD_DISPLAY error is generated. If <layer> is not + a valid EGLOutputLayerEXT associated with <dpy>, an + EGL_BAD_OUTPUT_LAYER_EXT error is generated. If <name> is not a + valid layer attribute name defined in Table 3.10.3.1, an + EGL_BAD_ATTRIBUTE error is generated. If <attribute> has non-string + type or does not allow read access, an EGL_BAD_ACCESS error is + generated. + + To query attributes of an EGLOutputPortEXT, use + + EGLBoolean eglQueryOutputPortAttribEXT( + EGLDisplay dpy, + EGLOutputPortEXT port, + EGLint attribute, + EGLAttrib *value) + + On success, this function returns EGL_TRUE and stores the value of + <attribute> in <value>. + + On failure, EGL_FALSE is returned. If <dpy> is not a valid, + initialized EGLDisplay, an EGL_BAD_DISPLAY error is generated. If + <port> is not a valid EGLOutputPortEXT associated with <dpy>, an + EGL_BAD_OUTPUT_PORT_EXT error is generated. If <attribute> is not a + valid port attribute name defined in Table 3.10.3.2, an + EGL_BAD_ATTRIBUTE error is generated. If <attribute> has string + type or does not allow read access, an EGL_BAD_ACCESS error is + generated. + + To query string properties of an EGLOutputPortEXT, use + + const char* eglQueryOutputPortStringEXT( + EGLDisplay dpy, + EGLOutputPortEXT port, + EGLint attribute) + + On success, this function returns a zero-terminated string + containing the value associated with <name>. + + On failure, NULL is returned. If <dpy> is not a valid, initialized + EGLDisplay, an EGL_BAD_DISPLAY error is generated. If <port> is not + a valid EGLOutputPortEXT associated with <dpy>, an + EGL_BAD_OUTPUT_PORT_EXT error is generated. If <name> is not a + valid port attribute name defined in Table 3.10.3.2, an + EGL_BAD_ATTRIBUTE error is generated. If <attribute> has non-string + type or does not allow read access, an EGL_BAD_ACCESS error is + generated. + + 3.10.3.2 Setting Output Attributes + + To set attributes of an EGLOutputLayerEXT, use + + EGLBoolean eglOutputLayerAttribEXT( + EGLDisplay dpy, + EGLOutputLayerEXT layer, + EGLint attribute, + EGLAttrib value) + + On success, this function returns EGL_TRUE and sets the value of + <attribute> to <value>. + + If <attribute> is EGL_SWAP_INTERVAL_EXT, the value provided will be + silently clamped to the range specified by the layer's + EGL_MIN_SWAP_INTERVAL and EGL_MAX_SWAP_INTERVAL values. + + On failure, EGL_FALSE is returned. If <dpy> is not a valid, + initialized EGLDisplay, an EGL_BAD_DISPLAY error is generated. If + <layer> is not a valid EGLOutputLayerEXT associated with <dpy>, an + EGL_BAD_OUTPUT_LAYER_EXT error is generated. If <attribute> is not a + valid layer attribute name defined in Table 3.10.3.1, an + EGL_BAD_ATTRIBUTE error is generated. If <attribute> does not + allow write access, an EGL_BAD_ACCESS error is generated. + + To set attributes of an EGLOutputPortEXT, use + + EGLBoolean eglOutputPortAttribEXT( + EGLDisplay dpy, + EGLOutputPortEXT port, + EGLint attribute, + EGLAttrib value) + + On success, this function returns EGL_TRUE and sets the value of + <attribute> to <value>. + + On failure, EGL_FALSE is returned. If <dpy> is not a valid, + initialized EGLDisplay, an EGL_BAD_DISPLAY error is generated. If + <port> is not a valid EGLOutputPortEXT associated with <dpy>, an + EGL_BAD_OUTPUT_PORT_EXT error is generated. If <attribute> is not a + valid port attribute name defined in Table 3.10.3.2, an + EGL_BAD_ATTRIBUTE error is generated. If <attribute> does not + allow write access, an EGL_BAD_ACCESS error is generated. + + 3.10.4 Setting Output Modes + + EGL does not currently define any mechanims to adjust display + modes through EGLOutputPortEXTs. These may be added via additional + extensions. + + 3.10.5 Posting to Outputs + + EGL does not currently define any mechanisms to post rendering + results to EGLOutputsLayerEXTs. These may be added via additional + extensions. However, unless otherwise specified, such mechanims + will respect the layer's EGL_SWAP_INTERVAL_EXT value, which + specifies the minimum number of video frame periods for which the + frames should be displayed, in a manner analogous to using + eglSwapInterval for the current draw surface. The default value of + EGL_SWAP_INTERVAL_EXT is 1, clamped to the layer's + EGL_MIN_SWAP_INTERVAL and EGL_MAX_SWAP_INTERVAL values. + + (Example: See extension specification + EGL_EXT_stream_consumer_egloutput) + +Issues + + 1. Should this extension provide a mechanism to enumerate outputs + associated with an EGLDevice and set their modes? + + RESOLVED: No. On many operating systems there already exist + standardized and/or widely accepted low level mechanisms for + performing these tasks. Duplicating this support in EGL would + impose an undesirable implementation burden where output handles + are only required as a means to direct rendering to a display + screen. Functions for enumerating screens or obtaining them from + platform-dependent representations will be provided by other + extensions. + + 2. Should output layer and port handles be associated with an + EGLDisplay, or vice versa? + + RESOLVED: Yes. Furthermore, it may only be possible to obtain + output handles from some EGLDisplays. The primary intended use + case is the EGLDisplay associated with an EGLDevice, through the + platform defined by EGL_EXT_platform_device. This represents raw + device access available in the absence of a window system. + EGLDisplays associated with other platforms typically represent + handles provided by window systems, which may not allow direct + access to the display control hardware. + + 3. Can the EGLDeviceEXT handle be returned by a query function + which returns integer attributes? + + RESOLVED: Yes. Function definition has been updated to use + EGLAttribEXT, which is compatible with EGL handles. + + 4. What display mode properties should be queriable by the base + extension? Does the application require width/height/refresh or + should those be left to other mechanisms or additional + extensions? If hardware supports selecting a portion of the + image for display, or restricting an image to a portion of the + screen, or scaling an image to a different resolution for + display, should all these settings be queriable? + + RESOLVED: The base extension will not define any display + properties. These will be left to future extensions if required. + + 5. How should stereo/multiview displays be handled? Should all + views share a single output or does each one have its own? + + UNRESOLVED. Left for a future extension to define. + + 6. This extension is currently focused on individual display layers + for the purpose of directing rendering output. An API covering + all hardware would associate one or more of those layers with a + display port. Do we need to abstract both? + + RESOLVED: Yes. Extension has been modified to abstract both + inputs (layers) and outputs (ports) of display control hardware. + An implementation is not required to return any ports in the + query function if it provides no means to operate on them. + +Revision History: + + #9 (August 22nd, 2014) James Jones + - Marked complete. + - Added minor coments to issue 5. + - Listed Daniel as the contact. + + #8 (June 10th, 2014) Daniel Kartch + - Fixed prototypes for layer/port attribute setting functions. + + #7 (June 5th, 2014) Daniel Kartch + - Assigned enumerated values for constants. + - Indicated default swap interval value. + + #6 (May 28th, 2014) Daniel Kartch + - Updated wording based on EGL 1.5 specification, using + EGLAttrib instead of EGLAttribEXT. + - Added functions to set layer and port attributes. + - Added table of valid attributes, with min/max/current swap + interval values, and adjusted function descriptions + accordingly. + - Refined description for output enumeration functions to better + indicate the effect of attribute list. + - Added effect of swap interval in posting section. + + #5 (January 31st, 2014) Daniel Kartch + - Added eglGetOutput* functions, folding in and generalizing + functionality previously provided by EXT_native_output + extension. + - Separated descriptions for layer and port query functions for + clarity. + + #4 (January 22nd, 2014) Daniel Kartch + - Added section clarifying that this extension provides no means + to use output ports to set display modes, but future + extensions may. + + #3 (January 17th, 2014) Daniel Kartch + - Updated names of example extension for obtaining and using + output handles. + - Fixed typos. + + #2 (November 12th, 2013) Daniel Kartch + - Replaced EGLOutput with EGLOutputLayer and added + EGLOutputPort (and modified/added corresponding functions), to + allow both inputs and outputs of display control hardware to + be abstracted. + - Modified attribute query functions to use EGLAttribEXT and + added string query functions. + - Removed display mode attributes. These can be defined by a + separate extension if desired. + - Removed destructor function for outputs and added section on + lifetime, as well as language describing their relationship to + EGLDisplays. + + #1 (October 25nd, 2013) Daniel Kartch + - Initial draft + diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_pixel_format_float.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_pixel_format_float.txt new file mode 100644 index 0000000..a14adcb --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_pixel_format_float.txt @@ -0,0 +1,136 @@ +Name + + EXT_pixel_format_float + +Name Strings + + EGL_EXT_pixel_format_float + +Contributors + + Tom Cooksey + Jesse Hall + Mathias Heyer + Adam Jackson + James Jones + Daniel Koch + Jeff Leger + Weiwan Liu + Jeff Vigil + +Contact + + Weiwan Liu, NVIDIA (weiwliu 'at' nvidia.com) + +Status + + Complete + +Version + + Version 4 - Nov 22, 2016 + +Number + + EGL Extension #106 + +Dependencies + + This extension is written against the wording of the EGL 1.5 specification + (August 27, 2014). + +Overview + + This extensions aims to provide similar functionality as GL_ARB_color_- + buffer_float, WGL_ARB_pixel_format_float and GLX_ARB_fbconfig_float. This + extension allows exposing new EGLConfigs that support formats with + floating-point RGBA components. This is done by introducing a new EGLConfig + attribute that represents the component type, i.e. fixed-point or + floating-point. Such new EGLConfigs can be used to create floating-point + rendering surfaces and contexts. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted as an attribute name in the <attrib_list> argument of + eglChooseConfig, and the <attribute> argument of eglGetConfigAttrib: + + EGL_COLOR_COMPONENT_TYPE_EXT 0x3339 + + Accepted as attribute values for the EGL_COLOR_COMPONENT_TYPE_EXT attribute + of eglChooseConfig: + + EGL_COLOR_COMPONENT_TYPE_FIXED_EXT 0x333A + EGL_COLOR_COMPONENT_TYPE_FLOAT_EXT 0x333B + + Additions to table 3.1, "EGLConfig attributes" in Section 3.4 "Configuration + Management": + + Attribute Type Notes + --------- ---- --------- + EGL_COLOR_COMPONENT_TYPE_EXT enum color component type + + Append one paragraph at the end of "The Color Buffer" section on page 21: + + EGL_COLOR_COMPONENT_TYPE_EXT indicates the color buffer component type, + and must be either EGL_COLOR_COMPONENT_TYPE_FIXED_EXT for fixed-point + color buffers, or EGL_COLOR_COMPONENT_TYPE_FLOAT_EXT for floating-point + color buffers. + + Add one entry to Table 3.4 and increment "Sort Priority" between "2" and + "11" by one for existing entries: + + Attribute Default + ----------- ------------ + EGL_COLOR_COMPONENT_TYPE_EXT EGL_COLOR_COMPONENT_TYPE_FIXED_EXT + + Selection Criteria Sort Order Priority + ------------------ ---------- -------- + Exact Special 2 + + Insert before the entry for EGL_COLOR_BUFFER_TYPE, and increment its + numbering and subsequent numbering by one: + + 2. Special: by EGL_COLOR_COMPONENT_TYPE_EXT where the precedence is + EGL_COLOR_COMPONENT_TYPE_FIXED_EXT, EGL_COLOR_COMPONENT_TYPE_FLOAT_EXT + + Change footnote 8 on page 30 to: + + Within the same EGL_COLOR_COMPONENT_TYPE_EXT, this rule places configs + with deeper color buffers first in the list returned by + eglChooseConfig... + +Issues + + 1. When reading from or rendering to a floating-point EGL surface, is there + any clamping performed on the values? + + RESOLVED: It depends on the behavior of the client API. For example, in + OpenGL and ES, by default no clamping will be done on the floating-point + values, unless the clamping behavior is changed via the client API. + + 2. When rendering to a floating-point EGL surface, since values may not be + clamped to [0, 1], what is the range of values that applications can use + to get display's "darkest black" and "brightest white"? + + RESOLVED: It is not in the scope of this extension to define a range of + values that corresponds to display's capability. Please refer to the EGL + specification for the chosen colorspace (EGL_GL_COLORSPACE), where such a + reference range may be defined. + +Revision History + + Rev. Date Author Changes + ---- -------- --------------- ------------------------------------------ + 1 12/11/15 Weiwan Liu Initial version + 2 05/18/16 Weiwan Liu Rename to EXT + 3 05/31/16 Weiwan Liu Add issues + 4 11/22/16 Weiwan Liu Change status to complete + diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_base.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_base.txt new file mode 100644 index 0000000..80bd1bc --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_base.txt @@ -0,0 +1,371 @@ +Name + + EXT_platform_base + +Name Strings + + EGL_EXT_platform_base + +Contributors + + Chad Versace <chad.versace@intel.com> + James Jones <jajones@nvidia.com> + +Contacts + + Chad Versace <chad.versace@intel.com> + +Status + + Complete + +Version + + Version 9, 2014.01.09 + +Number + + EGL Extension #57 + +Extension Type + + EGL client extension + +Dependencies + + Requires EGL 1.4. + + Requires EGL_EXT_client_extensions to query its existence without + a display. + + This extension is written against the wording of the 2013.02.11 revision + of the EGL 1.4 Specification. + +Overview + + This extension defines functionality and behavior for EGL implementations + that support multiple platforms at runtime. For example, on Linux an EGL + implementation could support X11, Wayland, GBM (Generic Buffer Manager), + Surface Flinger, and perhaps other platforms. + + In particular, this extension defines the following: + + 1. A mechanism by which an EGL client can detect which platforms the + EGL implementation supports. + + 2. New functions that enable an EGL client to specify to which + platform a native resource belongs when creating an EGL resource + from that native resource. For example, this extension enables an + EGL client to specify, when creating an EGLSurface from a native + window, that the window belongs to X11. + + 3. That an EGL client is not restricted to interacting with a single + platform per process. A client process can create and manage EGL + resources from multiple platforms. + + The generic term 'platform' is used throughout this extension + specification rather than 'window system' because not all EGL platforms + are window systems. In particular, those platforms that allow headless + rendering without a display server, such as GBM, are not window systems. + + This extension does not specify behavior specific to any platform, nor + does it specify the set of platforms that an EGL implementation may + support. Platform-specific details lie outside this extension's scope and + are instead described by extensions layered atop this one. + +New Types + + None + +New Procedures and Functions + + EGLDisplay eglGetPlatformDisplayEXT( + EGLenum platform, + void *native_display, + const EGLint *attrib_list); + + EGLSurface eglCreatePlatformWindowSurfaceEXT( + EGLDisplay dpy, + EGLConfig config, + void *native_window, + const EGLint *attrib_list); + + EGLSurface eglCreatePlatformPixmapSurfaceEXT( + EGLDisplay dpy, + EGLConfig config, + void *native_pixmap, + const EGLint *attrib_list); + +New Tokens + + None + +Additions to the EGL 1.4 Specification + + Replace each occurence of the term "window system" with "platform". The + rationale behind this change is that not all platforms are window systems, + yet the EGL 1.4 specification uses the two terms interchangeably. In + particular, platforms that allow headless rendering without a display + server, such as GBM, are not window systems. + + Append the following paragraph to the initial, unnamed subsection of + section 2.1 "Native Window System and Rendering APIs". + + "This specification does not define the set of platforms that may be + supported by the EGL implementation, nor does it specify behavior specific + to any platform. The set of supported platforms and their behavior is + defined by extensions. To detect if a particular platform is supported, + clients should query the EGL_EXTENSIONS string of EGL_NO_DISPLAY using + eglQueryString. + + Replace the text of section 3.2 "Initialization", from the start of the + section and up to and excluding the phrase "EGL may be intialized on + a display", with the following: + + "A display can be obtained by calling + + EGLDisplay eglGetPlatformDisplayEXT( + EGLenum platform, + void *native_display, + const EGLint *attrib_list); + + EGL considers the returned EGLDisplay as belonging to the native platform + specified by <platform>. This specification defines no valid value for + <platform>. Any specification that does define a valid value for + <platform> will also define requirements for the <native_display> + parameter. For example, an extension specification that defines support + for the X11 platform may require that <native_display> be a pointer to an + X11 Display, and an extension specification that defines support for the + Microsoft Windows platform may require that <native_display> be a pointer + to a Windows Device Context. + + All attribute names in <attrib_list> are immediately followed by the + corresponding desired value. The list is terminated with EGL_NONE. The + <attrib_list> is considered empty if either <attrib_list> is NULL or if + its first element is EGL_NONE. This specification defines no valid + attribute names for <attrib_list>. + + Multiple calls made to eglGetPlatformDisplayEXT with the same <platform> + and <native_display> will return the same EGLDisplay handle. + + An EGL_BAD_PARAMETER error is generated if <platform> has an invalid value. + If <platform> is valid but no display matching <native_display> is + available, then EGL_NO_DISPLAY is returned; no error condition is raised + in this case. + + A display can also be obtained by calling + + EGLDisplay eglGetDisplay(EGLNativeDisplayType display_id); + + The behavior of eglGetDisplay is similar to that of + eglGetPlatformDisplayEXT, but is specifided in terms of implementation- + specific behavior rather than platform-specific extensions. + As for eglGetPlatformDisplayEXT, EGL considers the returned EGLDisplay + as belonging to the same platform as <display_id>. However, the set of + platforms to which <display_id> is permitted to belong, as well as the + actual type of <display_id>, are implementation-specific. If <display_id> + is EGL_DEFAULT_DISPLAY, a default display is returned. Multiple calls + made to eglGetDisplay with the same <display_id> will return the same + EGLDisplay handle. If no display matching <display_id> is available, + EGL_NO_DISPLAY is returned; no error condition is raised in this case." + + In section 3.5.1 "Creating On-Screen Rendering Surfaces", replace the + second paragraph, which begins with "Using the platform-specific type" and + ends with "render into this surface", with the following: + + "Then call + + EGLSurface eglCreatePlatformWindowSurfaceEXT( + EGLDisplay dpy, + EGLConfig config, + void *native_window, + const EGLint *attrib_list); + + eglCreatePlatformWindowSurfaceEXT creates an onscreen EGLSurface and + returns a handle to it. Any EGL context created with a compatible + EGLConfig can be used to render into this surface. + + <native_window> must belong to the same platform as <dpy>, and EGL + considers the returned EGLSurface as belonging to that same platform. The + extension that defines the platform to which <dpy> belongs also defines + the requirements for the <native_window> parameter." + + In the remainder of section 3.5.1, replace each occurrence of + 'eglCreateWindowSurface' with 'eglCreatePlatformWindowSurfaceEXT'. + + Insert the sentence below after the first sentence of the last paragraph + of section 3.5.1: + + "If <dpy> and <native_window> do not belong to the same platform, then + undefined behavior occurs. [1]" + + Add the following footnote to section 3.5.1: + + "[1] See section 3.1.0.2 "Parameter Validation". + + Append the following to section 3.5.1: + + "An on-screen rendering surface may also be created by calling + + EGLSurface eglCreateWindowSurface( + EGLDisplay dpy, + EGLConfig config, + EGLNativeWindowType win, + const EGLint *attrib_list); + + The behavior of eglCreateWindowSurface is identical to that of + eglCreatePlatformWindowSurfaceEXT except that the set of platforms to + which <dpy> is permitted to belong, as well as the actual type of <win>, + are implementation specific. + + In section 3.5.4 "Creating Native Pixmap Rendering Surfaces", replace the + third paragraph, which begins with "Using the platform-specific type" and + ends with "render into this surface", with the following: + + "Then call + + EGLSurface eglCreatePlatformPixmapSurfaceEXT( + EGLDisplay dpy, + EGLConfig config, + void *native_pixmap, + const EGLint *attrib_list); + + eglCreatePlatformPixmapSurfaceEXT creates an offscreen EGLSurface and + returns a handle to it. Any EGL context created with a compatible + EGLConfig can be used to render into this surface. + + <native_pixmap> must belong to the same platform as <dpy>, and EGL + considers the returned EGLSurface as belonging to that same platform. The + extension that defines the platform to which <dpy> belongs also defines + the requirements for the <native_pixmap> parameter." + + In the remainder of section 3.5.4, replace each occurrence of + 'eglCreatePixmapSurface' with 'eglCreatePlatformPixmapSurfaceEXT' and each + occurence of 'eglCreateWindowSurface' with + 'eglCreatePlatformWindowSurfaceEXT'. + + Insert the sentence below after the first sentence of the last paragraph + of section 3.5.4: + + "If <dpy> and <native_pixmap> do not belong to the same platform, then + undefined behavior occurs. [1]" + + Add the following footnote to section 3.5.3: + + "[1] See section 3.1.0.2 "Parameter Validation". + + Append the following to section 3.5.2: + + "An offscreen rendering surface may also be created by calling + + EGLSurface eglCreatePixmapSurface( + EGLDisplay dpy, + EGLConfig config, + EGLNativePixmapType pixmap, + const EGLint *attrib_list); + + The behavior of eglCreatePixmapSurface is identical to that of + eglCreatePlatformPixmapSurfaceEXT except that the set of platforms to + which <dpy> is permitted to belong, as well as the actual type of + <pixmap>, are implementation specific. + +Issues + + 1. What rules define how EGL resources are shared among displays belonging + to different platforms? + + RESOLVED: Neither the EGL 1.4 specification nor any extension allow EGL + resources to be shared among displays. This extension does not remove + that restriction. + + 2. Rather than define the new function eglGetPlatformDisplayEXT(), should + this extension instead define new thread-local state for the currently + bound platform and an associated binding function, such as + eglBindPlatformEXT()? + + RESOLVED: No, for the following reasons. + + - A current trend among the Khronos workgroups is to remove use of + global state by introducing bindless objects. Introducing a new + thread-local binding point defies that trend. + + - Additional specification language would be required to define + the interactions between the currently bound platform and all + EGL functions that accept an EGLDisplay. (For example, if the + currently bound platform is Wayland, then what is the result of + calling eglCreateWindowSurface() with a display and native + window belonging to X11?) By choosing to not introduce the + notion of a "currently bound platform", we obtain a cleaner + extension specification and eliminate for EGL users a class of + potential bugs. + + 3. Should this extension define the notion of a default platform? + + RESOLVED: No. eglGetDisplay() can be used if a default platform is + needed. + + 4. Rather than define the new functions + eglCreatePlatform{Window,Pixmap}SurfaceEXT(), should we instead + redefine the EGLNative* types in eglplatform.h as void*? + + RESOLVED: No, this introduces problems for X11 applications. + + Suppose that a 64-bit X11 application is compiled against an old EGL + library (where EGLNativeWindowType is a typedef for XID, which is in + turn a typedef for a 64-bit unsigned integer on Fedora 18) and then + attempts to run against a new EGL library (where EGLNativeType is + a typedef for void*). To preserve the ABI of eglCreateWindowSurface() + in this situation, the new EGL library must re-interpret the + <native_window> parameter as an integer. + + However, this preservation of the ABI breaks source compatibility for + existing X11 applications. To successfully compile, each call to + + eglCreateWindowSurface(dpy, window, attribs) + + in existing X11 application source code would need to be replaced with + + eglCreateWindowSurface(dpy, (void*) window, attribs) . + + Requiring such widespread code modifications would be an unnecessary + burden to developers and Linux package maintainers. + +Revision History + + Version 9, 2014.01.09 (Jon Leech) + - Fix typo eglGetDisplayPlatformEXT -> eglGetPlatformDisplayEXT + + Version 8, 2013.07.03 (Chad Versace) + - Add "Extension Type" section, required by EGL_EXT_client_extensions v9. + + Version 7, 2013.06.07 (Chad Versace) + - Fix some awkward text (s/the EGL/EGL/). + - Remove text "attribute names are defined by platform-specific + extensions". + + Version 6, 2013.06.07 (Chad Versace) + - To "Dependencies" section, expand text that discusses + EGL_EXT_client_extensions. + + Version 5, 2013.05.18 (Chad Versace) + - Removed restriction that "attribute names are defined only by + platform-specific extensions". + - Resolve issue 3 as NO. + - Clarified some text and fixed grammatical errors. + + Version 4, 2013.05.14 (Chad Versace) + - Add <attrib_list> parameter to eglGetPlatformDisplayEXT, per + feedback at the April Khronos F2F. + + Version 3, 2013.04.26 (Chad Versace) + - Add issues 2, 3, 4. + + Version 2, 2013.03.24 (Chad Versace) + - Complete draft by adding text for pixmaps. + - The footnotes regarding undefined behavior, simplify them by + simply referring to section 3.1.0.2. + - Add issue 1 from Eric Anholt <eric@anholt.net>. + - Fix spelling and formatting errors. + + Version 1, 2013.03.13 (Chad Versace) + - Incomplete draft posted for review diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_device.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_device.txt new file mode 100644 index 0000000..45c4fe3 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_device.txt @@ -0,0 +1,161 @@ +Name + + EXT_platform_device + +Name Strings + + EGL_EXT_platform_device + +Contributors + + James Jones + Daniel Kartch + +Contacts + + James Jones, NVIDIA (jajones 'at' nvidia.com) + +Status + + Complete + +Version + + Version 6 - May 16th, 2014 + +Number + + EGL Extension #73 + +Extension Type + + EGL client extension + +Dependencies + + Requires EGL_EXT_device_base + + Requires EGL_EXT_platform_base or EGL 1.5 + + Written against the wording of EGL 1.5 + +Overview + + Increasingly, EGL and its client APIs are being used in place of + "native" rendering APIs to implement the basic graphics + functionality of native windowing systems. This creates demand + for a method to initialize EGL displays and surfaces directly on + top of native GPU or device objects rather than native window + system objects. The mechanics of enumerating the underlying + native devices and constructing EGL displays and surfaces from + them have been solved in various platform and implementation- + specific ways. The EGL device family of extensions offers a + standardized framework for bootstrapping EGL without the use of + any underlying "native" APIs or functionality. + + This extension defines a method to create an EGLDisplay from an + EGLDeviceEXT by treating the EGLDeviceEXT as an EGLNativeDisplay + object. + +New Types + + None + +New Functions + + None + +New Tokens + + Accepted by the <platform> parameter of eglGetPlatformDisplayEXT + and eglGetPlatformDisplay: + + EGL_PLATFORM_DEVICE_EXT 0x313F + +Replace the last paragraph of section 2.1 "Native Window System and +Rendering APIs" + + "This specification defines only the EGLDeviceEXT platform, and + behavior specific to it. Implementations may support other + platforms, but their existence and behavior is defined by + extensions. To detect support for other platforms, clients should + query the EGL_EXTENSIONS string of EGL_NO_DISPLAY using + eglQueryString (see section 3.3). + +Replace the second sentence of the paragraph following the +eglGetPlatformDisplay prototype + + "The only valid value for <platform> is EGL_PLATFORM_DEVICE_EXT. + When <platform> is EGL_PLATFORM_DEVICE_EXT, <native_display> must + be an EGLDeviceEXT object. Platform-specific extensions may + define other valid values for <platform>." + +Add the following sentence to the end of the second paragraph after +the eglCreatePlatformWindowSurface prototype. + + "There are no valid values of <native_window> when <dpy> belongs + to the EGL_PLATFORM_DEVICE_EXT platform." + +Add the following sentence to the end of the second paragraph after +the eglCreatePlatformPixmapSurface prototype. + + "There are no valid values of <native_pixmap> when <dpy> belongs + to the EGL_PLATFORM_DEVICE_EXT platform. + +Issues + + 1. Do EGLDevice-backed displays support window or pixmap surfaces? + If so, what native objects are they associated with? If not, + are EGLDevice-backed displays useful in any way? + + RESOLVED: This extension defines no method to create window or + pixmap surfaces on the EGLDeviceEXT platform. Other + extensions may define such functionality. Presumably, if + there are no other extensions that expose native window or + pixmap types associated with EGL devices, EGLDeviceEXT-backed + displays could expose EGLConfigs that only support rendering + to EGLStreamKHR or EGLPbuffer surfaces. + + 2. Should the EGL_PLATFORM_DEVICE_EXT platform be included in the + EGL specification as a special "blessed" platform, or exist + only as an extension like other platforms? + + RESOLVED: EGL devices are defined as part of the EGL + specification, so there's no reason to exclude their + associated platform from the core EGL specification. They are + not native objects, therefore they can not be referred to as a + native platform, even though they are used interchangeably + with native objects in this extension. + +Revision History: + + #6 (May 16th, 2014) James Jones + - Marked the extension complete + - Marked all issues resolved + + #5 (April 8th, 2014) James Jones + - Updated wording based on the EGL 1.5 spec + - Assigned values to tokens + + #4 (November 6th, 2013) James Jones + - Specified this is a device extension + - Requires, rather than interacts with EGL_EXT_platform_base + - Removed EGL_SUPPORTS_PLATFORM_DEVICE_EXT. There is no need + for a separate query now that the name string is listed in + the per-device extension string + + #3 (April 23rd, 2013) James Jones + - Fixed minor typos + + #2 (April 18th, 2013) James Jones + - Moved eglGetDisplayPointerEXT to a stand-alone extension + - Renamed from EGL_EXT_device_display to + EGL_EXT_platform_device + - Filled in the actual spec language modifications + - Replaced issue 2, since the original was moved to + EGL_EXT_display_attributes + - Reworded issue 1. + - Fixed some typos + + #1 (April 16th, 2013) James Jones + - Initial Draft diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_wayland.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_wayland.txt new file mode 100644 index 0000000..3e5c0fa --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_wayland.txt @@ -0,0 +1,135 @@ +Name + + EXT_platform_wayland + +Name Strings + + EGL_EXT_platform_wayland + +Contributors + + Chad Versace <chad.versace@intel.com> + +Contacts + + Chad Versace <chad.versace@intel.com> + +Status + + Complete + +Version + + Version 4, 2014-03-10 + +Number + + EGL Extension #63 + +Extension Type + + EGL client extension + +Dependencies + + Requires EGL_EXT_client_extensions to query its existence without + a display. + + Requires EGL_EXT_platform_base. + + This extension is written against the wording of version 7 of the + EGL_EXT_platform_base specification. + +Overview + + This extension defines how to create EGL resources from native Wayland + resources using the functions defined by EGL_EXT_platform_base. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted as the <platform> argument of eglGetPlatformDisplayEXT: + + EGL_PLATFORM_WAYLAND_EXT 0x31D8 + +Additions to the EGL Specification + + None. + +New Behavior + + To determine if the EGL implementation supports this extension, clients + should query the EGL_EXTENSIONS string of EGL_NO_DISPLAY. + + To obtain an EGLDisplay backed by a Wayland display, call + eglGetPlatformDisplayEXT with <platform> set to EGL_PLATFORM_WAYLAND_EXT. The + <native_display> parameter specifies the Wayland display to use and must + either point to a `struct wl_display` or be EGL_DEFAULT_DISPLAY. If + <native_display> is EGL_DEFAULT_DISPLAY, then EGL will create a new + wl_display structure by connecting to the default Wayland socket. The + manual page wl_display_connect(3) defines the location of the default + Wayland socket. + + To obtain an on-screen rendering surface from a Wayland window, call + eglCreatePlatformWindowSurfaceEXT with a <dpy> that belongs to Wayland and + a <native_window> that points to a `struct wl_egl_surface`. + + It is not valid to call eglCreatePlatformPixmapSurfaceEXT with a <dpy> + that belongs to Wayland. Any such call fails and generates + EGL_BAD_PARAMETER. + +Issues + + 1. Should this extension permit EGL_DEFAULT_DISPLAY as input to + eglGetPlatformDisplayEXT()? + + RESOLUTION: Yes. When given EGL_DEFAULT_DISPLAY, eglGetPlatformDisplayEXT + returns a display backed by the default Wayland display. + + 2. Should this extension support creation EGLPixmap resources from Wayland + pixmaps? + + RESOLVED. No. Wayland has no pixmap type. + + 3. Should the extension namespace be EXT or MESA? + + The only shipping EGL implementation today (2013-04-26) that supports + Wayland is Mesa. However, perhaps the extension should reside in the + EXT namespace in expectation that other vendors will also begin + supporting Wayland. + + RESOLVED. Use the EXT namespace because other vendors have expressed + interest in Wayland. + +Revision History + + Version 4, 2014-03-10(Chad Versace) + - Change resolution of issue #1 from "no" to "yes". Now + eglGetPlatformDisplayEXT accepts EGL_DEFAULT_DISPLAY for Wayland. + - Explain in more detail how EGL connects to the default Wayland + display. + + Version 3, 2013-10-16 (Chad Versace) + - Resolve issue #3 to use EXT namespace. + + Version 2, 2013-09-12 (Chad Versace) + - Update to wording of version 7 of EGL_EXT_platform_base spec. + - Add section "Extension Type". + - Rephrase the discussion of how to create a Wayland EGLDisplay + to follow the analogous discussion in the published + EGL_EXT_platform_x11 spec. + - Change resolution of issue 1 from yes to no, because of likely type + mismatch between EGL_DEFAULT_DISPLAY_TYPE and void*. + + Version 1, 2013-04-26 (Chad Versace) + - Initial draft + +# vim:ai:et:sw=4:ts=4: + diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_x11.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_x11.txt new file mode 100644 index 0000000..19bfc35 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_x11.txt @@ -0,0 +1,414 @@ +Name + + EXT_platform_x11 + +Name Strings + + EGL_EXT_platform_x11 + +Contributors + + Chad Versace <chad.versace@intel.com> + James Jones <jajones@nvidia.com> + +Contacts + + Chad Versace <chad.versace@intel.com> + +Status + + Complete + +Version + + Version 13, 2014-03-10 + +Number + + EGL Extension #59 + +Extension Type + + EGL client extension + +Dependencies + + Requires EGL_EXT_client_extensions to query its existence without + a display. + + Requires EGL_EXT_platform_base. + + This extension is written against the wording of version 7 of the + EGL_EXT_platform_base specification. + +Overview + + This extension defines how to create EGL resources from native X11 + resources using the functions defined by EGL_EXT_platform_base. + + This extension defines only how to create EGL resources from Xlib + resources. It does not define how to do so from xcb resources. All X11 + types discussed here are defined by the header `Xlib.h`. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted as the <platform> argument of eglGetPlatformDisplayEXT: + + EGL_PLATFORM_X11_EXT 0x31D5 + + Accepted as an attribute name in the <attrib_list> argument of + eglGetPlatformDisplayEXT: + + EGL_PLATFORM_X11_SCREEN_EXT 0x31D6 + +Additions to the EGL Specification + + None. + +New Behavior + + To determine if the EGL implementation supports this extension, clients + should query the EGL_EXTENSIONS string of EGL_NO_DISPLAY. + + On the X11 platform, an EGLDisplay refers to a specific X11 screen rather + than an X11 display connection. This is the case because separate X11 + screens, even when belonging to the same X11 display connection, may + reside on different GPUs and/or be driven by different drivers. Therefore, + different X11 screens may have different EGL capabilities. + + To obtain an EGLDisplay backed by an X11 screen, call + eglGetPlatformDisplayEXT with <platform> set to EGL_PLATFORM_X11_EXT. The + <native_display> parameter specifies the X11 display connection to use, and + must point to a valid X11 `Display` or be NULL. If <native_display> is + EGL_DEFAULT_DISPLAY, then EGL will create [1] a connection to the default + X11 display. The environment variable DISPLAY determines the default X11 + display as described in the manual page for XOpenDisplay(3). The value of + attribute EGL_PLATFORM_X11_SCREEN_EXT specifies the X11 screen to use. If + the attribute is omitted from <attrib_list>, then the display connection's + default screen is used. Otherwise, the attribute's value must be a valid + screen on the display connection. If the attribute's value is not a valid + screen, then an EGL_BAD_ATTRIBUTE error is generated. + + [fn1] The method by which EGL creates a connection to the default X11 + display is an internal implementation detail. The implementation may use + XOpenDisplay, xcb_connect, or any other method. + + To obtain an on-screen rendering surface from an X11 Window, call + eglCreatePlatformWindowSurfaceEXT with a <dpy> that belongs to X11 and + a <native_window> that points to an X11 Window. + + To obtain an offscreen rendering surface from an X11 Pixmap, call + eglCreatePlatformPixmapSurfaceEXT with a <dpy> that belongs to X11 and + a <native_pixmap> that points to an X11 Pixmap. + +Issues + + 1. Should this extension permit EGL_DEFAULT_DISPLAY as input to + eglGetPlatformDisplayEXT()? + + RESOLVED. Yes. When given EGL_DEFAULT_DISPLAY, eglGetPlatformDisplayEXT + returns an EGLDisplay backed by the default X11 display. + + 2. When given EGL_DEFAULT_DISPLAY, does eglGetPlatformDisplayEXT reuse an + existing X11 display connection or create a new one? + + RESOLVED. eglGetPlatformDisplayEXT creates a new connection because the + alternative is infeasible. EGL cannot reliably detect if the client + process already has a X11 display connection. + + +Example Code + + // This example program creates two EGL surfaces: one from an X11 Window + // and the other from an X11 Pixmap. + // + // If the macro USE_EGL_EXT_PLATFORM_X11 is defined, then the program + // creates the surfaces using the methods defined in this specification. + // Otherwise, it uses the methods defined by the EGL 1.4 specification. + // + // Compile with `cc -std=c99 example.c -lX11 -lEGL`. + + #include <stdlib.h> + #include <string.h> + + #include <EGL/egl.h> + #include <X11/Xlib.h> + + struct my_display { + Display *x11; + EGLDisplay egl; + }; + + struct my_config { + struct my_display dpy; + XVisualInfo *x11; + Colormap colormap; + EGLConfig egl; + }; + + struct my_window { + struct my_config config; + Window x11; + EGLSurface egl; + }; + + struct my_pixmap { + struct my_config config; + Pixmap x11; + EGLSurface egl; + }; + + static void + check_extensions(void) + { + #ifdef USE_EGL_EXT_PLATFORM_X11 + const char *client_extensions = eglQueryString(EGL_NO_DISPLAY, EGL_EXTENSIONS); + + if (!client_extensions) { + // EGL_EXT_client_extensions is unsupported. + abort(); + } + if (!strstr(client_extensions, "EGL_EXT_platform_x11")) { + abort(); + } + #endif + } + + static struct my_display + get_display(void) + { + struct my_display dpy; + + dpy.x11 = XOpenDisplay(NULL); + if (!dpy.x11) { + abort(); + } + + #ifdef USE_EGL_EXT_PLATFORM_X11 + dpy.egl = eglGetPlatformDisplayEXT(EGL_PLATFORM_X11_EXT, dpy.x11, + NULL); + #else + dpy.egl = eglGetDisplay(dpy.x11); + #endif + + if (dpy.egl == EGL_NO_DISPLAY) { + abort(); + } + + EGLint major, minor; + if (!eglInitialize(dpy.egl, &major, &minor)) { + abort(); + } + + return dpy; + } + + static struct my_config + get_config(struct my_display dpy) + { + struct my_config config = { + .dpy = dpy, + }; + + EGLint egl_config_attribs[] = { + EGL_BUFFER_SIZE, 32, + EGL_RED_SIZE, 8, + EGL_GREEN_SIZE, 8, + EGL_BLUE_SIZE, 8, + EGL_ALPHA_SIZE, 8, + + EGL_DEPTH_SIZE, EGL_DONT_CARE, + EGL_STENCIL_SIZE, EGL_DONT_CARE, + + EGL_RENDERABLE_TYPE, EGL_OPENGL_ES2_BIT, + EGL_SURFACE_TYPE, EGL_WINDOW_BIT | EGL_PIXMAP_BIT, + EGL_NONE, + }; + + EGLint num_configs; + if (!eglChooseConfig(dpy.egl, + egl_config_attribs, + &config.egl, 1, + &num_configs)) { + abort(); + } + if (num_configs == 0) { + abort(); + } + + XVisualInfo x11_visual_info_template; + if (!eglGetConfigAttrib(dpy.egl, + config.egl, + EGL_NATIVE_VISUAL_ID, + (EGLint*) &x11_visual_info_template.visualid)) { + abort(); + } + + int num_visuals; + config.x11 = XGetVisualInfo(dpy.x11, + VisualIDMask, + &x11_visual_info_template, + &num_visuals); + if (!config.x11) { + abort(); + } + + config.colormap = XCreateColormap(dpy.x11, + RootWindow(dpy.x11, 0), + config.x11->visual, + AllocNone); + if (config.colormap == None) { + abort(); + } + + return config; + } + + static struct my_window + get_window(struct my_config config) + { + XSetWindowAttributes attr; + unsigned long mask; + + struct my_window window = { + .config = config, + }; + + attr.colormap = config.colormap; + mask = CWColormap; + + window.x11 = XCreateWindow(config.dpy.x11, + DefaultRootWindow(config.dpy.x11), // parent + 0, 0, // x, y + 256, 256, // width, height + 0, // border_width + config.x11->depth, + InputOutput, // class + config.x11->visual, + mask, // valuemask + &attr); // attributes + if (!window.x11) { + abort(); + } + + #ifdef USE_EGL_EXT_PLATFORM_X11 + window.egl = eglCreatePlatformWindowSurfaceEXT(config.dpy.egl, + config.egl, + &window.x11, + NULL); + #else + window.egl = eglCreateWindowSurface(config.dpy.egl, + config.egl, + window.x11, + NULL); + #endif + + if (window.egl == EGL_NO_SURFACE) { + abort(); + } + + return window; + } + + static struct my_pixmap + get_pixmap(struct my_config config) + { + struct my_pixmap pixmap = { + .config = config, + }; + + pixmap.x11 = XCreatePixmap(config.dpy.x11, + DefaultRootWindow(config.dpy.x11), + 256, 256, // width, height + config.x11->depth); + if (!pixmap.x11) { + abort(); + } + + #ifdef USE_EGL_EXT_PLATFORM_X11 + pixmap.egl = eglCreatePlatformPixmapSurfaceEXT(config.dpy.egl, + config.egl, + &pixmap.x11, + NULL); + #else + pixmap.egl = eglCreatePixmapSurface(config.dpy.egl, + config.egl, + pixmap.x11, + NULL); + #endif + + if (pixmap.egl == EGL_NO_SURFACE) { + abort(); + } + + return pixmap; + } + + int + main(void) + { + check_extensions(); + + struct my_display dpy = get_display(); + struct my_config config = get_config(dpy); + struct my_window window = get_window(config); + struct my_pixmap pixmap = get_pixmap(config); + + return 0; + } + +Revision History + + Version 13, 2014-03-10 (Chad Versace) + - Update text to reflect resolution of issue #1. State that + <native_display> may be EGL_DEFAULT_DISPLAY. + - Explain in more detail how EGL connects to the default X11 display. + - Add and resolve issue #2. + + Version 12, 2014-02-11 (Chad Versace) + - Fix 2nd argument to XCreatePixmap in example code. + + Version 11, 2013-07-10 (Jon Leech) + - Fix enumerant values and assign extension number for publication + (Bug 10240). + + Version 10, 2013-07-03 (Chad Versace) + - Add "Extension Type" section, required by EGL_EXT_client_extensions v9. + + Version 9, 2013-06-11 (Chad Versace) + - Replace reference to version 5 of EGL_EXT_platform_base to version 7. + - Add James Jones as contributor. + + Version 8, 2013-06-07 (Chad Versace) + - Assign enum values to new tokens. + + Version 7, 2013-06-07 (Chad Versace) + - Explicitly require EGL_EXT_client_extensions in the Dependencies + section. + + Version 6, 2013-06-07 (Chad Versace) + - Add attribute EGL_PLATFORM_X11_SCREEN_EXT. + + Version 5, 2013-06-07 (Chad Versace) + - Rephrase against version 7 of EGL_EXT_platform_base. + + Version 4, 2013-06-07 (Chad Versace) + - Fix compilation of example code. + + Version 3, 2013-04-26 (Chad Versace) + - Add missing EXT suffix to new token. + + Version 2, 2013-04-22 (Chad Versace) + - Discuss EGL_DEFAULT_DISPLAY. + - Fix minor typographical and grammatical errors. + + Version 1, 2013.03.24 (Chad Versace) + - First draft diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_xcb.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_xcb.txt new file mode 100644 index 0000000..1411db6 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_xcb.txt @@ -0,0 +1,382 @@ +Name + + EXT_platform_xcb + +Name Strings + + EGL_EXT_platform_xcb + +Contributors + + Yuxuan Shui <yshuiv7@gmail.com> + +Contacts + + Yuxuan Shui <yshuiv7@gmail.com> + +Status + + Complete + +Version + + Version 1, 2020-08-28 + +Number + + EGL Extension #141 + +Extension Type + + EGL client extension + +Dependencies + + Requires EGL_EXT_client_extensions to query its existence without + a display. + + Requires EGL_EXT_platform_base. + + This extension is written against the wording of version 9 of the + EGL_EXT_platform_base specification. + +Overview + + This extension defines how to create EGL resources from native X11 + resources using the functions defined by EGL_EXT_platform_base. + + The native X11 resources required by this extension are xcb resources. + All X11 types discussed here are defined by the header `xcb.h`. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted as the <platform> argument of eglGetPlatformDisplayEXT: + + EGL_PLATFORM_XCB_EXT 0x31DC + + Accepted as an attribute name in the <attrib_list> argument of + eglGetPlatformDisplayEXT: + + EGL_PLATFORM_XCB_SCREEN_EXT 0x31DE + +Additions to the EGL Specification + + None. + +New Behavior + + To determine if the EGL implementation supports this extension, clients + should query the EGL_EXTENSIONS string of EGL_NO_DISPLAY. + + This extension defines the same set of behaviors as EGL_EXT_platform_x11, + except Xlib types are replaced with xcb types. + + To obtain an EGLDisplay backed by an X11 screen, call + eglGetPlatformDisplayEXT with <platform> set to EGL_PLATFORM_XCB_EXT. The + <native_display> parameter specifies the X11 display connection to use, and + must point to a valid xcb `xcb_connection_t` or be EGL_DEFAULT_DISPLAY. If + <native_display> is EGL_DEFAULT_DISPLAY, then EGL will create [1] a + connection to the default X11 display. The environment variable DISPLAY + determines the default X11 display, and, unless overridden by the + EGL_PLATFORM_XCB_SCREEN_EXT attribute, the default X11 screen - as + described in the documentation of `xcb_connect`. If the environment + variable DISPLAY is not present in this case, the result is undefined. The + value of attribute EGL_PLATFORM_XCB_SCREEN_EXT specifies the X11 screen to + use. If the attribute is omitted from <attrib_list>, and <native_display> + is not EGL_DEFAULT_DISPLAY, then screen 0 will be used. Otherwise, the + attribute's value must be a valid screen on the display connection. If the + attribute's value is not a valid screen, then an EGL_BAD_ATTRIBUTE error is + generated. + + [fn1] The method by which EGL creates a connection to the default X11 + display is an internal implementation detail. The implementation may use + xcb_connect, or any other method. + + To obtain an on-screen rendering surface from an X11 Window, call + eglCreatePlatformWindowSurfaceEXT with a <dpy> that belongs to X11 and + a <native_window> that points to an xcb_window_t. + + To obtain an offscreen rendering surface from an X11 Pixmap, call + eglCreatePlatformPixmapSurfaceEXT with a <dpy> that belongs to X11 and + a <native_pixmap> that points to an xcb_pixmap_t. + +Issues + + 1. As xcb_connection_t doesn't carry a screen number, how should a screen be + selected in eglGetPlatformDisplayEXT()? + + RESOLVED. The screen will be chosen with the following logic: + + * If EGL_PLATFORM_XCB_SCREEN_EXT is specified, it will always take + precedence. Whether <native_display> is EGL_DEFAULT_DISPLAY or not. + + * Otherwise, if <native_display> is not EGL_DEFAULT_DISPLAY, then + screen 0 will be used. + + * Otherwise, which is to say <native_display> is EGL_DEFAULT_DISPLAY. + Then the DISPLAY environment variable will be used to determine the + screen number. If DISPLAY contains a screen number, that will be + used; if not, then 0 will be used. + + * If the DISPLAY environment variable is not present when + <native_display> is EGL_DEFAULT_DISPLAY, the result will be undefined. + +Example Code + + // This example program creates two EGL surfaces: one from an X11 Window + // and the other from an X11 Pixmap. + // + // Compile with `cc example.c -lxcb -lEGL`. + + #include <stddef.h> + #include <stdlib.h> + #include <string.h> + + #include <EGL/egl.h> + #include <EGL/eglext.h> + #include <xcb/xcb.h> + + struct my_display { + xcb_connection_t *x11; + int screen; + int root_of_screen; + EGLDisplay egl; + }; + + struct my_config { + struct my_display dpy; + xcb_colormap_t colormap; + xcb_visualid_t visualid; + int depth; + EGLConfig egl; + }; + + struct my_window { + struct my_config config; + xcb_window_t x11; + EGLSurface egl; + }; + + struct my_pixmap { + struct my_config config; + xcb_pixmap_t x11; + EGLSurface egl; + }; + + static void check_extensions(void) { + const char *client_extensions = + eglQueryString(EGL_NO_DISPLAY, EGL_EXTENSIONS); + + if (!client_extensions) { + // EGL_EXT_client_extensions is unsupported. + abort(); + } + if (!strstr(client_extensions, "EGL_EXT_platform_xcb")) { + abort(); + } + } + + xcb_screen_t *get_screen(xcb_connection_t *c, int screen) { + xcb_screen_iterator_t iter; + + iter = xcb_setup_roots_iterator(xcb_get_setup(c)); + for (; iter.rem; --screen, xcb_screen_next(&iter)) + if (screen == 0) + return iter.data; + + return NULL; + } + + int get_visual_depth(xcb_connection_t *c, xcb_visualid_t visual) { + const xcb_setup_t *setup = xcb_get_setup(c); + for (xcb_screen_iterator_t i = xcb_setup_roots_iterator(setup); i.rem; + xcb_screen_next(&i)) { + for (xcb_depth_iterator_t j = + xcb_screen_allowed_depths_iterator(i.data); + j.rem; xcb_depth_next(&j)) { + const int len = xcb_depth_visuals_length(j.data); + const xcb_visualtype_t *visuals = xcb_depth_visuals(j.data); + for (int k = 0; k < len; k++) { + if (visual == visuals[k].visual_id) { + return j.data->depth; + } + } + } + } + abort(); + } + + static struct my_display get_display(void) { + struct my_display dpy; + + dpy.x11 = xcb_connect(NULL, &dpy.screen); + if (!dpy.x11) { + abort(); + } + + dpy.egl = eglGetPlatformDisplayEXT(EGL_PLATFORM_XCB_EXT, dpy.x11, + (const EGLint[]){ + EGL_PLATFORM_XCB_SCREEN_EXT, + dpy.screen, + EGL_NONE, + }); + + if (dpy.egl == EGL_NO_DISPLAY) { + abort(); + } + + EGLint major, minor; + if (!eglInitialize(dpy.egl, &major, &minor)) { + abort(); + } + + xcb_screen_t *screen = get_screen(dpy.x11, dpy.screen); + dpy.root_of_screen = screen->root; + + return dpy; + } + + static struct my_config get_config(struct my_display dpy) { + struct my_config config = { + .dpy = dpy, + }; + + EGLint egl_config_attribs[] = { + EGL_BUFFER_SIZE, + 32, + EGL_RED_SIZE, + 8, + EGL_GREEN_SIZE, + 8, + EGL_BLUE_SIZE, + 8, + EGL_ALPHA_SIZE, + 8, + + EGL_DEPTH_SIZE, + EGL_DONT_CARE, + EGL_STENCIL_SIZE, + EGL_DONT_CARE, + + EGL_RENDERABLE_TYPE, + EGL_OPENGL_ES2_BIT, + EGL_SURFACE_TYPE, + EGL_WINDOW_BIT | EGL_PIXMAP_BIT, + EGL_NONE, + }; + + EGLint num_configs; + if (!eglChooseConfig(dpy.egl, egl_config_attribs, &config.egl, 1, + &num_configs)) { + abort(); + } + if (num_configs == 0) { + abort(); + } + + if (!eglGetConfigAttrib(dpy.egl, config.egl, EGL_NATIVE_VISUAL_ID, + (EGLint *)&config.visualid)) { + abort(); + } + + config.colormap = xcb_generate_id(dpy.x11); + if (xcb_request_check(dpy.x11, + xcb_create_colormap_checked( + dpy.x11, XCB_COLORMAP_ALLOC_NONE, config.colormap, + dpy.root_of_screen, config.visualid))) { + abort(); + } + + config.depth = get_visual_depth(dpy.x11, config.visualid); + + return config; + } + + static struct my_window get_window(struct my_config config) { + xcb_generic_error_t *e; + + struct my_window window = { + .config = config, + }; + + window.x11 = xcb_generate_id(config.dpy.x11); + e = xcb_request_check( + config.dpy.x11, + xcb_create_window_checked(config.dpy.x11, // connection + XCB_COPY_FROM_PARENT, // depth + window.x11, // window id + config.dpy.root_of_screen, // root + 0, 0, // x, y + 256, 256, // width, height + 0, // border_width + XCB_WINDOW_CLASS_INPUT_OUTPUT, // class + config.visualid, // visual + XCB_CW_COLORMAP, // mask + (const int[]){ + config.colormap, + XCB_NONE, + })); + if (e) { + abort(); + } + + window.egl = eglCreatePlatformWindowSurfaceEXT(config.dpy.egl, config.egl, + &window.x11, NULL); + + if (window.egl == EGL_NO_SURFACE) { + abort(); + } + + return window; + } + + static struct my_pixmap get_pixmap(struct my_config config) { + struct my_pixmap pixmap = { + .config = config, + }; + + pixmap.x11 = xcb_generate_id(config.dpy.x11); + if (xcb_request_check( + config.dpy.x11, + xcb_create_pixmap(config.dpy.x11, config.depth, pixmap.x11, + config.dpy.root_of_screen, 256, 256))) { + abort(); + } + + pixmap.egl = eglCreatePlatformPixmapSurfaceEXT(config.dpy.egl, config.egl, + &pixmap.x11, NULL); + + if (pixmap.egl == EGL_NO_SURFACE) { + abort(); + } + + return pixmap; + } + + int main(void) { + check_extensions(); + + struct my_display dpy = get_display(); + struct my_config config = get_config(dpy); + struct my_window window = get_window(config); + struct my_pixmap pixmap = get_pixmap(config); + + return 0; + } + +Revision History + + Version 2, 2020.10.13 (Yuxuan Shui) + - Some wording changes + - Address the question about screen selection + + Version 1, 2020.08.28 (Yuxuan Shui) + - First draft diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_present_opaque.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_present_opaque.txt new file mode 100644 index 0000000..de2f6d8 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_present_opaque.txt @@ -0,0 +1,118 @@ +Name + + EXT_present_opaque + +Name Strings + + EGL_EXT_present_opaque + +Contributors + + Eric Engestrom + +Contacts + + Eric Engestrom (eric 'at' engestrom.ch) + +IP Status + + No known IP claims. + +Status + + Complete + +Version + + #1, August 8, 2021 + +Number + + EGL Extension #146 + +Extension Type + + EGL display extension + +Dependencies + + Requires EGL 1.4 and EGL_KHR_image_base extension + + This extension is written against the wording of the EGL 1.4 + specification, and EGL_KHR_image_base version 6. + +Overview + + This extension adds a new EGL surface attribute EGL_PRESENT_OPAQUE_EXT + to indicate that the surface should be presented as opaque, + disregarding any alpha channel if present. + If surface attribute EGL_PRESENT_OPAQUE_EXT is EGL_TRUE, then the + surface will be presented as opaque. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + New EGLSurface attribute name: + + EGL_PRESENT_OPAQUE_EXT 0x31DF + + +Additions to Chapter 3 of the EGL 1.4 Specification (Rendering Surfaces) + + Change the second paragraph in section 3.5 on p. 28 (describing + eglCreateWindowSurface): + + "Attributes that can be specified in attrib list include EGL_RENDER_BUFFER, + EGL_PRESENT_OPAQUE_EXT, EGL_VG_COLORSPACE, and EGL_VG_ALPHA_FORMAT." + + Add the following paragraph in section 3.5 on p. 28 before + "EGL_VG_COLORSPACE specifies the color space used by OpenVG" + (describing eglCreateWindowSurface attrib_list): + + "EGL_PRESENT_OPAQUE_EXT specifies the presentation opacity mode + of the window surface. If its value is EGL_TRUE, then the + surface's alpha channel (if any) will be ignored and considered + fully opaque. If its value is EGL_FALSE, then the compositor + doesn't change its behaviour, and considers the surface's alpha + channel the same way as if the extension wasn't implemented. The + default value of EGL_PRESENT_OPAQUE_EXT is EGL_FALSE." + + Add to Table 3.5: Queryable surface attributes and types on p. 37 + + EGL_PRESENT_OPAQUE_EXT boolean Surface presentation opacity mode + + Add following the second paragraph in section 3.6 on p. 39 (describing + eglQuerySurface): + + "Querying EGL_PRESENT_OPAQUE_EXT returns the presentation + opacity mode of the surface. The presentation opacity mode of + window surfaces is specified in eglCreateWindowSurface. The + presentation opacity mode of pbuffer and pixmap surfaces is + always EGL_FALSE." + + Add following after "which must be a valid native pixmap handle." in section 3.9.2 on + p. 53 (describing eglCopyBuffers): + + "If attribute EGL_PRESENT_OPAQUE_EXT of surface has value of EGL_TRUE, then + an EGL_BAD_ACCESS error is returned." + +Issues + + None + +Revision History + + Version 2, 2021-08-17 (Eric Engestrom) + - Re-worded the compositor's behaviour for EGL_FALSE. + - Marked extension as Complete. + + Version 1, 2021-08-08 (Eric Engestrom) + - Initial draft + diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_protected_content.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_protected_content.txt new file mode 100644 index 0000000..2421161 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_protected_content.txt @@ -0,0 +1,329 @@ +Name + + EXT_protected_content + +Name Strings + + EGL_EXT_protected_content + +Contributors + + Ramesh Viswanathan + Brian Ellis + Colin Sharp + Rajeev Kulkarni + Mohan Maiya + Maurice Ribble + Craig Donner + Jan-Harald Fredriksen + Daniel Koch + Michael Golds + Ray Smith + +Contacts + + Maurice Ribble (mribble 'at' qti.qualcomm.com) + +IP Status + + No known IP claims. + +Status + + Complete. + +Version + + Version 13, December 6, 2021 + +Number + + EGL Extension #97 + +Dependencies + + Requires EGL 1.4. + + Interactions with EGL_KHR_image_base extension. + + This extension is written against the wording of the EGL 1.4. + Specification (12/04/2013) + + This extension has interactions with EGL_EXT_protected_surface if that + extension is supported. The interactions are described in the main text. + +Overview + + This extension introduces the concept of protected contexts and protected + resources, specifically surfaces and EGLImages. Applications can choose at + creation time whether a context, surface or EGLImage is protected or not. + + A protected context is required to allow the GPU to operate on protected + resources, including protected surfaces and protected EGLImages. + + An explanation of undefined behavior in this extension: Several places + in this extension mention undefined behavior can result, which can + include program termination. The reason for this is because one way + to handle protected content is by using a protected virtual to physical + memory translation layer. With this sort of solution a system may generate + read or write faults when a non-protected source tries to access a protected + buffer. Depending on the system these faults might be ignored or they might + cause process termination. This undefined behavior should not include + actually allowing a transfer of data from a protected surface to a + non-protected surface. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted as an attribute name in the <attrib_list> parameter of + eglCreateContext, eglCreateWindowSurface, and eglCreateImageKHR; + and as an parameter of eglQuerySurface and eglQueryContext: + + EGL_PROTECTED_CONTENT_EXT 0x32C0 + + +Add a new section 2.7 entitled "Protected Content" at the end of Chapter 2 (EGL +Operation) + + "The attribute EGL_PROTECTED_CONTENT_EXT can be applied to EGL contexts, + EGL surfaces and EGLImages. If the attribute EGL_PROTECTED_CONTENT_EXT + is set to EGL_TRUE by the application, then the newly created EGL object + is said to be protected. A protected context is required to allow the + GPU to operate on protected resources, including protected surfaces and + protected EGLImages. + + GPU operations are grouped into pipeline stages. Pipeline stages can be + defined to be protected or not protected. Each stage defines + restrictions on whether it can read or write protected and unprotected + resources, as follows: + + When a GPU stage is protected, it: + - Can read from protected resources + - Can read from unprotected resources + - Can write to protected resources + - Can NOT write to unprotected resources + + When a GPU stage is not protected, it: + - Can NOT read from protected resources + - Can read from unprotected resources + - Can NOT write to protected resources + - Can write to unprotected resources + + Any accesses not following these restrictions will result in undefined + behavior. + + This extension does not specify which pipeline stages of a protected + context are protected or not. This is left to a client API extension to + define. All stages in a regular (not protected) context are not + protected. However, if EGL_EXT_protected_surface is also supported, a + regular (not protected) context will execute stages where one or more + protected resources is accessed as if it were a protected context. + + Note that the protection state of a stage may be left implementation + defined by a client API extension. This means that no guarantees can be + made about whether the stage will be protected or not protected. + Practically this means that the permitted operations for such a stage + are the intersection of the allowed operations for protected and not + protected stages, i.e it: + + - Can NOT read from protected resources + - Can read from unprotected resources + - Can NOT write to protected resources + - Can NOT write to unprotected resources + + Since this is not a very useful set of operations refer to the client API + extension to see what operations are actually allowed. + + This extension does not guarantee the implementation abides by a + system's digital rights management requirements. It must be verified + beyond the existence of this extension that the implementation of this + extension is trustworthy according to the requirements of a content + protection system." + +Additions to Chapter 3 of the EGL 1.4 Specification (Rendering Contexts) + + Change the fifth paragraph in section 3.7.1 Creating Rendering Contexts: + + "attrib list specifies a list of attributes for the context. The + list has the same structure as described for eglChooseConfig. + Attributes that can be specified in attrib list include + EGL_CONTEXT_CLIENT_VERSION and EGL_PROTECTED_CONTENT_EXT. The + EGL_CONTEXT_CLIENT_VERSION attribute may only be specified when + creating a OpenGL ES context (e.g. when the current rendering API is + EGL_OPENGL_ES_API)." + + Add the following paragraph in section 3.7.1 on p. 44 before "attrib list + may be NULL or empty (first attribute is EGL_NONE), in which case + attributes assume their default values as described below." + + "EGL_PROTECTED_CONTENT_EXT specifies the protected state of the new + context. If its value is EGL_TRUE, then the context is said to be + protected. If its value is EGL_FALSE, then the context is not + protected. See section 2.7 (Protected Content) for more information + about protected contexts. + + The default value of EGL_PROTECTED_CONTENT_EXT is EGL_FALSE." + + Add the following paragraph in section 3.7.4 Context Queries. Add after + the last paragraph after eglQueryContext queries. + + "Querying EGL_PROTECTED_CONTENT_EXT returns the current value" + +Additions to Chapter 3 of the EGL 1.4 Specification (Rendering Surfaces) + + Change the second paragraph in section 3.5 on p. 28 (describing + eglCreateWindowSurface): + + "Attributes that can be specified in attrib list include + EGL_RENDER_BUFFER, EGL_PROTECTED_CONTENT_EXT, EGL_VG_COLORSPACE, and + EGL_VG_ALPHA_FORMAT." + + Add the following paragraph in section 3.5 on p. 28 before + "EGL_VG_COLORSPACE specifies the color space used by OpenVG" (describing + eglCreateWindowSurface(attrib_list): + + "EGL_PROTECTED_CONTENT_EXT specifies the protected state of the + window surface. If its value is EGL_TRUE, then the surface content + is said to be protected. If its value is EGL_FALSE, then the surface + content is not protected. See section 2.7 (Protected Content) for + more information about protected and non-protected surfaces. + + Client APIs will not allow contents of protected surfaces to be + accessed by non-protected contexts in the system (including + non-secure software running on the CPU). Such operations will result + in undefined behavior. + + Calling eglSwapBuffers on such a protected surface will succeed, but + the contents may or may not be posted successfully depending on + whether those parts of the pipeline are capable of handling + protected content. Any disallowed operation will fail and result in + undefined behavior. + + The default value of EGL_PROTECTED_CONTENT_EXT is EGL_FALSE." + + Add the following paragraph in section 3.5.6 Surface Attributes. Add after + the last paragraph after eglQuerySurface attribute queries. + + "Querying EGL_PROTECTED_CONTENT_EXT returns the current value" + +Additions to EGL_KHR_image_base extension specification + + Add to section 2.5.1 Table bbb: + +-----------------------------+-------------------------+---------------+ + | Attribute | Description | Default Value | + +-----------------------------+-------------------------+---------------+ + | EGL_NONE | Marks the end of the | N/A | + | | attribute-value list | | + | EGL_IMAGE_PRESERVED_KHR | Whether to preserve | EGL_FALSE | + | | pixel data | | + | EGL_PROTECTED_CONTENT_EXT | Content protection | EGL_FALSE | + | | state | | + +-----------------------------+-------------------------+---------------+ + Table bbb. Legal attributes for eglCreateImageKHR <attrib_list> + parameter + + Add the following paragraph to section 2.5.1 before "Errors" (describing + eglCreateImageKHR): + + "If the value of attribute EGL_PROTECTED_CONTENT_EXT is EGL_TRUE + and the EGLImage sources can be guaranteed to be protected, then the + EGLImage is said to be protected. See section 2.7 (Protected Content) + for more information about protected resources including EGLImages. + + If the value of attribute EGL_PROTECTED_CONTENT_EXT is EGL_FALSE then: + + - If EGLImage sources are not protected, the EGLImage is said to be + not protected. See section 2.7 (Protected Content) for more + information about non-protected resources including EGLImages. + - If EGLImage sources are protected then the EGLImage content will + be inaccessible to any client context irrespective of whether the + context is protected or not. Trying to access such an EGLImage's + content will result in undefined behavior." + + Add the following to the Errors list in section 2.5.1 + + "If the value specified in <attrib_list> for EGL_PROTECTED_CONTENT_EXT + is EGL_TRUE, and EGL and its client is unable to make guarantees + regarding the protected state of the EGLImage source, the error + EGL_BAD_ACCESS is generated." + +Issues + 1) Can a protected context be shared with a non-protected context? + + RESOLVED - Yes. The rule that protected surfaces can only be used by + protected contexts still applies. An example use case is where + someone wants to render to unprotected textures within an unprotected + context and then share it with a protected context to be used as a texture. + + 2) Should all surfaces within a protected context be protected by default? + + RESOLVED - No, several implementations have limited amounts of protected + memory, so the API will require opting into protected memory. + + 3) Can these protected surfaces be used by stages other than fragment + shader stage? + + RESOLVED - Some hardware can't handle this so this behavior is undefined + unless there is explicit working in some new spec saying the behavior is + defined. This is put as an issue because this is an EGL extension and + should not be controlling OpenGL functionality. + + 4) Why is EGL_PROTECTED_CONTENT_EXT flag needed for EGLImages? + + RESOLVED - A few reasons for having an explicit flag instead + of inferring the protected status from EGLImage sources - + + 1) There are multiple EGL image extensions (EGL QCOM image, EGL + android image and so on) that accept buffers from external modules + instead of client resources or allow internally allocated memory. + For these use cases a protected attribute is useful, so we want to + keep this flag. + 2) An implementation might have a few non-standard setup steps that + need to be completed before a protected EGL image can be accessed. + This attribute along with a corresponding protected buffer will act + as a signal for the graphics driver to initiate/complete any such + steps. + 3) An application creating an image from an external resource may not + be aware of the fact that the resource is protected or may be unable + to access its content. The successful mapping of and access to a + protected buffer through an EGLImage will be predicated on the + buffer being protected, having a protected context and the intent of + the application to access that buffer by passing in EGL_TRUE for the + attribute EGL_PROTECTED_CONTENT_EXT. + + +Revision History + + Rev. Date Author Changes + ---- -------- -------- ---------------------------------------------- + 1 09/24/14 Ramesh Initial draft. + 2 11/20/14 Rajeev Second draft. + 3 03/07/16 mribble Make EXT and clean up for release. + 4 03/10/16 mribble Cleanup. + 5 03/18/16 mribble Fix issues brought up by Khronos group. + 6 03/24/16 mribble Resolved some small issues found by Jan-Harald. + 7 03/25/16 mribble Fix createContext wording. + 8 03/30/16 mribble Added issue 5. + 9 04/05/16 mribble Added issue 6 and better defined eglImage case. + 10 04/08/16 rsmith - Added general section on protected content. + Protected context, surface and image creation now + refer to the general protected content principles. + - Added explicit definition of which stages are + protected, including allowing for the protected + state of a stage to be undefined. + - Formalised interactions with + EGL_EXT_protected_surface. + - Removed references to the GPU protected mode, + including issue 3. + 11 04/10/16 mribble Merge and cleanup. + 12 04/14/16 Jon Leech Cleanup formatting, reflow paragraphs and + quote additions consistently. Assign extension + number. + 13 12/06/21 Jeff Vigil Add queries for protected content attribute. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_protected_surface.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_protected_surface.txt new file mode 100644 index 0000000..ec3665a --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_protected_surface.txt @@ -0,0 +1,230 @@ +Name + + EXT_protected_surface + +Name Strings + + EGL_EXT_protected_surface + +Contributors + + Frido Garritsen, Vivante + Yanjun Zhang, Vivante + Pontus Lidman, Marvell + Jesse Hall, Google + +Contacts + + Frido Garritsen (frido 'at' vivantecorp.com) + Yanjun Zhang (yzhang 'at' vivantecorp.com) + +Notice + + Copyright 2013 Vivante Corporation + +IP Status + + No known IP claims. + +Status + + Draft + +Version + + #7, January 20, 2014 + +Number + + EGL Extension #67 + +Dependencies + + Requires EGL 1.4 and EGL_KHR_image_base extension + + This extension is written against the wording of the EGL 1.4 + Specification (12/04/2013), and EGL_KHR_image_base spec. version 6. + +Overview + + This extension adds a new EGL surface attribute EGL_PROTECTED_CONTENT_EXT + to indicate if the content in the surface buffer is protected or not. + If surface attribute EGL_PROTECTED_CONTENT_EXT is EGL_TRUE, then the + surface content is only accessible to secure accesses. Any attempt to access + the buffer content non-securely will fail and result in undefined behavior + up to and including program termination. Also, any copy operations from the + protected surface to any non-protected surface by GPU are considered illegal. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + New EGLSurface attribute name: + + EGL_PROTECTED_CONTENT_EXT 0x32C0 + + +Additions to Chapter 3 of the EGL 1.4 Specification (Rendering Surfaces) + + Change the second paragraph in section 3.5 on p. 28 (describing eglCreateWindowSurface): + + "Attributes that can be specified in attrib list include EGL_RENDER_BUFFER, + EGL_PROTECTED_CONTENT_EXT, EGL_VG_COLORSPACE, and EGL_VG_ALPHA_FORMAT." + + Add the following paragraph in section 3.5 on p. 28 before "EGL_VG_COLORSPACE + specifies the color space used by OpenVG" (describing eglCreateWindowSurface + attrib_list): + + "EGL_PROTECTED_CONTENT_EXT specifies the protection state of the window + surface. If its value is EGL_TRUE, then the surface content resides in a + secure memory region. Secure surfaces may be written to by client APIs + using any combination of protected and non-protected input data. EGL and + client APIs will not allow contents of protected surfaces to be accessed + by non-secure devices in the system (including non-secure software + running on the CPU). They will also not allow the contents to be copied + to non-protected surfaces. Copies within a protected surface, or from one + protected surface to another, are allowed. eglSwapBuffers is allowed for + protected surfaces if and only if the window system is able to maintain + the security of the buffer contents. Any disallowed operation will + fail and result in undefined behavior, up to and including program + termination. If EGL_PROTECTED_CONTENT_EXT is EGL_FALSE, then the surface + content can be accessed by secure or non-secure devices and can be copied + to any other surfaces. The definition of secure and non-secure access is + up to the implementation and is out of scope of this specification. The + default value of EGL_PROTECTED_CONTENT_EXT is EGL_FALSE." + + Change the second paragraph in section 3.5 on p. 30 (describing + eglCreatePbufferSurface): + + "Attributes that can be specified in attrib list include EGL_WIDTH, + EGL_HEIGHT, EGL_LARGEST_PBUFFER, EGL_TEXTURE_FORMAT, EGL_TEXTURE_TARGET, + EGL_MIPMAP_TEXTURE, EGL_PROTECTED_CONTENT_EXT, EGL_VG_COLORSPACE, and + EGL_VG_ALPHA_FORMAT." + + Add following the second paragraph in section 3.5 on p. 31 (describing + eglCreatePbufferSurface attrib_list): + + "EGL_PROTECTED_CONTENT_EXT specifies the protection state of the pbuffer + surface. If its value is EGL_TRUE, then the surface content resides in a + secure memory region. Secure surfaces may be written to by client APIs + using any combination of protected and non-protected input data. EGL and + client APIs will not allow contents of protected surfaces to be accessed + by non-secure devices in the system (including non-secure software + running on the CPU). They will also not allow the contents to be copied + to non-protected surfaces. Copies within a protected surface, or from one + protected surface to another, are allowed. Any disallowed operation will + fail and result in undefined behavior, up to and including program + termination. If EGL_PROTECTED_CONTENT_EXT is EGL_FALSE, then the surface + content can be accessed by secure or non-secure devices and can be copied + to any other surfaces. The definition of secure and non-secure access is + up to the implementation and is out of scope of this specification. The + default value of EGL_PROTECTED_CONTENT_EXT is EGL_FALSE." + + Add to Table 3.5: Queryable surface attributes and types on p. 37 + + EGL_PROTECTED_CONTENT_EXT boolean Content protection state + + Add following the second paragraph in section 3.6 on p. 39 (describing + eglQuerySurface): + + "Querying EGL_PROTECTED_CONTENT_EXT returns the content protection state of + the surface. The protection state of window and pbuffer surfaces is specified + in eglCreateWindowSurface and eglCreatePbufferSurface. The protection state of + pixmap and client buffer (pbuffer) surfaces is always EGL_FALSE." + + Add following after "if either draw or read are bound to contexts in another thread, + an EGL_BAD_ACCESS error is generated." in section 3.7.3 p46 (describing eglMakeCurrent + errors): + + "If EGL_PROTECTED_CONTENT_EXT attributes of read is EGL_TRUE and + EGL_PROTECTED_CONTENT_EXT attributes of draw is EGL_FALSE, an + EGL_BAD_ACCESS error is generated." + + Add following after "which must be a valid native pixmap handle." in section 3.9.2 on + p. 53 (describing eglCopyBuffers): + + "If attribute EGL_PROTECTED_CONTENT_EXT of surface has value of EGL_TRUE, then + an EGL_BAD_ACCESS error is returned." + + +Additions to EGL_KHR_image_base extension specification + + Add to section 2.5.1 Table bbb: + + +-----------------------------+-------------------------+---------------+ + | Attribute | Description | Default Value | + +-----------------------------+-------------------------+---------------+ + | EGL_NONE | Marks the end of the | N/A | + | | attribute-value list | | + | EGL_IMAGE_PRESERVED_KHR | Whether to preserve | EGL_FALSE | + | | pixel data | | + | EGL_PROTECTED_CONTENT_EXT | Content protection | EGL_FALSE | + | | state | | + +-----------------------------+-------------------------+---------------+ + Table bbb. Legal attributes for eglCreateImageKHR <attrib_list> parameter + + Add the following paragraph to section 2.5.1 before "Errors" (describing + eglCreateImageKHR): + + "If the value of attribute EGL_PROTECTED_CONTENT_EXT is EGL_TRUE, then + image content is only accessible by secure devices in the system. A + complete definition of secure device is implementation-specific, but at + minimum a secure device must not expose the contents of a protected image + to non-secure devices or allow contents to be copied to non-protected + regions of memory. If an EGL client API cannot make such guarantees, + attempts to create an EGLImage sibling within that client API will fail + with an API-specific error. + + If the value of attribute EGL_PROTECTED_CONTENT_EXT is EGL_FALSE, then the + surface content can be accessed by secure or non-secure devices and can be + copied to any other surfaces." + +Issues + + 1. Should the spec define the behavior of secure and non-secure access? + + PROPOSED: No. Different CPU and GPU architectures have different secure access + implementations. The behavior of secure access violation is also different. Some + architectures will take a CPU exeception. On other architectures, reads will get + zeroes and writes will have no effect. This includes DMA transactions. So it is + better to leave the defination of illegal operation behavior out of this + specification. + + 2. Should the spec enumerate the legal and illegal operations in client APIs + such as OpenGL ES? + + PROPOSED: No. Enumerating these is possible, but is likely to get out of date + as new extensions and client API versions are introduced. Better to state the + principles that determine whether an operation is legal or illegal. If a version + of this extension is promoted to KHR or core status, enumerating the legal + operations because there will be a greater expectation that future extensions + will consider interactions. For OpenGL ES 3.0, a non-normative list of examples + would be: + * glReadPixels is illegal when the READ framebuffer is protected, + * glCopyTexImage2D is illegal when the READ framebuffer is protected, + * glCopyTexSubImage2D is illegal when the READ framebuffer is protected, unless + the target texture is a protected pbuffer, + * glBlitFramebuffer is illegal if the READ framebuffer is protected and the + DRAW framebuffer is not protected. + +Revision History + + Rev. Date Author Changes + ---- -------- -------- ------------------------------------------------- + 7 01/20/14 Jesse Reword PROTECTED_CONTENT descriptions to be more specific + about legality of client API operations. Add issue #2. + 6 01/14/14 Yanjun Change the extension from vendor specific to EXT. Add + EGL_BAD_ACCESS error to eglMakeCurrent, eglCopyBuffers. + 5 01/13/14 Jesse Define illegal operation behavior more broadly. + 4 01/10/14 Pontus Update description of illegal operation behavior in + terms of secure memory region and secure access. + 3 01/03/14 Yanjun Define the GPU and CPU behavior for illegal operations. + 2 12/13/13 Yanjun Prohibit GPU illegal copy from the protected surface to + non-protected surface. + 1 12/11/13 Yanjun Initial draft. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_stream_consumer_egloutput.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_stream_consumer_egloutput.txt new file mode 100644 index 0000000..61f3b0e --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_stream_consumer_egloutput.txt @@ -0,0 +1,248 @@ +Name + + EXT_stream_consumer_egloutput + +Name Strings + + EGL_EXT_stream_consumer_egloutput + +Contributors + + Daniel Kartch + James Jones + Christopher James Halse Rogers + +Contacts + + Daniel Kartch, NVIDIA (dkartch 'at' nvidia.com) + +Status + + Complete + +Version + + Version 7 - December 28th, 2015 + +Number + + EGL Extension #81 + +Extension Type + + EGL display extension + +Dependencies + + Requires EGL_KHR_stream. + Requires EGL_EXT_output_base. + +Overview + + Increasingly, EGL and its client APIs are being used in place of + "native" rendering APIs to implement the basic graphics + functionality of native windowing systems. This creates demand + for a method to initialize EGL displays and surfaces directly on + top of native GPU or device objects rather than native window + system objects. The mechanics of enumerating the underlying + native devices and constructing EGL displays and surfaces from + them have been solved in various platform and implementation- + specific ways. The EGL device family of extensions offers a + standardized framework for bootstrapping EGL without the use of + any underlying "native" APIs or functionality. + + This extension describes how to bind EGLOutputLayerEXTs as stream + consumers to send rendering directly to a display device without an + intervening window system. + +New Types + + None + +New Functions + + EGLBoolean eglStreamConsumerOutputEXT( + EGLDisplay dpy, + EGLStreamKHR stream, + EGLOutputLayerEXT layer); + +New Tokens + + None + +Replace section "3.10.2.1 No way to connect consumer to EGLStream" in +the EGL_KHR_stream extension with: + + 3.10.2.1 EGLOutputLayerEXT consumer + + Call + + EGLBoolean eglStreamConsumerOutputEXT( + EGLDisplay dpy, + EGLStreamKHR stream, + EGLOutputLayerEXT layer); + + to connect <output> as the consumer of <stream>. + + On failure EGL_FALSE is returned and an error is generated. + + - EGL_BAD_DISPLAY is generated if <dpy> is not a valid, + initialized EGLDisplay. + + - EGL_BAD_STREAM_KHR is generated if <stream> is not a valid + EGLStreamKHR created for <dpy>. + + - EGL_BAD_STATE_KHR is generated if <stream> is not in state + EGL_STREAM_STATE_CREATED_KHR. + + - EGL_BAD_OUTPUT_LAYER_EXT is generated if <layer> is not a + valid EGLOutputLayerEXT created for <dpy>. + + On success, <layer> is bound to <stream>, <stream> is placed in the + EGL_STREAM_STATE_CONNECTING_KHR state, and EGL_TRUE is returned. + Initially, no changes occur to the image displayed on <layer>. When + the <stream> enters state EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR, + <layer> will begin displaying frames, without further action + required on the application's part, as they become available, taking + into account any timestamps, swap intervals, or other limitations + imposed by the stream or producer attributes. + + Modifying the output layer's display mode is outside the scope of + EGL. If the producer does not automatically adjust it's dimensions + to match the consumer, then the caller is responsible for ensuring + that the producer's frame size and the display mode are compatible + before the first frame is placed in the stream. If these are not + compatible, the behavior is implementation dependent, but may not + hang or terminate. Among other possible behaviors, the + implementation may scale or letterbox the frames, post a blank image + to the display, or discard the frames without posting. + + Many display mode setting APIs have a mechanism that restricts + which of their clients can modify output attributes. Since + EGLOutput stream consumers will need to modify output attributes, + they require access to a display mode setting API handle with the + appropriate capabilities. If the application fails to provide + access to such permissions or privileged native objects when creating + the EGLDisplay associated with an output stream consumer and EGL is + not able to acquire them, the behavior of the stream consumer will be + undefined. Similarly, if the application or operating system revokes + the output modification permissions provided to the EGLDisplay, or + revokes permissions from the privileged native objects provided to + the EGLDisplay, future behavior of the stream consumer is undefined. + + If <layer> is rebound to a different stream by a subsequent call + to eglStreamConumerOutputEXT, then <stream> will be placed into the + EGL_STREAM_STATE_DISCONNECTED_KHR state. + +Issues + + 1. What happens to the display if the stream is destroyed while + still connected? + + RESOLVED: The EGLOutputLayer will maintain a reference to the + last frame consumed from the stream until a new frame is + received (through connection of a new stream or some interface + defined by another extension) or until the EGLOutputLayer is + destroyed. Until one of these occurs, the output will ensure + that memory containing the frame remains valid, but will do no + further reprogramming of the display layer state. In the event + the EGLOutputLayer is destroyed, the reference to the frame is + released, and random/invalid images may subsequently be + displayed if the application does not take separate action to + reprogram or disable the display. This behavior should + probably be defined in the EGL_EXT_output_base extension and + be shared regardless of the means by which the displayed image + was posted. + + 2. What happens to the stream if the display output is flipped to a + different image by a mechanism outside EGL? + + RESOLVED: Using native display APIs to directly change the + visible framebuffer while an EGLStream is bound to an + EGLOutputLayer has undefined results which depend on the + implementation, the display capabilities, and the + compatibility of the competing framebuffer sizes and formats. + A partial list of possible outcomes includes one interface + overriding the other, the visible image alternating between + the two frames, or the visible image becoming corrupted or + displaying random memory. + + 3. What happens if the display mode settings are not compatible + with the size and/or format of the incoming frames? + + RESOLVED: The behavior is implementation and device dependent. + The display may not terminate or hang, but otherwise may modify + or ignore the incoming frames. Additional extensions can be + defined if greater control of this behavior is desired. + + 4. How can changes to the display mode settings be synchronized + with changes in the size/format of frames generated by the + producer? + + RESOLVED: The base specification will assume that the + producer's frame size and the output layer's display mode are + established at initialization time and do not change for the + life of the stream. The ability to modify these states and + synchronize such modifications must be provided by additional + extensions. + + 5. The EGL_KHR_stream_producer_eglsurface extension, which is + likely to be used as a producer for streams directed to outputs, + explicitly ignores eglSwapInterval. But a swap interval is + desirable when directing output to a display screen. How can + this functionality be provided? + + RESOLVED: EGL_SWAP_INTERVAL_EXT added as an attribute to output + layers in the EGL_EXT_output_base specification. + + 6. How does EGL acquire the necessary capabilities to modify + display attributes from the application? + + RESOLVED: The application provides EGL with the necessary + permissions or native object handles when creating its EGLDisplay. + + 7. What is the behavior of EGLOutput stream consumers when EGL does + not have the necessary permissions to modify output attributes? + + RESOLVED: The behavior is undefined. Other options would be to + block consumption of frames indefinitely until permissions are + acquired via unspecified or native mechanisms, or to return + frames to the producer immediately when consumption fails due to + lack of permissions. However, both of these options may rely on + assumptions about the behavior of the underlying mode setting + APIs. Future extensions may refined the behavior of streams in + this case. + +Revision History: + + #7 (December 28th, 2015) James Jones + - Added issues 6 and 7. + - Added language to document the resolution of issues 6 and 7. + + #6 (August 22nd, 2014) James Jones + - Marked complete. + - Marked remaining unresolved issues resolved. + - Added an "Extension Type" section. + - Listed Daniel as the contact. + + #5 (June 5th, 2014) Daniel Kartch + - Added resolution for issues 3 and 4 and updated description + accordingly. + + #4 (May 28th, 2014) Daniel Kartch + - Added Issue 5 and its resolution. + + #3 (January 17th, 2014) Daniel Kartch + - Updated issues section with some proposed solutions and new + issues. + + #2 (November 13th, 2013) Daniel Kartch + - Replaced EGLOutputEXT with EGLOutputLayerEXT, as per changes + to EXT_output_base. + - Updated possible error states to reflect requirement that + output handles are now associated with a particular + EGLDisplay. + + #1 (October 28th, 2013) Daniel Kartch + - Initial draft + diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_surface_CTA861_3_metadata.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_surface_CTA861_3_metadata.txt new file mode 100644 index 0000000..50764b5 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_surface_CTA861_3_metadata.txt @@ -0,0 +1,136 @@ +Name + + EXT_surface_CTA861_3_metadata + +Name Strings + + EGL_EXT_surface_CTA861_3_metadata + +Contact + + Courtney Goeltzenleuchter (courtneygo 'at' google.com) + +Contributors + + James Jones + Weiwan Liu + +IP Status + + No known IP claims. + +Status + + Complete + +Version + + Version 5 - Nov 29, 2016 + +Number + + EGL Extension #117 + +Dependencies + + This extension requires EGL 1.5 and EGL_EXT_surface_SMPTE2086_metadata. + + This extension is written against the wording of the EGL 1.5 specification + (August 27, 2014). + +Overview + + This extension adds additional EGL surface attributes for the metadata + defined by the CTA (Consumer Technology Association) 861.3 standard. + This metadata, in addition to the SMPTE 2086 metadata, is used to define the + color volume of the mastering display as well as the content (CTA-861.3), + The mastering display is the display where creative work is done and creative + intent is established. To preserve such creative intent as much as possible + and achieve consistent color reproduction on different viewing displays, + it is useful for the display pipeline to know the color volume of the + original mastering display where content is created or tuned. This avoids + performing unnecessary mapping of colors that are not displayable on the + original mastering display. + + This extension adds the ability to pass the CTA-861.3 metadata via EGL, + from which the color volume can be derived. While the general purpose of the + metadata is to assist in the transformation between different color volumes + of different displays and help achieve better color reproduction, it is not + in the scope of this extension to define how exactly the metadata should be + used in such a process. It is up to the implementation to determine how to + make use of the metadata. + +New Procedures and Functions + + None. + +New Tokens + + Accepted as attribute by eglSurfaceAttrib and eglQuerySurface: + + EGL_CTA861_3_MAX_CONTENT_LIGHT_LEVEL_EXT 0x3360 + EGL_CTA861_3_MAX_FRAME_AVERAGE_LEVEL_EXT 0x3361 + +Additions to Chapter "3.5.6 Surface Attributes" of the EGL 1.5 Specification + + Add the following paragraph before the "Errors" section on page 43, + + If attribute is EGL_CTA861_3_MAX_CONTENT_LIGHT_LEVEL_EXT or EGL_CTA861_3_- + MAX_FRAME_AVERAGE_LEVEL_EXT, then value indicates the corresponding + maximum content light level and maximum frame average level. + The unit of value is 1 nit (candela per square meter). The + floating-point luminance values should be multiplied by + EGL_METADATA_SCALING, a constant scaling factor of 50000, before being + passed into eglSurfaceAttrib as integers. + + Exactly how the color volume information is used to assist the color + reproduction process is implementation dependant. + + The initial values of EGL_CTA861_3_MAX_CONTENT_LIGHT_LEVEL_EXT and + EGL_CTA861_3_MAX_FRAME_AVERAGE_LEVEL_EXT are EGL_DONT_CARE, which causes the + hints to be ignored. If value is not in the implementation's supported + range for attribute, a EGL_INVALID_VALUE error is generated, and some or + all of the metadata fields are ignored. + + Change the original footnote 12 at the end of section "3.5.6 Surface + Attributes" on page 45 to, + + [13] EGL_DISPLAY_SCALING (10000) and EGL_METADATA_SCALING_EXT (50000) + are used where EGL needs to take or return floating-point attribute + values, which would normally be smaller than 1, as integers while still + retaining sufficient precision to be meaningful. + + Addition to Table 3.5 "Queryable surface attributes and types", + + Attribute Type + ------------------------------------------------ + EGL_CTA861_3_MAX_CONTENT_LIGHT_LEVEL_EXT integer + EGL_CTA861_3_MAX_FRAME_AVERAGE_LEVEL_EXT integer + + Description + -------------------------------------------------------------------------------------- + Maximum content light level in nit multiplied by EGL_METADATA_SCALING_EXT + Maximum frame average light level in nit multiplied by EGL_METADATA_SCALING_EXT + + Add the following paragraph at the end of section "3.5.6 Surface Attributes" + on page 45, + + Querying EGL_CTA861_3_MAX_CONTENT_LIGHT_LEVEL_EXT EGL_CTA861_3_MAX_- + FRAME_AVERAGE_LEVEL_EXT returns respectively the maximum content light level + and maximum frame average level respectively. The values returned are + in units of 1 nit (candela per square meter), multiplied by the constant + value EGL_METADATA_SCALING_EXT (50000). The value of EGL_CTA861_3_MAX_- + CONTENT_LIGHT_LEVEL_EXT and EGL_CTA861_3_MAX_FRAME_AVERAGE_LEVEL_EXT can + be set via eglSurfaceAttrib as described above. + +Errors + + Described in the body text above. + +Issues + +Revision History + + Version 1, 2017/02/28 + - Initial draft + diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_surface_SMPTE2086_metadata.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_surface_SMPTE2086_metadata.txt new file mode 100644 index 0000000..2fa0b2e --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_surface_SMPTE2086_metadata.txt @@ -0,0 +1,247 @@ +Name + + EXT_surface_SMPTE2086_metadata + +Name Strings + + EGL_EXT_surface_SMPTE2086_metadata + +Contact + + Weiwan Liu (weiwliu 'at' nvidia.com) + +Contributors + + Tom Cooksey + Courtney Goeltzenleuchter + Mathias Heyer + Lauri Hyvarinen + James Jones + Daniel Koch + Jeff Leger + Sandeep Shinde + +IP Status + + No known IP claims. + +Status + + Complete + +Version + + Version 8 - Oct 16, 2017 + +Number + + EGL Extension #109 + +Dependencies + + This extension requires EGL 1.4. + + This extension is written against the wording of the EGL 1.5 specification + (August 27, 2014). + +Overview + + This extension adds a new set of EGL surface attributes for the metadata + defined by the SMPTE (the Society of Motion Picture and Television + Engineers) ST 2086 standard. The SMPTE 2086 metadata includes the color + primaries, white point and luminance range of the mastering display, which + all together define the color volume that contains all the possible colors + the mastering display can produce. The mastering display is the display + where creative work is done and creative intent is established. To preserve + such creative intent as much as possible and achieve consistent color + reproduction on different viewing displays, it is useful for the display + pipeline to know the color volume of the original mastering display where + content is created or tuned. This avoids performing unnecessary mapping of + colors that are not displayable on the original mastering display. + + This extension adds the ability to pass the SMPTE 2086 metadata via EGL, + from which the color volume can be derived. While the general purpose of the + metadata is to assist in the transformation between different color volumes + of different displays and help achieve better color reproduction, it is not + in the scope of this extension to define how exactly the metadata should be + used in such a process. It is up to the implementation to determine how to + make use of the metadata. + +New Procedures and Functions + + None. + +New Tokens + + Accepted as attribute by eglSurfaceAttrib and eglQuerySurface: + + EGL_SMPTE2086_DISPLAY_PRIMARY_RX_EXT 0x3341 + EGL_SMPTE2086_DISPLAY_PRIMARY_RY_EXT 0x3342 + EGL_SMPTE2086_DISPLAY_PRIMARY_GX_EXT 0x3343 + EGL_SMPTE2086_DISPLAY_PRIMARY_GY_EXT 0x3344 + EGL_SMPTE2086_DISPLAY_PRIMARY_BX_EXT 0x3345 + EGL_SMPTE2086_DISPLAY_PRIMARY_BY_EXT 0x3346 + EGL_SMPTE2086_WHITE_POINT_X_EXT 0x3347 + EGL_SMPTE2086_WHITE_POINT_Y_EXT 0x3348 + EGL_SMPTE2086_MAX_LUMINANCE_EXT 0x3349 + EGL_SMPTE2086_MIN_LUMINANCE_EXT 0x334A + +Additions to Chapter "3.5.6 Surface Attributes" of the EGL 1.5 Specification + + Add the following paragraph before the "Errors" section on page 43, + + If attribute is EGL_SMPTE2086_DISPLAY_PRIMARY_RX_EXT, EGL_SMPTE2086_- + DISPLAY_PRIMARY_RY_EXT, EGL_SMPTE2086_DISPLAY_PRIMARY_GX_EXT, EGL_- + SMPTE2086_DISPLAY_PRIMARY_GY_EXT, EGL_SMPTE2086_DISPLAY_PRIMARY_BX_EXT + or EGL_SMPTE2086_DISPLAY_PRIMARY_BY_EXT, then value indicates the + corresponding xy chromaticity coordinate[12] of the mastering display's + red, green or blue color primary, as configured for the mastering + process. The floating-point display primary coordinates should be + multiplied by EGL_METADATA_SCALING_EXT (50000)[13], before being passed + into eglSurfaceAttrib as integers. + + If attribute is EGL_SMPTE2086_WHITE_POINT_X_EXT or EGL_SMPTE2086_WHITE_- + POINT_Y_EXT, then value indicates the corresponding xy chromaticity + coordinate[12] of the mastering display's white point, as configured for + the mastering process. The floating-point white point chromaticity + coordinates should be multiplied by EGL_METADATA_SCALING_EXT (50000), + before being passed into eglSurfaceAttrib as integers. + + If attribute is EGL_SMPTE2086_MAX_LUMINANCE_EXT or EGL_SMPTE2086_MIN_- + LUMINANCE_EXT, then value indicates the maximum or minimum display + luminance of the mastering display, as configured for the mastering + process. The unit of value is 1 nit (candela per square meter). The + floating-point luminance values should be multiplied by + EGL_METADATA_SCALING_EXT, a constant scaling factor of 50000, before + being passed into eglSurfaceAttrib as integers. + + By defining the mastering display's color volume through color + primaries, white point, and luminance range, applications give EGL + and the underlying display pipeline hints as to how to reproduce colors + more closely to the original content when created on the mastering + display. Exactly how the color volume information is used to assist the + color reproduction process is implementation dependant. + + The initial values of EGL_SMPTE2086_DISPLAY_PRIMARY_RX_EXT, EGL_- + SMPTE2086_DISPLAY_PRIMARY_RY_EXT, EGL_SMPTE2086_DISPLAY_PRIMARY_GX_EXT, + EGL_SMPTE2086_DISPLAY_PRIMARY_GY_EXT, EGL_SMPTE2086_DISPLAY_PRIMARY_BX_- + EXT, EGL_SMPTE2086_DISPLAY_PRIMARY_BY_EXT, EGL_SMPTE2086_WHITE_POINT_X_- + EXT, EGL_SMPTE2086_WHITE_POINT_Y_EXT, EGL_SMPTE2086_MAX_LUMINANCE_EXT + and EGL_SMPTE2086_MIN_LUMINANCE_EXT are EGL_DONT_CARE, which causes the + hints to be ignored. If value is not in the implementation's supported + range for attribute, a EGL_BAD_PARAMETER error is generated, and some or + all of the metadata fields are ignored. + + Add the following footnote at the end of page 43, and increment all the + subsequent footnote numbers in Chapter 3, + + [12] Chromaticity coordinates x and y are as specified in CIE + 15:2004 "Calculation of chromaticity coordinates" (Section 7.3) and are + limited to between 0 and 1 for real colors for the mastering display. + + Change the original footnote 12 at the end of section "3.5.6 Surface + Attributes" on page 45 to, + + [13] EGL_DISPLAY_SCALING (10000) and EGL_METADATA_SCALING_EXT (50000) + are used where EGL needs to take or return floating-point attribute + values, which would normally be smaller than 1, as integers while still + retaining sufficient precision to be meaningful. + + Addition to Table 3.5 "Queryable surface attributes and types", + + Attribute Type + ------------------------------------------------ + EGL_SMPTE2086_DISPLAY_PRIMARY_RX_EXT integer + EGL_SMPTE2086_DISPLAY_PRIMARY_RY_EXT integer + EGL_SMPTE2086_DISPLAY_PRIMARY_GX_EXT integer + EGL_SMPTE2086_DISPLAY_PRIMARY_GY_EXT integer + EGL_SMPTE2086_DISPLAY_PRIMARY_BX_EXT integer + EGL_SMPTE2086_DISPLAY_PRIMARY_BY_EXT integer + EGL_SMPTE2086_WHITE_POINT_X_EXT integer + EGL_SMPTE2086_WHITE_POINT_Y_EXT integer + EGL_SMPTE2086_MAX_LUMINANCE_EXT integer + EGL_SMPTE2086_MIN_LUMINANCE_EXT integer + + Description + ------------------------------------------------------------------------------------------ + x chromaticity coordinate for red display primary multiplied by EGL_METADATA_SCALING_EXT + y chromaticity coordinate for red display primary multiplied by EGL_METADATA_SCALING_EXT + x chromaticity coordinate for green display primary multiplied by EGL_METADATA_SCALING_EXT + y chromaticity coordinate for green display primary multiplied by EGL_METADATA_SCALING_EXT + x chromaticity coordinate for blue display primary multiplied by EGL_METADATA_SCALING_EXT + y chromaticity coordinate for blue display primary multiplied by EGL_METADATA_SCALING_EXT + x chromaticity coordinate for white point multiplied by EGL_METADATA_SCALING_EXT + y chromaticity coordinate for white point multiplied by EGL_METADATA_SCALING_EXT + Maximum luminance in nit multiplied by EGL_METADATA_SCALING_EXT + Minimum luminance in nit multiplied by EGL_METADATA_SCALING_EXT + + Add the following paragraph at the end of section "3.5.6 Surface Attributes" + on page 45, + + Querying EGL_SMPTE2086_DISPLAY_PRIMARY_RX_EXT, EGL_SMPTE2086_DISPLAY_- + PRIMARY_RY_EXT, EGL_SMPTE2086_DISPLAY_PRIMARY_GX_EXT, EGL_SMPTE2086_- + DISPLAY_PRIMARY_GY_EXT, EGL_SMPTE2086_DISPLAY_PRIMARY_BX_EXT or EGL_- + SMPTE2086_DISPLAY_PRIMARY_BY_EXT returns respectively the xy + chromaticity coordinate of the mastering display's red, green or blue + color primary, multiplied by the constant value EGL_METADATA_SCALING_EXT + (50000). The display primary coordinates can be set via eglSurfaceAttrib + as described above. + + Querying EGL_SMPTE2086_WHITE_POINT_X_EXT, or EGL_SMPTE2086_WHITE_POINT_- + Y_EXT returns respectively the xy chromaticity coordinate of the + mastering display's white point, multiplied by the constant value EGL_- + METADATA_SCALING (50000). The white point coordinates can be set via + eglSurfaceAttrib as described above. + + Querying EGL_SMPTE2086_MAX_LUMINANCE_EXT or EGL_SMPTE2086_MIN_- + LUMINANCE_EXT returns respectively the maximum and minimum display + luminance of the mastering display. The values returned are in units of + 1 nit (candela per square meter), multiplied by the constant value EGL_- + METADATA_SCALING (50000). The value of EGL_SMPTE2086_MAX_LUMINANCE_EXT + and EGL_SMPTE2086_MIN_LUMINANCE_EXT can be set via eglSurfaceAttrib as + described above. + +Errors + + Described in the body text above. + +Issues + + 1. Should this extension define a valid data range for each metadata field? + + RESOLVED: No. It is not in the scope of this extension to define how the + metadata hints should be used in the display pipeline and, as a result, + what the valid data ranges are for the metadata fields. It is + implementation dependant, but related standards, such as SMPTE ST 2086, + can be used as reference. As described in the body, implemetations may + generate a EGL_BAD_PARAMTER error to notify applications that the input + metadata values are invalid or not supported. + +Revision History + + Version 1, 2016/04/22 + - Initial draft + + Version 2, 2016/05/25 + - Rename to EXT and introduce a new scaling factor + + Version 3, 2016/10/19 + - Add an error and revise issue 1 + + Version 4, 2016/11/22 + - Change status to complete + + Version 5, 2016/11/29 + - Add token assigments + + Version 6, 2017/02/28 + - Add 'EXT' suffix to 'EGL_METADATA_SCALING' + + Version 7, 2017/10/13 + - Rename EGL_INVALID_VALUE (which doesn't exist) to EGL_FALSE + + Version 8, 2017/10/16 + - Fix v7 change to use EGL_BAD_PARAMETER as the error code + generated vs. EGL_FALSE which is the expected return value of + the function. + diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_surface_compression.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_surface_compression.txt new file mode 100644 index 0000000..6610017 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_surface_compression.txt @@ -0,0 +1,289 @@ +Name + + EXT_surface_compression + +Name Strings + + EGL_EXT_surface_compression + +Contributors + + Jan-Harald Fredriksen, Arm + Lisa Wu, Arm + George Liu, Arm + Laurie Hedge, Imagination Technologies + +Contact + + Jan-Harald Fredriksen (jan-harald.fredriksen 'at' arm.com) + +IP Status + + No known IP claims. + +Status + + Complete + +Version + + Version 1 - November 15, 2021 + +Number + + EGL Extension #147 + +Dependencies + + These extensions are written against the wording of the EGL 1.5 + specification (August 27, 2014). + + This extension interacts with EGL_EXT_yuv_surface. + +Overview + + Applications may wish to take advantage of framebuffer compression. Some + platforms may support framebuffer compression at fixed bitrates. Such + compression algorithms generally produce results that are visually lossless, + but the results are typically not bit exact when compared to a non-compressed + result. + + This extension enables applications to opt-in to fixed-rate compression + for EGL window surfaces. + + Compression may not be supported for all framebuffer formats. It can still + be requested for all formats and applications can query what level of compression + was actually enabled. + +New Procedures and Functions + + EGLBoolean eglQuerySupportedCompressionRatesEXT( + EGLDisplay dpy, EGLConfig config, const EGLAttrib *attrib_list, + EGLint *rates, EGLint rate_size, EGLint *num_rates); + +New Tokens + + New attributes accepted by the <attrib_list> argument of + eglCreatePlatformWindowSurface and eglCreateWindowSurface: + EGL_SURFACE_COMPRESSION_EXT 0x34B0 + + [Only if EGL_EXT_yuv_surface is supported] + EGL_SURFACE_COMPRESSION_PLANE1_EXT 0x328E + EGL_SURFACE_COMPRESSION_PLANE2_EXT 0x328F + + Accepted as attribute values for EGL_SURFACE_COMPRESSION_EXT by + eglCreatePlatformWindowSurface and eglCreateWindowSurface: + EGL_SURFACE_COMPRESSION_FIXED_RATE_NONE_EXT 0x34B1 + EGL_SURFACE_COMPRESSION_FIXED_RATE_DEFAULT_EXT 0x34B2 + + EGL_SURFACE_COMPRESSION_FIXED_RATE_1BPC_EXT 0x34B4 + EGL_SURFACE_COMPRESSION_FIXED_RATE_2BPC_EXT 0x34B5 + EGL_SURFACE_COMPRESSION_FIXED_RATE_3BPC_EXT 0x34B6 + EGL_SURFACE_COMPRESSION_FIXED_RATE_4BPC_EXT 0x34B7 + EGL_SURFACE_COMPRESSION_FIXED_RATE_5BPC_EXT 0x34B8 + EGL_SURFACE_COMPRESSION_FIXED_RATE_6BPC_EXT 0x34B9 + EGL_SURFACE_COMPRESSION_FIXED_RATE_7BPC_EXT 0x34BA + EGL_SURFACE_COMPRESSION_FIXED_RATE_8BPC_EXT 0x34BB + EGL_SURFACE_COMPRESSION_FIXED_RATE_9BPC_EXT 0x34BC + EGL_SURFACE_COMPRESSION_FIXED_RATE_10BPC_EXT 0x34BD + EGL_SURFACE_COMPRESSION_FIXED_RATE_11BPC_EXT 0x34BE + EGL_SURFACE_COMPRESSION_FIXED_RATE_12BPC_EXT 0x34BF + +Modifications to the EGL 1.5 Specification + + Modify section 3.5.1 "Creating On-Screen Rendering Surfaces: + + Add EGL_SURFACE_COMPRESSION_EXT to the list of attributes that can + be specified in <attrib_list> for eglCreatePlatformWindowSurface. + + Add the following paragraph: + + EGL_SURFACE_COMPRESSION_EXT specifies the fixed-rate compression that may + be enabled for rendering to the window. + If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_NONE_EXT, then fixed-rate + compression is disabled. + If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_DEFAULT_EXT, + then the implementation may enable compression at a default, + implementation-defined, rate. + If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_1BPC_EXT, then the + implementation may enable fixed-rate compression with a bitrate of at + least 1 bit and less than 2 bits per component. + If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_2BPC_EXT, then the + implementation may enable fixed-rate compression with a bitrate of at + least 2 bits and less than 3 bits per component. + If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_3BPC_EXT, then the + implementation may enable fixed-rate compression with a bitrate of at + least 3 bits and less than 4 bits per component. + If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_4BPC_EXT, then the + implementation may enable fixed-rate compression with a bitrate of at + least 4 bits and less than 5 bits per component. + If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_5BPC_EXT, then the + implementation may enable fixed-rate compression with a bitrate of at + least 5 bits and less than 6 bits per component. + If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_6BPC_EXT, then the + implementation may enable fixed-rate compression with a bitrate of at + least 6 bits and less than 7 bits per component. + If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_7BPC_EXT, then the + implementation may enable fixed-rate compression with a bitrate of at + least 7 bits and less than 8 bits per component. + If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_8BPC_EXT, then the + implementation may enable fixed-rate compression with a bitrate of at + least 8 bits and less than 9 bits per component. + If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_9BPC_EXT, then the + implementation may enable fixed-rate compression with a bitrate of at + least 9 bits and less than 10 bits per component. + If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_10BPC_EXT, then the + implementation may enable fixed-rate compression with a bitrate of at + least 10 bits and less than 11 bits per component. + If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_11BPC_EXT, then the + implementation may enable fixed-rate compression with a bitrate of at + least 11 bits and less than 12 bits per component. + If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_12BPC_EXT, then the + implementation may enable fixed-rate compression with a bitrate of at + least 12 bits per component. + + For pixel formats with different number of bits per component, the + specified fixed-rate compression rate applies to the component with + the highest number of bits. + + The default value of EGL_SURFACE_COMPRESSION_EXT is + EGL_SURFACE_COMPRESSION_FIXED_RATE_NONE_EXT. + + [Only if EGL_EXT_yuv_surface is supported] + + If _config_ describes a surface with multiple planes (the + value of the EGL_YUV_NUMBER_OF_PLANES_EXT attribute is larger than one), + then the fixed-rate compression rate can be specified independently for + the each plane. + In this case, EGL_SURFACE_COMPRESSION_EXT specifies the fixed-rate + compression that may be enabled for rendering to plane 0, + EGL_SURFACE_COMPRESSION_PLANE1_EXT specifies the fixed-rate + compression that may be enabled for rendering to plane 1, and + EGL_SURFACE_COMPRESSION_PLANE2_EXT specifies the fixed-rate compression + that may be enabled for rendering to plane 2. + The supported values of EGL_SURFACE_COMPRESSION_PLANE1_EXT and + EGL_SURFACE_COMPRESSION_PLANE2_EXT are the same as for + EGL_SURFACE_COMPRESSION_EXT. + + If _config_ has more than one plane and the + EGL_SURFACE_COMPRESSION_PLANE1_EXT attribute is not specified, + then the value of EGL_SURFACE_COMPRESSION_EXT is used for all planes. + If _config_ has more than two planes and the + EGL_SURFACE_COMPRESSION_PLANE2_EXT attribute is not specified, + then the value of EGL_SURFACE_COMPRESSION_PLANE1_EXT is also used + for plane 2. + + The default value of EGL_SURFACE_COMPRESSION_PLANE1_EXT and + EGL_SURFACE_COMPRESSION_PLANE2_EXT is EGL_SURFACE_COMPRESSION_FIXED_RATE_NONE_EXT. + + Modify section 3.5.6 "Surface Attributes" + + Add entries to Table 3.5 "Queryable surface attributes and types": + + EGL_SURFACE_COMPRESSION_EXT enum Fixed-rate compression + + [Only if EGL_EXT_yuv_surface is supported] + EGL_SURFACE_COMPRESSION_PLANE1_EXT enum Fixed-rate compression for plane 1 + EGL_SURFACE_COMPRESSION_PLANE2_EXT enum Fixed-rate compression for plane 2 + + Add the following paragraph: + + Querying EGL_SURFACE_COMPRESSION_EXT returns the actual fixed-rate + compression applied to a surface. For YUV surfaces, the value applied to + the luma plane is returned. This value may be different to the one + requested when the surface was created. + For pbuffer and pixmap surfaces, the contents of <value> are not modified." + + [Only if EGL_EXT_yuv_surface is supported] + Querying EGL_SURFACE_COMPRESSION_PLANE1_EXT returns the actual + fixed-rate compression applied to plane 1 of a YUV surface. + Querying EGL_SURFACE_COMPRESSION_PLANE2_EXT returns the actual + fixed-rate compression applied to plane 2 of a YUV surface. + These values may be different to the one requested when the surface was created. + For pbuffer and pixmap surfaces, the contents of <value> are not modified." + + To get the list of all fixed-rate compression rates that are available on + a specified display and EGLConfig, call + + EGLBoolean eglQuerySupportedCompressionRatesEXT( + EGLDisplay dpy, EGLConfig config, const EGLAttrib *attrib_list, + EGLint *rates, EGLint rate_size, EGLint *num_rates); + + <attrib_list> specifies a list of attributes that will be provided when a surface is created with + this combination of display and EGLConfig. The accepted attributes are the same as for + eglCreatePlatformWindowSurface. + <rates> is a pointer to a buffer containing <rate_size> elements. On success, EGL_TRUE is + returned. The number of rates is returned in <num_rates>, and elements 0 through <num_rates>-1 of + <rates> are filled in with the available compression rates. + No more than <rate_size> compression rates will be returned even if more are available + on the specified display and config. However, if eglQuerySupportedCompressionRatesEXT is called with + <rates> = NULL, then no rates are returned, but the total number of rates available will be returned + in <num_rates>. + The possible values returned in <rates> are the attribute values accepted for + EGL_SURFACE_COMPRESSION_EXT by eglCreatePlatformWindowSurface and eglCreateWindowSurface, except + EGL_SURFACE_COMPRESSION_FIXED_RATE_NONE_EXT and EGL_SURFACE_COMPRESSION_FIXED_RATE_DEFAULT_EXT. + +Errors + + [Only if EGL_EXT_yuv_surface is supported] + Add to the error section of eglCreatePlatformWindowSurface: + + If the EGL_SURFACE_COMPRESSION_PLANE1_EXT attribute is specified and + _config_ does not describe a surface with at least 2 planes (the + EGL_YUV_NUMBER_OF_PLANES_EXT attribute is not greater than or + equal to 2), an EGL_BAD_MATCH error is generated. + + If the EGL_SURFACE_COMPRESSION_PLANE2_EXT attribute is specified and + _config_ does not describe a surface with at least 3 planes (the + EGL_YUV_NUMBER_OF_PLANES_EXT attribute is not greater than or + equal to 3), an EGL_BAD_MATCH error is generated. + + Add to the section describing eglQuerySupportedCompressionRatesEXT: + + * On failure, EGL_FALSE is returned. + * An EGL_NOT_INITIALIZED error is generated if EGL is not initialized on <dpy>. + * An EGL_BAD_PARAMETER error is generated if <num_rates> is NULL. + +Issues + + 1. Should fixed-rate compression be supported for pixmap or pbuffer + surfaces? + + No, no use-cases have been identified for this. + + 2. What is the result of querying EGL_SURFACE_COMPRESSION_EXT if + EGL_SURFACE_COMPRESSION_FIXED_RATE_DEFAULT_EXT was requested? + + Resolved. + The result will be the specific compression ratio chosen by the + implementation, or EGL_SURFACE_COMPRESSION_FIXED_RATE_NONE_EXT if + no fixed-rate compression was applied. + + 3. Should we expose different compressions rates per plane in this extension? + + Yes. + + 4. How can an application query the set of supported compression rates? + + Resolved. Option B. + + Two options were considered. + + Option A: + Reuse eglGetConfigAttrib(EGLDisplay dpy, EGLConfig config, EGLint attribute, EGLint *value); + + This is not ideal because: + - the compression modes are currently tied to the surface, not the EGLConfig + - we don't want this to affect EGLConfig selection etc. + - this query can only return a single value, so you'd need to query each of the + 12 bit rates separately. + + Option B: + Add a new query, specifically for the compression rates. This addresses the concerns + with Option A, and is very similar to the mechanism used for the OpenGL ES API. Main + downside is that it adds additional functions to the API. + +Revision History + + Version 1, 2021/11/15 + - Internal revisions diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_swap_buffers_with_damage.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_swap_buffers_with_damage.txt new file mode 100644 index 0000000..7a1f7fc --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_swap_buffers_with_damage.txt @@ -0,0 +1,343 @@ +Name + + EXT_swap_buffers_with_damage + +Name Strings + + EGL_EXT_swap_buffers_with_damage + +IP Status + + No known IP claims. + +Contributors + + Robert Bragg + Tapani Pälli + Kristian Høgsberg + Benjamin Franzke + Ian Stewart + James Jones + +Contacts + + Robert Bragg, Intel (robert.bragg 'at' intel.com) + +Status + + Published + +Version + + Version 11, February 20, 2020 + +Number + + EGL Extension #55 + +Dependencies + + Requires EGL 1.4 + + This extension is written against the wording of the EGL 1.4 + Specification. + +Overview + + This extension provides a means to issue a swap buffers request to + display the contents of the current back buffer and also specify a + list of damage rectangles that can be passed to a system + compositor so it can minimize how much it has to recompose. + + This should be used in situations where an application is only + animating a small portion of a surface since it enables the + compositor to avoid wasting time recomposing parts of the surface + that haven't changed. + +New Procedures and Functions + + EGLBoolean eglSwapBuffersWithDamageEXT ( + EGLDisplay dpy, + EGLSurface surface, + const EGLint *rects, + EGLint n_rects); + +New Tokens + + None + +Changes to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors) + + Add the following text to subsection 3.9.1 titled "Posting to a + Window" after the description of eglSwapBuffers. + + As an alternative to eglSwapBuffers use: + + EGLBoolean eglSwapBuffersWithDamageEXT ( + EGLDisplay dpy, + EGLSurface surface, + const EGLint *rects, + EGLint n_rects); + + to do the same thing as eglSwapBuffers but additionally report + a list of rectangles that define the region that has truly + changed since the last frame. To be clear; the entire contents + of the back buffer will still be swapped to the front so + applications using this API must still ensure that the entire + back buffer is consistent. The rectangles are only a hint for + the system compositor so it can avoid recomposing parts of the + surface that haven't really changed. + <rects> points to a list of integers in groups of four that + each describe a rectangle in screen coordinates in this + layout: {x, y, width, height}. The rectangles are specified + relative to the bottom-left of the surface and the x and y + components of each rectangle specify the bottom-left position + of that rectangle. <n_rects> determines how many groups of 4 + integers can be read from <rects>. It is not necessary to + avoid overlaps of the specified rectangles. + If <n_rects> is 0 then <rects> is ignored and the entire + surface is implicitly damaged and the behaviour is equivalent + to calling eglSwapBuffers. + The error conditions checked for are the same as for the + eglSwapBuffers api. + + Modify the first paragraph of Section 3.9.1 titled "Native Window + Resizing" + + "If the native window corresponding to <surface> has been + resized prior to the swap, <surface> must be resized to match. + <surface> will normally be resized by the EGL implementation + at the time the native window is resized. If the + implementation cannot do this transparently to the client, + then eglSwapBuffers and eglSwapBuffersWithDamageEXT must + detect the change and resize surface prior to copying its + pixels to the native window. In this case the meaningfulness + of any damage rectangles forwarded by + eglSwapBuffersWithDamageEXT to the native window system is + undefined." + + Modify the following sentences in Section 3.9.3, page 51 (Posting + Semantics) + + Paragraph 2, first sentence: + + "If <dpy> and <surface> are the display and surface for the + calling thread's current context, eglSwapBuffers, + eglSwapBuffersWithDamageEXT, and eglCopyBuffers perform an + implicit flush operation on the context (glFlush for OpenGL or + OpenGL ES context, vgFlush for an OpenVG context)." + + Paragraph 3, first sentence: + + "The destination of a posting operation (a visible window, for + eglSwapBuffers or eglSwapBuffersWithDamageEXT, or a native + pixmap, for eglCopyBuffers) should have the same number of + components and component sizes as the color buffer it's being + copied from." + + Paragraph 6, first two sentences: + + "The function + + EGLBoolean eglSwapInterval(EGLDisplay dpy, EGLint + interval); + + specifies the minimum number of video frame periods per color + buffer post operation for the window associated with the + current context. The interval takes effect when eglSwapBuffers + or eglSwapBuffersWithDamageEXT is first called subsequent to + the eglSwapInterval call." + + Modify the following sentences in Section 3.9.4, page 52 (Posting + Errors) + + Paragraph 1, first sentence: + + "eglSwapBuffers, eglSwapBuffersWithDamageEXT, and + eglCopyBuffers return EGL_FALSE on failure." + + Paragraph 1, seventh sentence: + + "If eglSwapBuffers or eglSwapBuffersWithDamageEXT are called + and the native window associated with <surface> is no longer + valid, an EGL_BAD_NATIVE_WINDOW error is generated. If + eglSwapBuffersWithDamageEXT is called and <n_rects>, is less + than zero or <n_rects> is greater than zero but <rects> is + NULL, EGL_BAD_PARAMETER is generated." + +Dependencies on OpenGL ES + + None + +Dependencies on OpenVG + + None + +Issues + +1) Do applications have to make sure the rectangles don't overlap? + + RESOLVED: No, that would be inconvenient for applications and we + see no difficulty for implementations to supporting overlapping + rectangles. + +2) Would it be valid for an implementation to discard the list of + rectangles internally and work just in terms of the + eglSwapBuffers api? + + RESOLVED: Yes, the rectangles are only there for optimization + purposes so although it wouldn't be beneficial to applications if + it was convenient at times then it would be compliant for an + implementation to discard the rectangles and just call + eglSwapBuffers instead. The error conditions that should be + checked for are compatible with the requirements for + eglSwapBuffers. + +3) What origin should be used for damage rectangles? + + RESOLVED: Bottom left since this is consistent with all other + uses of 2D window coordinates in EGL and OpenGL that specify a + bottom left origin. + + Originally this specification was written with a top-left origin + for the damage rectangles even though it was known to be + inconsistent and that was because most window systems use a + top-left origin and there are some awkward semantic details + related to handling native window resizing that we had hoped to + simplify. + + This extension and also several other existing EGL extensions + struggle to guarantee a reliable behaviour in response to native + window resizing which can happen asynchronously on some platforms + and this can make it difficult for applications to avoid certain + visual artefacts. + + The crux of the problem is that when a native window is + asynchronously resized then the window system may maintain the old + buffer contents with respect to a different origin than EGL's + bottom left origin. For this extension that means that EGL damage + rectangles that are intended to map to specific surface contents + may end up mapping to different contents when a native window is + resized because the rectangles and buffer contents will be moved in + different directions in relation to the new window size. + + In the end we decided that this issue isn't simply solved by + choosing to use a top-left origin and so we can instead aim for + consistency and clarify what guarantees we offer in relation to + native window resizing separate from this issue. + +4) What guarantees do we provide about the meaningfulness of EGL + damage rectangles that are forwarded to the native window system + when presenting to a native window that has been resized? + + RESOLVED: The meaningfulness of those forwarded damage rectangles + is undefined since this simplifies the implementation requirements + and we saw very little benefit to applications from providing + stricter guarantees. + + The number of applications that would be able to avoid fully + redrawing the contents of a window in response to a window resize + is expected to be so low that there would be almost no benefit to + defining strict guarantees here. + + Since EGL already states that the contents of window surface + buffers become undefined when a native window has been resized, + this limitation doesn't introduce any new issue for applications + to consider. Applications should already fully redraw buffer + contents in response to a native window resize, unless they are + following some platform specific documentation that provides + additional guarantees. + + For an example of the implementation details that make this an + awkward issue to provide guarantees for we can consider X11 based + platforms where native windows can be resized asynchronously with + respect to a client side EGL surface: + + With X11 there may be multiple "gravity" transformations that can + affect how surface buffer content is positioned with respect to a + new native window size; there is the core X "bit gravity" and + there is the EGL driver gravity that determines how a surface's + contents with one size should be mapped to a native window with a + different size. Without very careful cooperation between the EGL + driver and the core X implementation and without the right + architecture to be able to do transforms atomically with respect + to different clients that may enact a window resize then it is not + possible to reliably map EGL damage rectangles to native window + coordinates. + + The disadvantage of a driver that is not able to reliably map EGL + damage rectangles to native window coordinates is that a native + compositor may re-compose the wrong region of window. This may + result in a temporary artefact until the full window gets redrawn + and then re-composed. X11 already suffers other similar transient + artefacts when resizing windows. + + The authors of this spec believe that even if a driver can't do + reliable mappings of EGL damage rectangles then compositors would + be able mitigate the majority of related artefacts by ignoring + sub-window damage during an interactive window resize. + + The authors of this spec believe that that if an X11 driver did + want to reliably map EGL damage rectangles to the native window + coordinates then that may be technically feasible depending on the + driver architecture. For reference one approach that had been + considered (but not tested) is as follows: + + 1) When eglSwapBuffersWithDamageEXT is called, send EGL damage + rectangles from the client to a driver component within the + xserver un-transformed in EGL window surface coordinates with a + bottom-left origin. + + 2) Within the X server the driver component should look at the + bit-gravity of a window and use the bit-gravity convention to + copy EGL surface content to the front-buffer of a native window. + + 3) Within the X server the driver component should use the same + gravity transform that was used to present the surface content + to also transform the EGL damage rectangle coordinates. + + Note that because this transform is done in the xserver then + this is implicitly synchronized with all clients that would + otherwise be able to enact an asynchronous window resize. + + +Revision History + + Version 1, 29/07/2011 + - First draft + Version 2, 03/08/2011 + - Clarify that the rectangles passed may overlap + Version 3, 01/09/2011 + - Fix a missing '*' in prototype to make rects a pointer + Version 4, 11,02,2012 + - Clarify that implementing in terms of eglSwapBuffers would be + compliant. + Version 5, 11,02,2012 + - Tweak the cases where we report BAD_PARAMETER errors + Version 6, 05/02/2013 + - Specify more thorough updates across the EGL 1.4 spec + wherever it relates to the eglSwapBuffers api + - Clarify that passing <n_rects> of 0 behaves as if + eglSwapBuffers were called. + Version 7, 14/02/2013 + - Specify that a bottom-left origin should be used for rectangles + Version 8, 19/03/2013 + - Add Ian and James as contributors + - Add an issue explaining why we changed to a bottom-left origin + - Clarify that the behaviour is undefined when presenting to a + native window that has been resized. + - Document the awkward details that would be involved in + providing more strict guarantees when presenting to a native + window that has been resized. + Version 9, 12/06/2013, Chad Versace <chad.versace@intel.com> + - Remove the "all rights reserved" clause from the copyright notice. The + removal does not change the copyright notice's semantics, since the + clause is already implied by any unadorned copyright notice. But, the + removal does diminish the likelihood of unwarranted caution in readers + of the spec. + - Add "IP Status" section to explicitly state that this extension has no + knonw IP claims. + Version 10, 23/10/2014, Jon Leech + - Remove copyright after signoff from Intel. + Version 11, 20/02/2020, Jon Leech + - Constify rects parameter (EGL-Registry issue 98). diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_sync_reuse.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_sync_reuse.txt new file mode 100644 index 0000000..4c8ebb1 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_sync_reuse.txt @@ -0,0 +1,376 @@ +Name + + EXT_sync_reuse + +Name Strings + + EGL_EXT_sync_reuse + +Contributors + + Daniel Kartch + Jeff Vigil + Ray Smith + +Contacts + + Daniel Kartch, NVIDIA Corporation (dkartch 'at' nvidia.com) + +Status + + Complete + +Version + + Version 4, May 16, 2018 + +Number + + EGL Extension #128 + +Extension type + + EGL display extension + +Dependencies + + Requires EGL 1.5 or EGL 1.4 with EGL_KHR_fence_sync + + Interacts with EGL_KHR_reusable_sync + Interacts with EGL_ANDROID_native_fence_sync + Interacts with EGL_NV_cuda_event + + This extension is written against the wording of the EGL 1.5 + Specification. + +Overview + + The original EGLSync extensions separated sync objects into two + types: fence sync objects signaled by one time events in an + API command pipeline; and reusable sync objects signaled by commands + which can be issued again and again. However, this conflates + reusability of the event triggering a sync object with the EGLSync + object itself. + + Although the event associated with a fence sync object will only + occur once, there is no reason that it can't be replaced with a new + event. Doing so would avoid unnecessary allocation and free + operations in an application that repeatedly waits for events. With + the current interfaces, such applications must constantly create and + destroy new EGLSync objects. + + This extension allows all sync objects to be reusable. When a sync + object is in the signaled state, it can be reset back to an + unsignaled state, regenerating or reevaluating the events that + trigger them. For fence sync objects, this means generating a new + fence in the current API. For OpenCL event sync objects, this means + waiting for a new OpenCL event handle. This mechanism also allows + sync objects to be created in the signaled state with no associated + fence/event, and have one applied later. Thus all EGLSyncs required + by an application can be allocated up front, before any rendering + operations have begun. + +New Types + + None + +New Tokens + + None + +New Procedures and Functions + + EGLBoolean eglUnsignalSyncEXT( + EGLDisplay dpy, + EGLSync sync, + const EGLAttrib *attrib_list); + +Replace text of subsections of 3.8.1 through 3.8.1.2 of EGL 1.5 +Specification. Existing tables are preserved. + + 3.8.1 Sync Objects + + In addition to the aforementioned synchronization functions, which + provide an efficient means of serializing client and native API + operations within a thread, <sync objects> are provided to enable + synchronization of client API operations between threads and/or + between API contexts. Sync objects may be tested or waited upon by + application threads. + + Sync objects have a status with two possible states: <signaled> and + <unsignaled>, and may initially be in either state. EGL may be asked + to wait for a sync object to become signaled, or a sync objects + status may be queried. + + Depending on the type of a sync object, its status may be changed + either by an external event, or by explicitly signaling and/or + unsignaling the sync. All sync objects are reusable. Once they enter + the signaled state, they may be changed back to unsignaled, possibly + replacing the associated external event that signals them. + + Sync objects are associated with an EGLDisplay when they are + created, and have <attributes> defining additional aspects of the + sync object. All sync objects include attributes for their type and + their status. Additional attributes are discussed below for + different types of sync objects. If a sync object is created in the + signaled state, its initial attribute list may be incomplete, with + attributes necessary for its type provided when it is changed to + unsignaled. + + <Fence sync objects> have an associated fence command in a client + API. A new fence command is generated whenever the sync object + enters the unsignaled state. When the client API executes the fence + command, an event is generated which signals the corresponding fence + sync object. Fence sync objects may not be explicitly signaled. + Fence sync objects may be used to wait for partial completion of a + client API command stream, as a more flexible form of glFinish or + vgFinish. + + An <OpenCL event sync object> reflects the status of a corresponding + OpenCL event object to which the sync object is linked. This + provides another method of coordinating sharing of images between + EGL and OpenCL (see Chapter 9 of the OpenCL 1.0 Specification and + the cl_khr_egl_image extension). Waiting on such a sync object is + equivalent to waiting for completion of the linked OpenCL event + object. + + The command + + EGLSync eglCreateSync(EGLDisplay dpy, EGLenum type, const + EGLAttrib *attrib_list); + + creates a sync object of the specified <type> associated with the + specified display <dpy>, and returns a handle to the new object. + <attrib list> is NULL or an attribute-value list specifying other + attributes of the sync object, terminated by an attribute entry + EGL_NONE. Attributes not specified in the list will be assigned + their default values. + + The EGL_SYNC_STATUS attribute is defined for all sync types, but may + only be specified explicitly at creation time for some types of sync + objects, as discussed below. Other attributes are only allowed as + indicated below for the sync type. + + Errors + + eglCreateSync returns EGL_NO_SYNC on failure. + If <dpy> is not the name of a valid, initialized EGLDisplay, an + EGL_BAD_DISPLAY error is generated. + If <attrib_list> contains an attribute name not defined or not + allowed for the type of sync object being created, an + EGL_BAD_ATTRIBUTE error is generated. + If <type> is not a supported type of sync object, an + EGL_BAD_PARAMETER error is generated. + If <type> is EGL_SYNC_FENCE, the EGL_SYNC_STATUS attribute is + set to EGL_UNSIGNALED, and any of the following are true of the + current context for the bound API (the context returned by + eglGetCurrentContext), an EGL_BAD_MATCH error is generated: + * There is no current context (i.e., eglGetCurrentContext + returns EGL_NO_CONTEXT). + * <dpy> does not match the EGLDisplay of the context (the + EGLDisplay returned by eglGetCurrentDisplay). + * The context does not support fence commands. + + While in the unsignaled state, the synchronization event associated + with a sync object cannot be changed. When the <condition> of a sync + object in the unsignaled state is satisfied, the sync is signaled, + causing any eglClientWaitSync or eglWaitSync commands (see below) + blocking on the sync to unblock. + + Once signaled, a sync object may be reused for a new synchronization + event by switching it back to unsignaled. The command + + EGLBoolean eglUnsignalSyncEXT(EGLDisplay dpy, EGLSync sync, + const EGLAttrib *attrib_list); + + can be used to change the <sync> associated with display <dpy> from + the signaled state to the unsignaled state. The attribute list may + be used to provide or replace attributes specific to the sync type + as discussed below. The sync object's type and condition may not be + changed. + + Errors + + eglUnsignalSyncEXT returns EGL_FALSE on failure, and has no + effect on <sync>. + If <dpy> is not the name of a valid, initialized EGLDisplay, an + EGL_BAD_DISPLAY error is generated. + If <sync> is not a valid sync object associated with <dpy>, an + EGL_BAD_PARAMETER error is generated. + If <attrib_list> contains an attribute name not defined for the + type of <sync>, an EGL_BAD_ATTRIBUTE error is generated. + If <sync> is already in the unsignaled state, an EGL_BAD_ACCESS + error is generated. + If <sync>'s type is EGL_SYNC_FENCE and any of the following are + true of the current context for the bound API (the context + returned by eglGetCurrentContext), an EGL_BAD_MATCH error is + generated: + * There is no current context (i.e., eglGetCurrentContext + returns EGL_NO_CONTEXT). + * <dpy> does not match the EGLDisplay of the context (the + EGLDisplay returned by eglGetCurrentDisplay). + * The context does not support fence commands. + If <sync>'s type is EGL_SYNC_CL_EVENT and EGL_CL_EVENT_HANDLE + is not specified in <attrib_list>, then an EGL_BAD_ATTRIBUTE + error is generated. + + 3.8.1.1 Creating and Signaling Fence Sync Objects + + If type is EGL_SYNC_FENCE, a fence sync object is created. The + EGL_SYNC_STATUS attribute may be specified as either EGL_UNSIGNALED + or EGL_SIGNALED, and will default to EGL_UNSIGNALED. No other + attributes may be specified for a fence sync object, either with + eglCreateSync or eglUnsignalSyncEXT. Queriable attributes of the + fence sync object are set as shown in table 3.7. + + When a fence sync object is created in the unsignaled state, or + switched to that state with eglUnsignalSyncEXT, a fence command is + inserted into the command stream of the bound client APIs current + context (i.e., the context returned by eglGetCurrentContext), and is + associated with the sync object. + + The only condition supported for fence sync objects is + EGL_SYNC_PRIOR_COMMANDS_COMPLETE, which is satisfied by completion + of the fence command corresponding to the sync object, and all + preceding commands in the associated client API contexts command + stream. The sync object will not be signaled until all effects from + these commands on the client APIs internal and framebuffer state + are fully realized. No other state is affected by execution of the + fence command. + + Generation of fence commands for fence sync objects requires support + from the bound client API, and will not succeed unless the client + API satisfies one of the following properties. Note that eglWaitSync + (see section 3.8.1.3) also requires satisfying these conditions. + * client API is OpenGL, and either the OpenGL version is 3.2 or + greater, or the GL_ARB_sync extension is supported. + * client API is OpenGL ES, and either the OpenGL ES version is 3.0 + or greater, or the GL_OES_EGL_sync extension is supported. + * client API is OpenVG, and the VG_KHR_EGL_sync extension is + supported. + + 3.8.1.2 Creating and Signaling OpenCL Event Sync Objects + + If type is EGL_SYNC_CL_EVENT, an OpenCL event sync object is + created. The EGL_SYNC_STATUS attribute may not be explicitly + specified during creation of this type of sync object. If no + EGL_CL_EVENT_HANDLE attribute is specified at creation time, the + sync object will be created in the signaled state. Otherwise its + status will be determined by the provided OpenCL event, as described + below. An EGL_CL_EVENT_HANDLE must always be specified for + eglUnsignalSyncEXT. + + To use an OpenCL event sync object, the EGL_SYNC_CL_EVENT attribute + must be set to a valid OpenCL <event> handle returned by a call to + clEnqueueReleaseGLObjects or clEnqueueReleaseEGLObjects; other types + of OpenCL event handles are not supported. Implementations are not + required to validate the OpenCL event, and passing an invalid event + handle in <attrib_list> may result in undefined behavior up to and + including program termination. Note that EGL_CL_EVENT_HANDLE is not + a queriable property of a sync object. Queriable attributes of the + OpenCL event sync object are set as shown in table 3.8. + + The status of such a sync object depends on <event>. When the status + of <event> is CL_QUEUED, CL_SUBMITTED, or CL_RUNNING, the status of + the linked sync object will be EGL_UNSIGNALED. When the status of + <event> changes to CL_COMPLETE, the status of the linked sync object + will become EGL_SIGNALED. + + The only condition supported for OpenCL event sync objects is + EGL_SYNC_CL_EVENT_COMPLETE, which is satisfied when the status of + the OpenCL event associated with the sync object changes to + CL_COMPLETE. + + Associating an OpenCL event handle with a sync object places a + reference on the linked OpenCL object. When the sync object is + deleted or the event handle is replaced, the reference will be + removed from the OpenCL object. + +If EGL_KHR_reusable_sync is present, then for sync objects of type +EGL_SYNC_REUSABLE_KHR, the initial value of EGL_SYNC_STATUS may be +set to either EGL_UNSIGNALED or EGL_SIGNALED, and will default to +EGL_UNSIGNALED. + +If EGL_ANDROID_native_fence_sync is present, then for native fence sync +objects, the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute may be specified +in eglUnsignalSyncEXT as well as eglCreateSync. If it is set to anything +other than EGL_NO_NATIVE_FENCE_FD_ANDROID at creation time, then its +initial EGL_SYNC_STATUS will reflect the current status of the provided +fence FD, and it is an error to specifically set the status. If it is +set to EGL_NO_NATIVE_FENCE_FD_ANDROID, then its EGL_SYNC_STATUS may be +set to either EGL_UNSIGNALED (the default) or EGL_SIGNALED. If the +status is signaled, then no native fence will be generated until after +it is switched to unsignaled. If eglUnsignalSyncEXT is called for a +native fence sync object with an FD of EGL_NO_NATIVE_FENCE_FD_ANDROID, +then a new native fence will be generated at the next Flush(), as +described for eglCreateSync. + +If EGL_NV_cuda_event is present, then for CUDA event sync objects, the +EGL_CUDA_EVENT_HANDLE_NV may be specified in eglUnsignalSyncEXT as well +as eglCreateSync. The current CUDA event handle is evaluated at the time +the EGL sync object becomes unsignaled, and subsequent modification of +the CUDA object with cudaEventRecord has no effect on the sync object +until it is signaled. Subsequently restoring the sync object to +unsignaled will cause the CUDA object to be reevaluated. + +Issues + + 1. Should a new attribute be required to specify a sync object as + reusable? + + RESOLVED: No. The presence of this extension is sufficient to + indicate reusability of all sync objects. This will not create + any incompatibilities with existing applications that use sync + objects only once. + + 2. Can we leverage the existing eglSignalSyncKHR function from + EGL_KHR_reusable_sync for this extension? + + RESOLVED: No. Some types of sync objects require attributes + which are themselves single-use objects, and must be replaced + for the sync object to be reused. Therefore a new function which + takes an attribute list is required. + + 3. Should the function for unsignaling be based on eglSignalSyncKHR + from the KHR_reusable_sync extension, and take a mode parameter + to distinguish signaling/unsignaling? + + RESOLVED: No. While all sync objects will support unsignaling, + the reusable sync object is the only known one that supports + direct signaling, rather than signaling through some condition + being achieved. Therefore it is simplest to have the new + function only support unsignaling, and continue to use the old + extension for the one case where signaling is required. + + 4. If the initial attribute list is incomplete (e.g. an OpenCL + event handle is not provided during creation of an OpenCL event + sync object), should the EGL_SYNC_STATUS default to EGL_SIGNALED + rather than generating an error if it is left unspecified? + + RESOLVED: Handling of allowed/default values for EGL_SYNC_STATUS + is based on the sync type. For fence syncs, either value is + allowed, defaulting to EGL_UNSIGNALED. For OpenCL event syncs, + the value may not be specified, and instead is determined by + whether an OpenCL event is provided at creation time, and if so + by the status of that event. + +Revision History + + #4 (May 16, 2018) Daniel Kartch + - Minor corrections to wording + + #3 (April 20, 2018) Daniel Kartch + - Renamed to EXT + - Fixed grammatical errors and prepared for publication + + #2 (January 23, 2018) Daniel Kartch + - Rewrote some sections for clarity, and fixed typos + - Changed default/allowed behavior for signal state at creation + time to be determined by the sync type and other attributes. + - Simplified interaction with EGL_KHR_reusable_sync. + - Refined interaction with EGL_ANDROID_native_fence_sync to + clarify allowed initial states for the sync status and fix the + description of when new native fences are generated. + + #1 (January 16, 2018) Daniel Kartch + - Initial draft as XXX diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_yuv_surface.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_yuv_surface.txt new file mode 100644 index 0000000..15b854e --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_yuv_surface.txt @@ -0,0 +1,393 @@ +Name + + EXT_yuv_surface + +Name Strings + + EGL_EXT_yuv_surface + +Contributors + + Matt Trusten + Jeff Vigil + Arshad Bebal + Mohan Maiya + Amit Bansal + Tom Longo + Eric Engestrom + +Contacts + + Jeff Vigil, Qualcomm (jvigil 'at' qualcomm.com) + +Notice + + Copyright (c) 2014 Qualcomm Technologies, Inc. All Rights Reserved. + Qualcomm Technologies Proprietary and Confidential + +Status + + Complete + +Version + + Version 9, May 4th, 2017 + +Number + + EGL Extension #86 + +Dependencies + + EGL 1.4 is required. + + This extension is written against the wording of the EGL 1.4 + Specification. + +Overview + + This extension defines a set of new EGL configuration attributes and values + which allows EGL to create and use YUV surfaces. + + YUV formats can be described using a few simple parameters, and every format + can be given with these six parameters. These parameters include the color + order, the number of planes, subsample, plane depth, color conversion and + depth range. + + This extension describes how EGL will handle YUV surfaces, but requires that + the client API describe how to fill such a surface. An example of such an + extension would be GL_EXT_yuv_target. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + A new set of EGLConfig attributes are available: + EGL_YUV_ORDER_EXT 0x3301 + EGL_YUV_NUMBER_OF_PLANES_EXT 0x3311 + EGL_YUV_SUBSAMPLE_EXT 0x3312 + EGL_YUV_DEPTH_RANGE_EXT 0x3317 + EGL_YUV_CSC_STANDARD_EXT 0x330A + EGL_YUV_PLANE_BPP_EXT 0x331A + + Accepted as a new value for the EGL_COLOR_BUFFER_TYPE attribute: + EGL_YUV_BUFFER_EXT 0x3300 + + Accepted values for the EGL_YUV_ORDER_EXT attribute: + EGL_YUV_ORDER_YUV_EXT 0x3302 + EGL_YUV_ORDER_YVU_EXT 0x3303 + EGL_YUV_ORDER_YUYV_EXT 0x3304 + EGL_YUV_ORDER_UYVY_EXT 0x3305 + EGL_YUV_ORDER_YVYU_EXT 0x3306 + EGL_YUV_ORDER_VYUY_EXT 0x3307 + EGL_YUV_ORDER_AYUV_EXT 0x3308 + + Accepted values for the EGL_YUV_SUBSAMPLE_EXT attribute: + EGL_YUV_SUBSAMPLE_4_2_0_EXT 0x3313 + EGL_YUV_SUBSAMPLE_4_2_2_EXT 0x3314 + EGL_YUV_SUBSAMPLE_4_4_4_EXT 0x3315 + + Accepted values for the EGL_YUV_DEPTH_RANGE_EXT attribute: + EGL_YUV_DEPTH_RANGE_LIMITED_EXT 0x3318 + EGL_YUV_DEPTH_RANGE_FULL_EXT 0x3319 + + Accepted values for the EGL_YUV_CSC_STANDARD_EXT attribute: + EGL_YUV_CSC_STANDARD_601_EXT 0x330B + EGL_YUV_CSC_STANDARD_709_EXT 0x330C + EGL_YUV_CSC_STANDARD_2020_EXT 0x330D + + Accepted values for the EGL_YUV_PLANE_BPP_EXT attribute: + EGL_YUV_PLANE_BPP_0_EXT 0x331B + EGL_YUV_PLANE_BPP_8_EXT 0x331C + EGL_YUV_PLANE_BPP_10_EXT 0x331D + +Additions to Chapter 2 of the EGL 1.4 Specification (EGL Operation) + +Change the options of paragraph 6 from section 2.2: Rendering Contexts and +Drawing Surfaces + + A context can be used with any EGLSurface that it is compatible with + (subject to the restrictions discussed in the section on address space). A + surface and context are compatible if + * They support the same type of color buffer (RGB or luminance) + +To the following: + + A context can be used with any EGLSurface that it is compatible with + (subject to the restrictions discussed in the section on address space). A + surface and context are compatible if + * They support the same type of color buffer (RGB, YUV, or luminance) + +Additions to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors) + +Change the section marked from Buffer Descriptions and Attributes in Section 3.4 +to: + + The Color Buffer + + The color buffer contains pixel color values, and is shared by all + client APIs rendering to a surface. + EGL_COLOR_BUFFER_TYPE indicates the color buffer type, and must be + either EGL_RGB_BUFFER for an RGB color buffer, EGL_LUMINANCE_BUFFER for a + luminance color buffer, or EGL_YUV_BUFFER_EXT for a YUV color buffer. For + an RGB buffer, EGL_RED_SIZE, EGL_GREEN_SIZE, EGL_BLUE_SIZE must be non-zero, + and EGL_LUMINANCE_SIZE must be zero. For a luminance buffer, EGL_RED_SIZE, + EGL_GREEN_SIZE, EGL_BLUE_SIZE must be zero, and EGL_LUMINANCE_SIZE must be + non-zero. For both RGB and luminance color buffers, EGL_ALPHA_SIZE may be + zero or non-zero (the latter indicates the existence of a destination alpha + buffer). For a YUV buffer, all of EGL_RED_SIZE, EGL_GREEN_SIZE, EGL_BLUE_- + SIZE, EGL_LUMINANCE_SIZE, and EGL_ALPHA_SIZE must be zero. Instead, the + depth in bits per pixel for YUV is described using EGL_YUV_PLANE_BPP_EXT, + which describes the size of a single pixel in the Y plane, and the other + plane depths are derived from this. + EGL_YUV_ORDER_EXT is used to describe the plane order. + EGL_YUV_NUMBER_OF_PLANES_EXT describes the number of planes that will + be used for this surface. The allowed values for EGL_YUV_NUMBER_OF_PLANES_- + EXT must be greater than zero and not more than three. + EGL_YUV_SUBSAMPLE_EXT allows the user to decide how the surface will be + subsampled. + + Valid combinations are: + + EGL_YUV_SUBSAMPLE_EXT EGL_YUV_NUMBER_OF_PLANES_EXT EGL_YUV_ORDER_EXT EGL_YUV_PLANE_BPP_EXT + ------------------------- ----------------------------- ------------------ ------------------------ + EGL_YUV_SUBSAMPLE_4_2_0_EXT 2 or 3 EGL_YUV_ORDER_YUV_EXT or EGL_YUV_PLANE_BPP_8_EXT or + EGL_YUV_ORDER_YVU_EXT EGL_YUV_PLANE_BPP_10_EXT + + EGL_YUV_SUBSAMPLE_4_2_2_EXT 1 EGL_YUV_ORDER_YUYV_EXT or EGL_YUV_PLANE_BPP_8_EXT or + EGL_YUV_ORDER_YVYU_EXT or EGL_YUV_PLANE_BPP_10_EXT + EGL_YUV_ORDER_UYVY_EXT or + EGL_YUV_ORDER_VYUY_EXT + + EGL_YUV_SUBSAMPLE_4_2_2_EXT 2 or 3 EGL_YUV_ORDER_YUV_EXT or EGL_YUV_PLANE_BPP_8_EXT or + EGL_YUV_ORDER_YVU_EXT EGL_YUV_PLANE_BPP_10_EXT + + EGL_YUV_SUBSAMPLE_4_4_4_EXT 1 EGL_YUV_ORDER_AYUV_EXT EGL_YUV_PLANE_BPP_8_EXT or + EGL_YUV_PLANE_BPP_10_EXT + + Usage examples: + + Format Combination + ------------------ -------------------------------------------------------------- + NV12 EGL_YUV_SUBSAMPLE_EXT = EGL_YUV_SUBSAMPLE_4_2_0_EXT + - YUV420 EGL_YUV_NUMBER_OF_PLANES_EXT = 2 + - 2 Planes : Y + UV EGL_YUV_ORDER_EXT = EGL_YUV_ORDER_YUV_EXT + - 8 bit depth EGL_YUV_PLANE_BPP_EXT = EGL_YUV_PLANE_BPP_8_EXT + + NV21 EGL_YUV_SUBSAMPLE_EXT = EGL_YUV_SUBSAMPLE_4_2_0_EXT + - YUV420 EGL_YUV_NUMBER_OF_PLANES_EXT = 2 + - 2 Planes : Y + VU EGL_YUV_ORDER_EXT = EGL_YUV_ORDER_YVU_EXT + - 8 bit depth EGL_YUV_PLANE_BPP_EXT = EGL_YUV_PLANE_BPP_8_EXT + + YV12 EGL_YUV_SUBSAMPLE_EXT = EGL_YUV_SUBSAMPLE_4_2_0_EXT + - YUV420 EGL_YUV_NUMBER_OF_PLANES_EXT = 3 + - 3 Planes : Y + V + U EGL_YUV_ORDER_EXT = EGL_YUV_ORDER_YVU_EXT + - 8 bit depth EGL_YUV_PLANE_BPP_EXT = EGL_YUV_PLANE_BPP_8_EXT + + YUY2 EGL_YUV_SUBSAMPLE_EXT = EGL_YUV_SUBSAMPLE_4_2_2_EXT + - YUV422 EGL_YUV_NUMBER_OF_PLANES_EXT = 1 + - 1 Plane : Y + U + Y + V EGL_YUV_ORDER_EXT = EGL_YUV_ORDER_YUYV_EXT + - 8 bit depth EGL_YUV_PLANE_BPP_EXT = EGL_YUV_PLANE_BPP_8_EXT + + AYUV EGL_YUV_SUBSAMPLE_EXT = EGL_YUV_SUBSAMPLE_4_4_4_EXT + - YUV444 EGL_YUV_NUMBER_OF_PLANES_EXT = 1 + - 1 Plane : A + Y + U + V EGL_YUV_ORDER_EXT = EGL_YUV_ORDER_AYUV_EXT + - 8 bit depth EGL_YUV_PLANE_BPP_EXT = EGL_YUV_PLANE_BPP_8_EXT + + YUV420 Semi-Planar 10 Bit EGL_YUV_SUBSAMPLE_EXT = EGL_YUV_SUBSAMPLE_4_2_0_EXT + - YUV420 EGL_YUV_NUMBER_OF_PLANES_EXT = 2 + - 2 Planes : Y + UV EGL_YUV_ORDER_EXT = EGL_YUV_ORDER_YUV_EXT + - 10 bit depth EGL_YUV_PLANE_BPP_EXT = EGL_YUV_PLANE_BPP_10_EXT + + YUV422 Interleaved 10 Bit EGL_YUV_SUBSAMPLE_EXT = EGL_YUV_SUBSAMPLE_4_2_2_EXT + - YUV422 EGL_YUV_NUMBER_OF_PLANES_EXT = 1 + - 1 Plane : Y + U + Y + V EGL_YUV_ORDER_EXT = EGL_YUV_ORDER_YUYV_EXT + - 8 bit depth EGL_YUV_PLANE_BPP_EXT = EGL_YUV_PLANE_BPP_10_EXT + + EGL_YUV_PLANE_BPP_EXT describes the bit depth for the different + planes of a YUV surface. The available options are EGL_YUV_PLANE_BPP_0_- + EXT, EGL_YUV_PLANE_BPP_8_EXT and EGL_YUV_PLANE_BPP_10_EXT. If EGL_YUV_- + PLANE_BPP_0_EXT is specified, no color buffer will be created for the + surface. + EGL_YUV_DEPTH_RANGE_EXT describes the range of the pixel value and is + dependent on the EGL_YUV_PLANE_BPP_EXT setting: + + EGL_YUV_PLANE_BPP_EXT EGL_YUV_DEPTH_RANGE_LIMITED_EXT EGL_YUV_DEPTH_RANGE_FULL_EXT + (Inclusive) (Inclusive) + ------------------------- -------------------------------- ----------------------------- + EGL_YUV_PLANE_BPP_8_EXT or Y: 16 to 235, UV: 16 to 240 Y: 0 to 255, UV: 0 to 255 + EGL_YUV_PLANE_BPP_10_EXT Y: 64 to 940, UV: 64 to 960 Y: 0 to 1023, UV: 0 to 1023 + + If OpenGL or OpenGL ES rendering is supported for a luminance color + buffer (as described by the value of the EGL_RENDERABLE_TYPE attribute, + described below), it is treated as RGB rendering with the value of + GL_RED_BITS equal to EGL_LUMINANCE_SIZE and the values of GL_GREEN_BITS and + GL_BLUE_BITS equal to zero. The red component of fragments is written to the + luminance channel of the color buffer, the green and blue components are + discarded, and the alpha component is written to the alpha channel of the + color buffer (if present). + When rendering to the YUV surface, if EGL_YUV_ORDER_EXT is not EGL_- + YUV_ORDER_AYUV_EXT, the alpha channel will always be fully opaque. + Otherwise it is defined by the value provided to the alpha sample. + EGL_BUFFER_SIZE gives the total of the color component bits of the color + buffer for EGL_RGB_BUFFER or for EGL_LUMINANCE_BUFFER. For an RGB color + buffer, the total is the sum of EGL_RED_SIZE, EGL_GREEN_SIZE, EGL_BLUE_SIZE, + and EGL_ALPHA_SIZE. For a luminance color buffer, the total is the sum of + EGL_LUMINANCE_SIZE and EGL_ALPHA_SIZE. When EGL_COLOR_BUFFER_TYPE is of type + EGL_YUV_BUFFER_EXT, this will reflect the enumeration provided + as an integer) for EGL_YUV_PLANE_BPP_EXT, giving a value of 0, 8 or 10. + + Other EGLConfig Attribute Descriptions + + EGL_YUV_CSC_STANDARD_EXT can be set to either EGL_YUV_CSC_STANDARD_- + 601_EXT, EGL_YUV_CSC_STANDARD_709_EXT, or EGL_YUV_CSC_2020_EXT. If the + standard chosen is EGL_YUV_CSC_STANDARD_709_EXT, then the color conversion + follows the ITU-R BT.709 standard. If EGL_YUV_CSC_STANDARD_EXT is set to + EGL_YUV_CSC_2020_EXT, then the color conversion will be processed based on + ITU-R BT.2020. + + +Change option 2 in the section marked as 3.4.1.2 Sorting of EGLConfigs to: + + 2. Special: by EGL_COLOR_BUFFER_TYPE where the precendence is EGL_RGB_- + BUFFER, EGL_LUMINANCE_BUFFER, EGL_YUV_BUFFER_EXT. + +Change option 3 in the section marked as 3.4.1.2 Sorting of EGLConfigs to: + + 3. Special: by larger total number of color bits (for an RGB color buffer, + this is the sum of EGL_RED_SIZE, EGL_GREEN_SIZE, EGL_BLUE_SIZE, and + EGL_ALPHA_SIZE; for a luminance color buffer, the sum of EGL_LUMINANCE_SIZE + and EGL_ALPHA_SIZE; for YUV color buffers, this returns the integer value + with respect to the enumeration provided for EGL_YUV_PLANE_BPP_EXT) If the + requrested number of bits in attrib_list for a particular color component + is 0 or EGL_DONT_CARE, then the number of bits for the component is not + considered. Due to this, YUV color buffers are always last based on this + rule. + +The following options should be added between options 9 and 10 in section +3.4.1.2 (EGL_ALPHA_MASK_SIZE and EGL_NATIVE_VISUAL_TYPE): + + 10. Special: EGL_YUV_ORDER_EXT will be sorted in the following order: + EGL_NONE, EGL_YUV_ORDER_YUV_EXT, EGL_YUV_ORDER_YVU_EXT, EGL_YUV_ORDER_- + YUYV_EXT, EGL_YUV_ORDER_YVYU_EXT, EGL_YUV_ORDER_UYVY_EXT, EGL_YUV_ORDER_- + VYUY_EXT, and EGL_YUV_ORDER_AYUV_EXT. + +Change option 10 in section 3.4.1.2 (EGL_NATIVE_VISUAL_TYPE) to: + + 11. Special: by EGL_NATIVE_VISUAL_TYPE (the actual sort order is + implementation-defined, depending on the meaning of native visual types). + +New State + + Add to table 3.1 (EGLConfig Attributes): + + Attribute Type Notes + ----------------------------- ---- -------------------------------------------- + EGL_YUV_ORDER_EXT enum The order in which the samples will be found + inside the surface + EGL_YUV_NUMBER_OF_PLANES_EXT integer Number of planes for the surface, in the range of [1,3] + EGL_YUV_SUBSAMPLE_EXT enum Describes the sampling rate of the different planes. + EGL_YUV_DEPTH_RANGE_EXT enum Luma plane range. limited is [16,240] and + full range is [0,255] + EGL_YUV_CSC_STANDARD_EXT enum The standard used for color conversion. + EGL_YUV_PLANE_BPP_EXT enum How many bits are used for each plane of + the YUV surface + + Add to table 3.4 (Default values and match criteria for EGLConfig + attributes): + + Attribute Default Selection Sort Sort + Criteria Order Priority + ------------------------- -------------------------------- --------- ------- -------- + EGL_YUV_ORDER_EXT EGL_DONT_CARE Exact Special 10 + EGL_YUV_NUMBER_OF_PLANES_EXT 0 At least None + EGL_YUV_SUBSAMPLE_EXT EGL_DONT_CARE Exact None + EGL_YUV_DEPTH_RANGE_EXT EGL_DONT_CARE Exact None + EGL_YUV_CSC_STANDARD_EXT EGL_DONT_CARE Exact None + EGL_YUV_PLANE_BPP_EXT EGL_DONT_CARE Exact None + +Issues + 1. How will a EGL surface created with a YUV config properly detect that + valid values were used when filling pixel data? + + This problem occurs in situations when a specification which defines + rendering to the YUV surface cannot guarantee values that conform to the + configuration attributes. One possible situation for this is when a + the GL client is using GL_EXT_yuv_target and the EGL YUV surface is the + draw buffer. The shader can transform the values inside the shader, and + there is no guarantee that the values will fall into the EGL_YUV_DEPTH_- + RANGE_EXT value chosen. Other client specifications could have similar + issues and it may not be performant for some hardware to detect this + discrepancy. This includes interactions with extensions such as EGL_- + lock_surface, or any others that provide a mechanism to change the + contents of the YUV surface. + + One of the problems that can occur in situations like this will be + compound mathematical error should operations need to take place on the + buffer data. + + Proposal: Due to the performance problems or inability in some hardware + to deal with this issue, the pixel contents will be undefined and any + further operations to the pixel contents will also be undefined. + Therefore it is up to the application to guarantee the correct values + are stored within the surface. The EGL implementation need not attempt + any form of verification on the pixel data of the YUV surface, nor does + it have to guarantee the pixel data, even with communicating the surface + to other modules through a post or any other operation EGL performs. + + 2. Should an EGL_COLOR_BUFFER_TYPE = EGL_DONT_CARE request enumerate all + YUV configs? + + Resolved: Revision #9 changes the default values and selection criteria + to allow for full enumeration of all YUV configs. The default value of + EGL_COLOR_BUFFER_TYPE remains EGL_RGB_BUFFER, so this change only + affects explicit EGL_DONT_CARE requests. + +Example Configuration for NV12: + + const EGLint config_attribs[] = + { + EGL_SURFACE_TYPE, EGL_WINDOW_BIT, + EGL_RENDERABLE_TYPE, EGL_OPENGL_ES2_BIT, + EGL_COLOR_BUFFER_TYPE, EGL_YUV_BUFFER_EXT, + EGL_YUV_ORDER_EXT, EGL_ORDER_YUV_EXT, + EGL_YUV_NUMBER_OF_PLANES_EXT, 2, + EGL_YUV_SUBSAMPLE_EXT, EGL_YUV_SUBSAMPLE_4_2_0_EXT, + EGL_YUV_DEPTH_RANGE_EXT, EGL_YUV_DEPTH_RANGE_LIMITED_EXT, + EGL_YUV_CSC_STANDARD_EXT, EGL_YUV_CSC_STANDARD_601_EXT, + EGL_YUV_PLANE_BPP_EXT, EGL_YUV_PLANE_BPP_8_EXT, + EGL_NONE + }; + +Revision History +#1 March 12th, 2014 Initial Draft. + +#2 March 25th, 2014 Reformated and added more detail. + +#3 March 26th, 2014 Added usage examples. + Added memory layout definitions. + +#4 March 26th, 2014 Fixed some typos and formatting. + +#5 May 21st, 2014 Fixed some inconsistencies. + Added EGL_YUV_PLANE_DEPTH_0_QCOM. + +#6 May 27th, 2014 Relaxed some requirements. + Changed EGL_YUV_PLANE_DEPTH_<0,8,10>_QCOM to + EGL_YUV_PLANE_BPP_<0,8,10>_QCOM. + Added more detail. + +#7 October 7th, 2014 Issue (1) added. + Minor updates made (EXT_yuv_target) + +#8 October 24th, 2014 Updated for EXT and token values. + +#9 April 26th, 2017 Changed attributes default values and selection + criteria (see issue #2). + Changed status from Draft to Complete. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/HI/EGL_HI_clientpixmap.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/HI/EGL_HI_clientpixmap.txt new file mode 100644 index 0000000..5ca366d --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/HI/EGL_HI_clientpixmap.txt @@ -0,0 +1,144 @@ +Name + + HI_clientpixmap + +Name Strings + + EGL_HI_clientpixmap + +Contributors + + Guillaume Portier + +Contacts + + HI support. (support_renderion 'at' hicorp.co.jp) + +Status + + Shipping (Revision 3). + +Version + + Last Modified Date: June 7, 2010 + Revision 3 + +Number + + EGL Extension #24 + +Dependencies + + This extension is written against the wording of the EGL 1.4 + Specification. + +Overview + + The extension specified in this document provide a mechanism for + using memory allocated by the application as a color-buffer. + + +New Types + + EGLClientPixmapHI : specifies the width, height, stride, format + and memory pointer of the pixmap to be used by the function + eglCreatePixmapSurfaceHI to create the PixmapSurface. + + Members: + void* pData; + Pointer to a memory buffer allocated by the application + that will contain the result of the drawing operations. + It is up to the application to ensure that the buffer + size corresponds to iHeight * iStride * sizeof(pixel). + EGLint iWidth; + Width of the buffer in pixels. + EGLint iHeight; + Height of the buffer in pixels. The height of the buffer + can be negative; in that case the result of the + drawing operations will be vertically swapped. When + positive, pData will point at the bottom-left corner + of the image; when negative, to the top-left corner. + EGLint iStride; + Stride of the buffer, in pixels. It is important to note + that each row of the buffer must start on 32-bit + boundaries. + +New Procedures and Functions + + eglCreatePixmapSurfaceHI : creates an EGL ClientPixmap from + an EGLClientPixmapHI structure. eglCreatePixmapSurfaceHI usage + is identical to eglCreatePixmapSurface. In addition the ordering + of the color components in the color buffer can be specified by + the surface attribute described in the EGL_HI_colorformats + extension. + + In order to update the pointer to the data of the surface, the application + can call eglSurfaceAttrib with the EGL_CLIENT_PIXMAP_POINTER_HI attribute. + See below for an example. + +New Tokens + + None. + +Example + + + EGLClientPixmapHI pixmap; + EGLint attrib_list[] = { + EGL_RED_SIZE, 8, + EGL_GREEN_SIZE, 8, + EGL_BLUE_SIZE, 8, + EGL_ALPHA_SIZE, 8, + EGL_SURFACE_TYPE, EGL_PIXMAP_BIT, + // Specifying ARGB as a color format + EGL_COLOR_FORMAT_HI, EGL_COLOR_ARGB_HI, + EGL_NONE + }; + + // ‘access' being the memory to render into. + pixmap.pData = framebuffer.access; + pixmap.iWidht = framebuffer.width; + pixmap.iHeight = framebuffer.height; + pixmap.iStride = framebuffer.stride; + + + + //Get Config ARGB8 + eglChooseConfig(dpy, attrib_list, &config, 1, &num_config); + + // Create the pixmap + #ifdef EGL_EGLEXT_PROTOTYPES + + eglCreatePixmapSurfaceHI(eglDisplay, ppkConfig[0], &gHiPixmap); + + #else + + pfCreatePixmap = (PFNEGLCREATEPIXMAPSURFACEHIPROC) + eglGetProcAddress("eglCreatePixmapSurfaceHI"); + pfCreatePixmap(eglDisplay, ppkConfig[0], &gHiPixmap); + + #endif /* EGL_EGLEXT_PROTOTYPES */ + + + // Update the surface data pointer, from now we will render into the + // memory pointed by 'access2'. + eglSurfaceAttrib(eglDisplay, eglSurface, EGL_CLIENT_PIXMAP_POINTER_HI, + offscreen.access2); + +Issues + + None + + +Revision History + + June 7, 2010 (r3) + - Allow updating the pixmap data pointer using eglSurfaceAttrib with + the EGL_CLIENT_PIXMAP_POINTER_HI attribute. + + June 16, 2009 (r2) + - Split HI_clientpixmap into two different extensions: + - HI_colorformats + - HI_clientpixmap + + March 3, 2009 (r1) diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/HI/EGL_HI_colorformats.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/HI/EGL_HI_colorformats.txt new file mode 100644 index 0000000..c8dc97a --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/HI/EGL_HI_colorformats.txt @@ -0,0 +1,138 @@ +Name + + HI_colorformats + +Name Strings + + EGL_HI_colorformats + +Contributors + + Guillaume Portier + +Contacts + + HI support. (support_renderion 'at' hicorp.co.jp) + +Status + + Shipping (Revision 2) + +Version + + Last Modified Date: June 7, 2010 + Revision 2.1 + +Number + + EGL Extension #25 + +Dependencies + + These extensions are written against the wording of the EGL 1.4 + Specification. + +Overview + + The extensions specified in this document provide a mechanism for + creating ARGB color-buffers, as opposed to the default RGBA + format used by other EGL configurations. + +New Types + + None. + +New Procedures and Functions + + None. + +New Tokens + + Accepted in the <attrib_list> parameter of eglChooseConfig. + + EGL_COLOR_FORMAT_HI 0x8F70 + + Accepted as a value for the EGL_COLOR_FORMAT_HI token: + + EGL_COLOR_RGB_HI 0x8F71 + EGL_COLOR_RGBA_HI 0x8F72 + EGL_COLOR_ARGB_HI 0x8F73 + + + The default value for EGL_COLOR_FORMAT_HI is EGL_DONT_CARE. + If EGL_COLOR_FORMAT_HI is used with a value other than + EGL_DONT_CARE, EGL_COLOR_RGB_HI, EGL_COLOR_RGBA_HI or + EGL_COLOR_ARGB_HI then an EGL_BAD_ATTRIBUTE is generated. + + EGL_COLOR_RGB_HI, EGL_COLOR_RGBA_HI and EGL_COLOR_ARGB_HI + specify the order of the color components in the color-buffer. + EGL_COLOR_RGB_HI must be used only with configurations having no + alpha component, currently only 565. + + EGL_COLOR_RGBA_HI and EGL_COLOR_ARGB_HI must be used with + configurations having an alpha component. Currently available + configurations are: + - 4444 + - 5551 + - 8888 + Currently EGL_COLOR_ARGB_HI can be used only with the + 8888 configuration. + + If the value used for EGL_COLOR_FORMAT_HI does not match + the other specified attributes of the EGL config then an + EGL_BAD_MATCH is generated. + + When EGL_COLOR_FORMAT_HI is unspecified or equals EGL_DONT_CARE, + eglChooseConfig returns configurations having all kinds of color + component ordering. + + If eglCreatePixmapSurface is called with a configuration that + does not match the pixmap's native ordering then an EGL_BAD_MATCH + is generated. To be sure to call eglCreatePixmapSurface with a + compatible configuration, the application should either parse + the <configs> list returned by eglChooseConfig or explicitly specify + EGL_COLOR_FORMAT_HI to match the pixmap native format. + +Example + + EGLint attrib_list[] = { + EGL_RED_SIZE, 8, + EGL_GREEN_SIZE, 8, + EGL_BLUE_SIZE, 8, + EGL_ALPHA_SIZE, 8, + EGL_SURFACE_TYPE, EGL_PIXMAP_BIT, + + #ifdef USE_ARGB // Specifying ARGB as a color format + EGL_COLOR_FORMAT_HI, EGL_COLOR_ARGB_HI, + #else // Specifying RGBA as a color format + EGL_COLOR_FORMAT_HI, EGL_COLOR_RGBA_HI, + #endif + + EGL_NONE + }; + + // Get one of the configuration matching the config_list + eglChooseConfig(dpy, attrib_list, &config, 1, &num_config); + + // Create the pixmap + eglCreatePixmapSurface(dpy, config[0], pixmap, NULL); + + +Issues + + None. + + +Revision History + + + June 7, 2010 (r2.1) + - Corrected mistaken description of EGL_COLOR_FORMAT_HI as + attribute for eglCreatePixmapSurface. Clarified other text. + + June 16, 2009 (r2) + - Split HI_clientpixmap into two different extensions: + - HI_colorformats + - HI_clientpixmap + + March 3, 2009 (r1) diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/IMG/EGL_IMG_context_priority.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/IMG/EGL_IMG_context_priority.txt new file mode 100644 index 0000000..fa1b4a6 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/IMG/EGL_IMG_context_priority.txt @@ -0,0 +1,166 @@ +Name + + IMG_context_priority + +Name Strings + + EGL_IMG_context_priority + +Contributors + + Ben Bowman, Imagination Techonologies + Graham Connor, Imagination Techonologies + +Contacts + + Ben Bowman, Imagination Technologies (benji 'dot' bowman 'at' + imgtec 'dot' com) + +Status + + Complete + +Version + + Version 1.1, 8 September 2009 + +Number + + EGL Extension #10 + +Dependencies + + Requires EGL 1.0. + + This extension is written against the wording of the EGL 1.4 + Specification - May 2, 2008 (but may be implemented against earlier + versions). + +Overview + + This extension allows an EGLContext to be created with a priority + hint. It is possible that an implementation will not honour the + hint, especially if there are constraints on the number of high + priority contexts available in the system, or system policy limits + access to high priority contexts to appropriate system privilege + level. A query is provided to find the real priority level assigned + to the context after creation. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + New attributes accepted by the <attrib_list> argument of + eglCreateContext + + EGL_CONTEXT_PRIORITY_LEVEL_IMG 0x3100 + + New attribute values accepted in the <attrib_list> argument + of eglCreateContext: + + EGL_CONTEXT_PRIORITY_HIGH_IMG 0x3101 + EGL_CONTEXT_PRIORITY_MEDIUM_IMG 0x3102 + EGL_CONTEXT_PRIORITY_LOW_IMG 0x3103 + +Additions to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors) + + Modify the list of attributes supported by eglCreateContext in + section 3.7.1 (Creating Rendering Contexts) on p. 42: + + "<attrib_list> specifies a list of attributes for the context. + The list has the same structure as described for + eglChooseConfig. The only attributes that can be specified in + <attrib_list> are EGL_CONTEXT_CLIENT_VERSION and + EGL_CONTEXT_PRIORITY_LEVEL_IMG. The EGL_CONTEXT_CLIENT_VERSION + attribute may only be specified when creating a OpenGL ES + context (e.g. when the current rendering API is + EGL_OPENGL_ES_API). + + <attrib_list> may be NULL or empty (first attribute is + EGL_NONE), in which case attributes assume their default values + as described below. + + EGL_CONTEXT_CLIENT_VERSION determines which version of an OpenGL + ES context to create. An attribute value of 1 specifies creation + of an OpenGL ES 1.x context. An attribute value of 2 specifies + creation of an OpenGL ES 2.x context. The default value for + EGL_CONTEXT_CLIENT_VERSION is 1. + + EGL_CONTEXT_PRIORITY_LEVEL_IMG determines the priority level of + the context to be created. This attribute is a hint, as an + implementation may not support multiple contexts at some + priority levels and system policy may limit access to high + priority contexts to appropriate system privilege level. The + default value for EGL_CONTEXT_PRIORITY_LEVEL_IMG is + EGL_CONTEXT_PRIORITY_MEDIUM_IMG." + + + Modify the list of attributes supported by eglQueryContext in + section 3.7.4 (Context Queries) on p. 46: + + "eglQueryContext returns in <value> the value of attribute for + <ctx>. <attribute> must be set to EGL_CONFIG_ID, + EGL_CONTEXT_CLIENT_TYPE, EGL_CONTEXT_CLIENT_VERSION, + EGL_RENDER_BUFFER, or EGL_CONTEXT_PRIORITY_LEVEL_IMG. + + ... + + Querying EGL_CONTEXT_PRIORITY_LEVEL_IMG returns the priority + this context was actually created with. Note: this may not be + the same as specified at context creation time, due to + implementation limits on the number of contexts that can be + created at a specific priority level in the system." + +ISSUES: + + 1) Should the context priority be treated as a hint or a requirement + + RESOLVED: The context priority should be a hint. System policy may + limit high priority contexts to appropriate system privilege level. + Implementations may have a limit on the number of context supported + at each priority, and may require all contexts within a process to + have the same priority level. + + 2) Can an application find out what priority a context was assigned? + + RESOLVED: Provide a query to find the assigned priority for a + context. An application may find that it has a lower (or higher) + priority than requested (although it probably cannot do much with + the information). + + 3) How many priority levels should be defined? + + RESOLVED: Three seems appropriate, as the highest provides the + largest GPU timeslice and reduced latency. It might be useful to + specify a low priority context which has a small timeslice and high + latency. It is possible that a request for LOW will actually return + MEDIUM on an implementation that doesn't differentiate between the + lower two levels. + + 4) What should the default priority level be if not specified? + + OPTION 1: HIGH - This allows applications that are unaware of + this extension to get the highest priority possible. + + OPTIONS 2: MEDIUM - This allows truly high priority applications + to differentiate themselves from applications which are unaware + of this extension. + + RESOLVED: + OPTION 2: MEDIUM - Allow truly high priority applications to + differentiate themselves. + +Revision History + Version 1.1, 08/09/2009 (Jon Leech) Assign extension number and + publish in the Registry. Formatting cleanup. + Version 1.0, 30/04/2009 - Final clean up. Marked issues as resolved, + take out draft status + Version 0.3, 22/04/2009 - enums assigned from Khronos registry. + Version 0.2, 02/04/2009 - feedback from gdc. + Version 0.1, 31/03/2009 - first draft. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/IMG/EGL_IMG_image_plane_attribs.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/IMG/EGL_IMG_image_plane_attribs.txt new file mode 100644 index 0000000..35841dc --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/IMG/EGL_IMG_image_plane_attribs.txt @@ -0,0 +1,156 @@ +Name + + IMG_image_plane_attribs + +Name Strings + + EGL_IMG_image_plane_attribs + +Contributors + + Ben Bowman + Alistair Strachan + +Contacts + + Tobias Hector, Imagination Technologies (tobias 'dot' hector 'at' + imgtec 'dot' com) + +Status + + Complete + +Version + + Version 0.4, October 18, 2015 + +Number + + EGL Extension #95 + +Dependencies + + EGL_KHR_image_base is required. + + One of EGL_KHR_image, EGL_KHR_image_pixmap or + EGL_ANDROID_image_native_buffer is required. + + This extension is written against the wording of the EGL 1.2 + Specification as modified by EGL_KHR_image_base, + EGL_ANDROID_image_native_buffer and EGL_KHR_image_pixmap. + This extension interacts with GL_OES_EGL_image and GL_EXT_texture_rg. + +Overview + + This extension allows creating an EGLImage from a single plane of a + multi-planar Android native image buffer (ANativeWindowBuffer) or + a native pixmap (EGLNativePixmap). + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted by the <attrib_list> parameter of eglCreateImageKHR: + + EGL_NATIVE_BUFFER_MULTIPLANE_SEPARATE_IMG 0x3105 + EGL_NATIVE_BUFFER_PLANE_OFFSET_IMG 0x3106 + +Additions to Chapter 2 of the EGL 1.2 Specification (EGL Operation) + + Add to section 2.5.1 "EGLImage Specification" (as defined by the + EGL_KHR_image_base specification), in the description of + eglCreateImageKHR: + + Add the following to Table bbb (Legal attributes for eglCreateImageKHR + <attr_list> parameter), Section 2.5.1 (EGLImage Specification) + + +-----------------------------+-------------------------+---------------------------+---------------+ + | Attribute | Description | Valid <target>s | Default Value | + +-----------------------------+-------------------------+---------------------------+---------------+ + | EGL_NATIVE_BUFFER_MULTI | Whether a multiplane | EGL_NATIVE_BUFFER_ANDROID | EGL_FALSE | + | PLANE_SEPARATE_IMG | native buffer should be | EGL_NATIVE_PIXMAP_KHR | | + | | treated as separate | | | + | | buffers | | | + | | | | | + | EGL_NATIVE_BUFFER_ | Which plane of a multi- | EGL_NATIVE_BUFFER_ANDROID | 0 | + | PLANE_OFFSET_IMG | plane native buffer is | EGL_NATIVE_PIXMAP_KHR | | + | | used as the EGLImage | | | + | | source | | | + +-----------------------------+-------------------------+---------------------------+---------------+ + Table bbb. Legal attributes for eglCreateImageKHR <attrib_list> parameter + + ... + + If <target> is EGL_NATIVE_BUFFER_ANDROID or EGL_NATIVE_PIXMAP_KHR, and + <buffer> is a handle to a valid multi-planar surface, such as a YUV420 2 or + 3 planar video surface, an EGLImage will be created from only one of the + planes, as opposed to a single image representing all of the planes as is + normally the case. The intention of this extension is that a call to + glEGLImageTargetTexture2DOES or EGLImageTargetRenderbufferStorageOES with an + EGLImage created from a single plane of a multiplanar buffer will result in + a GL_RED or GL_RG texture or renderbuffer, depending on the format of the + multiplanar buffer. This allows an application to work directly in the YUV + colorspace, rather than forcing a conversion to the linear RGB colorspace, + potentially losing precision. + + The size of each image will represent the actual size of the data buffer + for that plane which may mean that the size of an EGLImage created from + plane 0 of a multi-planar buffer may not be the same as that of one + created from plane 1, which is determined by the YUV's sampling ratio (e.g. + a 420 will have planes 1 and 2, if present, represented by an image of half + the width). + + Add to the list of error conditions for eglCreateImageKHR: + + "* If EGL_NATIVE_BUFFER_MULTIPLANE_SEPARATE_IMG is EGL_TRUE, and <target> + is not EGL_NATIVE_BUFFER_ANDROID or EGL_NATIVE_PIXMAP_KHR, the error + EGL_BAD_PARAMETER is generated. + + * If EGL_NATIVE_BUFFER_MULTIPLANE_SEPARATE_IMG is EGL_TRUE, and + EGL_NATIVE_BUFFER_PLANE_OFFSET_IMG is greater than or equal to the + number of planes in <buffer>, the error EGL_BAD_MATCH is generated. + + * If EGL_NATIVE_BUFFER_MULTIPLANE_SEPARATE_IMG is EGL_FALSE, and + EGL_NATIVE_BUFFER_PLANE_OFFSET_IMG is greater than 0, the error + EGL_BAD_PARAMETER is generated. + + * If EGL_NATIVE_BUFFER_MULTIPLANE_SEPARATE_IMG is EGL_TRUE, and the + format of <buffer> is not supported by the implementation, + EGL_BAD_PARAMETER is generated." + +Dependencies on EGL_KHR_image_pixmap or EGL_KHR_image + + If neither of these extensions are supported, remove all references to + native pixmaps and EGL_NATIVE_PIXMAP_KHR. + +Dependencies on EGL_ANDROID_image_native_buffer + + If this extension is not supported, remove all references to + ANativeWindowBuffer and EGL_NATIVE_BUFFER_ANDROID. + +Issues + + None + +Revision History + +#0.4 (Tobias Hector, October, 2015) + - Add interactions with EGL_KHR_image_pixmap/EGL_KHR_image + - Added error language for unsupported formats +#0.3 (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). Note that this + change implies a new error will be generated when <target> is not + EGL_NATIVE_BUFFER_ANDROID and EGL_NATIVE_BUFFER_PLANE_OFFSET_IMG is + specified in <attrib_list>; this falls out from the generic + target-attribute matching error added to EGL_KHR_image_base. +#0.2 (Ben Bowman, May 30, 2012) + - Fixed some typos +#0.1 (Ben Bowman, May 30, 2012) + - First draft of extension . 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. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/MESA/EGL_MESA_drm_image.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/MESA/EGL_MESA_drm_image.txt new file mode 100644 index 0000000..0937d6b --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/MESA/EGL_MESA_drm_image.txt @@ -0,0 +1,157 @@ +Name + + MESA_drm_image + +Name Strings + + EGL_MESA_drm_image + +Contact + + Kristian Høgsberg <krh@bitplanet.net> + +Status + + Proposal + +Version + + Version 4, November 23, 2017 + +Number + + EGL Extension #26 + +Dependencies + + Requires EGL 1.4 or later. This extension is written against the + wording of the EGL 1.4 specification. + + EGL_KHR_base_image is required. + +Overview + + This extension provides entry points for integrating EGLImage with the + Linux DRM mode setting and memory management drivers. The extension + lets applications create EGLImages without a client API resource and + lets the application get the DRM buffer handles. + +IP Status + + Open-source; freely implementable. + +New Procedures and Functions + + EGLImageKHR eglCreateDRMImageMESA(EGLDisplay dpy, + const EGLint *attrib_list); + + EGLBoolean eglExportDRMImageMESA(EGLDisplay dpy, + EGLImageKHR image, + EGLint *name, + EGLint *handle, + EGLint *stride); + +New Tokens + + Accepted in the <attrib_list> parameter of eglCreateDRMImageMESA: + + EGL_DRM_BUFFER_FORMAT_MESA 0x31D0 + EGL_DRM_BUFFER_USE_MESA 0x31D1 + + Accepted as values for the EGL_IMAGE_FORMAT_MESA attribute: + + EGL_DRM_BUFFER_FORMAT_ARGB32_MESA 0x31D2 + + Bits accepted in EGL_DRM_BUFFER_USE_MESA: + + EGL_DRM_BUFFER_USE_SCANOUT_MESA 0x0001 + EGL_DRM_BUFFER_USE_SHARE_MESA 0x0002 + EGL_DRM_BUFFER_USE_CURSOR_MESA 0x0004 + + Accepted in the <target> parameter of eglCreateImageKHR: + + EGL_DRM_BUFFER_MESA 0x31D3 + + Use when importing drm buffer: + + EGL_DRM_BUFFER_STRIDE_MESA 0x31D4 + EGL_DRM_BUFFER_FORMAT_MESA 0x31D0 + +Additions to the EGL 1.4 Specification: + + To create a DRM EGLImage, call + + EGLImageKHR eglCreateDRMImageMESA(EGLDisplay dpy, + const EGLint *attrib_list); + + In the attribute list, pass EGL_WIDTH, EGL_HEIGHT and format and + use in the attrib list using EGL_DRM_BUFFER_FORMAT_MESA and + EGL_DRM_BUFFER_USE_MESA. The only format specified by this + extension is EGL_DRM_BUFFER_FORMAT_ARGB32_MESA, where each pixel + is a CPU-endian, 32-bit quantity, with alpha in the upper 8 bits, + then red, then green, then blue. The bit values accepted by + EGL_DRM_BUFFER_USE_MESA are EGL_DRM_BUFFER_USE_SCANOUT_MESA, + EGL_DRM_BUFFER_USE_SHARE_MESA and EGL_DRM_BUFFER_USE_CURSOR_MESA. + EGL_DRM_BUFFER_USE_SCANOUT_MESA requests that the created EGLImage + should be usable as a scanout buffer with the DRM kernel + modesetting API. EGL_DRM_BUFFER_USE_SHARE_MESA requests that the + EGLImage can be shared with other processes by passing the + underlying DRM buffer name. EGL_DRM_BUFFER_USE_CURSOR_MESA + requests that the image must be usable as a cursor with KMS. When + EGL_DRM_BUFFER_USE_CURSOR_MESA is set, width and height must both + be 64. + + To create a process local handle or a global DRM name for a + buffer, call + + EGLBoolean eglExportDRMImageMESA(EGLDisplay dpy, + EGLImageKHR image, + EGLint *name, + EGLint *handle, + EGLint *stride); + + If <name> is non-NULL, a global name is assigned to the image and + written to <name>, the handle (local to the DRM file descriptor, + for use with DRM kernel modesetting API) is written to <handle> if + non-NULL and the stride (in bytes) is written to <stride>, if + non-NULL. + + Import a shared buffer by calling eglCreateImageKHR with + EGL_DRM_BUFFER_MESA as the target, using EGL_WIDTH, EGL_HEIGHT, + EGL_DRM_BUFFER_FORMAT_MESA, EGL_DRM_BUFFER_STRIDE_MESA + in the attrib list. + +Issues + + 1. Why don't we use eglCreateImageKHR with a target that + indicates that we want to create an EGLImage from scratch? + + RESOLVED: The eglCreateImageKHR entry point is reserved for + creating an EGLImage from an already existing client API + resource. This is fine when we're creating the EGLImage from + an existing DRM buffer name, it doesn't seem right to overload + the function to also allocate the underlying resource. + + 2. Why don't we use an eglQueryImageMESA type functions for + querying the DRM EGLImage attributes (name, handle, and stride)? + + RESOLVED: The eglQueryImage function has been proposed often, + but it goes against the EGLImage design. EGLImages are opaque + handles to a 2D array of pixels, which can be passed between + client APIs. By referencing an EGLImage in a client API, the + EGLImage target (a texture, a renderbuffer or such) can be + used to query the attributes of the EGLImage. We don't have a + full client API for creating and querying DRM buffers, though, + so we use a new EGL extension entry point instead. + +Revision History + + Version 1, June 3, 2010 + Initial draft (Kristian Høgsberg) + Version 2, August 25, 2010 + Flesh out the extension a bit, add final EGL tokens, capture + some of the original discussion in the issues section. + Version 3, November 29, 2010 (Jon Leech) + Fix typo. + Version 4, November 23, 2017 (Kristian Høgsberg) + Fix typos, add EGL_DRM_BUFFER_USE_CURSOR_MESA diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/MESA/EGL_MESA_image_dma_buf_export.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/MESA/EGL_MESA_image_dma_buf_export.txt new file mode 100644 index 0000000..cc9497e --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/MESA/EGL_MESA_image_dma_buf_export.txt @@ -0,0 +1,147 @@ +Name + + MESA_image_dma_buf_export + +Name Strings + + EGL_MESA_image_dma_buf_export + +Contributors + + Dave Airlie + +Contact + + Dave Airlie (airlied 'at' redhat 'dot' com) + +Status + + Complete, shipping. + +Version + + Version 3, May 5, 2015 + +Number + + EGL Extension #87 + +Dependencies + + Requires EGL 1.4 or later. This extension is written against the + wording of the EGL 1.4 specification. + + EGL_KHR_base_image is required. + + The EGL implementation must be running on a Linux kernel supporting the + dma_buf buffer sharing mechanism. + +Overview + + This extension provides entry points for integrating EGLImage with the + dma-buf infrastructure. The extension allows creating a Linux dma_buf + file descriptor or multiple file descriptors, in the case of multi-plane + YUV image, from an EGLImage. + + It is designed to provide the complementary functionality to + EGL_EXT_image_dma_buf_import. + +IP Status + + Open-source; freely implementable. + +New Types + + This extension uses the 64-bit unsigned integer type EGLuint64KHR + first introduced by the EGL_KHR_stream extension, but does not + depend on that extension. The typedef may be reproduced separately + for this extension, if not already present in eglext.h. + + typedef khronos_uint64_t EGLuint64KHR; + +New Procedures and Functions + + EGLBoolean eglExportDMABUFImageQueryMESA(EGLDisplay dpy, + EGLImageKHR image, + int *fourcc, + int *num_planes, + EGLuint64KHR *modifiers); + + EGLBoolean eglExportDMABUFImageMESA(EGLDisplay dpy, + EGLImageKHR image, + int *fds, + EGLint *strides, + EGLint *offsets); + +New Tokens + + None + + +Additions to the EGL 1.4 Specification: + + To mirror the import extension, this extension attempts to return + enough information to enable an exported dma-buf to be imported + via eglCreateImageKHR and EGL_LINUX_DMA_BUF_EXT token. + + Retrieving the information is a two step process, so two APIs + are required. + + The first entrypoint + EGLBoolean eglExportDMABUFImageQueryMESA(EGLDisplay dpy, + EGLImageKHR image, + int *fourcc, + int *num_planes, + EGLuint64KHR *modifiers); + + is used to retrieve the pixel format of the buffer, as specified by + drm_fourcc.h, the number of planes in the image and the Linux + drm modifiers. <fourcc>, <num_planes> and <modifiers> may be NULL, + in which case no value is retrieved. + + The second entrypoint retrieves the dma_buf file descriptors, + strides and offsets for the image. The caller should pass + arrays sized according to the num_planes values retrieved previously. + Passing arrays of the wrong size will have undefined results. + If the number of fds is less than the number of planes, then + subsequent fd slots should contain -1. + + EGLBoolean eglExportDMABUFImageMESA(EGLDisplay dpy, + EGLImageKHR image, + int *fds, + EGLint *strides, + EGLint *offsets); + + <fds>, <strides>, <offsets> can be NULL if the infomatation isn't + required by the caller. + +Issues + +1. Should the API look more like an attribute getting API? + +ANSWER: No, from a user interface pov, having to iterate across calling +the API up to 12 times using attribs seems like the wrong solution. + +2. Should the API take a plane and just get the fd/stride/offset for that + plane? + +ANSWER: UNKNOWN,this might be just as valid an API. + +3. Does ownership of the file descriptor remain with the app? + +ANSWER: Yes, the app is responsible for closing any fds retrieved. + +4. If number of planes and number of fds differ what should we do? + +ANSWER: Return -1 for the secondary slots, as this avoids having +to dup the fd extra times to make the interface sane. + +Revision History + + Version 3, May, 2015 + Just use the KHR 64-bit type. + Version 2, March, 2015 + Add a query interface (Dave Airlie) + Version 1, June 3, 2014 + Initial draft (Dave Airlie) + diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/MESA/EGL_MESA_platform_gbm.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/MESA/EGL_MESA_platform_gbm.txt new file mode 100644 index 0000000..e40a774 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/MESA/EGL_MESA_platform_gbm.txt @@ -0,0 +1,319 @@ +Name + + MESA_platform_gbm + +Name Strings + + EGL_MESA_platform_gbm + +Contributors + + Chad Versace <chad.versace@intel.com> + Kristian Høgsberg <krh@bitplanet.org> + +Contacts + + Chad Versace <chad.versace@intel.com> + +Status + + Complete + +Version + + Version 7, 2016/01/04 + +Number + + EGL Extension #62 + +Extension Type + + EGL client extension + +Dependencies + + Requires EGL_EXT_client_extensions to query its existence without + a display. + + Requires EGL_EXT_platform_base. + + This extension is written against the wording of version 7 of the + EGL_EXT_platform_base specification. + +Overview + + This extension defines how to create EGL resources from native GBM + resources using the functions defined by EGL_EXT_platform_base. (GBM is + a Generic Buffer Manager for Linux). + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted as the <platform> argument of eglGetPlatformDisplayEXT: + + EGL_PLATFORM_GBM_MESA 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 eglGetPlatformDisplayEXT with + <platform> set to EGL_PLATFORM_GBM_MESA. The <native_display> parameter + specifies the GBM device to use and must either point to a `struct + gbm_device` or be NULL. If <native_display> is NULL, 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 + eglCreatePlatformWindowSurfaceEXT 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 eglCreatePlatformPixmapSurfaceEXT with a <dpy> that + belongs to the GBM platform. Any such call fails and generates + EGL_BAD_PARAMETER. + +Issues + + 1. Should this extension permit NULL as input to eglGetPlatformDisplayEXT? + + RESOLUTION: Yes. When given NULL, eglGetPlatformDisplayEXT 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_MESA_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_MESA_platform_gbm + const char *client_extensions = eglQueryString(EGL_NO_DISPLAY, EGL_EXTENSIONS); + + if (!client_extensions) { + // EGL_EXT_client_extensions is unsupported. + abort(); + } + if (!strstr(client_extensions, "EGL_MESA_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_MESA_platform_gbm + dpy.egl = eglGetPlatformDisplayEXT(EGL_PLATFORM_GBM_MESA, 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_MESA_platform_gbm + window.egl = eglCreatePlatformWindowSurfaceEXT(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 8, 2018-05-25 (Krzysztof Kosiński) + - Corrected EGL_DEFAULT_DISPLAY to NULL. The second argument to + eglGetPlatformDisplayEXT has type void*, while EGL_DEFAULT_DISPLAY has + type EGLNativeDisplayType, which is not guaranteed to be convertible + to void* - it could be int, long or intptr_t. + + Version 7, 2016-01-04 (Jon Leech) + - Free config memory allocated in sample code (Public Bug 1445). + + Version 6, 2014-02-12 (Chad Versace) + - Change resolution of issue #1 from "no" to "yes". Now + eglGetPlatformDisplayEXT accepts EGL_DEFAULT_DISPLAY for GBM. + + Version 5, 2013-010-15 (Chad Versace) + - Specify that EGL_NATIVE_VISUAL_ID is a GBM color format. + - Require for eglCreatePlatformWindowSurfaceEXT that the GBM color + format not differ between the EGLConfig and gbm_surface. (Suggested + by Kristian). + - Update example code to find matching EGL_NATIVE_VISUAL_ID. + + Version 4, 2013-09-13 (Chad Versace) + - Update the text and example code to wording of version 7 of + EGL_EXT_platform_base spec. + - Add section "Extension Type". + - Resolve issue #1 to "No". + - Add issue #2. + + Version 3, 2013-04-26 (Chad Versace) + - Add missing MESA suffix to new token. + + Version 2, 2013-04-23 (Chad Versace) + - Add issue #1 regarding EGL_DEFAULT_DISPLAY. + + Version 1, 2013.03.24 (Chad Versace) + - First draft diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/MESA/EGL_MESA_platform_surfaceless.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/MESA/EGL_MESA_platform_surfaceless.txt new file mode 100644 index 0000000..6ba562c --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/MESA/EGL_MESA_platform_surfaceless.txt @@ -0,0 +1,120 @@ +Name + + MESA_platform_surfaceless + +Name Strings + + EGL_MESA_platform_surfaceless + +Contributors + + Chad Versace <chadversary@google.com> + Haixia Shi <hshi@google.com> + Stéphane Marchesin <marcheu@google.com> + Zach Reizner <zachr@chromium.org> + Gurchetan Singh <gurchetansingh@google.com> + +Contacts + + Chad Versace <chadversary@google.com> + +Status + + DRAFT + +Version + + Version 2, 2016-10-13 + +Number + + EGL Extension #104 + +Extension Type + + EGL client extension + +Dependencies + + Requires EGL 1.5 or later; or EGL 1.4 with EGL_EXT_platform_base. + + This extension is written against the EGL 1.5 Specification (draft + 20140122). + + This extension interacts with EGL_EXT_platform_base as follows. If the + implementation supports EGL_EXT_platform_base, then text regarding + eglGetPlatformDisplay applies also to eglGetPlatformDisplayEXT; + eglCreatePlatformWindowSurface to eglCreatePlatformWindowSurfaceEXT; and + eglCreatePlatformPixmapSurface to eglCreatePlatformPixmapSurfaceEXT. + +Overview + + This extension defines a new EGL platform, the "surfaceless" platform. This + platfom's defining property is that it has no native surfaces, and hence + neither eglCreatePlatformWindowSurface nor eglCreatePlatformPixmapSurface + can be used. The platform is independent of any native window system. + + The platform's intended use case is for enabling OpenGL and OpenGL ES + applications on systems where no window system exists. However, the + platform's permitted usage is not restricted to this case. Since the + platform is independent of any native window system, it may also be used on + systems where a window system is present. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted as the <platform> argument of eglGetPlatformDisplay: + + EGL_PLATFORM_SURFACELESS_MESA 0x31DD + +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 on the surfaceless platform, call + eglGetPlatformDisplay with <platform> set to EGL_PLATFORM_SURFACELESS_MESA. + The <native_display> parameter must be EGL_DEFAULT_DISPLAY. + + eglCreatePlatformWindowSurface fails when called with a <display> that + belongs to the surfaceless platform. It returns EGL_NO_SURFACE and + generates EGL_BAD_NATIVE_WINDOW. The justification for this unconditional + failure is that the surfaceless platform has no native windows, and + therefore the <native_window> parameter is always invalid. + + Likewise, eglCreatePlatformPixmapSurface also fails when called with a + <display> that belongs to the surfaceless platform. It returns + EGL_NO_SURFACE and generates EGL_BAD_NATIVE_PIXMAP. + + The surfaceless platform imposes no platform-specific restrictions on the + creation of pbuffers, as eglCreatePbufferSurface has no native surface + parameter. Specifically, if the EGLDisplay advertises an EGLConfig whose + EGL_SURFACE_TYPE attribute contains EGL_PBUFFER_BIT, then the EGLDisplay + permits the creation of pbuffers with that config. + +Issues + + None. + +Revision History + + Version 2, 2016-10-13 (Chad Versace) + - Assign enum values + - Define interfactions with EGL 1.4 and EGL_EXT_platform_base. + - Add Gurchetan as contributor, as he implemented the pbuffer support. + + Version 1, 2016-09-23 (Chad Versace) + - Initial version + - Posted for review at + https://lists.freedesktop.org/archives/mesa-dev/2016-September/129549.html diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/MESA/EGL_MESA_query_driver.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/MESA/EGL_MESA_query_driver.txt new file mode 100644 index 0000000..bf260bd --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/MESA/EGL_MESA_query_driver.txt @@ -0,0 +1,95 @@ +Name + + MESA_query_driver + +Name Strings + + EGL_MESA_query_driver + +Contact + + Rob Clark <robdclark 'at' gmail.com> + Nicolai Hähnle <Nicolai.Haehnle 'at' amd.com> + +Contibutors + + Veluri Mithun <velurimithun38 'at' gmail.com> + +Status + + Complete + +Version + + Version 3, 2019-01-24 + +Number + + EGL Extension 131 + +Dependencies + + EGL 1.0 is required. + +Overview + + When an application has to query the name of a driver and for + obtaining driver's option list (UTF-8 encoded XML) of a driver + the below functions are useful. + + XML file formally describes all available options and also + includes verbal descriptions in multiple languages. Its main purpose + is to be automatically processed by configuration GUIs. + The XML shall respect the following DTD: + + <!ELEMENT driinfo (section*)> + <!ELEMENT section (description+, option+)> + <!ELEMENT description (enum*)> + <!ATTLIST description lang CDATA #REQUIRED + text CDATA #REQUIRED> + <!ELEMENT option (description+)> + <!ATTLIST option name CDATA #REQUIRED + type (bool|enum|int|float) #REQUIRED + default CDATA #REQUIRED + valid CDATA #IMPLIED> + <!ELEMENT enum EMPTY> + <!ATTLIST enum value CDATA #REQUIRED + text CDATA #REQUIRED> + +New Procedures and Functions + + char* eglGetDisplayDriverConfig(EGLDisplay dpy); + const char* eglGetDisplayDriverName(EGLDisplay dpy); + +Description + + By passing EGLDisplay as parameter to `eglGetDisplayDriverName` one can retrieve + driverName. Similarly passing EGLDisplay to `eglGetDisplayDriverConfig` we can retrieve + driverConfig options of the driver in XML format. + + The string returned by `eglGetDisplayDriverConfig` is heap-allocated and caller + is responsible for freeing it. + + EGL_BAD_DISPLAY is generated if `disp` is not an EGL display connection. + + EGL_NOT_INITIALIZED is generated if `disp` has not been initialized. + + If the implementation does not have enough resources to allocate the XML then an + EGL_BAD_ALLOC error is generated. + +New Tokens + + No new tokens + +Issues + + None + + +Revision History + + Version 1, 2018-11-05 - First draft (Veluri Mithun) + Version 2, 2019-01-23 - Final version (Veluri Mithun) + Version 3, 2019-01-24 - Mark as complete, add Khronos extension + number, fix parameter name in prototypes, + write revision history (Eric Engestrom) diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/NOK/EGL_NOK_swap_region2.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NOK/EGL_NOK_swap_region2.txt new file mode 100644 index 0000000..b09f551 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NOK/EGL_NOK_swap_region2.txt @@ -0,0 +1,227 @@ +Name + + NOK_swap_region2 + +Name Strings + + EGL_NOK_swap_region2 + +Notice + + Copyright 2010 Nokia. All rights reserved. + +Contributors + + Robert Palmer + Sami Kyöstilä + +Contacts + + Robert Palmer, Nokia (robert.palmer 'at' nokia.com) + Sami Kyöstilä, Nokia (sami.kyostila 'at' nokia.com) + +Status + + Internally reviewed + +Version + + 2 - April 29, 2010 + +Number + + EGL Extension #23 + +Dependencies + + Requires EGL 1.4 + + This extension is written against the wording of the EGL 1.4 + Specification. + +Overview + + This extension adds a new function which provides an alternative to + eglSwapBuffers. eglSwapBuffersRegion2NOK accepts two new parameters + in addition to those in eglSwapBuffers. The new parameters consist + of a pointer to a list of 4-integer blocks defining rectangles + (x, y, width, height) and an integer specifying the number of + rectangles in the list. + + The new parameters allow users to declare the region of the surface + that has been updated. The implementation uses this information to transfer + the updated region to the front buffer. Only the pixels within the + specified region are copied; any rendering outside that region will not + become visible on the window surface. This in contrast with the + EGL_NOK_swap_region extension which treats the modified region only as a + hint. + + This functional change is aimed at further reducing the processing and + bandwidth requirements of optimizations of applications whose graphics are + commonly subjected to region-based changes. Specifically, this extension + enables partial surface updates without requiring the use of preserved + swaps. + +New Procedures and Functions + + EGLAPI EGLBoolean EGLAPIENTRY eglSwapBuffersRegion2NOK( + EGLDisplay dpy, + EGLSurface surface, + EGLint numRects, + const EGLint* rects); + +New Types + + None + +New Tokens + + None + +Additions to Chapter 3 of the EGL 1.4 Specification (EGL Functions +and Errors) + + Add the following text to the end of the first subsection in + section 3.9.1 (prior to 'Native Window Resizing' subsection): + + "eglSwapBuffersRegion2NOK is an alternative to eglSwapBuffers + that allows the client to provide the region of the surface + which has been updated. This will allow processing and + bandwidth optimizations for applications whose graphics are + commonly subject to region-based changes. + + eglSwapBuffersRegion2NOK behaves in the same way as + eglSwapBuffers with the following modification: the additional + parameters <numRects> and <rects> provide specify a region which was + rendered to by the application. The implementation uses this + information to combine the modified backbuffer region with the previous + frontbuffer to form the new frontbuffer. The implementation guarantees + that all of the pixels within the modified region are posted for + display and none of the pixels outside the region are sourced. Only + back buffered surfaces can be used with eglSwapBuffersRegion2NOK. + + <rects> specifies a pointer to a list of 4-integer blocks + defining rectangles. The area covered by the rectangles + constitutes the region of the color buffer which has been + updated by the client. <numRects> specifies the number of + rectangles in the <rects> list. If <numRects> is set to zero + the update region is set to the width and height of the + surface. + + Each rectangle is specified as an integer 4-tuple in the form + (x, y, width, height). The x and y values provided by the client + must specify the bottom left corner of each rectangle as the + origin of the coordinate system is bottom left. Rectangles are + clipped (restricted) to the bounds of the EGLSurface. A + rectangle with width or height less than or equal 0 is ignored. + The region is defined by the union of all the specified + rectangles. The rectangles as specified must be disjoint. If + the rectangles are not disjoint or the user has rendered + outside of the region declared, the rendering results are + undefined." + + Insert "eglSwapBuffersRegion2NOK" appropriately after each instance + of "eglSwapBuffers" in the first paragraph in section 3.9.4 + + Add the following before the last sentence in the first + paragraph in section 3.9.4 + + "If eglSwapBuffersRegion2NOK is called and <numRects> is greater + than zero and <rects> is NULL, an EGL_BAD_PARAMETER error is + generated. If <numRects> is less than zero, an + EGL_BAD_PARAMETER error is generated." + + "If eglSwapBuffersRegion2NOK is called with a single buffered + <surface>, an EGL_BAD_MATCH error is generated." + +Dependencies on OpenGL ES + + None + +Dependencies on OpenVG + + None + + +Issues + + 1) Is there a limit on the number of rectangles that can be used? + Should there be a specified number which are guaranteed to be + supported? + + RESOLVED: This is limited by the amount of resources available to the + implementation. The implementation is free to fail with EGL_BAD_ALLOC if a + given update region cannot be processed due to resource constraints. + + 2) Are there any limitations on the location or size of rectangles? + + RESOLVED: The limitations placed on the validity of a rectangle is + that the width and height must be greater than zero and should not + overlap. Rectangles which have a width or height less than or equal + to zero will be ignored. If rectangles overlap the rendering + results are undefined. In addition all rectangles are clipped to + the area of the surface. Rectangles which are partially or + completely outside the boundary of the surface will not generate an + error. + + 3) How does eglSwapBuffersRegion2NOK interact with incremental + rendering? + + RESOLVED: This extension does not affect the client's ability to + perform incremental rendering. The ability to perform incremental + rendering is determined solely by the EGLSurface's + EGL_SWAP_BEHAVIOR attribute. The use of eglSwapBuffersRegion2NOK to + describe changed regions can still assist window system composition + optimizations even if the client is physically redrawing the entire + surface on every frame. + + If EGL_SWAP_BEHAVIOR is EGL_BUFFER_PRESERVED, the client can + restrict their rendering to a particular region (e.g. using scissor + rects) and then declare this region using eglSwapBuffersRegion2NOK. + + If EGL_SWAP_BEHAVIOR is EGL_BUFFER_DESTROYED, the client can + also restrict rendering to a particular region of the surface, but that + region must be completely re-rendered because the previous frame contents + are no longer available within that region. The application can then post + this region with eglSwapBuffersRegion2NOK. Since the buffer posting is + guaranteed to be limited to the declared region, the application does not + need to re-render or otherwise ensure pixel data outside the updated region + is valid. + + 4) How is this extension an improvement over EGL_NOK_swap_region? + + RESOLVED: This extension builds on the previous EGL_NOK_swap_region + extension by requiring that the implementation considers the update region + provided by the application as a mandate rather than a hint. This allows + for region-restricted rendering without requiring the use of preserved buffer + swaps which may be relatively expensive for the implementation. + + Furthermore, whilst preserved swap behaviour is necessary for incremental + rendering, many applications fully re-render modified surface regions and + so don't require preserved swap behaviour. This extension provides a + lighter weight surface update mechanism for such applications. + + 5) How does this extension compare to MESA_copy_sub_buffer? + + RESOLVED: There are two main differences between MESA_copy_sub_buffer and + this extension: + + 1. This extension allows for arbitrary update regions instead of a + single rectangle. + + 2. eglSwapBuffersRegion2NOK is specified to be a frame swap, so the + implementation is free to apply destructive swap behavior in + conjunction with this function call. This may allow for a + performance improvement. + +Revision History + + Version 1, 2010/04/28 (Sami Kyöstilä) + - First revision based on EGL_NOK_swap_region version 10. + Version 2, 2010/04/29 (Sami Kyöstilä) + - Specify operation in terms of copying from the back buffer into the + front buffer instead of involving the the system composition or the + display. + - Disallowed usage with anything else than back buffered surfaces. + - Clarified some sentences. +
\ No newline at end of file diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/NOK/EGL_NOK_texture_from_pixmap.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NOK/EGL_NOK_texture_from_pixmap.txt new file mode 100644 index 0000000..ebc4ee0 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NOK/EGL_NOK_texture_from_pixmap.txt @@ -0,0 +1,321 @@ +Name + + NOK_texture_from_pixmap + +Name Strings + + EGL_NOK_texture_from_pixmap + +Notice + + Copyright Nokia, 2009. + +Contributors + + +Contact + + Roland Scheidegger, Tungsten Graphics, sroland@tungstengraphics.com + +Status + + Shipping on N900 + +Version + + 0.2 (13 Nov 2009) + +Number + + EGL Extension #14 + +Dependencies + + EGL 1.1 is required. + Written against wording of EGL 1.4 specification. + OpenGL ES 2.0 is required. + GL_OES_texture_npot affects the definition of this extension. + +Overview + + This extension allows a color buffer to be used for both rendering and + texturing. + + EGL allows the use of color buffers of pbuffer drawables for texturing, + this extension extends this to allow the use of color buffers of pixmaps + too. + Other types of drawables could be supported by future extensions layered + on top of this extension, though only windows are really left which + are problematic. + + The functionality of this extension is similar to WGL_ARB_render_texture + which was incorporated into EGL 1.1. + However, the purpose of this extension is not to provide + "render to texture" like functionality but rather the ability to bind + existing native drawables (for instance X pixmaps) to a texture. Though, + there is nothing that prohibits it from being used for "render to + texture". + + - Windows are problematic as they can change size and therefore are not + supported by this extension. + + - Only a color buffer of a EGL pixmap created using an EGLConfig with + attribute EGL_BIND_TO_TEXTURE_RGB or EGL_BIND_TO_TEXTURE_RGBA + set to TRUE can be bound as a texture. + + - The texture internal format is determined when the color buffer + is associated with the texture, guaranteeing that the color + buffer format is equivalent to the texture internal format. + + - A client can create a complete set of mipmap images. + + +IP Status + + There are no known IP issues. + +Issues + + 1. What should this extension be called? + + EGL_EXT_texture_from_pixmap seemed most appropriate, but eventually + was changed to EGL_NOK_texture_from_pixmap since it's unknown if other + vendors are interested in implementing this. Even though it builds + on top of the EGL render_to_texture functionality and thus the + specifiation wording is quite different to the GLX version, keep the + name from the GLX version (except the vendor prefix) since the intention + is the same. Layering of future extensions on top of this extension for + using other type of drawables as textures follows the same conventions + as vertex/pixel buffer objects and vertex/fragment programs. + + + 2. What should the default value for EGL_TEXTURE_TARGET be? Should + users be required to set this value if EGL_TEXTURE_FORMAT is not + EGL_TEXTURE_FORMAT_NONE ? + + Unlike in OpenGL, in OES there is no difference between pot and npot + sized textures as far as the texture target is concerned, so + for all sizes EGL_TEXTURE_2D will be used for all pixmap sizes. + npot texture sizes (with reduced functionality) are only available + in OES 2.0 hence this version is required. While in theory it would be + possible to support this in OES 1.0 if pixmaps are restricted to power + of two sizes, it seems for all practical uses of this extension pixmap + sizes will be arbitrary. + + + 3. Should users be required to re-bind the drawable to a texture after + the drawable has been rendered to? + + It is difficult to define what the contents of the texture would be if + we don't require this. Also, requiring this would allow implementations + to perform an implicit copy at this point if they could not support + texturing directly out of renderable memory. + + The problem with defining the contents of the texture after rendering + has occured to the associated drawable is that there is no way to + synchronize the use of the buffer as a source and as a destination. + Direct OpenGL rendering is not necessarily done in the same command + stream as X rendering. At the time the pixmap is used as the source + for a texturing operation, it could be in a state halfway through a + copyarea operation in which half of it is say, white, and half is the + result of the copyarea operation. How is this defined? Worse, some + other OpenGL application could be halfway through a frame of rendering + when the composite manager sources from it. The buffer might just + contain the results of a "glClear" operation at that point. + + To gurantee tear-free rendering, a composite manager (in this case + using X) would run as follows: + + -receive request for compositing: + XGrabServer() + eglWaitNative() or XSync() + eglBindTexImage() + + <Do rendering/compositing> + + eglReleaseTexImage() + XUngrabServer() + + Apps that don't synchronize like this would get what's available, + and that may or may not be what they expect. + + + 4. Rendering done by the window system may be y-inverted compared + to the standard OpenGL texture representation. More specifically: + the X Window system uses a coordinate system where the origin is in + the upper left; however, the GL uses a coordinate system where the + origin is in the lower left. Should we define the contents of the + texture as the y-inverted contents of the drawable? + + X implementations may represent their drawables differently internally, + so y-inversion should be exposed as an EGLConfig attribute. + Applications will need to query this attribute and adjust their rendering + appropriately. + + If a drawable is y-inverted and is bound to a texture, the contents of the + texture will be y-inverted with respect to the standard GL memory layout. + This means the contents of a pixmap of size (width, height) at pixmap + coordinate (x, y) will be at location (x, height-y-1) in the texture. + Applications will need to adjust their texture coordinates accordingly to + avoid drawing the texture contents upside down. + + + + +New Procedures and Functions + + None + +New Tokens + + Accepted by the <Attribute> parameter of eglGetConfigAttrib and + the <attrib_list> parameter of eglChooseConfig: + + EGL_Y_INVERTED_NOK 0x307F + + +Additions to the OpenGL ES 2.0 Specification + + None. + + +Additions to the EGL Specification + + Add to table 3.1, EGLConfig Attributes: + + Attribute Type Notes + ------------------------------- ------- ----------------------------------- + EGL_Y_INVERTED_NOK boolean True if the drawable's framebuffer + is y-inverted. This can be used to + determine if y-inverted texture + coordinates need to be used when + texturing from this drawable when + it is bound to a texture target. + + Additions to table 3.4, Default values and match criteria for EGLConfig attributes: + + Attribute Default Selection Criteria Priority + ------------------------------- -------------------- ------------------ --------- + EGL_Y_INVERTED_NOK EGL_DONT_CARE Exact + + Modifications to 3.4, "Configuration Management" + + Modify 3rd last paragraph ("EGL BIND TO TEXTURE RGB and..."): + + EGL BIND TO TEXTURE RGB and EGL BIND TO TEXTURE RGBA are booleans + indicating whether the color buffers of a pbuffer or a pixmap created with + the EGLConfig can be bound to a OpenGL ES RGB or RGBA texture respectively. + Currently only pbuffers or pixmaps can be bound as textures, so these + attributes may only be EGL TRUE if the value of the EGL SURFACE TYPE + attribute includes EGL PBUFFER BIT or EGL_PIXMAP_BIT. It is possible to + bind a RGBA visual to a RGB texture, in which case the values in the alpha + component of the visual are ignored when the color buffer is used as a RGB + texture. + + Add after this: + + EGL_Y_INVERTED_NOK is a boolean describing the memory layout used for + drawables created with the EGLConfig. The attribute is True if the + drawable's framebuffer will be y-inverted. This can be used to determine + if y-inverted texture coordinates need to be used when texturing from this + drawable when it is bound to a texture target. + + Modifications to 3.5.4, "Creating Native Pixmap Rendering Surfaces" + + Modify paragraph 4 of the description of eglCreatePixmapSurface: + + <attrib_list> specifies a list of attributes for the pixmap. The list has + the same structure as described for eglChooseConfig. Attributes that can + be specified in <attrib_list> include EGL_TEXTURE_FORMAT, + EGL_TEXTURE_TARGET, EGL_MIPMAP_TEXTURE, EGL_VG_COLORSPACE and + EGL_VG_ALPHA_FORMAT. + EGL_TEXTURE_FORMAT, EGL_TEXTURE_TARGET and EGL_MIPMAP_TEXTURE have the same + meaning and default values as when used with eglCreatePbufferSurface. + + + Modifications to section 3.6.1, "Binding a Surface to a OpenGL ES Texture" + + Modify paragraph 2 of the description of eglBindTexImage: + + The texture target, the texture format and the size of the texture + components are derived from attributes of the specified <surface>, which + must be a pbuffer or pixmap supporting one of the EGL_BIND_TO_TEXTURE_RGB + or EGL_BIND_TO_TEXTURE_RGBA attributes. + + Modify paragraph 6 of the description of eglBindTexImage: + + ...as though glFinish were called on the last context to which that surface + were bound. If <surface> is a pixmap, it also waits for all effects of + native drawing to complete. + + Modify paragraph 7 of the description of eglBindTexImage: + + After eglBindTexImage is called, the specified <surface> is no longer + available for reading or writing by client APIs. Any read operation, + such as glReadPixels or eglCopyBuffers, which reads values from any of the + surface’s color buffers or ancillary buffers will produce indeterminate + results. In addition, draw operations that are done to the surface before + its color buffer is released from the texture produce indeterminate + results. Specifically, if the surface is current to a context + and thread then rendering commands will be processed and the context state + will be updated, but the surface may or may not be written. + If the surface is a pixmap, it can still be accessed for reading or + writing by native rendering calls, however reading and writing will produce + indeterminate results and will leave the texture in an undefined state. It + is up to the application to implement any synchronization required. + eglSwapBuffers has no effect if it is called on a bound surface. + + Modify paragraph 10 of the description of eglBindTexImage: + + Texture mipmap levels are automatically generated when all of the following + conditions are met while calling eglBindTexImage: + + - The EGL_MIPMAP_TEXTURE attribute of the pbuffer or pixmap being bound + is EGL_TRUE. + - The OpenGL ES texture parameter GL_GENERATE_MIPMAP is GL_TRUE for the + currently bound texture. + - The value of the EGL_MIPMAP_LEVEL attribute of the pbuffer or pixmap + being bound is equal to the value of the texture parameter + GL_TEXTURE_BASE_LEVEL. + + + Modifications to section 3.6.2, "Releasing a Surface from an OpenGL ES Texture" + + Modify paragraph 1 of the description of eglReleaseTexImage: + + ...The specified color buffer is released back to the surface. The surface + is made avalaible for reading and writing by client APIs when it no longer + has any color buffers bound as textures. + + Modify paragraph 2 of the description of eglReleaseTexImage: + + If the surface is a pixmap, the contents of the color buffer are + unaffected by eglReleaseTexImage. If the surface is a pbuffer, + the contents of the color buffer are undefined when it is first + released, in particular there is no guarantee that the texture + image is still present. In all cases, the contents of other + color buffers are unaffected by this call. ... + + Modify paragraph 5 of the description of eglReleaseTexImage: + + ...If <surface> is not a valid EGLSurface, or is not a bound pbuffer or + pixmap surface, then an EGL_BAD_SURFACE error is returned. + + + +Usage Examples + +(skipped for now) + + + +Version History + + 0. 12 Aug 2008 - RS + Initial version derived from GLX_EXT_texture_from_pixmap and EGL. + 0.1 30 Sept 2008 - RS + Changed name from EXT to NOKIA. + Clarified / fixed wording wrt differences to pbuffers. + 0.2 13 Nov 2009 - Sami Kyöstilä <sami.kyostila@nokia.com> + Changed extension and token names to comply with Nokia extension naming + scheme. Clarified interaction with native rendering. Formatting. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_3dvision_surface.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_3dvision_surface.txt new file mode 100644 index 0000000..c190687 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_3dvision_surface.txt @@ -0,0 +1,94 @@ +Name + + EGL_NV_3dvision_surface + +Name Strings + + EGL_NV_3dvision_surface + +Contact + + Greg Roth, NVIDIA (groth 'at' nvidia.com) + +Contributors + + Swaminathan Narayanan, NVIDIA + +IP Status + + NVIDIA Proprietary. + +Status + + Complete + +Version + + Last Modified Date: 02 December 2011 + Revision: 1 + +Number + + EGL Extension #46 + +Dependencies + + Requires EGL 1.4 + + Written against the EGL 1.4 specification. + +Overview + + NVIDIA 3D Vision provides stereoscopic 3d rendering without + requiring applications to change their rendering methods. However + there are cases where applications can benefit from adjusting 3D + vision parameters directly to experiment with this functionality in + applications not yet known to 3D Vision, to assist 3D Vision in + setting parameters correctly for unusual situations, or to present + application-specific user-accessible controls for 3D Vision + parameters. + + This extension provides the ability to explicitly create a surface + with 3D Vision support regardless of application detection. + +IP Status + + NVIDIA Proprietary + +New Procedures and Functions + + None + +New Tokens + + Accepted as an attribute to the <attrib_list> parameter of + CreateWindowSurface and CreatePbufferSurface + + EGL_AUTO_STEREO_NV 0x3136 + +Additions to Chapter 3 of the EGL 1.4 Specification (EGL Functions and +Errors) + + Additions to section 3.5.1 (Creating On-Screen Rendering Surfaces) + + Alter the end of the second to last paragraph: + + Attributes that can be specified in <attrib_list> include + EGL_RENDER_BUFFER, EGL_VG_COLORSPACE, EGL_VG_ALPHA_FORMAT, + and EGL_AUTO_STEREO_NV. + + Add before the last paragraph of section 3.5.1: + + EGL_AUTO_STEREO_NV specifies whether 3D Vision stereo + (stereo override) should be enabled in the driver. The default + value of EGL_AUTO_STEREO_NV is zero. + +Issues + + None + +Revision History + + Rev. Date Author Changes + ---- ------------- --------- ---------------------------------------- + 1 02 Dec 2011 groth Split 3D Vision capability from previous extension. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_context_priority_realtime.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_context_priority_realtime.txt new file mode 100644 index 0000000..5435c8c --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_context_priority_realtime.txt @@ -0,0 +1,195 @@ +Name + + NV_context_priority_realtime + +Name Strings + + EGL_NV_context_priority_realtime + +Contributors + + Sandeep Shinde + Kirill Artamonov + Sami Kiminki + Donghan Ryu + Daniel Koch + Mark Kilgard + +Contacts + + Sandeep Shinde, NVIDIA (sashinde 'at' nvidia 'dot' com) + +Status + + Complete + +Version + + Version 4 - November 21, 2017 + +Number + + EGL Extension #124 + +Dependencies + + Requires EGL 1.0. + + Requires EGL_IMG_context_priority + + This extension is written against the wording of the EGL 1.5 + Specification - August 27, 2014 (but may be implemented against earlier + versions). + +Overview + + This extension allows an EGLContext to be created with one extra + priority level in addition to three priority levels that are part of + EGL_IMG_context_priority extension. + + This new level has extra privileges that are not available to other three + levels. Some of the privileges may include: + - Allow realtime priority to only few contexts + - Allow realtime priority only to trusted applications + - Make sure realtime priority contexts are executed immediately + - Preempt any current context running on GPU on submission of + commands for realtime context + + The mechanism for determining which EGL context is allowed to use this + priority level is platform dependent. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + New attribute value accepted for the EGL_CONTEXT_PRIORITY_LEVEL_IMG + attribute in the <attrib_list> argument of eglCreateContext: + + EGL_CONTEXT_PRIORITY_REALTIME_NV 0x3357 + +Additions to Chapter 3 of the EGL 1.5 Specification (EGL Functions and Errors) + + Add a NEW section "3.7.1.7 Context Priority" to specify the context + priority attribute for EGL_IMG_context_priority and values: + + "3.7.1.7 Context Priority + + The attribute EGL_CONTEXT_PRIORITY_LEVEL_IMG specifies a context + priority hint for a context supporting context priority. This + attribute's value may be one of EGL_CONTEXT_PRIORITY_HIGH_IMG, + EGL_CONTEXT_PRIORITY_MEDIUM_IMG, EGL_CONTEXT_PRIORITY_LOW_IMG, + or EGL_CONTEXT_PRIORITY_REALTIME_NV. The default value for + EGL_CONTEXT_PRIORITY_LEVEL_IMG is EGL_CONTEXT_PRIORITY_MEDIUM_IMG. + + This attribute is a hint, as an implementation may not support + multiple contexts at some priority levels and system policy may limit + access to high priority contexts to appropriate system privilege + level. + + The value EGL_CONTEXT_PRIORITY_REALTIME_NV requests the created + context run at the highest possible priority and be capable of + preempting the current executing context when commands are flushed + by such a realtime context. + + This attribute is supported only for OpenGL and OpenGL ES contexts." + + Within section 3.7.4 "Context Queries" amend the eglQueryContext + discussion as follows: + + Change the sentence describing the attribute parameter to include + EGL_CONTEXT_PRIORITY_LEVEL_IMG so it reads: + + "attribute must be set to EGL_CONFIG_ID, EGL_CONTEXT_CLIENT_TYPE, + EGL_CONTEXT_CLIENT_VERSION, EGL_RENDER_BUFFER, or + EGL_CONTEXT_PRIORITY_LEVEL_IMG." + + After the discussion of "Querying EGL_RENDER_BUFFER", add: + + "Querying EGL_CONTEXT_PRIORITY_LEVEL_IMG returns the priority this + context was actually created with. Note: this may not be the same + as specified at context creation time, due to implementation limits + on the number of contexts that can be created at a specific priority + level in the system." + +Issues + + 1) The EGL_IMG_context_priority extension is written to amend the EGL + 1.4 specification. Should this extension amend EGL 1.5 or 1.4? + + RESOLVED: EGL 1.5 because it is newer and better organized to + extend context attributes. + + EGL 1.5 rewrites 3.7.1 "Creating Rendering Contexts" to have subsections + for different context attributes. This extension adds a new such section + that includes the EGL_IMG_context_priority attribute and values too. + + 2) Is context priority hint supported for both OpenGL and OpenGL ES contexts? + + RESOLVED: Yes. + + 3) What is the intended application of the realtime priority level? + + RESOLVED: One anticipated application is the system compositor + for a Head Mounted Display (HMD) requires realtime recomposition + for time-warping. + + 4) What action causes a context with realtime priority to preempt + other contexts? + + RESOLVED: Preemption by a context with realtime priority should + occur when there are pending rendering commands and an implicit or + explicit flush (i.e. glFlush or glFinish) occurs. + + 5) What does "trusted" or "appropriate system privilege level" + mean in practice for a Linux-based operating system such as Android? + + RESOLVED: Trusted means an application that has higher privileges + than other apps such as having CAP_SYS_NICE capability. On Android + such applications have to be registered in advance with the OS; + unpriviledged third party app cannot acquire this capability. + + This restriction exists so arbitrary applications do not starve or + otherwise compromise the interactivity of the system overall. + + 6) In practice how many realtime priority contexts can exist in a system to + get best performance? + + RESOLVED: Only one realtime priority context should be active at a given + moment to get best performance. + + 7) Can a context created with a realtime priority hint that is + in fact given a realtime priority, subsequently find that realtime + priority revoked and, if revoked, can it be restored? + + RESOLVED: No, once a context is created with specific priority level, the + priority will not change for lifetime of the context. This means there will + not be revoking or restoring of realtime priority to already created context. + + 8) The attrib_list for eglCreateContext could list the attribute + EGL_CONTEXT_PRIORITY_LEVEL_IMG multiple times with different valid values. + What happens in this case? + + RESOLVED: Behavior is undefined in this case. + + NVIDIA's EGL implementation handles such case by using the last (valid) attribute + value listed in the attrib_list array as the effective attribute value for + creating the context. + + The EGL specification is unfortunately silent on this issue. + + +Revision History + Version 1, 2016/11/23 (Sandeep Shinde) + - Initial version + Version 2, 2017/10/13 (Mark Kilgard) + - Complete and convert to NV extension + Version 3, 2017/10/31 (Sandeep Shinde) + - Few minor corrections. Issue 6 resolved. + Version 4, 2017/11/21 (Sandeep Shinde) + - Update enum value and add extension number diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_coverage_sample.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_coverage_sample.txt new file mode 100644 index 0000000..e016a6f --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_coverage_sample.txt @@ -0,0 +1,554 @@ +Name + + NV_coverage_sample + +Name Strings + + GL_NV_coverage_sample + EGL_NV_coverage_sample + +Contact + + Gary King, NVIDIA Corporation (gking 'at' nvidia.com) + +Notice + + Copyright NVIDIA Corporation, 2005 - 2007 + +Status + + NVIDIA Proprietary + +Version + + Last Modified Date: 2007/03/20 + NVIDIA Revision: 1.0 + +Number + + EGL Extension #17 + OpenGL ES Extension #72 + +Dependencies + + Written based on the wording of the OpenGL 2.0 specification + and the EXT_framebuffer_object specification. + + Written based on the wording of the EGL 1.2 specification. + + Requires OpenGL-ES 2.0 and OES_framebuffer_object. + + Requires EGL 1.1. + +Overview + + Anti-aliasing is a critical component for delivering high-quality + OpenGL rendering. Traditionally, OpenGL implementations have + implemented two anti-aliasing algorithms: edge anti-aliasing + and multisampling. + + Edge anti-aliasing computes fractional fragment coverage for all + primitives in a rendered frame, and blends edges of abutting + and/or overlapping primitives to produce smooth results. The + image quality produced by this approach is exceptionally high; + however, applications are render their geometry perfectly ordered + back-to-front in order to avoid artifacts such as bleed-through. + Given the algorithmic complexity and performance cost of performing + exact geometric sorts, edge anti-aliasing has been used very + sparingly, and almost never in interactive games. + + Multisampling, on the other hand, computes and stores subpixel + (a.k.a. "sample") coverage for rasterized fragments, and replicates + all post-alpha test operations (e.g., depth test, stencil test, + alpha blend) for each sample. After the entire scene is rendered, + the samples are filtered to compute the final anti-aliased image. + Because the post-alpha test operations are replicated for each sample, + all of the bleed-through and ordering artifacts that could occur with + edge anti-aliasing are avoided completely; however, since each sample + must be computed and stored separately, anti-aliasing quality is + limited by framebuffer storage and rendering performance. + + This extension introduces a new anti-aliasing algorithm to OpenGL, + which dramatically improves multisampling quality without + adversely affecting multisampling's robustness or significantly + increasing the storage required, coverage sampling. + + Coverage sampling adds an additional high-precision geometric + coverage buffer to the framebuffer, which is used to produce + high-quality filtered results (with or without the presence of a + multisample buffer). This coverage information is computed and stored + during rasterization; since applications may render objects where the + specified geometry does not correspond to the visual result (examples + include alpha-testing for "imposters," or extruded volume rendering + for stencil shadow volumes), coverage buffer updates may be masked + by the application, analagous to masking the depth buffer. + +IP Status + + NVIDIA Proprietary + +New Procedures and Functions + + void CoverageMaskNV( boolean mask ) + void CoverageOperationNV( enum operation ) + +New Tokens + + + Accepted by the <attrib_list> parameter of eglChooseConfig + and eglCreatePbufferSurface, and by the <attribute> + parameter of eglGetConfigAttrib + + EGL_COVERAGE_BUFFERS_NV 0x30E0 + EGL_COVERAGE_SAMPLES_NV 0x30E1 + + Accepted by the <internalformat> parameter of + RenderbufferStorageEXT and the <format> parameter of ReadPixels + + COVERAGE_COMPONENT_NV 0x8ED0 + + Accepted by the <internalformat> parameter of + RenderbufferStorageEXT + + COVERAGE_COMPONENT4_NV 0x8ED1 + + Accepted by the <operation> parameter of CoverageOperationNV + + COVERAGE_ALL_FRAGMENTS_NV 0x8ED5 + COVERAGE_EDGE_FRAGMENTS_NV 0x8ED6 + COVERAGE_AUTOMATIC_NV 0x8ED7 + + Accepted by the <attachment> parameter of + FramebufferRenderbuffer, and GetFramebufferAttachmentParameteriv + + COVERAGE_ATTACHMENT_NV 0x8ED2 + + Accepted by the <buf> parameter of Clear + + COVERAGE_BUFFER_BIT_NV 0x8000 + + Accepted by the <pname> parameter of GetIntegerv + + COVERAGE_BUFFERS_NV 0x8ED3 + COVERAGE_SAMPLES_NV 0x8ED4 + +Changes to Chapter 4 of the OpenGL 2.0 Specification + + Insert a new section, after Section 3.2.1 (Multisampling) + + "3.2.2 Coverage Sampling + + Coverage sampling is a mechanism to antialias all GL primitives: points, + lines, polygons, bitmaps and images. The technique is similar to + multisampling, with all primitives being sampled multiple times at each + pixel, and a sample resolve applied to compute the color values stored + in the framebuffer's color buffers. As with multisampling, coverage + sampling resolves color sample and coverage values to a single, displayable + color each time a pixel is updated, so antialiasing appears to be automatic + at the application level. Coverage sampling may be used simultaneously + with multisampling; however, this is not required. + + An additional buffer, called the coverage buffer, is added to + the framebuffer. This buffer stores additional coverage information + that may be used to produce higher-quality antialiasing than what is + provided by conventional multisampling. + + When the framebuffer includes a multisample buffer (3.5.6), the + samples contain this coverage information, and the framebuffer + does not include the coverage buffer. + + If the value of COVERAGE_BUFFERS_NV is one, the rasterization of + all primitives is changed, and is referred to as coverage sample + rasterization. Otherwise, primitive rasterization is referred to + as multisample rasterization (if SAMPLE_BUFFERS is one) or + single-sample rasterization (otherwise). The value of + COVERAGE_BUFFERS_NV is queried by calling GetIntegerv with <pname> + set to COVERAGE_BUFFERS_NV. + + During coverage sample rasterization the pixel fragment contents + are modified to include COVERAGE_SAMPLES_NV coverage values. The + value of COVERAGE_SAMPLES_NV is an implementation-dependent + constant, and is queried by calling GetIntegerv with <pname> set + to COVERAGE_SAMPLES_NV. + + The command + + CoverageOperationNV(enum operation) + + may be used to modify the manner in which coverage sampling is + performed for all primitives. If <operation> is + COVERAGE_ALL_FRAGMENTS_NV, coverage sampling will be performed and the + coverage buffer updated for all fragments generated during rasterization. + If <operation> is COVERAGE_EDGE_FRAGMENTS_NV, coverage sampling will + only be performed for fragments generated at the edge of the + primitive (by only updating fragments at the edges of primitives, + applications may get better visual results when rendering partially + transparent objects). If <operation> is COVERAGE_AUTOMATIC_NV, + the GL will automatically select the appropriate coverage operation, + dependent on the GL blend mode and the use of gl_LastFragColor / + gl_LastFragData in the bound fragment program. If blending is enabled, + or gl_LastFragColor / gl_LastFragData appears in the bound fragment + program, COVERAGE_AUTOMATIC_NV will behave identically to + COVERAGE_EDGE_FRAGMENTS_NV; otherwise, COVERAGE_AUTOMATIC_NV will behave + identically to COVERAGE_ALL_FRAGMENTS_NV. The default coverage operation + is COVERAGE_AUTOMATIC_NV." + + Insert a new section, after Section 3.3.3 (Point Multisample + Rasterization) + + "3.3.4 Point Coverage Sample Rasterization + + If the value of COVERAGE_BUFFERS_NV is one, then points are + rasterized using the following algorithm, regardless of whether + point antialiasing (POINT_SMOOTH) is enabled or disabled. Point + rasterization produces fragments using the same algorithm described + in section 3.3.3; however, sample points are divided into SAMPLES + multisample points and COVERAGE_SAMPLES_NV coverage sample points. + + Rasterization for multisample points uses the algorithm described + in section 3.3.3. Rasterization for coverage sample points uses + implementation-dependent algorithms, ultimately storing the results + in the coverage buffer." + + Insert a new section, after Section 3.4.4 (Line Multisample + Rasterization) + + "3.4.5 Line Coverage Sample Rasterization + + If the value of COVERAGE_BUFFERS_NV is one, then lines are + rasterized using the following algorithm, regardless of whether + line antialiasing (LINE_SMOOTH) is enabled or disabled. Line + rasterization produces fragments using the same algorithm described + in section 3.4.4; however, sample points are divided into SAMPLES + multisample points and COVERAGE_SAMPLES_NV coverage sample points. + + Rasterization for multisample points uses the algorithm described in + section 3.4.4. Rasterization for coverage sample points uses + implementation-dependent algorithms, ultimately storing results in + the coverage buffer." + + Insert a new section, after Section 3.5.6 (Polygon Multisample + Rasterization) + + "3.5.7 Polygon Coverage Sample Rasterization + + If the value of COVERAGE_BUFFERS_NV is one, then polygons are + rasterized using the following algorithm, regardless of whether + polygon antialiasing (POLYGON_SMOOTH) is enabled or disabled. Polygon + rasterization produces fragments using the same algorithm described in + section 3.5.6; however, sample points are divided into SAMPLES multisample + points and COVERAGE_SAMPLES_NV coverage sample points. + + Rasterization for multisample points uses the algorithm described in + section 3.5.7. Rasterization for coverage sample points uses + implementation-dependent algorithms, ultimately storing results in the + coverage buffer." + + Insert a new section, after Section 3.6.6 (Pixel Rectangle Multisample + Rasterization) + + "3.6.7 Pixel Rectangle Coverage Sample Rasterization + + If the value of COVERAGE_BUFFERS_NV is one, then pixel rectangles are + rasterized using the algorithm described in section 3.6.6." + + Modify the first sentence of the second-to-last paragraph of section + 3.7 (Bitmaps) to read: + + "Bitmap Multisample and Coverage Sample Rasterization + + If MULTISAMPLE is enabled, and the value of SAMPLE_BUFFERS is one; + or if the value of COVERAGE_BUFFERS_NV is one, then bitmaps are + rasterized using the following algorithm. [...]" + + Insert after the first paragraph of Section 4.2.2 (Fine Control of + Buffer Updates): + + "The coverage buffer can be enabled or disabled for writing coverage + sample values using + + void CoverageMaskNV( boolean mask ); + + If <mask> is non-zero, the coverage buffer is enabled for writing; + otherwise, it is disabled. In the initial state, the coverage + buffer is enabled for writing." + + And change the text of the last 2 paragraphs of Section 4.2.2 to read: + + "The state required for the various masking operations is three + integers and two bits: an integer for color indices, an integer for + the front and back stencil values, a bit for depth values, and a + bit for coverage sample values. A set of four bits is also required + indicating which components of an RGBA value should be written. In the + initial state, the integer masks are all ones, as are the bits + controlling the depth value, coverage sample value and RGBA component + writing. + + Fine Control of Multisample Buffer Updates + + When the value of SAMPLE_BUFFERS is one, ColorMask, DepthMask, + CoverageMask, and StencilMask or StencilMaskSeparate control the + modification of values in the multisample buffer. [...]" + + Change paragraph 2 of Section 4.2.3 (Clearing the Buffers) to read: + + "is the bitwise OR of a number of values indicating which buffers are to + be cleared. The values are COLOR_BUFFER_BIT, DEPTH_BUFFER_BIT, + STENCIL_BUFFER_BIT, ACCUM_BUFFER_BIT and COVERAGE_BUFFER_BIT_NV, indicating + the buffers currently enabled for color writing, the depth buffer, + the stencil buffer, the accumulation buffer and the virtual-coverage + buffer, respectively. [...]" + + Insert a new paragraph after paragraph 4 of Section 4.3.2 (Reading Pixels) + (beginning with "If there is a multisample buffer ..."): + + "If the <format> is COVERAGE_COMPONENT_NV, then values are taken from the + coverage buffer; again, if there is no coverage buffer, the error + INVALID_OPERATION occurs. When <format> is COVERAGE_COMPONENT_NV, + <type> must be GL_UNSIGNED_BYTE. Any other value for <type> will + generate the error INVALID_ENUM. If there is a multisample buffer, the + values are undefined." + + + +Modifications to the OES_framebuffer_object specification + + Add a new table at the end of Section 4.4.2.1 (Renderbuffer Objects) + + "+-------------------------+-----------------------+-----------+ + | Sized internal format | Base Internal Format | C Samples | + +-------------------------+-----------------------+-----------+ + | COVERAGE_COMPONENT4_NV | COVERAGE_COMPONENT_NV | 4 | + +-------------------------+-----------------------+-----------+ + Table 1.ooo Desired component resolution for each sized internal + format that can be used only with renderbuffers" + + Add to the bullet list in Section 4.4.4 (Framebuffer Completeness) + + "An internal format is 'coverage-renderable' if it is COVERAGE_COMPONENT_NV + or one of the COVERAGE_COMPONENT_NV formats from table 1.ooo. No other + formats are coverage-renderable" + + Add to the bullet list in Section 4.4.4.1 (Framebuffer Attachment + Completeness) + + "If <attachment> is COVERAGE_ATTACHMENT_NV, then <image> must have a + coverage-renderable internal format." + + Add a paragraph at the end of Section 4.4.4.2 (Framebuffer Completeness) + + "The values of COVERAGE_BUFFERS_NV and COVERAGE_SAMPLES_NV are derived from + the attachments of the currently bound framebuffer object. If the current + FRAMEBUFFER_BINDING_OES is not 'framebuffer-complete', then both + COVERAGE_BUFFERS_NV and COVERAGE_SAMPLES_NV are undefined. Otherwise, + COVERAGE_SAMPLES_NV is equal to the number of coverage samples for the + image attached to COVERAGE_ATTACHMENT_NV, or zero if COVERAGE_ATTACHMENT_NV + is zero." + +Additions to the EGL 1.2 Specification + + Add to Table 3.1 (EGLConfig attributes) + +---------------------------+---------+-----------------------------------+ + | Attribute | Type | Notes | + +---------------------------+---------+-----------------------------------+ + | EGL_COVERAGE_BUFFERS_NV | integer | number of coverage buffers | + | EGL_COVERAGE_SAMPLES_NV | integer | number of coverage samples per | + | | | pixel | + +---------------------------+---------+-----------------------------------+ + + Modify the first sentence of the last paragraph of the "Buffer + Descriptions and Attributes" subsection of Section 3.4 (Configuration + Management), p. 16 + + "There are no single-sample depth, stencil or coverage buffers for a + multisample EGLConfig; the only depth, stencil and coverage buffers are + those in the multisample buffer. [...]" + + And add the following text at the end of that paragraph: + + "The <coverage buffer> is used only by OpenGL ES. It contains primitive + coverage information that is used to produce a high-quality anti-aliased + image. The format of the coverage buffer is not specified, and its + contents are not directly accessible. Only the existence of the coverage + buffer, and the number of coverage samples it contains, are exposed by EGL. + + EGL_COVERAGE_BUFFERS_NV indicates the number of coverage buffers, which + must be zero or one. EGL_COVERAGE_SAMPLES_NV gives the number of coverage + samples per pixel; if EGL_COVERAGE_BUFFERS_NV is zero, then + EGL_COVERAGE_SAMPLES_NV will also be zero." + + Add to Table 3.4 (Default values and match criteria for EGLConfig + attributes) + + +---------------------------+-----------+-------------+---------+---------+ + | Attribute | Default | Selection | Sort | Sort | + | | | Criteria | Order | Priority| + +---------------------------+-----------+-------------+---------+---------+ + | EGL_COVERAGE_BUFFERS_NV | 0 | At Least | Smaller | 7 | + | EGL_COVERAGE_SAMPLES_NV | 0 | At Least | Smaller | 8 | + +---------------------------+-----------+-------------+---------+---------+ + And renumber existing sort priorities 7-11 as 9-13. + + Modify the list in "Sorting of EGLConfigs" (Section 3.4.1, pg 20) + + " [...] + 5. Smaller EGL_SAMPLE_BUFFERS + 6. Smaller EGL_SAMPLES + 7. Smaller EGL_COVERAGE_BUFFERS_NV + 8. Smaller EGL_COVERAGE_SAMPLES_NV + 9. Smaller EGL_DEPTH_SIZE + 10. Smaller EGL_STENCIL_SIZE + 11. Smaller EGL_ALPHA_MASK_SIZE + 12. Special: [...] + 13. Smaller EGL_CONFIG_ID [...]" + +Usage Examples + + (1) Basic Coverage Sample Rasterization + + glCoverageMaskNV(GL_TRUE); + glDepthMask(GL_TRUE); + glColorMask(GL_TRUE, GL_TRUE, GL_TRUE, GL_TRUE); + + while (1) + { + glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT | + GL_COVERAGE_BUFFER_BIT_NV); + glDrawElements(...); + eglSwapBuffers(...); + } + + (2) Multi-Pass Rendering Algorithms + + while (1) + { + glDepthMask(GL_TRUE); + glCoverageMaskNV(GL_TRUE); + glColorMask(GL_TRUE, GL_TRUE, GL_TRUE, GL_TRUE); + glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT | + GL_COVERAGE_BUFFER_BIT_NV); + + // first render pass: render Z-only (occlusion surface), with + // coverage info. color writes are disabled + + glCoverageMaskNV(GL_TRUE); + glDepthMask(GL_TRUE); + glColorMask(GL_FALSE, GL_FALSE, GL_FALSE, GL_FALSE); + glDepthFunc(GL_LESS); + glDrawElements(...); + + // second render pass: set Z test to Z-equals, disable Z-writes & + // coverage writes. enable color writes. coverage may be + // disabled, because subsequent rendering passes are rendering + // identical geometry -- since the final coverage buffer will be + // unchanged, we can disable coverage writes as an optimization. + + glCoverageMaskNV(GL_FALSE); + glDepthMask(GL_FALSE); + glDepthFunc(GL_EQUAL); + glColorMask(GL_TRUE, GL_TRUE, GL_TRUE, GL_TRUE); + glDrawElements(...); + + eglSwapBuffers(); + } + + (3) Rendering Translucent Objects on Top of Opaque Objects + + while (1) + { + glDepthMask(GL_TRUE); + glCoverageMaskNV(GL_TRUE); + glColorMask(GL_TRUE, GL_TRUE, GL_TRUE, GL_TRUE); + glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT | + GL_COVERAGE_BUFFER_BIT_NV); + + // render opaque, Z-buffered geometry with coverage info for the + // entire primitive. Overwrite coverage data for all fragments, so + // that interior fragments do not get resolved incorrectly. + + glDepthFunc(GL_LESS); + glCoverageOperationNV(GL_COVERAGE_ALL_FRAGMENTS_NV); + glDrawElements(...); + + // render translucent, Z-buffered geometry. to ensure that visible + // edges of opaque geometry remain anti-aliased, change the + // coverage operation to just edge fragments. this will maintain + // the coverage information underneath the translucent geometry, + // except at translucent edges. + + glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA); + glCoverageOperationNV(GL_COVERAGE_EDGE_FRAGMENTS_NV); + glEnable(GL_BLEND); + glDrawElements(...); + glDisable(GL_BLEND); + + eglSwapBuffers(); + } + + (4) Rendering Opacity-Mapped Particle Systems & HUDs on Top of Opaque + Geometry + + while (1) + { + glDepthMask(GL_TRUE); + glCoverageMaskNV(GL_TRUE); + glColorMask(GL_TRUE, GL_TRUE, GL_TRUE, GL_TRUE); + glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT | + GL_COVERAGE_BUFFER_BIT_NV); + + // render opaque, Z-buffered geometry, with coverage info. + glDepthFunc(GL_LESS); + glDrawElements(...); + + // render opacity-mapped geometry. disable Z writes, enable alpha + // blending. also, disable coverage writes -- the edges of the + // geometry used for the HUD/particle system have alpha values + // tapering to zero, so edge coverage is uninteresting, and + // interior coverage should still refer to the underlying opaque + // geometry, so that opaque edges visible through the translucent + // regions remain anti-aliased. + + glCoverageMaskNV(GL_FALSE); + glDepthMask(GL_FALSE); + glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA); + glEnable(GL_BLEND); + glDrawElements(...); + glDisable(GL_BLEND); + + eglSwapBuffers(); + } + + +Issues + + 1. Is any specific discussion of coverage sampling resolves required, + particularly with respect to application-provided framebuffer objects? + + RESOLVED: No. Because the coverage sampling resolve is an + implementation-dependent algorithm, it is always legal behavior for + framebuffer read / copy functions to return the value in the selected + ReadBuffer as if COVERAGE_BUFFERS_NV was zero. This allows + textures attached to the color attachment points of framebuffer objects + to behave predictably, even when COVERAGE_BUFFERS_NV is one. + + Implementations are encouraged, whenever possible, to use the highest- + quality coverage sample resolve supported for calls to eglSwapBuffers, + eglCopyBuffers, ReadPixels, CopyPixels and CopyTex{Sub}Image. + + 2. Should all render buffer & texture types be legal sources for image + resolves and coverage attachment? + + RESOLVED: This spec should not place any arbitrary limits on usage; + however, there are many reasons why implementers may not wish to + support coverage sampling for all surface types. + + Implementations may return FRAMEBUFFER_UNSUPPORTED_OES from + CheckFramebufferStatusOES if an object bound to COVERAGE_ATTACHMENT_NV + is incompatible with one or more objects bound to DEPTH_ATTACHMENT_OES, + STENCIL_ATTACHMENT_OES, or COLOR_ATTACHMENTi_OES. + +Revision History + +#1.0 - 20.03.2007 + + Renumbered enumerants. Reformatted to 80 columns. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_coverage_sample_resolve.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_coverage_sample_resolve.txt new file mode 100644 index 0000000..fa5cc15 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_coverage_sample_resolve.txt @@ -0,0 +1,127 @@ +Name + + NV_coverage_sample_resolve + +Name Strings + + EGL_NV_coverage_sample_resolve + +Contact + + James Jones, NVIDIA Corporation (jajones 'at' nvidia.com) + +Notice + + Copyright NVIDIA Corporation, 2011 + +Status + + NVIDIA Proprietary + +Version + + Last Modified Date: 2011/04/13 + NVIDIA Revision: 1.0 + +Number + + EGL Extension #30 + +Dependencies + + Written based on the wording of the EGL 1.4 specification. + + Trivially interacts with EGL_NV_coverage_sample + + Requires EGL 1.2. + +Overview + + NV_coverage_sample introduced a method to improve rendering quality + using a separate buffer to store coverage information for pixels in + the color buffers. It also provided a mechanism to disable writing + to the coverage buffer when coverage sample filtering was not needed + or undesirable. However, it did not provide a way to disable + reading data from the coverage buffer at resolve time. In some + cases performance can be improved by eliminating these memory reads. + To that end, this extension exposes a surface attribute that allows + applications to specify when no coverage sample resolve is desired. + +IP Status + + NVIDIA Proprietary + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted by the <attribute> parameter of eglSurfaceAttrib and + eglQuerySurface: + + EGL_COVERAGE_SAMPLE_RESOLVE_NV 0x3131 + + Accepted by the <value> parameter of eglSurfaceAttrib and returned + in the <value> parameter of eglQuerySurface when <attribute> is + EGL_COVERAGE_SAMPLE_RESOLVE_NV: + + EGL_COVERAGE_SAMPLE_RESOLVE_DEFAULT_NV 0x3132 + EGL_COVERAGE_SAMPLE_RESOLVE_NONE_NV 0x3133 + +Additions to Chapter 3 of the EGL 1.4 Specification (EGL Functions and +Errors) + + Additions to section 3.5.6 (Surface Attributes) + + Replace the last sentence of paragraph 2 (p. 35): + + "Attributes that can be specified are + EGL_COVERAGE_SAMPLE_RESOLVE_NV, EGL_MIPMAP_LEVEL, + EGL_MULTISAMPLE_RESOLVE, and EGL_SWAP_BEHAVIOR." + + Add the following paragraphs between paragraphs 2 and 3 (p. 35): + + "If <attribute> is EGL_COVERAGE_SAMPLE_RESOLVE_NV, then <value> + specifies the filter to use when resolving the coverage sample + buffer. A <value> of EGL_COVERAGE_SAMPLE_RESOLVE_DEFAULT_NV chooses + the default implementation-defined filtering method, while + EGL_MULTISAMPLE_RESOLVE_NONE_NV disables filtering based on coverage + data. + + "The initial value of EGL_COVERAGE_SAMPLE_RESOLVE_NV is + EGL_COVERAGE_SAMPLE_RESOLVE_DEFAULT_NV." + + Add the following paragraph after paragraph 13 (p. 36): + + "Querying EGL_COVERAGE_SAMPLE_RESOLVE_NV returns the filtering + method used when performing coverage buffer resolution. The filter + may be either EGL_COVERAGE_SAMPLE_RESOLVE_DEFAULT_NV or + EGL_COVERAGE_SAMPLE_RESOLVE_NONE_NV, as described above for + eglSurfaceAttrib." + +Interactions with EGL_NV_coverage_sample: + + This extension relies on language in EGL_NV_coverage_sample to + describe the coverage sample buffer. + + If EGL_NV_coverage_sample is not present, this extension has no + effect on rendering. + +Issues + + 1. Should it be an error to set EGL_COVERAGE_SAMPLE_RESOLVE_NV on + surfaces that don't have a coverage buffer? + + RESOLVED: No. EGL_COVERAGE_SAMPLE_RESOLVE_DEFAULT_NV will behave + the same as EGL_COVERAGE_SAMPLE_RESOLVE_NONE_NV in this case. + +Revision History + +#1 (James Jones, 2011-04-13) + + - Initial revision. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_cuda_event.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_cuda_event.txt new file mode 100644 index 0000000..cc54749 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_cuda_event.txt @@ -0,0 +1,206 @@ +Name + + NV_cuda_event + +Name Strings + + EGL_NV_cuda_event + +Contributors + + Debalina Bhattacharjee + Michael Chock + James Jones + Daniel Kartch + +Contact + + Michael Chock (mchock 'at' nvidia.com) + +Status + + Complete + +Version + + Version 2, June 28, 2018 + +Number + + EGL Extension #75 + +Extension Type + + EGL display extension + +Dependencies + + This extension is written against the language of EGL 1.5 and the + EGL_EXT_sync_reuse extension. + + Either EGL_KHR_fence_sync and the EGLAttrib type or EGL 1.5 are + required. + + This extension interacts with, but does not require, + EGL_EXT_sync_reuse. + + This extension interacts with EGL_NV_device_cuda. + +Overview + + This extension allows creating an EGL sync object linked to a CUDA + event object, potentially improving efficiency of sharing images and + compute results between the two APIs. + +IP Status + + No known claims. + +New Types + + A pointer to type cudaEvent_t, defined in the CUDA header files, may + be included in the attribute list passed to eglCreateSync. + +New Procedures and Functions + + None. + +New Tokens + + Accepted as attribute names in the <attrib_list> argument + of eglCreateSync: + + EGL_CUDA_EVENT_HANDLE_NV 0x323B + + Returned in <values> for eglGetSyncAttrib <attribute> + EGL_SYNC_TYPE: + + EGL_SYNC_CUDA_EVENT_NV 0x323C + + Returned in <values> for eglGetSyncAttrib <attribute> + EGL_SYNC_CONDITION: + + EGL_SYNC_CUDA_EVENT_COMPLETE_NV 0x323D + +Add to section 3.8.1 (Sync Objects) of the EGL 1.5 specification, after +the sixth paragraph: + + Likewise, a <CUDA event sync object> reflects the status of a + corresponding CUDA object. Waiting on this type of sync object is + equivalent to waiting for completion of the corresponding linked + CUDA event object. + +Add a new section following section 3.8.1.2 (Creating and Signaling +OpenCL Event Sync Objects): + + Section 3.8.1.X Creating and Signaling CUDA Event Sync Objects + + If <type> is EGL_SYNC_CUDA_EVENT_NV, a CUDA event sync object is + created. The <attrib_list> may contain the attribute + EGL_CUDA_EVENT_HANDLE_NV, set to a pointer to a cudaEvent_t object. + If it does not contain this attribute, the sync object will start in + the signaled state, and an event attribute must be provided the + first time eglUnsignalSyncEXT is called. Otherwise, a call to + eglUnsignalSyncEXT may replace this event attribute or leave it + unspecified, causing the previous object to be reused. + + A cudaEvent_t object provided to eglCreateSync or eglUnsignalSyncEXT + must be properly initialized and recorded by the CUDA API (using + cudaEventCreate and cudaEventRecord), and the CUDA device + used to create the event must correspond to <dpy>[fn1]. Note that + EGL_CUDA_EVENT_HANDLE_NV is not a queryable property of a sync + object. + + [fn1] If EGL_NV_device_cuda is supported, it is sufficient that the + CUDA device used to create the CUDA event matches the + EGL_CUDA_DEVICE_NV attribute of <dpy>'s underlying EGL + device. + + Attributes of the CUDA event sync object are set as follows: + + Attribute Name Initial Attribute Value(s) + ------------- -------------------------- + EGL_SYNC_TYPE EGL_SYNC_CUDA_EVENT_NV + EGL_SYNC_STATUS Depends on status of <event> + EGL_SYNC_CONDITION EGL_SYNC_CUDA_EVENT_COMPLETE_NV + + If an <event> is linked to the sync object, the status of this type + of sync object depends on the state of <event> evaluated at the time + of the most recent call to eglCreateSync or eglUnsignalSyncEXT. If + all device work preceding the most recent call to cudaEventRecord on + the event has not yet completed, the status of the linked sync + object will be EGL_UNSIGNALED. If all such work has completed, the + status of the linked sync object will be EGL_SIGNALED. Calling + cudaEventRecord to modify an event has no effect on the sync object + while its status is EGL_UNSIGNALED, but will have an effect if the + event is reevaluated at a subsequent eglUnsignalSyncEXT call. + + The only condition supported for CUDA event sync objects is + EGL_SYNC_CUDA_EVENT_COMPLETE_NV. It is satisfied when all device + work prior to the most recent call to cudaEventRecord at sync + unsignaling time has completed. + +If EGL_EXT_sync_reuse is not present, then change the second sentence of +3.8.1.X above to "The <attrib_list> must contain ..." and omit the +remaining sentences in the paragraph. Omit all references to +eglUnsignalSyncEXT. + +In 3.8.1 (Sync Objects), if EGL_EXT_sync_reuse is present, then add the +following to the error list for eglUnsignalSyncEXT. Otherwise add it to +the error list for eglCreateSync: + + If <type> is EGL_SYNC_CUDA_EVENT_NV and a EGL_CUDA_EVENT_HANDLE_NV + is not linked to the sync object, then an EGL_BAD_ATTRIBUTE error is + generated. If its attribute value is not a valid CUDA event pointer + or has not been initialized as described above, then + EGL_BAD_ATTRIBUTE may be generated, but the results are undefined + and may include program termination. + +Modify the third paragraph of section 3.8.1.4 (Querying Sync Object +Attributes): + + If any eglClientWaitSync or eglWaitSync commands are blocking on + <sync> when eglDestroySync is called, <sync> is flagged for deletion + and will be deleted when the associated fence command, OpenCL event + object, or CUDA event object has completed, and <sync> is no longer + blocking any such egl*WaitSync command. Otherwise, the sync object + is destroyed immediately. + +Replace the EGL_SYNC_CONDITION row of table 3.9 with: + + Attribute Description Supported Sync Objects + ------------------ ----------------------- ---------------------- + EGL_SYNC_CONDITION Signaling condition EGL_SYNC_FENCE, + EGL_SYNC_CL_EVENT, or + EGL_SYNC_CUDA_EVENT_NV + + Table 3.9 Attributes Accepted by eglGetSyncAttrib + + +Interactions with EGL versions prior to 1.5 + + This extension may be used with earlier versions of EGL, provided + that the EGL_KHR_fence_sync extension is supported. In this case, + replace all references to sync functions and tokens with + corresponding KHR-suffixed versions (e.g., replace eglCreateSync + with eglCreateSyncKHR). + + Additionally, this extension may be used with the 64-bit types and + functions added to EGL_KHR_fence_sync introduced by + EGL_KHR_cl_event2 (EGLAttribKHR and eglCreateSync64KHR). Support + for OpenCL events is not required. + +Issues + + None + +Revision History + + Version 2, 2018/06/28 (Daniel Kartch) + - Rewritten to clearly define interactions with + EGL_EXT_sync_reuse, without requiring it + - Fixed incorrect CUDA function name + - Fixed table spacing + + Version 1, 2014/06/20 (Michael Chock) + - initial version. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_depth_nonlinear.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_depth_nonlinear.txt new file mode 100644 index 0000000..b46b3ca --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_depth_nonlinear.txt @@ -0,0 +1,142 @@ +Name + + NV_depth_nonlinear + +Name Strings + + GL_NV_depth_nonlinear + EGL_NV_depth_nonlinear + +Contact + + Gary King, NVIDIA Corporation (gking 'at' nvidia.com) + +Notice + + Copyright NVIDIA Corporation, 2005 - 2007. + +Status + + NVIDIA Proprietary + +Version + + Last Modified: 2007/03/20 + NVIDIA Revision: 1.0 + +Number + + EGL Extension #18 + OpenGL ES Extension #73 + +Dependencies + + Written based on the wording of the OpenGL 2.0 Specification and + EGL 1.2 Specification. + + Requires EGL 1.1. + + Requires OpenGL-ES 1.0. + + OES_framebuffer_object affects the wording of this specification. + +Overview + + Due to the perspective divide, conventional integer Z-buffers have + a hyperbolic distribution of encodings between the near plane + and the far plane. This can result in inaccurate depth testing, + particularly when the number of depth buffer bits is small + and objects are rendered near the far plane. + + Particularly when the number of depth buffer bits is limited + (desirable and/or required in low-memory environments), artifacts + due to this loss of precision may occur even with relatively + modest far plane-to-near plane ratios (e.g., greater than 100:1). + + Many attempts have been made to provide alternate encodings for + Z-buffer (or alternate formulations for the stored depth) to + reduce the artifacts caused by perspective division, such as + W-buffers, Z-complement buffers and floating-point 1-Z buffers. + + This extension adds a non-linear encoded Z buffer to OpenGL, + which can improve the practically useful range of, e.g. 16-bit + depth buffers by up to a factor of 16, greatly improving depth + test quality in applications where the ratio between the near + and far planes can not be as tightly controlled. + +IP Status + + NVIDIA Proprietary + +New Procedures and Functions + + None + +New Tokens + + Accepted as a valid sized internal format by all functions accepting + sized internal formats with a base format of DEPTH_COMPONENT + + DEPTH_COMPONENT16_NONLINEAR_NV 0x8E2C + + Accepted by the <attrib_list> parameter of eglChooseConfig and + eglCreatePbufferSurface, and by the <attribute> parameter of + eglGetConfigAttrib + + EGL_DEPTH_ENCODING_NV 0x30E2 + + Accepted as a value in the <attrib_list> parameter of eglChooseConfig + and eglCreatePbufferSurface, and returned in the <value> parameter + of eglGetConfigAttrib + + EGL_DEPTH_ENCODING_NONE_NV 0 + EGL_DEPTH_ENCODING_NONLINEAR_NV 0x30E3 + +Changes to the OpenGL 2.0 Specification + + Add the following line to table 3.16 (p. 154) + + +--------------------------------+-----------------+------+ + | Sized Internal Format | Base Internal | D | + | | Format | Bits | + +--------------------------------+-----------------+------+ + | DEPTH_COMPONENT16_NONLINEAR_NV | DEPTH_COMPONENT | 16 | + +--------------------------------+-----------------+------+ + +Changes to the EGL 1.2 Specification + + Add the following line to table 3.1 (p. 14) + + +--------------------------+------+---------------------------------------+ + | Attribute | Type | Notes | + +--------------------------+------+---------------------------------------+ + | EGL_DEPTH_ENCODING_NV | enum | Type of depth-buffer encoding employed| + +--------------------------+------+---------------------------------------+ + + Modify the description of the depth buffer in Section 3.4 (p. 15) + + "The depth buffer is used only by OpenGL ES. It contains fragment depth + (Z) information generated during rasterization. EGL_DEPTH_SIZE indicates + the depth of this buffer in bits, and EGL_DEPTH_ENCODING_NV indicates which + alternate depth-buffer encoding (if any) should be used. Legal values for + EGL_DEPTH_ENCODING_NV are: EGL_DONT_CARE, EGL_DEPTH_ENCODING_NONE_NV and + EGL_DEPTH_ENCODING_NONLINEAR_NV." + + Add the following line to table 3.4 (p. 20) + + +-----------------------+---------------+-----------+-------+----------+ + | Attribute | Default | Selection | Sort | Sort | + | | | Criteria | Order | Priority | + +-----------------------+---------------+-----------+-------+----------+ + | EGL_DEPTH_ENCODING_NV | EGL_DONT_CARE | Exact | None | - | + +-----------------------+---------------+-------------------+----------+ + +Issues + + None + +Revision History + +#1.0 - 20.03.2007 + + Renumbered enumerants. Reformatted to 80 columns. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_device_cuda.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_device_cuda.txt new file mode 100644 index 0000000..1fdc5d6 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_device_cuda.txt @@ -0,0 +1,91 @@ +Name + + NV_device_cuda + +Name Strings + + EGL_NV_device_cuda + +Contributors + + Michael Chock + James Jones + +Contact + + Michael Chock (mchock 'at' nvidia.com) + +Status + + Complete + +Version + + Version 1, June 21, 2014 + +Number + + EGL Extension #74 + +Extension Type + + EGL device extension + +Dependencies + + This extension is written against the language of EGL 1.5 as + modified by EGL_EXT_device_base. + + EGL_EXT_device_base is required. + +Overview + + EGL and CUDA both have the capability to drive multiple devices, + such as GPUs, within a single system. To interoperate with one + another, both APIs must have compatible notions of such devices. + This extension defines a mapping from an EGL device to a CUDA device + enumerant. + +IP Status + + No known claims. + +New Types + + None. + +New Procedures and Functions + + None. + +New Tokens + + Accepted as a queried <attribute> in eglQueryDeviceAttribEXT: + + EGL_CUDA_DEVICE_NV 0x323A + +Add a new section 2.1.3 (CUDA Devices) after 2.1.2 (Devices) + + "Somewhat analogous to an EGL device, a CUDA device establishes a + namespace for CUDA operations. In the CUDA API, such a device is + represented by a C int. For more details, see the CUDA + documentation." + +Changes to section 3.2 (Device Enumeration) + + Replace the paragraph immediately following the prototype for + eglQueryDeviceAttribEXT: + + "The only valid value of <attribute> is EGL_CUDA_DEVICE_NV. On + success, EGL_TRUE is returned, and a valid CUDA device handle + corresponding to the EGL device is returned in <value>. This handle + is compatible with CUDA API functions." + +Issues + + None + +Revision History + + Version 1, 2014/06/24 (Michael Chock) + - initial version. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_n_buffer.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_n_buffer.txt new file mode 100644 index 0000000..9004652 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_n_buffer.txt @@ -0,0 +1,157 @@ +Name + + NV_triple_buffer + NV_quadruple_buffer + +Name Strings + + EGL_NV_triple_buffer + EGL_NV_quadruple_buffer + +Contributors + + Daniel Kartch, NVIDIA Corporation + Tom McReynolds, NVIDIA Corporation + Santanu Thangaraj, NVIDIA Corporation + +Contact + + Daniel Kartch, NVIDIA Corporation (dkartch 'at' nvidia.com) + +Status + + Complete. + +Version + + Version 1 - February 28, 2019 + +Number + + 133 + +Extension Type + + EGL display extension + +Dependencies + + Requires EGL 1.0 + + This extension is written against the wording of the EGL 1.3 + Specification. + +Overview + + NV_triple_buffer and NV_quadruple_buffer allow applications to + request additional back buffers, in order to produce greater and + less variable frame rates. + + This document describes two related extensions, one dependent on + the other. Implementations may choose to support only + NV_triple_buffer and not NV_quadruple_buffer, but not vice versa. + +New Types + + None + +New Procedures and Functions + + None + +New Tokens + + Added by NV_triple_buffer: + + Accepted as a value for EGL_RENDER_BUFFER in the <attrib_list> + parameter of eglCreateWindowSurface: + + EGL_TRIPLE_BUFFER_NV 0x3230 + + Added by NV_quadruple_buffer: + + Accepted as a value for EGL_RENDER_BUFFER in the <attrib_list> + parameter of eglCreateWindowSurface: + + EGL_QUADRUPLE_BUFFER_NV 0x3231 + +Additions to the EGL 1.3 Specification: + + Insert after third sentence of second paragraph of Section 2.2.2 + (Rendering Models): + + Windows may have more than one back buffer, allowing rendering + of a new frame to proceed while the copy requested by + eglSwapBuffers is still pending. + + Replace the third sentence of the EGL_RENDER_BUFFER description in + Section 3.5.1 (Creating On-Screen Rendering Surfaces): + + If its value is EGL_BACK_BUFFER, EGL_TRIPLE_BUFFER_NV, or + EGL_QUADRUPLE_BUFFER_NV, then client APIs should render into + the current back buffer. The implementation should provide + at least one, two, or three back buffers, respectively, which + will be used in rotation each frame. + + Change first sentence of third bullet point of eglQueryContext + description in Section 3.7.4 (Context Queries): + + If the context is bound to a window surface, then either + EGL_SINGLE_BUFFER, EGL_BACK_BUFFER, EGL_TRIPLE_BUFFER_NV, or + EGL_QUADRUPLE_BUFFER_NV may be returned. + + Replace first sentence of eglSwapBuffers description in + Section 3.9.1 + (Posting to a Window): + + If surface is a back-buffered window surface, then the current + color buffer is copied to the native window associated with + that surface. If there is more than one back buffer, then the + next color buffer in rotation becomes current, and rendering + of the next frame may proceed before the copy takes place, + provided any previous swaps from the new current buffer have + completed. + +Issues + + 1. Why do we need triple-buffering? + + RESOLVED: With only a single back buffer and a non-zero swap + interval, eglSwapBuffers must block rendering to the back- + buffer until the copy has completed. This can leave the CPU + and/or GPU idle, wasting valuable compute time, and possibly + cause the next frame to be delivered later than otherwise could + have been. Additional buffers allow rendering to continue even + when a frame is awaiting display, maximizing our use of + computational resources. + + 2. Why quadruple-buffering? Isn't triple-buffering enough to + produce frames as fast as the processor(s) and swap interval + allow? + + RESOLVED: When there is only a single rendering stream + operating on a system, triple-buffering is sufficient. However, + if other threads are contending for resources, variable + latencies may be introduced. This is especially problematic + with video, where any deviation in frame rate from the recorded + media can produce visible artifacts. Additional buffers smooth + out these latencies, allowing a steady frame rate. + + 3. Then why not arbitrary n-buffering? + + RESOLVED: The TRIPLE/QUADRUPLE buffer specification fits nicely + into the RENDER_BUFFER attribute already in use for + eglCreateWindowSurface. Arbitrary buffer counts would require a + new attribute. Additionally, case studies indicated no + significant benefit to using more than three back buffers, + especially when factoring in the added memory cost. + +Revision History + + #2 (February 28, 2019) Santanu Thangaraj + - Marked issues 1,2 and 3 as resolved. + - Included extension type section. + - Corrected line length violations. + + #1 (August 12, 2008) Daniel Kartch + - Initial Draft diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_native_query.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_native_query.txt new file mode 100644 index 0000000..ce35633 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_native_query.txt @@ -0,0 +1,137 @@ +Name + + NV_native_query + +Name Strings + + EGL_NV_native_query + +Contributors + + Mathias Heyer, NVIDIA + Daniel Kartch, NVIDIA + Peter Pipkorn, NVIDIA + Acorn Pooley, NVIDIA + Greg Roth, NVIDIA + +Contacts + + Peter Pipkorn, NVIDIA Corporation (ppipkorn 'at' nvidia.com) + +Status + + Complete + +Version + + Version 0.4, 25 Sept, 2012 + +Number + + EGL Extension #45 + +Dependencies + + Requires EGL 1.0 + + This extension is written against the wording of the EGL 1.4 + Specification. + +Overview + + This extension allows an application to query which native display, + pixmap and surface corresponds to a EGL object. + +New Procedures and Functions + + EGLBoolean eglQueryNativeDisplayNV( + EGLDisplay dpy, + EGLNativeDisplayType* display_id); + + EGLBoolean eglQueryNativeWindowNV( + EGLDisplay dpy, + EGLSurface surf, + EGLNativeWindowType* window); + + EGLBoolean eglQueryNativePixmapNV( + EGLDisplay dpy, + EGLSurface surf, + EGLNativePixmapType* pixmap); + +Changes to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors) + + In Chapter 3.2, after the description of eglInitialize and before the + description of eglTerminate insert + + "While initialized, the native display that corresponds to an + EGLDisplay can retrieved by + + EGLBoolean eglQueryNativeDisplayNV( + EGLDisplay dpy, + EGLNativeDisplayType* display_id); + + If the <dpy> is a valid and initialized EGLDisplay, EGL_TRUE + will be returned and the native display handle will be written + to <display_id>. Otherwise EGL_FALSE will be returned and the + contents of <display_id> are left untouched. If the <dpy> is + not valid, an EGL_BAD_DISPLAY error will be generated. If <dpy> + is not initialized, an EGL_NOT_INITIALIZED error will be + generated. If <display_id> is NULL, an EGL_BAD_PARAMETER error + will be generated. + + In Chapter 3.5 Rendering Surfaces, after section 3.5.1 insert + + "The native window that corresponds to an EGLSurface can be + retrieved by + + EGLBoolean eglQueryNativeWindowNV( + EGLDisplay dpy, + EGLSurface surf, + EGLNativeWindowType* win); + + The corresponding native window will be written to <win>, + and EGL_TRUE will be returned. If the call fails, EGL_FALSE + will be returned, and content of <win> will not be modified. + If <dpy> is not a valid EGLDisplay, an EGL_BAD_DISPLAY error + will be generated. If <dpy> is not initialized, an EGL_NOT_- + INITIALIZED error will be generated. If <surf> is not a valid + EGLSurface, or <surf> does not have a corresponding native + window, an EGL_BAD_SURFACE error will be generated." If <win> + is NULL, an EGL_BAD_PARAMETER error will be generated. + + After section 3.5.4 Creating Native Pixmap Rendering Surfaces insert + + "The native pixmap that corresponds to an EGLSurface can be + retrieved by + + EGLBoolean eglQueryNativePixmapNV( + EGLDisplay dpy, + EGLSurface surf, + EGLNativePixmapType* pixmap); + + The corresponding native pixmap will be written to <pixmap>, + and EGL_TRUE will be returned. If the call fails, EGL_FALSE + will be returned, and the content of <pixmap> will not be + modified. If <dpy> is not a valid EGLDisplay, an EGL_BAD_- + DISPLAY error will be generated. If <dpy> is not initialized, + an EGL_NOT_INITIALIZED error will be generated. If <surf> is + not a valid EGLSurface, or <surf> does not have a corresponding + native pixmap, an EGL_BAD_SURFACE error will be generated." If + <pixmap> is NULL, an EGL_BAD_PARAMETER error will be + generated. + +Issues + +Revision History +#4 (Greg Roth, Sept 25, 2012) + - Further document all potential errors for all functions + +#3 (Daniel Kartch, August 30, 2011) + - Add restriction that EGLDisplay be initialized + +#2 (Peter Pipkorn, December 16, 2009) + - Minor cleanup + +#1 (Peter Pipkorn, December 15, 2009) + - First Draft + diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_post_convert_rounding.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_post_convert_rounding.txt new file mode 100644 index 0000000..6b7c340 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_post_convert_rounding.txt @@ -0,0 +1,85 @@ +Name + + NV_post_convert_rounding + +Name Strings + + EGL_NV_post_convert_rounding + +Contributors + + Bryan Eyler, NVIDIA + Daniel Kartch, NVIDIA + Greg Roth, NVIDIA + Mark Vojkovich, NVIDIA + Nicolai de Haan Brogger, NVIDIA + Peter Pipkorn, NVIDIA + +Contacts + + Nicolai de Haan Brogger, NVIDIA Corporation (nicolaid 'at' nvidia.com) + +Status + + Complete + +Version + + Last Modified 17 Oct 2012 + Version 2 + +Number + + EGL Extension #44 + +Dependencies + + Requires EGL 1.0. + + This extension is written against the wording of the EGL 1.4 + Specification. + +Overview + + This extension defines the conversions for posting operations + when the destination's number of components or component sizes do + not match the color buffer. This extension supports posting a 24 bit + (888) color buffer to a 16 bit (565) destination buffer, posting a + 16 bit (565) color buffer to a 24 bit (888) destination buffer, and + posting a component that is present in the source buffer, but not + present in the destination buffer. + +New Procedures and Functions + + None + +Changes to Chapter 3 of the EGL 1.4 Specification (EGL Functions and +Errors) + + In Chapter 3.9.3, replace paragraph 3 with: + " For each color component, if the bit depth of the color + buffer being posted is 24 (888) and the destination buffer is + 16 (565), the lower order bits of the color buffer are + truncated. + + If the bit depth of the destination buffer is 24 (888) and the + color buffer being posted is 16 bit (565), a RGB gain and + rounding operation is applied to the color buffer values prior + to posting. The destination buffer will contain the rounded + (nearest) and clamped result of the vector product of [1.03125, + 1.015625, 1.03125] with the RGB values of the color buffer. + + For cases where a component is present in the color buffer but + the matching component is not present in the destination + buffer, that component will be dropped." + + In Chapter 3.9.3, remove paragraph 5. + +Issues + +Revision History +#2 (Greg Roth, Oct 17, 2012) + - Clarify limitations and reformat a bit. + +#1 (Nicolai de Haan Brogger, July 07, 2010) + - First Draft diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_post_sub_buffer.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_post_sub_buffer.txt new file mode 100644 index 0000000..69c113c --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_post_sub_buffer.txt @@ -0,0 +1,241 @@ +Name + + NV_post_sub_buffer + +Name Strings + + EGL_NV_post_sub_buffer + +Contributors + + Arcady Goldmints-Orlov + James Jones + Daniel Kartch + +Contact + + James Jones, NVIDIA Corporation (jajones 'at' nvidia.com) + +Status + + Draft. + +Version + + Version 3, November 5, 2010 + +Number + + EGL Extension #27 + +Dependencies + + Requires EGL 1.1 + + This extension is written against the wording of the EGL 1.4 + Specification + +Overview + + Many EGL client APIs do not support rendering to window surfaces + directly, so there is no way to efficiently make small updates to + window surfaces. Applications that need to perform many small updates + must either use the back-buffer preservation flag which forces + eglSwapBuffers to copy the entire back surface, or redraw the entire + back buffer on every update and hope eglSwapBuffers is implemented + using buffer-flipping. This extension provides a 3rd alternative: a + function which posts a sub-rectangle of a window surface and + preserves the back-buffer contents. + +New Types + + None. + +New Procedures and Functions + + EGLBoolean eglPostSubBufferNV(EGLDisplay dpy, + EGLSurface surface, + EGLint x, EGLint y, + EGLint width, EGLint height); + +New Tokens + + Accepted by the <attribute> parameter of eglQuerySurface and by the + <attrib_list> parameter of eglCreateWindowSurface: + + EGL_POST_SUB_BUFFER_SUPPORTED_NV 0x30BE + +Changes to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors) + + Modify the second paragraph of Section 3.5.1, page 27 + (Creating On-Screen Rendering Surfaces) + + "<attrib_list> specifies a list of attributes for the window. The list + has the same structure as described for eglChooseConfig. Attributes + that can be specified in <attrib_list> include EGL_POST_SUB_BUFFER_- + SUPPORTED_NV, EGL_RENDER_BUFFER, EGL_VG_COLORSPACE, and EGL_VG_ALPHA_- + FORMAT." + + Add the following between paragraphs 4 and 5 of Section 3.5.1, page 27 + (Creating On-Screen Rendering Surfaces) + + "EGL_POST_SUB_BUFFER_SUPPORTED_NV specifies whether the application + would perfer a surface that supports sub-buffer post operations, as + described in section 3.9.1. Its values can be EGL_TRUE, in which case + the implementation will attempt to allocate a surface that supports + sub-buffer posts, or EGL_FALSE, in which case the implementation will + not take sub-buffer post capabilities into account. + + "Implementations may not be able to support sub-buffer post + mechanisms, or may support them only on some native windows. Use + eglQuerySurface to determine a surface's capabilities (see section + 3.5.6)." + + Add the following entry to Table 3.5, page 36 + (Queryable surface attributes and types) + + Attribute Type Description + -------------------------------- ------- ------------------------ + EGL_POST_SUB_BUFFER_SUPPORTED_NV boolean Surface can be used with + eglPostSubBufferNV + + Add the following paragraph to Section 3.5.6, page 37 + (Surface Attributes) + + "Querying EGL_POST_SUB_BUFFER_SUPPORTED_NV returns EGL_TRUE if the + surface can use eglPostSubBufferNV (See section 3.9.1) to post sub- + rectangles of the back color buffer. Otherwise, EGL_FALSE is + returned." + + Replace all but the last paragraph of section Section 3.9.1, page 50 + (Posting to a Window) + + "To post the color buffer to a window, call + + EGLBoolean eglSwapBuffers(EGLDisplay dpy, + EGLSurface surface); + + "To post a sub-rectangle of the color buffer to a window, call + + EGLBoolean eglPostSubBufferNV(EGLDisplay dpy, + EGLSurface surface, EGLint x, EGLint y, + EGLint width, EGLint height); + + "Where <x> and <y> are pixel offsets from the bottom-left corner of + <surface>. + + "If <surface> is a back-buffered surface, then the requested portion + of the color buffer is copied to the native window associated with + that surface. If <surface> is a single-buffered window, pixmap, or + pbuffer surface, eglSwapBuffers and eglPostSubBufferNV have no + effect. + + "The contents of ancillary buffers are always undefined after calling + eglSwapBuffers or eglPostSubBufferNV. The contents of the color + buffer are unchanged if eglPostSubBufferNV is called, or if + eglSwapBuffers is called and the value of the EGL_SWAP_BEHAVIOR + attribute of <surface> is EGL_BUFFER_PRESERVED. The value of EGL_- + SWAP_BEHAVIOR can be set for some surfaces using eglSurfaceAttrib, as + described in section 3.5.6. + + "Native Window Resizing + + "If the native window corresponding to <surface> has been resized + prior to the swap, <surface> must be resized to match. <surface> will + normally be resized by the EGL implementation at the time the native + window is resized. If the implementation cannot do this transparently + to the client, then eglSwapBuffers and eglPostSubBufferNV must + detect the change and resize <surface> prior to copying its pixels to + the native window. The sub-rectangle defined by <x>, <y>, <width>, and + <height> parameters to eglPostSubBufferNV will be clamped to the + extents of <surface>. If, after clamping, the rectangle contains no + pixels, eglPostSubBufferNV will have no effect." + + Modify the following sentences in Section 3.9.3, page 51 (Posting + Semantics) + + Paragraph 2, first sentence: + + "If <dpy> and <surface> are the display and surface for the calling + thread's current context, eglSwapBuffers, eglPostSubBufferNV, and + eglCopyBuffers perform an implicit flush operation on the context + (glFlush for OpenGL or OpenGL ES context, vgFlush for an OpenVG + context)." + + Paragraph 3, first sentence: + + "The destination of a posting operation (a visible window, for + eglSwapBuffers or eglPostSubBufferNV, or a native pixmap, for + eglCopyBuffers) should have the same number of components and + component sizes as the color buffer it's being copied from." + + Paragraph 6, first two sentences: + + "The function + + EGLBoolean eglSwapInterval(EGLDisplay dpy, EGLint + interval); + + specifes the minimum number of video frame periods per color buffer + post operation for the window associated with the current context. The + interval takes effect when eglSwapBuffers or eglPostSubBufferNV is + first called subsequent to the eglSwapInterval call." + + Modify the following sentences in Section 3.9.4, page 52 (Posting + Errors) + + Paragraph 1, first sentence: + + "eglSwapBuffers, eglPostSubBufferNV, and eglCopyBuffers return + EGL_FALSE on failure." + + Paragraph 1, seventh sentence: + + "If eglSwapBuffers or eglPostSubBufferNV are called and the native + window associated with <surface> is no longer valid, an EGL_BAD_- + NATIVE_WINDOW error is generated. If eglPostSubBufferNV is called + and <x>, <y>, <width>, or <height> are less than zero, EGL_BAD_- + PARAMETER is generated." + +Issues + + 1. Should all surfaces be required to support sub-buffer posts if + this extension is supported? + + RESOLVED: No. Some implementations may support multiple types of + native windows. Support for sub-surface posting is therefore a + per-surface property, so a surface query should be used to determine + which surfaces support sub-surface posts. + + 2. What should this extension be called? + + RESOLVED: Names considered EGL_NV_copy_sub_buffer, EGL_NV_present_sub- + surface, EGL_NV_post_sub_buffer. eglCopySubBuffer() sounded too + similar to eglCopyBuffer(), which operates on different types of + surfaces. EGL_present_sub_surface was originally chosen as it was + sufficiently different than eglCopyBuffer(), but based on internal + feedback, the term "Post" is preferable to "Present" because it is + already used in the EGL spec to describe buffer presentation + operations. "Buffer" was chosen over "surface" at this point as well, + because it is more consistent with the eglSwapBuffers() and + eglCopyBuffer() commands, and eglPostSubBuffer() is still + differentiated enough from eglCopyBuffer() that the two won't be + confused. + +Revision History + +#3 (James Jones, November 5, 2010) + -Renamed from NV_present_sub_surface to NV_post_sub_buffer based on + feedback from internal reviews. + + -Allowed EGL_POST_SUB_BUFFER_SUPPORTED_NV to be used as a hint when + creating window surfaces. + + -Clarified that eglSwapInterval applies to all color-buffer post + operations affecting on-screen surfaces, not just eglSwapBuffers. + +#2 (James Jones, November 1, 2010) + - Fixed a few typos. + +#1 (James Jones, October 22, 2010) + - Initial revision, based on GLX_MESA_copy_sub_buffer diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_consumer_eglimage.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_consumer_eglimage.txt new file mode 100644 index 0000000..432fdbf --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_consumer_eglimage.txt @@ -0,0 +1,367 @@ +Name + + NV_stream_consumer_eglimage + +Name Strings + + EGL_NV_stream_consumer_eglimage + +Contributors + + Mukund Keshava + James Jones + Daniel Kartch + Sandeep Shinde + Pyarelal Knowles + Leo Xu + +Contacts + + Mukund Keshava, NVIDIA (mkeshava 'at' nvidia.com) + +Status + + Draft + +Version + + Version 3 - November 27, 2019 + +Number + + EGL Extension #139 + +Extension Type + + EGL display extension + +Dependencies + + Requires the EGL_KHR_stream extension. + + Requires the EGL_EXT_sync_reuse extension. + + This extension is written against the wording of the EGL 1.5 + Specification + +Overview + + An EGLStream consists of a sequence of image frames. This extension + allows these frames to be acquired as EGLImages. Frames from the + stream would be used as the content for the EGLImage. + +New Procedures and Functions + + EGLBoolean eglStreamImageConsumerConnectNV( + EGLDisplay dpy, + EGLStreamKHR stream, + EGLint num_modifiers, + const EGLuint64KHR *modifiers, + const EGLAttrib* attrib_list); + + EGLint eglQueryStreamConsumerEventNV( + EGLDisplay dpy, + EGLStreamKHR stream, + EGLTime timeout, + EGLenum *event, + EGLAttrib *aux); + + EGLBoolean eglStreamAcquireImageNV( + EGLDisplay dpy, + EGLStreamKHR stream, + EGLImage *pImage, + EGLSync sync); + + EGLBoolean eglStreamReleaseImageNV( + EGLDisplay dpy, + EGLStreamKHR stream, + EGLImage image, + EGLSync sync); + +New Tokens + + Accepted by the <target> parameter of eglCreateImage: + + EGL_STREAM_CONSUMER_IMAGE_NV 0x3373 + + Returned as an <event> from eglQueryStreamConsumerEventNV: + + EGL_STREAM_IMAGE_ADD_NV 0x3374 + EGL_STREAM_IMAGE_REMOVE_NV 0x3375 + EGL_STREAM_IMAGE_AVAILABLE_NV 0x3376 + +Add to section "3.9 EGLImage Specification and Management" of +the EGL 1.5 Specification, in the description of eglCreateImage: + + "Values accepted for <target> are listed in Table 3.10, below. + + +-------------------------------+-----------------------------------+ + | <target> | Notes | + +-------------------------------+-----------------------------------+ + | EGL_STREAM_CONSUMER_IMAGE_NV | Used with EGLStream objects | + +-------------------------------+-----------------------------------+ + Table 3.10: Legal values for eglCreateImage target parameter. + + If <target> is EGL_STREAM_CONSUMER_IMAGE_NV, a new EGLImage will be + created for the next consumer image frame in the EGLStream + referenced by <buffer> which is not currently bound to an EGLImage. + If the stream's producer reuses memory buffers for multiple image + frames, then an EGLImage obtained in this way will persist for the + next image frame that uses the same buffer, unless destroyed in + the interim. Otherwise, the user must create a new EGLImage for + every frame. Creating the EGLImage does not guarantee that the + image contents will be ready for use. The EGLImage must first be + acquired from the stream after creation. + + If the EGLImage created for a consumer image frame is destroyed via + eglDestroyImage, a new EGLImage needs to be created via + eglCreateImage for the same consumer image frame. + + <dpy> must be a valid initialized display. <ctx> must be + EGL_NO_CONTEXT. <buffer> must be a handle to a valid EGLStream + object, cast into the type EGLClientBuffer. + + Add to the list of error conditions for eglCreateImage: + + "* If <target> is EGL_STREAM_CONSUMER_IMAGE_NV and <buffer> is + not a valid stream handle associated with <dpy>, the error + EGL_BAD_STREAM_KHR is generated. + + * If <target> is EGL_STREAM_CONSUMER_IMAGE_NV, and <ctx> is not + EGL_NO_CONTEXT, the error EGL_BAD_PARAMETER is generated. + + * If <target> is EGL_STREAM_CONSUMER_IMAGE_NV, and there are no + buffers in the <stream> currently or if there are no buffers + associated with the stream that are not already bound to + EGLImages EGL_BAD_ACCESS is generated. + + eglCreateImage needs to be called with EGL_STREAM_CONSUMER_IMAGE_NV + as the <target> for every valid buffer in the EGLStream. + +Add section "3.10.2 Connecting an EGLStream to a consumer" in the +EGL_KHR_stream extension with this: + + 3.10.2.2 EGLImage consumer + + Call + + EGLBoolean eglStreamImageConsumerConnectNV( + EGLDisplay dpy, + EGLStreamKHR stream, + EGLint num_modifiers, + const EGLuint64KHR *modifiers, + const EGLAttrib* attrib_list); + + to connect the EGLImage consumer to the <stream>. An EGLImage + consumer allows image frames inserted in the stream to be received + as EGLImages, which can then be bound to any other object which + supports EGLImage. For each image frame, an EGLImage must first be + created as described in section "3.9 EGLImage Specification and + Management" of the EGL 1.5 Specification, and then the frame + contents must be latched to the EGLImage as described below. + + In <modifiers> the consumer can advertise an optional list of + supported DRM modifiers as described in + EXT_image_dma_buf_import_modifiers. This information could be + used by the producer to generate consumer supported image frames. + + If not NULL, <attrib_list> points to an array of name/value + pairs, terminated by EGL_NONE. Currently no attributes are + supported. + + On success, EGL_TRUE is returned. + + - <stream> state is set to EGL_STREAM_STATE_CONNECTING_KHR + allowing the producer to be connected. + + On failure, EGL_FALSE is returned and an error is generated. + + - EGL_BAD_DISPLAY is generated if <dpy> is not the handle of a + valid EGLDisplay object. + + - EGL_BAD_STREAM_KHR is generated if <stream> is not a valid + valid stream handle associated with <dpy>. + + - EGL_BAD_STATE_KHR is generated if the <stream> state is not + EGL_STREAM_STATE_CREATED_KHR before + eglStreamImageConsumerConnectNV is called. + + Call + + EGLint eglQueryStreamConsumerEventNV( + EGLDisplay dpy, + EGLStreamKHR stream, + EGLTime timeout, + EGLenum *event, + EGLAttrib *aux); + + to query the <stream> for the next pending event. + eglQueryStreamConsumerEventNV returns in <event> the event type + and returns in <aux> additional data associated with some events. + + If no event is pending at the time eglQueryStreamConsumerEventNV is + called, it will wait up to <timeout> nanoseconds for one to arrive + before returning. If <timeout> is EGL_FOREVER, the function will + not time out and will only return if an event arrives or the stream + becomes disconnected. + + On success, EGL_TRUE is returned. A new event will be returned. + The valid events are as follows: + + - EGL_STREAM_IMAGE_ADD_NV is returned if a buffer is present in + the stream which has not yet been bound to an EGLImage with + eglCreateImage. + + - EGL_STREAM_IMAGE_REMOVE_NV indicates that a buffer has been + removed from the stream and its EGLImage, whose handle is + returned in <aux>, can be destroyed when the consumer + application no longer requires it. + + - EGL_STREAM_IMAGE_AVAILABLE_NV indicates that there is a + new frame available in the stream that can be acquired via + eglStreamAcquireImageNV. + + On failure, EGL_FALSE is returned and an error is generated and + <event> and <aux> are not modified. + + - EGL_BAD_STREAM_KHR is generated if <stream> is not a valid + valid stream handle associated with <dpy>. + + EGL_TIMEOUT_EXPIRED is returned if the <timeout> duration is + complete, and there are no valid events that occured in this + duration. The <event> and <aux> parameters are not modified. + + Call + + EGLBoolean eglStreamAcquireImageNV( + EGLDisplay dpy, + EGLStreamKHR stream, + EGLImage *pImage, + EGLSync sync); + + to "latch" the next image frame in the image stream from <stream> + into an EGLImage. + + If <sync> is not EGL_NO_SYNC, then it must be an EGLSync with a type + of EGL_SYNC_FENCE, and it must be signaled (e.g., created with + EGL_SYNC_STATUS set to EGL_SIGNALED). eglStreamAcquireImageNV will + reset the state of <sync> to unsignaled, and <sync> will be signaled + when the producer is done writing to the frame. + + If <sync> is EGL_NO_SYNC, then eglStreamAcquireImageNV ignores the + sync object. + + On success, EGL_TRUE is returned. + + - <pImage> will have the most recent frame from the <stream> + + On failure, eglStreamAcquireImageNV returns EGL_FALSE, and an error + is generated. + + - EGL_BAD_DISPLAY is generated if <dpy> is not a valid, + initialized EGLDisplay. + + - EGL_BAD_STREAM_KHR is generated if <stream> is not a valid + valid stream handle associated with <dpy>. + + - EGL_BAD_ACCESS is generated if there are no frames in the + <stream> that are available to acquire. + + - EGL_BAD_PARAMETER is generated if <sync> is not a valid + EGLSync object or EGL_NO_SYNC. + + - EGL_BAD_ACCESS is generated if <sync> is not EGL_NO_SYNC and is + not a fence sync. + + - EGL_BAD_ACCESS is generated if <sync> is not EGL_NO_SYNC and is + not in the signaled state. + + Call + + EGLBoolean eglStreamReleaseImageNV( + EGLDisplay dpy, + EGLStreamKHR stream, + EGLImage image, + EGLSync sync); + + to release the <image> frame back to the stream. This takes a + <sync> that indicates when the consumer will be done using the + frame. Before calling eglStreamReleaseImageNV, the <image> + needs to have previously been acquired with + eglStreamAcquireImageNV. + + If <sync> is not EGL_NO_SYNC, then it must be an EGLSync with a + typeof EGL_SYNC_FENCE. eglStreamReleaseImageNV makes a copy of the + sync object, so the caller is free to delete or reuse <sync> as it + chooses. + + If <sync> is EGL_NO_SYNC, then the sync object is ignored. + + On success, EGL_TRUE is returned, and the frame is successfully + returned back to the stream. + + On failure, eglStreamReleaseImageNV returns EGL_FALSE, and an + error is generated. + + - EGL_BAD_DISPLAY is generated if <dpy> is not a valid, + initialized EGLDisplay. + + - 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_STREAM_KHR is generated if <stream> is not a valid + EGLStream created for <dpy>. + + - EGL_BAD_PARAMETER is generated if <image> is either invalid, + or is not held by the consumer. + + - EGL_BAD_PARAMETER is generated if <sync> is not a valid + EGLSync object or EGL_NO_SYNC. + + - EGL_BAD_ACCESS is generated if <sync> is not EGL_NO_SYNC and is + not a fence sync. + + If an acquired EGLImage has not yet released when eglDestroyImage + is called, then, then an implicit eglStreamReleaseImageNV will be + called. + +Add a new subsection 3.10.4.3.1 at the end of section "3.10.4.3 +EGL_STREAM_STATE_KHR Attribute" in the EGL_KHR_stream extension spec: + + 3.10.4.3.1 Interaction with EGL_STREAM_STATE_KHR + + Image frames that have been presented to the stream on the producer + side, but have not been bound to an EGLImage on the consumer side + yet, do not affect the EGLStream state. + + If a new frame is presented to the stream, the stream state goes + into EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR only if this frame is + bound to an EGLImage on the consumer, and if it has not already + been acquired. + + If an EGLImage bound on the consumer side has been destroyed via + eglDestroyImage, then the stream goes into + EGL_STREAM_STATE_EMPTY_KHR if there are no consumer frames left, + that are bound to an EGLImage. + +Issues + + +Revision History + + #5 (December 15, 2021) Kyle Brenneman + - Corrected and clarified the <sync> parameters + + #4 (December 10, 2021) Kyle Brenneman + - Added the missing const modifier for input parameters + + #3 (November 27, 2019) Mukund Keshava + - Refined some subsections with more details + + #2 (November 22, 2019) Mukund Keshava + - Refined some subsections with more details + - Added new subsection 3.10.4.3.1 + + #1 (November 13, 2019) Mukund Keshava + - initial draft diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_consumer_gltexture_yuv.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_consumer_gltexture_yuv.txt new file mode 100644 index 0000000..4aa0a66 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_consumer_gltexture_yuv.txt @@ -0,0 +1,280 @@ +Name + + NV_stream_consumer_gltexture_yuv + +Name Strings + + EGL_NV_stream_consumer_gltexture_yuv + +Contributors + + James Jones + Daniel Kartch + Nikhil Mahale + Daniel Koch + Jeff Gilbert + +Contacts + + James Jones, NVIDIA (jajones 'at' nvidia 'dot' com) + +Status + + Complete + +Version + + Version 4 - November 14, 2017 + +Number + + EGL Extension #94 + +Extension Type + + EGL display extension + +Dependencies + + Requires EGL_KHR_stream_consumer_gltexture + References EGL_EXT_yuv_surface + +Interactions with EGL_EXT_yuv_surface + + This extension makes use of several tokens defined in the + EGL_EXT_yuv_surface extension spec. However support for this + EGLStream extension does not require the EGLSurface extension, or + vice versa. Only the tokens are shared. + +Overview + + The EGL_KHR_stream_consumer_gltexture extension allows EGLStream + frames to be latched to a GL texture for use in rendering. These + frames are assumed to be stored in RGB format and accessed as such + by shader programs. If the producer uses a different color space, + the stream implementation must perform an implicit conversion. + + In cases where the producer operates in a native YUV color space, it + may be desirable for shaders to directly access the YUV components, + without conversion. This extension adds a new variant of the + function to bind GL textures as stream consumers which allows + attributes to specify the color space. + +New Types + + None + +New Functions + + EGLBoolean eglStreamConsumerGLTextureExternalAttribsNV( + EGLDisplay dpy, + EGLStreamKHR stream, + const EGLAttrib *attrib_list) + +New Tokens + + Accepted as attribute name in <attrib_list> by + eglStreamConsumerGLTextureExternalAttribsNV: + + EGL_YUV_PLANE0_TEXTURE_UNIT_NV 0x332C + EGL_YUV_PLANE1_TEXTURE_UNIT_NV 0x332D + EGL_YUV_PLANE2_TEXTURE_UNIT_NV 0x332E + +Reused Tokens From EGL_EXT_yuv_surface + + Accepted as attribute name in <attrib_list> by + eglStreamConsumerGLTextureExternalAttribsNV: + + EGL_YUV_NUMBER_OF_PLANES_EXT 0x3311 + + Accepted as value for EGL_COLOR_BUFFER_TYPE attribute in + <attrib_list> by eglStreamConsumerGLTextureExternalAttribsNV: + + EGL_YUV_BUFFER_EXT 0x3300 + +Replace entire description of eglStreamConsumerGLTextureExternalKHR in +section "3.10.2.1 GL Texture External consumer" of +EGL_KHR_stream_consumer_gltexture extension. + + Call + + EGLBoolean eglStreamConsumerGLTextureExternalAttribsNV( + EGLDisplay dpy, + EGLStreamKHR stream, + const EGLAttrib *attrib_list) + + to connect one or more texture objects in the OpenGL or OpenGL ES + context current to the calling thread as the consumer(s) of + <stream>. The identity and format of the texture objects used are + determined by <attrib_list> and the current context state. + + <attrib_list> must either be NULL or point to an array of name/value + pairs terminated by EGL_NONE. Valid attribute names are + EGL_COLOR_BUFFER_TYPE, EGL_YUV_NUMBER_OF_PLANES_EXT, and + EGL_YUV_PLANE<n>_TEXTURE_UNIT_NV. + + If the value of EGL_COLOR_BUFFER_TYPE is EGL_RGB_BUFFER (the + default), then the stream will be connected to a single texture + whose contents are available to shaders as RGB values. If the value + of EGL_COLOR_BUFFER_TYPE is EGL_YUV_BUFFER_EXT the stream will be + connected to some number of planar textures, determined by the value + of EGL_YUV_NUMBER_OF_PLANES_EXT, whose contents are available to + shaders as YUV values. The mapping between YUV values and texture + contents is described in table 3.10.2.1. + + If EGL_COLOR_BUFFER_TYPE is EGL_YUV_BUFFER_EXT, the default value of + EGL_YUV_NUMBER_OF_PLANES_EXT is 2. Otherwise it is 0. + + PLANE0 PLANE1 PLANE2 + # Planes Values Fields Values Fields Values Fields + -------------------------------------------------------------- + 1 YUV XYZ unused unused + 2 Y X UV XY unused + 3 Y X U X V X + + Table 3.10.2.1 YUV Planar Texture Mappings + + If EGL_COLOR_BUFFER_TYPE is EGL_RGB_BUFFER, the stream is connected + to the texture object currently bound to the active texture unit's + GL_TEXTURE_EXTERNAL_OES texture target in the current context. + + If EGL_COLOR_BUFFER_TYPE is EGL_YUV_BUFFER_EXT, attribute values + must be specified for EGL_YUV_PLANE<n>_TEXTURE_UNIT_NV for all <n> + less than the number of planes. The value of each attribute must + either be a valid texture unit index or EGL_NONE. No two of these + attributes may specify the same valid texture unit index or + reference separate texture units bound to the same texture object. + Plane <n> of the stream contents will be connected to the texture + object currently bound to the indexed texture unit's + GL_TEXTURE_EXTERNAL_OES texture target in the current context, or + will be left unused if the index is EGL_NONE. + + Once connected, the stream will remain associated with the initial + texture object(s) even if the texture units are bound to new + textures. + + (Note: Before this can succeed a GL_TEXTURE_EXTERNAL_OES texture + must be bound to the appropriate texture units 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_DISPLAY is generated if <dpy> is not a valid, + EGLDisplay. + + - EGL_BAD_STREAM_KHR is generated if <stream> is not a valid + EGLStreamKHR created for <dpy>. + + - EGL_BAD_STATE_KHR is generated if <stream> is not in state + EGL_STREAM_STATE_CREATED_KHR. + + - EGL_BAD_ATTRIBUTE is generated if any attribute name in + <attrib_list> is not a valid attribute. + + - EGL_BAD_PARAMETER is generated if the value of + EGL_COLOR_BUFFER_TYPE is not EGL_RGB_BUFFER or + EGL_YUV_BUFFER_EXT. + + - EGL_BAD_MATCH is generated if EGL_COLOR_BUFFER_TYPE is + EGL_RGB_BUFFER and EGL_YUV_NUMBER_OF_PLANES_EXT is not 0, or + if EGL_COLOR_BUFFER_TYPE is EGL_YUV_BUFFER_EXT and + EGL_YUV_NUMBER_OF_PLANES_EXT is not 1, 2, or 3. + + - EGL_BAD_MATCH is generated if any + EGL_YUV_PLANE<n>_TEXTURE_UNIT_NV is not specified for any <n> + less than EGL_YUV_NUMBER_OF_PLANES_EXT, or if it is specified + for any <n> greater than or equal to + EGL_YUV_NUMBER_OF_PLANES_EXT. + + - EGL_BAD_ACCESS is generated if any + EGL_YUV_PLANE<n>_TEXTURE_UNIT_NV is set to anything other than + a valid texture unit index or EGL_NONE. + + - EGL_BAD_ACCESS is generated if there is no GL context + current to the calling thread. + + - EGL_BAD_ACCESS is generated unless nonzero texture object + names are bound the GL_TEXTURE_EXTERNAL_OES texture target + of each of the appropriate texture units of the GL context + current to the calling thread. + + - EGL_BAD_ACCESS is generated if more than one planar surface + would be bound to the same texture object. + + - EGL_BAD_ACCESS is generated if the implementation cannot + support the requested planar arrangement. + + On success the texture(s) are connected to the <stream>, <stream> + is placed in the EGL_STREAM_STATE_CONNECTING_KHR state, and EGL_TRUE + is returned. + + When a producer is later connected, if it cannot support the planar + arrangement of the GL texture connection, it will fail with an + EGL_BAD_ACCESS error. + + If any 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 textures will be + "incomplete" until they are connected to a new EGLStream, connected + to a new EGLImage, or deleted. + + The function + + EGLBoolean eglStreamConsumerGLTextureExternalKHR( + EGLDisplay dpy, + EGLStreamKHR stream) + + is equivalent to eglStreamConsumerGLTextureExternalAttribsNV with + <attrib_list> list set to NULL. + +In the remainder of section "3.10.2.1 GL Texture External consumer", +replace all singular references to "texture" with "textures" and make +appropriate grammatical modifications. + +Issues + + 1. This competes with GL_EXT_yuv_target as a means for specifying + how YUV values can be directly accessed by a texture shader + without conversion to RGB. However, that extension also requires + a means to render to YUV surfaces in addition to using them as + textures. Should we go with the approach used here or create a + GL extension which defines a subset GL_EXT_yuv_target? + + RESOLVED: The extension as is serves immediate needs. Conflicts + and overlap with other extensions will be addressed if and when + there is a need to promote to EXT. + + 2. This also contradicts how previous extensions for EXTERNAL GL + textures bind multiplanar surfaces, using separate texture + objects rather than a single virtual texture object which + requires multiple texture units. This allows the application + greater control of the planar arrangement, and the ability to + leave planes unbound, which may reduce overhead for the + producer. But it makes applications less portabile if the + desired arrangement isn't supported. + + RESOLVED: The extension as is serves immediate needs. Conflicts + and overlap with other extensions will be addressed if and when + there is a need to promote to EXT. + +Revision History + + #4 (November 14, 2017) Mozilla Corporation + - Const-qualify attrib_list. + + #3 (August 19, 2015) NVIDIA Corporation + - Added enum values. + - Cleaned up and added contact info for publication. + + #2 (May 6, 2015) NVIDIA Corporation + - Consolidated error codes to make GL interaction simpler. + + #1 (April 15, 2015) NVIDIA Corporation + - Initial draft diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_dma.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_dma.txt new file mode 100644 index 0000000..16716b0 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_dma.txt @@ -0,0 +1,137 @@ +Name + + NV_stream_dma + +Name Strings + + EGL_NV_stream_dma + +Contributors + + Santanu Thangaraj + Daniel Kartch + Arihant Jejani + +Contacts + + Santanu Thangaraj, NVIDIA (sthangaraj 'at' nvidia.com) + Arihant Jejani, NVIDIA (ajejani 'at' nvidia.com) + +Status + + Draft + +Version + + Version 1 - April 15, 2019 + +Number + + 135 + +Extension Type + + EGL display extension + +Dependencies + + Requires EGL_NV_stream_remote extension. + + Requires EGL_NV_stream_cross_system extension. + + Interacts with EGL_NV_stream_socket extensions. + +Overview: + + This extension provides the framework for performing DMA transfers + between opposite ends of a single stream, if there is no shared + memory available between them. + + In case of cross system streams the buffer contents of one end of + the stream is transferred to other end using sockets by + EGL_NV_stream_socket extension. Transferring buffer contents + through sockets is slower compared to DMA transfers. Since DMA + transfers have higher throughput compared to sockets, using + EGL_NV_stream_dma extension, applications can request EGL to + utilize DMA channels to perform buffer copies. + +New types + + None + +New Procedures and functions + + None + +New Tokens + + Accepted as attribute names in eglCreateStreamKHR, + eglCreateStreamAttribKHR, eglQueryStreamKHR, and + eglQueryStreamAttribKHR: + + EGL_STREAM_DMA_NV 0x3371 + EGL_STREAM_DMA_SERVER_NV 0x3372 + +Add to list of failures in section "3.10.1 Creating an EGLStream" in +EGL_KHR stream: + - EGL_BAD_MATCH is generated if the value of EGL_STREAM_DMA_NV is + neither EGL_TRUE nor EGL_FALSE. + - EGL_BAD_MATCH is generated if the value of + EGL_STREAM_DMA_SERVER_NV is not EGL_DONT_CARE or a valid + DMA server identifier as defined by the platform. + +Add to "Table 3.10.4.4 EGLStream Attributes" in EGL_KHR_stream: + + Attribute Read/Write Type Section + ------------------------ ----------- ------ ---------- + EGL_STREAM_DMA_NV io EGLint 3.10.4.x + EGL_STREAM_DMA_SERVER_NV io platform dependent 3.10.4.x+1 + +Add new subsections to the end of section "3.10.4 EGLStream Attributes" +in EGL_KHR_stream: + + 3.10.4.x EGL_STREAM_DMA_NV Attribute + + The EGL_STREAM_DMA_NV attribute may be set when the stream is + created, and indicates whether the DMA channels have to be used to + transfer the buffer contents from producer to consumer. Legal + values are EGL_TRUE or EGL_FALSE. The default value is EGL_FALSE. + + A value of EGL_TRUE indicates that EGL has to use DMA channels to + transfer buffers from producer to consumer. + + If EGL_FALSE is specified, DMA channels will not be utilized for + buffer transfers. + + 3.10.4.x+1 EGL_STREAM_DMA_SERVER_NV Attribute + + The EGL_STREAM_DMA_SERVER_NV attribute is a platform dependent + identifier which may be set when the stream is created and it + indicates the server, which must be contacted to handle DMA + transfers, if that server is not local. Legal values, aside from + EGL_DONT_CARE, are determined by the implementation. The default + value is EGL_DONT_CARE. + +Issues + + 1. What happens when application requests DMA copy using + EGL_STREAM_DMA_NV attribute in eglCreateStreamKHR or + eglCreateStreamAttribKHR API, but the system does not support + access to DMA channels? + + RESOLVED: The functions return EGL_NO_STREAM_KHR and + EGL_BAD_ATTRIBUTE error is set. + + 2. What happens when application requests DMA copy using + EGL_STREAM_DMA_NV attribute in eglCreateStreamKHR or + eglCreateStreamAttribKHR API, and the system supports DMA + channels, but currently none of the channels are available for + use? + + RESOLVED: The functions return EGL_NO_STREAM_KHR and + EGL_BAD_ATTRIBUTE error is set. + +Revision History + + #1 (April 15, 2019) Santanu Thangaraj + - Initial version diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_fifo_next.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_fifo_next.txt new file mode 100644 index 0000000..8199487 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_fifo_next.txt @@ -0,0 +1,105 @@ +Name + + NV_stream_fifo_next + +Name Strings + + EGL_NV_stream_fifo_next + +Contributors + + Daniel Kartch + Miguel A. Vico + +Contacts + + Daniel Kartch, NVIDIA (dkartch 'at' nvidia.com) + +Status + + Draft + +Version + + Version 3 - October 27, 2016 + +Number + + EGL Extension #110 + +Extension Type + + EGL display extension + +Dependencies + + Requires EGL_KHR_stream_fifo + +Overview + + When operating on a FIFO stream, a consumer may need to know the + timestamp associated with the next frame in the stream before + deciding whether to acquire it or reuse the previous frame. In the + case of a FIFO size of 1, the EGL_STREAM_TIME_PRODUCER_KHR attribute + is sufficient to determine this. However, when the size is greater + than 1, there may be frames available with earlier time stamps than + the one most recently inserted by the producer. This extension + enables querying of the next pending frame in a stream. + +New Types + + None + +New Functions + + None + +New Tokens + + Accepted as the <attribute> parameter of eglQueryStreamu64KHR + + EGL_PENDING_FRAME_NV 0x3329 + + Accepted as the <attribute> parameter of eglQueryStreamTimeKHR + + EGL_STREAM_TIME_PENDING_NV 0x332A + +Add to "Table 3.10.4.4 EGLStream Attributes" in the EGL_KHR_stream +extension spec: + + Attribute Read/Write Type Section + -------------------------- ---------- ------------ -------- + EGL_PENDING_FRAME_NV ro EGLuint64KHR 3.10.4.x + EGL_STREAM_TIME_PENDING_NV ro EGLTimeKHR 3.10.4.y + +Add new subsections to section "3.10.4 EGLStream Attributes" in the +EGL_KHR_stream extension spec + + 3.10.4.x EGL_PENDING_FRAME_NV Attribute + + The EGL_PENDING_FRAME_NV attribute indicates the frame number of the + image frame that would be obtained if an acquire operation were + performed at the time of the query. This is the value that + EGL_PRODUCER_FRAME_KHR contained just after this image frame was + inserted into the stream. + + 3.10.4.y EGL_STREAM_TIME_PENDING_NV Attribute + + The EGL_STREAM_TIME_PENDING_NV attribute indicates the timestamp of + the image frame that would be obtained if an acquire operation were + performed at the time of the query. + +Issues + + None + +Revision History + + #3 (October 27, 2016) Daniel Kartch + - Clean up for publication + + #2 (April 2nd, 2015) Miguel A. Vico + - Assigned enumerated values for constants. + + #1 (March 20th, 2015) Daniel Kartch + - Initial draft diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_fifo_synchronous.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_fifo_synchronous.txt new file mode 100644 index 0000000..f34804f --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_fifo_synchronous.txt @@ -0,0 +1,211 @@ +Name + + NV_stream_fifo_synchronous + +Name Strings + + EGL_NV_stream_fifo_synchronous + +Contributors + + Daniel Kartch + Adam Cheney + +Contacts + + Daniel Kartch, NVIDIA (dkartch 'at' nvidia.com) + +Status + + Draft + +Version + + Version 4 - October 27, 2016 + +Number + + EGL Extension #111 + +Extension Type + + EGL display extension + +Dependencies + + Requires EGL_KHR_stream_fifo + +Interactions with EGL_NV_stream_sync and +EGL_KHR_stream_consumer_gltexture + + This extension affects implementations of stream synchronization and + GL texture consumer extensions in that it alters when functions + waiting for new frames will be unblocked. However, as these waits + are still tied to transitions to the + EGL_STREAM_STATE_NEW_FRAME_AVAILALBLE_KHR state, no changes are + required to the wording of those specifications. + +Overview + + On platforms which support asynchronous rendering, frames may be + inserted into a stream by the producer and become available to the + consumer before rendering of the images has completed. When this + happens, commands issued by the consumer which read from the image + must implicitly wait before they can be executed. In many use cases, + this is desirable behavior. Rendering pipelines are kept full, and + frames are created and processed as fast as possible. + + However, in the case of a compositor which is consuming frames from + multiple producers at once, combining them into a single output + image, this can slow the compositor to the frame rate of the slowest + producer. If the application acquires and uses an image from one + producer which requires a long time to finish rendering, it will be + prevented from presenting new frames from faster producers in a + timely fashion. In this case, the compositor would prefer to reuse + an older frame from the slower producer until the new one is ready. + + This could be handled with existing interfaces by the producer + issuing appropriate Finish call before inserting the frame into the + stream. However this requires the producer to have knowledge of the + consumer's use case, and also introduces undesirable bubbles into + the producer's pipeline which will slow it even further. + + This extension allows streams to be configured to defer the + availability of new frames inserted by the producer until they are + ready to be used. The producer proceeds as normal, but the frames + visible to the consumer through query and acquire operations do not + update immediately. + + Interactions of this feature with a stream operating in mailbox mode + would be hard to define. Because newly inserted frames replace + previous unacquired ones, it is possible that the consumer would + never see a completed frame become available. Therefore this feature + is only available for streams operating in FIFO mode. + +New Types + + None + +New Functions + + None + +New Tokens + + Accepted as an attribute name in the <attrib_list> parameter of + eglCreateStreamKHR and a the <attribute> parameter of + eglQueryStreamKHR: + + EGL_STREAM_FIFO_SYNCHRONOUS_NV 0x3336 + +Add new entry to table "3.10.4.4 EGLStream Attributes" in the +EGL_KHR_stream extension + + Attribute Read/Write Type Section + ------------------------------ ---------- ---------- -------- + EGL_STREAM_FIFO_SYNCHRONOUS_NV io EGLBoolean 3.10.4.y + +Add new subsection to section "3.10.4 EGLStream Attributes" in the +EGL_KHR_stream extension + + 3.10.4.y EGL_STREAM_FIFO_SYNCHRONOUS_NV Attribute + + The EGL_STREAM_FIFO_SYNCHRONOUS_NV attribute controls whether frames + inserted by the producer become available to the consumer + synchronously or asynchronously. If set to EGL_FALSE, then when a + present operation for a new frame successfully completes, the state + will immediately become EGL_STREAM_NEW_FRAME_AVAILABLE_KHR, queries + of the most recently produced frame will indicate this frame, and + acquire operations will be able to retrieve this frame. If set to + EGL_TRUE, then until any asynchronous rendering for this frame + completes, the state will not update, any queries of the most + recently produced frame will only indicate the frame whose rendering + most recently completed, and acquire operations will only obtain + older completed frames. + + The default value is EGL_FALSE. If set to EGL_TRUE, the value of + EGL_STREAM_FIFO_LENGTH_KHR must be non-zero, or an EGL_BAD_MATCH + error will be generated. + +Replace first two sentences of section "3.10.4.4 EGL_PRODUCER_FRAME +Attribute" in the EGL_KHR_stream extension + + The EGL_PRODUCER_FRAME_KHR attribute indicates how many image + frames have become available for the consumer to acquire. This is + also known as the "frame number" of the most recent ready frame + (where the first frame inserted has a frame number of 1). In + asynchronous operation, this is the frame most recently inserted by + the producer. In synchronous operation, this is the frame whose + image content generation has most recently finished. + +Replace contents of section "3.10.4.x+3 EGL_STREAM_TIME_PRODUCER_KHR" in +the EGL_KHR_stream_fifo extension + + This indicates the timestamp of the most recent ready frame in the + EGLStream (i.e. frame number EGL_PRODUCER_FRAME_KHR). + +Replace the second through fifth paragraphs of "3.10.5.2 EGLStream operation +in fifo mode" in the EGL_KHR_stream_fifo extension. + + In fifo mode the EGLStream conceptually operates as a fifo. An image + frame in the fifo is considered "ready" if all operations on the + image scheduled prior to its insertion in the stream have completed, + or if the value of EGL_STREAM_FIFO_SYNCHRONOUS_NV is EGL_FALSE. + + 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 image frame at the + tail of the fifo is ready, and is removed from the fifo. If the + state is EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR then the fifo has + no ready image frames 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"). + + When EGL_STREAM_FIFO_SYNCHRONOUS_NV is EGL_FALSE, any consumer + operations which read from the image frame must implicitly wait for + any producer operations used to generate the image contents to + complete. Apart from the assumption that any such operations will + eventually finish, there are no guaranteed bounds on the time + required, and therefore no guaranteed bounds on when the consumer's + operations will complete. In cases where reusing a previous frame is + preferable to unknown latency between the time a consumer acquires a + new frame and the time its processing of that frame is done, + EGL_STREAM_FIFO_SYNCHRONOUS_NV should be set to EGL_TRUE. + + If there is no new ready frame at the tail of the fifo 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, or before any such frame has finished rendering in the case of + synchronous operation). In this case the state of the EGLStream + will be EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR until a new image + frame is ready (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 the producer + is stalled until the fifo is no longer full. When there is at + least one ready frame at the tail of the fifo, the EGLStream state + is EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR. + +Issues + + None + +Revision History + + #4 (October 27, 2016) Daniel Kartch + - Clean up for publication + + #3 (September 30, 2015) Daniel Kartch + - Reserve enum. + + #2 (March 30, 2015) Daniel Kartch + - Fix grammatical and typographical errors. + + #1 (March 27, 2015) Daniel Kartch + - Initial draft diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_flush.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_flush.txt new file mode 100644 index 0000000..0b26508 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_flush.txt @@ -0,0 +1,132 @@ +Name + + NV_stream_flush + +Name Strings + + EGL_NV_stream_flush + +Contributors + + Santanu Thangaraj + Daniel Kartch + +Contacts + + Santanu Thangaraj, NVIDIA (sthangaraj 'at' nvidia.com) + +Status + + Draft + +Version + + Version 3 - April 11, 2018 + +Number + + 127 + +Extension Type + + EGL display extension + +Dependencies + + Requires the EGL_KHR_stream extension. + + Requires either the EGL_KHR_stream_cross_process_fd or + EGL_NV_stream_remote extensions. + + This extension is written based on the wording of version 27 of + the EGL_KHR_stream extension. + +Overview: + + The EGL_KHR_stream_cross_process_fd and EGL_NV_stream_remote + extensions do not guarantee that when the state of the EGLStream + object representing one endpoint of the stream changes, + the state of the other endpoint will immediately reflect + that change. Depending on the implementation, there may be some + latency in the propagation of state changes. + + This latency will not affect any applications which rely solely + on the stream itself for communication. State changes made on + one side will eventually be visible on the other side, + and can then be responded to. + + This only affects applications which use some additional means of + communication outside of the stream itself, which may encounter + race conditions. In particular, if an application inserts a frame + into a stream, then sends a message to the other side indicating + that the frame is ready, the other side may encounter an error if + it tries to acquire the frame and it is not yet available. + + One solution is to force all operations that change state of one + endpoint to behave synchronously, and not return until the change + is reflected on the other endpoint. However this adds undesirable + delays for the majority of applications and operations where such + synchronization is not required. This extension instead provides + a means for applications to explicitly invoke such + synchronization only where required. + +New types + + None + +New Procedures and functions + + EGLBoolean eglStreamFlushNV( + EGLDisplay dpy, + EGLStreamKHR stream); + +New Tokens + + None + +Add a new subsection "3.10.x EGLStream flush" at the end of section +"3.10 EGLStreams" in EGL_KHR_stream extension. + + The command + + EGLBoolean eglStreamFlushNV( + EGLDisplay dpy, + EGLStreamKHR stream); + + When called with either producer or consumer endpoint of the + stream, will block until any state changes made to this endpoint + prior to the call are visible on the EGLStream object of the other + endpoint. + + On success, EGL_TRUE will be returned. On failure, EGL_FALSE will + be returned and an error will be generated. + + - EGL_BAD_STREAM_KHR is generated if <stream> is not a valid + EGLStream. + + - EGL_BAD_STATE_KHR is generated if <stream> is in + EGL_STREAM_STATE_DISCONNECTED_KHR state. + + - EGL_BAD_DISPLAY is generated if <dpy> is not a valid + EGLDisplay. + + - EGL_NOT_INITIALIZED is generated if <dpy> is not initialized. + +Issues + + 1. When both producer and consumer are connected to a single + EGLStream object, what happens when eglStreamFlushNV is called? + + RESOLVED: The function returns without any blocking. + +Revision History + + #3 (April 11, 2018) Jon Leech + - Add missing NV suffix to eglStreamFlushNV + + #2 (April 2, 2018) Santanu Thangaraj + - Update based on comments from Daniel Kartch + - General cleanup + + #1 (March 26, 2018) Santanu Thangaraj + - Initial draft diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_frame_limits.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_frame_limits.txt new file mode 100644 index 0000000..75c0e49 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_frame_limits.txt @@ -0,0 +1,152 @@ +Name + + NV_stream_frame_limits + +Name Strings + + EGL_NV_stream_frame_limits + +Contributors + + Daniel Kartch + +Contacts + + Daniel Kartch, NVIDIA (dkartch 'at' nvidia.com) + +Status + + Draft + +Version + + Version 4 - October 27, 2016 + +Number + + EGL Extension #113 + +Dependencies + + Requires EGL_KHR_stream + + Interacts with EGL_EXT_stream_consumer_egloutput + +Overview + + Some stream consumers may allow more than one frame to be acquired + at a time, so that applications can operate on sequences of images + rather than individual images. This in turn may lead to producers + allocating additional buffers to keep the fifo full while fulfilling + the consumer's needs. Applications may wish to limit the resources + allocated for a given stream, and some stream implementations may be + able to operate more efficiently if they know in advance how many + buffers will be used. + + This extension defines two new stream attributes which provide hints + as to how many frames the application will require, allowing the + implementation to plan accordingly. + +New functions + + None + +New tokens + + Accepted as an attribute name in the <attrib_list> parameter of + eglCreateStreamKHR and as the <attribute> parameter of + eglQueryStreamKHR. + + EGL_PRODUCER_MAX_FRAME_HINT_NV 0x3337 + EGL_CONSUMER_MAX_FRAME_HINT_NV 0x3338 + + +Add to "Table 3.10.4.4 EGLStream Attributes" + + Attribute Read/Write Type Section + ------------------------------ ---------- ------ ---------- + EGL_PRODUCER_MAX_FRAME_HINT_NV io EGLint 3.10.4.x + EGL_CONSUMER_MAX_FRAME_HINT_NV io EGLint 3.10.4.x+1 + +Add new subsections to section "3.10.4 EGLStream Attributes" + + 3.10.4.x EGL_PRODUCER_MAX_FRAME_HINT_NV Attribute + + The EGL_PRODUCER_MAX_FRAME_HINT_NV attribute indicates a limit on how + many outstanding frames the producer application intends to have at + any given time. This includes all frames currently being generated, + waiting in in the stream's mailbox or FIFO, and held by the consumer. + Its default value is EGL_DONT_CARE. + + The implementation may make use of this hint to determine how many + buffers or other resources to allocate for the stream. It is not + necessarily an error for an application to attempt to insert more + than this many frames into the stream at once. However, exceeding + available resources may cause a producer to block or return an error, + as per its specification. + + 3.10.4.x+1 EGL_CONSUMER_MAX_FRAME_HINT_NV Attribute + + The EGL_CONSUMER_MAX_FRAME_HINT_NV attribute indicates a limit on how + many frames the consumer application intends to acquire at the same + time. Its default value EGL_DONT_CARE. + + The implementation may make use of this hint to determine how many + buffers or other resources to allocate for the stream. It is not + necessarily an error for an application to attempt to acquire more + than this many frames at once. However, exceeding available resources + may cause the consumer or producer to block or return an error, as per + their specifications. + +Add to the description of eglStreamConsumerOutputEXT in the +EGL_KHR_stream_consumer_egloutput extension + + When the producer generates frames faster than the output device can + display them, <stream>'s EGL_CONSUMER_MAX_FRAME_HINT_NV attribute can + be used to throttle the output. No more than the specified number of + frames will be scheduled for display at a time. If specified, the value + should be set to at least 2, to allow one frame to be displayed while + another is acquired and scheduled for display. + +Issues + + 1. Is a generic stream extension really necessary, or can such + limits instead be imposed in the producer and consumer + interfaces? + + RESOLVED: Yes, it is necessary. There are several use cases + where an application may need to impose limits and cannot do so + through the producer and consumer interfaces: + a) The producer and client interfaces are already published and + do not allow room for extension to impose limits. + b) The stream is cross-process, and one process needs to impose + limits on the endpoint provided by the other process. + In addition, a common method for imposing such limits simplifies + programming of large application suites which make use of + multiple types of producers and consumers, and allows the limits + on producer and consumer endpoints to be set to compatible + values. + + 2. Should the attributes be hints or hard limits? + + RESOLVED: Hints. The variety of possible producers and consumers + makes it difficult to specify what the behavior should be if a + hard limit is exceeded. The goal here is to allow the application + to coordinate its resource requirements with the implementation. + If it fails to limit itself to the hinted values, we allow + producers or consumers to block or fail as appropriate for their + interfaces, but do not require it. + +Revision History + + #4 (October 27, 2016) Daniel Kartch + - Clean up for publication + + #3 (September 14, 2106) Daniel Kartch + - Switched from hard limits to hints + + #2 (January 8, 2016) Daniel Kartch + - Assigned enum values + + #1 (October 30, 2015) Daniel Kartch + - Initial draft diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_metadata.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_metadata.txt new file mode 100644 index 0000000..d5a613e --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_metadata.txt @@ -0,0 +1,335 @@ +Name + + NV_stream_metadata + +Name Strings + + EGL_NV_stream_metadata + +Contributors + + Daniel Kartch + Gajanan Bhat + Laszlo Weber + Lawrence Ibarria + Miguel A. Vico + +Contacts + + Daniel Kartch, NVIDIA (dkartch 'at' nvidia 'dot' com) + +Status + + Complete + +Version + + Version 8 - July 31, 2015 + +Number + + EGL Extension #93 + + +Extension Type + + EGL display extension + +Dependencies + + Requires EGL_KHR_stream + + Interacts with EGL_EXT_device_base + +Overview + + Application suites which make use of streams to transmit images may + need to communicate additional data between the producer and + consumer, synchronized with the frame updates. This data may change + infrequently, such as a movie title and track number to be displayed + to the user, or every frame, such as a focal length and exposure + time used to process the image. Transmitting this data outside the + scope of the stream may be inconvenient, particularly in the case of + cross-process streams. But the nature of the data is highly + application-dependent, so it is not feasible for an EGL + implementation to define specific extensions for a broad range of + application data. + + This extension provides a means for an application (or application + suite in the cross-process case) to associate arbitrary metadata + with a stream. Multiple metadata fields are available, allowing them + to be updated and used independently by separate subcomponents of + producers and consumers, respectively. The format of the data is + determined by the application, which is responsible for writing and + reading it correctly. + +New Types + + None + +New Functions + + EGLBoolean eglQueryDisplayAttribNV( + EGLDisplay dpy, + EGLint attribute, + EGLAttrib* value); + + EGLBoolean eglSetStreamMetadataNV( + EGLDisplay dpy, + EGLStreamKHR stream, + EGLint n, + EGLint offset, + EGLint size, + const void* data); + + EGLBoolean eglQueryStreamMetadataNV( + EGLDisplay dpy, + EGLStreamKHR stream, + EGLenum name, + EGLint n, + EGLint offset, + EGLint size, + void* data); + +New Tokens + + Accepted as <attribute> by eglQueryDisplayAttribNV: + + EGL_MAX_STREAM_METADATA_BLOCKS_NV 0x3250 + EGL_MAX_STREAM_METADATA_BLOCK_SIZE_NV 0x3251 + EGL_MAX_STREAM_METADATA_TOTAL_SIZE_NV 0x3252 + + Accepted as <name> by eglQueryStreamMetatdataNV: + + EGL_PRODUCER_METADATA_NV 0x3253 + EGL_CONSUMER_METADATA_NV 0x3254 + EGL_PENDING_METADATA_NV 0x3328 + + Accepted in <attrib_list> by eglCreateStreamKHR and as <attribute> + by eglQueryStreamKHR: + + EGL_METADATA0_SIZE_NV 0x3255 + EGL_METADATA1_SIZE_NV 0x3256 + EGL_METADATA2_SIZE_NV 0x3257 + EGL_METADATA3_SIZE_NV 0x3258 + + EGL_METADATA0_TYPE_NV 0x3259 + EGL_METADATA1_TYPE_NV 0x325A + EGL_METADATA2_TYPE_NV 0x325B + EGL_METADATA3_TYPE_NV 0x325C + + +Add to section "3.3 EGL Queries" + + To query attributes of an initialized display, call + + EGLBoolean eglQueryDisplayAttribNV( + EGLDisplay dpy, + EGLint attribute, + EGLAttrib* value) + + On success, EGL_TRUE is returned, and the value associated with + attribute <name> is returned in <value>. + + If <name> is EGL_MAX_STREAM_METADATA_BLOCKS_NV, the total number + of independent metadata blocks supported by each stream is returned. + If <name> is EGL_MAX_STREAM_METADATA_BLOCK_SIZE_NV, the maximum size + supported for an individual metadata block is returned. If <name> is + EGL_MAX_STREAM_METADATA_TOTAL_SIZE_NV, the maximum combined size of + all metadata blocks supported by a single stream is returned. + + On failure, EGL_FALSE is returned. An EGL_BAD_DISPLAY error is + generated if <dpy> is not a valid initialized display. An + EGL_BAD_ATTRIBUTE error is generated if <name> is not a valid + attribute name. + +If EGL_EXT_device_base is present, eglQueryDisplayAttribNV is equivalent +to eglQueryDisplayAttribEXT, and calls to either will return the same +values. + +Add to table "3.10.4.4 EGLStream Attributes" in EGL_KHR_stream + + Attribute Read/Write Type Section + ------------------------ ---------- ------ ---------- + EGL_METADATA<n>_SIZE_NV io EGLint 3.10.4.x + EGL_METADATA<n>_TYPE_NV io EGLint 3.10.4.x+1 + +Add new subsections to section "3.10.4 EGLStream Attributes" of +EGL_KHR_stream + + 3.10.4.x EGL_METADATA<n>_SIZE_NV + + The EGL_METADATA<n>_SIZE_NV attribute indicates the size of the + <n>th metadata block associated with a stream. If <n> is not less + than the value of EGL_MAX_STREAM_METADATA_BLOCKS_NV for the parent + EGLDisplay, the attribute is treated as unknown. + + These attributes may only be set when the stream is created. The + default value is 0. The value may not exceed that of + EGL_MAX_STREAM_METADATA_BLOCK_SIZE_NV for the parent EGLDisplay. + Furthermore, the total size of all metadata blocks may not exceed + the value of EGL_MAX_STREAM_METADATA_TOTAL_SIZE_NV. If either of + these restrictions are exceeded, an EGL_BAD_PARAMETER error is + generated. + + 3.10.4.x+1 EGL_METADATA<n>_TYPE_NV + + The EGL_METADATA<n>_TYPE_NV attribute indicates an optional + application-defined type associated with the stream's <n>th metadata + block. If <n> is not less than the value of + EGL_MAX_STREAM_METADATA_BLOCKS_NV for the parent EGLDisplay, the + attribute is treated as unknown. + + These attributes may only be set when the stream is created. The + default value is 0. It is not required that a type be provided for + every metadata block for which a size has been specified. These may + be used to help separate application components coordinate their use + of the stream's metadata blocks. + +Add new section to "3.10 EGLStreams" of EGL_KHR_stream + + 3.10.y EGLStream metadata + + An application may associate arbitrary blocks of additional data + with the stream, to be updated in sync with the frames. The contents + and format of these data blocks are left to the application, subject + to size restrictions imposed by the implementation. The application + must specify the sizes of its metadata blocks at the time the stream + is created. The contents may be completely or partially modified + every frame or less frequently, as the application chooses. When a + new frame is inserted into the stream, a snapshot of the current + metadata contents are associated with the frame, and may then be + queried from the stream. + + The contents of all metadata blocks of non-zero size are initialized + to zeroes. To modify the contents of a portion of a metadata block, + call + + EGLBoolean eglSetStreamMetadataNV( + EGLDisplay dpy, + EGLStreamKHR stream, + EGLint n, + EGLint offset, + EGLint size, + const void* data) + + On success, EGL_TRUE is returned and the first <size> bytes pointed + to by <data> will be copied to the <n>th metadata block of <stream>, + starting at <offset> bytes from the beginning of the block. This + data will be associated with all subsequent frames inserted into the + stream until the contents are next modified. + + On failure, EGL_FALSE is returned + - An EGL_BAD_DISPLAY error is generated if <dpy> is not a valid + display. + - An EGL_BAD_STREAM_KHR error is generated if <stream> is not a + valid stream associated with <dpy>. + - An EGL_BAD_STATE_KHR error is generated if the state of + <stream> is not EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR, + EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR, or + EGL_STREAM_STATE_EMPTY_KHR. + - An EGL_BAD_ACCESS error is generated if the producer and + consumer endpoints of the stream are represented by separate + EGLStream objects, and the producer is not attached to + <stream>. + - An EGL_BAD_PARAMETER error is generated if <n> is negative or + is equal to or greather than the value of + EGL_MAX_STREAM_METADATA_BLOCKS_NV for <dpy>. + - An EGL_BAD_PARAMETER error is generated if <offset> or <size> + are negative, or if <offset>+<size> is greater than the value + of EGL_METADATA<n>_SIZE_NV for <stream>. + + If <data> does not point to valid readable memory of at least <size> + bytes, undefined behavior will result. If the value of <size> is + zero, no error will occur, but the function will have no effect. + + To query the contents of a metadata block for a frame, call + + EGLBoolean eglQueryStreamMetadataNV( + EGLDisplay dpy, + EGLStreamKHR stream, + EGLenum name, + EGLint n, + EGLint offset, + EGLint size, + void* data) + + On success, EGL_TRUE is returned and <size> bytes starting from the + <offset>th byte of the <n>th metadata block of <stream> will be + copied into the memory pointed to by <data>. If <name> is + EGL_PRODUCER_METADATA_NV, the metadata will be taken from the frame + most recently inserted into the stream by the producer. If <name> is + EGL_CONSUMER_METADATA_NV, the metadata will be taken from the frame + most recently acquired by the consumer. If <name> is + EGL_PENDING_METADATA_NV, the metadata will be taken from the frame + which would be obtained if an acquire operation were performed at + the time of the query. + + On failure, EGL_FALSE is returned + - An EGL_BAD_DISPLAY error is generated if <dpy> is not a valid + display. + - An EGL_BAD_STREAM_KHR error is generated if <stream> is not a + valid stream associated with <dpy>. + - An EGL_BAD_STATE_KHR error is generated if the state of + <stream> is not EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR or + EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR. + - An EGL_BAD_ATTRIBUTE error is generated if <name> is not + EGL_PRODUCER_METADATA_NV, EGL_CONSUMER_METADATA_NV, or + EGL_PENDING_METADATA_NV. + - An EGL_BAD_PARAMETER error is generated if <n> is negative or + is equal to or greater than the value of + EGL_MAX_STREAM_METADATA_BLOCKS_NV for <dpy>. + - An EGL_BAD_PARAMETER error is generated if <offset> or <size> + are negative, or if <offset>+<size> is greater than the value + of EGL_METADATA<n>_SIZE_NV for <stream>. + + If <data> does not point to valid writeable memory of at least + <size> bytes, undefined behavior will result. If the value of <size> + is zero, no error will occur, but the function will have no effect. + +Issues + + 1. What happens if multiple calls are made to + eglSetStreamMetadataNV without presenting a new frame? + + RESOLVED: If the calls specify overlapping ranges of the same + metadata block, the earlier data in the overlapped portion is + overwritten. Only the most recent values are associated with + the next frame when it is inserted into the stream. + + 2. What happens if multiple frames are presented without calling + eglSetStreamMetadataNV? + + RESOLVED: The most recently provided data is reused. + +Revision History + + #8 (July 31, 2015) Daniel Kartch + - Cleaned up and added contact info for publication. + + #7 (April 2, 2015) Miguel A. Vico + - Assigned enumerated value for metadata of pending frame. + + #6 (March 20, 2015) Daniel Kartch + - Add query for metadata of pending frame. + + #5 (January 15, 2015) Daniel Kartch + - Add paragraph of supported attributes to description of + eglQueryDisplayAttribNV. + - Added/updated error conditions to set/query functions. + - Fixed errors in prototypes. + + #4 (January 6, 2015) Daniel Kartch + - Fixed errors in prototypes. + - Added enum values. + + #3 (December 12, 2014) Daniel Kartch + - Clarified language on how metadata becomes associated with + frames inserted into the stream. + - Fixed typos. + + #2 (December 12, 2014) Daniel Kartch + - Added offset and size to Set and Query functions. + + #1 (December 11, 2014) Daniel Kartch + - Initial draft diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_origin.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_origin.txt new file mode 100644 index 0000000..5f56646 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_origin.txt @@ -0,0 +1,298 @@ +Name + + NV_stream_origin + +Name Strings + + EGL_NV_stream_origin + +Contributors + + Miguel A. Vico + James Jones + Daniel Kartch + +Contacts + + Miguel A. Vico (mvicomoya 'AT' nvidia.com) + +Status + + Complete. + +Version + + Version 5 - May 20, 2019 + +Number + + 134 + +Extension Type + + EGL display extension + +Dependencies + + Requires the EGL_KHR_stream extension. + + This extension is written based on the wording of version 26 of the + EGL_KHR_stream extension. + +Overview + + EGL does not define a frame orientation. However, window systems or + rendering APIs might. + + Ideally, when using EGL streams, frame orientation is agreed upon by + both the connected consumer and producer and appropriate handling is + performed within EGL to satisfy both endpoints needs. Thus, + applications will rarely have to worry about frame orientation. + + However, in some cases consumer applications such as compositors + might still need to access the frame data as provided by the + consumer. Hence, they need to know what orientation was set for the + stream frames. This will allow applications to adjust the way they + access the frame data. + + Similarly, producer applications might need to adjust how rendering + commands are issued depending on the orientation set for the stream + frames. + + This extension provides new attributes to allow EGL stream users to + query frame orientation and whether it is handled automatically by + the producer or consumer endpoints so that clients are not required + to take further actions. + +New Functions + + None. + +New Tokens + + Accepted as the <attribute> parameter of eglQueryStreamKHR and + eglQueryStreamAttribKHR: + + EGL_STREAM_FRAME_ORIGIN_X_NV 0x3366 + EGL_STREAM_FRAME_ORIGIN_Y_NV 0x3367 + EGL_STREAM_FRAME_MAJOR_AXIS_NV 0x3368 + + EGL_CONSUMER_AUTO_ORIENTATION_NV 0x3369 + EGL_PRODUCER_AUTO_ORIENTATION_NV 0x336A + + Returned by eglQueryStreamKHR and eglQueryStreamAttribKHR when + attribute is EGL_STREAM_FRAME_ORIGIN_X_NV: + + EGL_LEFT_NV 0x336B + EGL_RIGHT_NV 0x336C + + Returned by eglQueryStreamKHR and eglQueryStreamAttribKHR when + attribute is EGL_STREAM_FRAME_ORIGIN_Y_NV: + + EGL_TOP_NV 0x336D + EGL_BOTTOM_NV 0x336E + + Returned by eglQueryStreamKHR and eglQueryStreamAttribKHR when + attribute is EGL_STREAM_FRAME_MAJOR_AXIS_NV: + + EGL_X_AXIS_NV 0x336F + EGL_Y_AXIS_NV 0x3370 + +Add to table "3.10.4.4 EGLStream Attributes" + + Attribute Read/Write Type Section + --------------------------------- ---------- ---------- ----------- + EGL_STREAM_FRAME_ORIGIN_X_NV ro EGLint 3.10.4.x + EGL_STREAM_FRAME_ORIGIN_Y_NV ro EGLint 3.10.4.x+1 + EGL_STREAM_FRAME_MAJOR_AXIS_NV ro EGLint 3.10.4.x+2 + EGL_CONSUMER_AUTO_ORIENTATION_NV ro EGLBoolean 3.10.4.x+3 + EGL_PRODUCER_AUTO_ORIENTATION_NV ro EGLBoolean 3.10.4.x+4 + +Add new subsections to the end of section "3.10.4 EGLStream Attributes" +in EGL_KHR_stream: + + 3.10.4.x EGL_STREAM_FRAME_ORIGIN_X_NV + + EGL_STREAM_FRAME_ORIGIN_X_NV is a read-only attribute that + indicates the position on the X axis of the origin relative to the + stream images surface as agreed upon by consumer and producer. + + The relative position on X may be one of the following: + + - EGL_LEFT_NV - Coordinates on the X axis will be 0 on the left + border and increase towards the right border until <frame + width> is reached. + + - EGL_RIGHT_NV - Coordinates on the X axis will be <frame width> + on the left border and decrease towards the right border until + 0 is reached. + + - EGL_DONT_CARE - No orientation on the X axis was set by the EGL + implementation. Applications must coordinate what they are + doing. + + EGL_STREAM_FRAME_ORIGIN_X_NV will not be defined until a consumer + and a producer are connected to the stream. Querying it before that + will generate an EGL_BAD_STATE_KHR error. + + + 3.10.4.x+1 EGL_STREAM_FRAME_ORIGIN_Y_NV + + EGL_STREAM_FRAME_ORIGIN_Y_NV is a read-only attribute that + indicates the position on the Y axis of the origin relative to the + stream images surface as agreed upon by consumer and producer. + + The relative position on Y may be one of the following: + + - EGL_TOP_NV - Coordinates on the Y axis will be 0 on the top + border and increase towards the bottom border until <frame + height> is reached. + + - EGL_BOTTOM_NV - Coordinates on the Y axis will be <frame + height> on the top border and decrease towards the bottom + border until 0 is reached. + + - EGL_DONT_CARE - No orientation on the Y axis was set by the EGL + implementation. Applications must coordinate what they are + doing. + + EGL_STREAM_FRAME_ORIGIN_Y_NV will not be defined until a consumer + and a producer are connected to the stream. Querying it before that + will generate an EGL_BAD_STATE_KHR error. + + + 3.10.4.x+2 EGL_STREAM_FRAME_MAJOR_AXIS_NV + + EGL_STREAM_FRAME_MAJOR_AXIS_NV is a read-only attribute that + indicates whether the stream images are X-major or Y-major. + + The major axis may be one of the following: + + - EGL_X_AXIS_NV - Frames are laid out such that consecutive + pixels with same Y coordinate reside next to each other in + memory. + + - EGL_Y_AXIS_NV - Frames are laid out such that consecutive + pixels with same X coordinate reside next to each other in + memory. + + - EGL_DONT_CARE - No major axis was set by the EGL + implementation. Applications must coordinate what they are + doing. + + EGL_STREAM_FRAME_MAJOR_AXIS_NV will not be defined until a consumer + and a producer are connected to the stream. Querying it before that + will generate an EGL_BAD_STATE_KHR error. + + + 3.10.4.x+3 EGL_CONSUMER_AUTO_ORIENTATION_NV + + EGL_CONSUMER_AUTO_ORIENTATION_NV is a read-only attribute that + indicates whether the consumer endpoint will handle frame orientation + automatically so that the consumer application is not required to + take further actions. + + The following values can be returned: + + - EGL_TRUE - The consumer application can read frames as normal. + The consumer will flip images as needed if the expected + orientation does not match. + + - EGL_FALSE - The consumer application is expected to query the + frame orientation and process images accordingly if it does not + match with the expected orientation. + + EGL_CONSUMER_AUTO_ORIENTATION_NV will not be defined until a consumer + and a producer are connected to the stream. Querying it before that + will generate an EGL_BAD_STATE_KHR error. + + + 3.10.4.x+4 EGL_PRODUCER_AUTO_ORIENTATION_NV + + EGL_PRODUCER_AUTO_ORIENTATION_NV is a read-only attribute that + indicates whether the producer endpoint will handle frame orientation + automatically so that the producer application is not required to + take further actions. + + The following values can be returned: + + - EGL_TRUE - The producer application can generate frames as + normal. The producer will flip images as needed if the + expected orientation does not match. + + - EGL_FALSE - The producer application is expected to query the + frame orientation and generate images accordingly if it does + not match with the expected orientation. + + EGL_PRODUCER_AUTO_ORIENTATION_NV will not be defined until a consumer + and a producer are connected to the stream. Querying it before that + will generate an EGL_BAD_STATE_KHR error. + + +Add to the error list in section "3.10.4.2 Querying EGLStream +Attributes": + + - EGL_BAD_STATE_KHR is generated if <attribute> is any of + EGL_STREAM_FRAME_ORIGIN_X_NV, EGL_STREAM_FRAME_ORIGIN_Y_NV, + EGL_STREAM_FRAME_MAJOR_AXIS_NV, EGL_CONSUMER_AUTO_ORIENTATION_NV, + or EGL_PRODUCER_AUTO_ORIENTATION_NV and the stream is in + EGL_STREAM_STATE_CREATED_KHR or EGL_STREAM_STATE_CONNECTING_KHR + state. + +Issues + + 1. Frame orientation is only needed for and relevant to specific + consumers and producers. What should the query of either + EGL_STREAM_FRAME_ORIGIN_X_NV, EGL_STREAM_FRAME_ORIGIN_Y_NV, + EGL_STREAM_FRAME_MAJOR_AXIS_NV when consumers or producers that do + not define a frame orientation are connected to the stream? + + RESOLVED: If the consumer or producer connected to the stream does + not define a frame orientation, the queries will return + EGL_DONT_CARE and applications must coordinate what they do. + + 2. What should the query return when the connected consumer or + producer defines a frame orientation but can actually handle any? + + RESOLVED: Quering EGL_STREAM_FRAME_ORIGIN_X_NV, + EGL_STREAM_FRAME_ORIGIN_Y_NV, or EGL_STREAM_FRAME_MAJOR_AXIS_NV + will return the default frame orientation. + + Querying EGL_CONSUMER_AUTO_ORIENTATION_NV or + EGL_PRODUCER_AUTO_ORIENTATION_NV will return whether the consumer + or producer can handle any orientation automatically so that + applications do not need to worry about it. + + If querying EGL_CONSUMER_AUTO_ORIENTATION_NV or + EGL_PRODUCER_AUTO_ORIENTATION_NV returns EGL_FALSE, the + corresponding application is expected to query the frame + orientation and take the appropriate action if that does not match + the expected orientation. + +Revision History + + #5 (May 20th, 2019) Miguel A. Vico + - Allocate extension number + - Mark extension as complete + + #4 (January 30th, 2019) Miguel A. Vico + - Allocate values for added enumerants + - Minor fixes to the major axis attribute description + + #3 (October 8th, 2018) Miguel A. Vico + - Collapsed producer and consumer orientation attributes + - Added major axis attribute to fully define orientation + - Added two new attributes to indicate whether the producer or + consumer can handle orientation automatically. + - Rewritten issue #1 + - Added issue #2 and its resolution + - Overall spec changes to reflect the above points + + #2 (August 19th, 2016) Miguel A. Vico + - Rename newly added attributes as consumer and producer + attributes + - Added both issue #1 and its resolution + - Overall spec changes to reflect the above points + + #1 (August 1st, 2016) Miguel A. Vico + - Initial draft diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_remote.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_remote.txt new file mode 100644 index 0000000..c8eb464 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_remote.txt @@ -0,0 +1,472 @@ +Name + + NV_stream_remote + NV_stream_cross_object + NV_stream_cross_display + NV_stream_cross_process + NV_stream_cross_partition + NV_stream_cross_system + +Name Strings + + EGL_NV_stream_remote + +Contributors + + Daniel Kartch + Bogdan Naodovic + James Jones + Zander Clucas + +Contacts + + Daniel Kartch, NVIDIA (dkartch 'at' nvidia.com) + +Status + + Draft + +Version + + Version 4 - June 01, 2016 + +Number + + EGL Extension #114 + +Extension Type + + EGL display extension + +Dependencies + + Requires EGL_KHR_stream + + Interacts with EGL_KHR_stream_cross_process_fd + + All EGL_NV_stream_cross_* extensions require EGL_NV_stream_remote, + but are independent of each other. + +Overview + + This extension provides a generic framework for establishing stream + connections when the producer and consumer endpoints are not + associated with the same EGLStream object. The cross-process streams + allowed by the EGL_KHR_stream_cross_process_fd extension are one + example of such a connection. Other potential examples include + streams between objects associated with different EGLDisplays in a + single process, streams between processes residing in separate + virtual machine partitions on a single system, or streams between + entirely separate systems connected via the internet. + + The approach used by EGL_KHR_stream_cross_process_fd has several + drawbacks: + - It creates a new pair of stream creation and query functions + which are specific to both the type of stream and the method + used for communicating the stream's identity. Extending this + methodology would require new pairs of functions for every new + type of stream connection. + - It allows creation of the connected stream objects without any + indication of which side will be the consumer and which will be + the producer. It even allows, although this was probably not + intended, a cross-process stream to be established, but have + both producer and consumer exist in the same process, with the + other process acting as a voyeur that can observe state and + perhaps modify attributes, but not operate on frames. + - The use of file descriptors generated by EGL in one process + and accessed by EGL in another to establish communication has + potential security flaws, and may not be available at all on + some real-time operating systems. + + Rather than implement new connection types using this model, we + propose a more generic approach that does not require a + proliferation of new interfaces and avoids any ambiguities in how + the stream will be used. These extensions can coexist with + EGL_KHR_stream_cross_process_fd, but allow for more control of + stream communication by the applications. + + These extensions provide the framework with which arbitrary stream + object pairs can be established, but by themselves are insufficient + to create such pairs. In addition, a separate extension must be + used to determine the protocol by which the two objects will + communicate. See for example the EGL_NV_stream_socket extension. + + Several optional types of separate stream objects are defined, + with successive levels of remoteness. It should be assumed that + a more remote type will be less efficient in transfering images, + and therefore applications should choose the least remote type + available that is compatible with their use cases. + +New Types + + None + +New Functions + + None + +New Tokens + + Returned by eglQueryStreamKHR and eglQueryStreamAttribKHR when + attribute is EGL_STREAM_STATE_KHR: + + EGL_STREAM_STATE_INITIALIZING_NV 0x3240 + + Accepted as attribute names in eglCreateStreamKHR, + eglCreateStreamAttribKHR, eglQueryStreamKHR, and + eglQueryStreamAttribKHR: + + EGL_STREAM_TYPE_NV 0x3241 + EGL_STREAM_PROTOCOL_NV 0x3242 + EGL_STREAM_ENDPOINT_NV 0x3243 + + Accepted by eglCreateStreamKHR and eglCreateStreamAttribKHR, and + returned by eglQueryStreamKHR and eglQueryStreamAttribKHR, as value + when attribute is EGL_STREAM_TYPE_NV, EGL_STREAM_PROTOCOL_NV or + EGL_STREAM_ENDPOINT_NV: + + EGL_STREAM_LOCAL_NV 0x3244 + + When EGL_NV_stream_cross_object is present, accepted by + eglCreateStreamKHR and eglCreateStreamAttribKHR and returned by + eglQueryStreamKHR and eglQueryStreamAttribKHR as value for + attribute EGL_STREAM_TYPE_NV: + + EGL_STREAM_CROSS_OBJECT_NV 0x334D + + When EGL_NV_stream_cross_display is present, accepted by + eglCreateStreamKHR and eglCreateStreamAttribKHR and returned by + eglQueryStreamKHR and eglQueryStreamAttribKHR as value for + attribute EGL_STREAM_TYPE_NV: + + EGL_STREAM_CROSS_DISPLAY_NV 0x334E + + When EGL_NV_stream_cross_process is present, accepted as + value for attribute EGL_STREAM_TYPE_NV by eglCreateStreamKHR + and eglCreateStreamAttribKHR. When either + EGL_NV_stream_cross_process or EGL_KHR_stream_cross_process_fd + is present, returned by eglQueryStreamKHR and + eglQueryStreamAttribKHR for attribute EGL_STREAM_TYPE_NV: + + EGL_STREAM_CROSS_PROCESS_NV 0x3245 + + When EGL_NV_stream_cross_partition is present, accepted by + eglCreateStreamKHR and eglCreateStreamAttribKHR and returned by + eglQueryStreamKHR and eglQueryStreamAttribKHR as value for + attribute EGL_STREAM_TYPE_NV: + + EGL_STREAM_CROSS_PARTITION_NV 0x323F + + When EGL_NV_stream_cross_system is present, accepted by + eglCreateStreamKHR and eglCreateStreamAttribKHR and returned by + eglQueryStreamKHR and eglQueryStreamAttribKHR as value for + attribute EGL_STREAM_TYPE_NV: + + EGL_STREAM_CROSS_SYSTEM_NV 0x334F + + If EGL_KHR_stream_cross_process_fd is present, returned by + eglQueryStreamKHR and eglQueryStreamAttribKHR when attribute is + EGL_STREAM_PROTOCOL_NV: + + EGL_STREAM_PROTOCOL_FD_NV 0x3246 + + Accepted by eglCreateStreamKHR and eglCreateStreamAttribKHR, and + returned by eglQueryStreamKHR and eglQueryStreamAttribKHR when + attribute is EGL_STREAM_ENDPOINT_NV: + + EGL_STREAM_PRODUCER_NV 0x3247 + EGL_STREAM_CONSUMER_NV 0x3248 + +Add to "Glossary" of EGL_KHR_stream: + + Local stream + A stream implemented with both consumer and producer attached to a + single EGLStream object. + + Remote stream + A stream implemented with two EGLStream objects that communicate + with each other, with the consumer attached to one object and the + producer attached to the other. + +Add to section "3.10.1 Creating an EGLStream" in EGL_KHR_stream: + + If a remote EGLStream is created, as described in section "3.10.5.x + Remote streams", and is paired with an EGLStream object which has + conflicting values for some attributes, creation will succeed, but + the stream will enter state EGL_STREAM_STATE_DISCONNECTED_KHR once + communication is established. + +Add to list of failures in section "3.10.1 Creating an EGLStream" in +EGL_KHR stream: + + - EGL_BAD_MATCH is generated if the value of any one of the + EGL_STREAM_TYPE_NV, EGL_STREAM_PROTOCOL_NV, or + EGL_STREAM_ENDPOINT_NV attributes is EGL_STREAM_LOCAL_NV and + any other of these attributes is neither EGL_STREAM_LOCAL_NV + nor EGL_DONT_CARE. + +Add to section "3.10.2 Connecting an EGLStream to a consumer" in +EGL_KHR_stream: + + Any function which connects a consumer to an EGLStream will fail and + generate an EGL_BAD_ACCESS error if the value of the EGLStream's + EGL_STREAM_ENDPOINT_NV attribute is EGL_STREAM_PRODUCER_NV. + +Add to section "3.10.3 Connecting an EGLStream to a producer" in +EGL_KHR_stream: + + Any function which connects a producer to an EGLStream will fail and + generate an EGL_BAD_ACCESS error if the value of the EGLStream's + EGL_STREAM_ENDPOINT_NV attribute is EGL_STREAM_CONSUMER_NV. + +Add to "Table 3.10.4.4 EGLStream Attributes" in EGL_KHR_stream: + + Attribute Read/Write Type Section + -------------------------- ---------- ------ ---------- + EGL_STREAM_TYPE_NV io EGLint 3.10.4.x + EGL_STREAM_PROTOCOL_NV io EGLint 3.10.4.x+1 + EGL_STREAM_ENDPOINT_NV io EGLint 3.10.4.x+2 + +Add to beginning of state list in section "3.10.4.3 EGL_STREAM_STATE_KHR +Attribute" in EGL_KHR_stream: + + - EGL_STREAM_STATE_INITIALIZING_NV - The EGLStream object + represents one endpoint of a remote stream and has not yet + established communication with the opposite endpoint. + +Replace the first entry in the state transition table in section +"3.10.4.3 EGL_STREAM_STATE_KHR Attribute" in EGL_KHR_stream: + + -> EGL_STREAM_STATE_INITIALIZING_NV + A new remote EGLStream is created in this state. + + EGL_STREAM_STATE_INITIALIZING_NV -> + EGL_STREAM_STATE_CREATED_KHR + Occurs when a remote EGLStream object establishes communication with + the opposite endpoint. + + -> EGL_STREAM_STATE_CREATED_KHR + A new local EGLStream or EGLStream of undetermined type is created + in this state. + +Add new subsections to the end of section "3.10.4 EGLStream Attributes" +in EGL_KHR_stream: + + 3.10.4.x EGL_STREAM_TYPE_NV Attribute + + The EGL_STREAM_TYPE_NV attribute may be set when the stream + is created, and indicates the type of connection between the + EGLStream objects to which the consumer and producer are attached. + Legal values are EGL_DONT_CARE and EGL_STREAM_LOCAL_NV. The + default value is EGL_DONT_CARE. + + A value of EGL_STREAM_LOCAL_NV indicates that this is a local + stream with both consumer and producer connected to a single + EGLStream object. + + If EGL_DONT_CARE is initially specified, the value of the attribute + will automatically be changed to the appropriate value once both + consumer and producer are attached, depending on the functions used. + + Other possible values for EGL_STREAM_TYPE_NV may be defined by + additional extensions to indicate a remote stream. Where used, + the EGL_STREAM_PROTOCOL_NV attribute must also be set to a + communication protocol compatible with the stream type. + + 3.10.4.x+1 EGL_STREAM_PROTOCOL_NV Attribute + + The EGL_STREAM_PROTOCOL_NV attribute may be set when the stream is + created, and indicates the manner in which communication is + established between the EGLStream objects to which the consumer + and producer are attached. Legal values are EGL_DONT_CARE and + EGL_STREAM_LOCAL_NV. The default value is EGL_DONT_CARE. + + A value of EGL_STREAM_LOCAL_NV indicates that this is a local + stream with both consumer and producer connected to a single + EGLStream object, so no communication protocol is required. + + If EGL_DONT_CARE is initially specified, the value of the attribute + will automatically be changed to the appropriate value once both + consumer and producer are attached, depending on the functions used. + + Other possible values for EGL_STREAM_PROTOCOL_NV may be defined by + additional extensions to indicate the communication protocol to be + used for a remote stream. Not all communication protocols are + compatible with all stream types, and vice versa. If incompatible + types and protocols are specified, an EGL_BAD_MATCH error will be + generated. + + 3.10.4.x+2 EGL_STREAM_ENDPOINT_NV Attribute + + The EGL_STREAM_ENDPOINT_NV attribute may be set when the stream is + created, and indicates the endpoints which will be attached to the + EGLStream object. Legal values are EGL_DONT_CARE, + EGL_STREAM_LOCAL_NV, EGL_STREAM_CONSUMER_NV, and + EGL_STREAM_PRODUCER_NV. The default value is EGL_DONT_CARE. + + A value of EGL_STREAM_LOCAL_NV indicates that this is a local + stream with both consumer and producer connected to a single + EGLStream object. + + A value of EGL_STREAM_CONSUMER_NV indicates that the EGLStream + object represents the consumer side of a remote stream. + + A value of EGL_STREAM_PRODUCER_NV indicates that the EGLStream + object represents the producer side of a remote stream. + + If EGL_DONT_CARE is initially specified, the value of the attribute + will automatically be changed to the appropriate value once both + consumer and producer are attached, depending on the functions used. + +If EGL_NV_stream_cross_object is present, in section 3.10.4.x above, +add EGL_STREAM_CROSS_OBJECT_NV to the list of legal values, and insert + + A value of EGL_STREAM_CROSS_OBJECT_NV indicates that the stream + object represents one endpoint of a remote stream whose other + endpoint is obtained from the same EGLDisplay. + +If EGL_NV_stream_cross_display is present, in section 3.10.4.x above, +add EGL_STREAM_CROSS_DISPLAY_NV to the list of legal values, and insert + + A value of EGL_STREAM_CROSS_DISPLAY_NV indicates that the stream + object represents one endpoint of a remote stream whose other + endpoint may be obtained from a different EGLDisplay in the same + process. + +If EGL_NV_stream_cross_process or EGL_NV_stream_cross_process_fd is +present, in section "3.10.4.x" above, add EGL_STREAM_CROSS_PROCESS_NV +to the list of legal values, and insert + + A value of EGL_STREAM_CROSS_PROCESS_NV indicates that the stream + object represents one endpoint of a remote stream whose other + endpoint may reside in a separate process. + +If EGL_NV_stream_cross_partition is present, in section 3.10.4.x +above, add EGL_STREAM_CROSS_PARTITION_NV to the list of legal values, +and insert + + A value of EGL_STREAM_CROSS_PARTITION_NV indicates that the stream + object represents one endpoint of a remote stream whose other + endpoint may reside in a separate virtual machine partition on + the same system. The partitions are not required to be using the + same operating systems, but must support compatible communication + protocols. + +If EGL_NV_stream_cross_system is present, in section 3.10.4.x above, +add EGL_STREAM_CROSS_SYSTEM_NV to the list of legal values, and insert + + A value of EGL_STREAM_CROSS_SYSTEM_NV indicates that the stream + object represents one endpoint of a remote stream whose other + endpoint may reside on an independent hardware system with no + directly sharable memory resources. + +If EGL_KHR_stream_cross_process_fd is present, in section 3.10.4.x+1 +above, add EGL_STREAM_PROTOCOL_FD_NV to the list of legal values, and +insert + + A value of EGL_STREAM_PROTOCOL_FD_NV indicates that the stream is + a remote stream whose communication is established using a file + descriptor. The details of what this file descriptor represents + are implementation dependent. If the EGL_STREAM_PROTOCOL_NV + attribute is initialized with this value, the EGL_STREAM_TYPE_NV + attribute must specify a value of EGL_STREAM_CROSS_PROCESS_NV or + an EGL_BAD_MATCH failure is generated. + + If an initial value of EGL_DONT_CARE is specified and a file + descriptor is subsequently obtained with + eglGetStreamFileDescriptorKHR, the value will be automatically + changed to EGL_STREAM_PROTOCOL_FD_NV. + +Add a new subsection to the end of "3.10.5 EGLStream operation": + + 3.10.5.x Remote streams + + An EGLStream object may be created as the endpoint of a remote + stream by specifying EGL_STREAM_PRODUCER_NV or + EGL_STREAM_CONSUMER_NV as the value for its EGL_STREAM_ENDPOINT_NV + attribute. Valid and compatible EGL_STREAM_TYPE_NV and + EGL_STREAM_PROTOCOL_NV values other than EGL_DONT_CARE or + EGL_STREAM_LOCAL_NV must also be specified. + + If a value for EGL_STREAM_ENDPOINT_NV is not specified, the stream + is assumed to be local, but other extensions (see for example + EGL_KHR_stream_cross_process_fd) may allow it to be converted to a + remote stream before the producer has been attached. + + When an EGLStream object is created as remote, any unspecified + attribute will be initially set to a value of EGL_DONT_CARE. Pairs + of EGLStream objects representing opposite endpoints of a stream are + not required to specify the same attribute lists, but their + attributes must be compatible. When communication is established + between the endpoints, they will exchange attribute settings: + - If both endpoints have a value of EGL_DONT_CARE for an + attribute, the default value will be assigned. + - If one endpoint has a value of EGL_DONT_CARE for an attribute, + it will be set to the other endpoint's value. + - If neither endpoint has a value of EGL_DONT_CARE for an + attribute, their values must agree. In most cases, this means + the values must be identical, but this may not be true for all + attributes. In particular, one endpoint must specify an + EGL_STREAM_ENDPOINT_NV value of EGL_STREAM_CONSUMER_NV, and + the other must specify a value of EGL_STREAM_PRODUCER_NV. + If the values for any attribute are not compatible, the stream will + transition to the EGL_STREAM_STATE_DISCONNECTED_KHR state. + + Additionally, if the two EGLStream objects representing a remote + stream are created for EGLDisplays which cannot share resources, + the stream will transition to the EGL_STREAM_STATE_DISCONNECTED_KHR + state. + + When using remote streams, there may be latency in communicating + state changes between the EGLStream objects representing the two + endpoints. For instance, when a new frame is inserted into the + stream by the producer, the consumer endpoint may not immediately + transition to EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR. Similarly, + when a frame is acquired by the consumer, the producer endpoint may + not immediately transition to + EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR. Applications should rely + only on the state of the endpoint on which they are operating to + determine the expected results of that operation. + +In section "3.10.1.1 Duplicating an EGLStream from a file descriptor" of +the EGL_KHR_stream_cross_process_fd extension, add to the failure list +for eglGetStreamFileDescriptor + + - EGL_BAD_ACCESS is generated if the EGL_STREAM_TYPE_NV + attribute of <stream> is anything other than EGL_DONT_CARE or + EGL_STREAM_CROSS_PROCESS_NV. + + - EGL_BAD_ACCESS is generated if the EGL_STREAM_PROTOCOL_NV + attribute of <stream> is anything other than EGL_DONT_CARE or + EGL_STREAM_PROTOCOL_FD_NV. + + - EGL_BAD_ACCESS is generated if the EGL_STREAM_ENDPOINT_NV + attribute of <stream> is EGL_STREAM_LOCAL_NV. + +Issues + + None + +Revision History + + #4 (June 01, 2016) + - Removed sync object definition. It will be provided by a + separate extension. + - Folded in cross-partition extension. + - Added types for cross-object, cross-display, and + cross-system streams. + - General cleanup in preparation for publication. + + #3 (September 16, 2015) Zander Clucas + - Removed dependence of the CROSS_PROCESS type on the + EGL_NV_cross_process_fd extension + - Added CROSS_PROCESS to the list of STREAM_TYPE legal values + - Added CROSS_PROCESS requirement for cross_process_fd protocol + + #2 (December 11, 2014) Daniel Kartch + - Rewrote as NV draft for earlier release. + - Added section for creation of sync object. + - Reserved enum values. + + #1 (October 10, 2014) Daniel Kartch + - Initial EXT draft diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_reset.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_reset.txt new file mode 100644 index 0000000..1cb0d06 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_reset.txt @@ -0,0 +1,306 @@ +Name + + NV_stream_reset + +Name Strings + + EGL_NV_stream_reset + +Contributors + + Daniel Kartch + +Contacts + + Daniel Kartch, NVIDIA (dkartch 'at' nvidia.com) + +Status + + Draft + +Version + + Version 6 - October 27, 2016 + +Number + + EGL Extension #112 + +Extension Type + + EGL display extension + +Dependencies + + Requires the EGL_KHR_stream extension. + + Modifies the EGL_KHR_stream_fifo extension. + + Modifies the EGL_KHR_stream_consumer_gltexture extension. + + Modifies the EGL_EXT_stream_consumer_egloutput extension. + + Interacts with the EGL_KHR_stream_cross_process_fd and + EGL_NV_stream_remote extensions. + + This extension is written based on the wording of version 26 of the + EGL_KHR_stream extension. + +Overview + + The base stream extension requires that, once the producer inserts + the first frame into the stream, at least one frame is always + available to be acquired by the consumer until the stream + disconnects. However, there are some use cases in which the producer + or the consumer may wish to allow the stream to empty without + permanently disconnecting. + + An example of a use case where the producer may wish to empty the + stream is a security or rear-view camera which temporarily stops + producing new frames, perhaps due to a hardware reset. Continuing to + display the last frame available would produce a false impression of + the current state, and should be avoided for safety reasons. A + better solution would be to let the consumer know there was no + available image, so that it could take appropriate actions, and then + recover when the camera begins streaming again. + + This use case could be handled with existing functionality by + disconnecting and destroying the stream and then recreating and + reconnecting it when new frames are available. However, this can be + burdensome, particularly when the producer and consumer reside in + separate processes. + + An example of a use case where the consumer may wish to empty the + stream is an image processer which operates on each frame exactly + once. After processing, it will not waste resources operating on the + same frame a second time. This use case can be handled by carefully + monitoring the availability of a new frame before performing an + acquire operation. But returning the buffer(s) as soon as they are + no longer needed allows for better resource management. + + This extension allows a stream to be completely drained of existing + frames by the consumer or flushed of existing frames by the producer + without disconnecting, so that processing may continue again when + new frames are produced. + +New Functions + + EGLBoolean eglResetStreamNV( + EGLDisplay dpy, + EGLStreamKHR stream); + +New Tokens + + Accepted as an attribute in the <attrib_list> parameter of + eglCreateStreamKHR and the <attrib> parameter of eglQueryStreamKHR: + + EGL_SUPPORT_RESET_NV 0x3334 + EGL_SUPPORT_REUSE_NV 0x3335 + +To table "3.10.4.4 EGLStream Attributes", add entry + + Attribute Read/Write Type Section + -------------------------- ---------- ------ ---------- + EGL_SUPPORT_RESET_NV io EGLint 3.10.4.x + EGL_SUPPORT_REUSE_NV io EGLint 3.10.4.x+1 + +Modify entries in the list of state transitions in "3.10.4.3 +EGL_STREAM_STATE_KHR Attribute" + + EGL_STREAM_STATE_EMPTY_KHR -> + EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR + Occurs when the producer inserts the first image frame and any + subsequent frame after the stream has been drained. + + EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR -> + EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR + Occurs when the producer inserts a new image frame and only + previously consumed frames are available. + + EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR -> + EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR + Occurs when the consumer begins examining the last unconsumed + frame and reuse of old frames is enabled. + +Add entries to the list of state transitions in "3.10.4.3 +EGL_STREAM_STATE_KHR Attribute" + + EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR -> + EGL_STREAM_STATE_EMPTY_KHR + Occurs when the stream is reset. + + EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR -> + EGL_STREAM_STATE_EMPTY_KHR + Occurs when the stream is reset or, if reuse of old frames is + disabled, when the consumer begins examining the last unconsumed + frame. + +Add new sections at the end of section "3.10.4 EGLStream Attributes" + + 3.10.4.x EGL_SUPPORT_RESET_NV Attribute + + The EGL_SUPPORT_RESET_NV attribute may only be set when the stream + is created. By default, it is EGL_FALSE. If set to EGL_TRUE, the + stream will allow restoration of the stream state back to + EGL_STREAM_STATE_EMPTY_KHR state from + EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR or + EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR, releasing existing frames, + as described in section 3.10.5.x. + + Not all consumers are required to support stream resets. Attempting + to attach a consumer which does not support resets to a stream with + EGL_SUPPORT_RESET_NV set to EGL_TRUE will fail with an + EGL_BAD_MATCH error. + + Not all producers will provide a means to reset streams themselves, + but any producer may be connected to a stream which supports resets + and may be used with the eglStreamResetNV function. + + 3.10.4.x+1 EGL_SUPPORT_REUSE_NV Attribute + + The EGL_SUPPORT_REUSE_NV attribute may only be set when the stream + is created. By default, it is EGL_TRUE. If EGL_TRUE, then when the + consumer acquires the last available image frame from the stream, it + will be held for reuse until a new frame is inserted to replace it. + If EGL_FALSE, no frames will be available to the consumer until the + producer inserts a new one. + +Modify third paragraph of "3.10.5.1 EGLStream operation in mailbox mode" + + 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, supports reuse of frames, and has not been reset) or + discarded (otherwise). + +If EGL_KHR_stream_fifo is present, insert at beginning of fourth paragraph +of "3.10.5.2 EGLStream operation in fifo mode" + + If the EGL_SUPPORT_REUSE_NV attribute is EGL_TRUE and the stream has + not been reset since the image frame was consumed, then if the fifo + is empty ... + +Insert a new paragraph after the above + + If the EGL_SUPPORT_REUSE_NV attribute is EGL_FALSE or the stream has + been reset, then if the fifo is empty when the consumer is finished + consuming an image frame, the frame is discarded and the stream is + left in the EGL_STREAM_STATE_EMPTY_KHR state until new frames are + produced. + +Add a new section to "3.10.5 EGLStream operation" + + 3.10.5.x EGLStream reset + + For resource management or safety reasons, it may be necessary to + invalidate and reclaim frames pending in the stream. This is only + possible if the stream's EGL_SUPPORT_RESET_NV attribute is set to + EGL_TRUE. + + Stream resets cause any unconsumed image frames waiting in the + stream to be immediately discarded, and place the stream in the + EGL_STREAM_STATE_EMPTY_KHR state. Frames currently held by the + consumer are not immediately affected, but will be discarded once + released, even if the stream would normally hold old frames for + reuse. After the reset, new frames inserted by the producer are + processed normally. + + Stream resets may be issued by some producers as described in their + specifications, and may also be triggered by the application calling + + EGLBoolean eglResetStreamNV( + EGLDisplay dpy, + EGLStreamKHR stream) + + On success, EGL_TRUE is returned and a reset of the stream is + initiated. On failure, EGL_FALSE is returned and an error is + generated. + + - EGL_BAD_DISPLAY is generated if <dpy> is not a valid + EGLDisplay. + + - EGL_NOT_INITIALIZED is generated if <dpy> is not initialized. + + - EGL_BAD_STREAM_KHR is generated if <stream> is not a valid + EGLStream created for <dpy>. + + - EGL_BAD_STATE_KHR is generated if <stream> is in + EGL_STREAM_STATE_CREATED_KHR, EGL_STREAM_STATE_CONNECTING_KHR, + or EGL_STREAM_STATE_DISCONNECTED_KHR state. + + - EGL_BAD_ACCESS is generated if <stream>'s + EGL_SUPPORT_RESET_NV attribute is not EGL_TRUE. + + If a stream is already in the EGL_STREAM_STATE_EMPTY_KHR state, a + reset will have no effect. + +If EGL_KHR_stream_cross_process_fd or EGL_NV_stream_remote is present, +add to the list of errors above + + - EGL_BAD_ACCESS is generated if <stream> represents the + consumer endpoint of a stream whose producer endpoint is + represented by a different EGLStreamKHR handle (e.g. for + cross-process streams). + +If EGL_KHR_stream_consumer_gltexture is supported, modify the first +sentence of the fifth paragraph of the description of +eglStreamConsumerAcquireKHR + + If the producer has not inserted any new image frames since the + last call to eglStreamConsumerAcquireKHR, and the stream has been + reset or does not support reuse of frames, then + eglStreamConsumerAcquireKHR will fail. If it has not been reset and + reuse is supported, then eglStreamConsumerAcquireKHR will "latch" + the same image frame it latched last time + eglStreamConsumerAcquireKHR was called. + +If EGL_EXT_stream_consumer_egloutput is supported, add to the +description if eglStreamConsumerOutputEXT + + If the stream is reset to the EGL_STREAM_STATE_EMPTY_KHR state, any + currently displayed frame will be released, and the displayed image + will be reset to some default state determined by the display + hardware and the implementation. Possible behavior includes, but is + not limited to, displaying a black screen, displaying a default + splash screen, displaying a "no input" message, or powering off the + display. If and when the stream again enters the + EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR state, processing of frames + will resume as described above. + +Issues + + 1. When this extension is present, should all streams automatically + support resetting? + + RESOLVED: No. Applications which are not aware of this extension + may not be prepared to handle an unexpected return to the EMPTY + state. Therefore support for this feature must be explicitly + requested. + +Revision History + + #6 (October 27, 2016) Daniel Kartch + - Clean up for publication + + #5 (July 23rd, 2015) Daniel Kartch + - Added interaction with cross-process streams. + + #4 (July 22nd, 2015) Daniel Kartch + - Added enum values. + + #3 (July 20th, 2015) Daniel Kartch + - Changed to NV specification + - Removed flush option from eglResetStream. Resetting will + always flush pending frames. + - Added EGL_SUPPORT_REUSE_NV flag to control whether released + frames are saved or discarded immediately. + - Removed reference to unpublished stream_sequence extension. + + #2 (August 21th, 2014) Daniel Kartch + - Added paragraph to indicate that producers do not impose + restrictions on use of reset. + - Clarified consumer behavior on reset. + - Added interactions with GL texture and EGLOutput consumers. + + #1 (August 12th, 2014) Daniel Kartch + - Initial draft diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_socket.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_socket.txt new file mode 100644 index 0000000..2d5e209 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_socket.txt @@ -0,0 +1,229 @@ +Name + + NV_stream_socket + NV_stream_socket_unix + NV_stream_socket_inet + +Name Strings + + EGL_NV_stream_socket + EGL_NV_stream_socket_unix + EGL_NV_stream_socket_inet + +Contributors + + Daniel Kartch + Bogdan Naodovic + James Jones + Zander Clucas + Tarun Bansal + +Contacts + + Daniel Kartch, NVIDIA (dkartch 'at' nvidia.com) + +Status + + Draft + +Version + + Version 6 - October 27, 2016 + +Number + + EGL Extension #115 + +Extension Type + + EGL display extension + +Dependencies + + EGL_NV_stream_socket requires EGL_NV_stream_remote. + + EGL_NV_stream_socket_unix requires EGL_NV_stream_socket. + + EGL_NV_stream_socket_inet requires EGL_NV_stream_socket. + +Overview + + These extensions build on the framework for remote streams provided + in EGL_NV_stream_remote to define a means for two EGLStream objects + representing opposite ends of a single stream to establish + communication using a socket. The application is expected to create + and connnect both ends of the socket before creating the stream + objects. + + The base EGL_NV_stream_socket extension defines most of the + attributes required to initialize the stream objects. The + EGL_NV_stream_socket_unix and EGL_NV_stream_socket_inet extensions + indicate support for UNIX domain and internet protocol socket types, + respectively. Additional extensions may provide support for other + socket types. The type of socket is important, as certain operations + are only available with certain types, which may influence how the + streams are implemented. For instance, UNIX domain sockets allow + file descriptors to be passed between processes, while internet + protocol sockets do not. This ability may allow more efficient + sharing of resources between the socket endpoints. + + An application using this extension will bear some similarity to the + example code from the EGL_KHR_stream_cross_process_fd extension, + which also uses sockets to establish the communication between two + processes and then create a pair of EGLStream objects. The key + difference is that in that case, the sockets are merely a temporary + means to an end to pass a file descriptor between the processes. + Once that is accomplished, the sockets are discarded. + + The file descriptor used by that extension may represent an + underlying object such as shared memory which allows more efficient + communication than the sockets themselves. However, there is nothing + preventing an implementation of EGL_NV_stream_socket from creating + and passing such a file descriptor as well, gaining the same + efficiency. Therefore, a protocol based on sockets will work at + least as well as one based on file descriptors, with the added + benefit of being more portable. + +New Types + + None + +New Functions + + None + +New Tokens for EGL_NV_stream_socket + + Accepted by eglCreateStreamKHR and returned by eglQueryStreamKHR + when attribute is EGL_STREAM_PROTOCOL_NV: + + EGL_STREAM_PROTOCOL_SOCKET_NV 0x324B + + Accepted as attribute names by eglCreateStreamKHR and + eglQueryStreamKHR functions + + EGL_SOCKET_HANDLE_NV 0x324C + EGL_SOCKET_TYPE_NV 0x324D + +New Tokens for EGL_NV_stream_socket_unix + + Accepted by eglCreateStreamKHR and returned by eglQueryStreamKHR + when attribute is EGL_SOCKET_TYPE_NV: + + EGL_SOCKET_TYPE_UNIX_NV 0x324E + +New Tokens for EGL_NV_stream_socket_inet + + Accepted by eglCreateStreamKHR and returned by eglQueryStreamKHR + when attribute is EGL_SOCKET_TYPE_NV: + + EGL_SOCKET_TYPE_INET_NV 0x324F + +Add to list of failures in section "3.10.1 Creating an EGLStream" in EGL_KHR stream: + + - EGL_BAD_MATCH is generated if the value of EGL_STREAM_PROTOCOL_NV + is EGL_STREAM_PROTOCOL_SOCKET_NV and values are not provided for + EGL_SOCKET_HANDLE_NV and EGL_SOCKET_TYPE_NV. + +Add to "Table 3.10.4.4 EGLStream Attributes" in EGL_KHR_stream: + + Attribute Read/Write Type Section + -------------------------- ---------- ------ ---------- + EGL_SOCKET_HANDLE_NV io EGLint 3.10.4.y + EGL_SOCKET_TYPE_NV io EGLint 3.10.4.y+1 + +In section "3.10.4.x+1 EGL_STREAM_PROTOCOL_NV Attribute" of +EGL_NV_stream_remote, add EGL_STREAM_PROTOCOL_SOCKET_NV to the list of +legal values and add + + A value of EGL_STREAM_PROTOCOL_SOCKET_NV indicates that the stream + is a remote stream whose communication is established using a socket + connection provided by the application. The details of the messages + passed through the socket are implementation dependent, and may be + influenced by the stream and socket types. This value for the + EGL_STREAM_PROTOCOL_NV attribute is compatible with values of + EGL_STREAM_CROSS_OBJECT_NV, EGL_STREAM_CROSS_DISPLAY_NV, + EGL_STREAM_CROSS_PROCESS_NV, and EGL_STREAM_CROSS_PARTITION_NV for + the EGL_STREAM_TYPE_NV attribute. + +Add new subsections to the end of section "3.10.4 EGLStream Attributes" +in EGL_KHR_stream: + + 3.10.4.y EGL_SOCKET_HANDLE_NV Attribute + + The EGL_SOCKET_HANDLE_NV attribute may be set when the stream + is created, and provides the handle to a blocking socket which will + be used to communicate with the other endpoint of the stream. If the + value of EGL_STREAM_PROTOCOL_NV is not EGL_STREAM_PROTOCOL_SOCKET_NV, + this attribute is ignored. + + The type of this value is operating system dependent, and the + default value will be an invalid socket handle for the operating + system. In particular, for unix-like operating systems, the value is + a socket file descriptor as returned by socket() and related + functions, and the default value is -1. + + Prior to creating the EGLStream object, the application may use the + socket handle as it wishes. But once the EGLStream object has been + successfully created, it assumes full ownership of this socket. If + the application subsequently writes to, reads from, or closes the + socket, undefined behavior will result. Furthermore, if any data + sent over the socket prior to creating the EGLStream object is not + consumed before the opposite EGLStream object is created, undefined + behavior will result. + + When the EGLStream object is deleted, the socket handle will be + closed by the stream. + + 3.10.4.y+1 EGL_SOCKET_TYPE_NV Attribute + + The EGL_SOCKET_TYPE_NV attribute may be set when the stream is + created, and indicates the type of the socket provided by the + EGL_STREAM_SOCKET_HANDLE_NV attribute. If the value of + EGL_STREAM_PROTOCOL_NV is not EGL_STREAM_PROTOCOL_SOCKET_NV this + attribute is ignored. + + The default value is EGL_NONE. + +If EGL_NV_stream_socket_unix is present, add to section "3.10.4.y+1 +EGL_SOCKET_TYPE_NV Attribute" above: + + A value of EGL_SOCKET_TYPE_UNIX_NV indicates that the socket handle + represents a Unix domain socket, created with SOCK_STREAM type. + +If EGL_NV_stream_socket_inet is present, add to section "3.10.4.y+1 +EGL_SOCKET_TYPE_NV Attribute" above: + + A value of EGL_SOCKET_TYPE_INET_NV indicates that the socket handle + represents an internet protocol socket, created with SOCK_STREAM + type. + +Issues + + None + +Revision History + + #6 (October 27, 2016) Daniel Kartch + - Indicate that the socket handle provided should represent + a blocking socket. + + #5 (June 7, 2016) Daniel Kartch + - Add contact and clean up in preparation for publication. + + #4 (September 16, 2015) Zander Clucas + - Indicated STREAM_SOCKET_PROTOCOL as compatible with socket + type CROSS_PROCESS. + + #3 (December 16, 2014) Daniel Kartch + - Refined overview to clarify comparison with + EGL_KHR_cross_process_fd. + - Indicated SOCK_STREAM as a requirement for the socket types. + + #2 (December 11, 2014) Daniel Kartch + - Rewrote as NV draft for earlier release. + - Reserved enum values. + + #1 (October 10, 2014) Daniel Kartch + - Initial EXT draft + diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_sync.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_sync.txt new file mode 100644 index 0000000..5604c4d --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_sync.txt @@ -0,0 +1,198 @@ +Name + + NV_stream_sync + +Name Strings + + EGL_NV_stream_sync + +Contributors + + Acorn Pooley + Marcus Lorentzon + +Contacts + + Ian Stewart, NVIDIA (istewart 'at' nvidia.com) + +Status + + Complete + +Version + + Version 6, June 5, 2012 + +Number + + EGL Extension #56 + +Dependencies + + Requires EGL 1.2. + Requires EGL_KHR_stream extension + Requires EGL_KHR_reusable_sync + + This extension is written based on the wording of the EGL 1.2 + specification. + +Overview + + This extension defines a new type of reusable sync object. This + sync object will be signaled each time a new image frame becomes + available in an EGLStream for the consumer to consume. + +New functions + + EGLSyncKHR eglCreateStreamSyncNV( + EGLDisplay dpy, + EGLStreamKHR stream, + EGLenum type, + const EGLint *attrib_list); + +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_NEW_FRAME_NV 0x321F + + +Add a new paragraph to section "3.8.1 Sync Objects" in the +EGL_KHR_reusable_sync extension, just before the paragraph that +mentions the eglClientWaitSyncKHR function: + + The command + + EGLSyncKHR eglCreateStreamSyncNV( + EGLDisplay dpy, + EGLStreamKHR stream, + EGLenum type, + const EGLint *attrib_list); + + creates a sync object of the specified <type> associated with the + specified display <dpy> and the specified EGLStream <stream>, 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. The + state of <stream> must not be EGL_STREAM_STATE_CREATED_KHR or + EGL_STREAM_STATE_DISCONNECTED_KHR. + + If <type> is EGL_SYNC_NEW_FRAME_NV, a stream-new-frame reusable + sync object is created. In this case <attrib_list> must be NULL or + empty (containing only EGL_NONE). Attributes of the reusable + stream-new-frame sync object are set as follows: + + Attribute Name Initial Attribute Value(s) + --------------- -------------------------- + EGL_SYNC_TYPE_KHR EGL_SYNC_NEW_FRAME_NV + EGL_SYNC_STATUS_KHR EGL_UNSIGNALED_KHR + + Any time the state of <stream> transitions to + EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR (from any other state), + the returned stream-new-frame reusable sync object is signaled. + (This effectively means the sync object will become signaled + whenever the producer inserts a new image frame into the + EGLStream.) + + EGL does not automatically unsignal the stream-new-frame reusable + sync object. Generally applications will want to unsignal the + sync object after it has been signaled so that the availability + of the next frame can + be detected. + + 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 <stream> is not a valid EGLStream created for <dpy>, + EGL_NO_SYNC_KHR is returned and an EGL_BAD_STREAM error is + generated. + * If <stream>'s state is EGL_STREAM_STATE_CREATED_KHR or + EGL_STREAM_STATE_DISCONNECTED_KHR then EGL_NO_SYNC_KHR is + returned and an EGL_BAD_ACCESS error is generated. + * If a sync object of <type> has already been created for + <stream> (and not destroyed), EGL_NO_SYNC_KHR is returned and + an EGL_BAD_ACCESS error is generated. + * If <type> is not a supported type of stream sync object, + EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE error is + generated. + +Issues + 1. Is this extension useful, or does the built in blocking + behavior of the consumer described by the + EGL_NV_stream_consumer_gltexture extension render this + un-useful? + + RESOLVED: Yes. It is useful to have a thread waiting on the + signal. + + 2. Does EGL automatically unsignal the sync object? + + RESOLVED: No. After the sync object has been signaled, it is + up to the application to unsignal it before waiting on it + again. It is important to check for the availability of + another frame by querying EGL_PRODUCER_FRAME_KHR after + unsignaling the sync object and before waiting on the sync + object to prevent a race condition. This can be done using + the following code: + + void ConsumeFrames(EGLDisplay dpy, EGLStreamKHR stream) + { + EGLuint64KHR last_frame = 0; + EGLuint64KHR new_frame = 0; + EGLSyncKHR sync; + + sync = eglCreateStreamSyncNV(dpy, + stream, + EGL_SYNC_NEW_FRAME_NV, + 0); + + for(;;) { + eglSignalSyncKHR(dpy, sync, EGL_UNSIGNALED_KHR); + eglQueryStreamu64KHR(dpy, + stream, + EGL_PRODUCER_FRAME_KHR, + &new_frame); + if (new_frame != last_frame) { + last_frame = new_frame; + ConsumeNewFrame(stream); + } else { + eglClientWaitSyncKHR(dpy, sync, 0, EGL_FOREVER_KHR); + } + } + } + +Revision History + + #7 (July 10, 2013) Jon Leech + - Fix spelling of 'signalled' -> 'signaled' and assign extension + number for publication. + + #6 (June 5, 2012) Acorn Pooley + - Add error if stream is in state EGL_STREAM_STATE_CREATED_KHR + or EGL_STREAM_STATE_DISCONNECTED_KHR when sync is created. + + #5 (September 30, 2011) Acorn Pooley + - Change eglCreateStreamSyncKHR to eglCreateStreamSyncNV + + #4 (September 28, 2011) Acorn Pooley + - Add issue 2 + - Fix return type of eglCreateStreamSyncNV + + #3 (September 27, 2011) Acorn Pooley + - Assign enum values (bug 8064) + + #2 (July 6, 2011) Acorn Pooley + - Rename EGL_KHR_image_stream to EGL_KHR_stream + + #1 (June 30, 2011) Acorn Pooley + - Initial draft + diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_sync.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_sync.txt new file mode 100644 index 0000000..0bf0077 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_sync.txt @@ -0,0 +1,554 @@ +Name + + NV_sync + +Name Strings + + EGL_NV_sync + +Contributors + + Gary King + Gregory Prisament + Acorn Pooley + Jon Leech + +Contacts + + Acorn Pooley, NVIDIA Corporation (apooley 'at' nvidia.com) + Gary King, NVIDIA Corporation (gking 'at' nvidia.com) + +Status + + Complete + +Version + + Version 7, July 27, 2010 + +Number + + EGL Extension #19 + +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 like that + extension, introduces only a single type of sync object, the + "fence sync object." Additional types of sync objects may be + introduced in later extensions. + + Fence sync objects have corresponding fences, which are inserted + into client API command streams. A sync object can be queried + for a given condition, such as completion of the corresponding + fence. Fence completion 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 extension is nearly identical to NVIDIA's original proposal for the + EGL_KHR_sync extension, which some minor differences outlined in Issue 7 + below. + +New Types + + /* + * EGLSyncNV is an opaque handle to an EGL sync object + */ + typedef void* EGLSyncNV; + + /* + * EGLTimeNV is a 64-bit unsigned integer representing intervals in + * nanoseconds (unadjusted standard time). A type defined in the + * standard Khronos <KHR/khrplatform.h> header is used instead of + * a less-portable native C type. + */ + #include <KHR/khrplatform.h> + typedef khronos_utime_nanoseconds_t EGLTimeNV; + +New Procedures and Functions + + EGLSyncNV eglCreateFenceSyncNV( EGLDisplay dpy, + EGLenum condition, + const EGLint *attrib_list ); + + EGLBoolean eglDestroySyncNV( EGLSyncNV sync ); + + EGLBoolean eglFenceNV( EGLSyncNV sync ); + + EGLint eglClientWaitSyncNV( EGLSyncNV sync, + EGLint flags, EGLTimeNV timeout ); + + EGLBoolean eglSignalSyncNV( EGLSyncNV sync, EGLenum mode ); + + EGLBoolean eglGetSyncAttribNV( EGLSyncNV sync, EGLint attribute, + EGLint *value ); + + +New Tokens + + Accepted in the <condition> parameter of eglCreateFenceSyncNV, and + returned in <value> when eglGetSyncAttribNV is called with <attribute> + EGL_SYNC_CONDITION_NV: + + EGL_SYNC_PRIOR_COMMANDS_COMPLETE_NV 0x30E6 + + Accepted as an attribute name in the <attrib_list> parameter of + eglCreateFenceSyncNV, and by the <attribute> parameter of + eglGetSyncAttribNV: + + EGL_SYNC_STATUS_NV 0x30E7 + + Accepted as an attribute value in the <attrib_list> parameter of + eglCreateFenceSyncNV for the EGL_SYNC_STATUS_NV attribute, by + the <mode> parameter of eglSignalSyncNV and returned in <value> + when eglGetSyncAttribNV is called with <attribute> + EGL_SYNC_STATUS_NV: + + EGL_SIGNALED_NV 0x30E8 + EGL_UNSIGNALED_NV 0x30E9 + + Accepted in the <flags> parameter of eglClientWaitSyncNV: + + EGL_SYNC_FLUSH_COMMANDS_BIT_NV 0x0001 + + Accepted in the <timeout> parameter of eglClientWaitSyncNV: + + EGL_FOREVER_NV 0xFFFFFFFFFFFFFFFFull + + Returned by eglClientWaitSyncNV: + + EGL_ALREADY_SIGNALED_NV 0x30EA + EGL_TIMEOUT_EXPIRED_NV 0x30EB + EGL_CONDITION_SATISFIED_NV 0x30EC + + Accepted in the <attribute> parameter of eglGetSyncAttribNV: + + EGL_SYNC_TYPE_NV 0x30ED + EGL_SYNC_CONDITION_NV 0x30EE + + Returned in <value> when eglGetSyncAttribNV is called with + <attribute> EGL_SYNC_TYPE_NV: + + EGL_SYNC_FENCE_NV 0x30EF + + Returned by eglCreateFenceSyncNV in the event of an error: + + EGL_NO_SYNC_NV ((EGLSyncNV)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>. Events may be associated with a sync object. When an + event is initially associated with a sync object, the object is + unsignaled (its status is set to unsignaled). Once a sync object has + been created, EGL may be asked to wait for a sync object to become + signaled. Sync objects may also be signaled or unsignaled explicitly. + Sync objects are associated with an EGLDisplay; this association + is made when the sync object is created. + + Only one type of sync object is defined, the fence sync object, whose + associated events are triggered by fence commands which are inserted + into the command streams of client API contexts. 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 + + EGLSyncNV eglCreateFenceSyncNV( EGLDisplay dpy, + enum condition, + EGLint *attrib_list ); + + creates a fence sync object for the specified display <dpy> and returns + a handle to the new object. The sync object is assigned a type of + EGL_SYNC_FENCE_NV. <condition> must be + EGL_SYNC_PRIOR_COMMANDS_COMPLETE_NV. <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. Attributes accepted by fence sync objects + are listed in table 3.aa + + Attribute Name Attribute Value(s) Default Value + --------------- ------------------------------------ -------------- + EGL_SYNC_STATUS_NV EGL_SIGNALED_NV, EGL_UNSIGNALED_NV EGL_SIGNALED_NV + + Table 3.aa Fence Sync Object Attributes + + * If <dpy> is not the name of a valid, initialized EGLDisplay, + EGL_NO_SYNC_NV is returned and an EGL_BAD_DISPLAY error is generated. + + * If <condition> is not EGL_SYNC_PRIOR_COMMANDS_COMPLETE_NV, + EGL_NO_SYNC_NV is returned and an EGL_BAD_PARAMETER error is generated. + + * If any attribute not appearing in table 3.?? is specified in + <attrib_list>, EGL_NO_SYNC_NV is returned and an EGL_BAD_ATTRIBUTE error is + generated. + + + The command + + EGLBoolean eglFenceNV( EGLSyncNV sync ); + + inserts a fence command into the command stream of the bound API's current + context (i.e., the context returned by eglGetCurrentContext), and + assoicates it with sync object <sync>. <sync> must be a sync object + created with eglCreateFenceSyncNV, and the display associated with <sync> + must match the current display (i.e., the display returned by + eglGetCurrentDisplay). Calling eglFenceNV unsignals <sync>. + + When the condition of <sync> is satisfied by the fence command, <sync> is + signaled by the associated client API context, causing any + eglClientWaitSyncNV commands (see below) blocking on <sync> to unblock. + The condition EGL_SYNC_PRIOR_COMMANDS_COMPLETE_NV 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. <sync> + 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. + + Multiple fence commands may be inserted in any client API command stream + for a single sync object. The sync object is unsignaled every time a new + fence command is issued, and signaled every time a previous fence command + completes, so its status is indeterminate until all fence commands + associated with the sync object have completed. However, each time a fence + command completes (signaling the sync object), at least one + eglClientWaitSyncNV command blocking on that sync object will unblock. + + EGL_TRUE is returned upon successful insertion of the fence command. + + * If <sync> is not a valid sync object with a type of EGL_SYNC_FENCE_NV, + EGL_FALSE is returned and an EGL_BAD_PARAMETER error is generated. + + * If the display associated with <sync> does not match the current + display, EGL_FALSE is returned and an EGL_BAD_MATCH error is generated. + + * If no context is current for the bound API (i.e., eglGetCurrentContext + returns EGL_NO_CONTEXT), EGL_FALSE is returned and an EGL_BAD_MATCH error + is generated. + + The command + + EGLint eglClientWaitSyncNV( EGLSyncNV sync, uint flags, + EGLTimeNV timeout ); + + blocks the calling thread until the specified sync object <sync> is + signaled, or until a specified timeout value expires. If <sync> is + signaled at the time eglClientWaitSyncNV is called then eglClientWaitSyncNV + will not block. If <sync> is unsignaled at the time eglClientWaitSyncNV is + called then eglClientWaitSyncNV will wait up to <timeout> nanoseconds for + <sync> to become signaled. + + If the value of <timeout> is zero, then eglClientWaitSyncNV will never + block and simply tests the current status of <sync>. If the value of + <timeout> is the special value EGL_FOREVER_NV then eglClientWaitSyncNV + does not time out. + + eglClientWaitSyncNV returns one of three status values describing the + reason for returning. A return value of EGL_ALREADY_SIGNALED_NV will + always be returned if <sync> was signaled when eglClientWaitSyncNV was + called, even if <timeout> is zero. A return value of + EGL_TIMEOUT_EXPIRED_NV indicates that indicates that the specified + timeout period expired before <sync> was signaled. A return value of + EGL_CONDITION_SATISFIED_NV indicates that <sync> was signaled before + the timeout expired. + + Note that a fence sync object can be in the signaled state because one of + three events has occured: + + 1. A previously inserte fence has completed and has signaled the sync + object. + 2. The sync object was created. Creation of a sync object sets it in the + signaled state by default, unless the attribute EGL_SYNC_STATUS_NV + is set to EGL_UNSIGNALED_NV in the attribute list. + 3. The sync object was signaled by a previously issued + eglSignalSyncNV(sync, EGL_SIGNALED_NV) command. + + 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 eglClientWaitSyncNV may + wait forever. To help prevent this behavior (footnote1), if the + EGL_SYNC_FLUSH_COMMANDS_BIT_NV bit is set in <flags>, and <sync> is + unsignaled when eglClientWaitSyncNV 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_NV + bit is ignored. + + (footnote 1): The simple Flush behavior defined by + EGL_SYNC_FLUSH_COMMANDS_BIT_NV 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. + + If a sync object is deleted when an eglClientWaitSyncNV is blocking on + that object, the behavior of eglClientWaitSyncNV is undefined. Some + possible behaviors are to return immediately, to wait for fence commands + associated with the deleted sync to complete, or to not return until the + timeout period expires. + + * If <sync> is not a valid sync object, EGL_FALSE is returned and an + EGL_BAD_PARAMETER error is generated. + + + The command + + EGLBoolean eglSignalSyncNV( EGLSyncNV sync, enum mode ); + + signals or unsignals the 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 eglSignalSyncNV, the status of <sync> transitions + from unsignaled to signaled, then at least one eglClientWaitSyncNV + commands blocking on <sync> will unblock. + + Assuming no errors are generated, EGL_TRUE is returned. + + Mode Effect + ------------------ ------------- + EGL_SIGNALED_NV Set the status of <sync> to signaled + EGL_UNSIGNALED_NV Set the status of <sync> to unsignaled + + Table 3.bb Modes Accepted by eglSignalSyncNV Command + + * If <sync> is not a valid sync object, EGL_FALSE is returned and an + EGL_BAD_PARAMETER error is generated. + + + The command + + EGLBoolean eglGetSyncAttribNV( EGLSyncNV 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; these are listed 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_NV Type of the sync object All + EGL_SYNC_STATUS_NV Status of the sync object All + EGL_SYNC_CONDITION_NV Signaling condition EGL_SYNC_FENCE_NV + + * If <sync> is not a valid sync object, EGL_FALSE is returned and an + EGL_BAD_PARAMETER error is generated. + + The command + + EGLBoolean eglDestroySyncNV( EGLSyncNV sync ); + + is used to destroy an existing sync object. If any eglClientWaitSyncNV + commands are blocking on <sync> when eglDestroySyncNV is called, their + behavior is undefined. After calling eglDestroySyncNV, <sync> is no + longer a valid sync object. Assuming no errors are generated, EGL_TRUE + is returned. + + * If <sync> is not a valid sync object, EGL_FALSE is returned and an + EGL_BAD_PARAMETER error is generated. + +Issues + + 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 + (eglClientWaitSyncNV) 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. 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. 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 EGLSyncNV 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_NV_sync remains minimal and easy + to implement on a variety of platforms. + + 6. Please provide a more detailed description of how ClientWaitSyncNV + behaves. + + RESPONSE: Issue 18 in the ARB_sync specification includes a very + detailed description of ClientWaitSyncARB (the ARB_sync equivalent of + ClientWaitSyncNV). This is provided (unmodified) below: + + Does ClientWaitSyncARB wait on an event, or on sync object + status? What is the meaning of sync object status? + + RESOLVED: ClientWaitSyncARB 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 need to be imbedded into the actual + spec language): + + R1) A sync object has two possible status values: signaled or + unsignaled (corresponding to SYNC_STATUS_ARB values of + SIGNALED_ARB or UNSIGNALED_ARB, respectively). + + R2) When created, the state of the sync object is signaled by + default, but may be explicitly set to unsignaled. + + R3) A fence command is inserted into a command stream. A sync + object is not. + + R4) When a fence command is inserted into a command stream using + FenceARB(), the status of the sync object associated with + that fence command is set to the unsignaled state. + + R5) Multiple fence commands can be associated with the same sync + object. + + R6) 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 + SYNC_PRIOR_COMMANDS_COMPLETE_ARB. + + R7) A wait function, such as ClientWaitSyncARB, waits on a sync + object, not on a fence. + + R8) A wait function, such as ClientWaitSyncARB, 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. + + Some of the behaviors resulting from these rules are: + + B1) Calling ClientWaitSyncARB with a timeout of 0 will return + TRUE if the sync object is in the signaled state. Note that + calling ClientWaitSyncARB with a timeout of 0 in a loop can + miss state transitions. + B2) Stacking fences is allowed. Each fence, once its condition + has been met, will set its associated sync object to the + signaled state. If the sync object is already in the + signaled state, it stays in that state. + B3) ClientWaitSyncARB could take a timeout parameter and return + a boolean. If the timeout period has expired, + ClientWaitSyncARB will unblock and return FALSE to the + caller. If ClientWaitSyncARB unblocks because the sync + object it was waiting on is in the signaled state, it will + return TRUE. + B4) We could define a FinishMultipleSync() command that will + unblock once all (or any) of the sync objects passed to it + are in the signaled state (also see issue 12). + B5) We could define a set/resetSyncObject function to manually + set the sync object in the signaled or unsignaled state. + This makes it easy for apps to reuse a sync object in the + multi-context case, so the sync object can be blocked upon + before a fence command is associated with it in the command + stream. + B6) We could define an API to convert a sync object into an OS + specific synchronization primitive (Events on Windows, file + descriptors or X-events or semaphores on Unix?) + + 7) How does this extension differ from (relate to) EGL_KHR_sync: + + RESPONSE: + As of the time of writing this, the EGL_KHR_sync specification has not + been finalized by Khronos and continues to undergo revision. However, + NVIDIA has the functionality outlined in this specification implemented + and has decided to make it available to developers immediately. + + For the most part, EGL_KHR_sync is identical to revision 5 of EGL_KHR_sync + with the following changes: + + a) Enum values are different + b) EGLTimeNV is unsigned long long instead of uint64_t. + c) Behaviour when there are multiple waiting threads is undefined. + +Revision History + +#7 (Jon Leech, July 27, 2010) + - Redefine EGLTimeNV type to use a typedef from the standard + Khronos headers instead of a native C type, for portability. +#6 (Greg Prisament, May 28, 2009) + - Branch spec & turn it into an _NV extension. +#5 (Greg Prisament, July 22, 2008) + - Removed NativeSyncKHR, CreateNativeSyncKHR, and corresponding wording. + - Correct EGLuint to EGLint (EGLuint doesn't exist). +#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/NV/EGL_NV_system_time.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_system_time.txt new file mode 100644 index 0000000..2f45147 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/NV/EGL_NV_system_time.txt @@ -0,0 +1,99 @@ +Name + + NV_system_time + +Name Strings + + EGL_NV_system_time + +Contact + + Jason Allen, NVIDIA Corporation (jallen 'at' nvidia.com) + +Status + + TBD + +Version + + Version 1, July 7, 2011 + +Number + + EGL Extension #31 + +Dependencies + + Requires EGL 1.2 + +Overview + + This extension exposes an alternative method of querying the system time + from the driver instead of the operating system. + +Issues + + Add 64 bit types? + + Yes, EGL doesn't support any 64 bit types so this extension adds int64 + and uint64 types. + +New Types + + EGLint64NV: 64bit signed integer + EGLuint64NV: 64bit unsigned integer + +New Procedures and Functions + + EGLuint64NV eglGetSystemTimeFrequencyNV(void); + EGLuint64NV eglGetSystemTimeNV(void); + +New Tokens + + None + +Description + + The command: + + EGLuint64NV eglGetSystemTimeFrequencyNV(void); + + returns the frequency of the system timer, in counts per second. The + frequency will not change while the system is running. + + The command: + + EGLuint64NV eglGetSystemTimeNV(void); + + returns the current value of the system timer. The system time in seconds + can be calculated by dividing the returned value by the frequency returned + by the eglGetSystemTimeFrequencyNV command. + + Multiple calls to eglGetSystemTimeNV may return the same values, applications + need to be careful to avoid divide by zero errors when using the interval + calculated from successive eglGetSystemTimeNV calls. + +Usage Example + + EGLuint64NV frequency = eglGetSystemTimeFrequencyNV(); + + loop + { + EGLuint64NV start = eglGetSystemTimeNV() / frequency; + + // draw + + EGLuint64NV end = eglGetSystemTimeNV() / frequency; + + EGLuint64NV interval = end - start; + if (interval > 0) + update_animation(interval); + + eglSwapBuffers(dpy, surface); + } + +Revision History + +#1 (Jon Leech, 2011/07/07) + - Add missing fields, assign extension number, and publish in the registry. + diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/TIZEN/EGL_TIZEN_image_native_buffer.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/TIZEN/EGL_TIZEN_image_native_buffer.txt new file mode 100644 index 0000000..72710b7 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/TIZEN/EGL_TIZEN_image_native_buffer.txt @@ -0,0 +1,114 @@ +Name + + TIZEN_image_native_buffer + +Name Strings + + EGL_TIZEN_image_native_buffer + +Contributors + + Dongyeon Kim + Minsu Han + Inpyo Kang + Zeeshan Anwar + +Contact + + Dongyeon Kim, Samsung Electronics (dy5.kim 'at' samsung.com) + Zeeshan Anwar, Samsung Electronics (z.anwar 'at' samsung.com) + +Status + + This extension is obsolete and has been replaced by + EGL_TIZEN_image_native_buffer + +Version + + Version 2, July 23, 2014 + +Number + + EGL Extension #76 + +Dependencies + + EGL 1.2 is required. + + EGL_KHR_image_base is required. + + This extension is written against the wording of the EGL 1.2 + Specification. + +Overview + + This extension enables using a Tizen native buffer (struct + native_buffer) as an EGLImage source. + +New Types + + None. + +New Procedures and Functions + + None. + +New Tokens + + Accepted by the <target> parameter of eglCreateImageKHR: + + EGL_NATIVE_BUFFER_TIZEN 0x32A0 + +Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors) + + 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_BUFFER_TIZEN | Used for Tizen native_buffer objects | + +-------------------------+--------------------------------------+ + Table aaa. Legal values for eglCreateImageKHR <target> parameter + + ... + + If <target> is EGL_NATIVE_BUFFER_TIZEN, <dpy> must be a valid display, + <ctx> must be EGL_NO_CONTEXT, <buffer> must be a pointer to a valid + native_buffer 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_BUFFER_TIZEN and <buffer> is not a + pointer to a valid native_buffer, the error EGL_BAD_PARAMETER + is generated. + + * If <target> is EGL_NATIVE_BUFFER_TIZEN and <ctx> is not + EGL_NO_CONTEXT, the error EGL_BAD_CONTEXT is generated. + + * If <target> is EGL_NATIVE_BUFFER_TIZEN and <buffer> was created + with properties (format, usage, dimensions, etc.) not supported by + the EGL implementation, the error EGL_BAD_PARAMETER is generated." + +Issues + + 1. Should this extension define what combinations of native_buffer + properties implementations are required to support? + + RESOLVED: No. + + The requirements have evolved over time and will continue to change with + future Tizen releases. The minimum requirements for a given Tizen + version should be documented by that version. + + +Revision History + +#2 (Zeeshan Anwar, July 01, 2014) + - Assigned the value to EGL_NATIVE_BUFFER_TIZEN +#1 (Dongyeon Kim, June 05, 2013) + - Initial draft. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/TIZEN/EGL_TIZEN_image_native_surface.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/TIZEN/EGL_TIZEN_image_native_surface.txt new file mode 100644 index 0000000..3d8ed3c --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/TIZEN/EGL_TIZEN_image_native_surface.txt @@ -0,0 +1,121 @@ +Name + + TIZEN_image_native_surface + +Name Strings + + EGL_TIZEN_image_native_surface + +Contributors + + Dongyeon Kim + Zeeshan Anwar + Minsu Han + Inpyo Kang + +Contact + + Dongyeon Kim, Samsung Electronics (dy5.kim 'at' samsung.com) + Zeeshan Anwar, Samsung Electronics (z.anwar 'at' samsung.com) + +Status + + Complete + +Version + + Version 3, August 13, 2014 + +Number + + EGL Extension #77 + +Dependencies + + EGL 1.2 is required. + + EGL_KHR_image_base is required. + + This extension is written against the wording of the EGL 1.2 + Specification. + +Overview + + Tizen Buffer Manager (TBM) is a user space, generic memory + management framework to create and share memory buffers between + different system components. This extension enables using a Tizen + Buffer Manager (TBM) surface object (struct tbm_surface_h) as an + EGLImage source. + +New Types + + None. + +New Procedures and Functions + + None. + +New Tokens + + Accepted by the <target> parameter of eglCreateImageKHR: + + EGL_NATIVE_SURFACE_TIZEN 0x32A1 + +Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors) + + 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_SURFACE_TIZEN | Used for Tizen tbm_surface_h objects | + +---------------------------+------------------------------------+ + Table aaa. Legal values for eglCreateImageKHR <target> parameter + + ... + + If <target> is EGL_NATIVE_SURFACE_TIZEN, <dpy> must be a valid + display, <ctx> must be EGL_NO_CONTEXT, <buffer> must be a pointer + to a valid tbm_surface_h 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_SURFACE_TIZEN and <buffer> is not + a pointer to a valid tbm_surface_h, the error EGL_BAD_PARAMETER + is generated. + + * If <target> is EGL_NATIVE_SURFACE_TIZEN and <ctx> is not + EGL_NO_CONTEXT, the error EGL_BAD_CONTEXT is generated. + + * If <target> is EGL_NATIVE_SURFACE_TIZEN and <buffer> was + created with properties (format, usage, dimensions, etc.) not + supported by the EGL implementation, the error + EGL_BAD_PARAMETER is generated." + +Issues + + 1. Should this extension define what combinations of tbm_surface_h + properties implementations are required to support? + + RESOLVED: No. + + The requirements have evolved over time and will continue to change + with future Tizen releases. The minimum requirements for a given + Tizen version should be documented by that version. + + +Revision History +#3 (Zeeshan Anwar, August 13, 2014) + - Changed tbm_surface to tbm_surface_h + +#2 (Zeeshan Anwar, July 23, 2014) + - Changed extension name and target name + - Assigned value to EGL_NATIVE_SURFACE_TIZEN + +#1 (Zeeshan Anwar, July 18, 2014) + - Initial draft. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/WL/EGL_WL_bind_wayland_display.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/WL/EGL_WL_bind_wayland_display.txt new file mode 100644 index 0000000..2b2dd59 --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/WL/EGL_WL_bind_wayland_display.txt @@ -0,0 +1,217 @@ +Name + + WL_bind_wayland_display + +Name Strings + + EGL_WL_bind_wayland_display + +Contact + + Kristian Høgsberg <krh@bitplanet.net> + Benjamin Franzke <benjaminfranzke@googlemail.com> + +Status + + Complete + +Version + + Version 6, July 14, 2017 + +Number + + EGL Extension #136 + +Dependencies + + Requires EGL 1.4 or later. This extension is written against the + wording of the EGL 1.4 specification. + + EGL_KHR_image_base is required. + +Overview + + This extension provides entry points for binding and unbinding the + wl_display of a Wayland compositor to an EGLDisplay. Binding a + wl_display means that the EGL implementation should provide one or + more interfaces in the Wayland protocol to allow clients to create + wl_buffer objects. On the server side, this extension also + provides a new target for eglCreateImageKHR, to create an EGLImage + from a wl_buffer. + + Adding an implementation-specific Wayland interface, allows the + EGL implementation to define specific wayland requests and events, + needed for buffer sharing in an EGL Wayland platform. + +IP Status + + Open-source; freely implementable. + +New Procedures and Functions + + EGLBoolean eglBindWaylandDisplayWL(EGLDisplay dpy, + struct wl_display *display); + + EGLBoolean eglUnbindWaylandDisplayWL(EGLDisplay dpy, + struct wl_display *display); + + EGLBoolean eglQueryWaylandBufferWL(EGLDisplay dpy, + struct wl_resource *buffer, + EGLint attribute, EGLint *value); + +New Tokens + + Accepted as <target> in eglCreateImageKHR + + EGL_WAYLAND_BUFFER_WL 0x31D5 + + Accepted in the <attrib_list> parameter of eglCreateImageKHR: + + EGL_WAYLAND_PLANE_WL 0x31D6 + + Possible values for EGL_TEXTURE_FORMAT: + + EGL_TEXTURE_Y_U_V_WL 0x31D7 + EGL_TEXTURE_Y_UV_WL 0x31D8 + EGL_TEXTURE_Y_XUXV_WL 0x31D9 + EGL_TEXTURE_EXTERNAL_WL 0x31DA + + Accepted in the <attribute> parameter of eglQueryWaylandBufferWL: + + EGL_TEXTURE_FORMAT 0x3080 + EGL_WAYLAND_Y_INVERTED_WL 0x31DB + + +Additions to the EGL 1.4 Specification: + + To bind a server-side wl_display to an EGLDisplay, call + + EGLBoolean eglBindWaylandDisplayWL(EGLDisplay dpy, + struct wl_display *display); + + To unbind a server-side wl_display from an EGLDisplay, call + + EGLBoolean eglUnbindWaylandDisplayWL(EGLDisplay dpy, + struct wl_display *display); + + eglBindWaylandDisplayWL returns EGL_FALSE when there is already a + wl_display bound to EGLDisplay otherwise EGL_TRUE. + + eglUnbindWaylandDisplayWL returns EGL_FALSE when there is no + wl_display bound to the EGLDisplay currently otherwise EGL_TRUE. + + XXXXXXXX + EGL_WAYLAND_BUFFER_WL + + + To query attributes of a wl_buffer created by the EGL + implementation installed by eglBindWaylandDisplayWL, call: + + EGLBoolean eglQueryWaylandBufferWL(EGLDisplay dpy, + struct wl_resource *buffer, + EGLint attribute, + EGLint *value); + + A wl_buffer can have several planes, typically in case of planar + YUV formats. Depending on the exact YUV format in use, the + compositor will have to create one or more EGLImages for the + various planes. The eglQueryWaylandBufferWL function should be + used to first query the wl_buffer texture format using + EGL_TEXTURE_FORMAT as the attribute. If the wl_buffer object is + not an EGL wl_buffer (wl_shm and other wayland extensions can + create wl_buffer objects of different types), this query will + return EGL_FALSE. In that case the wl_buffer can not be used with + EGL and the compositor should have another way to get the buffer + contents. + + If eglQueryWaylandBufferWL succeeds, the returned value will be + one of EGL_TEXTURE_RGB, EGL_TEXTURE_RGBA, EGL_TEXTURE_Y_U_V_WL, + EGL_TEXTURE_Y_UV_WL, EGL_TEXTURE_Y_XUXV_WL. The value returned + describes how many EGLImages must be used, which components will + be sampled from each EGLImage and how they map to rgba components + in the shader. The naming conventions separates planes by _ and + within each plane, the order or R, G, B, A, Y, U, and V indicates + how those components map to the rgba value returned by the + sampler. X indicates that the corresponding component in the rgba + value isn't used. + + RGB and RGBA buffer types: + + EGL_TEXTURE_RGB + One plane, samples RGB from the texture to rgb in the + shader. Alpha channel is not valid. + + EGL_TEXTURE_RGBA + One plane, samples RGBA from the texture to rgba in the + shader. + + YUV buffer types: + + EGL_TEXTURE_Y_U_V_WL + Three planes, samples Y from the first plane to r in + the shader, U from the second plane to r, and V from + the third plane to r. + + EGL_TEXTURE_Y_UV_WL + Two planes, samples Y from the first plane to r in + the shader, U and V from the second plane to rg. + + EGL_TEXTURE_Y_XUXV_WL + Two planes, samples Y from the first plane to r in + the shader, U and V from the second plane to g and a. + + EGL_TEXTURE_EXTERNAL_WL + Treated as a single plane texture, but sampled with + samplerExternalOES according to OES_EGL_image_external + + After querying the wl_buffer layout, create EGLImages for the + planes by calling eglCreateImageKHR with wl_buffer as + EGLClientBuffer, EGL_WAYLAND_BUFFER_WL as the target, NULL + context. If no attributes are given, an EGLImage will be created + for the first plane. For multi-planar buffers, specify the plane + to create the EGLImage for by using the EGL_WAYLAND_PLANE_WL + attribute. The value of the attribute is the index of the plane, + as defined by the buffer format. Writing to an EGLImage created + from a wl_buffer in any way (such as glTexImage2D, binding the + EGLImage as a renderbuffer etc) will result in undefined behavior. + + Further, eglQueryWaylandBufferWL accepts attributes EGL_WIDTH and + EGL_HEIGHT to query the width and height of the wl_buffer. + + Also, eglQueryWaylandBufferWL may accept + EGL_WAYLAND_Y_INVERTED_WL attribute to query orientation of + wl_buffer. If EGL_WAYLAND_Y_INVERTED_WL is supported + eglQueryWaylandBufferWL returns EGL_TRUE and value is a boolean + that tells if wl_buffer is y-inverted or not. If + EGL_WAYLAND_Y_INVERTED_WL is not supported + eglQueryWaylandBufferWL returns EGL_FALSE, in that case + wl_buffer should be treated as if value of + EGL_WAYLAND_Y_INVERTED_WL was EGL_TRUE. + +Issues + +Revision History + + Version 1, March 1, 2011 + Initial draft (Benjamin Franzke) + Version 2, July 5, 2012 + Add EGL_WAYLAND_PLANE_WL attribute to allow creating an EGLImage + for different planes of planar buffer. (Kristian Høgsberg) + Version 3, July 10, 2012 + Add eglQueryWaylandBufferWL and the various buffer + formats. (Kristian Høgsberg) + Version 4, July 19, 2012 + Use EGL_TEXTURE_FORMAT, EGL_TEXTURE_RGB, and EGL_TEXTURE_RGBA, + and just define the new YUV texture formats. Add support for + EGL_WIDTH and EGL_HEIGHT in the query attributes (Kristian Høgsberg) + Version 5, July 16, 2013 + Change eglQueryWaylandBufferWL to take a resource pointer to the + buffer instead of a pointer to a struct wl_buffer, as the latter has + been deprecated. (Ander Conselvan de Oliveira) + Version 6, September 16, 2013 + Add EGL_WAYLAND_Y_INVERTED_WL attribute to allow specifying + wl_buffer's orientation. + Version 7, July 14, 2017 + Add EGL_WAYLAND_BUFFER_WL EGLImage target. Reword for inclusion in + Khronos registry. diff --git a/engine-ocean/External/glew/auto/EGL-Registry/extensions/WL/EGL_WL_create_wayland_buffer_from_image.txt b/engine-ocean/External/glew/auto/EGL-Registry/extensions/WL/EGL_WL_create_wayland_buffer_from_image.txt new file mode 100644 index 0000000..8395cae --- /dev/null +++ b/engine-ocean/External/glew/auto/EGL-Registry/extensions/WL/EGL_WL_create_wayland_buffer_from_image.txt @@ -0,0 +1,101 @@ +Name + + WL_create_wayland_buffer_from_image + +Name Strings + + EGL_WL_create_wayland_buffer_from_image + +Contributors + + Neil Roberts + Axel Davy + Daniel Stone + +Contact + + Neil Roberts <neil.s.roberts@intel.com> + +Status + + Complete + +Version + + Version 2, October 25, 2013 + +Number + + EGL Extension #137 + +Dependencies + + Requires EGL 1.4 or later. This extension is written against the + wording of the EGL 1.4 specification. + + EGL_KHR_base_image is required. + +Overview + + This extension provides an entry point to create a wl_buffer which shares + its contents with a given EGLImage. The expected use case for this is in a + nested Wayland compositor which is using subsurfaces to present buffers + from its clients. Using this extension it can attach the client buffers + directly to the subsurface without having to blit the contents into an + intermediate buffer. The compositing can then be done in the parent + compositor. + + The nested compositor can create an EGLImage from a client buffer resource + using the existing WL_bind_wayland_display extension. It should also be + possible to create buffers using other types of images although there is + no expected use case for that. + +IP Status + + Open-source; freely implementable. + +New Procedures and Functions + + struct wl_buffer *eglCreateWaylandBufferFromImageWL(EGLDisplay dpy, + EGLImageKHR image); + +New Tokens + + None. + +Additions to the EGL 1.4 Specification: + + To create a client-side wl_buffer from an EGLImage call + + struct wl_buffer *eglCreateWaylandBufferFromImageWL(EGLDisplay dpy, + EGLImageKHR image); + + The returned buffer will share the contents with the given EGLImage. Any + updates to the image will also be updated in the wl_buffer. Typically the + EGLImage will be generated in a nested Wayland compositor using a buffer + resource from a client via the EGL_WL_bind_wayland_display extension. + + If there was an error then the function will return NULL. In particular it + will generate EGL_BAD_MATCH if the implementation is not able to represent + the image as a wl_buffer. The possible reasons for this error are + implementation-dependant but may include problems such as an unsupported + format or tiling mode or that the buffer is in memory that is inaccessible + to the GPU that the given EGLDisplay is using. + +Issues + + 1) Under what circumstances can the EGL_BAD_MATCH error be generated? Does + this include for example unsupported tiling modes? + + RESOLVED: Yes, the EGL_BAD_MATCH error can be generated for any reason + which prevents the implementation from representing the image as a + wl_buffer. For example, these problems can be but are not limited to + unsupported tiling modes, inaccessible memory or an unsupported pixel + format. + +Revision History + + Version 1, September 6, 2013 + Initial draft (Neil Roberts) + Version 2, October 25, 2013 + Added a note about more possible reasons for returning EGL_BAD_FORMAT. |