tef-animation 0.1.0 → 0.1.1

data/lib/tef/Animation/Coordinate.rb

@@ -4,7 +4,17 @@ $coordinate_def ||= {
 	y: 1,
 }
 
+# TheElectricFursuits module.
+# @see https://github.com/TheElectricFursuits
 module TEF
+	# Animation-Related Module
+	#
+	# This module wraps all classes related to TEF 'Synth'-Line animation.
+	# They are meant to provide an abstraction layer over the hardware-implemented
+	# animations that run on slave devices, such as the FurComs-Connected Synth Bit,
+	# and give the user full access to high-level functions such as configuring
+	# named parameters, setting up value smoothing and transitions, and
+	# creating and deleting objects.
 	module Animation
 		class Coordinate
 			$coordinate_def.each do |c, id|

data/lib/tef/Animation/Eyes.rb

@@ -1,6 +1,8 @@
 
 require_relative 'Animatable.rb'
 
+# TheElectricFursuits module.
+# @see https://github.com/TheElectricFursuits
 module TEF
 	module Animation
 		class Eye < Animatable

data/lib/tef/Animation/Value.rb

@@ -1,14 +1,64 @@
 
-
+# TheElectricFursuits module.
+# @see https://github.com/TheElectricFursuits
 module TEF
+	# Animation-Related Module
+	#
+	# This module wraps all classes related to TEF 'Synth'-Line animation.
+	# They are meant to provide an abstraction layer over the hardware-implemented
+	# animations that run on slave devices, such as the FurComs-Connected Synth Bit,
+	# and give the user full access to high-level functions such as configuring
+	# named parameters, setting up value smoothing and transitions, and
+	# creating and deleting objects.
 	module Animation
 		class Value
 			PARAM_TYPES = 	[:add, :multiply, :dampen, :delay, :from, :jump, :velocity];
 
+			# @return [Integer] Hardware-Number of this Value
 			attr_reader :ID
 
+			# @return [String, nil] Module-ID of the {Animatable} that this
+			#  Value belongs to.
 			attr_reader :module_id
 
+			# @!attribute [rw] add
+			# @return [Numeric] The add-offset to apply to this Value.
+			#  Can be used either to set the absolute target (with {#from} being
+			# nil), or to specify an offset of the number grabbed from {#from}.
+
+			# @!attribute [rw] multiply
+			# @return [Numeric] Multiplication factor. Will be applied to
+			#  ({#from} + {#add}) * {#multiply}. 0 means no multiplication.
+
+			# @!attribute [rw] dampen
+			# @return [Numeric] dampening factor. Causes the actual output value
+			#  to smoothly transition to the target value ((from + add) * multiply).
+			#  Larger values take longer (higher dampening)
+
+			# @!attribute [rw] delay
+			# @return [Numeric] delay factor. If it and {#dampen} are nonzero,
+			#  will cause the actual output to oscillate slightly. Also
+			#  causes {#velocity} to have an effect. Higher delays cause
+			#  slower transitions, and may need more {#dampen}ing to mitigate
+			#  overshoot.
+
+			# @!attribute [rw] from
+			# @return [String,nil] If not set to nil, defines the other {Value}
+			#  that this Value will take the output from. Allows the user
+			#  to follow some other parameter and create interesting linkages.
+
+			# @!attribute [w] jump
+			# @return [Numeric] Instantly jump to the given number, skipping
+			#  animation and smoothing. Will not reconfigure the actual target,
+			#  and can thusly be used to temporarily "bump" the value.
+
+			# @!attribute [w] velocity
+			# @return [Numeric] Set the velocity of the value. Only has an
+			#  effect if {#dampen} and {#delay} are nonzero.
+
+			# Initialize a new Value.
+			# @param [Integer] value_num The hardware ID of this Value.
+			#  must match the ID defined in the animation slaves.
 			def initialize(value_num)
 				@ID = value_num;
 
@@ -26,11 +76,22 @@ module TEF
 				end
 			end
 
+			# @return [String] Total ID of this Value, in the form
+			#   'SxxMxxVxx'
 			def total_id()
 				"#{@module_id}V#{@ID.to_s(16)}"
 			end
 
+			# Internal function to set any of the Value's parameters.
+			#
+			# This can be called by the user, but it is preferrable to use
+			# {#configure} or the matching parameter setter functions.
 			def generic_set(key, value)
+				if key == :from
+					self.from = value
+					return
+				end
+
 				raise ArgumentError, 'Key does not exist!' unless PARAM_TYPES.include? key
 				raise ArgumentError, "Input must be numeric!" unless value.is_a? Numeric
 
@@ -54,6 +115,13 @@ module TEF
 				end
 			end
 
