electra 0.1.0

data/lib/electra/module.rb

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+module Electra
+  # Ordered SPIR-V module builder. IDs belong to a module, never a global pool.
+  class Module
+    # SPIR-V logical module layout order.
+    SECTIONS = %i[capabilities extensions imports memory_model entry_points execution_modes debug annotations declarations functions].freeze
+    attr_reader :version
+
+    # @param version [String] SPIR-V version, 1.0 through 1.6
+    # @param generator [Integer] 32-bit generator word; zero means unregistered
+    def initialize(version: "1.0", generator: 0)
+      major, minor = version.to_s.split(".").map(&:to_i)
+      raise Error, "supported versions are 1.0 through 1.6" unless major == 1 && minor && minor.between?(0, 6) && version.to_s == "#{major}.#{minor}"
+      @version = (major << 16) | (minor << 8)
+      @generator = Binary.word(generator)
+      @sections = SECTIONS.to_h { |section| [section, []] }
+      @next_id = 1
+      @types = {}
+      @constants = {}
+      @names = {}
+      @definitions = {}
+      @capabilities = {}
+      @extensions = {}
+      @imports = {}
+      @decorations = {}
+      @entries = {}
+      @functions = []
+      capability(:Shader)
+      memory_model(:Logical, :GLSL450)
+    end
+
+    # Allocate a module-local forward ID. A named reservation is idempotent.
+    # @param name [Object, nil] optional lookup key
+    # @return [Integer] SSA identifier, which must later be defined exactly once
+    def reserve_id(name = nil)
+      return @names[name] if name && @names.key?(name)
+      raise Error, "SPIR-V id limit exceeded" if @next_id >= Binary::MAX_BOUND
+      id = @next_id
+      @next_id += 1
+      @names[name] = id if name
+      id
+    end
+    alias ref reserve_id
+
+    # Low-level escape hatch. Operands follow the Khronos grammar order,
+    # including result type/result IDs. Reserve forward IDs with #ref first.
+    def emit(section, opcode, *operands)
+      buffer = @sections[section] or raise Error, "unknown section #{section}"
+      words = Binary.encode(opcode.to_s, operands)
+      schema = INSTRUCTIONS.fetch(opcode.to_s)[1]
+      index = schema.index { |kind, _| kind == "IdResult" }
+      if index
+        id = operands[index].to_i
+        raise Error, "id #{id} was not reserved in this module" unless id.between?(1, @next_id - 1)
+        raise Error, "id #{id} already defined" if @definitions[id]
+        @definitions[id] = true
+      end
+      buffer.concat(words)
+      self
+    end
+
+    # Add a capability once, using its Khronos spelling.
+    # @return [self]
+    def capability(name)
+      key = Binary.enum("Capability", name)[0]
+      emit(:capabilities, "OpCapability", name) unless @capabilities[key]
+      @capabilities[key] = true
+      self
+    end
+
+    # Add an OpExtension declaration once.
+    # @return [self]
+    def extension(name)
+      emit(:extensions, "OpExtension", name) unless @extensions[name]
+      @extensions[name] = true
+      self
+    end
+
+    # @return [Integer] deduplicated extended-instruction set ID
+    def import(name)
+      @imports[name] ||= reserve_id.tap { |id| emit(:imports, "OpExtInstImport", id, name) }
+    end
+
+    # Replace the module's single addressing/memory-model declaration.
+    # @return [self]
+    def memory_model(addressing = :Logical, model = :GLSL450)
+      @sections[:memory_model] = Binary.encode("OpMemoryModel", [addressing, model])
+      self
+    end
+
+    # Attach a debug name; does not change numeric ID allocation.
+    # @return [self]
+    def name(target, text)
+      emit(:debug, "OpName", identifier(target), text)
+    end
+
+    # Add a decoration. Conflicting values for the same decoration are errors.
+    # @return [self]
+    def decorate(target, decoration, *values)
+      apply_decoration("OpDecorate", identifier(target), decoration, values)
+    end
+
+    # Decorate a struct member, for example Offset or MatrixStride.
+    # @return [self]
+    def member_decorate(target, member, decoration, *values)
+      apply_decoration("OpMemberDecorate", identifier(target), decoration, values, member)
+    end
+
+    # Resolve and structurally intern a type description.
+    # @param description [Symbol, String, Array, Type] scalar/composite type
+    # @return [Type] immutable type record owned by this module
+    def type(description)
+      if description.is_a?(Type)
+        raise Error, "type belongs to another module" unless description.owner.equal?(self)
+        return description
+      end
+      raise Error, "type must be a Symbol, String, Type or Array" unless description.is_a?(Array) || description.is_a?(Symbol) || description.is_a?(String)
+      key = description.is_a?(Array) ? description.dup.freeze : description.to_sym
+      return @types[key] if @types.key?(key)
+      if (alias_description = expand_type_alias(key))
+        return @types[key] = type(alias_description)
+      end
+      define_type(key, description)
+    end
+
+    # @return [Type] fixed-size array with optional explicit ArrayStride
+    def array(element, length, stride: nil)
+      value = type([:array, element, length, stride])
+      decorate(value, :ArrayStride, stride) if stride
+      value
+    end
+
+    # @return [Type] struct with optional member offsets and Block decoration
+    def struct(*members, offsets: nil, block: false)
+      raise Error, "one offset per struct member is required" if offsets && offsets.length != members.length
+      value = type([:struct, members.freeze, nil, offsets&.freeze, block])
+      decorate(value, :Block) if block
+      offsets&.each_with_index { |offset, index| member_decorate(value, index, :Offset, offset) }
+      value
+    end
+
+    # Intern a scalar or nested composite constant by its exact bit pattern.
+    # @return [Value] module-scoped constant (not a mutable variable)
+    def constant(description, value)
+      value_type = type(description)
+      opcode, args = constant_encoding(value_type, value)
+      key = [value_type.id, opcode, *args]
+      @constants[key] ||= begin
+        id = reserve_id
+        emit(:declarations, opcode, value_type.id, id, *args)
+        Value.new(self, nil, value_type, id)
+      end
+    end
+
+    # @yieldparam function [Function] fragment shader builder
+    # @return [Function] completed entry point
+    def fragment_shader(name = "main", &block) = define_shader(:Fragment, name, &block)
+    # @yieldparam function [Function] vertex shader builder
+    # @return [Function] completed entry point
+    def vertex_shader(name = "main", &block) = define_shader(:Vertex, name, &block)
+
+    # Serialize sections in specification order and reject unresolved IDs.
+    # @return [String] little-endian SPIR-V bytes; retain for repeated GPU use
+    def to_binary
+      raise Error, "unfinished shader" unless @functions.all?(&:finished?)
+      missing = (1...@next_id).reject { |id| @definitions[id] }
+      raise Error, "unresolved ids: #{missing.join(', ')}" unless missing.empty?
+      binary = [Binary::MAGIC, @version, @generator, @next_id, 0, *SECTIONS.flat_map { |section| @sections.fetch(section) }].pack("V*")
+      Binary.disassemble(binary)
+      binary
+    end
+
+    # Extract an ID after checking module ownership.
+    # @return [Integer]
+    def identifier(value)
+      if value.respond_to?(:owner)
+        raise Error, "value belongs to another module" unless value.owner.equal?(self)
+      end
+      value.respond_to?(:id) ? value.id : value
+    end
+
+    private
+
+    def expand_type_alias(key)
+      return unless key.is_a?(Symbol)
+      if (match = key.to_s.match(/\A([biu]?)vec([2-4])\z/))
+        [:vector, {"" => :float, "b" => :bool, "i" => :int, "u" => :uint}.fetch(match[1]), match[2].to_i]
+      elsif (match = key.to_s.match(/\Amat([2-4])(?:x([2-4]))?\z/))
+        [:matrix, "vec#{match[2] || match[1]}".to_sym, match[1].to_i]
+      end
+    end
+
+    def define_type(key, description)
+      element = nil
+      length = nil
+      members = []
+      case key
+      when :void then kind, opcode, args = :void, "OpTypeVoid", []
+      when :bool then kind, opcode, args = :bool, "OpTypeBool", []
+      when :float then kind, opcode, args = :float, "OpTypeFloat", [32]
+      when :int then kind, opcode, args = :int, "OpTypeInt", [32, 1]
+      when :uint then kind, opcode, args = :uint, "OpTypeInt", [32, 0]
+      else
+        raise Error, "unknown type #{description.inspect}" unless key.is_a?(Array)
+        kind = key[0]
+        case kind
+        when :vector, :matrix
+          element, length = type(key[1]), key[2]
+          raise Error, "vector/matrix dimensions must be 2..4" unless length.is_a?(Integer) && length.between?(2, 4)
+          raise Error, "invalid vector scalar" if kind == :vector && !%i[float int uint bool].include?(element.kind)
+          raise Error, "matrix needs float column vectors" if kind == :matrix && !(element.kind == :vector && element.element.kind == :float)
+          capability(:Matrix) if kind == :matrix
+          opcode, args = kind == :vector ? ["OpTypeVector", [element.id, length]] : ["OpTypeMatrix", [element.id, length]]
+        when :pointer
+          element = type(key[2])
+          length = key[1]
+          opcode, args = "OpTypePointer", [key[1], element.id]
+        when :function
+          members = key.drop(1).map { |item| type(item) }
+          opcode, args = "OpTypeFunction", members.map(&:id)
+        when :image2d
+          element = type(:float)
+          opcode, args = "OpTypeImage", [element.id, :"2D", 0, 0, 0, 1, :Unknown]
+        when :sampled_image
+          element = type([:image2d])
+          opcode, args = "OpTypeSampledImage", [element.id]
+        when :array
+          element, length = type(key[1]), key[2]
+          raise Error, "array length must be positive" unless length.is_a?(Integer) && length.between?(1, 0xffffffff)
+          opcode, args = "OpTypeArray", [element.id, constant(:uint, length).id]
+        when :struct
+          members = key[1].map { |item| type(item) }
+          opcode, args = "OpTypeStruct", members.map(&:id)
+        else
+          raise Error, "unknown type #{description.inspect}"
+        end
+      end
+      # Aliases, pointers and composites all converge on structural IDs.
+      canonical = [opcode, *args, *(key.is_a?(Array) && [:array, :struct].include?(kind) ? key.drop(3) : [])].freeze
+      return @types[key] = @types[canonical] if @types.key?(canonical)
+      id = reserve_id
+      emit(:declarations, opcode, id, *args)
+      value = Type.new(id:, kind:, element:, length:, members: members.freeze, owner: self)
+      @types[key] = @types[canonical] = value
+    end
+
+    def constant_encoding(value_type, value)
+      case value_type.kind
+      when :bool
+        raise Error, "boolean constant must be true or false" unless value == true || value == false
+        opcode, args = value ? ["OpConstantTrue", []] : ["OpConstantFalse", []]
+      when :float
+        raise Error, "float constant must be Numeric" unless value.is_a?(Numeric)
+        opcode, args = "OpConstant", [Binary.float_bits(value)]
+      when :int, :uint
+        range = value_type.kind == :int ? (-0x80000000..0x7fffffff) : (0..0xffffffff)
+        raise Error, "integer constant out of range" unless value.is_a?(Integer) && range.cover?(value)
+        opcode, args = "OpConstant", [value & 0xffffffff]
+      when :vector, :matrix, :array, :struct
+        expected = value_type.kind == :struct ? value_type.members.length : value_type.length
+        raise Error, "expected #{expected} composite elements" unless value.is_a?(Array) && value.length == expected
+        args = value.each_with_index.map do |item, index|
+          component_type = value_type.kind == :struct ? value_type.members[index] : value_type.element
+          constant(component_type, item).id
+        end
+        opcode = "OpConstantComposite"
+      else
+        raise Error, "type cannot be a constant"
+      end
+      [opcode, args]
+    end
+
+    def apply_decoration(opcode, id, decoration, values, member = nil)
+      number = Binary.enum("Decoration", decoration)[0]
+      key = [id, member, number]
+      raise Error, "conflicting #{decoration} decoration" if @decorations.key?(key) && @decorations[key] != values
+      unless @decorations.key?(key)
+        emit(:annotations, opcode, id, *[member].compact, decoration, *values)
+        @decorations[key] = values.freeze
+      end
+      self
+    end
+
+    def define_shader(stage, entry_name)
+      raise Error, "shader block required" unless block_given?
+      raise Error, "duplicate entry point #{entry_name}" if @entries[[stage, entry_name]]
+      function = Function.new(self, stage)
+      @functions << function
+      yield function
+      function.finish
+      @entries[[stage, entry_name]] = function.id
+      emit(:entry_points, "OpEntryPoint", stage, function.id, entry_name, *function.interfaces)
+      emit(:execution_modes, "OpExecutionMode", function.id, :OriginUpperLeft) if stage == :Fragment
+      name(function.id, entry_name)
+      function
+    end
+  end
+end

