texel 0.1.0

data/lib/texel/image_transformations.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Texel
+  module ImageTransformations
+    FILTERS = %i[box triangle cubic mitchell lanczos].freeze
+    EDGES = %i[clamp reflect wrap zero].freeze
+
+    def flip_y
+      flipped = String.new(capacity: data.bytesize, encoding: Encoding::BINARY)
+      (height - 1).downto(0) { |row| flipped << data.byteslice(row * row_bytes, row_bytes) }
+      dup_with(data: flipped)
+    end
+
+    def convert(channels: self.channels, dtype: self.dtype)
+      validate_conversion!(channels, dtype)
+      return self if channels == self.channels && dtype == self.dtype
+
+      values = PixelData.unpack(data, self.dtype)
+      values = PixelData.convert_channels(values, width * height, self.channels, channels, self.dtype)
+      values = PixelData.convert_dtype(values, self.dtype, dtype)
+      dup_with(data: PixelData.pack(values, dtype), channels: channels, dtype: dtype)
+    end
+
+    def resize(new_width, new_height, filter: :mitchell, edge: :clamp)
+      validate_resize!(new_width, new_height, filter, edge)
+      return self if new_width == width && new_height == height
+
+      Resampler.resize(self, new_width, new_height, filter: filter, edge: edge)
+    end
+
+    def resize_to_fit(maximum)
+      raise FormatError, "maximum dimension must be a positive integer" unless maximum.is_a?(Integer) && maximum.positive?
+
+      scale = [maximum.to_f / width, maximum.to_f / height, 1.0].min
+      resize([(width * scale).round, 1].max, [(height * scale).round, 1].max)
+    end
+
+    def to_linear
+      ColorTransform.linearize(self)
+    end
+
+    def to_srgb
+      ColorTransform.delinearize(self)
+    end
+
+    def premultiply
+      transform_alpha(:premultiply)
+    end
+
+    def unpremultiply
+      transform_alpha(:unpremultiply)
+    end
+
+    def mipmaps(fast: false)
+      levels = [self]
+      levels << next_mipmap(levels.last, fast: fast) until levels.last.width == 1 && levels.last.height == 1
+      levels
+    end
+
+    private
+
+    def next_mipmap(source, fast:)
+      target_width = [source.width / 2, 1].max
+      target_height = [source.height / 2, 1].max
+      if fast && source.color_space == :srgb
+        encoded = source.dup_with(color_space: :unknown).resize(target_width, target_height, filter: :box)
+        return encoded.dup_with(color_space: :srgb)
+      end
+      return source.resize(target_width, target_height, filter: :box) if source.color_space != :srgb
+
+      linear = source.to_linear.resize(target_width, target_height, filter: :box)
+      ColorTransform.delinearize(linear, dtype: source.dtype)
+    end
+
+    def transform_alpha(operation)
+      unless [2, 4].include?(channels)
+        raise FormatError, "#{operation} requires an image with 2 or 4 channels"
+      end
+      return self if (operation == :premultiply) == premultiplied?
+
+      values = PixelData.unpack(data, dtype)
+      maximum = PixelData::MAX_VALUES.fetch(dtype).to_f
+      (width * height).times do |pixel|
+        offset = pixel * channels
+        alpha = values[offset + channels - 1].to_f / maximum
+        (channels - 1).times do |channel|
+          value = operation == :premultiply ? values[offset + channel] * alpha : divide_alpha(values[offset + channel], alpha)
+          values[offset + channel] = PixelData.cast(value, dtype)
+        end
+      end
+      dup_with(data: PixelData.pack(values, dtype), premultiplied: operation == :premultiply)
+    end
+
+    def divide_alpha(value, alpha)
+      alpha.zero? ? 0.0 : value / alpha
+    end
+
+    def validate_conversion!(target_channels, target_dtype)
+      raise FormatError, "channels must be between 1 and 4" unless target_channels.is_a?(Integer) && target_channels.between?(1, 4)
+      return if Image::DTYPE_SIZES.key?(target_dtype)
+
+      raise FormatError, "unsupported dtype #{target_dtype.inspect}"
+    end
+
+    def validate_resize!(target_width, target_height, filter, edge)
+      unless target_width.is_a?(Integer) && target_width.positive? && target_height.is_a?(Integer) && target_height.positive?
+        raise FormatError, "resize dimensions must be positive integers"
+      end
+      raise FormatError, "unsupported resize filter #{filter.inspect}" unless FILTERS.include?(filter)
+      raise FormatError, "unsupported edge mode #{edge.inspect}" unless EDGES.include?(edge)
+    end
+  end
+
+  Image.include(ImageTransformations)
+end

