• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1Name
2
3    EXT_x11_sync_object
4
5Name Strings
6
7    GL_EXT_x11_sync_object
8
9Contributors
10
11    Piers Daniell
12    Pierre-Loup Griffais
13    James Jones
14    Aaron Plattner
15
16Contact
17
18    James Jones, NVIDIA corporation (jajones 'at' nvidia.com)
19
20Status
21
22    Complete.
23
24Version
25
26    Last Modified Date: Jan 26, 2011
27    Author Revision: 2
28
29Number
30
31    406
32
33Dependencies
34
35    OpenGL 3.2, or an earlier OpenGL version supporting the ARB_sync
36    extension, is required.
37
38    Written based on the wording of the OpenGL 3.2 specification.
39
40    ARB_cl_event trivially affects the definition of this extension.
41
42    This extension is only supported with contexts created on an X11
43    display that supports the X Synchronization Extension version 3.1 or
44    later.
45
46Overview
47
48    Synchronization objects added the ability to better coordinate
49    operations between multiple GL command streams.  However, it is
50    desirable to have the same level of coordination between GL
51    command streams and external rendering APIs.  This extension
52    introduces two new concepts to build upon the synchronization
53    infrastructure provided by ARB_sync:
54
55      1) A means to import an X Synchronization Fence object into the
56         GL and use it as a sync object.
57
58      2) The concept of a reusable sync object.
59
60    The latter is necessary because the import operation is expensive
61    and performing it every time a synchronization point was reached
62    would make the synchronization prohibitively slow.
63
64    This extension stops short of allowing the GL to change the state
65    of imported/reusable sync objects, but does not add any language
66    that would prohibit such functionality from being added in a
67    subsequent extension.
68
69New Procedures and Functions
70
71    sync ImportSyncEXT(enum external_sync_type,
72                       intptr external_sync,
73                       bitfield flags);
74
75New Types
76
77    None
78
79New Tokens
80
81    Accepted by the <external_sync_type> parameter of
82    ImportSyncEXT:
83
84        SYNC_X11_FENCE_EXT                         0x90E1
85
86Additions to Chapter 2 of the OpenGL 3.2 Specification (OpenGL
87Operation)
88
89    None
90
91Additions to Chapter 3 of the OpenGL 3.2 Specification (Rasterization)
92
93    None
94
95Additions to Chapter 4 of the OpenGL 3.2 Specification (Per-Fragment
96Operations and the Framebuffer)
97
98    None
99
100Additions to Chapter 5 of the OpenGL 3.2 Specification (Special
101Functions)
102
103  Modify Section 5.2 "Sync Objects and Fences" (p. 241)
104
105  (Add after the seventh paragraph, p. 242)
106
107    "Additional types of sync objects can be imported from external
108    APIs. The command
109
110        sync ImportSyncEXT(enum external_sync_type,
111                           intptr external_sync,
112                           bitfield flags);
113
114    creates a GL sync object of the type <external_sync_type> based on
115    the object referred to by <external_sync>.
116
117    "<external_sync_type> must be SYNC_X11_FENCE_EXT, and
118    <external_sync> must be the XID of a valid X11 Synchronization Fence
119    object.  The status of the sync object returned will be SIGNALED
120    when the X object is in the triggered state, or UNSIGNALED
121    otherwise.
122
123    "<flags> must be 0."
124
125  (Replace the last sentence of paragraph 8, p. 242)
126
127    "The initial property values for a sync object created by FenceSync
128    or ImportSyncEXT are shown in tables 5.1 or 5.2 respectively.  A
129    sync object created using ImportSyncEXT should hold a reference to
130    any external resources needed to maintain the GL state associated
131    with the GL object should the external object be destroyed."
132
133  (Replace paragraph 9 with the following, p. 242)
134
135    "If FenceSync or ImportSyncEXT fail to create a sync object, zero
136    will be returned and a GL error will be generated as described. An
137    INVALID_ENUM error is generated if <condition> is not
138    SYNC_GPU_COMMANDS_COMPLETE or <external_sync_type> is not
139    SYNC_X11_FENCE_EXT.  If <flags> is not zero, or if <external_sync>
140    does not refer to a valid X Synchronization Fence object, an
141    INVALID_VALUE error is generated.
142
143    "However, implementations are not required to validate
144    <external_sync>, and passing an invalid external sync object handle
145    may result in undefined behavior up to and including program
146    termination."
147
148  (Add table 5.2 immediately following table 5.1, p. 243)
149
150    Property Name             Property Value
151    ------------------------  -------------------------------------
152    OBJECT_TYPE               <external_sync_type>
153    SYNC_CONDITION            NONE
154    SYNC_STATUS               dependent on state of <external_sync>
155    SYNC_FLAGS                <flags>
156
157    Table 5.2: Initial properties of a sync object created with
158    ImportSyncEXT.
159
160  (Replace paragraph 12 with the following, p. 243)
161
162    "If <sync> is in the signaled state, or if no ClientWaitSync or
163    WaitSync commands are blocking on <sync>, the object is deleted
164    immediately.  Otherwise, <sync> is flagged for deletion and will be
165    deleted when it reaches the signaled state and is no longer blocking
166    any ClientWaitSync or WaitSync command.  In either case, after
167    returning from DeleteSync the <sync> name is invalid and can no
168    longer be used to refer to the sync object.
169
170  Modify section 5.2.2 "Signaling" (p. 245)
171
172  (Replace the first paragraph with the following, p. 245)
173
174    "A sync object enters the signaled state only once the corresponding
175    fence command has completed and signaled the sync object, or the
176    external sync object associated with it has reached a state
177    corresponding to the GL signaled state as described in table 5.3."
178
179  (Add table 5.3)
180
181    OBJECT_TYPE         External state corresponding to GL signaled state
182    ------------------  -------------------------------------------------
183    SYNC_X11_FENCE_EXT  triggered
184
185  (Replace the last sentence of the last paragraph with the following,
186  p. 246)
187
188    "Additionally, sync objects linked to external sync objects require
189    implementation-specific, non-queriable internal state uniquely
190    identifying the external object.  The initial values of sync object
191    state are defined as specified by FenceSync and ImportSyncEXT."
192
193Additions to Chapter 6 of the OpenGL 3.2 Specification (State and State
194Requests)
195
196  Modify section 6.1.7 "Sync Object State" (p. 256)
197
198  (Replace the last sentence of paragraph 4 with the following, p. 256)
199
200    "The only types supported are SYNC_FENCE and SYNC_X11_FENCE_EXT."
201
202Additions to Appendix D of the OpenGL 3.2 Specification (Shared Objects
203and Multiple Contexts)
204
205  Modify section D.1.2 "Deleted Object and Object Name Lifetimes"
206  (p. 324)
207
208  Replace sentence 3 in the first paragraph with the following, (p. 324)
209
210    "A sync object is in use while it is not in the signaled state, or
211    while there are any GL clients and/or servers blocked on the sync
212    object as a result of ClientWaitSync or WaitSync commands."
213
214GLX Protocol
215
216    TBD
217
218Dependencies on ARB_sync
219
220    ARB_sync or GL version 3.2 or above are required to implement this
221    extension.
222
223Dependencies on ARB_cl_event
224
225    If ARB_cl_event is present, the language of the two specs must be
226    merged.  There should be no technical conflicts, but the actual
227    text modifications overlap.
228
229Errors
230
231    The error INVALID_ENUM is generated if ImportSyncEXT is called
232    where <external_sync_type> is not SYNC_X11_FENCE_EXT.
233
234    The error INVALID_VALUE is generated if ImportSyncEXT is called
235    where <external_sync> does not refer to a valid X11 Synchronization
236    Fence object.
237
238    The error INVALID_VALUE is generated if ImportSyncEXT is called
239    where <flags> is not 0.
240
241New State
242
243    None
244
245Issues
246
247    1) Should the import command be a generic entry point, or
248    specialized for X11 sync fence objects?
249
250      RESOLVED: A generic command is used.  This command can be reused
251      by future extensions to import other sync types.  It takes a
252      pointer-sized parameter that can be used to import any type of
253      synchronization object.  Objects that require more than one
254      value to uniquely identify them, e.g. OpenCL events, can define
255      an intermediate structure that contains all required values and
256      then pass in a pointer to the structure.
257
258    2) What happens if the X11 sync object is destroyed while the GL
259    sync object referencing it is still in use?
260
261      RESOLVED: The GL object should hold a reference on any resources
262      needed to continue using the sync object until the GL object is
263      deleted.
264
265Revision History
266
267    Date: 26-Jan-2011
268    Revision: 2 (James Jones)
269       - Renamed from EXT_x_sync_object to EXT_x11_sync_object.
270       - Added issues 1 and 2 and related spec language.
271       - Added language describing when external syncs are signaled.
272       - Added language describing when external syncs are deleted.
273
274    Date: 20-Jan-2011
275    Revision: 1 (James Jones)
276      - Initial Revision.
277