Class: Vizcore::DSL::TimelineBuilder

Inherits:
Object
  • Object
show all
Defined in:
lib/vizcore/dsl/timeline_builder.rb

Overview

Collects ordered timeline scene markers and converts them to transitions.

Defined Under Namespace

Classes: Point

Constant Summary collapse

DEFAULT_BEATS_PER_BAR = 
4

Instance Method Summary collapse

Constructor Details

#initialize(beats_per_bar: DEFAULT_BEATS_PER_BAR, bpm: nil) ⇒ TimelineBuilder

Returns a new instance of TimelineBuilder.

Parameters:

  • bpm (Numeric, nil) (defaults to: nil) —

    fixed BPM for mixed-unit timeline conversion



12
13
14
15
16
 
# File 'lib/vizcore/dsl/timeline_builder.rb', line 12

def initialize(beats_per_bar: DEFAULT_BEATS_PER_BAR, bpm: nil)
  @beats_per_bar = positive_integer(beats_per_bar, "beats_per_bar")
  @entries = []
  @bpm = positive_float(bpm, "timeline bpm") unless bpm.nil?
end

Instance Method Details

#at(position, scene:, cue: nil) ⇒ Hash

Add a scene marker at a timeline position.

Parameters:

  • position (Numeric, Point) —

    seconds by default, or a value from ‘seconds`, `beats`, or `bars`

  • scene (Symbol, String) —

    scene to activate at the position

  • cue (Symbol, String, nil) (defaults to: nil) —

    optional cue identifier for marker metadata

Returns:

  • (Hash) 


34
35
36
37
38
39
40
41
42
43
44
 
# File 'lib/vizcore/dsl/timeline_builder.rb', line 34

def at(position, scene:, cue: nil)
  point = normalize_position(position)
  entry = {
    at: point.value,
    unit: point.unit,
    scene: scene.to_sym
  }
  entry[:cue] = cue.to_sym if cue
  @entries << entry
  entry
end

#bars(value, beats_per_bar: nil) ⇒ Point

Parameters:

  • value (Numeric) —

    bars from the timeline start

  • beats_per_bar (Integer, nil) (defaults to: nil) —

    meter override

Returns:



61
62
63
64
 
# File 'lib/vizcore/dsl/timeline_builder.rb', line 61

def bars(value, beats_per_bar: nil)
  beats_per_measure = beats_per_bar.nil? ? @beats_per_bar : positive_integer(beats_per_bar, "beats_per_bar")
  beats(non_negative_float(value, "timeline bars") * beats_per_measure)
end

#beats(value) ⇒ Point

Parameters:

  • value (Numeric) —

    beats from the timeline start

Returns:



54
55
56
 
# File 'lib/vizcore/dsl/timeline_builder.rb', line 54

def beats(value)
  Point.new(value: non_negative_float(value, "timeline beats"), unit: :beats)
end

#evaluate { ... } ⇒ Vizcore::DSL::TimelineBuilder

Evaluate a timeline block.

Yields:

  • Timeline marker definitions

Returns:



22
23
24
25
26
 
# File 'lib/vizcore/dsl/timeline_builder.rb', line 22

def evaluate(&block)
  instance_eval(&block) if block
  validate_entries!
  self
end

#seconds(value) ⇒ Point

Parameters:

  • value (Numeric) —

    seconds from the timeline start

Returns:



48
49
50
 
# File 'lib/vizcore/dsl/timeline_builder.rb', line 48

def seconds(value)
  Point.new(value: non_negative_float(value, "timeline seconds"), unit: :seconds)
end

#to_h ⇒ Array<Hash>

Returns serialized marker definitions.

Returns:

  • (Array<Hash>) —

    serialized marker definitions



67
68
69
 
# File 'lib/vizcore/dsl/timeline_builder.rb', line 67

def to_h
  @entries.map(&:dup)
end

#transitions ⇒ Array<Hash>

Returns generated scene transitions.

Returns:

  • (Array<Hash>) —

    generated scene transitions



72
73
74
75
76
77
78
79
80
81
82
 
# File 'lib/vizcore/dsl/timeline_builder.rb', line 72

def transitions
  return [] if @entries.length < 2

  @entries.each_cons(2).map do |from_entry, to_entry|
    {
      from: from_entry.fetch(:scene),
      to: to_entry.fetch(:scene),
      trigger: trigger_for(from_entry, to_entry)
    }
  end
end