diff --git a/doc/articles/Asynchronous Operations.md b/doc/articles/Asynchronous Operations.md index bf08a3f..8380a4a 100644 --- a/doc/articles/Asynchronous Operations.md +++ b/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} diff --git a/doc/articles/Extensions.md b/doc/articles/Extensions.md index cbf14b4..e6daca5 100644 --- a/doc/articles/Extensions.md +++ b/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: diff --git a/tests/compile/main.inl b/tests/compile/main.inl index d870aeb..e75240a 100644 --- a/tests/compile/main.inl +++ b/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; } diff --git a/webgpu.h b/webgpu.h index 2f51b47..5c4aabe 100644 --- a/webgpu.h +++ b/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,11 +3980,17 @@ 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; /** @@ -3965,7 +3998,9 @@ typedef struct 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. diff --git a/webgpu.yml b/webgpu.yml index 08851e3..5ac72e6 100644 --- a/webgpu.yml +++ b/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 + 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 pointer: immutable + - name: supported_instance_features + doc: | + TODO + type: standalone + free_members: true + members: + - name: features + doc: | + TODO + type: array + 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: |