ovr_sdk
view LibOVR/Src/CAPI/CAPI_HSWDisplay.h @ 0:1b39a1b46319
initial 0.4.4
| author | John Tsiombikas <nuclear@member.fsf.org> |
|---|---|
| date | Wed, 14 Jan 2015 06:51:16 +0200 |
| parents | |
| children |
line source
1 /************************************************************************************
3 Filename : CAPI_HSWDisplay.h
4 Content : Implements Health and Safety Warning system.
5 Created : July 3, 2014
6 Authors : Paul Pedriana
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_HSWDisplay_h
28 #define OVR_CAPI_HSWDisplay_h
30 #include "../OVR_CAPI.h"
31 #include "CAPI_HMDRenderState.h"
32 #include <time.h>
36 //-------------------------------------------------------------------------------------
37 // ***** HSWDISPLAY_LOG
38 //
39 // Debug log wrapper.
41 #if !defined(HSWDISPLAY_LOG_ENABLED)
42 #ifdef OVR_BUILD_DEBUG
43 #define HSWDISPLAY_LOG_ENABLED 1
44 #else
45 #define HSWDISPLAY_LOG_ENABLED 0
46 #endif
47 #endif
49 #if HSWDISPLAY_LOG_ENABLED
50 #define HSWDISPLAY_LOG(...) OVR_DEBUG_LOG(__VA_ARGS__)
51 #else
52 #define HSWDISPLAY_LOG(...)
53 #endif
56 //-------------------------------------------------------------------------------------
57 // ***** HSWDISPLAY_DISTANCE
58 //
59 // Floating point value in the range of ~0.75 to ~3.0 which controls the distance
60 // (in meters) of the display from the viewer.
62 #ifndef HSWDISPLAY_DISTANCE
63 #define HSWDISPLAY_DISTANCE 1.5f
64 #endif
67 //-------------------------------------------------------------------------------------
68 // ***** HSWDISPLAY_SCALE
69 //
70 // Floating point value in the range of ~0.1 to ~2.0 which controls the size scale of the
71 // SDK-rendered HSW display. The value is an arbitrary relative value, though this may
72 // change in future SDK versions.
74 #ifndef HSWDISPLAY_SCALE
75 #define HSWDISPLAY_SCALE 0.92f
76 #endif
81 //-------------------------------------------------------------------------------------
82 // ***** Experimental C API functions
83 //
84 // These are currently not formally supported and may be promoted to the formal C API
85 // or may be removed in the future.
87 extern "C"
88 {
89 // Normally if an application uses SDK-based distortion rendering
90 // (ovrHmd_BeginFrame / ovrHmd_EndFrame) then the SDK also takes care of
91 // drawing the health and safety warning. If an application is using
92 // SDK-based rendering but wants to draw the warning display itself,
93 // it call this function with enabled set to false.
94 OVR_EXPORT void ovrhmd_EnableHSWDisplaySDKRender(ovrHmd hmd, ovrBool enabled);
95 }
98 namespace OVR { namespace CAPI {
101 //-------------------------------------------------------------------------------------
102 // ***** CAPI::HSWDisplay
103 //
104 // Note: This will be renamed to HSWDisplay in the future.
105 //
106 // Implements the logic for the Health and Safety (HAS) warning display. Primarily this
107 // is two things: providing information about whether the warning needs to be currently
108 // displayed, and implementing the display itself.
109 //
110 // An HSWDisplay is associated 1:1 with an HMD. There can be at most one HSWDisplay
111 // being displayed on an HMD at a time. If a warning needs to be displayed while an
112 // existing one is present, it replaces the existing one.
113 //
114 // Notes
115 // Warnings are displayed per HMD (head mounted display).
116 // The app can have multiple HMDs.
117 // There can be multiple users of a given HMD over time, with each identified by a different user profile.
118 // There can be multiple apps using HMDs.
119 //
120 // Shows upon first entering a VR application (or VR mode in an application) when in Event Mode (e.g. trade show).
121 // Shows upon each wearing of the HMD.
122 // If the user profile is switched while display is active, the display must restart.
123 // Doesn't show in app when app was started by a launcher app.
124 //
125 // First display ever (per profile): 15 seconds until the display can be dismissed.
126 // Subsequent displays: 6 seconds until the display can be dismissed. Per profile.
127 // Dismissing occurs via HMD tap, designated keypress, gaze detection on OK button for N seconds,
128 // and possibly via an input gesture in the future.
129 //
130 // If the warning fades out upon completion, the fade out should begin after the full display time has elapsed,
131 // but it needs to avoid interfering (e.g. obscuring) with the application. This likely means the application
132 // would need to put in a couple seconds delay to allow the fade to complete.
133 // Ideally we'd handle the case of a user switching HMDs and not needing to see the warning again.
135 class HSWDisplay : public RefCountBase<HSWDisplay>
136 {
137 public:
138 HSWDisplay(ovrRenderAPIType api, ovrHmd hmd, const HMDRenderState& renderState);
140 virtual ~HSWDisplay();
142 // Must be called after construction and before use.
143 virtual bool Initialize(const ovrRenderAPIConfig*)
144 { return true; }
146 // Must be called before destruction.
147 virtual void Shutdown() {}
149 // Enables or disables the HSW display system. It may be disabled only for development uses.
150 // It is enabled by default.
151 void Enable(bool enable);
153 // Enables or disables our internal rendering when Render is called. If set to false then the
154 // application is expected to implement drawing of the display when Displayed is true.
155 // It is enabled by default.
156 void EnableRender(bool enable);
158 // Triggers a display of the HSW display for the associated HMD. Restarts the display if
159 // the warning is already being displayed.
160 void Display();
162 // This function should be called per HMD every frame in order to give this class processing time.
163 // Writes the new state to newHSWDisplayState if it's non-NULL.
164 // The graphicsContext argument indicates if the Tick is occurring within a graphics context and
165 // thus if graphics operations are allowed during the TickState call.
166 // Returns true if the new state results in a required warning display (ovrHSWDisplayState::Displayed became true).
167 bool TickState(ovrHSWDisplayState *newHSWDisplayState = NULL, bool graphicsContext = false);
169 // Gets the current state of the HSW display.
170 // Corresponds to ovrhmd_GetHSWDisplayState.
171 void GetState(ovrHSWDisplayState *hasWarningState) const;
173 // Removes the HSW display display if the minimum dismissal time has occurred.
174 // Returns true if the warning display could be dissmissed or was not displayed at the time of the call.
175 // Corresponds to ovrhmd_DismissHSWDisplay.
176 bool Dismiss();
178 // Returns true if the HMD appears to be currently mounted and in a state that a
179 // warning display would be viewable.
180 bool IsDisplayViewable() const;
182 // Draws the warning to the eye texture(s). This must be done at the end of a
183 // frame but prior to executing the distortion rendering of the eye textures.
184 virtual void Render(ovrEyeType, const ovrTexture*);
186 // Resets the current profile's HAS settings (e.g. to act as if the user has never seen the HSW display before).
187 void ResetProfileData();
189 // Returns the ovrRenderAPIType. This is essentially the same as RTTI, as it's indicating what subclass
190 // is being used for this.
191 ovrRenderAPIType GetRenderAPIType() const // e.g. ovrRenderAPI_D3D11
192 { return RenderAPIType; }
194 // Returns the required HSW display text for the current profile's locale.
195 // Useful for implementing custom warning displays. Returns the required strlen
196 // of the text, and thus success is indicated by a return value < strCapacity.
197 // size_t GetText(char *str, size_t strCapacity);
199 // Creates and constructs an instance of an HSWDisplay subclass based on the API type.
200 static HSWDisplay* Factory(ovrRenderAPIType apiType, ovrHmd hmd, const HMDRenderState& renderState);
202 private:
203 OVR_NON_COPYABLE(HSWDisplay)
205 protected:
206 virtual void DisplayInternal() {}
207 virtual void DismissInternal() {}
208 virtual void RenderInternal(ovrEyeType, const ovrTexture*) {}
209 virtual void UnloadGraphics() {}
210 virtual void LoadGraphics() {}
212 // Profile functionality
213 time_t GetCurrentProfileLastHSWTime() const;
214 void SetCurrentProfileLastHSWTime(time_t t);
216 // Generates an appropriate stereo ortho projection matrix.
217 static void GetOrthoProjection(const HMDRenderState& RenderState, Matrix4f OrthoProjection[2]);
219 // Returns the default HSW display texture data.
220 static const uint8_t* GetDefaultTexture(size_t& TextureSize);
222 protected:
223 bool Enabled; // If true then the HSW display system is enabled. True by default.
224 bool Displayed; // If true then the warning is currently visible and the following variables have meaning. Else there is no warning being displayed for this application on the given HMD.
225 bool SDKRendered; // If true then the display is being rendered by the SDK as opposed to the application.
226 bool DismissRequested; // If true then the warning has been requested to be hidden.
227 bool RenderEnabled; // If true then we handle rendering when Render is called. Else we skip it and assume the application is otherwise handling it itself.
228 bool UnloadGraphicsRequested; // If true then an unload of graphics was requested. This acts as a message from the main thread to the drawing thread so that the unload happens in the expected thread.
229 double StartTime; // Absolute time when the warning was first displayed. See ovr_GetTimeInSeconds().
230 double DismissibleTime; // Absolute time when the warning can be dismissed.
231 double LastPollTime; // Used to prevent us from polling the required display state every frame but rather more like every 200 milliseconds.
232 const ovrHmd HMD; // The HMDState this HSWDisplay instance corresponds to.
233 mutable bool HMDMounted; // True if the HMD was most recently found to be mounted. We need this in order to maintain HMDNewlyMounted.
234 mutable bool HMDNewlyMounted; // True if HMDMounted has transitioned from false to true. We need this in order to tell if the HMD was recently mounted so we can display the HSW display.
235 const ovrRenderAPIType RenderAPIType; // e.g. ovrRenderAPI_D3D11
236 const HMDRenderState& RenderState; // Information about the rendering setup.
238 // Settings cache
239 mutable String LastProfileName;
240 mutable int LastHSWTime;
242 }; // class HSWDisplay
246 }} // namespace OVR::CAPI
249 #endif // OVR_CAPI_HSWDisplay_h