rlsl 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15d160bc13d36ac3efc480e1a99f20b374740d27d26a30a1eb73685883d16c67
-  data.tar.gz: 8f6a6dc93d8956138756c4e6356fb58b62b850998445b5dad8adcc02d22d4f18
+  metadata.gz: f67d6c410b44bdc05706df3bb9bd923d89484a779ff379a8015ff7a4003333a4
+  data.tar.gz: 9231a24a3a255afb8e6512af7cd6e9fa5201e5b5bdf2fad914370f0b843c80b2
 SHA512:
-  metadata.gz: 644a31110884bacb33734231caee01dad98086a71f5d82738e343fe14e4316938a5432b0e3c3f8c47b40f8b940f534b786d46c9a3dc56ecaad2fd8414a857be4
-  data.tar.gz: fdd2eb0cb01d5dfbf5d485e5da40bbaa61dde2c92bd6d2dda9f3ebb1f3ff0538483c6ddaa0fe8beed09ef17207e24d846ced805a0f9f473473405c6d3c737db1
+  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,8 @@
 # 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
 

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,37 +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)
-
-### Optional: Metal Shader Execution (macOS only)
-
-To run Metal shaders natively, install the [metaco](https://github.com/ydah/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.define_metal`) works without metaco. The gem is only required when calling `render_metal` at runtime.
+Ruby-style `Math::PI` and `Math::TAU` are accepted as aliases in shader source.
 
 ## Development
 
-After checking out the repo, run `bundle install` to install dependencies. Then, run `rake test` to run the tests.
+After checking out the repo, run `bundle install` to install dependencies. Then run `rake verify` for lint and tests.
 
 ```bash
 $ bundle install
-$ rake test
+$ rake verify
 ```
 
-For a quick local coverage summary, run `COVERAGE=1 rake test`. It prints the overall `lib/` coverage and the lowest-covered files without requiring extra gems.
+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.
+
+## Contributing
+
+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

@@ -12,7 +12,7 @@ module RLSL
           char = segment[index]
 
           if quote
-            quote = nil if char == quote && segment[index - 1] != "\\"
+            quote = nil if char == quote && !escaped?(segment, index)
           else
             case char
             when '"', "'"
@@ -39,7 +39,7 @@ module RLSL
 
         arguments_source.each_char.with_index do |char, index|
           if quote
-            quote = nil if char == quote && arguments_source[index - 1] != "\\"
+            quote = nil if char == quote && !escaped?(arguments_source, index)
             next
           end
 
@@ -63,6 +63,17 @@ module RLSL
 
         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_scanner.rb

@@ -39,6 +39,11 @@ module RLSL
       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]
@@ -57,6 +62,28 @@ module RLSL
         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
@@ -88,7 +115,7 @@ module RLSL
         cursor = index + 1
 
         while cursor < @code.length
-          if @code[cursor] == quote && @code[cursor - 1] != "\\"
+          if @code[cursor] == quote && !escaped?(cursor)
             return [@code[index..cursor], cursor + 1]
           end
 
@@ -97,6 +124,17 @@ module RLSL
 
         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

data/lib/rlsl/base_translator.rb

@@ -28,8 +28,9 @@ module RLSL
 
     REMOVED_IDENTIFIERS = %w[static inline].freeze
 
-    def initialize(uniforms, helpers_code, fragment_code)
+    def initialize(uniforms, helpers_code, fragment_code, name: nil)
       @uniforms = uniforms
+      @shader_name = name&.to_s
       @helpers_source = normalize_source(helpers_code)
       @fragment_source = normalize_source(fragment_code)
     end
@@ -45,11 +46,14 @@ module RLSL
     def translate_code(source)
       snippet = normalize_source(source)
       return "" if snippet.code.empty?
+      validate_source_format!(snippet)
       return snippet.code if snippet.target_code?
 
       profile.translate(snippet.code)
     end
 
+    def validate_source_format!(_source); end
+
     def generate_shader(_helpers, _fragment)
       raise NotImplementedError, "Subclasses must implement generate_shader"
     end
