ovr_sdk

annotate LibOVR/Src/CAPI/CAPI_HSWDisplay.h @ 0:1b39a1b46319

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