+			# Configure the Value with a Hash.
+			#
+			# This lets the user configure the Value by passing a Hash.
+			# The data will be passed into the six attributes of this Value
+			# according to their key.
+			# @example
+			#  a_color.configure({ add: 2, dampen: 10 })
 			def configure(data)
 				if data.is_a? Numeric
 					self.add = data
@@ -92,10 +160,16 @@ module TEF
 				return !@changes.empty?
 			end
 
+			# Internal function to strip trailing zeroes for floats
 			private def rcut(value)
 				value.to_s.gsub(/(\.)0+$/, '')
 			end
 
+			# @private
+			# Internal function to retrieve the list of changes for this Value.
+			# @note Do not call this as user unless you know what you are doing!
+			#  This will delete the retrieved changes, which may cause loss of
+			#  data if they are not properly sent to the animation slaves!
 			def set_string()
 				return nil unless has_changes?
 

data/lib/tef/ParameterStack/Override.rb

@@ -1,13 +1,39 @@
 
 require_relative 'Stack.rb'
 
+# TheElectricFursuits module.
+# @see https://github.com/TheElectricFursuits
 module TEF
 	module ParameterStack
+		# Override class.
+		#
+		# This class represents one 'access point' for the software,
+		# with which it can override certain values of the {Stack}
+		# it belongs to.
+		#
+		# Using it is as simple as using a Hash:
+		# @example
+		#  override = Override.new(central_stack, 10);
+		#  override['SomeParam'] = 5
+		#  override['SomeParam'] = nil # Relinquish control over the value.
 		class Override
 			include Comparable
 
+			# @return [Numeric] Level of this Override.
+			#   Higher levels mean higher priority. The highest-level
+			#   override that is active for any given key will determine
+			#   that key's value!
 			attr_reader :level
 
+			# Initialize an Override.
+			#
+			# Values can be written into the Override immediately after
+			# creation. When the Override is no longer used,
+			# make sure to call {#destroy!}
+			#
+			# @param [Stack] stack The stack to write to.
+			# @param [Numeric] init_level Level of this Override.
+			#  Can not be changed, is always the same for all keys!
 			def initialize(stack, init_level = 0)
 				raise ArgumentError, 'Handler must be CoreStack!' unless stack.is_a? Stack
 
@@ -21,10 +47,17 @@ module TEF
 				@stack.add_override self
 			end
 
+			# @return The value of this Override for a given key.
+			# @note This will not be the global key. Use {Stack#[]} to retrieve
+			#  the currently active key.
 			def [](key)
 				@overrides[key]
 			end
 
+			# Set the value for the given key.
+			# Setting nil as value causes this Override to relinquish control
+			# @param key Hash-Key
+			# @param new_value User-defined value. If nil, relinquishes control.
 			def []=(key, new_value)
 				return if @overrides[key] == new_value
 
@@ -37,13 +70,18 @@ module TEF
 				@stack.override_claims self, key
 			end
 
+			# @return [true,false] Whether this Override includes a given key
 			def include?(key)
 				@overrides.include? key
 			end
+
+			# @return [Array] List of keys
 			def keys
 				@overrides.keys
 			end
 
+			# Delete a value for the given key.
+			# Equivalent to calling {#[]=} nil
 			def delete(key)
 				return unless @overrides.include? key
 				@overrides.delete key
@@ -53,6 +91,15 @@ module TEF
 				@stack.recompute_single key
 			end
 
+			# Destroy this Override.
+			#
+			# This function MUST be called if the user no longer
+			# needs this object. It relinquishes control over all the
+			# values that this Override formerly held.
+			#
+			# Note that nothing else is modified, and
+			# {Stack#add_override} could be used to re-add
+			# this Override.
 			def destroy!
 				@stack.remove_override self
 			end

data/lib/tef/ParameterStack/Stack.rb

@@ -1,10 +1,29 @@
 
 require_relative 'Override.rb'
 
+# TheElectricFursuits module.
+# @see https://github.com/TheElectricFursuits
 module TEF
+	# Module for the ParameterStack TEF code.
+	#
+	# The ParameterStack system is a module designed to let multiple different
+	# subsystems of code interact and configure certain core parameters.
+	# Each subystem is assigned its own {ParameterStack::Override}, and can
+	# seamlessly take and relinquish control over parameters at any time.
 	module ParameterStack
+		# Parameter Stack class.
+		#
+		# This class contains all parameters that have been configured by
+		# {Override}s. It provides a way to retrieve the currently valid
+		# coniguration, as well as letting the user (de)regsiter new {Override}s.
 		class Stack
+
+			# @return [Hash] Hash whose keys specify which parameters have been
+			#  changed since the last recompute cycle.
 			attr_reader :changes