@@ -117,12 +121,30 @@ module RLSL
 
     def uniform_lines(resolution_line:, &block)
       lines = [resolution_line]
-      @uniforms.each do |name, type|
+      value_uniforms.each do |name, type|
         lines << block.call(name, uniform_type_to_target(type))
       end
       lines
     end
 
+    def value_uniforms
+      @uniforms.reject { |_name, type| type.to_sym == :sampler2D }
+    end
+
+    def texture_uniforms
+      @uniforms.select { |_name, type| type.to_sym == :sampler2D }
+    end
+
+    def indent_source(source, spaces)
+      prefix = " " * spaces
+      source.to_s.lines.map { |line| line.strip.empty? ? line : "#{prefix}#{line}" }.join.rstrip
+    end
+
+    def generated_by_comment(language)
+      suffix = @shader_name ? ": #{@shader_name}" : ""
+      "// #{language} shader generated by RLSL#{suffix}"
+    end
+
     def profile
       return self.class::PROFILE if self.class.const_defined?(:PROFILE, false)
 

data/lib/rlsl/code_generator/math_prelude.rb

@@ -10,33 +10,125 @@ module RLSL
           static inline vec2 vec2_new(float x, float y) { return (vec2){x, y}; }
           static inline vec3 vec3_new(float x, float y, float z) { return (vec3){x, y, z}; }
           static inline vec4 vec4_new(float x, float y, float z, float w) { return (vec4){x, y, z, w}; }
+          static inline vec2 vec2_splat(float x) { return vec2_new(x, x); }
+          static inline vec3 vec3_splat(float x) { return vec3_new(x, x, x); }
+          static inline vec4 vec4_splat(float x) { return vec4_new(x, x, x, x); }
+
+          static inline vec2 vec2_from_vec2(vec2 v) { return v; }
+          static inline vec3 vec3_from_vec3(vec3 v) { return v; }
+          static inline vec4 vec4_from_vec4(vec4 v) { return v; }
+          static inline vec3 vec3_from_vec2_float(vec2 v, float z) { return vec3_new(v.x, v.y, z); }
+          static inline vec3 vec3_from_float_vec2(float x, vec2 v) { return vec3_new(x, v.x, v.y); }
+          static inline vec4 vec4_from_vec3_float(vec3 v, float w) { return vec4_new(v.x, v.y, v.z, w); }
+          static inline vec4 vec4_from_float_vec3(float x, vec3 v) { return vec4_new(x, v.x, v.y, v.z); }
+          static inline vec4 vec4_from_vec2_vec2(vec2 a, vec2 b) { return vec4_new(a.x, a.y, b.x, b.y); }
+          static inline vec4 vec4_from_vec2_float_float(vec2 v, float z, float w) { return vec4_new(v.x, v.y, z, w); }
+          static inline vec4 vec4_from_float_vec2_float(float x, vec2 v, float w) { return vec4_new(x, v.x, v.y, w); }
+          static inline vec4 vec4_from_float_float_vec2(float x, float y, vec2 v) { return vec4_new(x, y, v.x, v.y); }
+
+          static inline float vec2_component(vec2 v, int i) { return i == 0 ? v.x : v.y; }
+          static inline float vec3_component(vec3 v, int i) { return i == 0 ? v.x : (i == 1 ? v.y : v.z); }
+          static inline float vec4_component(vec4 v, int i) {
+            return i == 0 ? v.x : (i == 1 ? v.y : (i == 2 ? v.z : v.w));
+          }
+
+          #define RLSL_DEFINE_SWIZZLES(type) \
+            static inline vec2 type##_swizzle2(type v, int a, int b) { \
+              return vec2_new(type##_component(v, a), type##_component(v, b)); \
+            } \
+            static inline vec3 type##_swizzle3(type v, int a, int b, int c) { \
+              return vec3_new(type##_component(v, a), type##_component(v, b), type##_component(v, c)); \
+            } \
+            static inline vec4 type##_swizzle4(type v, int a, int b, int c, int d) { \
+              return vec4_new(type##_component(v, a), type##_component(v, b), type##_component(v, c), type##_component(v, d)); \
+            }
+          RLSL_DEFINE_SWIZZLES(vec2)
+          RLSL_DEFINE_SWIZZLES(vec3)
+          RLSL_DEFINE_SWIZZLES(vec4)
+          #undef RLSL_DEFINE_SWIZZLES
 
           static inline vec2 vec2_add(vec2 a, vec2 b) { return (vec2){a.x + b.x, a.y + b.y}; }
           static inline vec3 vec3_add(vec3 a, vec3 b) { return (vec3){a.x + b.x, a.y + b.y, a.z + b.z}; }
