wgpu 1.1.0 → 1.2.1

data/lib/wgpu/native/distribution.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module WGPU
+  module Native
+    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 = [
+        {
+          pattern: /x86_64-linux/,
+          archive: "wgpu-linux-x86_64-release.zip",
+          library: "libwgpu_native.so",
+          sha256: "271481ef76fbf3ea09631a6079e9493636ecf813cd9c92306c44a1a452991ba1"
+        },
+        {
+          pattern: /aarch64-linux/,
+          archive: "wgpu-linux-aarch64-release.zip",
+          library: "libwgpu_native.so",
+          sha256: "a2f22248200997b69373273b10d50a58164f6ed840877289f3e46bff317b134e"
+        },
+        {
+          pattern: /x86_64-darwin/,
+          archive: "wgpu-macos-x86_64-release.zip",
+          library: "libwgpu_native.dylib",
+          sha256: "660fe9be59b555ec1d7c839e5cf8b6c71762938af61ab444a7a58dd87970dba2"
+        },
+        {
+          pattern: /arm64-darwin/,
+          archive: "wgpu-macos-aarch64-release.zip",
+          library: "libwgpu_native.dylib",
+          sha256: "15367c26fdbe6892db35007d39f3883593384e777360b70e6bd704cb5dedde53"
+        },
+        {
+          pattern: /(?:x64|x86_64)-(?:mingw|mswin)/,
+          archive: "wgpu-windows-x86_64-msvc-release.zip",
+          library: "wgpu_native.dll",
+          sha256: "f14ca334b4d253881bde2605bd147f332178d705f56fbd74f81458797c77fce1"
+        }
+      ].map(&:freeze).freeze
+
+      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")
+
+        artifact = ARTIFACTS.find { |candidate| candidate[:pattern].match?(platform) }
+        return artifact if artifact
+
+        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
+
+        xdg_cache = present_value(env["XDG_CACHE_HOME"])
+        return File.join(File.expand_path(xdg_cache), "wgpu-ruby", VERSION) if xdg_cache
+
+        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
+          Unsupported platform: #{platform}
+          Supported 64-bit platforms: #{supported}
+          Build wgpu-native for this host and set WGPU_LIB_PATH to the shared library.
+        MESSAGE
+      end
+
+      def default_cache_base(env:, home:, host_os:)
+        case host_os
+        when /darwin/
+          File.join(File.expand_path(home), "Library", "Caches")
+        when /mingw|mswin/
+          local_app_data = present_value(env["LOCALAPPDATA"])
+          local_app_data || File.join(File.expand_path(home), "AppData", "Local")
+        else
+          File.join(File.expand_path(home), ".cache")
+        end
+      end
+      private_class_method :default_cache_base
+
+      def present_value(value)
+        value unless value.nil? || value.empty?
+      end
+      private_class_method :present_value
+    end
+
+    WGPU_VERSION = Distribution::VERSION
+  end
+end

data/lib/wgpu/native/enum_helper.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module WGPU
+  module Native
+    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)
+
+        mapping = mapping_for(enum)
+        result = mapping[value]
+        return result unless result.nil?
+
+        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)
+
+        values = value.is_a?(Array) ? value : [value]
+        unless values.all? { |item| item.is_a?(Symbol) }
+          raise ArgumentError, "#{name} must be a Symbol, Integer, or Array of Symbols"
+        end
+
+        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)
+
+        mapping = mapping_for(enum)
+        return [:none] if value.zero? && mapping.key?(:none)
+
+        mapping.filter_map do |symbol, bit|
+          symbol if bit.positive? && power_of_two?(bit) && (value & bit) == bit
+        end
+      end
+
+      def mapping_for(enum)
+        mapping = enum.respond_to?(:to_h) ? enum.to_h : enum
+        unless mapping.respond_to?(:key?) && mapping.respond_to?(:keys)
+          raise ArgumentError, "enum must be an FFI::Enum or Hash"
+        end
+
+        mapping
+      end
+      private_class_method :mapping_for
+
+      def unknown_value_message(name, value, candidates)
+        formatted = candidates.grep(Symbol).sort.map(&:inspect).join(", ")
+        "Unknown #{name} #{value.inspect}. Valid values: #{formatted}"
+      end
+      private_class_method :unknown_value_message
+
+      def power_of_two?(value)
+        (value & (value - 1)).zero?
+      end
+      private_class_method :power_of_two?
+    end
+  end
+end

