• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1Name
2
3    WGL_I3D_swap_frame_usage
4
5Name Strings
6
7    WGL_I3D_swap_frame_usage
8
9Version
10
11    Date: 5/1/2000   Revision: 1.3
12
13Number
14
15    ???
16
17Dependencies
18
19    WGL_EXT_extensions_string is required.
20    WGL_EXT_swap_control affects the definition of this extension
21
22Overview
23
24    This extension allows an application to obtain the percent of time
25    used to draw a frame.  A floating-point value in the range [0,max]
26    is returned which is calculated as follows:
27
28                              td
29                   percent = ----
30                              tf
31
32    where td is the time measured from the last buffer swap (or call to
33    enable the statistic) to when the application issued a buffer swap,
34    tf is the entire time for a frame which may be multiple screen
35    refreshes depending on the swap interval as set by the
36    WGL_swap_control extension.
37
38    The value, percent, indicates the amount of time spent during the
39    draw.  If the value is in the range [0,1], the buffer swap occurred
40    within the time period required to maintain a constant frame rate.
41    If the value is in the range (1,max], a constant frame rate was not
42    achieved.  The value indicates the number of frames required to
43    draw.
44
45    There is also a mechanism to determine whether a frame swap was
46    missed.
47
48New Procedures and Functions
49
50    BOOL wglGetFrameUsageI3D(float *pUsage)
51
52    BOOL wglBeginFrameTrackingI3D(void)
53
54    BOOL wglEndFrameTrackingI3D(void)
55
56    BOOL wglQueryFrameTrackingI3D(DWORD *pFrameCount,
57                                  DWORD *pMissedFrames,
58                                  float *pLastMissedUsage)
59
60New Tokens
61
62    None
63
64Additions to Chapter 2 of the 1.2 GL Specification (OpenGL Operation)
65
66    None
67
68Additions to Chapter 3 of the 1.2 GL Specification (Rasterization)
69
70    None
71
72Additions to Chapter 4 of the 1.2 GL Specification (Per-Fragment Operations
73and the Framebuffer)
74
75    None
76
77Additions to Chapter 5 of the 1.2 GL Specification (Special Functions)
78
79    None
80
81Additions to Chapter 6 of the 1.2 GL Specification (State and State Requests)
82
83    None
84
85Additions to the WGL Specification
86
87    wglGetFrameUsageI3D returns a floating-point value in <pUsage>
88    that represents the percentage of time that the application spent
89    drawing a scene.  The percentage is calculated as the time spent
90    within the time available.
91
92    The time available is the frame refresh time unless a swap interval
93    has been established.  In this case, the time available is an
94    integer multiple of the frame time as established by the swap
95    interval.
96
97    Missed frame swaps can be tracked by calling the following function:
98
99       BOOL wglBeginFrameTrackingI3D(void)
100
101    wglBeginFrameTrackingI3D resets a "missed frame" count and
102    synchronizes with the next frame vertical sync before it returns.
103    If a swap is missed based in the rate control specified by the
104    <interval> set by wglSwapIntervalEXT or the default swap of once
105    per frame, the missed frame count is incremented.
106
107    The current missed frame count and total number of swaps since
108    the last call to wglBeginFrameTrackingI3D can be obtained by
109    callling the following function:
110
111       BOOL wglQueryFrameTrackingI3D(DWORD *pFrameCount,
112                                     DWORD *pMissedFrames,
113                                     float *pLastMissedUsage)
114
115    The location pointed to by <pFrameCount> will be updated with the
116    number of swaps that have occurred.  This value may not match the
117    number of swaps that have been requested since swaps may be
118    queued by the implementation.  This function can be called at any
119    time and does not synchronize to vertical blank.
120
121    The location pointed to by <pMissedFrames> will contain the number
122    swaps that missed the specified frame.  The frame usage for the
123    last missed frame is returned in the location pointed to by
124    <pLastMissedUsage>.
125
126    Frame tracking is disabled by calling the function
127
128       BOOL wglEndFrameTrackingI3D(void)
129
130    This function will not return until all swaps have occurred.  The
131    application can call wglQueryFrameTrackingI3D for a final swap and
132    missed frame count.
133
134    If these functions fail, FALSE is returned.  To get extended
135    error information, call GetLastError.
136
137Dependencies on WGL_EXT_extensions_string
138
139    Because there is no way to extend wgl, these calls are defined in
140    the ICD and can be called by obtaining the address with
141    wglGetProcAddress.  Because this extension is a WGL extension, it
142    is not included in the GL_EXTENSIONS string.  Its existence can be
143    determined with the WGL_EXT_extensions_string extension.
144
145Errors
146
147    If the function succeeds, the return value is TRUE. If the function
148    fails, the return value is FALSE.  To get extended error information,
149    call GetLastError.
150
151       ERROR_DC_NOT_FOUND      An RC was not current to the calling
152                               thread; therefore, no DC could be
153                               obtained.
154
155       ERROR_BUSY              The resource used for obtaining usage
156                               was currently in use by another
157                               application.
158
159New State
160
161    None
162
163New Implementation Dependent State
164
165    None
166