+          static inline vec4 vec4_add(vec4 a, vec4 b) { return (vec4){a.x + b.x, a.y + b.y, a.z + b.z, a.w + b.w}; }
 
           static inline vec2 vec2_sub(vec2 a, vec2 b) { return (vec2){a.x - b.x, a.y - b.y}; }
           static inline vec3 vec3_sub(vec3 a, vec3 b) { return (vec3){a.x - b.x, a.y - b.y, a.z - b.z}; }
-
-          static inline vec2 vec2_mul(vec2 a, float s) { return (vec2){a.x * s, a.y * s}; }
-          static inline vec3 vec3_mul(vec3 a, float s) { return (vec3){a.x * s, a.y * s, a.z * s}; }
-
-          static inline vec2 vec2_div(vec2 a, float s) { return (vec2){a.x / s, a.y / s}; }
-          static inline vec3 vec3_div(vec3 a, float s) { return (vec3){a.x / s, a.y / s, a.z / s}; }
+          static inline vec4 vec4_sub(vec4 a, vec4 b) { return (vec4){a.x - b.x, a.y - b.y, a.z - b.z, a.w - b.w}; }
+
+          static inline vec2 vec2_add_scalar(vec2 a, float s) { return (vec2){a.x + s, a.y + s}; }
+          static inline vec3 vec3_add_scalar(vec3 a, float s) { return (vec3){a.x + s, a.y + s, a.z + s}; }
+          static inline vec4 vec4_add_scalar(vec4 a, float s) { return (vec4){a.x + s, a.y + s, a.z + s, a.w + s}; }
+          static inline vec2 vec2_scalar_add(float s, vec2 a) { return vec2_add_scalar(a, s); }
+          static inline vec3 vec3_scalar_add(float s, vec3 a) { return vec3_add_scalar(a, s); }
+          static inline vec4 vec4_scalar_add(float s, vec4 a) { return vec4_add_scalar(a, s); }
+
+          static inline vec2 vec2_sub_scalar(vec2 a, float s) { return (vec2){a.x - s, a.y - s}; }
+          static inline vec3 vec3_sub_scalar(vec3 a, float s) { return (vec3){a.x - s, a.y - s, a.z - s}; }
+          static inline vec4 vec4_sub_scalar(vec4 a, float s) { return (vec4){a.x - s, a.y - s, a.z - s, a.w - s}; }
+          static inline vec2 vec2_scalar_sub(float s, vec2 a) { return (vec2){s - a.x, s - a.y}; }
+          static inline vec3 vec3_scalar_sub(float s, vec3 a) { return (vec3){s - a.x, s - a.y, s - a.z}; }
+          static inline vec4 vec4_scalar_sub(float s, vec4 a) { return (vec4){s - a.x, s - a.y, s - a.z, s - a.w}; }
+
+          static inline vec2 vec2_mul_scalar(vec2 a, float s) { return (vec2){a.x * s, a.y * s}; }
+          static inline vec3 vec3_mul_scalar(vec3 a, float s) { return (vec3){a.x * s, a.y * s, a.z * s}; }
+          static inline vec4 vec4_mul_scalar(vec4 a, float s) { return (vec4){a.x * s, a.y * s, a.z * s, a.w * s}; }
+          static inline vec2 vec2_scalar_mul(float s, vec2 a) { return vec2_mul_scalar(a, s); }
+          static inline vec3 vec3_scalar_mul(float s, vec3 a) { return vec3_mul_scalar(a, s); }
+          static inline vec4 vec4_scalar_mul(float s, vec4 a) { return vec4_mul_scalar(a, s); }
+          static inline vec2 vec2_mul_components(vec2 a, vec2 b) { return (vec2){a.x * b.x, a.y * b.y}; }
+          static inline vec3 vec3_mul_components(vec3 a, vec3 b) { return (vec3){a.x * b.x, a.y * b.y, a.z * b.z}; }
+          static inline vec4 vec4_mul_components(vec4 a, vec4 b) { return (vec4){a.x * b.x, a.y * b.y, a.z * b.z, a.w * b.w}; }
+
+          static inline vec2 vec2_div_scalar(vec2 a, float s) { return (vec2){a.x / s, a.y / s}; }
+          static inline vec3 vec3_div_scalar(vec3 a, float s) { return (vec3){a.x / s, a.y / s, a.z / s}; }
+          static inline vec4 vec4_div_scalar(vec4 a, float s) { return (vec4){a.x / s, a.y / s, a.z / s, a.w / s}; }
+          static inline vec2 vec2_scalar_div(float s, vec2 a) { return (vec2){s / a.x, s / a.y}; }
+          static inline vec3 vec3_scalar_div(float s, vec3 a) { return (vec3){s / a.x, s / a.y, s / a.z}; }
+          static inline vec4 vec4_scalar_div(float s, vec4 a) { return (vec4){s / a.x, s / a.y, s / a.z, s / a.w}; }
+          static inline vec2 vec2_div_components(vec2 a, vec2 b) { return (vec2){a.x / b.x, a.y / b.y}; }
+          static inline vec3 vec3_div_components(vec3 a, vec3 b) { return (vec3){a.x / b.x, a.y / b.y, a.z / b.z}; }
+          static inline vec4 vec4_div_components(vec4 a, vec4 b) { return (vec4){a.x / b.x, a.y / b.y, a.z / b.z, a.w / b.w}; }
+
+          /* Legacy names used by raw C fragments. */
+          static inline vec2 vec2_mul(vec2 a, float s) { return vec2_mul_scalar(a, s); }
+          static inline vec3 vec3_mul(vec3 a, float s) { return vec3_mul_scalar(a, s); }
+          static inline vec2 vec2_div(vec2 a, float s) { return vec2_div_scalar(a, s); }
+          static inline vec3 vec3_div(vec3 a, float s) { return vec3_div_scalar(a, s); }
 
           static inline float vec2_dot(vec2 a, vec2 b) { return a.x * b.x + a.y * b.y; }
           static inline float vec3_dot(vec3 a, vec3 b) { return a.x * b.x + a.y * b.y + a.z * b.z; }
