1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/LibOVR/Src/CAPI/CAPI_HSWDisplay.h	Wed Jan 14 06:51:16 2015 +0200
     1.3 @@ -0,0 +1,249 @@
     1.4 +/************************************************************************************
     1.5 +
     1.6 +Filename    :   CAPI_HSWDisplay.h
     1.7 +Content     :   Implements Health and Safety Warning system.
     1.8 +Created     :   July 3, 2014
     1.9 +Authors     :   Paul Pedriana
    1.10 +
    1.11 +Copyright   :   Copyright 2014 Oculus VR, LLC All Rights reserved.
    1.12 +
    1.13 +Licensed under the Oculus VR Rift SDK License Version 3.2 (the "License"); 
    1.14 +you may not use the Oculus VR Rift SDK except in compliance with the License, 
    1.15 +which is provided at the time of installation or download, or which 
    1.16 +otherwise accompanies this software in either electronic or hard copy form.
    1.17 +
    1.18 +You may obtain a copy of the License at
    1.19 +
    1.20 +http://www.oculusvr.com/licenses/LICENSE-3.2 
    1.21 +
    1.22 +Unless required by applicable law or agreed to in writing, the Oculus VR SDK 
    1.23 +distributed under the License is distributed on an "AS IS" BASIS,
    1.24 +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    1.25 +See the License for the specific language governing permissions and
    1.26 +limitations under the License.
    1.27 +
    1.28 +************************************************************************************/
    1.29 +
    1.30 +#ifndef OVR_CAPI_HSWDisplay_h
    1.31 +#define OVR_CAPI_HSWDisplay_h
    1.32 +
    1.33 +#include "../OVR_CAPI.h"
    1.34 +#include "CAPI_HMDRenderState.h"
    1.35 +#include <time.h>
    1.36 +
    1.37 +
    1.38 +
    1.39 +//-------------------------------------------------------------------------------------
    1.40 +// ***** HSWDISPLAY_LOG
    1.41 +//
    1.42 +// Debug log wrapper.
    1.43 +
    1.44 +#if !defined(HSWDISPLAY_LOG_ENABLED)
    1.45 +    #ifdef OVR_BUILD_DEBUG
    1.46 +        #define HSWDISPLAY_LOG_ENABLED 1
    1.47 +    #else
    1.48 +        #define HSWDISPLAY_LOG_ENABLED 0
    1.49 +    #endif
    1.50 +#endif
    1.51 +
    1.52 +#if HSWDISPLAY_LOG_ENABLED
    1.53 +    #define HSWDISPLAY_LOG(...) OVR_DEBUG_LOG(__VA_ARGS__)
    1.54 +#else
    1.55 +    #define HSWDISPLAY_LOG(...)
    1.56 +#endif
    1.57 +
    1.58 +
    1.59 +//-------------------------------------------------------------------------------------
    1.60 +// ***** HSWDISPLAY_DISTANCE
    1.61 +//
    1.62 +// Floating point value in the range of ~0.75 to ~3.0 which controls the distance 
    1.63 +// (in meters) of the display from the viewer.
    1.64 +
    1.65 +#ifndef HSWDISPLAY_DISTANCE
    1.66 +    #define HSWDISPLAY_DISTANCE 1.5f
    1.67 +#endif
    1.68 +
    1.69 +
    1.70 +//-------------------------------------------------------------------------------------
    1.71 +// ***** HSWDISPLAY_SCALE
    1.72 +//
    1.73 +// Floating point value in the range of ~0.1 to ~2.0 which controls the size scale of the 
    1.74 +// SDK-rendered HSW display. The value is an arbitrary relative value, though this may 
    1.75 +// change in future SDK versions.
    1.76 +
    1.77 +#ifndef HSWDISPLAY_SCALE
    1.78 +    #define HSWDISPLAY_SCALE 0.92f
    1.79 +#endif
    1.80 +
    1.81 +
    1.82 +
    1.83 +
    1.84 +//-------------------------------------------------------------------------------------
    1.85 +// ***** Experimental C API functions
    1.86 +//
    1.87 +// These are currently not formally supported and may be promoted to the formal C API
    1.88 +// or may be removed in the future.
    1.89 +
    1.90 +extern "C"
    1.91 +{
    1.92 +    // Normally if an application uses SDK-based distortion rendering 
    1.93 +    // (ovrHmd_BeginFrame / ovrHmd_EndFrame) then the SDK also takes care of 
    1.94 +    // drawing the health and safety warning. If an application is using 
    1.95 +    // SDK-based rendering but wants to draw the warning display itself, 
    1.96 +    // it call this function with enabled set to false.
    1.97 +    OVR_EXPORT void ovrhmd_EnableHSWDisplaySDKRender(ovrHmd hmd, ovrBool enabled);
    1.98 +}
    1.99 +
   1.100 +
   1.101 +namespace OVR { namespace CAPI {
   1.102 +
   1.103 +
   1.104 +//-------------------------------------------------------------------------------------
   1.105 +// ***** CAPI::HSWDisplay
   1.106 +//
   1.107 +// Note: This will be renamed to HSWDisplay in the future.
   1.108 +//
   1.109 +// Implements the logic for the Health and Safety (HAS) warning display. Primarily this
   1.110 +// is two things: providing information about whether the warning needs to be currently
   1.111 +// displayed, and implementing the display itself. 
   1.112 +//
   1.113 +// An HSWDisplay is associated 1:1 with an HMD. There can be at most one HSWDisplay 
   1.114 +// being displayed on an HMD at a time. If a warning needs to be displayed while an  
   1.115 +// existing one is present, it replaces the existing one. 
   1.116 +//
   1.117 +// Notes
   1.118 +//    Warnings are displayed per HMD (head mounted display).
   1.119 +//    The app can have multiple HMDs.
   1.120 +//    There can be multiple users of a given HMD over time, with each identified by a different user profile.
   1.121 +//    There can be multiple apps using HMDs.
   1.122 +//
   1.123 +//    Shows upon first entering a VR application (or VR mode in an application) when in Event Mode (e.g. trade show).
   1.124 +//    Shows upon each wearing of the HMD.
   1.125 +//    If the user profile is switched while display is active, the display must restart.
   1.126 +//    Doesn't show in app when app was started by a launcher app.
   1.127 +//
   1.128 +//    First display ever (per profile): 15 seconds until the display can be dismissed.
   1.129 +//    Subsequent displays: 6 seconds until the display can be dismissed. Per profile.
   1.130 +//    Dismissing occurs via HMD tap, designated keypress, gaze detection on OK button for N seconds, 
   1.131 +//        and possibly via an input gesture in the future.
   1.132 +//
   1.133 +//    If the warning fades out upon completion, the fade out should begin after the full display time has elapsed, 
   1.134 +//        but it needs to avoid interfering (e.g. obscuring) with the application. This likely means the application 
   1.135 +//        would need to put in a couple seconds delay to allow the fade to complete.
   1.136 +//    Ideally we'd handle the case of a user switching HMDs and not needing to see the warning again.
   1.137 +
   1.138 +class HSWDisplay : public RefCountBase<HSWDisplay>
   1.139 +{
   1.140 +public:
   1.141 +    HSWDisplay(ovrRenderAPIType api, ovrHmd hmd, const HMDRenderState& renderState);
   1.142 +
   1.143 +    virtual ~HSWDisplay();
   1.144 +
   1.145 +    // Must be called after construction and before use.
   1.146 +    virtual bool Initialize(const ovrRenderAPIConfig*)
   1.147 +        { return true; }
   1.148 +
   1.149 +    // Must be called before destruction.
   1.150 +    virtual void Shutdown() {}
   1.151 +
   1.152 +    // Enables or disables the HSW display system. It may be disabled only for development uses.
   1.153 +    // It is enabled by default. 
   1.154 +    void Enable(bool enable);
   1.155 +
   1.156 +    // Enables or disables our internal rendering when Render is called. If set to false then the 
   1.157 +    // application is expected to implement drawing of the display when Displayed is true.
   1.158 +    // It is enabled by default. 
   1.159 +    void EnableRender(bool enable);
   1.160 +
   1.161 +    // Triggers a display of the HSW display for the associated HMD. Restarts the display if 
   1.162 +    // the warning is already being displayed. 
   1.163 +    void Display();
   1.164 +
   1.165 +    // This function should be called per HMD every frame in order to give this class processing time. 
   1.166 +    // Writes the new state to newHSWDisplayState if it's non-NULL.
   1.167 +    // The graphicsContext argument indicates if the Tick is occurring within a graphics context and
   1.168 +    // thus if graphics operations are allowed during the TickState call.
   1.169 +    // Returns true if the new state results in a required warning display (ovrHSWDisplayState::Displayed became true).
   1.170 +    bool TickState(ovrHSWDisplayState *newHSWDisplayState = NULL, bool graphicsContext = false);
   1.171 +
   1.172 +    // Gets the current state of the HSW display. 
   1.173 +    // Corresponds to ovrhmd_GetHSWDisplayState.
   1.174 +    void GetState(ovrHSWDisplayState *hasWarningState) const;
   1.175 +
   1.176 +    // Removes the HSW display display if the minimum dismissal time has occurred. 
   1.177 +    // Returns true if the warning display could be dissmissed or was not displayed at the time of the call.
   1.178 +    // Corresponds to ovrhmd_DismissHSWDisplay.
   1.179 +    bool Dismiss();
   1.180 +
   1.181 +    // Returns true if the HMD appears to be currently mounted and in a state that a 
   1.182 +    // warning display would be viewable.
   1.183 +    bool IsDisplayViewable() const;
   1.184 +
   1.185 +    // Draws the warning to the eye texture(s). This must be done at the end of a 
   1.186 +    // frame but prior to executing the distortion rendering of the eye textures. 
   1.187 +    virtual void Render(ovrEyeType, const ovrTexture*);
   1.188 +
   1.189 +    // Resets the current profile's HAS settings (e.g. to act as if the user has never seen the HSW display before).
   1.190 +    void ResetProfileData();
   1.191 +
   1.192 +    // Returns the ovrRenderAPIType. This is essentially the same as RTTI, as it's indicating what subclass
   1.193 +    // is being used for this.
   1.194 +    ovrRenderAPIType GetRenderAPIType() const // e.g. ovrRenderAPI_D3D11
   1.195 +        { return RenderAPIType; }
   1.196 +
   1.197 +    // Returns the required HSW display text for the current profile's locale. 
   1.198 +    // Useful for implementing custom warning displays. Returns the required strlen 
   1.199 +    // of the text, and thus success is indicated by a return value < strCapacity.
   1.200 +    // size_t GetText(char *str, size_t strCapacity);
   1.201 +
   1.202 +    // Creates and constructs an instance of an HSWDisplay subclass based on the API type.
   1.203 +    static HSWDisplay* Factory(ovrRenderAPIType apiType, ovrHmd hmd, const HMDRenderState& renderState);
   1.204 +
   1.205 +private:
   1.206 +    OVR_NON_COPYABLE(HSWDisplay)
   1.207 +
   1.208 +protected:
   1.209 +    virtual void DisplayInternal() {}
   1.210 +    virtual void DismissInternal() {}
   1.211 +    virtual void RenderInternal(ovrEyeType, const ovrTexture*) {}
   1.212 +    virtual void UnloadGraphics() {}
   1.213 +    virtual void LoadGraphics() {}
   1.214 +
   1.215 +    // Profile functionality
   1.216 +    time_t GetCurrentProfileLastHSWTime() const;
   1.217 +    void   SetCurrentProfileLastHSWTime(time_t t);
   1.218 +
   1.219 +    // Generates an appropriate stereo ortho projection matrix.
   1.220 +    static void GetOrthoProjection(const HMDRenderState& RenderState, Matrix4f OrthoProjection[2]);
   1.221 +
   1.222 +    // Returns the default HSW display texture data.
   1.223 +    static const uint8_t* GetDefaultTexture(size_t& TextureSize);
   1.224 +
   1.225 +protected:
   1.226 +    bool                   Enabled;                 // If true then the HSW display system is enabled. True by default.
   1.227 +    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.
   1.228 +    bool                   SDKRendered;             // If true then the display is being rendered by the SDK as opposed to the application.
   1.229 +    bool                   DismissRequested;        // If true then the warning has been requested to be hidden.
   1.230 +    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.
   1.231 +    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.
   1.232 +    double                 StartTime;               // Absolute time when the warning was first displayed. See ovr_GetTimeInSeconds().
   1.233 +    double                 DismissibleTime;         // Absolute time when the warning can be dismissed.
   1.234 +    double                 LastPollTime;            // Used to prevent us from polling the required display state every frame but rather more like every 200 milliseconds.
   1.235 +    const ovrHmd           HMD;                     // The HMDState this HSWDisplay instance corresponds to.
   1.236 +    mutable bool           HMDMounted;              // True if the HMD was most recently found to be mounted. We need this in order to maintain HMDNewlyMounted.
   1.237 +    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.
   1.238 +    const ovrRenderAPIType RenderAPIType;           // e.g. ovrRenderAPI_D3D11
   1.239 +    const HMDRenderState&  RenderState;             // Information about the rendering setup.
   1.240 +
   1.241 +    // Settings cache
   1.242 +    mutable String         LastProfileName;
   1.243 +    mutable int            LastHSWTime;
   1.244 +
   1.245 +}; // class HSWDisplay
   1.246 +
   1.247 +
   1.248 +
   1.249 +}} // namespace OVR::CAPI
   1.250 +
   1.251 +
   1.252 +#endif // OVR_CAPI_HSWDisplay_h