data/lib/wgpu/native/enums.rb

@@ -61,6 +61,21 @@ 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,
+      :instance_dropped, 0x00000003,
+      :failed_creation, 0x00000004
+    )
+
     BufferMapState = enum(
       :unmapped, 0x00000001,
       :pending, 0x00000002,
@@ -283,7 +298,9 @@ module WGPU
       :sint32, 0x00000024,
       :sint32x2, 0x00000025,
       :sint32x3, 0x00000026,
-      :sint32x4, 0x00000027
+      :sint32x4, 0x00000027,
+      :unorm10_10_10_2, 0x00000028,
+      :unorm8x4_bgra, 0x00000029
     )
 
     IndexFormat = enum(
@@ -366,11 +383,11 @@ module WGPU
       :undefined, 0x00000000,
       :never, 0x00000001,
       :less, 0x00000002,
-      :less_equal, 0x00000003,
-      :greater, 0x00000004,
-      :greater_equal, 0x00000005,
-      :equal, 0x00000006,
-      :not_equal, 0x00000007,
+      :equal, 0x00000003,
+      :less_equal, 0x00000004,
+      :greater, 0x00000005,
+      :not_equal, 0x00000006,
+      :greater_equal, 0x00000007,
       :always, 0x00000008
     )
 
@@ -467,7 +484,9 @@ module WGPU
       :timeout, 0x00000003,
       :outdated, 0x00000004,
       :lost, 0x00000005,
-      :error, 0x00000006
+      :out_of_memory, 0x00000006,
+      :device_lost, 0x00000007,
+      :error, 0x00000008
     )
 
     QueryType = enum(
@@ -523,6 +542,15 @@ module WGPU
       :info, 0x00000003
     )
 
+    LogLevel = enum(
+      :off, 0x00000000,
+      :error, 0x00000001,
+      :warn, 0x00000002,
+      :info, 0x00000003,
+      :debug, 0x00000004,
+      :trace, 0x00000005
+    )
+
     FeatureName = enum(
       :undefined, 0x00000000,
       :depth_clip_control, 0x00000001,
@@ -540,7 +568,39 @@ module WGPU
       :float32_filterable, 0x0000000D,
       :float32_blendable, 0x0000000E,
       :clip_distances, 0x0000000F,
-      :dual_source_blending, 0x00000010
+      :dual_source_blending, 0x00000010,
+      # wgpu-native extensions from wgpu.h.
+      :push_constants, 0x00030001,
+      :texture_adapter_specific_format_features, 0x00030002,
+      :multi_draw_indirect_count, 0x00030004,
+      :vertex_writable_storage, 0x00030005,
+      :texture_binding_array, 0x00030006,
+      :sampled_texture_and_storage_buffer_array_non_uniform_indexing, 0x00030007,
+      :pipeline_statistics_query, 0x00030008,
+      :storage_resource_binding_array, 0x00030009,
+      :partially_bound_binding_array, 0x0003000A,
+      :texture_format_16bit_norm, 0x0003000B,
+      :texture_compression_astc_hdr, 0x0003000C,
+      :mappable_primary_buffers, 0x0003000E,
+      :buffer_binding_array, 0x0003000F,
+      :uniform_buffer_and_storage_texture_array_non_uniform_indexing, 0x00030010,
+      :polygon_mode_line, 0x00030013,
+      :polygon_mode_point, 0x00030014,
+      :conservative_rasterization, 0x00030015,
+      :spirv_shader_passthrough, 0x00030017,
+      :vertex_attribute_64bit, 0x00030019,
+      :texture_format_nv12, 0x0003001A,
+      :ray_query, 0x0003001C,
+      :shader_f64, 0x0003001D,
+      :shader_i16, 0x0003001E,
+      :shader_primitive_index, 0x0003001F,
+      :shader_early_depth_test, 0x00030020,
+      :subgroup, 0x00030021,
+      :subgroup_vertex, 0x00030022,
+      :subgroup_barrier, 0x00030023,
+      :timestamp_query_inside_encoders, 0x00030024,
+      :timestamp_query_inside_passes, 0x00030025,
+      :shader_int64, 0x00030026
     )
   end
 end