rlsl 0.1.1 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0753b46ec16e2df8308ecab2b9e197cf24ab1d02f5028240d8fa6f9a886529b
-  data.tar.gz: dcaf85ad34c2e2f4aa9479dbe3f405fd063d9d46c47966a1d4e137a8c4c513cd
+  metadata.gz: f67d6c410b44bdc05706df3bb9bd923d89484a779ff379a8015ff7a4003333a4
+  data.tar.gz: 9231a24a3a255afb8e6512af7cd6e9fa5201e5b5bdf2fad914370f0b843c80b2
 SHA512:
-  metadata.gz: 13bd3732c03a7b6f0c0244ee63cc4d49ebba3264fa1dc6e8a78237b8e1d0c69ed15129787174871556e6afb8452d8cba6fb6c8bbac3f31a5488765a9866a1977
-  data.tar.gz: e970cf8b44c96da77f52c0b6b68f578c896b710f2e5e41e5089726d652e762b51f1d6e3523393f4d31c355c9f3c845f7ca115dba2d1bba0e0e14d0e013dc06fc
+  metadata.gz: e6fb3852aa2f2e8910cba85f5904e8fe1de204d07544f0289bd9fba0c68c185b848b163616e5c37f53184fedb4cb62dd456a61fe36793ce450ef40de04fd7116
+  data.tar.gz: c52f07944ea36ca72e95ee5ea6425d5e2b410cfee054dd9ccfd23053b9b42851248f7eb93f49bfa8f8899acc953590ba7240911dd4e9dd961752a86a30d73522

data/.rubocop.yml

@@ -0,0 +1,8 @@
+AllCops:
+  NewCops: disable
+
+# These class-level profile factories intentionally remain public even though
+# their source location follows the protected instance API.
+Lint/IneffectiveAccessModifier:
+  Exclude:
+    - lib/rlsl/base_translator.rb

data/CHANGELOG.md

@@ -1,6 +1,17 @@
 # Changelog
 
-## Unreleased
+## 1.0.1 - 2026-09-25
+
+- Add Metal texture bindings and tighten shader typing and target validation.
+
+## 1.0.0 - 2026-04-05
+
+- Breaking: custom translator and emitter integrations now require explicit target `PROFILE` definitions; the old stateful Prism transpiler API and compatibility aliases have been removed.
+- Added: the Ruby shader DSL now supports ternary expressions, compound local assignments, and fragment transpilation that can reference globals/constants defined in Ruby helpers.
+- Added: `functions` now supports validated signatures via `define`, plus shorthand declarations for `int`, `bool`, `mat2`, `mat3`, `mat4`, and `sampler2D`.
+- Changed: compiled shaders and Metal shaders now validate and normalize uniform values at runtime, with clearer errors for missing uniforms and invalid scalar/vector/bool inputs.
+- Fixed: integer type inference for custom function calls is preserved, and block source extraction is more reliable for assigned `if` expressions and modifier forms.
+- Fixed: native extension builds and target capability errors are more robust, reducing backend-specific build and translation failures.
 
 ## 0.1.1 - 2026-01-04
 
@@ -8,4 +19,4 @@
 
 ## 0.1.0 - 2026-01-04
 
-- Initial release.
+- Initial release.

data/README.md

@@ -1,6 +1,19 @@
-# RLSL
+<h1 align="center">RLSL</h1>
 