data/lib/texel/info.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Texel
+  Info = Data.define(:width, :height, :channels, :format) do
+    def initialize(width:, height:, channels:, format:)
+      super
+      freeze
+    end
+  end
+end

data/lib/texel/native.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Texel
+  module Native
+    class OperationError < StandardError; end
+
+    @available = false
+    @load_error = nil
+
+    class << self
+      attr_reader :load_error
+
+      def available?
+        @available
+      end
+
+      def metadata(bytes)
+        call_bridge(:metadata, bytes)
+      end
+
+      def decode(bytes, channels, dtype)
+        call_bridge(:decode, bytes, channels || 0, dtype_code(dtype))
+      end
+
+      def encode(data, format, width, height, channels, dtype, quality)
+        call_bridge(
+          :encode, data, format_code(format), width, height, channels, dtype_code(dtype), Integer(quality)
+        )
+      end
+
+      def resize(data, source_width, source_height, width, height, channels, dtype, srgb, filter, edge, premultiplied)
+        call_bridge(
+          :resize, data, source_width, source_height, width, height, channels, dtype_code(dtype),
+          srgb, filter, edge, premultiplied
+        )
+      end
+
+      def pack_f16(data)
+        call_bridge(:pack_f16, data)
+      end
+
+      private
+
+      def call_bridge(method, *arguments)
+        raise OperationError, native_unavailable_message unless available?
+
+        NativeBridge.public_send(method, *arguments)
+      rescue RuntimeError => e
+        raise OperationError, e.message
+      end
+
+      def native_unavailable_message
+        detail = load_error&.message
+        ["native extension is unavailable", detail].compact.join(": ")
+      end
+
+      def dtype_code(dtype)
+        { u8: 0, u16: 1, f32: 2 }.fetch(dtype)
+      end
+
+      def format_code(format)
+        { png: 0, jpg: 1, jpeg: 1, bmp: 2, tga: 3, hdr: 4 }.fetch(format)
+      end
+    end
+
+    unless ENV["TEXEL_DISABLE_NATIVE"] == "1"
+      load_errors = []
+      ruby_abi = RUBY_VERSION.split(".").first(2).join(".")
+
+      ["texel/#{ruby_abi}/texel_native", "texel/texel_native"].each do |extension|
+        begin
+          require extension
+          @available = true
+          break
+        rescue LoadError => error
+          load_errors << error
+        end
+      end
+
+      unless @available
+        begin
+          require_relative "../../ext/texel/texel_native"
+          @available = true
+        rescue LoadError => development_error
+          @load_error = development_error
+          @load_error.set_backtrace(load_errors.first&.backtrace || development_error.backtrace)
+        end
+      end
+    end
+  end
+end

data/lib/texel/pixel_data.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Texel
+  module PixelData
+    MAX_VALUES = { u8: 255, u16: 65_535, f32: 1.0 }.freeze
+    UNPACK_DIRECTIVES = { u8: "C*", u16: "S<*", f32: "e*" }.freeze
+    PACK_DIRECTIVES = { u8: "C*", u16: "S<*", f32: "e*" }.freeze
+
+    module_function
+
+    def unpack(data, dtype)
+      data.unpack(UNPACK_DIRECTIVES.fetch(dtype))
+    end
+
+    def pack(values, dtype)
+      values.pack(PACK_DIRECTIVES.fetch(dtype)).b
+    end
+
+    def normalize(value, dtype)
+      value.to_f / MAX_VALUES.fetch(dtype)
+    end
+
+    def denormalize(value, dtype)
+      maximum = MAX_VALUES.fetch(dtype)
+      clamped = value.clamp(0.0, 1.0)
+      return clamped if dtype == :f32
+
+      (clamped * maximum).round
+    end
+
+    def cast(value, dtype)
+      return value.to_f if dtype == :f32
+
+      value.round.clamp(0, MAX_VALUES.fetch(dtype))
+    end
+
+    def convert_dtype(values, source, target)
+      return values if source == target
+
+      values.map { |value| denormalize(normalize(value, source), target) }
+    end
+
+    def convert_channels(values, pixel_count, source_channels, target_channels, dtype)
+      return values if source_channels == target_channels
+
+      maximum = MAX_VALUES.fetch(dtype)
+      result = Array.new(pixel_count * target_channels)
+      pixel_count.times do |pixel_index|
+        source = values.slice(pixel_index * source_channels, source_channels)
+        target = channel_values(source, source_channels, target_channels, maximum, dtype)
+        result[pixel_index * target_channels, target_channels] = target
+      end
+      result
+    end
+
+    def channel_values(source, source_channels, target_channels, maximum, dtype)
+      red, green, blue, alpha = rgba_values(source, source_channels, maximum)
+      gray = cast((red * 0.299) + (green * 0.587) + (blue * 0.114), dtype)
+
+      case target_channels
+      when 1 then [gray]
+      when 2 then [gray, alpha]
+      when 3 then [red, green, blue]
+      when 4 then [red, green, blue, alpha]
+      end
+    end
+    private_class_method :channel_values
+
+    def rgba_values(source, source_channels, maximum)
+      case source_channels
+      when 1 then [source[0], source[0], source[0], maximum]
+      when 2 then [source[0], source[0], source[0], source[1]]
+      when 3 then [source[0], source[1], source[2], maximum]
+      when 4 then source
+      end
+    end
+    private_class_method :rgba_values
+  end
+end

