[breaking] Refactor Instance capabilities into features/limits, add SPIRV feature

doc/articles/Asynchronous Operations.md

@@ -61,7 +61,7 @@ Waits on any WGPUFuture in the list of `futures` to complete for `timeoutNS` nan
 
 ### Timed Wait {#Timed-Wait}
 
-Use of _timed waits_ (`timeoutNS > 0`), must be enabled on the WGPUInstance in @ref wgpuCreateInstance with `WGPUInstanceFeatures::timedWaitAnyEnable`, and the number of futures waited on must be less than or equal to `WGPUInstanceFeatures::timedWaitAnyMaxCount`. Supported instance features may be queried using @ref wgpuGetInstanceCapabilities.
+Use of _timed waits_ (`timeoutNS > 0`), must be enabled on the WGPUInstance in @ref wgpuCreateInstance() with @ref WGPUInstanceFeatureName_TimedWaitAnyEnable, and the number of futures waited on must be less than or equal to @ref WGPUInstanceLimits::timedWaitAnyMaxCount.
 
 ### Mixed Sources {#Mixed-Sources}
 

doc/articles/Extensions.md

@@ -34,7 +34,8 @@ When an application is running against an unknown `webgpu.h` implementation, ext
     - New (root) structs, enum/bitflag types, and callback types are always supported if the methods that accept them exist.
 - New enum/bitflag values and [chained structs](@ref StructChaining) are available iff the corresponding "feature" was already explicitly enabled for the context where they're used:
     - Device features are detected via @ref wgpuAdapterGetFeatures() and enabled via @ref WGPUDeviceDescriptor::requiredFeatures.
-    - Instance features are detected via @ref wgpuGetInstanceCapabilities() and enabled via @ref WGPUInstanceDescriptor::capabilities.
+    - Instance features are detected via @ref wgpuHasInstanceFeature() and @ref wgpuGetInstanceFeatures(), and enabled via @ref WGPUInstanceDescriptor::requiredFeatures.
+    - Instance limits are detected via @ref wgpuGetInstanceLimits(), and enabled via @ref WGPUInstanceDescriptor::requiredLimits.
 
 The following design principles should be followed to ensure future extensibility:
 

tests/compile/main.inl