data/lib/electra/type.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Electra
+  # Immutable structural type metadata; IDs are local to its owner module.
+  Type = Data.define(:id, :kind, :element, :length, :members, :owner) do
+    # @return [Integer] numeric SPIR-V type identifier
+    def to_i = id
+    # @return [Type] vector element type, or self for other types
+    def scalar = kind == :vector ? element : self
+  end
+end

data/lib/electra/value.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Electra
+  # Immutable SSA value or typed variable pointer, tied to one module/function.
+  class Value
+    attr_reader :owner, :function, :type, :id, :storage
+
+    def initialize(owner, function, type, id, storage = nil)
+      @owner, @function, @type, @id, @storage = owner, function, type, id, storage
+      freeze
+    end
+
+    # @return [Integer] numeric SPIR-V identifier
+    def to_i = id
+    # @return [Value] loaded SSA value, or self for an existing SSA value
+    def load
+      return self unless storage
+      function.result("OpLoad", type, id)
+    end
+
+    # Store a type-compatible value into a writable variable.
+    # @return [self]
+    def store(value)
+      raise Error, "cannot store to #{storage || 'an SSA value'}" unless %i[Output Function Private].include?(storage)
+      item = function.value(value, type)
+      function.emit("OpStore", id, item.id)
+      self
+    end
+
+    # @param index [Integer, Symbol] vector index or rgba/xyzw component
+    # @return [Value] extracted scalar
+    def component(index)
+      raise Error, "component needs a function-local value" unless function
+      index = {r: 0, g: 1, b: 2, a: 3, x: 0, y: 1, z: 2, w: 3}.fetch(index, index)
+      raise Error, "component index out of bounds" unless type.kind == :vector && index.is_a?(Integer) && index.between?(0, type.length - 1)
+      function.result("OpCompositeExtract", type.element, load.id, index)
+    end
+  end
+end

