1Name 2 3 ANGLE_blob_cache 4 5Name Strings 6 7 GL_ANGLE_blob_cache 8 9Contributors 10 11 Geoff Lang 12 13Contact 14 15 Geoff Lang (geofflang 'at' google.com) 16 17Notice 18 19 Copyright (c) 2024 The Khronos Group Inc. Copyright terms at 20 http://www.khronos.org/registry/speccopyright.html 21 22Status 23 24 Draft 25 26Version 27 28 Version 1, October 4, 2024 29 30Number 31 32 OpenGL ES Extension #?? 33 34Dependencies 35 36 Requires OpenGL ES 2.0 37 38 Written against the OpenGL ES 3.2 specification. 39 40Overview 41 42 This extension provides a mechanism for an OpenGL context to cache binary 43 blobs. The application must implement the cache and is in control of caching 44 behavior. 45 46 This extension adds caching callbacks per-context which is useful for 47 isolating cached data and providing extra security. 48 49 50New Procedures and Functions 51 52 void SetBlobCacheFuncsANGLE(SETBLOBPROCANGLE set, 53 GETBLOBPROCANGLE get, 54 const void* userParam); 55 56 void GetPointervANGLE(enum pname, void **params); 57 58New Types 59 60 The callback functions that applications can define, and 61 are accepted by SetBlobCacheFuncsANGLE, are defined as: 62 63 typedef GLsizeiptr (GL_APIENTRY *GLGETBLOBPROCANGLE)(const void *key, 64 GLsizeiptr keySize, 65 void *value, 66 GLsizeiptr valueSize, 67 const void *userParam); 68 69 typedef void (GL_APIENTRY *GLSETBLOBPROCANGLE)(const void *key, 70 GLsizeiptr keySize, 71 const void *value, 72 GLsizeiptr valueSize, 73 const void *userParam); 74 75 Note that these function pointers are defined as having the same calling 76 convention as the GL functions. 77 78New Tokens 79 80 Tokens accepted by the <pname> parameter of GetPointerv: 81 82 BLOB_CACHE_GET_FUNCTION_ANGLE 0x96BF 83 BLOB_CACHE_SET_FUNCTION_ANGLE 0x96EF 84 BLOB_CACHE_USER_PARAM_ANGLE 0x972D 85 86Additions to the OpenGL ES Specification 87 88 Add a new section after 18 Debug Output: 89 90 "Chapter 19 91 Persistent Caching 92 93 Application developers can set callback functions which GL may use for 94 getting and setting persistently cached data blobs. The command 95 96 void SetBlobCacheFuncsANGLE(SETBLOBPROCANGLE set, 97 GETBLOBPROCANGLE get, 98 const void* userParam); 99 100 stores the get and set callbacks and user parameter. Only one blob cache 101 get and set function can be installed on the current context. Specifying NULL 102 for the callbacks will clear the current callbacks and disable blob caching. 103 Applications can provide user-specified data through the pointer <userParam>. 104 The context will store this pointer and will include it as one of the parameters 105 in each call to the callback function. 106 107 Applications can query the current callback functions and the current 108 user-specified parameter by obtaining the values of 109 BLOB_CACHE_GET_FUNCTION_ANGLE, BLOB_CACHE_SET_FUNCTION_ANGLE and 110 BLOB_CACHE_USER_PARAM_ANGLE. 111 112 To insert a new binary value into the cache and associate it with a given 113 key, a GL context can call the application-provided callback function 114 115 sizeiptr get(const void *key, sizeiptr keySize, void *value, sizeiptr valueSize, 116 const void *userParam); 117 118 <key> and <value> are pointers to the beginning of the key and value, 119 respectively, that are to be inserted. <keySize> and <valueSize> specify 120 the size in bytes of the data pointed to by <key> and <value> respectively. 121 122 To retrieve the binary value associated with a given key from the cache, a 123 GL context can call the application-provided callback function 124 125 set(const void *key, sizeiptr keySize, const void *value, sizeiptr valueSize, 126 const void *userParam); 127 128 129 <key> is a pointer to the beginning of the key. <keySize> specifies the 130 size in bytes of the binary key pointed to by <key>. If the cache contains 131 a value associated with the given key then the size of that binary value in 132 bytes is returned. Otherwise 0 is returned. 133 134 If the cache contains a value for the given key and its size in bytes is 135 less than or equal to <valueSize> then the value is written to the memory 136 pointed to by <value>. Otherwise nothing is written to the memory pointed 137 to by <value>. 138 139 Additionally, these callbacks must be declared with the same platform-dependent 140 calling convention used in the definition of the type GLGETBLOBPROCANGLE and 141 GLSETBLOBPROCANGLE. Anything else will result in undefined behavior. 142 143Errors 144 145 An INVALID_OPERATION error is generated by SetBlobCacheFuncsANGLE if one of 146 <get> or <set> are NULL and the other is non-NULL. 147 148New State 149 150 Modify Table 21.57: Miscellaneous 151 152 Add: 153 154 Initial 155 Get Value Type Get Command Value Description 156 --------------------------------- ---- ----------- ------- --------------------- 157 GL_BLOB_CACHE_GET_FUNCTION_ANGLE Y GetPointerv NULL Blob cache getter function 158 GL_BLOB_CACHE_SET_FUNCTION_ANGLE Y GetPointerv NULL Blob cache setter function 159 GL_BLOB_CACHE_USER_PARAM_ANGLE Y GetPointerv NULL Blob cache callback user 160 data parameter 161 162Conformance Tests 163 164 TBD 165 166Issues 167 168 None 169 170Revision History 171 172 Rev. Date Author Changes 173 ---- ------------- --------- ---------------------------------------- 174 1 Oct 4, 2024 geofflang Initial version 175