data/lib/texel/registry.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Texel
+  module Registry
+    Entry = Data.define(:format, :magic, :codec, :extensions, :required_gem)
+
+    @entries = {}
+
+    class << self
+      def register(format, magic:, codec:, extensions: [format.to_s], required_gem: nil)
+        normalized = format.to_sym
+        @entries[normalized] = Entry.new(
+          format: normalized,
+          magic: magic,
+          codec: codec,
+          extensions: Array(extensions).map { |extension| extension.to_s.downcase }.freeze,
+          required_gem: required_gem
+        ).freeze
+      end
+
+      def fetch(format)
+        @entries[format.to_sym]
+      end
+
+      def formats
+        @entries.keys.freeze
+      end
+
+      def detect(bytes, extension: nil)
+        detected = @entries.values.find { |entry| magic_matches?(entry.magic, bytes) }
+        return detected.format if detected
+
+        by_extension(extension)&.format
+      end
+
+      def codec_for!(format, operation:)
+        entry = fetch(format)
+        raise FormatError, "unsupported image format #{format.inspect}" unless entry
+        if entry.required_gem && !entry.codec
+          raise MissingCodecError, "#{entry.format.to_s.upcase} requires the #{entry.required_gem} gem"
+        end
+        unless entry.codec&.public_send("can_#{operation}?", entry.format)
+          raise MissingCodecError, "#{entry.format.to_s.upcase} #{operation} support is unavailable"
+        end
+
+        entry.codec
+      end
+
+      private
+
+      def magic_matches?(magic, bytes)
+        return false unless magic
+        return magic.call(bytes) if magic.respond_to?(:call)
+
+        Array(magic).any? { |signature| bytes.start_with?(signature.b) }
+      end
+
+      def by_extension(extension)
+        return unless extension
+
+        normalized = extension.to_s.delete_prefix(".").downcase
+        @entries.values.find { |entry| entry.extensions.include?(normalized) }
+      end
+    end
+  end
+end

data/lib/texel/resampler.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Texel
+  module Resampler
+    FILTER_CODES = { box: 1, triangle: 2, cubic: 3, mitchell: 5, lanczos: 7 }.freeze
+    EDGE_CODES = { clamp: 0, reflect: 1, wrap: 2, zero: 3 }.freeze
+
+    module_function
+
+    def resize(image, width, height, filter:, edge:)
+      if encoded_srgb_requires_linear_path?(image)
+        linear = ColorTransform.linearize(image)
+        resized = resize(linear, width, height, filter: filter, edge: edge)
+        return ColorTransform.delinearize(resized, dtype: image.dtype)
+      end
+
+      if Native.available?
+        data = Native.resize(
+          image.data, image.width, image.height, width, height, image.channels, image.dtype,
+          image.color_space == :srgb, FILTER_CODES.fetch(filter), EDGE_CODES.fetch(edge), image.premultiplied?
+        )
+        return image.dup_with(data: data, width: width, height: height)
+      end
+
+      resize_in_ruby(image, width, height)
+    rescue Native::OperationError => e
+      raise FormatError, "resize failed: #{e.message}"
+    end
+
+    def encoded_srgb_requires_linear_path?(image)
+      image.color_space == :srgb && (image.dtype != :u8 || !Native.available?)
+    end
+    private_class_method :encoded_srgb_requires_linear_path?
+
+    def resize_in_ruby(image, target_width, target_height)
+      source = PixelData.unpack(image.data, image.dtype)
+      output = Array.new(target_width * target_height * image.channels)
+      target_height.times do |target_y|
+        source_y = (((target_y + 0.5) * image.height / target_height) - 0.5).clamp(0, image.height - 1)
+        y0, y1, vertical = interpolation_points(source_y, image.height)
+        target_width.times do |target_x|
+          source_x = (((target_x + 0.5) * image.width / target_width) - 0.5).clamp(0, image.width - 1)
+          x0, x1, horizontal = interpolation_points(source_x, image.width)
+          image.channels.times do |channel|
+            output[((target_y * target_width) + target_x) * image.channels + channel] = interpolate(
+              source, image, x0, x1, y0, y1, channel, horizontal, vertical
+            )
+          end
+        end
+      end
+      image.dup_with(data: PixelData.pack(output, image.dtype), width: target_width, height: target_height)
+    end
+    private_class_method :resize_in_ruby
+
+    def interpolation_points(position, size)
+      lower = position.floor
+      upper = [lower + 1, size - 1].min
+      [lower, upper, position - lower]
+    end
+    private_class_method :interpolation_points
+
+    def interpolate(source, image, x0, x1, y0, y1, channel, horizontal, vertical)
+      top = mix(sample(source, image, x0, y0, channel), sample(source, image, x1, y0, channel), horizontal)
+      bottom = mix(sample(source, image, x0, y1, channel), sample(source, image, x1, y1, channel), horizontal)
+      PixelData.cast(mix(top, bottom, vertical), image.dtype)
+    end
+    private_class_method :interpolate
+
+    def sample(source, image, x, y, channel)
+      source[((y * image.width) + x) * image.channels + channel]
+    end
+    private_class_method :sample
+
+    def mix(left, right, amount)
+      left + ((right - left) * amount)
+    end
+    private_class_method :mix
+  end
+end