@@ -86,7 +86,7 @@ int main(void) {
     { WGPUCompilationMessage x = WGPU_COMPILATION_MESSAGE_INIT; }
     { WGPUConstantEntry x = WGPU_CONSTANT_ENTRY_INIT; }
     { WGPUFuture x = WGPU_FUTURE_INIT; }
-    { WGPUInstanceCapabilities x = WGPU_INSTANCE_CAPABILITIES_INIT; }
+    { WGPUInstanceLimits x = WGPU_INSTANCE_LIMITS_INIT; }
     { WGPULimits x = WGPU_LIMITS_INIT; }
     { WGPUMultisampleState x = WGPU_MULTISAMPLE_STATE_INIT; }
     { WGPUPassTimestampWrites x = WGPU_PASS_TIMESTAMP_WRITES_INIT; }
@@ -107,6 +107,7 @@ int main(void) {
     { WGPUStencilFaceState x = WGPU_STENCIL_FACE_STATE_INIT; }
     { WGPUStorageTextureBindingLayout x = WGPU_STORAGE_TEXTURE_BINDING_LAYOUT_INIT; }
     { WGPUSupportedFeatures x = WGPU_SUPPORTED_FEATURES_INIT; }
+    { WGPUSupportedInstanceFeatures x = WGPU_SUPPORTED_INSTANCE_FEATURES_INIT; }
     { WGPUSupportedWGSLLanguageFeatures x = WGPU_SUPPORTED_WGSL_LANGUAGE_FEATURES_INIT; }
     { WGPUSurfaceCapabilities x = WGPU_SURFACE_CAPABILITIES_INIT; }
     { WGPUSurfaceConfiguration x = WGPU_SURFACE_CONFIGURATION_INIT; }

webgpu.h

@@ -220,7 +220,7 @@ struct WGPUCompilationMessage;
 struct WGPUConstantEntry;
 struct WGPUExtent3D;
 struct WGPUFuture;
-struct WGPUInstanceCapabilities;
+struct WGPUInstanceLimits;
 struct WGPULimits;
 struct WGPUMultisampleState;
 struct WGPUOrigin3D;
@@ -243,6 +243,7 @@ struct WGPUShaderSourceWGSL;
 struct WGPUStencilFaceState;
 struct WGPUStorageTextureBindingLayout;
 struct WGPUSupportedFeatures;
+struct WGPUSupportedInstanceFeatures;
 struct WGPUSupportedWGSLLanguageFeatures;
 struct WGPUSurfaceCapabilities;
 struct WGPUSurfaceColorManagement;
@@ -605,6 +606,19 @@ typedef enum WGPUIndexFormat {
     WGPUIndexFormat_Force32 = 0x7FFFFFFF
 } WGPUIndexFormat WGPU_ENUM_ATTRIBUTE;
 
+typedef enum WGPUInstanceFeatureName {
+    /**
+     * Enable use of ::wgpuInstanceWaitAny with `timeoutNS > 0`.
+     */
+    WGPUInstanceFeatureName_TimedWaitAnyEnable = 0x00000001,
+    /**
+     * Enable passing SPIR-V shaders to @ref wgpuDeviceCreateShaderModule,
+     * via @ref WGPUShaderSourceSPIRV.
+     */
+    WGPUInstanceFeatureName_ShaderSourceSPIRV = 0x00000002,
+    WGPUInstanceFeatureName_Force32 = 0x7FFFFFFF
+} WGPUInstanceFeatureName WGPU_ENUM_ATTRIBUTE;
+
 typedef enum WGPULoadOp {
     /**
      * `0`. Indicates no value is passed for this argument. See @ref SentinelValues.
@@ -2054,32 +2068,23 @@ typedef struct WGPUFuture {
 })
 
 /**
- * Features enabled on the WGPUInstance
- *
- * Default values can be set using @ref WGPU_INSTANCE_CAPABILITIES_INIT as initializer.
+ * Default values can be set using @ref WGPU_INSTANCE_LIMITS_INIT as initializer.
  */
-typedef struct WGPUInstanceCapabilities {
+typedef struct WGPUInstanceLimits {
     WGPUChainedStruct * nextInChain;
-    /**
-     * Enable use of ::wgpuInstanceWaitAny with `timeoutNS > 0`.
-     *
-     * The `INIT` macro sets this to `WGPU_FALSE`.
-     */
-    WGPUBool timedWaitAnyEnable;
     /**
      * The maximum number @ref WGPUFutureWaitInfo supported in a call to ::wgpuInstanceWaitAny with `timeoutNS > 0`.
      *
      * The `INIT` macro sets this to `0`.
      */
     size_t timedWaitAnyMaxCount;
-} WGPUInstanceCapabilities WGPU_STRUCTURE_ATTRIBUTE;
+} WGPUInstanceLimits WGPU_STRUCTURE_ATTRIBUTE;
 
 /**
- * Initializer for @ref WGPUInstanceCapabilities.
+ * Initializer for @ref WGPUInstanceLimits.
  */
-#define WGPU_INSTANCE_CAPABILITIES_INIT _wgpu_MAKE_INIT_STRUCT(WGPUInstanceCapabilities, { \
+#define WGPU_INSTANCE_LIMITS_INIT _wgpu_MAKE_INIT_STRUCT(WGPUInstanceLimits, { \
     /*.nextInChain=*/NULL _wgpu_COMMA \
-    /*.timedWaitAnyEnable=*/WGPU_FALSE _wgpu_COMMA \
     /*.timedWaitAnyMaxCount=*/0 _wgpu_COMMA \
 })
 
@@ -3003,6 +3008,28 @@ typedef struct WGPUSupportedFeatures {
     /*.features=*/NULL _wgpu_COMMA \
 })
 
