vizcore 0.1.0 → 1.1.0

data/lib/vizcore/dsl/layer_group_builder.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require_relative "layer_builder"
+
+module Vizcore
+  module DSL
+    # Collects related layers and applies shared layer parameters.
+    class LayerGroupBuilder
+      # @param name [Symbol, String] group identifier stored on nested layer params
+      # @param styles [Hash] reusable layer parameter styles
+      # @param defaults [Hash] scene defaults already applied before group params
+      def initialize(name:, styles: {}, defaults: {})
+        @name = name.to_sym
+        @styles = styles
+        @params = deep_dup(defaults)
+        @layers = []
+      end
+
+      # Evaluate a group block.
+      #
+      # @yield Layer group DSL methods
+      # @return [Vizcore::DSL::LayerGroupBuilder]
+      def evaluate(&block)
+        instance_eval(&block) if block
+        self
+      end
+
+      # Define one layer in this group.
+      #
+      # @param name [Symbol, String] layer identifier
+      # @yield Layer definition block
+      # @return [void]
+      def layer(name, &block)
+        builder = LayerBuilder.new(name: name, styles: @styles, defaults: layer_defaults)
+        builder.evaluate(&block)
+        @layers << builder.to_h
+      end
+
+      # @param value [Symbol, String] layer compositing mode shared by nested layers
+      # @return [Symbol]
+      def blend(value)
+        @params[:blend] = value.to_sym
+      end
+
+      # Store an ordered color palette shared by nested layers.
+      #
+      # @param colors [Array<String, Array<String>>] color values such as "#00ffff"
+      # @raise [ArgumentError] when no non-blank colors are supplied
+      # @return [Array<String>]
+      def palette(*colors)
+        @params[:palette] = normalize_palette(colors)
+      end
+
+      # Merge a named style into this group's shared params.
+      #
+      # @param name [Symbol, String] style identifier
+      # @raise [ArgumentError] when the style is unknown
+      # @return [Hash] applied style params
+      def use_style(name)
+        style_name = name.to_sym
+        style_params = @styles.fetch(style_name) { raise ArgumentError, "unknown style: #{style_name}" }
+        @params.merge!(deep_dup(style_params))
+      end
+
+      # @return [Array<Hash>] serialized nested layers
+      def to_a
+        @layers.map { |layer| deep_dup(layer) }
+      end
+
+      # Stores dynamic one-argument setters into shared group params.
+      # @api private
+      def method_missing(method_name, *args, &block)
+        if block.nil? && args.length == 1
+          @params[method_name.to_sym] = args.first
+          return args.first
+        end
+
+        super
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        @params.key?(method_name.to_sym) || super
+      end
+
+      private
+
+      def layer_defaults
+        deep_dup(@params).merge(group: @name)
+      end
+
+      def normalize_palette(colors)
+        values = colors.flatten.map { |color| color.to_s.strip }.reject(&:empty?)
+        raise ArgumentError, "group #{@name} palette requires at least one color" if values.empty?
+
+        values
+      end
+
+      def deep_dup(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, entry), output|
+            output[key] = deep_dup(entry)
+          end
+        when Array
+          value.map { |entry| deep_dup(entry) }
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/vizcore/dsl/mapping_resolver.rb

@@ -1,23 +1,31 @@
 # frozen_string_literal: true
 
+require_relative "../shape"
+
 module Vizcore
   module DSL
     # Resolves `map` definitions into concrete per-layer parameter values.
     class MappingResolver
+      def initialize
+        @mapping_state = {}
+      end
+
       # @param scene_layers [Array<Hash>]
       # @param audio [Hash]
       # @return [Array<Hash>] normalized layer payloads with resolved params
-      def resolve_layers(scene_layers:, audio:)
+      def resolve_layers(scene_layers:, audio:, time: 0.0, frame: 0, resolution: [1280, 720], globals: {}, custom_shape_overrides: {})
         normalize_scene_layers(scene_layers).map do |layer|
-          resolve_layer(layer, audio)
+          resolve_layer(layer, audio, time: time, frame: frame, resolution: resolution, globals: globals, custom_shape_overrides: custom_shape_overrides)
         end
       end
 
       private
 
