1 Name 2 3 MESA_swap_frame_usage 4 5 Name Strings 6 7 GLX_MESA_swap_frame_usage 8 9 Contact 10 11 Ian Romanick, IBM, idr at us.ibm.com 12 13 Status 14 15 Deployed in DRI drivers post-XFree86 4.3. 16 17 Version 18 19 Date: 5/1/2003 Revision: 1.1 20 21 Number 22 23 ??? 24 25 Dependencies 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 33 Overview 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 67 New 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 85 New Tokens 86 87 None 88 89 Additions to Chapter 2 of the 1.4 GL Specification (OpenGL Operation) 90 91 None 92 93 Additions to Chapter 3 of the 1.4 GL Specification (Rasterization) 94 95 None 96 97 Additions to Chapter 4 of the 1.4 GL Specification (Per-Fragment Operations 98 and the Framebuffer) 99 100 None 101 102 Additions to Chapter 5 of the 1.4 GL Specification (Special Functions) 103 104 None 105 106 Additions to Chapter 6 of the 1.4 GL Specification (State and State Requests) 107 108 None 109 110 Additions 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 178 Errors 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 186 GLX Protocol 187 188 None. This extension only extends to direct rendering contexts. 189 190 New State 191 192 None 193 194 New Implementation Dependent State 195 196 None 197 198 Revision 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