+/**
+ * Default values can be set using @ref WGPU_SUPPORTED_INSTANCE_FEATURES_INIT as initializer.
+ */
+typedef struct WGPUSupportedInstanceFeatures {
+    /**
+     * Array count for `features`. The `INIT` macro sets this to 0.
+     */
+    size_t featureCount;
+    /**
+     * The `INIT` macro sets this to `NULL`.
+     */
+    WGPUInstanceFeatureName const * features;
+} WGPUSupportedInstanceFeatures WGPU_STRUCTURE_ATTRIBUTE;
+
+/**
+ * Initializer for @ref WGPUSupportedInstanceFeatures.
+ */
+#define WGPU_SUPPORTED_INSTANCE_FEATURES_INIT _wgpu_MAKE_INIT_STRUCT(WGPUSupportedInstanceFeatures, { \
+    /*.featureCount=*/0 _wgpu_COMMA \
+    /*.features=*/NULL _wgpu_COMMA \
+})
+
 /**
  * Default values can be set using @ref WGPU_SUPPORTED_WGSL_LANGUAGE_FEATURES_INIT as initializer.
  */
@@ -3953,19 +3980,27 @@ typedef struct WGPUFutureWaitInfo {
 typedef struct WGPUInstanceDescriptor {
     WGPUChainedStruct * nextInChain;
     /**
-     * Instance capabilities to enable.
-     *
-     * The `INIT` macro sets this to @ref WGPU_INSTANCE_CAPABILITIES_INIT.
+     * Array count for `requiredFeatures`. The `INIT` macro sets this to 0.
      */
-    WGPUInstanceCapabilities capabilities;
+    size_t requiredFeatureCount;
+    /**
+     * The `INIT` macro sets this to `NULL`.
+     */
+    WGPUInstanceFeatureName const * requiredFeatures;
+    /**
+     * The `INIT` macro sets this to `NULL`.
+     */
+    WGPU_NULLABLE WGPUInstanceLimits const * requiredLimits;
 } WGPUInstanceDescriptor WGPU_STRUCTURE_ATTRIBUTE;
 
 /**
  * Initializer for @ref WGPUInstanceDescriptor.
  */
 #define WGPU_INSTANCE_DESCRIPTOR_INIT _wgpu_MAKE_INIT_STRUCT(WGPUInstanceDescriptor, { \
     /*.nextInChain=*/NULL _wgpu_COMMA \
-    /*.capabilities=*/WGPU_INSTANCE_CAPABILITIES_INIT _wgpu_COMMA \
+    /*.requiredFeatureCount=*/0 _wgpu_COMMA \
+    /*.requiredFeatures=*/NULL _wgpu_COMMA \
+    /*.requiredLimits=*/NULL _wgpu_COMMA \
 })
 
 /**
@@ -4481,10 +4516,20 @@ extern "C" {
  */
 typedef WGPUInstance (*WGPUProcCreateInstance)(WGPU_NULLABLE WGPUInstanceDescriptor const * descriptor) WGPU_FUNCTION_ATTRIBUTE;
 /**
- * Proc pointer type for @ref wgpuGetInstanceCapabilities:
- * > @copydoc wgpuGetInstanceCapabilities
+ * Proc pointer type for @ref wgpuGetInstanceFeatures:
+ * > @copydoc wgpuGetInstanceFeatures
  */
