vizcore 0.1.0 → 1.1.0

data/docs/shape_dsl.md

@@ -0,0 +1,269 @@
+# Vizcore Shape DSL
+
+Vizcore shape layers can declare 2D vector primitives directly in Ruby. Calling a
+shape primitive inside a layer automatically marks that layer as `type: :shape`.
+
+```ruby
+Vizcore.define do
+  scene :logo do
+    layer :badge do
+      rect :panel, width: 360, height: 160, radius: 24 do
+        fill "#111827"
+        stroke width: 2, color: "#38bdf8"
+        opacity 0.8
+      end
+
+      star :spark, points: 5, radius: 72, inner_radius: 28 do
+        translate x: 180, y: 0
+        map beat_pulse, to: :scale, range: 0.8..1.4
+      end
+    end
+  end
+end
+```
+
+## Primitives
+
+Supported primitives:
+
+- `circle id = nil, x: 0, y: 0, radius: 100, count: 1, segments: 96`
+- `line id = nil, x1: -100, y1: 0, x2: 100, y2: 0`
+- `rect id = nil, x: 0, y: 0, width:, height:, radius: 0`
+- `polygon id = nil, points: [[x, y], ...], closed: true`
+- `polyline id = nil, points: [[x, y], ...]`
+- `path id = nil, detail: 32, tolerance: nil, max_segments: 4096 do ... end`
+- `bezier id = nil, from:, control:, to:` for quadratic curves
+- `bezier id = nil, from:, c1:, c2:, to:` for cubic curves
+- `star id = nil, points: 5, radius: 100, inner_radius: 50`
+- `custom_shape name_or_class, **params`
+
+`draw do ... end` may be used to group declarations for readability.
+`group do ... end` applies shared style and transform to child primitives.
+
+## Path Commands
+
+Path blocks support an SVG-like command subset:
+
+```ruby
+path :blob, detail: 48 do
+  move_to 0, 120
+  line_to 120, 0
+  quad_to 80, -100, 0, -120
+  cubic_to -80, -100, -120, 80, 0, 120
+  close
+end
+```
+
+Commands are serialized as `M`, `L`, `Q`, `C`, `H`, `V`, `A`, and `Z`. The
+Canvas2D renderer draws `arc_to` as an SVG-style elliptical arc, and the line
+fallback/snapshot renderer flattens curves and arcs to line segments.
+`detail` controls the default curve/arc subdivision count. When `tolerance` is
+provided, quadratic and cubic curves use adaptive flattening instead. `max_segments`
+caps the number of flattened line segments per path; the DSL raises when the
+estimated flattened path would exceed that budget.
+
+## Style And Transform
+
+Inside a shape block, these methods target the shape rather than the layer:
+
+```ruby
+fill "#f472b6"
+stroke 2
+stroke width: 3, color: "#ffffff"
+blend :add
+opacity 0.75
+
+translate x: 100, y: 40
+translate 100, 40
+rotate 30
+scale 1.2
+scale x: 1.4, y: 0.8
+origin x: 0, y: 0
+```
+
+The transform order is origin adjustment, scale, rotate, then translate.
+
+## Groups
+
+Groups are flattened into child primitives during DSL evaluation. Child shapes
+inherit style values they do not set themselves, and group opacity is multiplied
+with child opacity.
+
+```ruby
+group :spinner do
+  translate x: 0, y: 80
+  rotate 15
+  scale 1.2
+  opacity 0.75
+  stroke width: 2, color: "#38bdf8"
+
+  12.times do |index|
+    rect width: 12, height: 80 do
+      translate x: 0, y: 160
+      rotate index * 30
+    end
+  end
+end
+```
+
+## Mapping
+
+Mappings declared inside a shape block are scoped to that shape:
+
+```ruby
+circle :ring, radius: 120 do
+  map bass, to: :radius, range: 80..240
+  map beat_pulse, to: :scale, range: 1.0..1.4
+  map high, to: :opacity, range: 0.2..1.0
+end
+```
+
+Transform aliases:
+
+- `:translate_x` -> `transform.translate.x`
+- `:translate_y` -> `transform.translate.y`
+- `:rotate` and `:rotation` -> `transform.rotate`
+- `:scale` -> `transform.scale`
+- `:scale_x` -> `transform.scale.x`
+- `:scale_y` -> `transform.scale.y`
+- `:origin_x` -> `transform.origin.x`
+- `:origin_y` -> `transform.origin.y`
+
+You can also map to a named shape from the layer scope:
+
+```ruby
+rect :panel, width: 360, height: 160
+map bass, to: shape(:panel).rotate, range: -12..12
+```
+
+Mappings inside a static `custom_shape` block are applied to each primitive
+generated by that custom shape:
+
+```ruby
+custom_shape :badge, radius: 120 do
+  fill "#22d3ee"
+  map beat_pulse, to: :scale, range: 0.8..1.2
+end
+```
+
+## Custom Shapes
+
+Custom shapes are registered in Ruby and expanded into regular shape
+primitives before the browser receives the scene.
+
+```ruby
+class DiamondShape
+  include Vizcore::Shape
+
+  param :radius, default: 100, min: 10, max: 400
+
+  def draw(ctx)
+    radius = ctx.param(:radius)
+
+    ctx.polygon points: [
+      [0, radius],
+      [radius, 0],
+      [0, -radius],
+      [-radius, 0]
+    ]
+  end
+end
+
+Vizcore.register_shape :diamond, DiamondShape
+```
+
+Use the registered shape from a layer:
+
+```ruby
+layer :generated_logo do
+  custom_shape :diamond, radius: 140 do
+    rotate 45
+    stroke width: 2, color: "#ffffff"
+  end
+end
+```
+
+Block registration is supported for small generators:
+
+```ruby
+Vizcore.register_shape :spark do |ctx|
+  ctx.star points: 5, radius: ctx.param(:radius, 80), inner_radius: 32
+end
+```
+
+`draw(ctx)` may return a primitive hash, an array of primitive hashes, or build
+primitives with `ctx.draw`, `ctx.circle`, `ctx.rect`, `ctx.path`, and the other
+shape methods. Values declared with `param` are validated against their
+`min`/`max` metadata before `draw(ctx)` runs, and dynamic custom shape
+descriptors include the same schema for editor tooling.
+
+By default, custom shapes are expanded when the DSL is evaluated. Use
+`dynamic: true` when the generator needs mapped params, `ctx.time`, `ctx.frame`,
+or `ctx.audio` at runtime:
+
+```ruby
+custom_shape :orbit, count: 32, radius: 260, dynamic: true do
+  fill "#22d3ee"
+  map bass, to: :radius, range: 120..280
+  map beat_pulse, to: :scale, range: 0.8..1.2
+end
+```
+
+Inside a dynamic custom shape block, mappings to custom params such as `:radius`
+are applied before `draw(ctx)` runs. Transform aliases such as `:scale` and
+`:rotate` are applied to the generated primitives after expansion.
+
+Use `static: true` for generators that are independent of runtime context. Static
+custom shapes with identical renderer, params, layer context, palette, and
+resolution reuse a cached expansion, while each call still receives its own copy
+of the generated primitives.
+
+## Coordinates
+
+New shape schema layers use center-origin logical coordinates by default:
+
+- `x` increases to the right.
+- `y` increases upward.
+- `x: 0, y: 0` is the center of the canvas.
+
+Legacy `circle` and `line` layers without `shape_schema_version: 2` keep the old
+coordinate heuristic for compatibility with existing examples.
+
+Set `units :ndc` on the layer to use normalized device coordinates directly.
+
+## Validation
+
+The DSL raises early for malformed primitives:
+
+- duplicate shape IDs within a layer
+- negative `radius`, `inner_radius`, `width`, `height`, or `stroke_width`
+- `polygon` with fewer than 3 points
+- `polyline` with fewer than 2 points
+- `path` without commands
+- `path` whose estimated flattened segment count exceeds `max_segments`
+- unknown `custom_shape`
+- custom shapes that return unsupported primitive kinds
+
+`vizcore validate` also emits warnings for shape payloads that are renderable but
+likely surprising: unsupported primitive kinds in raw `params[:shapes]`, fills
+that line fallback will ignore, opacity values outside `0..1`, and zero or very
+large scale values that will collapse or clamp.
+
+## Renderer Notes
+
+The browser renderer uses a Canvas2D shape backend composited through the
+existing WebGL layer pipeline. It supports fill, stroke color/width, opacity,
+dash, line caps/joins, transforms, and logical/ndc coordinates for the shape
+schema.
+
+If Canvas2D is unavailable, the browser falls back to the existing line renderer.
+That fallback ignores fill and only approximates stroke geometry. The software
+snapshot renderer also uses line flattening.
+
+The browser HUD includes local shape editor controls for resolved shape layers:
+primitive kind, translate, rotate, scale, opacity, fill, stroke color, and stroke
+width can be adjusted in the running view without mutating the source DSL file.
+Dynamic custom shape params with `param` metadata are also exposed as HUD
+controls; changing one sends a runtime override to the server so the Ruby custom
+shape is re-expanded on the next frame. The HUD also lists valid mapping target
+paths for layer params, primitive params/transforms, and custom shape params.

