Brian Paul | 09b00c5 | 2003-05-01 19:12:23 +0000 | [diff] [blame] | 1 | Name |
| 2 | |
| 3 | MESA_swap_frame_usage |
| 4 | |
| 5 | Name Strings |
| 6 | |
| 7 | GLX_MESA_swap_frame_usage |
| 8 | |
| 9 | Contact |
| 10 | |
Brian Paul | c784d87 | 2003-05-02 15:04:20 +0000 | [diff] [blame] | 11 | Ian Romanick, IBM, idr at us.ibm.com |
Brian Paul | 09b00c5 | 2003-05-01 19:12:23 +0000 | [diff] [blame] | 12 | |
| 13 | Status |
| 14 | |
| 15 | Deployed in DRI drivers post-XFree86 4.3. |
| 16 | |
| 17 | Version |
| 18 | |
Brian Paul | c784d87 | 2003-05-02 15:04:20 +0000 | [diff] [blame] | 19 | Date: 5/1/2003 Revision: 1.1 |
Brian Paul | 09b00c5 | 2003-05-01 19:12:23 +0000 | [diff] [blame] | 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 | |
Ian Romanick | 6e2ab82 | 2006-05-03 17:12:12 +0000 | [diff] [blame] | 35 | This extension allows an application to determine what portion of the |
Brian Paul | 09b00c5 | 2003-05-01 19:12:23 +0000 | [diff] [blame] | 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 |
Ian Romanick | 6e2ab82 | 2006-05-03 17:12:12 +0000 | [diff] [blame] | 62 | issuance of a swap and the swap actually occurring. |
Brian Paul | 09b00c5 | 2003-05-01 19:12:23 +0000 | [diff] [blame] | 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 |
Ian Romanick | 6e2ab82 | 2006-05-03 17:12:12 +0000 | [diff] [blame] | 113 | between two buffer-swap operations being committed. In unextended GLX the |
Brian Paul | 09b00c5 | 2003-05-01 19:12:23 +0000 | [diff] [blame] | 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 |
Ian Romanick | 6e2ab82 | 2006-05-03 17:12:12 +0000 | [diff] [blame] | 122 | the swap is committed before target_msc, and is greater than or equal to |
Brian Paul | 09b00c5 | 2003-05-01 19:12:23 +0000 | [diff] [blame] | 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 |
Ian Romanick | 6e2ab82 | 2006-05-03 17:12:12 +0000 | [diff] [blame] | 146 | calling the following function: |
Brian Paul | 09b00c5 | 2003-05-01 19:12:23 +0000 | [diff] [blame] | 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 |
Ian Romanick | 6e2ab82 | 2006-05-03 17:12:12 +0000 | [diff] [blame] | 155 | number of swaps that have been committed. This value may not match the |
Brian Paul | 09b00c5 | 2003-05-01 19:12:23 +0000 | [diff] [blame] | 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 | |
Ian Romanick | 6e2ab82 | 2006-05-03 17:12:12 +0000 | [diff] [blame] | 174 | If these functions are successful, zero is returned. If the context |
Brian Paul | 09b00c5 | 2003-05-01 19:12:23 +0000 | [diff] [blame] | 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 |
Brian Paul | c784d87 | 2003-05-02 15:04:20 +0000 | [diff] [blame] | 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. |