data/lib/electra/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Electra
+  # Library semantic version (independent from SPIR-V module versions).
+  VERSION = "0.1.0"
+end

data/lib/electra.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "electra/version"
+require_relative "electra/data_compat"
+
+# Pure Ruby construction and inspection of UI vertex/fragment SPIR-V modules.
+module Electra
+  # Invalid shader construction, malformed binary or unsupported assembly.
+  class Error < StandardError; end
+
+  # Decode a SPIR-V module using the generated Khronos operand grammar.
+  # @param binary [String] complete SPIR-V bytes, little or big endian
+  # @return [String] numeric-ID assembly, including round-trip header comments
+  # @raise [Error] on malformed header, framing, strings, operands or ID bounds
+  def self.disassemble(binary)
+    Binary.disassemble(binary)
+  end
+
+  # Assemble numeric-ID SPIR-V text without invoking an external compiler.
+  # @param source [String] assembly in the format returned by {.disassemble}
+  # @return [String] binary bytes
+  # @raise [Error] on malformed or unsupported assembly
+  def self.assemble(source)
+    Binary.assemble(source)
+  end
+end
+
+require_relative "electra/binary"
+require_relative "electra/type"
+require_relative "electra/module"
+require_relative "electra/value"
+require_relative "electra/function"

data/sig/electra.rbs

