gecko-dev/widget/nsIGfxInfo.idl

/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

/* NOTE: this interface is completely undesigned, not stable and likely to change */
[scriptable, builtinclass, uuid(1accd618-4c80-4703-9d29-ecf257d397c8)]
interface nsIGfxInfo : nsISupports
{
  /*
   * These are win32-specific
   */
  readonly attribute boolean D2DEnabled;
  readonly attribute boolean DWriteEnabled;
  readonly attribute boolean EmbeddedInFirefoxReality;
  readonly attribute AString AzureCanvasBackend;
  readonly attribute AString AzureContentBackend;
  readonly attribute boolean usingGPUProcess;
  readonly attribute boolean usingRemoteCanvas;
  readonly attribute boolean usingAcceleratedCanvas;
  readonly attribute boolean hasBattery;
  readonly attribute AString DWriteVersion;
  readonly attribute AString cleartypeParameters;
  readonly attribute float textScaleFactor;

  /*
   * These are non-Android linux-specific
   */
  readonly attribute AString windowProtocol;
  readonly attribute AString testType;

  /*
   * These are valid across all platforms.
   */
  readonly attribute AString ContentBackend;
  readonly attribute boolean isHeadless;
  readonly attribute unsigned long TargetFrameRate;
  readonly attribute ACString CodecSupportInfo;

  // XXX: Switch to a list of devices, rather than explicitly numbering them.

  // Present on all platforms, but only useful on Android
  cenum FontVisibilityDeviceDetermination : 8 {
    Unassigned = 0,
    Unknown_Platform = 1,
    Windows_Platform = 2,
    MacOS_Unknown = 3,
    Android_Unknown_Release_Version = 4,
    Android_Unknown_Peloton = 5,
    Android_Unknown_vbox = 6,
    Android_Unknown_mitv = 7,
    Android_Chromebook = 8,
    Android_Amazon = 9,
    Android_sub_9 = 10,
    Android_9_11 = 11,
    Android_12_plus = 12,
    Linux_Unknown = 13,
    Linux_Ubuntu_any = 14,
    Linux_Ubuntu_20 = 15,
    Linux_Ubuntu_22 = 16,
    Linux_Fedora_any = 17,
    Linux_Fedora_38 = 18,
    Linux_Fedora_39 = 19,
    MacOS_13_plus = 20,
    MacOS_sub_13 = 21
  };
  readonly attribute nsIGfxInfo_FontVisibilityDeviceDetermination fontVisibilityDetermination;
  readonly attribute AString fontVisibilityDeterminationStr;

  /**
   * The name of the display adapter.
   */
  readonly attribute AString adapterDescription;
  readonly attribute AString adapterDescription2;

  readonly attribute AString adapterDriver;
  readonly attribute AString adapterDriver2;

  /* These types are inspired by DXGI_ADAPTER_DESC */
  readonly attribute AString adapterVendorID;
  readonly attribute AString adapterVendorID2;

  readonly attribute AString adapterDeviceID;
  readonly attribute AString adapterDeviceID2;

  readonly attribute AString adapterSubsysID;
  readonly attribute AString adapterSubsysID2;

  /**
   * The amount of RAM in MB in the display adapter.
   */
  readonly attribute unsigned long adapterRAM;
  readonly attribute unsigned long adapterRAM2;

  readonly attribute AString adapterDriverVendor;
  readonly attribute AString adapterDriverVendor2;

  readonly attribute AString adapterDriverVersion;
  readonly attribute AString adapterDriverVersion2;

  readonly attribute AString adapterDriverDate;
  readonly attribute AString adapterDriverDate2;

  readonly attribute boolean isGPU2Active;

  readonly attribute ACString drmRenderDevice;

  /**
   * Returns an array of objects describing each monitor. Guaranteed properties
   * are "screenWidth" and "screenHeight". This is only implemented on Desktop.
   *
   * Windows additionally supplies "refreshRate" and "pseudoDisplay".
   *
   * OS X additionally supplies "scale".
   */
  [implicit_jscontext]
  jsval getMonitors();

  Array<ACString> getFailures(out Array<long> indices);

  [noscript, notxpcom] void logFailure(in ACString failure);

%{C++
  /*
   * A set of constants for features that we can ask this GfxInfo object
   * about via GetFeatureStatus
   */
  enum FeatureType : uint8_t {
    FEATURE_INVALID = 0,
#define GFXINFO_FEATURE(id, name, pref) FEATURE_##id,
#include "mozilla/widget/GfxInfoFeatureDefs.h"
#undef GFXINFO_FEATURE
    FEATURE_COUNT,
    /* This must be the first value after INVALID/ALL/OPTIONAL. */
    FEATURE_START = FEATURE_DIRECT2D
  };

  /*
   * A set of return values from GetFeatureStatus
   */
  enum FeatureStatusType : uint8_t {
    FEATURE_STATUS_INVALID = 0,
#define GFXINFO_FEATURE_STATUS(id) FEATURE_##id,
#include "mozilla/widget/GfxInfoFeatureStatusDefs.h"
#undef GFXINFO_FEATURE_STATUS
  };
%}

