1Name 2 3 APPLE_fence 4 5Name Strings 6 7 GL_APPLE_fence 8 9Contact 10 11 Geoff Stahl, Apple (gstahl 'at' apple.com) 12 13Status 14 15 Shipping as of August 24, 2002 (Mac OS X v10.2) 16 17Version 18 19 $Date: 2002/08/23 00:31:45 $ $Revision: 1.3 $ 20 21Number 22 23 272 24 25Dependencies 26 27 None 28 29Overview 30 31 This extension is provided a finer granularity of synchronizing GL command 32 completion than offered by standard OpenGL, which currently offers only two 33 mechanisms for synchronization: Flush and Finish. Since Flush merely assures 34 the user that the commands complete in a finite (though undetermined) amount 35 of time, it is, thus, of only modest utility. Finish, on the other hand, 36 stalls CPU execution until all pending GL commands have completed forcing 37 completely synchronous operation, which most often not the desired result. 38 This extension offers a middle ground - the ability to "finish" a subset of 39 the command stream, and the ability to determine whether a given command has 40 completed or not. 41 42 This extension introduces the concept of a "fence" to the OpenGL command 43 stream with SetFenceAPPLE. Once the fence is inserted into the command 44 stream, it can be tested for its completion with TestFenceAPPLE. Moreover, 45 the application may also request a partial Finish up to a particular "fence" 46 using the FinishFenceAPPLE command -- that is, all commands prior to the 47 fence will be forced to complete until control is returned to the calling 48 process. These new mechanisms allow for synchronization between the host 49 CPU and the GPU, which may be accessing the same resources (typically 50 memory). 51 52 Fences are created and deleted, as are other objects in OpenGL, specifically 53 with GenFencesAPPLE and DeleteFencesAPPLE. The former returns a list of 54 unused fence names and the later deletes the provided list of fence names. 55 56 In addition to being able to test or finish a fence this extension allows 57 testing for other types of completion, including texture objects, vertex 58 array objects, and draw pixels. This allows the client to use 59 TestObjectAPPLE or FinishObjectAPPLE with FENCE_APPLE, TEXTURE, 60 VERTEX_ARRAY, or DRAW_PIXELS_APPLE with the same type of results as 61 TestFenceAPPLE and FinishFenceAPPLE. Specifically, using the FENCE_APPLE 62 type is equivalent to calling TestFenceAPPLE or FinishFenceAPPLE with the 63 particular fence name. Using TEXTURE as the object type tests or waits for 64 completion of a specific texture, meaning when there are no pending 65 rendering commands which use that texture object. Using the VERTEX_ARRAY 66 type will test or wait for drawing commands using that particular vertex 67 array object name. Finally, DRAW_PIXELS_APPLE will wait or test for 68 completion of all pending DrawPixels commands. These tests and finishes 69 operate with the same limitations and results as test and finish fence. 70 71 One use of this extension is in conjunction with APPLE_vertex_array_range to 72 determine when graphics hardware has completed accessing vertex data from a 73 vertex array range. Once a fence has been tested TRUE or finished, all 74 vertex indices issued before the fence must have completed being accessed. 75 This ensures that the vertex data memory corresponding to the issued vertex 76 indices can be safely modified (assuming no other outstanding vertex indices 77 are issued subsequent to the fence). 78 79Issues 80 81 How is TestObjectAPPLE or FinishObjectAPPLE used with DRAW_PIXELS_APPLE? 82 83 Resolution: Currently there is no support DrawPixels with storage using 84 the APPLE_client_storage extension and thus this option has no utility, 85 due to implementation specifics, which always copy the DrawPixels 86 buffer, thus allowing the client to immediately modify the data used by 87 DrawPixels. Once the APPLE_client_storage extension is supported, 88 DrawPixels modification synchronization will be required after drawing 89 with a buffer, which resides in client space. 90 91 Do we need an IsFenceAPPLE command? 92 93 RESOLUTION: Yes. IsFenceAPPLE makes APPLE_fence's API orthogonal to 94 other OpenGL object interfaces, and can be used as any other Is... 95 command would be. 96 97 Are the fences sharable between multiple contexts? 98 99 RESOLUTION: No. 100 101 What is the relative performance of the calls? 102 103 Execution of a SetFenceAPPLE is not free. In the initial 104 implementation, a Flush is generated. This will likely change for 105 future implementations and should not be depended on. A Finish will not 106 be generated in any case. 107 108 Is the TestFenceAPPLE call really necessary? How often would this be used 109 compared to the FinishFenceAPPLE call (which also flushes to ensure this 110 happens in finite time)? 111 112 TestFenceAPPLE allows clients to provide logic to handle 113 synchronization issues rather than forcing completely synchronous 114 operation at the point of testing or finishing. 115 116 Should we allow these commands to be compiled within display list? 117 Which ones? How about within Begin/End pairs? 118 119 RESOLUTION: DeleteFencesAPPLE, GenFencesAPPLE, TestFenceAPPLE, 120 TestObjectAPPLE, and IsFenceAPPLE are executed immediately while 121 FinishFenceAPPLE, FinishObjectAPPLE and SetFenceAPPLE are compiled. 122 None of these commands are allowed within Begin/End pairs. 123 124New Procedures and Functions 125 126 void GenFencesAPPLE(sizei n, uint *fences); 127 128 void DeleteFencesAPPLE(sizei n, const uint *fences); 129 130 void SetFenceAPPLE(uint fence); 131 132 boolean IsFenceAPPLE(uint fence); 133 134 boolean TestFenceAPPLE(uint fence); 135 136 void FinishFenceAPPLE(uint fence); 137 138 boolean TestObjectAPPLE(enum object, uint name); 139 140 void FinishObjectAPPLE(enum object, int name); 141 142New Tokens 143 144 Accepted by the <object> parameter of TestObjectAPPLE and FinishObjectAPPLE: 145 146 DRAW_PIXELS_APPLE 0x8A0A 147 FENCE_APPLE 0x8A0B 148 149Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions) 150 151 Add to the end of Section 5.4 "Display Lists" 152 153 "DeleteFencesAPPLE, GenFencesAPPLE, TestFenceAPPLE, IsFenceAPPLE, and 154 TestObjectAPPLE are not complied into display lists but are executed 155 immediately." 156 157 After the discussion of Flush and Finish (Section 5.5) add a 158 description of the fence operations: 159 160 "5.X Fences 161 162 The command 163 164 void SetFenceAPPLE(uint fence); 165 166 sets a fence within the GL command stream and assigns the fence a status of 167 FALSE. No other state is affected by execution of the fence command. A 168 fence's state can be queried by calling the command 169 170 boolean TestFenceAPPLE(uint fence); 171 172 The command 173 174 void FinishFenceAPPLE(uint fence); 175 176 forces all GL commands prior to the fence to complete. FinishFenceAPPLE does 177 not return until all effects from these commands on GL client and server 178 state and the frame buffer are fully realized. 179 180 The fence must first be created before it can be used. The command 181 182 void GenFencesAPPLE(sizei n, uint *fences); 183 184 returns n previously unused fence names in fences. These names are marked 185 as used for the purposes of GenFencesAPPLE only and acquire boolean state 186 only when they have been set. 187 188 Fences are deleted by calling 189 190 void DeleteFencesAPPLE(sizei n, const uint *fences); 191 192 fences contains n names of fences to be deleted. After a fence is deleted, 193 it has no state, and its name is again unused. Unused names in fences are 194 silently ignored. 195 196 If the fence passed to TestFenceAPPLE or FinishFenceAPPLE is not the name of 197 a fence, the error INVALID_OPERATION is generated. In this case, 198 TestFenceAPPLE will return TRUE, for the sake of consistency. Note, fences 199 that have note been set prior to calling TestFenceAPPLE or FinishFenceAPPLE 200 act as if the state is TRUE and the fence command has already been 201 completed. In other words TestFenceAPPLE returns TRUE and FinishFenceAPPLE 202 will not block on fences that have not been set. 203 204 State must be maintained to indicate which fence integers are currently used 205 or set. In the initial state, no indices are in use. When a fence integer 206 is set, status of the fence is also maintained. The status is a boolean. 207 208 Once the status of a fence has been finished (via FinishFenceAPPLE) or 209 tested and the returned status is TRUE (via TestFenceAPPLE), the status 210 remains TRUE until the next SetFenceAPPLE of the fence. 211 212 The command 213 214 boolean TestObjectAPPLE(enum object, uint name); 215 216 and the command 217 218 void FinishObjectAPPLE(enum object, int name); 219 220 work in a similar fashion to TestFenceAPPLE and FinishFenceAPPLE but on 221 other types of "objects". Both of these commands take an object, which can 222 be FENCE_APPLE, TEXTURE, VERTEX_ARRAY, or DRAW_PIXELS_APPLE and an object 223 name. These commands are useful for synchronizing the update of buffers for 224 textures, draw pixels, or vertex arrays, especially when using extensions 225 such as Apple's vertex array range or client storage. 226 227 If the object parameter for TestObjectAPPLE or FinishObjectAPPLE is 228 FENCE_APPLE then these commands work in exactly the same manner as 229 TestFenceAPPLE and FinishFenceAPPLE, respectively. If the object parameter 230 is TEXTURE then these routines test or finish the use of a texture object, 231 thus FinishObjectAPPLE will block and TestFenceAPPLE will return FALSE while 232 there are pending rendering commands utilizing the texture object in 233 question. If the object parameter is VERTEX_ARRAY, FinishObjectAPPLE will 234 block and TestFenceAPPLE will return FALSE while there are pending rendering 235 commands utilizing the vertex array object in question. Note, in both these 236 cases object name 0 will work as expected, thus testing or finishing the 237 default texture or vertex array object. If the object parameter is 238 DRAW_PIXELS_APPLE, FinishObjectAPPLE will block and TestFenceAPPLE will 239 return FALSE while there are pending DrawPixels commands. For all other 240 cases, assuming a valid object type and name are used, FinishObjectAPPLE 241 will return immediately and TestFenceAPPLE will return TRUE. 242 243 INVALID_OPERATION error is generated if FinishObjectAPPLE or TestFenceAPPLE 244 is called with either an invalid object type enumeration or a name, which is 245 not the name of a valid object of the type specified in the object 246 parameter. 247 248Additions to Chapter 6 of the OpenGL 1.2.1 Specification (State and State Requests) 249 250 Insert new section after Section 6.1.10 "Minmax Query" 251 252 "6.1.11 Fence Query 253 254 The command 255 256 boolean IsFenceAPPLE(uint fence); 257 258 returns TRUE if texture is the name of a fence. If fence is not the name of 259 a fence, or if an error condition occurs, IsFenceAPPLE returns FALSE. A 260 name returned by GenFencesAPPLE, but not yet set via SetFenceAPPLE, is not 261 the name of a fence. 262 263Additions to the GLX Specification 264 265 None 266 267GLX Protocol 268 269 None 270 271Errors 272 273 INVALID_VALUE is generated if GenFencesAPPLE parameter <n> is negative. 274 275 INVALID_VALUE is generated if DeleteFencesAPPLE parameter <n> is negative. 276 277 INVALID_OPERATION is generated if the fence used in TestFenceAPPLE or 278 FinishFenceAPPLE is not the name of a fence. 279 280 INVALID_OPERATION is generated if the object name used in TestObjectAPPLE or 281 FinishObjectAPPLE is not the name of an object of the type requested in the 282 object parameter. 283 284 INVALID_OPERATION is generated if any of the commands defined in 285 this extension is executed between the execution of Begin and the 286 corresponding execution of End. 287 288 INVALID_VALUE is generated if DeleteFencesAPPLE or GenFencesAPPLE are 289 called where n is negative. 290 291New State 292 293 None 294 295New Implementation Dependent State 296 297 None 298 299Implementation Details 300 301 This section describes implementation-defined limits: 302 303 SetFenceAPPLE calls are not free. They should be used prudently, and a 304 "good number" of commands should be sent between calls to SetFenceAPPLE. 305 Testing or finishing a fence may cause a Flush if commands up to the 306 fence being tested have not been submitted to the hardware. 307 308Revision History 309 310 None 311 312