tef-animation 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3bc7c194c8425278ad0369c293684b65008f293f
-  data.tar.gz: b59ce88b52067a8c5b2b8c2070e7abf408d073e5
+  metadata.gz: 92421ddea4eb5a58abffa7fdb3ec987f645281d7
+  data.tar.gz: c2fc1d82fdffc6ecc435ed47554f3dca0bb5834b
 SHA512:
-  metadata.gz: 9e1c4ed9339a1054e69a5b2074e6f1741da37c3490e7cac055c1f696ad3e6365ecc2b2dda615265df8d3ebd072f1a9b9665d3ca9ef9e31bb9a8fd42c53a5c02a
-  data.tar.gz: 13d28689ecdd5bba1fbb8028076b39ba3623b62b0f7b8f7e38cafdf108941395907790509bef2d340939eb4b1e817561f12d5a01185e95466d20fb2b5e417b74
+  metadata.gz: df1fd4e30609e37ee34281ccad04a759af87155757af7886d163c7082caa3e9427854b09353d042342ebd2e8e5d00c4ec3b79289bb7c7ecbff21353d1abb9e10
+  data.tar.gz: 96069806358729bff76ecebe28a925caf52d8587acc9ba05dc7950595e9ad1f3b5980b32a16ca84a074fd5f9ef896eda0c5d496061ab1c8c08f42806051cead0

data/lib/tef/Animation/Animatable.rb

@@ -3,24 +3,80 @@ require_relative 'Value.rb'
 require_relative 'Color.rb'
 require_relative 'Coordinate.rb'
 
+# 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
+		# Animatable base class.
+		#
+		# This class implements all necessary functions to write a custom
+		# animatable object with ease. It provides a DSL to easily
+		# register new animatable colours, values and coordinates, and handles
+		# updating and configuring them.
+		#
+		# By inheriting from this base class, the user must only define
+		# the animatable properties of their object by using:
+		# - {Animatable#animatable_attr}
+		# - {Animatable#animatable_color}
+		# - {Animatable#animatable_coordinate}
+		#
+		# The object must also be passed to the Animation handler, by calling:
+		# handler['S123M123'] = your_instance;
 		class Animatable
+			# @return [String, nil] Module ID of this object as in SxxMxx, or nil.
 			attr_reader :module_id
+
+			# @return [Time, nil] If set, returns the time this object will
+			#  auto-delete. This will not delete the Ruby object, but it will
+			#  send a delete request to the animation slaves.
 			attr_reader :death_time
 
+			# @return [Numeric, nil] If set, returns the time (in s) that this
+			#  object will live for. If the object is currently a live animation,
+			#  setting this will make the object die in the given number of
+			#  seconds. If it is not currently animated, it will make the object
+			#  die after the given number of seconds, starting from when it
+			#  was registered with the handler.
 			attr_reader :death_delay
 
+			# @private
+			# @return [Array<{Symbol, Integer>] List of registered animatable attributes
 			def self.get_attr_list
 				@class_attribute_list ||= {}
 			end
+			# @private
+			# @return [Array<Symbol, Integer>] List of registered animatable colours
 			def self.get_color_list
 				@class_color_list ||= {}
 			end
+			# @private
+			# @return [Array<Symbol, Integer>] List of registered animatable coordinates
 			def self.get_coordinate_list
 				@class_coordinate_list ||= {}
 			end
 
+			# Defines a new animatable attribute.
+			#
+			# The defined attribute will become accessible via a getter and
+			# convenience setter function, giving the user access to the
+			# created {Value} instance.
+			#
+			# @param name [Symbol] Name of the attribute, as symbol. Will
+			#  create getter and setter functions.
+			# @param id [Numeric] Address of the animatable attribute. Must match
+			#  the address defined in the animation C++ code!
+			#
+			# @!macro [attach] anim.attribute
+			#   @!attribute [rw] $1
+			#     @return [Value] Animated value '$1' (ID $2)
 			def self.animatable_attr(name, id)
 				get_attr_list()[name] = id
 
@@ -37,6 +93,19 @@ module TEF
 				end
 			end
 
+			# Defines a new animatable color
+			#
+			# The defined color will become accessible via a getter and
+			# convenience setter function, giving the user access to the
+			# created {Color} instance.
+			#
+			# @param name [Symbol] Name of the color, as symbol. Will
+			#  create getter and setter functions.
+			# @param id [Numeric] Address of the animatable color. Must match
+			#  the address defined in the animation C++ code!
+			# @!macro [attach] anim.color
+			#   @!attribute [rw] $1
+			#     @return [Color] Animated color '$1' (ID $2)
 			def self.animatable_color(name, id)
 				get_color_list()[name] = id
 