data/examples/README.md

@@ -0,0 +1,59 @@
+# Vizcore Examples
+
+Run the browser gallery for launch commands and scene metadata:
+
+```bash
+vizcore gallery
+```
+
+Most examples also work directly:
+
+```bash
+vizcore start examples/basic.rb
+vizcore start examples/audio_inspector.rb --audio-source mic
+vizcore start examples/audio_inspector.rb --audio-source mic --noise-gate 0.001
+vizcore start examples/vj_techno_warehouse.rb --audio-source file --audio-file examples/assets/complex_demo_loop.wav
+```
+
+## Core Examples
+
+| File | Description |
+|---|---|
+| `basic.rb` | Single wireframe cube layer |
+| `intro_drop.rb` | Beat-triggered scene transition |
+| `file_audio_demo.rb` | File audio source walkthrough |
+| `complex_audio_showcase.rb` | Dense multi-layer showcase |
+| `rhythm_geometry.rb` | Drum-reactive geometric pattern |
+| `ruby_crystal_show.rb` | Ruby-themed crystal visual |
+| `parser_visualizer.rb` | Parser-themed token and AST sketch |
+| `live_coding_minimal.rb` | Tiny live-coding scene |
+| `club_intro_drop.rb` | Intro, build, drop flow |
+| `shader_playground.rb` | Focused shader params example |
+| `audio_inspector.rb` | Audio feature visualization |
+| `readme_demo.rb` | Minimal beat pulse to ring radius demo |
+| `midi_scene_switch.rb` | MIDI scene switching |
+| `midi_controller_show.rb` | MIDI pads and CC controls |
+| `kansai_rubykaigi_visual.rb` | Event showcase visual |
+| `custom_shader.rb` | Custom GLSL shader |
+| `unyo_liquid.rb` | Liquid wobble and FFT blob |
+
+## VJ Set Examples
+
+Ready-to-run scenes grouped by genre / mood. All scenes accept live mic input
+or any audio file. `B` toggles Blackout, `F` toggles Freeze, and scenes that
+declare tap tempo use Space.
+
+| File | Genre / Mood | BPM | Scenes | Notes |
+|---|---|---|---|---|
+| `vj_techno_warehouse.rb` | Techno / Warehouse | 128-140 | 4 | wireframe + particles |
+| `vj_dnb_jungle.rb` | Drum & Bass / Jungle | 170-180 | 3 | kick/snare/hihat split |
+| `vj_ambient_chill_room.rb` | Ambient / Chill | 60-90 | 2 | beatless, drone-friendly |
+| `vj_hiphop_cipher.rb` | HipHop / Cipher | 85-100 | 3 | text-forward |
+| `vj_jpop_idol_live.rb` | J-POP / Idol | 130-180 | 4 | color fields + tap tempo |
+| `vj_synthwave_retro.rb` | Synthwave / Retro | 100-120 | 3 | circle and line primitives |
+| `vj_glitch_industrial.rb` | Glitch / Industrial | n/a | 3 | feedback + difference blend |
+| `vj_festival_mainstage.rb` | EDM / Mainstage | 124-132 | 5 | uses `extends:` and `group` |
+
+Use `examples/vj_festival_mainstage.yml` as a manifest pattern for file-audio
+rehearsal. Replace `audio_file` with your set recording or switch to
+`audio_source: mic` for live input.