-Ruby Like Shading Language - A Ruby DSL for writing shaders that transpile to multiple GPU shader languages.
+<p align="center">Ruby Like Shading Language — write shaders in Ruby and transpile them to GPU and CPU targets.</p>
+
+<p align="center">
+  <a href="https://rubygems.org/gems/rlsl"><img src="https://badge.fury.io/rb/rlsl.svg" alt="Gem Version"></a>
+  <a href="https://rubygems.org/gems/rlsl"><img src="https://img.shields.io/gem/dt/rlsl?label=downloads" alt="Downloads"></a>
+  <a href="https://www.ruby-lang.org/"><img src="https://img.shields.io/badge/ruby-%3E%3D3.1-CC342D?logo=ruby&amp;logoColor=white" alt="Ruby Version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-750014.svg" alt="License"></a>
+</p>
+
+[Features](#features) · [Installation](#installation) · [Usage](#usage) · [Texture Resources](#texture-resources) · [Supported Types](#supported-types)
+
+***
+
+RLSL is a Ruby DSL for shader authoring with type inference and target-specific code generation. Its C target supports CPU rendering.
 
 ## Features
 
@@ -33,6 +46,30 @@ Or install it yourself as:
 $ gem install rlsl
 ```
 
+### Requirements
+
+- Ruby >= 3.1.0
+- [Prism](https://github.com/ruby/prism) >= 1.0.0 (for Ruby parsing)
+- A working Ruby C-extension toolchain for `RLSL.define` (`make` is selected from Ruby's `RbConfig`)
+
+The test matrix covers supported Ruby releases on Ubuntu, macOS, and Windows, and runs a dedicated compatibility job against the declared Prism 1.0.0 lower bound. Metal runtime execution is macOS-only. GLSL, WGSL, and MSL source generation is platform-independent.
+
+### Optional: Metal Shader Execution (macOS only)
+
+To run Metal shaders natively, install the [metaco](https://github.com/rbgfx/metaco) gem separately:
+
+```bash
+$ gem install metaco
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "metaco", platforms: :ruby, install_if: -> { RUBY_PLATFORM.include?("darwin") }
+```
+
+MSL code generation (`RLSL.to_msl` or `RLSL.define_metal`) works without metaco. The gem is only required when calling `render_metal` at runtime.
+
 ## Usage
 
 ### Basic Example
@@ -82,7 +119,7 @@ end
 ### Generate MSL (Metal)
 
 ```ruby
-metal_shader = RLSL.define_metal(:my_shader) do
+msl_code = RLSL.to_msl(:my_shader) do
   uniforms do
     float :time
   end
@@ -93,6 +130,8 @@ metal_shader = RLSL.define_metal(:my_shader) do
 end
 ```
 
+`RLSL.to_glsl`, `RLSL.to_wgsl`, and `RLSL.to_msl` return source strings. `RLSL.define` compiles the C target for CPU rendering, while `RLSL.define_metal` returns an `RLSL::MSL::Shader` for optional Metal execution.
+
 ### Using Helper Functions
 
 ```ruby
@@ -102,8 +141,8 @@ RLSL.to_glsl(:complex_shader) do
   end
 
   functions do
-    float :noise
-    vec3 :get_color
+    define :noise, returns: :float, params: { p: :vec2 }
+    define :get_color, returns: :vec3, params: { uv: :vec2, t: :float }
   end
 
   helpers(:ruby) do
@@ -123,6 +162,53 @@ RLSL.to_glsl(:complex_shader) do
 end
 ```
 
+Every Ruby helper function needs a complete declaration in `functions`; parameter names and order must match the Ruby method definition. This prevents unknown parameters from silently becoming floats.
+
+### Fragment Parameters and Explicit Source
+
+Fragment parameters are positional. The first parameter is the fragment coordinate (`vec2`), the second is the resolution (`vec2`), and the third is the uniform object. Their Ruby names may be changed; generated target code uses the canonical names `frag_coord`, `resolution`, and `u`.
+
+Ruby-mode blocks are captured from their source file when `fragment` or `helpers` is declared. They must come from a readable file, and multiple shader blocks must not start on the same source line. Code created by `eval`, `ruby -e`, or some REPLs has no readable source file. Once declared, later edits to the file do not change the captured shader source.
+
+For generated code and REPL use, provide the Ruby source explicitly with `fragment_source` or `helpers_source`:
+
+```ruby
+builder = RLSL::ShaderBuilder.new(:generated_shader)
+builder.fragment_source <<~RUBY
+  |coordinate, size, uniforms|
+  uv = coordinate / size
+  vec3(uv.x, uv.y, uniforms.time)
+RUBY
+```
+
+A block with parameters is automatically treated as Ruby shader code. A no-argument block defaults to legacy C-source mode; use `fragment(:ruby) { vec3(1.0, 0.0, 0.0) }` to select Ruby mode explicitly. Raw helper or fragment source can be selected with `helpers(:c)` and `fragment(:c)`.
+
+WGSL generation supports Ruby shader source only. Legacy C snippets can still be translated to C, GLSL, and MSL, but `to_wgsl` rejects them because C declarations and function syntax cannot be converted into valid WGSL by identifier rewriting alone.
+
+Use `builder.uniform_types` to inspect declared uniform types. The block form of `uniforms` remains the declaration API.
+
+Uniform names must be ASCII identifiers and may not use the RLSL-reserved names `resolution`, `frag_coord`, or `u`. Duplicate uniform declarations are rejected. The generated GLSL uniform block uses `std140` at binding 1.
+
+### Texture Resources
+
+`sampler2D` uniforms are source-generation resources for GLSL, WGSL, and MSL. Use `texture`, `texture2D`, or `textureLod` in Ruby shader code. They are not fields in the uniform buffer:
+
+- GLSL reserves binding 0 for output and binding 1 for the uniform block; textures begin at binding 2.
+- WGSL uses group 0 bindings 0 and 1 for the uniform buffer and output. Each texture/sampler pair then uses bindings 2/3, 4/5, and so on.
+- MSL uses texture 0 for output, texture 1 onward for sampled textures, and buffer 0 for uniforms. The generated shader uses an internal linear sampler.
+
+The C renderer does not bind `sampler2D` resources; attempts to use texture
+functions on C are rejected with a target-capability error. Metal runtime
+rendering accepts a `textures:` hash keyed by sampler name and binds each
+texture in declaration order:
+
+```ruby
+shader.render_metal(handle, width, height, uniforms, textures: { albedo: texture })
+```
+
+Texture-enabled source can also be emitted with `to_glsl`, `to_wgsl`, or
+`to_msl` and bound by the host application.
+
 ## Supported Types
 
 - `bool` - Boolean (conditional logic)
@@ -136,6 +222,8 @@ end
 - `mat2` - 2x2 matrix (2D texture coordinate transformations)
 - `sampler2D` - 2D texture sampler
 
+Scalar and vector uniforms (`bool`, `int`, `float`, and `vec2` through `vec4`) are supported by the CPU and Metal runtime packers. Matrix and sampler uniforms are source-generation only.
+
 ## Built-in Functions
 
 RLSL supports common shader functions:
@@ -150,35 +238,22 @@ RLSL supports common shader functions:
 - `PI` - 3.14159265358979323846
 - `TAU` - 6.28318530717958647692
 
-## Requirements
-
-- Ruby >= 3.1.0
-- [Prism](https://github.com/ruby/prism) gem (for Ruby parsing)
+Ruby-style `Math::PI` and `Math::TAU` are accepted as aliases in shader source.
 
-### Optional: Metal Shader Execution (macOS only)
+## Development
 
-To run Metal shaders natively, install the [metaco](https://github.com/ydah/metaco) gem separately:
+After checking out the repo, run `bundle install` to install dependencies. Then run `rake verify` for lint and tests.
 
 ```bash
-$ gem install metaco
-```
-
-Or add to your Gemfile:
-
-```ruby
-gem "metaco", platforms: :ruby, install_if: -> { RUBY_PLATFORM.include?("darwin") }
+$ bundle install
+$ rake verify
 ```
 
-MSL code generation (`RLSL.define_metal`) works without metaco. The gem is only required when calling `render_metal` at runtime.
-
-## Development
+For a quick local coverage summary, run `COVERAGE=1 rake test`. Set `COVERAGE_MIN=85` to enforce a minimum percentage. Target compiler integration tests use `glslangValidator`, Naga's `naga` CLI, and `xcrun metal` when those tools are installed; CI requires the GLSL and WGSL validators.
 
-After checking out the repo, run `bundle install` to install dependencies. Then, run `rake test` to run the tests.
+## Contributing
 
-```bash
-$ bundle install
-$ rake test
-```
+Bug reports and pull requests are welcome at [rbgfx/rlsl](https://github.com/rbgfx/rlsl).
 
 ## License
 

data/Rakefile

@@ -2,6 +2,7 @@
 
 require "bundler/gem_tasks"
 require "rake/testtask"
+require "rubocop/rake_task"
 
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
@@ -10,3 +11,9 @@ Rake::TestTask.new(:test) do |t|
 end
 
 task default: :test
+
+RuboCop::RakeTask.new(:lint) do |task|
+  task.options = ["--cache", "false", "--only", "Lint,Security", "lib"]
+end
+
+task verify: %i[lint test]

data/lib/rlsl/base_translator/call_parser.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module RLSL
+  class BaseTranslator
+    class CallParser
+      def self.extract_group(segment, opening_index)
+        depth = 0
+        index = opening_index
+        quote = nil
+
+        while index < segment.length
+          char = segment[index]
+
+          if quote
+            quote = nil if char == quote && !escaped?(segment, index)
+          else
+            case char
+            when '"', "'"
+              quote = char
+            when "(", "[", "{"
+              depth += 1
+            when ")", "]", "}"
+              depth -= 1
+              return [segment[(opening_index + 1)...index], index] if depth.zero?
+            end
+          end
+
+          index += 1
+        end
+
+        raise ArgumentError, "Unbalanced delimiter in translation source"
+      end
+
+      def self.split_arguments(arguments_source)
+        arguments = []
+        depth = 0
+        quote = nil
+        start_index = 0
+
+        arguments_source.each_char.with_index do |char, index|
+          if quote
+            quote = nil if char == quote && !escaped?(arguments_source, index)
+            next
+          end
+
+          case char
+          when '"', "'"
+            quote = char
+          when "(", "[", "{"
+            depth += 1
+          when ")", "]", "}"
+            depth -= 1
+          when ","
+            next unless depth.zero?
+
+            arguments << arguments_source[start_index...index]
+            start_index = index + 1
+          end
+        end
+
+        tail = arguments_source[start_index..]
+        return [] if arguments.empty? && tail.to_s.strip.empty?
+
+        arguments << tail
+      end
+
+      def self.escaped?(source, index)
+        backslashes = 0
+        cursor = index - 1
+        while cursor >= 0 && source[cursor] == "\\"
+          backslashes += 1
+          cursor -= 1
+        end
+
+        backslashes.odd?
+      end
+    end
+  end
+end

data/lib/rlsl/base_translator/code_rewriter.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative "call_parser"
+require_relative "code_scanner"
+
+module RLSL
+  class BaseTranslator
+    class CodeRewriter
+      IDENTIFIER_PATTERN = /[A-Za-z_][A-Za-z0-9_]*/
+
+      def initialize(code)
+        @code = code.to_s
+      end
+
+      def rewrite(identifier_replacements:, call_rewrites:, removed_identifiers:)
+        rewrite_segment(
+          @code,
+          identifier_replacements: stringify_keys(identifier_replacements),
+          call_rewrites: stringify_keys(call_rewrites),
+          removed_identifiers: Array(removed_identifiers).map(&:to_s)
+        )
+      end
+
+      private
+
+      def rewrite_segment(segment, identifier_replacements:, call_rewrites:, removed_identifiers:)
+        CodeScanner.new(segment).each_segment.map do |code_segment|
+          code_segment.code? ? rewrite_code_segment(
+            code_segment.text,
+            identifier_replacements: identifier_replacements,
+            call_rewrites: call_rewrites,
+            removed_identifiers: removed_identifiers
+          ) : code_segment.text
+        end.join
+      end
+
+      def rewrite_code_segment(segment, identifier_replacements:, call_rewrites:, removed_identifiers:)
+        output = +""
+        index = 0
+
+        while index < segment.length
+          if identifier_start?(segment, index)
+            identifier, identifier_end = read_identifier(segment, index)
+            call_index = skip_whitespace(segment, identifier_end)
+
+            if call_rewrites.key?(identifier) && segment[call_index] == "("
+              arguments_source, closing_index = CallParser.extract_group(segment, call_index)
+              rewritten_args = CallParser.split_arguments(arguments_source).map do |argument|
+                rewrite_segment(
+                  argument,
+                  identifier_replacements: identifier_replacements,
+                  call_rewrites: call_rewrites,
+                  removed_identifiers: removed_identifiers
+                ).strip
+              end
+              output << render_call(call_rewrites.fetch(identifier), rewritten_args)
+              index = closing_index + 1
+              next
+            end
+
+            unless removed_identifiers.include?(identifier)
+              output << (identifier_replacements[identifier] || identifier)
+            end
+            index = identifier_end
+            next
+          end
+
+          output << segment[index]
+          index += 1
+        end
+
+        output
+      end
+
+      def render_call(rewriter, arguments)
+        return rewriter.call(arguments) if rewriter.respond_to?(:call)
+
+        "#{rewriter}(#{arguments.join(', ')})"
+      end
+
+      def stringify_keys(hash)
+        hash.each_with_object({}) do |(key, value), memo|
+          memo[key.to_s] = value
+        end
+      end
+
+      def identifier_start?(segment, index)
+        segment[index] =~ /[A-Za-z_]/
+      end
+
+      def read_identifier(segment, index)
+        match = IDENTIFIER_PATTERN.match(segment, index)
+        [match[0], match.end(0)]
+      end
+
+      def skip_whitespace(segment, index)
+        current_index = index
+        current_index += 1 while current_index < segment.length && whitespace?(segment[current_index])
+        current_index
+      end
+
+      def whitespace?(char)
+        char =~ /\s/
+      end
+    end
+  end
+end

data/lib/rlsl/base_translator/code_scanner.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module RLSL
+  class BaseTranslator
+    class CodeScanner
+      Segment = Struct.new(:type, :text, keyword_init: true) do
+        def code?
+          type == :code
+        end
+      end
+
+      def initialize(code)
+        @code = code.to_s
+      end
+
+      def each_segment
+        return enum_for(:each_segment) unless block_given?
+
+        buffer = +""
+        index = 0
+
+        while index < @code.length
+          preserved, next_index = read_preserved_segment(index)
+          unless preserved
+            buffer << @code[index]
+            index += 1
+            next
+          end
+
+          yield Segment.new(type: :code, text: buffer) unless buffer.empty?
+          buffer = +""
+          yield Segment.new(type: preserved[:type], text: preserved[:text])
+          index = next_index
+        end
+
+        yield Segment.new(type: :code, text: buffer) unless buffer.empty?
+      end
+
+      private
+
+      def read_preserved_segment(index)
+        if preprocessor_start?(index)
+          directive, next_index = read_preprocessor(index)
+          return [{ type: :preprocessor, text: directive }, next_index]
+        end
+
+        if line_comment_start?(index)
+          comment, next_index = read_line_comment(index)
+          return [{ type: :line_comment, text: comment }, next_index]
+        end
+
+        if block_comment_start?(index)
+          comment, next_index = read_block_comment(index)
+          return [{ type: :block_comment, text: comment }, next_index]
+        end
+
+        if string_delimiter?(@code[index])
+          literal, next_index = read_quoted(index)
+          return [{ type: :string, text: literal }, next_index]
+        end
+
+        nil
+      end
+
+      def preprocessor_start?(index)
+        return false unless @code[index] == "#"
+
+        line_start = @code.rindex("\n", index - 1)
+        prefix = @code[(line_start ? line_start + 1 : 0)...index]
+        prefix.match?(/\A[ \t]*\z/)
+      end
+
+      def read_preprocessor(index)
+        cursor = index
+
+        loop do
+          newline_index = @code.index("\n", cursor)
+          return [@code[index..], @code.length] unless newline_index
+
+          line = @code[cursor...newline_index]
+          return [@code[index...newline_index], newline_index] unless line.rstrip.end_with?("\\")
+
+          cursor = newline_index + 1
+        end
+      end
+
+      def line_comment_start?(index)
+        @code[index, 2] == "//"
+      end
+
+      def block_comment_start?(index)
+        @code[index, 2] == "/*"
+      end
+
+      def string_delimiter?(char)
+        char == '"' || char == "'"
+      end
+
+      def read_line_comment(index)
+        newline_index = @code.index("\n", index)
+        end_index = newline_index ? newline_index : @code.length
+        [@code[index...end_index], end_index]
+      end
+
+      def read_block_comment(index)
+        closing_index = @code.index("*/", index + 2)
+        raise ArgumentError, "Unterminated block comment in translation source" unless closing_index
+
+        end_index = closing_index + 2
+        [@code[index...end_index], end_index]
+      end
+
+      def read_quoted(index)
+        quote = @code[index]
+        cursor = index + 1
+
+        while cursor < @code.length
+          if @code[cursor] == quote && !escaped?(cursor)
+            return [@code[index..cursor], cursor + 1]
+          end
+
+          cursor += 1
+        end
+
+        raise ArgumentError, "Unterminated string literal in translation source"
+      end
+
+      def escaped?(index)
+        backslashes = 0
+        cursor = index - 1
+        while cursor >= 0 && @code[cursor] == "\\"
+          backslashes += 1
+          cursor -= 1
+        end
+
+        backslashes.odd?
+      end
+    end
+  end
+end