-typedef WGPUStatus (*WGPUProcGetInstanceCapabilities)(WGPUInstanceCapabilities * capabilities) WGPU_FUNCTION_ATTRIBUTE;
+typedef void (*WGPUProcGetInstanceFeatures)(WGPUSupportedInstanceFeatures * features) WGPU_FUNCTION_ATTRIBUTE;
+/**
+ * Proc pointer type for @ref wgpuGetInstanceLimits:
+ * > @copydoc wgpuGetInstanceLimits
+ */
+typedef WGPUStatus (*WGPUProcGetInstanceLimits)(WGPUInstanceLimits * limits) WGPU_FUNCTION_ATTRIBUTE;
+/**
+ * Proc pointer type for @ref wgpuHasInstanceFeature:
+ * > @copydoc wgpuHasInstanceFeature
+ */
+typedef WGPUBool (*WGPUProcHasInstanceFeature)(WGPUInstanceFeatureName feature) WGPU_FUNCTION_ATTRIBUTE;
 /**
  * Proc pointer type for @ref wgpuGetProcAddress:
  * > @copydoc wgpuGetProcAddress
@@ -5349,6 +5394,13 @@ typedef void (*WGPUProcShaderModuleRelease)(WGPUShaderModule shaderModule) WGPU_
  */
 typedef void (*WGPUProcSupportedFeaturesFreeMembers)(WGPUSupportedFeatures supportedFeatures) WGPU_FUNCTION_ATTRIBUTE;
 
+// Procs of SupportedInstanceFeatures
+/**
+ * Proc pointer type for @ref wgpuSupportedInstanceFeaturesFreeMembers:
+ * > @copydoc wgpuSupportedInstanceFeaturesFreeMembers
+ */
+typedef void (*WGPUProcSupportedInstanceFeaturesFreeMembers)(WGPUSupportedInstanceFeatures supportedInstanceFeatures) WGPU_FUNCTION_ATTRIBUTE;
+
 // Procs of SupportedWGSLLanguageFeatures
 /**
  * Proc pointer type for @ref wgpuSupportedWGSLLanguageFeaturesFreeMembers:
@@ -5506,15 +5558,23 @@ typedef void (*WGPUProcTextureViewRelease)(WGPUTextureView textureView) WGPU_FUN
  */
 WGPU_EXPORT WGPUInstance wgpuCreateInstance(WGPU_NULLABLE WGPUInstanceDescriptor const * descriptor) WGPU_FUNCTION_ATTRIBUTE;
 /**
- * Query the supported instance capabilities.
+ * Get the list of @ref WGPUInstanceFeatureName values supported by the instance.
  *
- * @param capabilities
- * The supported instance capabilities
+ * @param features
+ * This parameter is @ref ReturnedWithOwnership.
+ */
+WGPU_EXPORT void wgpuGetInstanceFeatures(WGPUSupportedInstanceFeatures * features) WGPU_FUNCTION_ATTRIBUTE;
+/**
+ * Get the limits supported by the instance.
  *
  * @returns
  * Indicates if there was an @ref OutStructChainError.
  */
-WGPU_EXPORT WGPUStatus wgpuGetInstanceCapabilities(WGPUInstanceCapabilities * capabilities) WGPU_FUNCTION_ATTRIBUTE;
+WGPU_EXPORT WGPUStatus wgpuGetInstanceLimits(WGPUInstanceLimits * limits) WGPU_FUNCTION_ATTRIBUTE;
+/**
+ * Check whether a particular @ref WGPUInstanceFeatureName is supported by the instance.
+ */
+WGPU_EXPORT WGPUBool wgpuHasInstanceFeature(WGPUInstanceFeatureName feature) WGPU_FUNCTION_ATTRIBUTE;
 /**
  * Returns the "procedure address" (function pointer) of the named function.
  * The result must be cast to the appropriate proc pointer type.
@@ -6112,6 +6172,18 @@ WGPU_EXPORT void wgpuShaderModuleRelease(WGPUShaderModule shaderModule) WGPU_FUN
 WGPU_EXPORT void wgpuSupportedFeaturesFreeMembers(WGPUSupportedFeatures supportedFeatures) WGPU_FUNCTION_ATTRIBUTE;
 /** @} */
 