data/examples/assets/README.md

@@ -0,0 +1,19 @@
+# Example Assets
+
+`complex_demo_loop.wav` is bundled for repeatable file-audio testing.
+
+For logos or show-specific art, place your own files in this directory and
+reference them from a scene:
+
+```ruby
+layer :logo do
+  type :svg
+  file "assets/your_logo.svg"
+  fit :contain
+  map beat_pulse, to: :scale, range: 0.9..1.08
+end
+```
+
+No copyrighted venue logos, artist marks, photos, or fonts are bundled with
+Vizcore examples. Keep those assets local to your project unless you have the
+right to redistribute them.

data/examples/audio_inspector.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# Visualizes the same audio features shown in the HUD inspector.
+Vizcore.define do
+  audio_normalize mode: :adaptive, window: 2.0, target: 0.85, floor: 0.001
+
+  scene :audio_inspector do
+    layer :bars do
+      shader :audio_bars
+      param :bar_count, default: 32.0, range: 12.0..64.0, step: 1.0
+      param :floor_glow, default: 0.18, range: 0.0..1.0, step: 0.02
+      blend :screen
+      map amplitude, to: :floor_glow, gain: 1.6, range: 0.08..0.5
+    end
+
+    layer :peak_blob do
+      type :radial_blob
+      radius 0.28
+      wobble 0.35
+      blend :add
+      map amplitude, to: :radius, range: 0.22..0.58, curve: :sqrt
+      map fft_spectrum => :spectrum
+      map treble, to: :wobble, range: 0.2..1.2
+    end
+
+    layer :label do
+      type :text
+      content "AUDIO"
+      font_size 76
+      glow_strength 0.2
+      map beat_pulse, to: :glow_strength, range: 0.12..0.8
+    end
+  end
+end