@@ -49,6 +118,20 @@ module TEF
 				end
 			end
 
+			# Defines a new animatable coordinate.
+			#
+			# The defined coordinate will become accessible via a getter and
+			# convenience setter function, giving the user access to the
+			# created {Value} instance.
+			#
+			# @param name [Symbol] Name of the coordinate, as symbol. Will
+			#  create getter and setter functions.
+			# @param id [Numeric] Starting address of the coordinates. Expects
+			#  the coordinate parameters to be sequential!
+			#
+			# @!macro [attach] anim.attribute
+			#   @!attribute [rw] $1
+			#     @return [Coordinate] Coordinate for '$1' (ID $2)
 			def self.animatable_coordinate(name, start)
 				get_coordinate_list()[name] = start
 
@@ -57,6 +140,10 @@ module TEF
 				end
 			end
 
+			# Initialize a generic animatable object.
+			#
+			# This will initialize the necessary internal hashes
+			# that contain the animatable attributes, colors and coordinates.
 			def initialize()
 				@animatable_attributes = {}
 				@animatable_colors = {}
@@ -84,6 +171,21 @@ module TEF
 				@death_time_changed = true
 			end
 
+			# Make this object die in a given number of seconds.
+			# After the timer set here expires, the object will automatically
+			# be deleted. As the slaves will do it automatically, it is good
+			# practice to give any temporary object a death time, if possible, to
+			# have them automatically cleaned up.
+			#
+			# It is possible to remove a death time or extend it, by calling
+			# this function another time.
+			#
+			# @note This will not delete the Ruby object, but it will be
+			#  unregistered from the {Animation::Handler}. It can safely
+			#  be re-registered to re-create a new object.
+			#
+			# @param t [Numeric, nil] The time, in seconds until this object will
+			#  be killed.
 			def die_in(t)
 				if t.nil?
 					self.death_time = nil
@@ -98,10 +200,25 @@ module TEF
 				@death_delay = t
 			end
 
+			# Instantly deletes this object from the animation slaves.
+			# @see #die_in
 			def die!
 				self.death_time = Time.at(0)
 			end
 
+			# Quickly configure this object.
+			#
+			# This is a convenience function to very quickly and easily
+			# (re)configure this animatable object. It will take a hash
+			# or named options, and will pass the values of the hash to
+			# the matching {Value}, {Color} or {Coordinate}
+			#
+			# @see Value#configure
+			# @see Color#configure
+			# @see Coordinate#configure
+			#
+			# @example
+			#   my_box.configure up: 10, down: 5, left: { dampen: 0.4, add: 2 }
 			def configure(h = nil, **opts)
 				h ||= opts;
 
@@ -118,17 +235,29 @@ module TEF
 				end
 			end
 
+			# Return a default creation string.
+			#
+			# This function MUST be overwritten by the user to provide a proper
+			# creation string! It will be sent over FurComs via the 'NEW' topic
+			# and must contain all necessary information for the slaves to
+			# construct the matching object.
 			def creation_string
-				""
+				''
 			end
 
-			def all_animatable_attributes
+			private def all_animatable_attributes
 				out =  @animatable_attributes.values
 				out += @animatable_coordinates.values.map(&:animatable_attributes)
 
 				out.flatten
 			end
 
+			# @private
+			# Set the module ID of this object manually.
+			#
+			# @note Do not call this function, it is purely internal.
+			#  Only the {Handler} may set the module ID, otherwise undefined
+			#  behavior may occour!
 			def module_id=(new_str)
 				unless new_str =~ /^S[\d]{1,3}M[\d]{1,3}$/ || new_str.nil?
 					raise ArgumentError, 'Target must be a valid Animation Value'
@@ -143,6 +272,10 @@ module TEF
 				@module_id = new_str
 			end
 
+			# @private
+			#
+			# Returns a String to be sent via FurComs to configure the object
+			# to die in a certain number of seconds.
 			def death_time_string
 				return nil unless @death_time_changed
 
@@ -155,6 +288,23 @@ module TEF
 				"#{@module_id} #{remaining_time};"
 			end
 
+			# @private
+			#
+			# Returns an array of 'SET' Hashes, to be sent over the FurComs
+			# bus, 'SET' topic. They represent raw value configurations of the
+			# animatable values.
+			#
+			# The {Handler} that called this function has the duty of packing
+			# them into complete commands, as the initial module ID can be
+			# left out for sequential value access, saving a few bytes
+			# each transfer.
+			#
+			# @note Never call this unless you are the {Handler}! It will
+			#  mark the changes as already transmitted, so manually calling
+			#  this will cause data loss!
+			#
+			# @return [Array<Hash>] An array containing Hashes outlining each
+			#  value's SET string.
 			def get_set_strings()
 				return [] unless @module_id
 
