wgpu 1.2.0 → 1.2.1

data/lib/wgpu/native/capabilities.rb

@@ -3,10 +3,14 @@
 module WGPU
   module Native
     class << self
+      # Reports whether future-based callback waiting is available.
+      # @return [Boolean]
       def future_api?
         optional_function_available?(:wgpuInstanceWaitAny)
       end
 
+      # Reports whether explicit device polling is available.
+      # @return [Boolean]
       def device_poll_available?
         optional_function_available?(:wgpuDevicePoll)
       end
@@ -15,13 +19,23 @@ module WGPU
       # implementation is a Rust panic stub. Calling it aborts the process, so
       # symbol presence alone cannot be used as a capability check.
       def compilation_info_available?
-        Distribution::VERSION != "v27.0.4.0"
+        Distribution.capability_implemented?(:compilation_info)
       end
 
+      # Reports whether querying buffer map state is safe in the pinned runtime.
+      # @return [Boolean]
       def buffer_map_state_available?
-        Distribution::VERSION != "v27.0.4.0"
+        Distribution.capability_implemented?(:buffer_map_state)
       end
 
+      # Reports whether native asynchronous pipeline creation is implemented.
+      # @return [Boolean]
+      def pipeline_async_available?
+        Distribution.capability_implemented?(:pipeline_async)
+      end
+
+      # Reports whether native logging callbacks and levels are available.
+      # @return [Boolean]
       def logging_available?
         optional_function_available?(:wgpuSetLogCallback) &&
           optional_function_available?(:wgpuSetLogLevel)

data/lib/wgpu/native/distribution.rb

@@ -7,6 +7,17 @@ module WGPU
     module Distribution
       VERSION = "v27.0.4.0"
       RELEASE_BASE_URL = "https://github.com/gfx-rs/wgpu-native/releases/download/#{VERSION}"
