Ian's buffer swap extensions

1 files changed, 196 insertions, 0 deletions

diff --git a/docs/MESA_swap_frame_usage.spec b/docs/MESA_swap_frame_usage.spec
new file mode 100644
index 00000000000..028a6b8f7ec
--- /dev/null
+++ b/docs/MESA_swap_frame_usage.spec
@@ -0,0 +1,196 @@
+Name
+
+    MESA_swap_frame_usage
+
+Name Strings
+
+    GLX_MESA_swap_frame_usage
+
+Contact
+
+    Ian Romanick, IBM  (idr 'at' us.ibm.com)
+
+Status
+
+    Deployed in DRI drivers post-XFree86 4.3.
+
+Version
+
+    Date: 3/17/2003   Revision: 1.0
+
+Number
+
+    ???
+
+Dependencies
+
+    GLX_SGI_swap_control affects the definition of this extension.
+    GLX_MESA_swap_control affects the definition of this extension.
+    GLX_OML_sync_control affects the definition of this extension.
+
+    Based on WGL_I3D_swap_frame_usage version 1.3.
+
+Overview
+
+    This extension allows an application to deterine what portion of the
+    swap period has elapsed since the last swap operation completed.  The
+    "usage" value is a floating point value on the range [0,max] which is
+    calculated as follows:
+
+                              td
+                   percent = ----
+                              tf
+
+    where td is the time measured from the last completed buffer swap (or
+    call to enable the statistic) to when the next buffer swap completes, tf
+    is the entire time for a frame which may be multiple screen refreshes
+    depending on the swap interval as set by the GLX_SGI_swap_control or
+    GLX_OML_sync_control extensions. 
+
+    The value, percent, indicates the amount of time spent between the
+    completion of the two swaps.  If the value is in the range [0,1], the
+    buffer swap occurred within the time period required to maintain a
+    constant frame rate.  If the value is in the range (1,max], a constant
+    frame rate was not achieved.  The value indicates the number of frames
+    required to draw.
+
+    This definition of "percent" differs slightly from
+    WGL_I3D_swap_frame_usage.  In WGL_I3D_swap_frame_usage, the measurement
+    is taken from the completion of one swap to the issuance of the next.
+    This representation may not be as useful as measuring between
+    completions, as a significant amount of time may pass between the
+    issuance of a swap and the swap actually occuring.
+
+    There is also a mechanism to determine whether a frame swap was
+    missed.
+
+New Procedures and Functions
+
+    int glXGetFrameUsageMESA(Display *dpy,
+                             GLXDrawable drawable,
+    	                     float *usage)
+
+    int glXBeginFrameTrackingMESA(Display *dpy,
+                                  GLXDrawable drawable)
+
+    int glXEndFrameTrackingMESA(Display *dpy,
+                                GLXDrawable drawable)
+
+    int glXQueryFrameTrackingMESA(Display *dpy,
+                                  GLXDrawable drawable,
+				  int64_t *swapCount,
+                                  int64_t *missedFrames,
+                                  float *lastMissedUsage)
+
+New Tokens
+
+    None
+
+Additions to Chapter 2 of the 1.4 GL Specification (OpenGL Operation)
+
+    None
+
+Additions to Chapter 3 of the 1.4 GL Specification (Rasterization)
+
+    None
+
+Additions to Chapter 4 of the 1.4 GL Specification (Per-Fragment Operations
+and the Framebuffer)
+
+    None
+
+Additions to Chapter 5 of the 1.4 GL Specification (Special Functions)
+
+    None
+
+Additions to Chapter 6 of the 1.4 GL Specification (State and State Requests)
+
+    None
+
+Additions to the GLX 1.3 Specification
+
+    The frame usage is measured as the percentage of the swap period elapsed
+    between two buffer-swap operations being commited.  In unextened GLX the
+    swap period is the vertical refresh time.  If SGI_swap_control or
+    MESA_swap_control are supported, the swap period is the vertical refresh
+    time multiplied by the swap interval (or one if the swap interval is set
+    to zero).
+    
+    If OML_sync_control is supported, the swap period is the vertical
+    refresh time multiplied by the divisor parameter to
+    glXSwapBuffersMscOML.  The frame usage in this case is less than 1.0 if
+    the swap is commited before target_msc, and is greater than or equal to
+    1.0 otherwise.  The actual usage value is based on the divisor and is
+    never less than 0.0.
+
+       int glXBeginFrameTrackingMESA(Display *dpy,
+                                     GLXDrawable drawable,
+				     float *usage)
+
+    glXGetFrameUsageMESA returns a floating-point value in <usage>
+    that represents the current swap usage, as defined above.
+
+    Missed frame swaps can be tracked by calling the following function:
+
+       int glXBeginFrameTrackingMESA(Display *dpy,
+                                     GLXDrawable drawable)
+
+    glXBeginFrameTrackingMESA resets a "missed frame" count and
+    synchronizes with the next frame vertical sync before it returns.
+    If a swap is missed based in the rate control specified by the
+    <interval> set by glXSwapIntervalSGI or the default swap of once
+    per frame, the missed frame count is incremented.
+
+    The current missed frame count and total number of swaps since
+    the last call to glXBeginFrameTrackingMESA can be obtained by
+    callling the following function:
+
+       int glXQueryFrameTrackingMESA(Display *dpy,
+                                     GLXDrawable drawable,
+				     int64_t *swapCount,
+                                     int64_t *missedFrames,
+                                     float *lastMissedUsage)
+
+    The location pointed to by <swapCount> will be updated with the
+    number of swaps that have been commited.  This value may not match the
+    number of swaps that have been requested since swaps may be
+    queued by the implementation.  This function can be called at any
+    time and does not synchronize to vertical blank.
+
+    The location pointed to by <missedFrames> will contain the number
+    swaps that missed the specified frame.  The frame usage for the
+    last missed frame is returned in the location pointed to by
+    <lastMissedUsage>.
+
+    Frame tracking is disabled by calling the function
+
+       int glXEndFrameTrackingMESA(Display *dpy,
+                                   GLXDrawable drawable)
+
+    This function will not return until all swaps have occurred.  The
+    application can call glXQueryFrameTrackingMESA for a final swap and
+    missed frame count.
+
+    If these functions are succesful, zero is returned.  If the context
+    associated with dpy and drawable is not a direct context,
+    GLX_BAD_CONTEXT is returned.
+
+Errors
+
+    If the function succeeds, zero is returned.  If the function
+    fails, one of the following error codes is returned:
+
+       GLX_BAD_CONTEXT         The current rendering context is not a direct
+       			       context.
+
+GLX Protocol
+
+    None.  This extension only extends to direct rendering contexts.
+
+New State
+
+    None
+
+New Implementation Dependent State
+
+    None