+          static inline float vec4_dot(vec4 a, vec4 b) { return a.x * b.x + a.y * b.y + a.z * b.z + a.w * b.w; }
+
+          static inline vec3 vec3_cross(vec3 a, vec3 b) {
+            return vec3_new(a.y * b.z - a.z * b.y, a.z * b.x - a.x * b.z, a.x * b.y - a.y * b.x);
+          }
 
           static inline float vec2_length(vec2 v) { return sqrtf(v.x * v.x + v.y * v.y); }
           static inline float vec3_length(vec3 v) { return sqrtf(v.x * v.x + v.y * v.y + v.z * v.z); }
+          static inline float vec4_length(vec4 v) { return sqrtf(vec4_dot(v, v)); }
+
+          static inline float vec2_distance(vec2 a, vec2 b) { return vec2_length(vec2_sub(a, b)); }
+          static inline float vec3_distance(vec3 a, vec3 b) { return vec3_length(vec3_sub(a, b)); }
+          static inline float vec4_distance(vec4 a, vec4 b) { return vec4_length(vec4_sub(a, b)); }
 
-          static inline vec2 vec2_normalize(vec2 v) { float l = vec2_length(v); return l > 0 ? vec2_div(v, l) : v; }
-          static inline vec3 vec3_normalize(vec3 v) { float l = vec3_length(v); return l > 0 ? vec3_div(v, l) : v; }
+          static inline vec2 vec2_normalize(vec2 v) { float l = vec2_length(v); return l > 0 ? vec2_div_scalar(v, l) : v; }
+          static inline vec3 vec3_normalize(vec3 v) { float l = vec3_length(v); return l > 0 ? vec3_div_scalar(v, l) : v; }
+          static inline vec4 vec4_normalize(vec4 v) { float l = vec4_length(v); return l > 0 ? vec4_div_scalar(v, l) : v; }
 
           static inline float fract(float x) { return x - floorf(x); }