+
+			# @return [Hash] Hash of the overrides that have control over
+			#  a given parameter key.
 			attr_reader :active_overrides
 
 			def initialize()
@@ -22,16 +41,32 @@ module TEF
 				@default_override = Override.new(self, -1);
 			end
 
+			# @return Returns the currently configured parameter for the given key.
 			def [](key)
 				@current_values[key]
 			end
+
+			# Set the default parameter for a given key.
+			#
+			# Default parameters have a level of -1, meaning that any
+			# {Override} with priority >= 0 (the default) will claim the value.
 			def []=(key, value)
 				@default_override[key] = value
 			end
+
 			def keys
 				@current_values.keys
 			end
 
+			# Add a callback for immediate parameter changes.
+			#
+			# The given block will be called for any change of a parameter,
+			# so should be used sparingly. Recursive parameter setting should also
+			# be carefully avoided!
+			#
+			# @param [Array] keys Key whitelist to trigger on.
+			# @yieldparam key Key that was changed.
+			# @yieldparam value New value of the key
 			def on_recompute(*keys, &block)
 				@recompute_blocks << {
 					block: block,
@@ -39,6 +74,16 @@ module TEF
 				}
 			end
 
+			# Add a callback to be called during {#process_changes}.
+			#
+			# The given block will be called if a change in a key specified by
+			# the filters occoured, and will be called during {#process_changes}.
+			#
+			# This lets the user only act on changes, and act on them in bunches,
+			# rather than on every individual change.
+			#
+			# @param [String, Regexp] filters List of filters to use. Acts like
+			#  a whitelist, can be a Regexp
 			def on_change(*filters, &block)
 				filters = nil if filters.empty?
 
@@ -57,6 +102,11 @@ module TEF
 				end
 			end
 
+			# Check if an {Override} can claim a key.
+			#
+			# This is mainly an internal function. It will check if the passed
+			# {Override} has permission to claim the given key, and will
+			# change the value accordingly.
 			def override_claims(override, key)
 				return if !(@active_overrides[key].nil?) && (@active_overrides[key] > override)
 
@@ -69,6 +119,12 @@ module TEF
 				mark_key_change key
 			end
 
+			# Re-Calculate which {Override} is currently claiming a given key.
+			#
+			# This method is mainly for internal work. It will iterate through
+			# the list of {Overrides} to find the next in line that wants
+			# to claim the given key.
+			# May be slow!
 			def recompute_single(key)
 				old_value = @current_values[key]
 
@@ -95,6 +151,9 @@ module TEF
 				mark_key_change key if old_value != @current_values[key]
 			end
 
+			# Recompute the owner of the list of keys.
+			# Mainly an internal function, used by an {Override} that is
+			# de-registering itself.
 			def recompute(keys)
 				keys.each do |key|
 					recompute_single key
@@ -116,6 +175,11 @@ module TEF
 				return false
 			end
 
+			# Trigger processing of all {#on_change} callbacks.
+			#
+			# Works best when triggered after all changes for a given
+			# time-tick have been performed, such as during a
+			# {Sequencing::Player#after_exec} callback.
 			def process_changes()
 				change_list = @changes.keys
 

data/lib/tef/ProgramSelection/ProgramID.rb

@@ -1,12 +1,47 @@
 
 
+
+# TheElectricFursuits module.
+# @see https://github.com/TheElectricFursuits
 module TEF
+	# Program Selection related module
+	#
+	# This module is meant to wrap around the functions that define and help with
+	# program selection.
+	# Its main purpose is to provide an easy to use identification and selection
+	# system for the various animations and effects of a fursuit. Often, different
+	# effects can have the same name (such as a 'hello' animation), and
+	# even within a certain type of animation (a group), variations of the same
+	# animaton can occour.
+	#
+	# The code here thusly provides a {ProgramSelection::ID} for identification,
+	# as well as a {ProgramSelection::Selector} that eases selection of a fitting
+	# program in certain situations.
 	module ProgramSelection
+		# Program ID class.
+		#
+		# This class is meant to uniquely identify a specific program.
+		# It also provides a {#hash} and {#==} operator, allowing the use
+		# as hash key.
 		class ID
+			# @return [String] Main title of the program.
+			#  Often defines the action the program will execute, i.e. 'hello'
+			#  or 'red alert'
 			attr_reader :title
+			# @return [Array<String>] List of groups this program belongs to.
+			#  Further defines the program by providing a bit of context, such as
+			#  'portal', 'glad os', etc.
 			attr_reader :groups
+
+			# @return [String] The variant of this program.
+			#  Its main purpose is to separate different variations of the same
+			#  general program, such as when there are different 'hello's from
+			#  the same groups. Has no effect on the actual selection.
 			attr_reader :variant
 
