docs/MESA_swap_frame_usage.spec

   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 deterine 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 occuring.
  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 commited.  In unextened 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 commited 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     callling 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 commited.  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 succesful, 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.