+          static inline float rlsl_mod(float x, float y) { return x - y * floorf(x / y); }
+          static inline float sign_f(float x) { return (x > 0.0f) - (x < 0.0f); }
+          static inline float step_f(float edge, float x) { return x < edge ? 0.0f : 1.0f; }
           static inline float mix_f(float a, float b, float t) { return a + (b - a) * t; }
+          static inline vec2 mix_v2(vec2 a, vec2 b, float t) {
+            return (vec2){a.x + (b.x - a.x) * t, a.y + (b.y - a.y) * t};
+          }
           static inline vec3 mix_v3(vec3 a, vec3 b, float t) {
             return (vec3){a.x + (b.x - a.x) * t, a.y + (b.y - a.y) * t, a.z + (b.z - a.z) * t};
           }
+          static inline vec4 mix_v4(vec4 a, vec4 b, float t) {
+            return (vec4){a.x + (b.x - a.x) * t, a.y + (b.y - a.y) * t, a.z + (b.z - a.z) * t, a.w + (b.w - a.w) * t};
+          }
 
           static inline float clamp_f(float x, float lo, float hi) {
             return x < lo ? lo : (x > hi ? hi : x);
@@ -53,8 +145,9 @@ module RLSL
           }
 
           static inline vec2 hash22(vec2 p) {
-            float n = sinf(vec2_dot(p, vec2_new(127.1f, 311.7f)));
-            return vec2_new(fract(n * 43758.5453f), fract(n * 12345.6789f));
+            float x = sinf(vec2_dot(p, vec2_new(127.1f, 311.7f)));
+            float y = sinf(vec2_dot(p, vec2_new(269.5f, 183.3f)));
+            return vec2_new(fract(x * 43758.5453f), fract(y * 43758.5453f));
           }
 
           static inline vec3 reflect(vec3 I, vec3 N) {

data/lib/rlsl/code_generator/ruby_wrapper_generator.rb

@@ -20,7 +20,7 @@ module RLSL
             for (int x = 0; x < width; x++) {
               vec2 frag_coord = vec2_new((float)x, (float)flipped_y);
               vec3 color = shader_#{@context.name}(frag_coord, resolution, uniforms);
-              int idx = (y * width + x) * 4;
+              size_t idx = ((size_t)y * (size_t)width + (size_t)x) * 4;
               // Output as BGRA (macOS native format)
               pixels[idx] = (uint8_t)(clamp_f(color.z, 0.0f, 1.0f) * 255.0f);
               pixels[idx+1] = (uint8_t)(clamp_f(color.y, 0.0f, 1.0f) * 255.0f);
@@ -29,9 +29,49 @@ module RLSL
             }
           }
 