@@ -0,0 +1,105 @@
+module Electra
+  VERSION: String
+  type type_description = Symbol | String | Type | Array[untyped]
+  type branch = ^(Function) -> untyped
+
+  class Error < StandardError
+  end
+
+  def self.disassemble: (String binary) -> String
+  def self.assemble: (String source) -> String
+
+  class Type < Data
+    attr_reader id: Integer
+    attr_reader kind: Symbol
+    attr_reader element: Type?
+    attr_reader length: (Integer | Symbol)?
+    attr_reader members: Array[Type]
+    attr_reader owner: Module
+    def to_i: () -> Integer
+    def scalar: () -> Type
+  end
+
+  class Module
+    attr_reader version: Integer
+    def initialize: (?version: String, ?generator: Integer) -> void
+    def reserve_id: (?untyped name) -> Integer
+    alias ref reserve_id
+    def emit: (Symbol section, String | Symbol opcode, *untyped operands) -> self
+    def capability: (String | Symbol | Integer name) -> self
+    def extension: (String name) -> self
+    def import: (String name) -> Integer
+    def memory_model: (?String | Symbol addressing, ?String | Symbol model) -> self
+    def name: (Integer | Type | Value target, String text) -> self
+    def decorate: (Integer | Type | Value target, String | Symbol decoration, *untyped values) -> self
+    def member_decorate: (Integer | Type | Value target, Integer member, String | Symbol decoration, *untyped values) -> self
+    def type: (type_description description) -> Type
+    def array: (type_description element, Integer length, ?stride: Integer?) -> Type
+    def struct: (*type_description members, ?offsets: Array[Integer]?, ?block: bool) -> Type
+    def constant: (type_description description, untyped value) -> Value
+    def fragment_shader: (?String name) { (Function) -> untyped } -> Function
+    def vertex_shader: (?String name) { (Function) -> untyped } -> Function
+    def to_binary: () -> String
+    def identifier: (Integer | Type | Value value) -> Integer
+  end
+
+  class Value
+    attr_reader owner: Module
+    attr_reader function: Function?
+    attr_reader type: Type
+    attr_reader id: Integer
+    attr_reader storage: Symbol?
+    def initialize: (Module owner, Function? function, Type type, Integer id, ?Symbol? storage) -> void
+    def to_i: () -> Integer
+    def load: () -> Value
+    def store: (untyped value) -> self
+    def component: (Integer | Symbol index) -> Value
+  end
+
+  class Function
+    attr_reader owner: Module
+    attr_reader id: Integer
+    attr_reader interfaces: Array[Integer]
+    attr_reader stage: Symbol
+    def initialize: (Module owner, Symbol stage) -> void
+    def input: (type_description type, ?location: Integer?, ?builtin: Symbol?, ?flat: bool) -> Value
+    def output: (type_description type, ?location: Integer?, ?builtin: Symbol?) -> Value
+    def sampled_image_2d: (?set: Integer, ?binding: Integer) -> Value
+    def uniform_buffer: (*type_description types, ?set: Integer, ?binding: Integer, offsets: Array[Integer]) -> Value
+    def push_constant: (*type_description types, offsets: Array[Integer]) -> Value
+    def member: (Value buffer, Integer index) -> Value
+    def constant: (untyped item, ?type_description? type) -> Value
+    def value: (untyped item, ?type_description? expected) -> Value
+    def construct: (type_description description, *untyped items) -> Value
+    def splat: (untyped item, ?Integer count) -> Value
+    def sample: (Value texture, untyped uv, ?lod: untyped) -> Value
+    def add: (untyped left, untyped right) -> Value
+    def sub: (untyped left, untyped right) -> Value
+    def div: (untyped left, untyped right) -> Value
+    def mod: (untyped left, untyped right) -> Value
+    def mul: (untyped left, untyped right) -> Value
+    def negate: (untyped item) -> Value
+    def dot: (untyped left, untyped right) -> Value
+    def transpose: (untyped item) -> Value
+    def convert: (untyped item, type_description description) -> Value
+    def equal: (untyped left, untyped right) -> Value
+    def not_equal: (untyped left, untyped right) -> Value
+    def less_than: (untyped left, untyped right) -> Value
+    def less_equal: (untyped left, untyped right) -> Value
+    def greater_than: (untyped left, untyped right) -> Value
+    def greater_equal: (untyped left, untyped right) -> Value
+    def logical_and: (untyped left, untyped right) -> Value
+    def logical_or: (untyped left, untyped right) -> Value
+    def logical_not: (untyped item) -> Value
+    def select: (untyped condition, untyped yes, untyped no) -> Value
+    def if_else: (untyped condition, branch yes, ?branch? no) -> Value?
+    def discard: () -> nil
+    def discard_if: (untyped condition) -> nil
+    def return_void: () -> nil
+    def ext: (Symbol operation, *untyped items) -> Value
+    def emit: (String opcode, *untyped operands) -> self
+    def result: (String opcode, type_description type, *untyped operands) -> Value
+    def finish: () -> self
+    def finished?: () -> bool
+  end
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: electra
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yudai Takada
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+email:
+- t.yudai92@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE-SPIRV-Headers.txt
+- LICENSE.txt
+- README.md
+- examples/example_shaders.rb
+- lib/electra.rb
+- lib/electra/binary.rb
+- lib/electra/data_compat.rb
+- lib/electra/function.rb
+- lib/electra/grammar.rb
+- lib/electra/module.rb
+- lib/electra/type.rb
+- lib/electra/value.rb
+- lib/electra/version.rb
+- sig/electra.rbs
+homepage: https://github.com/noxdea/electra
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/noxdea/electra
+  changelog_uri: https://github.com/noxdea/electra/blob/main/CHANGELOG.md
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.19
+specification_version: 4
+summary: A pure Ruby SPIR-V shader emitter and disassembler
+test_files: []