+			# @return [Numeric] The hash key of this ID. Allows
+			#  identification and comparison of keys in a Hash. Two keys match if
+			#  they have the same groups, title and are of the same variant.
 			attr_reader :hash
 
 			def initialize(title, groups, variant)
@@ -17,6 +52,8 @@ module TEF
 				@hash = @title.hash ^ @groups.hash ^ @variant.hash
 			end
 
+			# @return [true, false] Two keys match if
+			#  they have the same groups, title and are of the same variant.
 			def ==(other)
 				if other.is_a? String
 					@title == other
@@ -30,6 +67,8 @@ module TEF
 			end
 			alias eql? ==
 
+			# @return [-1..1] Sorting operator, sorts alphabetically by title,
+			#  then group, then variant.
 			def <=>(other)
 				tsort = (@title <=> other.title)
 				return tsort unless tsort.zero?
@@ -40,6 +79,13 @@ module TEF
 				@variant <=> other.variant
 			end
 
+			# Compute the selection score for this ID.
+			# Used in {Selector} to determine the best-matching program ID
+			# for a given group scoring.
+			#
+			# @param [Hash<String, Numeric>] Hash of group weights. Any group
+			#  of this ID that has a weight will be added to the score.
+			# @return [Numeric] Sum of the selected group weights.
 			def get_scoring(group_weights)
 				score = 0;
 

data/lib/tef/ProgramSelection/ProgramSelector.rb

@@ -3,7 +3,16 @@ require_relative 'ProgramID.rb'
 
 module TEF
 	module ProgramSelection
+		# Program Selector class.
+		#
+		# This class's purpose is to provide a central list of all known
+		# programs, as well as to give the user a method of easily selecting
+		# a matching program for a given situation or query.
 		class Selector
+
+			# @return [Hash<String, Numeric>] Weights of groups.
+			#  Used when selecing a program via {#fetch_ID} or {#fetch_string}.
+			#  Higher weights mean higher preference
 			attr_accessor :group_weights
 
 			def initialize()
@@ -13,6 +22,22 @@ module TEF
 				@group_weights = {}
 			end
 
+			# Register a new ID to the list of known {ID}s.
+			#
+			# This will ensure that the given {ID} is present in the list
+			# of known IDs. It will then return either the given {ID} or an equivalent
+			# ID already present in the list. Either can be used for identification.
+			#
+			# This function can be used in two ways, either by passing a {ID} as
+			# only argument, or by passing a String as first argument and optional
+			# group and variant specifiers.
+			#
+			# @param [ID, String] program Program {ID} OR a String to use
+			#   as program title.
+			# @param [Array<String>] pgroups Optional list of groups to construct
+			#   a new {ID} with.
+			# @param [String, nil] pvariant Optional variant specification to
+			#   construct a new {ID} with.
 			def register_ID(program, pgroups = [], pvariant = nil)
 				if program.is_a? String
 					program = ID.new(program, pgroups, pvariant)
@@ -31,6 +56,21 @@ module TEF
 				program
 			end
 
+			# Fetch an {ID} from the list of known IDs.
+			#
+			# This will fetch a specific {ID} from the list of IDs, based on
+			# its title and group weights.
+			# The title MUST match the given title. Then, the group scoring
+			# of each matching ID will be calculated, based on {#group_weights} and
+			# the given group weights. From all IDs with maximum group weight,
+			# a random variant will be selected, and will be returned.
+			#
+			# @param [String] title Title to look for. Must exactly match the
+			#  title of the {ID}.
+			# @param [Hash<String, Numeric>] group_weights Group weights. Higher
+			#  group score means a specific {ID} will be preferred.
+			# @return [nil, ID] Either nil if no {ID} with matching title was found,
+			#  or the ID with best group score.
 			def fetch_ID(title, group_weights = {})
 				return nil if @known_programs[title].nil?
 
@@ -56,6 +96,20 @@ module TEF
 				current_list.sample
 			end
 
+			# Fetch an {ID} based on a string.
+			#
+			# This function performs similarly to {#fetch_ID}, but is based on
+			# a more human readable string.
+			# The input is parsed as follows:
+			# - It is split at the first ' from '
+			# - The first part is taken as a title.
+			# - The second part will be split through ' and '. Each resulting
+			#   array element is taken as group weight with a score of 2.
+			#
+			# @example
+			#  selector.fetch_string('hello from portal and turret')
+			#   # This is equivalent to:
+			#  selector.fetch_ID('hello', { 'portal' => 2, 'turret' => 2})
 			def fetch_string(str)
 				title, groups = str.split(" from ");
 				groups ||= "";