• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1Name
2
3    NV_timeline_semaphore
4
5Name Strings
6
7    GL_NV_timeline_semaphore
8
9Contributors
10
11    Carsten Rohde, NVIDIA
12    James Jones, NVIDIA
13
14Contact
15
16    Carsten Rohde, NVIDIA Corporation (crohde 'at' nvidia.com)
17
18Status
19
20    Complete
21
22Version
23
24    Last Modified Date: Jul 10, 2020
25    Revision:           1
26
27Number
28
29    551
30    OpenGL ES Extension #330
31
32Dependencies
33
34    Written against the OpenGL 4.6 and OpenGL ES 3.2 specifications.
35
36    GL_NV_timeline_semaphore requires GL_EXT_semaphore or a version of
37    OpenGL or OpenGL ES that incorporates it.
38
39Overview
40
41    The Vulkan API introduces the concept of timeline semaphores.
42    This extension brings those concepts to the OpenGL API by adding
43    a semaphore type to the semaphore object. In OpenGL, timeline semaphore
44    signal and wait operations are similar to the corresponding operations on
45    imported Direct3D 12 fences defined in EXT_external_objects_win32.
46
47New Procedures and Functions
48
49    void CreateSemaphoresNV(sizei n, uint *semaphores);
50
51    void SemaphoreParameterivNV(uint semaphore,
52                                enum pname,
53                                const GLint *params);
54
55    void GetSemaphoreParameterivNV(uint semaphore,
56                                   enum pname,
57                                   int *params);
58
59New Tokens
60
61    Accepted by the <pname> parameter of SemaphoreParameterivNV
62    and GetSemaphoreParameterivNV:
63
64        SEMAPHORE_TYPE_NV                           0x95B3
65
66    Accepted by the <param> parameter of SemaphoreParameterivNV and
67    GetSemaphoreParameterivNV when <pname> parameter is SEMAPHORE_TYPE_NV:
68
69        SEMAPHORE_TYPE_BINARY_NV                    0x95B4
70        SEMAPHORE_TYPE_TIMELINE_NV                  0x95B5
71
72    Accepted by the <pname> parameter of SemaphoreParameterui64vNV
73    and GetSemaphoreParameterui64vNV:
74
75        TIMELINE_SEMAPHORE_VALUE_NV                 0x9595
76
77    Accepted by the <pname> parameter to GetIntegerv, GetFloatv, GetDoublev,
78    GetInteger64v, and GetBooleanv:
79
80        MAX_TIMELINE_SEMAPHORE_VALUE_DIFFERENCE_NV  0x95B6
81
82
83Additions to Chapter 4 of the OpenGL 4.6 Specification (Event Model)
84
85    Add the following to section 4.2 Semaphore Objects after paragraph
86    which describes command GenSemaphoresEXT:
87
88        The command
89
90            void CreateSemaphoresNV(sizei n,
91                                    uint *semaphores);
92
93        returns <n> previously unused semaphore names in <semaphores>.
94        The semaphores named contain default state, but initially have no
95        external semaphores associated with them.
96
97    Replace section 4.2.2 Semaphore Parameters with the following:
98
99        Semaphore parameters control the type of the semaphore and how
100        semaphore wait and signal operations behave.
101        Table 4.3 defines which parameters are available for a semaphore
102        based on the external handle type from which it was imported.
103        Semaphore parameters are set using the commands
104
105            void SemaphoreParameterivNV(uint semaphore,
106                                        enum pname,
107                                        const int *params);
108
109        and
110
111            void SemaphoreParameterui64vEXT(uint semaphore,
112                                            enum pname,
113                                            const uint64 *params);
114
115        <semaphore> is the name of the semaphore object on which the
116        parameter <pname> will be set to the value(s) in <pname>.
117
118        Table 4.3: Semaphore parameters
119
120        | Name                        | Handle Types                | Legal Values                         |
121        +-----------------------------+-----------------------------+--------------------------------------+
122        | SEMAPHORE_TYPE_NV           | any handle type             | SEMAPHORE_TYPE_BINARY_NV (default)   |
123        |                             |                             | SEMAPHORE_TYPE_TIMELINE_NV           |
124        +-----------------------------+-----------------------------+--------------------------------------+
125        | TIMELINE_SEMAPHORE_VALUE_NV | any handle type             | any value                            |
126        +-----------------------------+-----------------------------+--------------------------------------+
127
128        The default type of a semaphore is SEMAPHORE_TYPE_BINARY_NV. Only when the semaphore is imported
129        from a D3D fence, the semaphore type defaults to SEMAPHORE_TYPE_TIMELINE_NV.
130
131        Parameters of a semaphore object may be queried with the commands
132
133            void GetSemaphoreParameteriEXT(uint semaphore,
134                                           enum pname,
135                                           uint64 *params);
136
137        and
138
139            void GetSemaphoreParameterui64EXT(uint semaphore,
140                                              enum pname,
141                                              uint64 *params);
142
143        <semaphore> is the semaphore object from with the parameter <pname>
144        is queried.  The value(s) of the parameter are returned in <params>.
145        <pname> may be any value in table 4.3.
146
147    Add the following after the first paragraph of section 4.2.3 "Waiting
148    for Semaphores"
149
150        If <semaphore> is of the type SEMAPHORE_TYPE_TIMELINE_NV, it will
151        reach the signaled state when its value is greater than or equal
152        to the value specified by its TIMELINE_SEMAPHORE_VALUE_NV parameter.
153
154    Add the following at the end of section 4.2.3 "Waiting for Semaphores":
155
156        When using binary semaphores, for every wait on a semaphore there must
157        be a prior signal of that semaphore that will not be consumed by a
158        different wait on the semaphore.
159        When using timeline semaphores, wait-before-signal behavior is
160        well-defined and applications can wait for semaphore before the
161        corresponding semaphore signal operation is flushed.
162
163        MAX_TIMELINE_SEMAPHORE_VALUE_DIFFERENCE_NV indicates the maximum
164        difference allowed by the implementation between the current value
165        of a timeline semaphore and any pending wait operations
166
167    Add the following after the first paragraph of section 4.2.4 "Signaling
168    Semaphores"
169
170        If <semaphore> is of the type SEMAPHORE_TYPE_TIMELINE_NV, its value
171        will be set to the value specified by its TIMELINE_SEMAPHORE_VALUE_NV
172        parameter when the signal operation completes.
173
174    Add the following at the end of section 4.2.4 "Signaling for Semaphores":
175
176        MAX_TIMELINE_SEMAPHORE_VALUE_DIFFERENCE_NV indicates the maximum
177        difference allowed by the implementation between the current value
178        of a timeline semaphore and any pending signal operations.
179
180
181Example
182
183    GLuint semapohre;
184    glCreateSemaphoresNV(1, &semaphore);
185    GLenum semaphoreType = GL_SEMAPHORE_TYPE_TIMELINE_NV;
186    glSemaphoreParameterivNV(semaphore, GL_SEMAPHORE_TYPE_NV, (GLint*)&semaphoreType);
187    glImportSemaphoreFdEXT(semaphore, GL_HANDLE_TYPE_OPAQUE_FD_EXT, fd); // or win32 equivalent
188
189    GLuint64 semaphoreValue = 0;
190
191    while (...) {
192        glSemaphoreParameterui64vEXT(semaphore, GL_TIMELINE_SEMAPHORE_VALUE_NV, &semaphoreValue);
193        glWaitSemaphoreEXT(semaphore, ...);
194
195        ...
196
197        semaphoreValue ++;
198        glSemaphoreParameterui64vEXT(semaphore, GL_TIMELINE_SEMAPHORE_VALUE_NV, &semaphoreValue);
199        glSignalSemaphoreEXT(semaphore, ...);
200    }
201
202    glDeleteSemaphoresEXT(1, &semaphore);
203
204
205Issues
206
207    (1) Should we add client functions to signal and wait for the semaphore on
208        the CPU?
209
210        RESOLVED: No. We already declined to add external Vulkan fence interop
211                  with GL on the basis that you can just do that with Vulkan
212                  if you need it.
213
214    (2) Should GetIntegerv and GetBooleanv be allowed to query
215        MAX_TIMELINE_SEMAPHORE_VALUE_DIFFERENCE_NV?
216
217        RESOLVED: Yes. Although it's dangerous to use them they don't throw an
218                  error but you are advised to use GetInteger64v.
219
220Revision History
221
222    Revision 1, 2020-07-10 (Carsten Rohde)
223        - Initial draft.
224