+      VERSION_COMPONENTS = VERSION.delete_prefix("v").split(".").map { |part| Integer(part, 10) }.freeze
+      unless VERSION_COMPONENTS.length == 4 && VERSION_COMPONENTS.all? { |part| part.between?(0, 255) }
+        raise "wgpu-native VERSION must have four byte-sized components: #{VERSION}"
+      end
+      # wgpuGetVersion packs vMAJOR.MINOR.PATCH.BUILD into four big-endian bytes.
+      ENCODED_VERSION = VERSION_COMPONENTS.reduce(0) { |encoded, part| (encoded << 8) | part }
+      UNIMPLEMENTED_CAPABILITIES = {
+        compilation_info: [VERSION].freeze,
+        buffer_map_state: [VERSION].freeze,
+        pipeline_async: [VERSION].freeze
+      }.freeze
 
       ARTIFACTS = [
         {
@@ -43,6 +54,10 @@ module WGPU
 
       module_function
 
+      # Selects the native release artifact for a Ruby platform.
+      # @param platform [String] Ruby platform identifier
+      # @return [Hash] artifact metadata
+      # @raise [LoadError] if the platform is unsupported
       def artifact_for(platform = RUBY_PLATFORM)
         raise LoadError, unsupported_platform_message(platform) if platform.include?("musl")
 
@@ -52,6 +67,12 @@ module WGPU
         raise LoadError, unsupported_platform_message(platform)
       end
 
+      # Returns the preferred versioned native-library cache directory.
+      #
+      # @param env [Hash] environment used for cache overrides
+      # @param home [String] user home directory
+      # @param host_os [String] host operating-system identifier
+      # @return [String] absolute cache directory
       def primary_cache_dir(env: ENV, home: Dir.home, host_os: RbConfig::CONFIG["host_os"])
         override = present_value(env["WGPU_CACHE_DIR"])
         return File.join(File.expand_path(override), VERSION) if override
@@ -62,24 +83,66 @@ module WGPU
         File.join(default_cache_base(env:, home:, host_os:), "wgpu-ruby", VERSION)
       end
 
+      # Returns the legacy versioned cache directory.
+      #
+      # @param home [String] user home directory
+      # @return [String] absolute legacy cache directory
       def legacy_cache_dir(home: Dir.home)
         File.join(File.expand_path(home), ".cache", "wgpu-ruby", VERSION)
       end
 
+      # Returns cache directories in lookup order.
+      #
+      # @param env [Hash] environment used for cache overrides
+      # @param home [String] user home directory
+      # @param host_os [String] host operating-system identifier
+      # @return [Array<String>] unique cache directories
       def cache_directories(env: ENV, home: Dir.home, host_os: RbConfig::CONFIG["host_os"])
         [primary_cache_dir(env:, home:, host_os:), legacy_cache_dir(home:)].uniq
       end
 
+      # Returns candidate cached library paths for a platform.
+      #
+      # @param platform [String] Ruby platform identifier
+      # @param env [Hash] environment used for cache overrides
+      # @param home [String] user home directory
+      # @param host_os [String] host operating-system identifier
+      # @return [Array<String>] candidate shared-library paths
+      # @raise [LoadError] if the platform is unsupported
       def library_paths(platform: RUBY_PLATFORM, env: ENV, home: Dir.home,
                         host_os: RbConfig::CONFIG["host_os"])
         library = artifact_for(platform)[:library]
         cache_directories(env:, home:, host_os:).map { |directory| File.join(directory, "lib", library) }
       end
 
+      # Builds the download URL for an artifact entry.
+      #
+      # @param artifact [Hash] entry from {ARTIFACTS}
+      # @return [String] release archive URL
       def release_url(artifact)
         "#{RELEASE_BASE_URL}/#{artifact.fetch(:archive)}"
       end
 
+      # Decodes the packed native version into a release tag.
+      #
+      # @param encoded_version [Integer] four-byte packed version
+      # @return [String] version in +vMAJOR.MINOR.PATCH.BUILD+ form
+      def version_string(encoded_version)
+        components = [24, 16, 8, 0].map { |shift| (encoded_version >> shift) & 0xFF }
+        "v#{components.join(".")}"
+      end
+
+      # Reports whether a native capability is implemented by the pinned release.
+      # @param name [Symbol] capability name
+      # @return [Boolean]
+      def capability_implemented?(name)
+        !UNIMPLEMENTED_CAPABILITIES.fetch(name, []).include?(VERSION)
+      end
+
+      # Builds an actionable unsupported-platform message.
+      #
+      # @param platform [String] Ruby platform identifier
+      # @return [String] diagnostic message
       def unsupported_platform_message(platform)
         supported = ARTIFACTS.map { |artifact| artifact[:pattern].inspect }.join(", ")
         <<~MESSAGE.chomp

data/lib/wgpu/native/enum_helper.rb

@@ -5,6 +5,12 @@ module WGPU
     module EnumHelper
       module_function
 
+      # Converts a symbolic enum member to its integer value.
+      # @param enum [FFI::Enum, Hash] enum mapping
+      # @param value [Symbol, Integer] member or native value
+      # @param name [String] name used in validation errors
+      # @return [Integer]
+      # @raise [ArgumentError] if the value is invalid
       def coerce(enum, value, name: "enum")
         return value if value.is_a?(Integer)
         raise ArgumentError, "#{name} must be a Symbol or Integer, got #{value.class}" unless value.is_a?(Symbol)
@@ -16,6 +22,13 @@ module WGPU
         raise ArgumentError, unknown_value_message(name, value, mapping.keys)
       end
 
+      # Converts symbolic flag names to their combined integer bitset.
+      #
+      # @param enum [FFI::Enum, Hash] flag mapping
+      # @param value [Symbol, Integer, Array<Symbol>] flags to convert
+      # @param name [String] name used in validation errors
+      # @return [Integer] combined bitset
+      # @raise [ArgumentError] if a flag is unknown or has an invalid type
       def coerce_flags(enum, value, name: "flags")
         return value if value.is_a?(Integer)
 
@@ -27,6 +40,10 @@ module WGPU
         values.reduce(0) { |flags, item| flags | coerce(enum, item, name:) }
       end
 
+      # Expands a bitset into its independent symbolic flags.
+      # @param enum [FFI::Enum, Hash] flag mapping
+      # @param value [Integer] combined bitset
+      # @return [Array<Symbol>]
       def decompose_flags(enum, value)
         raise ArgumentError, "flag value must be an Integer" unless value.is_a?(Integer)
 

data/lib/wgpu/native/enums.rb

@@ -61,6 +61,14 @@ module WGPU
       :unknown, 0x00000004
     )
 
+    CreatePipelineAsyncStatus = enum(
+      :success, 0x00000001,
+      :instance_dropped, 0x00000002,
+      :validation_error, 0x00000003,
+      :internal_error, 0x00000004,
+      :unknown, 0x00000005
+    )
+
     DeviceLostReason = enum(
       :unknown, 0x00000001,
       :destroyed, 0x00000002,