1Name
2
3    MESA_swap_frame_usage
4
5Name Strings
6
7    GLX_MESA_swap_frame_usage
8
9Contact
10
11    Ian Romanick, IBM, idr at us.ibm.com
12
13Status
14
15    Deployed in DRI drivers post-XFree86 4.3.
16
17Version
18
19    Date: 5/1/2003   Revision: 1.1
20
21Number
22
23    ???
24
25Dependencies
26
27    GLX_SGI_swap_control affects the definition of this extension.
28    GLX_MESA_swap_control affects the definition of this extension.
29    GLX_OML_sync_control affects the definition of this extension.
30
31    Based on WGL_I3D_swap_frame_usage version 1.3.
32
33Overview
34
35    This extension allows an application to determine what portion of the
36    swap period has elapsed since the last swap operation completed.  The
37    "usage" value is a floating point value on the range [0,max] which is
38    calculated as follows:
39
40                              td
41                   percent = ----
42                              tf
43
44    where td is the time measured from the last completed buffer swap (or
45    call to enable the statistic) to when the next buffer swap completes, tf
46    is the entire time for a frame which may be multiple screen refreshes
47    depending on the swap interval as set by the GLX_SGI_swap_control or
48    GLX_OML_sync_control extensions. 
49
50    The value, percent, indicates the amount of time spent between the
51    completion of the two swaps.  If the value is in the range [0,1], the
52    buffer swap occurred within the time period required to maintain a
53    constant frame rate.  If the value is in the range (1,max], a constant
54    frame rate was not achieved.  The value indicates the number of frames
55    required to draw.
56
57    This definition of "percent" differs slightly from
58    WGL_I3D_swap_frame_usage.  In WGL_I3D_swap_frame_usage, the measurement
59    is taken from the completion of one swap to the issuance of the next.
60    This representation may not be as useful as measuring between
61    completions, as a significant amount of time may pass between the
62    issuance of a swap and the swap actually occurring.
63
64    There is also a mechanism to determine whether a frame swap was
65    missed.
66
67New Procedures and Functions
68
69    int glXGetFrameUsageMESA(Display *dpy,
70                             GLXDrawable drawable,
71    	                     float *usage)
72
73    int glXBeginFrameTrackingMESA(Display *dpy,
74                                  GLXDrawable drawable)
75
76    int glXEndFrameTrackingMESA(Display *dpy,
77                                GLXDrawable drawable)
78
79    int glXQueryFrameTrackingMESA(Display *dpy,
80                                  GLXDrawable drawable,
81				  int64_t *swapCount,
82                                  int64_t *missedFrames,
83                                  float *lastMissedUsage)
84
85New Tokens
86
87    None
88
89Additions to Chapter 2 of the 1.4 GL Specification (OpenGL Operation)
90
91    None
92
93Additions to Chapter 3 of the 1.4 GL Specification (Rasterization)
94
95    None
96
97Additions to Chapter 4 of the 1.4 GL Specification (Per-Fragment Operations
98and the Framebuffer)
99
100    None
101
102Additions to Chapter 5 of the 1.4 GL Specification (Special Functions)
103
104    None
105
106Additions to Chapter 6 of the 1.4 GL Specification (State and State Requests)
107
108    None
109
110Additions to the GLX 1.3 Specification
111
112    The frame usage is measured as the percentage of the swap period elapsed
113    between two buffer-swap operations being committed.  In unextended GLX the
114    swap period is the vertical refresh time.  If SGI_swap_control or
115    MESA_swap_control are supported, the swap period is the vertical refresh
116    time multiplied by the swap interval (or one if the swap interval is set
117    to zero).
118    
119    If OML_sync_control is supported, the swap period is the vertical
120    refresh time multiplied by the divisor parameter to
121    glXSwapBuffersMscOML.  The frame usage in this case is less than 1.0 if
122    the swap is committed before target_msc, and is greater than or equal to
123    1.0 otherwise.  The actual usage value is based on the divisor and is
124    never less than 0.0.
125
126       int glXBeginFrameTrackingMESA(Display *dpy,
127                                     GLXDrawable drawable,
128				     float *usage)
129
130    glXGetFrameUsageMESA returns a floating-point value in <usage>
131    that represents the current swap usage, as defined above.
132
133    Missed frame swaps can be tracked by calling the following function:
134
135       int glXBeginFrameTrackingMESA(Display *dpy,
136                                     GLXDrawable drawable)
137
138    glXBeginFrameTrackingMESA resets a "missed frame" count and
139    synchronizes with the next frame vertical sync before it returns.
140    If a swap is missed based in the rate control specified by the
141    <interval> set by glXSwapIntervalSGI or the default swap of once
142    per frame, the missed frame count is incremented.
143
144    The current missed frame count and total number of swaps since
145    the last call to glXBeginFrameTrackingMESA can be obtained by
146    calling the following function:
147
148       int glXQueryFrameTrackingMESA(Display *dpy,
149                                     GLXDrawable drawable,
150				     int64_t *swapCount,
151                                     int64_t *missedFrames,
152                                     float *lastMissedUsage)
153
154    The location pointed to by <swapCount> will be updated with the
155    number of swaps that have been committed.  This value may not match the
156    number of swaps that have been requested since swaps may be
157    queued by the implementation.  This function can be called at any
158    time and does not synchronize to vertical blank.
159
160    The location pointed to by <missedFrames> will contain the number
161    swaps that missed the specified frame.  The frame usage for the
162    last missed frame is returned in the location pointed to by
163    <lastMissedUsage>.
164
165    Frame tracking is disabled by calling the function
166
167       int glXEndFrameTrackingMESA(Display *dpy,
168                                   GLXDrawable drawable)
169
170    This function will not return until all swaps have occurred.  The
171    application can call glXQueryFrameTrackingMESA for a final swap and
172    missed frame count.
173
174    If these functions are successful, zero is returned.  If the context
175    associated with dpy and drawable is not a direct context,
176    GLX_BAD_CONTEXT is returned.
177
178Errors
179
180    If the function succeeds, zero is returned.  If the function
181    fails, one of the following error codes is returned:
182
183       GLX_BAD_CONTEXT         The current rendering context is not a direct
184       			       context.
185
186GLX Protocol
187
188    None.  This extension only extends to direct rendering contexts.
189
190New State
191
192    None
193
194New Implementation Dependent State
195
196    None
197
198Revision History
199
200    1.1,  5/1/03   Added contact information.
201    1.0,  3/17/03  Initial version based on WGL_I3D_swap_frame_usage.
202