+/**
+ * \defgroup WGPUSupportedInstanceFeaturesMethods WGPUSupportedInstanceFeatures methods
+ * \brief Functions whose first argument has type WGPUSupportedInstanceFeatures.
+ *
+ * @{
+ */
+/**
+ * Frees members which were allocated by the API.
+ */
+WGPU_EXPORT void wgpuSupportedInstanceFeaturesFreeMembers(WGPUSupportedInstanceFeatures supportedInstanceFeatures) WGPU_FUNCTION_ATTRIBUTE;
+/** @} */
+
 /**
  * \defgroup WGPUSupportedWGSLLanguageFeaturesMethods WGPUSupportedWGSLLanguageFeatures methods
  * \brief Functions whose first argument has type WGPUSupportedWGSLLanguageFeatures.

webgpu.yml

@@ -515,6 +515,18 @@ enums:
       - name: uint32
         doc: |
           TODO
+  - name: instance_feature_name
+    doc: |
+      TODO
+    entries:
+      - null
+      - name: timed_wait_any_enable
+        doc: |
+          Enable use of ::wgpuInstanceWaitAny with `timeoutNS > 0`.
+      - name: shader_source_SPIRV
+        doc: |
+          Enable passing SPIR-V shaders to @ref wgpuDeviceCreateShaderModule,
+          via @ref WGPUShaderSourceSPIRV.
   - name: load_op
     doc: |
       TODO
@@ -2084,25 +2096,30 @@ structs:
       - name: completed
         doc: Whether or not the future completed.
         type: bool
-  - name: instance_capabilities
+  - name: instance_descriptor
     doc: |
-      Features enabled on the WGPUInstance
+      TODO
     type: extensible
     members:
-      - name: timed_wait_any_enable
-        doc: Enable use of ::wgpuInstanceWaitAny with `timeoutNS > 0`.
-        type: bool
-      - name: timed_wait_any_max_count
-        doc: The maximum number @ref WGPUFutureWaitInfo supported in a call to ::wgpuInstanceWaitAny with `timeoutNS > 0`.
-        type: usize
-  - name: instance_descriptor
+      - name: required_features
+        doc: |
+          TODO
+        type: array<enum.instance_feature_name>
+        pointer: immutable
+      - name: required_limits
+        doc: |
+          TODO
+        type: struct.instance_limits
+        pointer: immutable
+        optional: true
+  - name: instance_limits
     doc: |
       TODO
     type: extensible
     members:
-      - name: capabilities
-        doc: Instance capabilities to enable.
-        type: struct.instance_capabilities
+      - name: timed_wait_any_max_count
+        doc: The maximum number @ref WGPUFutureWaitInfo supported in a call to ::wgpuInstanceWaitAny with `timeoutNS > 0`.
+        type: usize
   - name: limits
     doc: |
       TODO
@@ -2833,6 +2850,17 @@ structs:
           TODO
         type: array<enum.feature_name>
         pointer: immutable
+  - name: supported_instance_features
+    doc: |
+      TODO
+    type: standalone
+    free_members: true
+    members:
+      - name: features
+        doc: |
+          TODO
+        type: array<enum.instance_feature_name>
+        pointer: immutable
   - name: supported_WGSL_language_features
     doc: |
       TODO
@@ -3465,16 +3493,40 @@ functions:
         type: struct.instance_descriptor
         pointer: immutable
         optional: true
-  - name: get_instance_capabilities
-    doc: Query the supported instance capabilities.
+  - name: get_instance_features
+    doc: |
+      Get the list of @ref WGPUInstanceFeatureName values supported by the instance.
+    args:
+      - name: features
+        doc: |
+          TODO
+        type: struct.supported_instance_features
+        pointer: mutable
+        passed_with_ownership: true
+  - name: get_instance_limits
+    doc: |
+      Get the limits supported by the instance.
     returns:
       doc: Indicates if there was an @ref OutStructChainError.
       type: enum.status
     args:
-      - name: capabilities
-        doc: The supported instance capabilities
-        type: struct.instance_capabilities
+      - name: limits
+        doc: |
+          TODO
+        type: struct.instance_limits
         pointer: mutable
+  - name: has_instance_feature
+    doc: |
+      Check whether a particular @ref WGPUInstanceFeatureName is supported by the instance.
+    returns:
+      doc: |
+        TODO
+      type: bool
+    args:
+      - name: feature
+        doc: |
+          TODO
+        type: enum.instance_feature_name
 objects:
   - name: adapter
     doc: |