data/lib/texel/source_reader.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Texel
+  module SourceReader
+    Source = Data.define(:bytes, :extension)
+
+    module_function
+
+    def read(source)
+      return read_path(source) if path?(source)
+      return read_io(source) if source.respond_to?(:read)
+      return Source.new(bytes: immutable_binary(source), extension: nil) if source.is_a?(String)
+
+      raise FormatError, "source must be a file path, binary String, or readable IO"
+    end
+
+    def extension_for_path(path)
+      value = path.respond_to?(:to_path) ? path.to_path : path
+      File.extname(value).delete_prefix(".").downcase.then { |extension| extension unless extension.empty? }
+    end
+
+    def path?(source)
+      source.respond_to?(:to_path) || (source.is_a?(String) && File.file?(source))
+    rescue ArgumentError
+      false
+    end
+    private_class_method :path?
+
+    def read_path(source)
+      path = source.respond_to?(:to_path) ? source.to_path : source
+      Source.new(bytes: File.binread(path).freeze, extension: extension_for_path(path))
+    rescue SystemCallError => e
+      raise FormatError, "could not read #{path}: #{e.message}"
+    end
+    private_class_method :read_path
+
+    def read_io(io)
+      bytes = io.read
+      raise FormatError, "IO#read must return a String" unless bytes.is_a?(String)
+
+      Source.new(bytes: immutable_binary(bytes), extension: io.respond_to?(:path) ? extension_for_path(io.path) : nil)
+    end
+    private_class_method :read_io
+
+    def immutable_binary(bytes)
+      return bytes if bytes.encoding == Encoding::BINARY && bytes.frozen?
+
+      bytes.dup.force_encoding(Encoding::BINARY).freeze
+    end
+    private_class_method :immutable_binary
+  end
+end

data/lib/texel/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Texel
+  VERSION = "0.1.0"
+end