+          typedef struct {
+            uint8_t *pixels;
+            int width;
+            int height;
+            vec2 resolution;
+            Uniforms uniforms;
+          } render_arguments;
+
+          static void *render_without_gvl(void *opaque) {
+            render_arguments *arguments = (render_arguments *)opaque;
+
+            #ifdef __APPLE__
+            dispatch_apply(arguments->height, dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^(size_t y) {
+              render_scanline(arguments->pixels, arguments->width, arguments->height, (int)y,
+                              arguments->resolution, arguments->uniforms);
+            });
+            #else
+            for (int y = 0; y < arguments->height; y++) {
+              render_scanline(arguments->pixels, arguments->width, arguments->height, y,
+                              arguments->resolution, arguments->uniforms);
+            }
+            #endif
+
+            return NULL;
+          }
+
           static VALUE shader_#{@context.name}_render(VALUE self, VALUE rb_buffer, VALUE rb_width, VALUE rb_height#{@context.uniform_argument_list}) {
-            int width = NUM2INT(rb_width);
-            int height = NUM2INT(rb_height);
+            long long requested_width = NUM2LL(rb_width);
+            long long requested_height = NUM2LL(rb_height);
+            if (requested_width <= 0 || requested_width > INT_MAX ||
+                requested_height <= 0 || requested_height > INT_MAX) {
+              rb_raise(rb_eArgError, "width and height must be positive integers no greater than INT_MAX");
+            }
+
+            size_t width_size = (size_t)requested_width;
+            size_t height_size = (size_t)requested_height;
+            if (height_size > SIZE_MAX / width_size || width_size * height_size > SIZE_MAX / 4) {
+              rb_raise(rb_eRangeError, "render dimensions overflow the output buffer size");
+            }
+
+            size_t required_bytes = width_size * height_size * 4;
+            int width = (int)requested_width;
+            int height = (int)requested_height;
             vec2 resolution = vec2_new((float)width, (float)height);
 
             Uniforms uniforms;
@@ -39,17 +79,14 @@ module RLSL
 
             Check_Type(rb_buffer, T_STRING);
             rb_str_modify(rb_buffer);
+            if ((size_t)RSTRING_LEN(rb_buffer) < required_bytes) {
+              rb_raise(rb_eArgError, "pixel buffer is too small: need %zu bytes, got %ld",
+                       required_bytes, RSTRING_LEN(rb_buffer));
+            }
             uint8_t *pixels = (uint8_t *)RSTRING_PTR(rb_buffer);
 
-            #ifdef __APPLE__
-            dispatch_apply(height, dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^(size_t y) {
-              render_scanline(pixels, width, height, (int)y, resolution, uniforms);
-            });
-            #else
-            for (int y = 0; y < height; y++) {
-              render_scanline(pixels, width, height, y, resolution, uniforms);
-            }
-            #endif
+            render_arguments arguments = {pixels, width, height, resolution, uniforms};
+            rb_thread_call_without_gvl(render_without_gvl, &arguments, RUBY_UBF_IO, NULL);
 
             return Qnil;
           }
@@ -87,6 +124,9 @@ module RLSL
 
         <<~C.strip
           Check_Type(rb_#{uniform_name}, T_ARRAY);
+          if (RARRAY_LEN(rb_#{uniform_name}) != #{vector_size}) {
+            rb_raise(rb_eArgError, "uniform #{uniform_name} must contain exactly #{vector_size} components");
+          }
           uniforms.#{uniform_name} = #{constructor}(
         #{components.join(",\n")}
           );

data/lib/rlsl/code_generator/template_context.rb

@@ -3,10 +3,11 @@
 module RLSL
   class CodeGenerator
     class TemplateContext
-      attr_reader :name
+      attr_reader :name, :extension_name
 
-      def initialize(name:, uniforms:, helpers_block:, fragment_block:)
-        @name = name
+      def initialize(name:, uniforms:, helpers_block:, fragment_block:, extension_name: name)
+        @name = RLSL.validate_shader_name!(name)
+        @extension_name = RLSL.validate_identifier!(extension_name, context: "extension name")
         @uniforms = uniforms
         @helpers_block = helpers_block
         @fragment_block = fragment_block
@@ -23,6 +24,8 @@ module RLSL
       end
 
       def fragment_code
+        return "" unless @fragment_block
+
         @fragment_block.call
       end