tef-animation 0.1.0 → 0.1.1

data/lib/tef/Sequencing/SequencePlayer.rb

@@ -6,7 +6,25 @@ require_relative 'SheetSequence.rb'
 
 module TEF
 	module Sequencing
+		# Sequene Player class.
+		#
+		# This class is meant as a easy means to play {BaseSequence}s.
+		# It allows the user to start and stop sequences, play them in parallel,
+		# or overwrite them.
+		#
+		# Register hooks to be called after an execution step with {#after_exec}.
+		#
+		# Start playing a sequence by using {#[]=}, then use {#delete} to stop
+		# it prematurely.
+		#
+		# @todo Add pausing of sequences. Requires the BaseSequence to have a
+		#   time conversion built-in as well.
 		class Player
+
+			# Initialize a player instance
+			#
+			# It can immediately be used to play {BaseSequence}s or {Sheet}s, though
+			# {#after_exec} callbacks should first be registered.
 			def initialize()
 				@activeSequences = {}
 				@sequenceMutex = Mutex.new
@@ -24,10 +42,31 @@ module TEF
 				@playThread.abort_on_exception = true
 			end
 
+			# Add a callback to be executed after a animation step.
+			#
+			# The block passed to this function will be executed after each
+			# {EventCollector#execute!}, i.e. after every tick of the animation
+			# system.
+			# This makes it possible to connect it to the Animation system,
+			# for example by calling {Animation::Handler#update_tick},
+			# as well as the parameter stack by calling
+			# {ParameterStack::Stack#process_changes}
 			def after_exec(&block)
 				@post_exec_cbs << block if block_given?
 			end
 
+			# Insert and start a new program.
+			#
+			# This will:
+			# - Stop and tear the currently playing program under 'key' down.
+			# - Instantiate a {SheetSequence} IF the program is a {Sheet}
+			# - Immediately start playing the new program.
+			#
+			# The inserted program is returned.
+			# {#delete} can be used to stop a given program.
+			#
+			# @param key Arbitrary key to identify the program with.
+			# @param [BaseSequence, Sheet] program Program to start playing.
 			def []=(key, program)
 				@sequenceMutex.synchronize do
 					if @activeSequences[key]
@@ -35,7 +74,6 @@ module TEF
 					end
 
 					if program.is_a? Sheet
-						puts "Inited sheet with start at #{Time.now()}"
 						program = SheetSequence.new(Time.now(), 1, sheet: program)
 					end
 
@@ -48,6 +86,8 @@ module TEF
 				program
 			end
 
+			# Delete a given program by its key.
+			# This will stop and tear the specified program down.
 			def delete(key)
 				@sequenceMutex.synchronize do
 					if @activeSequences[key]

data/lib/tef/Sequencing/Sheet.rb

@@ -1,16 +1,51 @@
 
+require_relative 'EventCollector.rb'
 
 module TEF
 	module Sequencing
+		# Sheet class
+		#
+		# This class is meant as a container for the minimum
+		# amount of information necessary to instantiate a {SheetSequence}.
+		#
+		# It provides a clean and easy way for the user to define
+		# a sequence of events, as well as minimally necessary information
+		# such as the speed of the sequence or the starting and ending
+		# times.
 		class Sheet
+			# @return [Numeric] The local starting time. Defaults to
+			#  0, i.e the sheet will start playing immediately.
+			#  This does not affect the actual time scaling, but instead
+			#  is merely used to know when to instantiate the {SheetSequence}
 			attr_accessor :start_time
+
+			# @return [Numeric] The local ending-time. Defaults to nil, i.e.
+			#  it will be auto-determined by the notes in the sheet.
+			#  Affects when the sheet is torn down and stops
+			#  execution!
 			attr_accessor :end_time
 
+			# @return [Numeric, nil] Tempo of the sheet. Defines the execution
+			#  speed in BPM. If left nil, the execution speed of the parent
+			#  sheet is used.
 			attr_accessor :tempo
 
+			# @return [nil, Proc] Block to call when setting up the {SheetSequence}.
+			#  This is the main way of letting the user configure the {SheetSequence},
+			#  as this block is called from the context of the sheet itself.
+			#  Look at the functions of the Sheet Sequence for more details.
+			#
+			# @see SheetSequence#at
+			# @see SheetSequence#after
+			# @see SheetSequence#play
 			attr_reader :setup_block
 			attr_reader :teardown_block
 
