mirror of
https://github.com/godotengine/godot-angle-static.git
synced 2026-01-03 14:09:33 +03:00
315ecd2074
This instruments the plumbing for the extension without adding any functionality or exposing the extensions string. The extension text is also updated to reflect the new entry point design and naming. Also this corrects a few mistakes. This will be followed up by the tests (which won't run) and then the extension functionality in ANGLE. BUG=angleproject:1897 Change-Id: I5b009e23bc27da06b067375525bd6fc574027702
234 lines
8.3 KiB
Plaintext
234 lines
8.3 KiB
Plaintext
Name
|
|
|
|
EGL_ANGLE_program_cache_control
|
|
|
|
Name Strings
|
|
|
|
EGL_ANGLE_program_cache_control
|
|
|
|
Contributors
|
|
|
|
Jamie Madill, Google
|
|
|
|
Contacts
|
|
|
|
Jamie Madill (jmadill 'at' google.com)
|
|
|
|
Status
|
|
|
|
Draft
|
|
|
|
Version
|
|
|
|
Version 1, June 29, 2017
|
|
|
|
Number
|
|
|
|
EGL Extension #??
|
|
|
|
Dependencies
|
|
|
|
Requires EGL 1.5.
|
|
|
|
Written against the EGL 1.5 specification.
|
|
|
|
Overview
|
|
|
|
This extension allows the for creation of an OpenGL or OpenGL ES contexts
|
|
that have access to an internal binary program cache. It also allows for
|
|
querying and populating the contents of the binary cache.
|
|
|
|
An OpenGL ES implementation supporting GL_ANGLE_program_cache_control or
|
|
equivalent functionality is required.
|
|
|
|
New Types
|
|
|
|
None
|
|
|
|
New Procedures and Functions
|
|
|
|
EGLint eglProgramCacheGetAttribANGLE(
|
|
EGLDisplay dpy,
|
|
EGLenum attrib);
|
|
|
|
void eglProgramCacheQueryANGLE(
|
|
EGLDisplay dpy,
|
|
EGLint index,
|
|
void *key,
|
|
EGLint *keysize,
|
|
void *binary,
|
|
EGLint *binarysize);
|
|
|
|
void eglProgramCachePopulateANGLE(
|
|
EGLDisplay dpy,
|
|
const void *key,
|
|
EGLint keysize,
|
|
const void *binary,
|
|
EGLint binarysize);
|
|
|
|
EGLint eglProgramCacheResizeANGLE(
|
|
EGLDisplay dpy,
|
|
EGLint limit,
|
|
EGLenum mode);
|
|
|
|
New Tokens
|
|
|
|
Accepted as a value for 'attrib' in eglProgramCacheGetAttribANGLE:
|
|
|
|
EGL_PROGRAM_CACHE_SIZE_ANGLE 0x3455
|
|
EGL_PROGRAM_CACHE_KEY_LENGTH_ANGLE 0x3456
|
|
|
|
Accepted as a value for 'mode' in eglProgramCacheResizeANGLE:
|
|
|
|
EGL_PROGRAM_CACHE_RESIZE_ANGLE 0x3457
|
|
EGL_PROGRAM_CACHE_TRIM_ANGLE 0x3458
|
|
|
|
Accepted as an attribute name in the <*attrib_list> argument to
|
|
eglCreateContext:
|
|
|
|
EGL_CONTEXT_PROGRAM_BINARY_CACHE_ENABLED_ANGLE 0x3459
|
|
|
|
Additions to the EGL 1.5 Specification
|
|
|
|
Add the following to section 3.7.1 "Creating Rendering Contexts":
|
|
|
|
EGL_CONTEXT_PROGRAM_BINARY_CACHE_ENABLED_ANGLE indicates whether the context
|
|
should be created with the GL_PROGRAM_BINARY_CACHE_ENABLE_ANGLE state
|
|
initialized to GL_TRUE or GL_FALSE. The default value of
|
|
EGL_CONTEXT_PROGRAM_BINARY_CACHE_ENABLED_ANGLE is EGL_TRUE. See section 3.13
|
|
for details on the program binary cache.
|
|
|
|
Add a section 3.13 to the end of section 3 "EGL Program Binary Cache":
|
|
|
|
Each display has an associated program binary cache. This cache stores
|
|
compiled programs for re-use on subsequent calls to glLinkProgram. The
|
|
application can control the behaviour of the cache by enabling or disabling
|
|
its use per-context (see section 3.7.1) and specifying a cache size. It
|
|
can also query the current cache values and populate the cache during start-
|
|
up.
|
|
|
|
Program binary cache properties may be queried using
|
|
|
|
EGLint eglProgramCacheGetAttribANGLE(EGLDisplay dpy, EGLenum attrib);
|
|
|
|
The only accepted values for 'attrib' are EGL_PROGRAM_CACHE_SIZE_ANGLE and
|
|
EGL_PROGRAM_CACHE_KEY_LENGTH_ANGLE. A query for EGL_PROGRAM_CACHE_SIZE_ANGLE
|
|
will return the number of cache entries in the program cache. A
|
|
query of EGL_PROGRAM_CACHE_KEY_LENGTH_ANGLE will return the required length
|
|
(in bytes) of the 'key' parameter to eglProgramCacheQueryANGLE and
|
|
eglPopulateProgramCacheANGLE. Any other value for 'attrib' will produce an
|
|
error of EGL_BAD_ATTRIBUTE, and an invalid display for 'dpy' will produce an
|
|
error of EGL_BAD_DISPLAY. All error cases will return zero.
|
|
|
|
Cache contents may be queried by using
|
|
|
|
void eglProgramCacheQueryANGLE(EGLDisplay dpy, EGLint index,
|
|
void *key, EGLint *keysize, void *binary, EGLint *binarysize);
|
|
|
|
If 'dpy' is not a valid display an EGL_BAD_DISPLAY error is generated. If
|
|
'index' is not equal to or greater than zero and less than
|
|
EGL_PROGRAM_CACHE_SIZE_ANGLE, an EGL_BAD_PARAMETER error is generated. If
|
|
'dpy' is not a valid display EGL_BAD_DISPLAY is generated. If 'binarysize'
|
|
and 'keysize' are non-null, and 'binary' and 'key' are null, the size of the
|
|
binary at 'index' is written to 'binarysize', and the key size to 'keysize'.
|
|
If 'binary' is not null, 'binarysize' specifies the maximum size of the
|
|
'binary' out parameter, and if 'keysize' is not null, the size of the 'key'
|
|
out parameter. Any attempt to write more than 'binarysize' or 'keysize'
|
|
bytes will produce an EGL_BAD_ACCESS error in this case. If 'keysize' or
|
|
'binarysize' is null, an EGL_BAD_PARAMETER error is generated. If 'key' is
|
|
not null, 'binary' must also be non-null, and vice versa, or an
|
|
EGL_BAD_PARAMETER error is generated. If the cache contents change such that
|
|
a cache entry at 'index' is not retrievable, either EGL_BAD_ACCESS is
|
|
generated or a null key and binary are returned. Valid entries returned are
|
|
not guaranteed to be in the cache. Otherwise, the binary is written to
|
|
'binary' and the program key is written to 'key'.
|
|
|
|
The cache may be warmed up on startup with
|
|
|
|
void eglProgramCachePopulateANGLE(EGLDisplay dpy, const void *key,
|
|
EGLint keysize, const void *binary, EGLint binarysize);
|
|
|
|
If 'dpy' is not a valid display an EGL_BAD_DISPLAY error is generated. If
|
|
'binarysize' is not positive or is greater than an internally defined
|
|
maximum size, EGL_BAD_PARAMETER is generated. If 'keysize' does not equal
|
|
EGL_PROGRAM_CACHE_KEY_LENGTH_ANGLE, EGL_BAD_PARAMETER is generated. If the
|
|
program binary is invalid for any reason, behaviour is undefined. Otherwise
|
|
the program will be loaded into the internal binary cache with the key
|
|
'key'. If 'binary' or 'key' are null, an EGL_BAD_PARAMETER error is
|
|
generated.
|
|
|
|
The cache contents size may be changed using
|
|
|
|
EGLint eglProgramCacheResizeANGLE(EGLDisplay dpy, EGLint limit,
|
|
EGLenum mode);
|
|
|
|
If 'dpy' is not a valid display an EGL_BAD_DISPLAY error is generated. If
|
|
limit is negative then EGL_BAD_PARAMETER is generated. If 'mode' is
|
|
EGL_PROGRAM_CACHE_RESIZE, cache contents are discarded and a new maximum
|
|
cache size is set to 'limit'. If 'limit' is larget than an implementation-
|
|
defined internal constant, EGL_BAD_PARAMETER is generated. Otherwise the
|
|
initial cache size is returned. If 'mode' is EGL_PROGRAM_CACHE_TRIM, cache
|
|
resources are released until the total cache size, in bytes, is less than or
|
|
equal to 'limit', and the number of bytes of memory released is returned.
|
|
In any error case, zero is returned.
|
|
|
|
Errors
|
|
|
|
None
|
|
|
|
New State
|
|
|
|
None
|
|
|
|
Conformance Tests
|
|
|
|
TBD
|
|
|
|
Issues
|
|
|
|
1. Should the cache control be a property of the display or the contexts?
|
|
|
|
The cache itself will internally be a property of the display, since we
|
|
want to share caches between contexts. It is possible to design an
|
|
implementation with other kinds of cache sharing, such as between share
|
|
groups.
|
|
|
|
We can choose to prefer simplicity of design in this case.
|
|
|
|
RESOLVED: the cache should be a property of the display.
|
|
|
|
2. What should happen if the cache is modified as the user is querying its
|
|
contents?
|
|
|
|
It is more difficult to design a query API such that it can be returned
|
|
atomically. Hence the cache can change in some cases while it is being
|
|
queried. This can be controlled in the application layer. It can also be
|
|
locked using OS-level synchronization.
|
|
|
|
Introducing undefined behaviour can be very problematic.
|
|
|
|
RESOLVED: we should use a mutex or similar lock to allow for multithreaded
|
|
access, and not expose undefined behaviour.
|
|
|
|
3. Should we expose the key/value semantics or just have a binary value?
|
|
|
|
Having just the binary would eliminate one query enum, and make the APIs
|
|
simpler. Having both key and value represents the implementation exactly.
|
|
|
|
RESOLVED: we should expose the key to mirror the implementation.
|
|
|
|
4. Should the extension allow for setting cache size limits?
|
|
|
|
If caches are a property of the display, they could be set in
|
|
eglGetPlatformDisplay as an attribute.
|
|
|
|
Cache controls can be a necessary feature for memory management.
|
|
|
|
RESOLVED: yes, we should expose cache size controls.
|
|
|
|
Revision History
|
|
|
|
Rev. Date Author Changes
|
|
---- ------------- --------- ----------------------------------------
|
|
1 June 29, 2017 jmadill Initial version
|