@@ -170,6 +320,9 @@ module TEF
 				out_elements
 			end
 
+			# @private
+			#
+			# @see #get_set_strings
 			def get_setc_strings()
 				return [] unless @module_id
 

data/lib/tef/Animation/Animation_Handler.rb

@@ -3,11 +3,36 @@ require 'xasin_logger'
 
 require_relative 'Animatable.rb'
 
+# TheElectricFursuits module.
+# @see https://github.com/TheElectricFursuits
 module TEF
 	module Animation
+		# Animation object handler.
+		#
+		# This class is the handler for one coherent animation system.
+		# Its main purpose is to (de)register animatable objects, distributing
+		# IDs and handing out packed update messages onto a FurComs bus.
 		class Handler
 			include XasLogger::Mix
 
+			# Initialize a Handler.
+			#
+			# This will initialize a handler and connect it to the passed FurComs
+			# bus.
+			# The user may immediately start registering objects after creating
+			# this class, though if the FurComs bus is not connected yet this may
+			# cause very early messages to be lost!
+			#
+			# @param [FurComs::Base] furcoms_bus The FurComs Bus connecting
+			#  instance. Must support send_message(topic, data), nothing else.
+			#
+			# @note {#update_tick} MUST be called after performing any
+			#  changes, be it adding a new {Animatable} or changing values
+			#  of a known animatable. It is recommended to call this function
+			#  only after all changes for a given tick have been performed, so
+			#  that they can be sent over as a batch.
+			#  {Sequencing::Player#after_exec} can be used to register a callback
+			#  to call {#update_tick}.
 			def initialize(furcoms_bus)
 				@furcoms = furcoms_bus
 
@@ -20,6 +45,13 @@ module TEF
 				init_x_log('Animation Handler')
 			end
 
+			# Create a String key representation.
+			#
+			# This will take either a hash or a String,
+			# convert it to a standard String key representation, and then
+			# verify it for correctness.
+			# @param [String, Hash] key the key to clean up.
+			# @return [String] Cleaned string
 			def clean_key(key)
 				key = 'S%<S>dM%<M>d' % key if key.is_a? Hash
 
@@ -30,10 +62,20 @@ module TEF
 				key
 			end
 
+			# @return [Animatable] Returns the Animatable with matching key.
 			def [](key)
 				@active_animations[clean_key key]
 			end
 
+			# Register or replace a {Animatable}.
+			#
+			# This lets the user register a new {Animatable} object with given
+			# key, or replace or delete a pre-existing animation object.
+			#
+			# @param [String, Hash] key The key to write into.
+			# @param [Animatable, nil] Will delete any pre-existing animation, then
+			#  either replace it with the given {Animatable}, or, if nil was
+			#  given, will delete the animation entry.
 			def []=(key, new_obj)
 				@animation_mutex.synchronize {
 					key = clean_key key
@@ -42,18 +84,23 @@ module TEF
 
 					if new_obj.nil?
 						@pending_deletions[key] = true
+						@pending_creations.delete key
 
 					elsif new_obj.is_a? Animatable
 						new_obj.module_id = key
 
 						@active_animations[key] = new_obj
 						@pending_creations[key] = new_obj.creation_string
+						@pending_deletions.delete key
 					else
 						raise ArgumentError, 'New animation object is of invalid type'
 					end
 				}
 			end
 
+			# Internal function to join an Array of strings and send it onto
+			# the FurComs bus on a given topic.
+			# Useful to batch-send, which is a bit more efficient.
 			private def join_and_send(topic, data)
 				return if data.empty?
 
@@ -70,8 +117,12 @@ module TEF
 				@furcoms.send_message topic, out_str
 			end
 
-			# TODO Replace this with a time-synched system
-			# using the main synch time
+			# Internal function to send out death updates.
+		 	# This will send out to topic DTIME, updating the Animatable's
+			# death_time, as well as sending to DELETE for deleted animations.
+			#
+			# @todo Replace this with a time-synched system
+			# using the main synch time, rather than using relative time.
 			private def update_deaths
 				death_reconfigs = [];
 
@@ -99,6 +150,9 @@ module TEF
 				join_and_send('DELETE', deletions)
 			end
 
+			# Private function to send out creation strings.
+			# Will simply send a string per new object, as we do not often
+			# need to initialize objects.
 			private def update_creations
 				@pending_creations.each do |key, val|
 					@furcoms.send_message('NEW', val)
@@ -107,6 +161,15 @@ module TEF
 				@pending_creations = {}
 			end
 