+			# Initialize a new Sheet.
+			#
+			# The user should configure the sheet by writing into
+			# {#start_time}, {#end_time} and by supplying at least a
+			# {#sequence}
 			def initialize()
 				@start_time = 0;
 				@end_time = nil;
@@ -21,10 +56,23 @@ module TEF
 				@teardown_block = nil;
 			end
 
+			# Configure a block to call when setting up the {SheetSequence}.
+			# This is the main way of letting the user configure the {SheetSequence},
+			# as this block is called from the context of the sheet itself.
+			# Look at the functions of the Sheet Sequence for more details.
+			#
+			# @see SheetSequence#at
+			# @see SheetSequence#after
+			# @see SheetSequence#play
 			def sequence(&block)
 				@setup_block = block;
 			end
 
+			# Configure the block to call when the {SheetSequence} is about to
+			# be torn down. Use this to stop or delete any resources allocated
+			# to the sheet.
+			#
+			# Guaranteed to always be called.
 			def teardown(&block)
 				@teardown_block = block;
 			end

data/lib/tef/Sequencing/SheetSequence.rb

@@ -4,7 +4,25 @@ require_relative 'Sheet.rb'
 
 module TEF
 	module Sequencing
+		# Sheet Sequence class.
+		#
+		# This is the main way for the user to specify an exact sequence of events
+		# to execute. It is construced with the help of a {Sheet}, which
+		# acts as specification for this Sheet Sequence.
+		#
+		# Think of the {Sheet} as being the script for a play or movie, while
+		# the {SheetSequence} has the job of actually performing everything.
 		class SheetSequence < BaseSequence
+
+			# Initialize a SheetSequence.
+			#
+			# This is mostly done via {Player#[]=} by passing a {Sheet}.
+			# However, a sequence can also be manually instantiated.
+			#
+			# After initialization, the sheet's {Sheet#setup_block} is called
+			# to fill this SheetSequence with actual content.
+			# The user may also call {#at} and {#after} manually to add additional
+			# events.
 			def initialize(offset, slope, **options)
 				super(offset, slope, **options);
 
@@ -55,6 +73,23 @@ module TEF
 				super();
 			end
 
+			# Insert an event or subsheet into the event list.
+			#
+			# This is the main way of adding events to this sequence.
+			# Each call to the function will insert a new event at the specified
+			# time, which will call the passed block.
+			# If, instead, a parameter called :sheet or :sequence is passed,
+			# instead the the passed sequence will be instantiated and
+			# added to the list of programs.
+			# Any further options are directly passed to the constructor
+			# of the class specified by the :sequence parameter
+			#
+			# If a block was passed, it will be instance_exec'd at the specified
+			# time.
+			#
+			# Note that any used or created resources shall be destroyed in
+			# the {Sheet#teardown} block. Sub-Sequences as well as notes
+			# played by {#play} are automatically torn down.
 			def at(time, **options, &block)
 				@latest_note_time = time;
 
@@ -82,10 +117,22 @@ module TEF
 				@notes.insert((i || -1), new_event);
 			end
 
+			# Similar to {#at}, but specifies time relative to the
+			# last event time.
+			# @see #at
 			def after(time, **options, &block)
 				at(time + (@latest_note_time || 0) , **options, &block);
 			end
 
+			# Play a music file, using `play`
+			#
+			# The PID of the music playing task is saved, and the process
+			# will be killed when this sheet is torn down. The user does not
+			# have to do anything else, but may choose to prematurely kill
+			# the playback by using {#kill}
+			#
+			# @param [String] music_piece Path of the file to play.
+			# @return [Numeric] The PID of the spawned process.
 			def play(music_piece, volume = 0.3)
 				play_pid = spawn(*%W{play -q --volume #{volume} #{music_piece}});
 
@@ -98,11 +145,12 @@ module TEF
 				play_pid
 			end
 
+			# Shorthand to kill
 			def kill(pid)
 				Process.kill('QUIT', pid);
 			end
 
-			def overload_append_events(collector)
+			private def overload_append_events(collector)
 				i = 0
 				loop do
 					next_program = @subprograms[i]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tef-animation
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - TheSystem