data/lib/texel/wgpu.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require_relative "../texel"
+require_relative "half_float"
+
+module Texel
+  module WGPU
+    ALIGNMENT = 256
+    FORMAT_ALIASES = {
+      r8unorm: :r8_unorm,
+      rg8unorm: :rg8_unorm,
+      rgba8unorm: :rgba8_unorm,
+      rgba8unorm_srgb: :rgba8_unorm_srgb,
+      r16float: :r16_float,
+      rg16float: :rg16_float,
+      rgba16float: :rgba16_float,
+      r32float: :r32_float,
+      rg32float: :rg32_float,
+      rgba32float: :rgba32_float
+    }.freeze
+    FORMAT_INFO = {
+      r8_unorm: { channels: 1, dtype: :u8, transfer: :u8 },
+      rg8_unorm: { channels: 2, dtype: :u8, transfer: :u8 },
+      rgba8_unorm: { channels: 4, dtype: :u8, transfer: :u8 },
+      rgba8_unorm_srgb: { channels: 4, dtype: :u8, transfer: :u8 },
+      r16_float: { channels: 1, dtype: :f32, transfer: :f16 },
+      rg16_float: { channels: 2, dtype: :f32, transfer: :f16 },
+      rgba16_float: { channels: 4, dtype: :f32, transfer: :f16 },
+      r32_float: { channels: 1, dtype: :f32, transfer: :f32 },
+      rg32_float: { channels: 2, dtype: :f32, transfer: :f32 },
+      rgba32_float: { channels: 4, dtype: :f32, transfer: :f32 }
+    }.freeze
+
+    module_function
+
+    def upload(image, device:, queue:, usage: %i[texture_binding copy_dst], mips: true, format: nil, label: nil)
+      validate_image!(image)
+      texture_format = normalize_format(format || infer_format(image))
+      levels = mips ? image.mipmaps : [image]
+      texture = device.create_texture(
+        label: label,
+        size: extent(image),
+        format: texture_format,
+        usage: normalize_usage(usage),
+        mip_level_count: levels.length
+      )
+
+      levels.each_with_index do |level, mip_level|
+        data, bytes_per_row = pad_rows(level, format: texture_format)
+        queue.write_texture(
+          destination: { texture: texture, mip_level: mip_level, origin: { x: 0, y: 0, z: 0 } },
+          data: data,
+          data_layout: { offset: 0, bytes_per_row: bytes_per_row, rows_per_image: level.height },
+          size: extent(level)
+        )
+      end
+      texture
+    end
+
+    def infer_format(image)
+      validate_image!(image)
+      if image.channels == 3
+        raise FormatError, "3-channel images are unsupported by WebGPU; convert to 4 channels first"
+      end
+
+      case [image.dtype, image.channels, image.color_space]
+      in [:u8, 4, :srgb] then :rgba8_unorm_srgb
+      in [:u8, 4, _] then :rgba8_unorm
+      in [:u8, 1, _] then :r8_unorm
+      in [:u8, 2, _] then :rg8_unorm
+      in [:f32, 4, _] then :rgba16_float
+      in [:f32, 1, _] then :r16_float
+      in [:f32, 2, _] then :rg16_float
+      else
+        raise FormatError, "WebGPU upload does not support #{image.dtype} images with #{image.channels} channels"
+      end
+    end
+
+    def pad_rows(image, format: nil)
+      texture_format = normalize_format(format || infer_format(image))
+      info = validate_format!(image, texture_format)
+      transfer_data = transfer_data(image, info.fetch(:transfer))
+      component_size = { u8: 1, f16: 2, f32: 4 }.fetch(info.fetch(:transfer))
+      row_bytes = image.width * image.channels * component_size
+      bytes_per_row = align(row_bytes)
+      return [transfer_data.freeze, bytes_per_row] if row_bytes == bytes_per_row
+
+      padding = "\0".b * (bytes_per_row - row_bytes)
+      padded = String.new(capacity: bytes_per_row * image.height, encoding: Encoding::BINARY)
+      image.height.times do |row|
+        padded << transfer_data.byteslice(row * row_bytes, row_bytes) << padding
+      end
+      [padded.freeze, bytes_per_row]
+    end
+
+    def align(byte_count)
+      ((byte_count + ALIGNMENT - 1) / ALIGNMENT) * ALIGNMENT
+    end
+
+    def extent(image)
+      { width: image.width, height: image.height, depth_or_array_layers: 1 }
+    end
+    private_class_method :extent
+
+    def transfer_data(image, transfer)
+      transfer == :f16 ? HalfFloat.pack(image.data) : image.data
+    end
+    private_class_method :transfer_data
+
+    def validate_format!(image, format)
+      info = FORMAT_INFO[format]
+      raise FormatError, "unsupported WebGPU texture format #{format.inspect}" unless info
+      return info if image.channels == info.fetch(:channels) && image.dtype == info.fetch(:dtype)
+
+      expected = "#{info.fetch(:dtype)}/#{info.fetch(:channels)}ch"
+      raise FormatError, "#{format} requires #{expected} pixels, got #{image.dtype}/#{image.channels}ch"
+    end
+    private_class_method :validate_format!
+
+    def normalize_format(format)
+      symbol = format.to_sym
+      FORMAT_ALIASES.fetch(symbol, symbol)
+    end
+    private_class_method :normalize_format
+
+    def normalize_usage(usage)
+      values = usage.is_a?(Array) ? usage.dup : [usage]
+      values << :copy_dst unless values.include?(:copy_dst)
+      values.freeze
+    end
+    private_class_method :normalize_usage
+
+    def validate_image!(image)
+      raise FormatError, "expected a Texel::Image" unless image.is_a?(Image)
+    end
+    private_class_method :validate_image!
+  end
+end