gfx/config/gfxConfig.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6 #ifndef mozilla_gfx_config_gfxConfig_h
   7 #define mozilla_gfx_config_gfxConfig_h
   8
   9 #include <functional>
  10 #include "gfxFeature.h"
  11 #include "gfxFallback.h"
  12 #include "mozilla/Assertions.h"
  13 #include "mozilla/Maybe.h"
  14
  15 namespace mozilla {
  16 namespace gfx {
  17
  18 // Defined in GraphicsMessages.ipdlh.
  19 class FeatureFailure;
  20
  21 // Manages the history and state of a graphics feature. The flow of a feature
  22 // is:
  23 //   - A default value, set by all.js, or gfxPlatform.
  24 //   - A user value, set by an external value or user pref.
  25 //   - An environment value, determined by system/hardware factors or
  26 //   nsIGfxInfo.
  27 //   - A runtime value, determined by any failures encountered after enabling
  28 //     the feature.
  29 //
  30 // Each state change for a feature is recorded in this class.
  31 class gfxConfig {
  32  public:
  33   // Return the full state history of a feature.
  34   static FeatureState& GetFeature(Feature aFeature);
  35
  36   // Query whether a parameter is enabled, taking into account any user or
  37   // runtime overrides. The algorithm works as follow:
  38   //
  39   //  1. If a runtime decision disabled the feature, return false.
  40   //  2. If the user force-enabled the feature, return true.
  41   //  3. If the environment disabled the feature, return false.
  42   //  4. If the user specified a decision, return it.
  43   //  5. Return the base setting for the feature.
  44   static bool IsEnabled(Feature aFeature);
  45
  46   // Query the history of a parameter. ForcedOnByUser returns whether or not
  47   // the user specifically used a "force" preference to enable the parameter.
  48   // IsDisabledByDefault returns whether or not the initial status of the
  49   // feature, before adding user prefs and runtime decisions, was disabled.
  50   static bool IsForcedOnByUser(Feature aFeature);
  51
  52   // This returns true if the feature was disabled by default, or was never
  53   // initialized to begin with.
  54   static bool IsDisabledByDefault(Feature aFeature);
  55
  56   // Query the status value of a parameter. This is computed similar to
  57   // IsEnabled:
  58   //
  59   //  1. If a runtime failure was set, return it.
  60   //  2. If the user force-enabled the feature, return ForceEnabled.
  61   //  3. If an environment status was set, return it.
  62   //  4. If a user status was set, return it.
  63   //  5. Return the default status.
  64   static FeatureStatus GetValue(Feature aFeature);
  65
  66   // Reset the entire state of a feature.
  67   static void Reset(Feature aFeature);
  68
  69   // Initialize the base value of a parameter. The return value is aEnable.
  70   static bool SetDefault(Feature aFeature, bool aEnable,
  71                          FeatureStatus aDisableStatus,
  72                          const char* aDisableMessage);
  73   static void DisableByDefault(Feature aFeature, FeatureStatus aDisableStatus,
  74                                const char* aDisableMessage,
  75                                const nsACString& aFailureId = EmptyCString());
  76   static void EnableByDefault(Feature aFeature);
  77
  78   // Inherit a computed value from another process.
  79   static void Inherit(Feature aFeature, FeatureStatus aStatus);
  80
  81   // Set a environment status that overrides both the default and user
  82   // statuses; this should be used to disable features based on system
  83   // or hardware problems that can be determined up-front. The only
  84   // status that can override this decision is the user force-enabling
  85   // the feature.
  86   static void Disable(Feature aFeature, FeatureStatus aStatus,
  87                       const char* aMessage,
  88                       const nsACString& aFailureId = EmptyCString());
  89
  90   // Given a preference name, infer the default value and whether or not the
  91   // user has changed it. |aIsEnablePref| specifies whether or not the pref
  92   // is intended to enable a feature (true), or disable it (false).
  93   static void SetDefaultFromPref(Feature aFeature, const char* aPrefName,
  94                                  bool aIsEnablePref, bool aDefaultValue);
  95
  96   // Disable a parameter based on a runtime decision. This permanently
  97   // disables the feature, since runtime decisions override all other
  98   // decisions.
  99   static void SetFailed(Feature aFeature, FeatureStatus aStatus,
 100                         const char* aMessage,
 101                         const nsACString& aFailureId = EmptyCString());
 102
 103   // Force a feature to be disabled permanently. This is the same as
 104   // SetFailed(), but the name may be clearer depending on the context.
 105   static void ForceDisable(Feature aFeature, FeatureStatus aStatus,
 106                            const char* aMessage,
 107                            const nsACString& aFailureId = EmptyCString()) {
 108     SetFailed(aFeature, aStatus, aMessage, aFailureId);
 109   }
 110
 111   // Convenience helpers for SetFailed().
 112   static bool MaybeSetFailed(Feature aFeature, bool aEnable,
 113                              FeatureStatus aDisableStatus,
 114                              const char* aDisableMessage,
 115                              const nsACString& aFailureId = EmptyCString()) {
 116     if (!aEnable) {
 117       SetFailed(aFeature, aDisableStatus, aDisableMessage, aFailureId);
 118       return false;
 119     }
 120     return true;
 121   }
 122
 123   // Convenience helper for SetFailed().
 124   static bool MaybeSetFailed(Feature aFeature, FeatureStatus aStatus,
 125                              const char* aDisableMessage,
 126                              const nsACString& aFailureId = EmptyCString()) {
 127     return MaybeSetFailed(aFeature,
 128                           (aStatus != FeatureStatus::Available &&
 129                            aStatus != FeatureStatus::ForceEnabled),
 130                           aStatus, aDisableMessage, aFailureId);
 131   }
 132
 133   // Re-enables a feature that was previously disabled, by attaching it to a
 134   // fallback. The fallback inherits the message that was used for disabling
 135   // the feature. This can be used, for example, when D3D11 fails at runtime
 136   // but we acquire a second, successful device with WARP.
 137   static void Reenable(Feature aFeature, Fallback aFallback);
 138
 139   // Same as SetDefault, except if the feature already has a default value
 140   // set, the new value will be set as a runtime value. This is useful for
 141   // when the base value can change (for example, via an update from the
 142   // parent process).
 143   static bool InitOrUpdate(Feature aFeature, bool aEnable,
 144                            FeatureStatus aDisableStatus,
 145                            const char* aDisableMessage);
 146
 147   // Set a user status that overrides the base value (but not runtime value)
 148   // of a parameter.
 149   static void UserEnable(Feature aFeature, const char* aMessage);
 150   static void UserForceEnable(Feature aFeature, const char* aMessage);
 151   static void UserDisable(Feature aFeature, const char* aMessage,
 152                           const nsACString& aFailureId = EmptyCString());
 153
 154   // Query whether a fallback has been toggled.
 155   static bool UseFallback(Fallback aFallback);
 156
 157   // Add a log entry denoting that a given fallback had to be used. This can
 158   // be called from any thread in the UI or GPU process.
 159   static void EnableFallback(Fallback aFallback, const char* aMessage);
 160
 161   // Run a callback for each initialized FeatureState.
 162   typedef std::function<void(const char* aName, const char* aDescription,
 163                              FeatureState& aFeature)>
 164       FeatureIterCallback;
 165   static void ForEachFeature(const FeatureIterCallback& aCallback);
 166
 167   // Run a callback for each enabled fallback.
 168   typedef std::function<void(const char* aName, const char* aMsg)>
 169       FallbackIterCallback;
 170   static void ForEachFallback(const FallbackIterCallback& aCallback);
 171
 172   // Get the most descriptive failure id message for this feature.
 173   static const nsCString& GetFailureId(Feature aFeature);
 174
 175   static void ImportChange(Feature aFeature,
 176                            const Maybe<FeatureFailure>& aChange);
 177
 178   static void Init();
 179   static void Shutdown();
 180
 181  private:
 182   void ForEachFallbackImpl(const FallbackIterCallback& aCallback);
 183
 184  private:
 185   FeatureState& GetState(Feature aFeature) {
 186     MOZ_ASSERT(size_t(aFeature) < kNumFeatures);
 187     return mFeatures[size_t(aFeature)];
 188   }
 189   const FeatureState& GetState(Feature aFeature) const {
 190     MOZ_ASSERT(size_t(aFeature) < kNumFeatures);
 191     return mFeatures[size_t(aFeature)];
 192   }
 193
 194   bool UseFallbackImpl(Fallback aFallback) const;
 195   void EnableFallbackImpl(Fallback aFallback, const char* aMessage);
 196
 197  private:
 198   static const size_t kNumFeatures = size_t(Feature::NumValues);
 199   static const size_t kNumFallbacks = size_t(Fallback::NumValues);
 200
 201  private:
 202   FeatureState mFeatures[kNumFeatures];
 203   uint64_t mFallbackBits;
 204
 205  private:
 206   struct FallbackLogEntry {
 207     Fallback mFallback;
 208     char mMessage[80];
 209   };
 210
 211   FallbackLogEntry mFallbackLog[kNumFallbacks];
 212   size_t mNumFallbackLogEntries;
 213 };
 214
 215 }  // namespace gfx
 216 }  // namespace mozilla
 217
 218 #endif  // mozilla_gfx_config_gfxConfig_h