| Name |
| |
| APPLE_fence |
| |
| Name Strings |
| |
| GL_APPLE_fence |
| |
| Contact |
| |
| Geoff Stahl, Apple (gstahl 'at' apple.com) |
| |
| Status |
| |
| Shipping as of August 24, 2002 (Mac OS X v10.2) |
| |
| Version |
| |
| $Date: 2002/08/23 00:31:45 $ $Revision: 1.3 $ |
| |
| Number |
| |
| 272 |
| |
| Dependencies |
| |
| None |
| |
| Overview |
| |
| This extension is provided a finer granularity of synchronizing GL command |
| completion than offered by standard OpenGL, which currently offers only two |
| mechanisms for synchronization: Flush and Finish. Since Flush merely assures |
| the user that the commands complete in a finite (though undetermined) amount |
| of time, it is, thus, of only modest utility. Finish, on the other hand, |
| stalls CPU execution until all pending GL commands have completed forcing |
| completely synchronous operation, which most often not the desired result. |
| This extension offers a middle ground - the ability to "finish" a subset of |
| the command stream, and the ability to determine whether a given command has |
| completed or not. |
| |
| This extension introduces the concept of a "fence" to the OpenGL command |
| stream with SetFenceAPPLE. Once the fence is inserted into the command |
| stream, it can be tested for its completion with TestFenceAPPLE. Moreover, |
| the application may also request a partial Finish up to a particular "fence" |
| using the FinishFenceAPPLE command -- that is, all commands prior to the |
| fence will be forced to complete until control is returned to the calling |
| process. These new mechanisms allow for synchronization between the host |
| CPU and the GPU, which may be accessing the same resources (typically |
| memory). |
| |
| Fences are created and deleted, as are other objects in OpenGL, specifically |
| with GenFencesAPPLE and DeleteFencesAPPLE. The former returns a list of |
| unused fence names and the later deletes the provided list of fence names. |
| |
| In addition to being able to test or finish a fence this extension allows |
| testing for other types of completion, including texture objects, vertex |
| array objects, and draw pixels. This allows the client to use |
| TestObjectAPPLE or FinishObjectAPPLE with FENCE_APPLE, TEXTURE, |
| VERTEX_ARRAY, or DRAW_PIXELS_APPLE with the same type of results as |
| TestFenceAPPLE and FinishFenceAPPLE. Specifically, using the FENCE_APPLE |
| type is equivalent to calling TestFenceAPPLE or FinishFenceAPPLE with the |
| particular fence name. Using TEXTURE as the object type tests or waits for |
| completion of a specific texture, meaning when there are no pending |
| rendering commands which use that texture object. Using the VERTEX_ARRAY |
| type will test or wait for drawing commands using that particular vertex |
| array object name. Finally, DRAW_PIXELS_APPLE will wait or test for |
| completion of all pending DrawPixels commands. These tests and finishes |
| operate with the same limitations and results as test and finish fence. |
| |
| One use of this extension is in conjunction with APPLE_vertex_array_range to |
| determine when graphics hardware has completed accessing vertex data from a |
| vertex array range. Once a fence has been tested TRUE or finished, all |
| vertex indices issued before the fence must have completed being accessed. |
| This ensures that the vertex data memory corresponding to the issued vertex |
| indices can be safely modified (assuming no other outstanding vertex indices |
| are issued subsequent to the fence). |
| |
| Issues |
| |
| How is TestObjectAPPLE or FinishObjectAPPLE used with DRAW_PIXELS_APPLE? |
| |
| Resolution: Currently there is no support DrawPixels with storage using |
| the APPLE_client_storage extension and thus this option has no utility, |
| due to implementation specifics, which always copy the DrawPixels |
| buffer, thus allowing the client to immediately modify the data used by |
| DrawPixels. Once the APPLE_client_storage extension is supported, |
| DrawPixels modification synchronization will be required after drawing |
| with a buffer, which resides in client space. |
| |
| Do we need an IsFenceAPPLE command? |
| |
| RESOLUTION: Yes. IsFenceAPPLE makes APPLE_fence's API orthogonal to |
| other OpenGL object interfaces, and can be used as any other Is... |
| command would be. |
| |
| Are the fences sharable between multiple contexts? |
| |
| RESOLUTION: No. |
| |
| What is the relative performance of the calls? |
| |
| Execution of a SetFenceAPPLE is not free. In the initial |
| implementation, a Flush is generated. This will likely change for |
| future implementations and should not be depended on. A Finish will not |
| be generated in any case. |
| |
| Is the TestFenceAPPLE call really necessary? How often would this be used |
| compared to the FinishFenceAPPLE call (which also flushes to ensure this |
| happens in finite time)? |
| |
| TestFenceAPPLE allows clients to provide logic to handle |
| synchronization issues rather than forcing completely synchronous |
| operation at the point of testing or finishing. |
| |
| Should we allow these commands to be compiled within display list? |
| Which ones? How about within Begin/End pairs? |
| |
| RESOLUTION: DeleteFencesAPPLE, GenFencesAPPLE, TestFenceAPPLE, |
| TestObjectAPPLE, and IsFenceAPPLE are executed immediately while |
| FinishFenceAPPLE, FinishObjectAPPLE and SetFenceAPPLE are compiled. |
| None of these commands are allowed within Begin/End pairs. |
| |
| New Procedures and Functions |
| |
| void GenFencesAPPLE(sizei n, uint *fences); |
| |
| void DeleteFencesAPPLE(sizei n, const uint *fences); |
| |
| void SetFenceAPPLE(uint fence); |
| |
| boolean IsFenceAPPLE(uint fence); |
| |
| boolean TestFenceAPPLE(uint fence); |
| |
| void FinishFenceAPPLE(uint fence); |
| |
| boolean TestObjectAPPLE(enum object, uint name); |
| |
| void FinishObjectAPPLE(enum object, int name); |
| |
| New Tokens |
| |
| Accepted by the <object> parameter of TestObjectAPPLE and FinishObjectAPPLE: |
| |
| DRAW_PIXELS_APPLE 0x8A0A |
| FENCE_APPLE 0x8A0B |
| |
| Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions) |
| |
| Add to the end of Section 5.4 "Display Lists" |
| |
| "DeleteFencesAPPLE, GenFencesAPPLE, TestFenceAPPLE, IsFenceAPPLE, and |
| TestObjectAPPLE are not complied into display lists but are executed |
| immediately." |
| |
| After the discussion of Flush and Finish (Section 5.5) add a |
| description of the fence operations: |
| |
| "5.X Fences |
| |
| The command |
| |
| void SetFenceAPPLE(uint fence); |
| |
| sets a fence within the GL command stream and assigns the fence a status of |
| FALSE. No other state is affected by execution of the fence command. A |
| fence's state can be queried by calling the command |
| |
| boolean TestFenceAPPLE(uint fence); |
| |
| The command |
| |
| void FinishFenceAPPLE(uint fence); |
| |
| forces all GL commands prior to the fence to complete. FinishFenceAPPLE does |
| not return until all effects from these commands on GL client and server |
| state and the frame buffer are fully realized. |
| |
| The fence must first be created before it can be used. The command |
| |
| void GenFencesAPPLE(sizei n, uint *fences); |
| |
| returns n previously unused fence names in fences. These names are marked |
| as used for the purposes of GenFencesAPPLE only and acquire boolean state |
| only when they have been set. |
| |
| Fences are deleted by calling |
| |
| void DeleteFencesAPPLE(sizei n, const uint *fences); |
| |
| fences contains n names of fences to be deleted. After a fence is deleted, |
| it has no state, and its name is again unused. Unused names in fences are |
| silently ignored. |
| |
| If the fence passed to TestFenceAPPLE or FinishFenceAPPLE is not the name of |
| a fence, the error INVALID_OPERATION is generated. In this case, |
| TestFenceAPPLE will return TRUE, for the sake of consistency. Note, fences |
| that have note been set prior to calling TestFenceAPPLE or FinishFenceAPPLE |
| act as if the state is TRUE and the fence command has already been |
| completed. In other words TestFenceAPPLE returns TRUE and FinishFenceAPPLE |
| will not block on fences that have not been set. |
| |
| State must be maintained to indicate which fence integers are currently used |
| or set. In the initial state, no indices are in use. When a fence integer |
| is set, status of the fence is also maintained. The status is a boolean. |
| |
| Once the status of a fence has been finished (via FinishFenceAPPLE) or |
| tested and the returned status is TRUE (via TestFenceAPPLE), the status |
| remains TRUE until the next SetFenceAPPLE of the fence. |
| |
| The command |
| |
| boolean TestObjectAPPLE(enum object, uint name); |
| |
| and the command |
| |
| void FinishObjectAPPLE(enum object, int name); |
| |
| work in a similar fashion to TestFenceAPPLE and FinishFenceAPPLE but on |
| other types of "objects". Both of these commands take an object, which can |
| be FENCE_APPLE, TEXTURE, VERTEX_ARRAY, or DRAW_PIXELS_APPLE and an object |
| name. These commands are useful for synchronizing the update of buffers for |
| textures, draw pixels, or vertex arrays, especially when using extensions |
| such as Apple's vertex array range or client storage. |
| |
| If the object parameter for TestObjectAPPLE or FinishObjectAPPLE is |
| FENCE_APPLE then these commands work in exactly the same manner as |
| TestFenceAPPLE and FinishFenceAPPLE, respectively. If the object parameter |
| is TEXTURE then these routines test or finish the use of a texture object, |
| thus FinishObjectAPPLE will block and TestFenceAPPLE will return FALSE while |
| there are pending rendering commands utilizing the texture object in |
| question. If the object parameter is VERTEX_ARRAY, FinishObjectAPPLE will |
| block and TestFenceAPPLE will return FALSE while there are pending rendering |
| commands utilizing the vertex array object in question. Note, in both these |
| cases object name 0 will work as expected, thus testing or finishing the |
| default texture or vertex array object. If the object parameter is |
| DRAW_PIXELS_APPLE, FinishObjectAPPLE will block and TestFenceAPPLE will |
| return FALSE while there are pending DrawPixels commands. For all other |
| cases, assuming a valid object type and name are used, FinishObjectAPPLE |
| will return immediately and TestFenceAPPLE will return TRUE. |
| |
| INVALID_OPERATION error is generated if FinishObjectAPPLE or TestFenceAPPLE |
| is called with either an invalid object type enumeration or a name, which is |
| not the name of a valid object of the type specified in the object |
| parameter. |
| |
| Additions to Chapter 6 of the OpenGL 1.2.1 Specification (State and State Requests) |
| |
| Insert new section after Section 6.1.10 "Minmax Query" |
| |
| "6.1.11 Fence Query |
| |
| The command |
| |
| boolean IsFenceAPPLE(uint fence); |
| |
| returns TRUE if texture is the name of a fence. If fence is not the name of |
| a fence, or if an error condition occurs, IsFenceAPPLE returns FALSE. A |
| name returned by GenFencesAPPLE, but not yet set via SetFenceAPPLE, is not |
| the name of a fence. |
| |
| Additions to the GLX Specification |
| |
| None |
| |
| GLX Protocol |
| |
| None |
| |
| Errors |
| |
| INVALID_VALUE is generated if GenFencesAPPLE parameter <n> is negative. |
| |
| INVALID_VALUE is generated if DeleteFencesAPPLE parameter <n> is negative. |
| |
| INVALID_OPERATION is generated if the fence used in TestFenceAPPLE or |
| FinishFenceAPPLE is not the name of a fence. |
| |
| INVALID_OPERATION is generated if the object name used in TestObjectAPPLE or |
| FinishObjectAPPLE is not the name of an object of the type requested in the |
| object parameter. |
| |
| INVALID_OPERATION is generated if any of the commands defined in |
| this extension is executed between the execution of Begin and the |
| corresponding execution of End. |
| |
| INVALID_VALUE is generated if DeleteFencesAPPLE or GenFencesAPPLE are |
| called where n is negative. |
| |
| New State |
| |
| None |
| |
| New Implementation Dependent State |
| |
| None |
| |
| Implementation Details |
| |
| This section describes implementation-defined limits: |
| |
| SetFenceAPPLE calls are not free. They should be used prudently, and a |
| "good number" of commands should be sent between calls to SetFenceAPPLE. |
| Testing or finishing a fence may cause a Flush if commands up to the |
| fence being tested have not been submitted to the hardware. |
| |
| Revision History |
| |
| None |
| |