data/examples/club_intro_drop.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+# File-audio friendly intro -> build -> drop flow.
+Vizcore.define do
+  scene :intro do
+    layer :grid do
+      shader :neon_grid
+      opacity 0.75
+      map mid, to: :effect_intensity, range: 0.08..0.28
+    end
+
+    layer :title do
+      type :text
+      content "INTRO"
+      font_size 84
+      map beat_pulse, to: :glow_strength, range: 0.12..0.65
+    end
+  end
+
+  scene :build do
+    layer :rings do
+      shader :spectrum_rings
+      blend :screen
+      map bass, to: :effect_intensity, gain: 1.4, range: 0.16..0.5
+    end
+
+    layer :particles do
+      type :particle_field
+      count 2200
+      blend :add
+      map amplitude, to: :speed, range: 0.4..3.2
+      map treble, to: :sparkle, range: 0.0..0.9
+    end
+  end
+
+  scene :drop do
+    layer :tunnel do
+      shader :bass_tunnel
+      blend :screen
+    end
+
+    layer :flash do
+      shader :glitch_flash
+      blend :add
+      map beat_pulse, to: :intensity, range: 0.2..1.0, attack: 1.0, release: 0.08
+    end
+
+    layer :drop_text do
+      type :text
+      content "DROP"
+      font_size 122
+      blend :screen
+      map beat_pulse, to: :glow_strength, range: 0.3..1.0
+    end
+  end
+
+  transition from: :intro, to: :build do
+    trigger { beat_count >= 32 || frame_count >= 240 }
+    effect :crossfade, duration: 1.0
+  end
+
+  transition from: :build, to: :drop do
+    trigger { beat_count >= 64 || frame_count >= 480 }
+    effect :flash, duration: 0.35
+  end
+
+  key "i" do
+    switch_scene :intro
+  end
+
+  key "u" do
+    switch_scene :build
+  end
+
+  key "d" do
+    switch_scene :drop
+  end
+end

data/examples/kansai_rubykaigi_visual.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# Kansai RubyKaigi visual: ruby crystal, water ripple, geometric pattern, and title.
+Vizcore.define do
+  scene :kansai_rubykaigi do
+    layer :lake_ripple do
+      shader :liquid_wobble
+      wobble 0.18
+      warp 0.32
+      distortion 0.16
+      opacity 0.86
+      blend :screen
+      effect :feedback
+      effect_intensity 0.08
+
+      map bass, to: :wobble, gain: 0.9, range: 0.12..0.58, curve: :sqrt
+      map mid, to: :warp, gain: 1.2, range: 0.22..1.45
+      map high, to: :effect_intensity, range: 0.04..0.22
+    end
+
+    layer :kyoto_pattern do
+      shader :kaleidoscope
+      opacity 0.34
+      blend :add
+      vj_effect :mirror
+      effect_intensity 0.18
+
+      map mid, to: :effect_intensity, gain: 1.2, range: 0.08..0.42
+    end
+
+    layer :ruby_glow do
+      shader :ruby_crystal
+      facets 8.0
+      refraction 0.52
+      opacity 0.82
+      blend :screen
+      effect :bloom
+
+      map bass, to: :refraction, gain: 0.9, range: 0.34..0.86, curve: :sqrt
+      map beat_pulse, to: :effect_intensity, range: 0.12..0.72
+    end
+
+    layer :spark_line do
+      type :particle_field
+      count 1800
+      force_field :vortex
+      turbulence 0.18
+      blend :add
+
+      map amplitude, to: :speed, gain: 2.2, range: 0.25..4.2, curve: :sqrt
+      map bass, to: :size, gain: 2.0, range: 1.4..5.4
+      map hihat, to: :sparkle, gain: 2.4, range: 0.0..1.0
+    end
+
+    layer :event_title do
+      type :text
+      content "KANSAI RUBYKAIGI"
+      font "IBM Plex Sans"
+      font_size 66
+      align :center
+      color "#fff4e6"
+      stroke width: 2, color: "#120617"
+      shadow color: "#ff335f", blur: 20
+      glow_strength 0.28
+      blend :screen
+
+      map beat_pulse, to: :glow_strength, range: 0.2..0.92
+    end
+  end
+end