  /**
   * Ask about a feature, and return the status of that feature.
   * If the feature is not ok then aFailureId will give a unique failure Id
   * otherwise it will be empty.
   */
  long getFeatureStatus(in long aFeature, [optional] out ACString aFailureId);
  AString getFeatureStatusStr(in AString aFeature, [optional] out ACString aFailureId);

  /*
   * Ask about a feature, return the minimum driver version required for it if its status is
   * FEATURE_BLOCKED_DRIVER_VERSION, otherwise return an empty string.
   */
  AString getFeatureSuggestedDriverVersion(in long aFeature);
  AString getFeatureSuggestedDriverVersionStr(in AString aFeature);

  // only useful on X11
  [noscript, notxpcom] void GetData();

  /**
   * Maximum refresh rate among detected monitors. -1 if unknown. aMixed is set
   * to true if we know there are multiple displays and they have different
   * refresh rates, else false. The returned value is in Hz.
   */
  [noscript, notxpcom] long GetMaxRefreshRate(out boolean aMixed);

  [implicit_jscontext]
  jsval getInfo();

  // Return an object describing all features that have been configured:
  //
  //   "features": [
  //     // For each feature:
  //     {
  //       "name": <string>,
  //       "description": <string>,
  //       "status": <string>,
  //       "log": [
  //          // One or more log entries, the first denotes the default value.
  //          {
  //            "type": <string>,    // "base", "user", "env", or "runtime"
  //            "status": <string>,
  //            "message": <string>  // Set unless type is "base" and status is "available".
  //          }
  //       ]
  //     }
  //   ]
  //   "fallbacks": [
  //     // For each workaround:
  //     {
  //       "name:" <string>,
  //       "description": <string>,
  //       "message": <string>
  //     ]
  //   }
  //
  // When a message is prefixed with a '#', it is a special status code. Status
  // codes are unique identifiers that can be searched in the codebase to find
  // which line of code caused the message. Some codes are standardized to
  // improve about:support messaging:
  //
  //   "[CONTEXT_]FEATURE_FAILURE_BUG_<number>"
  //     CONTEXT is optional and can currently only be "BLOCKLIST".
  //     <number> refers to a bug number in Bugzilla.
  //
  [implicit_jscontext]
  jsval getFeatureLog();

  // Returns an object containing information about graphics features. It is
  // intended to be directly included into the Telemetry environment.
  //
  //   "layers":
  //   {
  //     "compositor": "d3d9", "d3d11", "opengl", "basic", or "none"
  //                   // ("none" indicates no compositors have been created)
  //     // Feature is one of "d3d9", "d3d11", "opengl", "basic", or "d2d".
  //     "<feature>": {
  //       // Each backend can have one of the following statuses:
  //       //   "unused"      - This feature has not been requested.
  //       //   "unavailable" - OS version or restriction prevents use.
  //       //   "blocked"     - An internal condition (such as safe mode) prevents use.
  //       //   "blocklisted" - Blocked due to a blocklist restriction.
  //       //   "denied"      - Blocked due to allowlist restrictions.
  //       //   "disabled"    - User explicitly disabled this default feature.
  //       //   "failed"      - Feature failed to initialize.
  //       //   "available"   - User has this feature available by default.
  //       "status": "<status>",
  //       "version": "<version>",
  //       "warp": true|false,           // D3D11 only.
  //       "textureSharing": true|false, // D3D11 only.
  //     }
  //   }
  [implicit_jscontext]
  jsval getFeatures();

  // Returns an array listing any active crash guards.
  //
  //   [
  //     {
  //       // Type is one of "d3d11layers", or "glcontext".
  //       "type":        "<identifier>",
  //
  //       // Preference that must be deleted/reset to retrigger the guard.
  //       "prefName":    "<preference>",
  //     }
  //   ]
  [implicit_jscontext]
  jsval getActiveCrashGuards();

  // Forces the GPU process to start or shutdown. This is intended only for
  // xpcshell-tests.
  boolean controlGPUProcessForXPCShell(in boolean aEnable);

  // Kills the GPU process cleanly, without generating a crash dump.
  // This is intended only for use by tests.
  void killGPUProcessForTests();

  // Causes the GPU process to crash. This is intended only for use by tests.
  void crashGPUProcessForTests();
};