+			# Internal function to optimize sending values.
+			#
+			# Updating values can be optimized in certain ways. The initial
+			# value specifier can be left out if the next value to update
+			# has an ID one after the former message.
+			#
+			# This can significantly reduce message length, for example after
+			# creating a new object and initializing it. Being able to leave out the
+			# Value ID saves about 10 bytes per value!
 			private def optimize_and_send(messages)
 				last_change = {}
 				out_str = '';
@@ -137,11 +200,13 @@ module TEF
 				@furcoms.send_message 'SET', out_str
 			end
 
+			# Internal function, will merely collect
+			# the change strings from all known animations.
 			private def update_values()
 				pending_changes = []
 
 				@animation_mutex.synchronize {
-					@active_animations.each do |key, anim|
+					@active_animations.each do |_, anim|
 						pending_changes += anim.get_set_strings
 					end
 				}
@@ -152,6 +217,8 @@ module TEF
 				optimize_and_send pending_changes
 			end
 
+			# Internal function, will collect all color change strings from
+			# active animations and send it over FurComs
 			private def update_colors
 				pending_changes = []
 
@@ -167,6 +234,17 @@ module TEF
 				join_and_send 'CSET', pending_changes
 			end
 
+			# Update tick.
+			#
+			# Calling this function will send all updates and changes over the
+			# FurComs bus. It is ensured that they occour in the following order:
+			#
+			# - All modules that have actively been deleted in Ruby will be
+			#   deleted.
+			# - Newly created and registered {Animatable}s will be created
+			#   on the animation slaves.
+			# - All {Value} changes of all {Animatable}s will be sent.
+			# - All {Color} changes will be sent.
 			def update_tick()
 				update_creations
 

data/lib/tef/Animation/Color.rb

@@ -1,13 +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 Color
 			PARAM_TYPES = [:jump, :velocity, :target, :delay_a, :delay_b];
 
+			# @return [Integer] Hardware-Number of this Color
 			attr_reader :ID
 
+			# @return [String, nil] Module-ID of the {Animatable} that this
+			#  color belongs to.
 			attr_reader :module_id
 
+			# @!attribute [rw] jump
+			# Immediately set the color of this Color to the jump value,
+			# skipping animation. If animation is set, the Color will then
+			# fade back to the value defined by {#target}
+			# @return [Numeric] Current RGB color code.
+
+			# @!attribute [rw] velocity
+			# Set the animation buffer to the given color. Has no effect
+			# unless {#delay_b} was configued, in which case the animation will
+			# temporarily fade to velocity, then fade back to {#target}
+			# @return [Numeric] Current RGB color code.
+
+			# @!attribute [rw] target
+			# Target of the color animation. Set this as hexadecimal RGB color
+			# code, i.e. 0xRRGGBB, with an optional alpha channel (i.e. 0xFF000000)
+			# for a fully transparent black.
+
+			# @!attribute [rw] delay_a
+			# Smoothing delay for color transition. If {#delay_b} is zero and
+			# delay_a is nonzero, setting {#target} will cause the actual
+			# color to slowly transition to {#target}. Larger values cause
+			# *faster* transitions!
+			#
+			# If delay_b is set, delay_a defines the smoothing speed between the
+			# 'velocity' color and the actual color.
+
+			# @!attribute [rw] delay_b
+			# Smoothing delay for color transition. If both {#delay_a} and delay_b
+			# are nonzero, setting {#target} will cause a smooth transition of the
+			# output color.
+			#
+			# delay_b defines the transition speed of {#target} to an internal,
+			# non-visible 'velocity' color.
+
+			# Initialize a new color.
+			# @param [Integer] value_num The hardware ID of this Color.
+			#  must match the ID defined in the animation slaves.
 			def initialize(value_num)
 				@ID = value_num;
 
@@ -25,10 +76,16 @@ module TEF
 				end
 			end
 
+			# @return [String] Total ID of this Color, in the form
+			#   'SxxMxxVxx'
 			def total_id()
 				"#{@module_id}V#{@ID}"
 			end
 
+			# Internal function to set any of the Color'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)
 				raise ArgumentError, 'Key does not exist!' unless PARAM_TYPES.include? key
 				raise ArgumentError, "Input must be numeric!" unless value.is_a? Numeric
@@ -53,6 +110,13 @@ module TEF
 				end
 			end
 
+			# Configure the color with a hash.
+			#
+			# This lets the user configure the color by passing a hash.
+			# The data will be passed into the five attributes of this color
+			# according to their key.
+			# @example
+			#  a_color.configure({ delay_a: 10, target: 0xFF0000 })
 			def configure(data)
 				if data.is_a? Numeric
 					self.target = data
@@ -69,10 +133,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 color.
+			# @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?