Improved Docs, AnimationStepApplyMesh+Materials, some other minor tweaks

luprex/cpp/core/animqueue.hpp

@@ -1,13 +1,15 @@
 ///////////////////////////////////////////////////////////////////
 //
-// ANIMATION QUEUES
+// ANIMATION QUEUES AND ANIMATION STEPS
+//
+// See "Animation Queues and Tangible Actors.md" for an overview.
 //
 // An animation queue is a fifo queue of animation steps.  New animations are
 // pushed on the back, and old ones are popped from the front.
 //
 // An animation step is a set of key-value pairs, where each key is an
-// identifier, and each value is either a number, a boolean, an XYZ coordinate,
-// or a string.  A key-value pair can be either persistent or nonpersistent.
+// identifier, and each value is either a number, boolean, vector,
+// token, or string.  A key-value pair can be either persistent or nonpersistent.
 // So a typical animation step might be:
 //
 //    action=walk  [nonpersistent]
@@ -22,9 +24,34 @@
 // by mixing the hash value of the previous step with the hash value
 // of the encoded string of key-value pairs.
 //
+//
 ///////////////////////////////////////////////////////////////////
 //
-// SERIALIZED STORAGE
+// Class AnimStepEditor is used to read+write animation steps.
+//
+// Note: this class is not used for storage of animation steps.
+// Animation steps are stored in class AnimQueue.  AnimStepEditor
+// is only used when you want to extract animation steps from
+// an AnimQueue, or insert new animation steps into an AnimQueue.
+// 
+// Class AnimStepEditor is quite simple: it's a map from Key to
+// AnimValue.  AnimValue is a container that can hold a number,
+// string, vector, token, or boolean.  Class AnimStepEditor provides
+// a variety of accessors to set key-value pairs.
+// 
+// For example, you can populate an animation step by setting
+// key-value pairs directly.  You can import key-value pairs
+// from a lua table.  You can also merge key-value pairs from
+// a different AnimStepEditor.
+//
+// When importing from a lua_table or a from another AnimStepEditor,
+// there are rules for resolving conflicts between any key-value
+// pairs that are already in the builder with those being imported.
+// See the documentation for those functions for more information.
+//
+///////////////////////////////////////////////////////////////////
+//
+// Class AnimQueue stores animation queues.
 //
 // The entired animation queue is stored in a serialized format,
 // as a shared string.  This means that the animation queue can be
@@ -118,7 +145,7 @@ struct AnimValue : public SimpleDynamicValue {
 };
 
 
-class AnimState
+class AnimStepEditor
 {
 private:
     using Map = eng::map<eng::string, AnimValue>;
@@ -126,7 +153,7 @@ private:
 
     // Set the default value, internal
     //
-    eng::string add_default(const eng::string &name, const AnimValue &v, const AnimState *other);
+    eng::string add_default(const eng::string &name, const AnimValue &v, const AnimStepEditor *other);
 
 public:
     // Clear everything
@@ -160,7 +187,7 @@ public:
 
     // Constructs an empty state.
     //
-    AnimState() {}
+    AnimStepEditor() {}
 
     // Convert to an encoded string.
     //
@@ -188,7 +215,7 @@ public:
     //  - If no default value can be found in 'other', then a hardwired
     //    default value is provided.
     //
-    eng::string add_defaults(const AnimState *other);
+    eng::string add_defaults(const AnimStepEditor *other);
     
     // Parse an animstate from a Lua Table.
     //
@@ -199,7 +226,7 @@ public:
     // 
     // If 'allowauto' is true, then the lua table may contain a key-value
     // pair of the form (key, math.auto).  These keys will be stored in the
-    // AnimState map with mapentry.type == SimpleDynamicTag::AUTO.
+    // AnimStepEditor map with mapentry.type == SimpleDynamicTag::AUTO.
     // This is done to express an intent that the value should be
     // automatically computer later.
     // 
@@ -207,7 +234,7 @@ public:
 
     // Generate a merged animstate using a previous state and an update.
     //
-    // Keys from both previous and update are combined to create this AnimState.
+    // Keys from both previous and update are combined to create this AnimStepEditor.
     // Values from 'update' override values from 'previous'.  Persistent flags
     // are taken from 'previous'.  If a key exists in both previous and update,
     // and the key is persistent in 'previous', then the types must match,
@@ -218,7 +245,7 @@ public:
     // a rule to compute that value automatically.  Failure to find a rule
     // results in an error.
     //
-    eng::string merge(const AnimState &previous, const AnimState &update);
+    eng::string merge(const AnimStepEditor &previous, const AnimStepEditor &update);
 
     // Convert an animstate to a lua table.
     //
@@ -250,7 +277,7 @@ public:
 
     // Constructor from an encoded string.
     //
-    AnimState(std::string_view s) { decode(s); }
+    AnimStepEditor(std::string_view s) { decode(s); }
 };
 
 struct AnimCoreState
@@ -271,7 +298,7 @@ public:
     // Clear the steps to an initial state.
     //
     void clear();
-    void clear(const AnimState &initial);
+    void clear(const AnimStepEditor &initial);
 
     // Change the size limit.
     //
@@ -282,14 +309,14 @@ public:
     // Note: add does not automatically compose the step with the previous
     // step, you have to do that yourself.
     //
-    void add(const AnimState &state);
+    void add(const AnimStepEditor &state);
 
     // Replace the most recent animation step.
     //
     // Note: replace does not automatically compose the step with the previous
     // step, you have to do that yourself.
     //
-    void replace(const AnimState &state);
+    void replace(const AnimStepEditor &state);
 
     // Serialize or deserialize to a StreamBuffer
     //
@@ -324,11 +351,11 @@ public:
 
     // Get the final entry, all persistent variables.
     //
-    AnimState get_final_persistent() const;
+    AnimStepEditor get_final_persistent() const;
 
     // Get the final entry, everything persistent and non-persistent.
     //
-    AnimState get_final_everything() const;
+    AnimStepEditor get_final_everything() const;
     
     // Get a serialized representation of the animation queue.
     //