data/examples/live_coding_minimal.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Short scene intended for live-coding demos.
+Vizcore.define do
+  scene :main do
+    layer :pulse do
+      type :radial_blob
+      radius 0.34
+      wobble 0.2
+      map amplitude, to: :radius, range: 0.22..0.7, curve: :sqrt
+      map fft_spectrum => :spectrum
+    end
+
+    layer :beat_label do
+      type :text
+      content "VIZCORE"
+      font_size 86
+      glow_strength 0.2
+      map beat_pulse, to: :glow_strength, range: 0.12..0.85
+    end
+  end
+end

data/examples/midi_controller_show.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+# MIDI controller showcase: pads switch scenes, knobs control global shader uniforms.
+Vizcore.define do
+  set :global_intensity, 0.65
+  set :global_color, 0.15
+
+  midi :controller, device: :default
+
+  scene :midi_warmup do
+    layer :ribbon do
+      shader :waveform_ribbon
+      blend :screen
+      effect :bloom
+      map mid, to: :effect_intensity, range: 0.08..0.24
+    end
+
+    layer :title do
+      type :text
+      content "MIDI CONTROL"
+      font_size 72
+      color "#e8fbff"
+      glow_strength 0.16
+      blend :screen
+      map beat_pulse, to: :glow_strength, range: 0.12..0.65
+    end
+  end
+
+  scene :midi_drop do
+    layer :stars do
+      shader :starfield
+      blend :screen
+      effect :glitch
+      map high, to: :effect_intensity, range: 0.1..0.65
+    end
+
+    layer :drop_text do
+      type :text
+      content "DROP"
+      font_size 118
+      color "#fff1d6"
+      glow_strength 0.25
+      blend :add
+      map beat_pulse, to: :glow_strength, range: 0.25..1.0
+    end
+  end
+
+  scene :midi_crystal do
+    layer :crystal do
+      shader :ruby_crystal
+      facets 7.0
+      refraction 0.44
+      blend :screen
+      map bass, to: :refraction, gain: 0.9, range: 0.32..0.82
+      map mid, to: :facets, gain: 1.8, range: 5.0..10.0
+    end
+  end
+
+  midi_map note: 36 do
+    switch_scene :midi_warmup
+  end
+
+  midi_map note: 37 do
+    switch_scene :midi_drop
+  end
+
+  midi_map note: 38 do
+    switch_scene :midi_crystal
+  end
+
+  midi_map cc: 1 do |value|
+    set :global_intensity, value / 127.0
+  end
+
+  midi_map cc: 2 do |value|
+    set :global_color, value / 127.0
+  end
+end

data/examples/midi_scene_switch.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
 Vizcore.define do
+  set :global_intensity, 0.65
+
   midi :controller, device: :default
 
   scene :warmup do
     layer :grid do
-      shader :neon_grid
+      shader :waveform_ribbon
       map frequency_band(:mid) => :intensity
     end
   end

data/examples/parser_visualizer.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+# Parser-themed visual sketch: token flow, AST energy, and reduce flashes.
+Vizcore.define do
+  scene :parser_visualizer do
+    layer :token_stream do
+      shader :waveform_ribbon
+      blend :screen
+      effect :crt
+      effect_intensity 0.18
+      map amplitude, to: :effect_intensity, range: 0.08..0.32
+    end
+
+    layer :ast_nodes do
+      type :particle_field
+      count 2200
+      force_field :vortex
+      turbulence 0.28
+      blend :add
+      map bass, to: :size, gain: 3.0, range: 1.8..6.5, curve: :sqrt
+      map mid, to: :speed, gain: 2.0, range: 0.4..4.2
+      map hihat, to: :sparkle, gain: 2.2, range: 0.0..1.0
+    end
+
+    layer :reduce_flash do
+      shader :ruby_crystal
+      facets 7.0
+      refraction 0.42
+      blend :add
+      effect :bloom
+      map kick, to: :effect_intensity, gain: 2.0, range: 0.05..0.55
+      map beat_pulse, to: :refraction, range: 0.32..0.86
+    end
+
+    layer :parser_label do
+      type :text
+      content "SHIFT  ->  REDUCE  ->  ACCEPT"
+      font "IBM Plex Mono"
+      font_size 58
+      align :center
+      fill "#d9ffe8"
+      stroke width: 2, color: "#06111f"
+      glow_strength 0.26
+      blend :screen
+      map beat_pulse, to: :glow_strength, range: 0.18..0.9
+    end
+  end
+end