ovr_sdk
view LibOVR/Src/CAPI/CAPI_FrameTimeManager.h @ 3:f12a8f74fe1f
added the Xcode project
| author | John Tsiombikas <nuclear@member.fsf.org> |
|---|---|
| date | Wed, 21 Jan 2015 11:37:50 +0200 |
| parents | |
| children |
line source
1 /************************************************************************************
3 Filename : CAPI_FrameTimeManager.h
4 Content : Manage frame timing and pose prediction for rendering
5 Created : November 30, 2013
6 Authors : Volga Aksoy, Michael Antonov
8 Copyright : Copyright 2014 Oculus VR, LLC All Rights reserved.
10 Licensed under the Oculus VR Rift SDK License Version 3.2 (the "License");
11 you may not use the Oculus VR Rift SDK except in compliance with the License,
12 which is provided at the time of installation or download, or which
13 otherwise accompanies this software in either electronic or hard copy form.
15 You may obtain a copy of the License at
17 http://www.oculusvr.com/licenses/LICENSE-3.2
19 Unless required by applicable law or agreed to in writing, the Oculus VR SDK
20 distributed under the License is distributed on an "AS IS" BASIS,
21 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
22 See the License for the specific language governing permissions and
23 limitations under the License.
25 ************************************************************************************/
27 #ifndef OVR_CAPI_FrameTimeManager_h
28 #define OVR_CAPI_FrameTimeManager_h
30 #include "../OVR_CAPI.h"
31 #include "../Kernel/OVR_Timer.h"
32 #include "../Kernel/OVR_Math.h"
33 #include "../Util/Util_Render_Stereo.h"
35 namespace OVR { namespace CAPI {
38 //-------------------------------------------------------------------------------------
39 // ***** TimeDeltaCollector
41 // Helper class to collect median times between frames, so that we know
42 // how long to wait.
43 struct TimeDeltaCollector
44 {
45 TimeDeltaCollector() : Median(-1.0), Count(0), ReCalcMedian(true) { }
47 void AddTimeDelta(double timeSeconds);
48 void Clear() { Count = 0; }
50 double GetMedianTimeDelta() const;
51 double GetMedianTimeDeltaNoFirmwareHack() const;
53 double GetCount() const { return Count; }
55 enum { Capacity = 12 };
56 private:
57 double TimeBufferSeconds[Capacity];
58 mutable double Median;
59 int Count;
60 mutable bool ReCalcMedian;
61 };
64 //-------------------------------------------------------------------------------------
65 // ***** FrameLatencyTracker
67 // FrameLatencyTracker tracks frame Present to display Scan-out timing, as reported by
68 // the DK2 internal latency tester pixel read-back. The computed value is used in
69 // FrameTimeManager for prediction. View Render and TimeWarp to scan-out latencies are
70 // also reported for debugging.
71 //
72 // The class operates by generating color values from GetNextDrawColor() that must
73 // be rendered on the back end and then looking for matching values in FrameTimeRecordSet
74 // structure as reported by HW.
76 class FrameLatencyTracker
77 {
78 public:
80 enum { FramesTracked = Util::LT2_IncrementCount-1 };
82 FrameLatencyTracker();
84 // DrawColor == 0 is special in that it doesn't need saving of timestamp
85 unsigned char GetNextDrawColor();
87 void SaveDrawColor(unsigned char drawColor, double endFrameTime,
88 double renderIMUTime, double timewarpIMUTime );
90 void MatchRecord(const Util::FrameTimeRecordSet &r);
92 bool IsLatencyTimingAvailable();
93 void GetLatencyTimings(float& latencyRender, float& latencyTimewarp, float& latencyPostPresent);
95 void Reset();
97 public:
99 struct FrameTimeRecordEx : public Util::FrameTimeRecord
100 {
101 bool MatchedRecord;
102 double RenderIMUTimeSeconds;
103 double TimewarpIMUTimeSeconds;
104 };
106 // True if rendering read-back is enabled.
107 bool TrackerEnabled;
109 enum SampleWaitType {
110 SampleWait_Zeroes, // We are waiting for a record with all zeros.
111 SampleWait_Match // We are issuing & matching colors.
112 };
114 SampleWaitType WaitMode;
115 int MatchCount;
116 // Records of frame timings that we are trying to measure.
117 FrameTimeRecordEx FrameEndTimes[FramesTracked];
118 int FrameIndex;
119 // Median filter for (ScanoutTimeSeconds - PostPresent frame time)
120 TimeDeltaCollector FrameDeltas;
121 // Latency reporting results
122 double RenderLatencySeconds;
123 double TimewarpLatencySeconds;
124 double LatencyRecordTime;
125 };
129 //-------------------------------------------------------------------------------------
130 // ***** FrameTimeManager
132 // FrameTimeManager keeps track of rendered frame timing and handles predictions for
133 // orientations and time-warp.
135 class FrameTimeManager
136 {
137 public:
138 FrameTimeManager(bool vsyncEnabled);
140 // Data that affects frame timing computation.
141 struct TimingInputs
142 {
143 // Hard-coded value or dynamic as reported by FrameTimeDeltas.GetMedianTimeDelta().
144 double FrameDelta;
145 // Screen delay from present to scan-out, as potentially reported by ScreenLatencyTracker.
146 double ScreenDelay;
147 // Negative value of how many seconds before EndFrame we start timewarp. 0.0 if not used.
148 double TimewarpWaitDelta;
150 TimingInputs()
151 : FrameDelta(0), ScreenDelay(0), TimewarpWaitDelta(0)
152 { }
153 };
155 // Timing values for a specific frame.
156 struct Timing
157 {
158 TimingInputs Inputs;
160 // Index of a frame that started at ThisFrameTime.
161 unsigned int FrameIndex;
162 // Predicted absolute times for when this frame will show up on screen.
163 // Generally, all values will be >= NextFrameTime, since that's the time we expect next
164 // vsync to succeed.
165 double ThisFrameTime;
166 double TimewarpPointTime;
167 double NextFrameTime;
168 double MidpointTime;
169 double EyeRenderTimes[2];
170 double TimeWarpStartEndTimes[2][2];
172 Timing()
173 {
174 memset(this, 0, sizeof(Timing));
175 }
177 void InitTimingFromInputs(const TimingInputs& inputs, HmdShutterTypeEnum shutterType,
178 double thisFrameTime, unsigned int frameIndex);
179 };
182 // Called on startup to provided data on HMD timing.
183 void Init(HmdRenderInfo& renderInfo);
185 // Called with each new ConfigureRendering.
186 void ResetFrameTiming(unsigned frameIndex,
187 bool dynamicPrediction, bool sdkRender);
189 void SetVsync(bool enabled) { VsyncEnabled = enabled; }
191 // BeginFrame returns time of the call
192 // TBD: Should this be a predicted time value instead ?
193 double BeginFrame(unsigned frameIndex);
194 void EndFrame();
196 // Thread-safe function to query timing for a future frame
197 Timing GetFrameTiming(unsigned frameIndex);
199 // if eye == ovrEye_Count, timing is for MidpointTime as opposed to any specific eye
200 double GetEyePredictionTime(ovrEyeType eye, unsigned int frameIndex);
201 ovrTrackingState GetEyePredictionTracking(ovrHmd hmd, ovrEyeType eye, unsigned int frameIndex);
202 Posef GetEyePredictionPose(ovrHmd hmd, ovrEyeType eye);
204 void GetTimewarpPredictions(ovrEyeType eye, double timewarpStartEnd[2]);
205 void GetTimewarpMatrices(ovrHmd hmd, ovrEyeType eye, ovrPosef renderPose, ovrMatrix4f twmOut[2],double debugTimingOffsetInSeconds = 0.0);
207 // Used by renderer to determine if it should time distortion rendering.
208 bool NeedDistortionTimeMeasurement() const;
209 void AddDistortionTimeMeasurement(double distortionTimeSeconds);
212 // DK2 Latency test interface
214 // Get next draw color for DK2 latency tester (3-byte RGB)
215 void GetFrameLatencyTestDrawColor(unsigned char outColor[3])
216 {
217 outColor[0] = ScreenLatencyTracker.GetNextDrawColor();
218 outColor[1] = ScreenLatencyTracker.IsLatencyTimingAvailable() ? 255 : 0;
219 outColor[2] = ScreenLatencyTracker.IsLatencyTimingAvailable() ? 0 : 255;
220 }
222 // Must be called after EndFrame() to update latency tester timings.
223 // Must pass color reported by NextFrameColor for this frame.
224 void UpdateFrameLatencyTrackingAfterEndFrame(unsigned char frameLatencyTestColor[3],
225 const Util::FrameTimeRecordSet& rs);
227 void GetLatencyTimings(float& latencyRender, float& latencyTimewarp, float& latencyPostPresent)
228 {
229 return ScreenLatencyTracker.GetLatencyTimings(latencyRender, latencyTimewarp, latencyPostPresent);
230 }
232 const Timing& GetFrameTiming() const { return FrameTiming; }
234 private:
235 double calcFrameDelta() const;
236 double calcScreenDelay() const;
237 double calcTimewarpWaitDelta() const;
239 //Revisit dynamic pre-Timewarp delay adjustment logic
240 /*
241 void updateTimewarpTiming();
245 // TimewarpDelayAdjuster implements a simple state machine that reduces the amount
246 // of time-warp waiting based on skipped frames.
247 struct TimewarpDelayAdjuster
248 {
249 enum StateInLevel
250 {
251 // We are ok at this level, and will be waiting for some time before trying to reduce.
252 State_WaitingToReduceLevel,
253 // After decrementing a level, we are verifying that this won't cause skipped frames.
254 State_VerifyingAfterReduce
255 };
257 enum {
258 MaxDelayLevel = 5,
259 MaxInfiniteTimingLevel = 3,
260 MaxTimeIndex = 6
261 };
263 StateInLevel State;
264 // Current level. Higher levels means larger delay reduction (smaller overall time-warp delay).
265 int DelayLevel;
266 // Index for the amount of time we'd wait in this level. If attempt to decrease level fails,
267 // with is incrementing causing the level to become "sticky".
268 int WaitTimeIndexForLevel[MaxTimeIndex + 1];
269 // We skip few frames after each escalation to avoid too rapid of a reduction.
270 int InitialFrameCounter;
271 // What th currect "reduction" currently is.
272 double TimewarpDelayReductionSeconds;
273 // When we should try changing the level again.
274 double DelayLevelFinishTime;
276 public:
277 TimewarpDelayAdjuster() { Reset(); }
279 void Reset();
281 void UpdateTimewarpWaitIfSkippedFrames(FrameTimeManager* manager,
282 double measuredFrameDelta,
283 double nextFrameTime);
285 double GetDelayReduction() const { return TimewarpDelayReductionSeconds; }
286 };
287 */
290 HmdRenderInfo RenderInfo;
291 // Timings are collected through a median filter, to avoid outliers.
292 TimeDeltaCollector FrameTimeDeltas;
293 TimeDeltaCollector DistortionRenderTimes;
294 FrameLatencyTracker ScreenLatencyTracker;
296 // Timing changes if we have no Vsync (all prediction is reduced to fixed interval).
297 bool VsyncEnabled;
298 // Set if we are rendering via the SDK, so DistortionRenderTimes is valid.
299 bool DynamicPrediction;
300 // Set if SDk is doing the rendering.
301 bool SdkRender;
302 // Direct to rift.
303 bool DirectToRift;
305 // Total frame delay due to VsyncToFirstScanline, persistence and settle time.
306 // Computed from RenderInfor.Shutter.
307 double VSyncToScanoutDelay;
308 double NoVSyncToScanoutDelay;
309 double ScreenSwitchingDelay;
311 //Revisit dynamic pre-Timewarp delay adjustment logic
312 //TimewarpDelayAdjuster TimewarpAdjuster;
314 // Current (or last) frame timing info. Used as a source for LocklessTiming.
315 Timing FrameTiming;
316 // TBD: Don't we need NextFrame here as well?
317 LocklessUpdater<Timing, Timing> LocklessTiming;
319 // IMU Read timings
320 double RenderIMUTimeSeconds;
321 double TimewarpIMUTimeSeconds;
322 };
325 }} // namespace OVR::CAPI
327 #endif // OVR_CAPI_FrameTimeManager_h