-      def resolve_layer(layer, audio)
-        params = (layer[:params] || {}).dup
-        params.merge!(resolve_mappings(layer[:mappings], audio))
+      def resolve_layer(layer, audio, time:, frame:, resolution:, globals:, custom_shape_overrides:)
+        params = deep_dup(layer[:params] || {})
+        apply_custom_shape_overrides!(params, layer_name: layer[:name], custom_shape_overrides: custom_shape_overrides)
+        merge_resolved_mappings!(params, resolve_mappings(layer[:mappings], audio, layer_name: layer[:name]))
+        expand_dynamic_custom_shapes!(params, layer: layer, audio: audio, time: time, frame: frame, resolution: resolution, globals: globals)
 
         output = {
           name: layer.fetch(:name).to_s,
@@ -27,20 +35,201 @@ module Vizcore
         output[:shader] = layer[:shader].to_s if layer[:shader]
         output[:glsl] = layer[:glsl].to_s if layer[:glsl]
         output[:glsl_source] = layer[:glsl_source].to_s if layer[:glsl_source]
+        output[:param_schema] = Array(layer[:param_schema]).map(&:dup) if layer[:param_schema]
         output
       end
 
-      def resolve_mappings(mappings, audio)
+      def resolve_mappings(mappings, audio, layer_name:)
         Array(mappings).each_with_object({}) do |mapping, resolved|
           source = mapping[:source]
           target = mapping[:target]
           next unless source && target
 
           value = resolve_source_value(source, audio)
-          resolved[target.to_sym] = value unless value.nil?
+          value = apply_transform(value, mapping[:transform], state_key: [layer_name, target, source])
+          resolved[target.to_s] = value unless value.nil?
+        end
+      end
+
+      def merge_resolved_mappings!(params, mappings)
+        mappings.each do |target, value|
+          if target.include?(".")
+            assign_nested_param(params, target.split("."), value)
+          else
+            params[target.to_sym] = value
+          end
+        end
+      end
+
+      def expand_dynamic_custom_shapes!(params, layer:, audio:, time:, frame:, resolution:, globals:)
+        descriptors = Array(params.delete(:custom_shapes) || params.delete("custom_shapes"))
+        return if descriptors.empty?
+
+        params[:shapes] = Array(params[:shapes])
+        controls = []
+        descriptors.each_with_index do |descriptor, index|
+          start_index = params[:shapes].length
+          expanded = expand_dynamic_custom_shape(descriptor, layer: layer, palette: params[:palette], audio: audio, time: time, frame: frame, resolution: resolution, globals: globals)
+          params[:shapes].concat(expanded)
+          controls << custom_shape_control_descriptor(descriptor, index: index, start_index: start_index, count: expanded.length)
+        end
+        params[:custom_shape_controls] = controls unless controls.empty?
+      end
+
+      def expand_dynamic_custom_shape(descriptor, layer:, palette:, audio:, time:, frame:, resolution:, globals:)
+        values = Hash(descriptor)
+        renderer = values.fetch(:renderer)
+        shape_name = values[:name] || renderer
+        primitives = Vizcore::Shape.expand_custom_shape(
+          renderer,
+          params: Hash(values[:params] || {}),
+          shape_id: values[:shape_id],
+          layer_name: layer[:name],
+          palette: Array(palette),
+          audio: audio,
+          time: time,
+          frame: frame,
+          resolution: resolution,
+          globals: globals,
+          shape_name: shape_name
+        )
+        primitives.each { |primitive| apply_custom_shape_attributes!(primitive, values) }
+      end
+
+      def custom_shape_control_descriptor(descriptor, index:, start_index:, count:)
+        values = Hash(descriptor)
+        {
+          index: index,
+          name: (values[:name] || values["name"] || "custom_shape").to_s,
+          params: deep_dup(Hash(values[:params] || values["params"] || {})),
+          param_schema: Array(values[:param_schema] || values["param_schema"]).map { |entry| deep_dup(entry) },
+          shape_indices: (start_index...(start_index + count)).to_a
+        }
+      end
+
+      def apply_custom_shape_overrides!(params, layer_name:, custom_shape_overrides:)
+        layer_overrides = custom_shape_layer_overrides(custom_shape_overrides, layer_name)
+        return if layer_overrides.empty?
+
+        descriptors = Array(params[:custom_shapes] || params["custom_shapes"])
+        layer_overrides.each do |index, values|
+          descriptor = descriptors[Integer(index)]
+          next unless descriptor && values.is_a?(Hash)
+
+          descriptor[:params] ||= {}
+          values.each do |param_name, value|
+            key = param_name.to_sym
+            descriptor[:params][key] = value
+          end
+        rescue ArgumentError, TypeError
+          next
         end
       end
 
+      def custom_shape_layer_overrides(overrides, layer_name)
+        values = Hash(overrides)
+        name = layer_name.to_s
+        Hash(values[name] || values[layer_name.to_sym] || {})
+      rescue TypeError
+        {}
+      end
+
+      def apply_custom_shape_attributes!(primitive, descriptor)
+        style = Hash(descriptor[:style] || {})
+        style.each do |key, value|
+          symbol_key = key.to_sym
+          if symbol_key == :opacity && primitive.key?(:opacity)
+            primitive[:opacity] = numeric(style[:opacity] || style["opacity"], :opacity) * numeric(primitive[:opacity], :opacity)
+          else
+            primitive[symbol_key] = deep_dup(value) unless primitive.key?(symbol_key)
+          end
+        end
+
+        transform = Hash(descriptor[:transform] || {})
+        primitive[:transform] = compose_shape_transform(transform, primitive[:transform]) unless transform.empty?
+        primitive
+      end
+
+      def assign_nested_param(container, path, value)
+        key = path.shift
+        if path.empty?
+          assign_nested_value(container, key, value)
+          return
+        end
+
+        next_container = nested_value(container, key)
+        next_container = create_nested_container(container, key, path.first) if next_container.nil?
+        return unless next_container
+
+        assign_nested_param(next_container, path, value)
+      end
+
+      def nested_value(container, key)
+        return container[key.to_i] if container.is_a?(Array) && integer_key?(key)
+        return container[key.to_sym] if container.is_a?(Hash)
+
+        nil
+      end
+
+      def create_nested_container(container, key, next_key)
+        return unless container.is_a?(Hash)
+
+        value = integer_key?(next_key) ? [] : {}
+        container[key.to_sym] = value
+      end
+
+      def assign_nested_value(container, key, value)
+        if container.is_a?(Array) && integer_key?(key)
+          container[key.to_i] = value
+        elsif container.is_a?(Hash)
+          container[key.to_sym] = value
+        end
+      end
+
+      def integer_key?(value)
+        value.match?(/\A\d+\z/)
+      end
+
+      def compose_shape_transform(parent, child)
+        return deep_dup(child || {}) unless parent
+
+        child ||= {}
+        output = deep_dup(parent)
+        output[:translate] = add_shape_xy(parent[:translate], child[:translate]) if child.key?(:translate)
+        output[:origin] = child[:origin] if child.key?(:origin)
+        output[:rotate] = numeric(parent[:rotate] || 0, :rotate) + numeric(child[:rotate] || 0, :rotate) if child.key?(:rotate)
+        output[:scale] = multiply_shape_scale(parent[:scale], child[:scale]) if child.key?(:scale)
+        output
+      end
+
+      def add_shape_xy(parent, child)
+        parent ||= {}
+        child ||= {}
+        {
+          x: numeric(parent[:x] || parent["x"] || 0, :"translate.x") + numeric(child[:x] || child["x"] || 0, :"translate.x"),
+          y: numeric(parent[:y] || parent["y"] || 0, :"translate.y") + numeric(child[:y] || child["y"] || 0, :"translate.y")
+        }
+      end
+
+      def multiply_shape_scale(parent, child)
+        parent = shape_scale_pair(parent)
+        child = shape_scale_pair(child)
+        { x: parent[:x] * child[:x], y: parent[:y] * child[:y] }
+      end
+
+      def shape_scale_pair(value)
+        return { x: numeric(value[:x] || value["x"] || 1, :"scale.x"), y: numeric(value[:y] || value["y"] || 1, :"scale.y") } if value.is_a?(Hash)
+
+        scale = numeric(value || 1, :scale)
+        { x: scale, y: scale }
+      end
+
+      def numeric(value, name)
+        Float(value)
+      rescue ArgumentError, TypeError
+        raise ArgumentError, "param #{name} must be numeric"
+      end
+
       def resolve_source_value(source, audio)
         case source[:kind]&.to_sym
         when :amplitude
@@ -49,8 +238,16 @@ module Vizcore
           audio.dig(:bands, source[:band]&.to_sym)
         when :fft_spectrum
           audio[:fft]
+        when :onset
+          resolve_onset(source, audio)
+        when :kick, :snare, :hihat
+          audio.dig(:drums, source[:kind].to_sym)
         when :beat
           audio[:beat]
+        when :beat_confidence
+          audio[:beat_confidence]
+        when :beat_pulse
+          audio[:beat_pulse]
         when :beat_count
           audio[:beat_count]
         when :bpm
@@ -60,10 +257,96 @@ module Vizcore
         end
       end
 
+      def resolve_onset(source, audio)
+        band = source[:band]&.to_sym
+        return audio[:onset] unless band
+
+        audio.dig(:onsets, band)
+      end
+
+      def apply_transform(value, transform, state_key:)
+        return value if transform.nil? || transform.empty?
+        return transform_array(value, transform) if value.is_a?(Array)
+        return nil if value.is_a?(Hash) || value.nil?
+
+        transformed = transform_scalar(value, transform)
+        return nil if transformed.nil?
+
+        apply_smoothing(transformed, transform, state_key)
+      end
+
+      def transform_array(value, transform)
+        value.map do |entry|
+          transform_scalar(entry, transform, fallback: 0.0) || 0.0
+        end
+      end
+
+      def transform_scalar(value, transform, fallback: nil)
+        numeric = numeric_value(value, fallback: fallback)
+        return nil if numeric.nil?
+
+        numeric = 0.0 if transform.key?(:deadzone) && numeric.abs < Float(transform[:deadzone])
+        numeric *= Float(transform[:gain]) if transform.key?(:gain)
+        numeric = apply_curve(numeric, transform[:curve]) if transform[:curve]
+        numeric = [numeric, Float(transform[:min])].max if transform.key?(:min)
+        numeric = [numeric, Float(transform[:max])].min if transform.key?(:max)
+        numeric
+      end
+
+      def numeric_value(value, fallback:)
+        return value ? 1.0 : 0.0 if value == true || value == false
+
+        Float(value)
+      rescue ArgumentError, TypeError
+        fallback
+      end
+
+      def apply_curve(value, curve)
+        case curve.to_sym
+        when :linear
+          value
+        when :sqrt
+          Math.sqrt([value, 0.0].max)
+        when :square
+          value * value
+        when :ease_out
+          clamped = [[value, 0.0].max, 1.0].min
+          1.0 - ((1.0 - clamped) * (1.0 - clamped))
+        end
+      end
+
+      def apply_smoothing(value, transform, state_key)
+        return value unless transform.key?(:attack) || transform.key?(:release)
+
+        previous = @mapping_state[state_key]
+        if previous.nil?
+          @mapping_state[state_key] = value
+          return value
+        end
+
+        alpha = value >= previous ? transform.fetch(:attack, 1.0) : transform.fetch(:release, 1.0)
+        smoothed = previous + (value - previous) * alpha
+        @mapping_state[state_key] = smoothed
+        smoothed
+      end
+
       def normalize_scene_layers(scene_layers)
         Array(scene_layers).map { |layer| deep_symbolize(layer) }
       end
 
+      def deep_dup(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, entry), output|
+            output[key] = deep_dup(entry)
+          end
+        when Array
+          value.map { |entry| deep_dup(entry) }
+        else
+          value
+        end
+      end
+
       def deep_symbolize(value)
         case value
         when Hash

data/lib/vizcore/dsl/mapping_transform_builder.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Vizcore
+  module DSL
+    # Collects block-style mapping transform options.
+    class MappingTransformBuilder
+      # @param initial [Hash]
+      def initialize(initial = {})
+        @values = initial.each_with_object({}) do |(key, value), output|
+          output[key.to_sym] = value
+        end
+      end
+
+      # @return [Vizcore::DSL::MappingTransformBuilder]
+      def evaluate(&block)
+        instance_eval(&block) if block
+        self
+      end
+
+      # @param value [Numeric]
+      # @return [Numeric]
+      def gain(value)
+        @values[:gain] = value
+      end
+
+      # @param value [Range, Array]
+      # @return [Range, Array]
+      def range(value)
+        @values[:range] = value
+      end
+
+      # @param value [Numeric]
+      # @return [Numeric]
+      def min(value)
+        @values[:min] = value
+      end
+
+      # @param value [Numeric]
+      # @return [Numeric]
+      def max(value)
+        @values[:max] = value
+      end
+
+      # @param value [Symbol, String]
+      # @return [Symbol, String]
+      def curve(value)
+        @values[:curve] = value
+      end
+
+      # @param value [Numeric]
+      # @return [Numeric]
+      def deadzone(value)
+        @values[:deadzone] = value
+      end
+
+      # @param attack [Numeric, nil]
+      # @param release [Numeric, nil]
+      # @return [Hash]
+      def smooth(attack: nil, release: nil)
+        @values[:attack] = attack unless attack.nil?
+        @values[:release] = release unless release.nil?
+        @values
+      end
+
+      # @return [Hash]
+      def to_h
+        @values.dup
+      end
+    end
+  end
+end

data/lib/vizcore/dsl/reaction_builder.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Vizcore
+  module DSL
+    # Collects high-level `react_to` DSL entries and converts them to mappings.
+    class ReactionBuilder
+      # @param mapping_factory [#call] builds one normalized mapping hash
+      def initialize(mapping_factory:)
+        @mapping_factory = mapping_factory
+        @mappings = []
+      end
+
+      # Evaluate a `react_to` block.
+      #
+      # @yield Reaction DSL methods
+      # @raise [ArgumentError] when the block does not define any reaction
+      # @return [Array<Hash>] normalized mapping payloads
+      def evaluate(&block)
+        instance_eval(&block) if block
+        raise ArgumentError, "react_to requires at least one change or trigger" if @mappings.empty?
+
+        @mappings.map(&:dup)
+      end
+
+      # Continuously map the reaction source to a target parameter.
+      #
+      # @param target [Symbol, String] layer parameter name
+      # @param options [Hash] mapping transform options
+      # @return [void]
+      def change(target, **options)
+        @mappings << @mapping_factory.call(target, options)
+      end
+
+      # Map the reaction source to an event-like target parameter.
+      #
+      # @param target [Symbol, String] layer parameter name
+      # @param options [Hash] mapping transform options
+      # @return [void]
+      def trigger(target, **options)
+        change(target, **options)
+      end
+    end
+  end
+end

data/lib/vizcore/dsl/scene_builder.rb

@@ -1,15 +1,23 @@
 # frozen_string_literal: true
 
 require_relative "layer_builder"
+require_relative "layer_group_builder"
 
 module Vizcore
   module DSL
     # Collects layer definitions inside a single scene block.
     class SceneBuilder
       # @param name [Symbol, String] scene identifier
-      def initialize(name:)
+      # @param styles [Hash] reusable layer parameter styles
+      # @param themes [Hash] reusable scene-wide layer parameter themes
+      # @param layers [Array<Hash>] initial layer definitions
+      def initialize(name:, styles: {}, themes: {}, layers: [])
         @name = name.to_sym
-        @layers = []
+        @styles = styles
+        @themes = themes
+        @theme_name = nil
+        @theme_params = {}
+        @layers = layers.map { |layer| deep_dup(layer) }
       end
 
       # Evaluate a scene block.
@@ -27,17 +35,65 @@ module Vizcore
       # @yield Layer definition block
       # @return [void]
       def layer(name, &block)
-        builder = LayerBuilder.new(name: name)
+        builder = LayerBuilder.new(name: name, styles: @styles, defaults: @theme_params)
         builder.evaluate(&block)
         @layers << builder.to_h
       end
 
+      # Define a related group of layers with shared params.
+      #
+      # @param name [Symbol, String] group identifier
+      # @yield Layer group definition block
+      # @return [void]
+      def group(name, &block)
+        builder = LayerGroupBuilder.new(name: name, styles: @styles, defaults: @theme_params)
+        builder.evaluate(&block)
+        @layers.concat(builder.to_a)
+      end
+
+      # Apply a named theme as default params for all layers in this scene.
+      #
+      # @param name [Symbol, String] theme identifier
+      # @raise [ArgumentError] when the theme is unknown
+      # @return [Hash] applied theme params
+      def use_theme(name)
+        theme_name = name.to_sym
+        theme_params = @themes.fetch(theme_name) { raise ArgumentError, "unknown theme: #{theme_name}" }
+        @theme_name = theme_name
+        @theme_params = deep_dup(theme_params)
+        @layers = @layers.map { |layer| apply_theme_defaults(layer, @theme_params) }
+        deep_dup(@theme_params)
+      end
+
       # @return [Hash] serialized scene payload
       def to_h
-        {
+        scene = {
           name: @name,
-          layers: @layers.map { |layer| layer.dup }
+          layers: @layers.map { |layer| deep_dup(layer) }
         }
+        scene[:theme] = @theme_name if @theme_name
+        scene
+      end
+
+      private
+
+      def apply_theme_defaults(layer, theme_params)
+        themed_layer = deep_dup(layer)
+        themed_layer[:params] = deep_dup(theme_params).merge(Hash(themed_layer[:params] || {}))
+        themed_layer
+      end
+
+      def deep_dup(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, entry), output|
+            output[key] = deep_dup(entry)
+          end
+        when Array
+          value.map { |entry| deep_dup(entry) }
+        else
+          value
+        end
       end
     end
   end