Merge pull request #229 from parasol-framework/test/animation

Improve animation support

docs/xml/modules/classes/metaclass.xml

@@ -222,6 +222,17 @@
       <type>STRING</type>
     </field>
 
+    <field>
+      <name>Objects</name>
+      <comment>Returns an allocated list of all objects that belong to this class.</comment>
+      <access read="G">Get</access>
+      <type>LONG []</type>
+      <description>
+<p>This field will compile a list of all objects that belong to the class.  The list is sorted with the oldest object appearing first.</p>
+<p>The resulting array must be terminated with <function module="Core">FreeResource</function> after use.</p>
+      </description>
+    </field>
+
     <field>
       <name>OpenCount</name>
       <comment>The total number of active objects that are linked back to the MetaClass.</comment>
@@ -242,17 +253,6 @@
       </description>
     </field>
 
-    <field>
-      <name>PrivateObjects</name>
-      <comment>Returns an allocated list of all objects that belong to this class.</comment>
-      <access read="G">Get</access>
-      <type>LONG []</type>
-      <description>
-<p>This field will compile a list of all objects that belong to the class.  The list is sorted with the oldest object appearing first.</p>
-<p>The resulting array must be terminated with <function module="Core">FreeResource</function> after use.</p>
-      </description>
-    </field>
-
     <field>
       <name>RootModule</name>
       <comment>Returns a direct reference to the RootModule object that hosts the class.</comment>

docs/xml/modules/classes/vector.xml

@@ -245,9 +245,11 @@
     <method>
       <name>TracePath</name>
       <comment>Returns the coordinates for a vector path, using callbacks.</comment>
-      <prototype>ERR vecTracePath(OBJECTPTR Object, FUNCTION * Callback)</prototype>
+      <prototype>ERR vecTracePath(OBJECTPTR Object, FUNCTION * Callback, DOUBLE Scale, LONG Transform)</prototype>
       <input>
         <param type="FUNCTION *" name="Callback">The function to call with each coordinate of the path.</param>
+        <param type="DOUBLE" name="Scale">Set to 1.0 (recommended) to trace the path at a scale of 1 to 1.</param>
+        <param type="LONG" name="Transform">Set to TRUE if all transforms applicable to the vector should be applied to the path.</param>
       </input>
       <description>
 <p>Any vector that generates a path can be traced by calling this method.  Tracing allows the caller to follow the path for each pixel that would be drawn if the path were to be rendered with a stroke size of 1.  The prototype of the callback function is <code>ERR Function(OBJECTPTR Vector, LONG Index, LONG Command, DOUBLE X, DOUBLE Y, APTR Meta)</code>.</p>
@@ -256,6 +258,7 @@
       </description>
       <result>
         <error code="Okay">Operation successful.</error>
+        <error code="NoData">The vector does not define a path.</error>
         <error code="NullArgs">Function call missing argument value(s)</error>
       </result>
     </method>
@@ -563,6 +566,16 @@
       </description>
     </field>
 
+    <field>
+      <name>PathTimestamp</name>
+      <comment>This counter is modified each time the path is regenerated.</comment>
+      <access read="R">Read</access>
+      <type>INT</type>
+      <description>
+<p>The PathTimestamp can be used as a basic means of recording the state of the vector's path, and checking that state for changes at a later time.  For more active monitoring and response, clients should subscribe to the <code>PATH_CHANGED</code> event.</p>
+      </description>
+    </field>
+
     <field>
       <name>Prev</name>
       <comment>The previous vector in the branch, or NULL.</comment>

docs/xml/modules/core.xml

@@ -3449,10 +3449,11 @@ SetField(Object, FID_Statement|TSTR, "string");
       <field name="Type" type="ULONG">Type of the field</field>
     </struct>
 
-    <struct name="HSV" comment="Colour structure for Hue, Saturation and Value components.">
+    <struct name="HSV" comment="Colour structure for Hue, Saturation and Value/Light components.">
       <field name="Hue" type="DOUBLE">Between 0 and 359.999</field>
       <field name="Saturation" type="DOUBLE">Between 0 and 1.0</field>
       <field name="Value" type="DOUBLE">Between 0 and 1.0.  Corresponds to Value, Lightness or Brightness</field>
+      <field name="Alpha" type="DOUBLE">Alpha blending value from 0 to 1.0.</field>
     </struct>
 
     <struct name="InputEvent">

include/parasol/main.h

@@ -63,18 +63,18 @@ class ScopedAccessMemory { // C++ wrapper for automatically releasing shared mem
 // Defer() function for calling lambdas at end-of-scope
 
 template <typename FUNC> struct deferred_call {
-   deferred_call(const deferred_call& that) = delete;
-   deferred_call& operator=(const deferred_call& that) = delete;
-   deferred_call(deferred_call&& that) = delete;
-   deferred_call(FUNC&& f) : func(std::forward<FUNC>(f)) { }
+   deferred_call(const deferred_call &that) = delete;
+   deferred_call & operator = (const deferred_call &that) = delete;
+   deferred_call(deferred_call &&that) = delete;
+   deferred_call(FUNC &&f) : func(std::forward<FUNC>(f)) { }
 
    ~deferred_call() { func(); }
 
 private:
    FUNC func;
 };
 
-template <typename F> deferred_call<F> Defer(F&& f) {
+template <typename F> deferred_call<F> Defer(F &&f) {
    return deferred_call<F>(std::forward<F>(f));
 }
 
@@ -128,7 +128,7 @@ class ScopedObjectLock { // C++ wrapper for automatically releasing an object
 
 //********************************************************************************************************************
 // Resource guard for any allocation that can be freed with FreeResource().  Retains the resource ID rather than the
-// pointer to ensure that termination is safe even if the original resource gets terminated elsewhere.
+// pointer to ensure that termination is safe, even if the original resource gets terminated elsewhere.
 //
 // Usage: pf::GuardedResource resource(thing)
 
@@ -145,13 +145,14 @@ class GuardedResource {
 };
 
 //********************************************************************************************************************
-// The object equivalent of GuardedResource.  Also guarantees safety for object termination.
+// The object equivalent of GuardedResource.  Also guarantees safety for object termination.  The use of
+// GuardedObject is considered essential for interoperability with the C++ class destruction model.
 
 template <class T = BaseClass, class C = std::atomic_int>
 class GuardedObject {
    private:
       C * count;  // Count of GuardedObjects accessing the same resource.  Can be LONG (non-threaded) or std::atomic_int
-      T * object;
+      T * object; // Pointer to the Parasol object being guarded.  Use '*' or '->' operators to access.
 
    public:
       OBJECTID id; // Object UID
@@ -234,7 +235,7 @@ class GuardedObject {
          else { pf::Log log(__FUNCTION__); log.warning(ERR::InUse); }
       }
 
-      constexpr bool empty() { return !object; }
+      constexpr bool empty() { return !object; } // Returns true if no object is being guarded.
 
       T * operator->() { return object; }; // Promotes underlying methods and fields
       T * & operator*() { return object; }; // To allow object pointer referencing when calling functions

include/parasol/modules/core.h

@@ -1354,6 +1354,7 @@ struct HSV {
    DOUBLE Hue;           // Between 0 and 359.999
    DOUBLE Saturation;    // Between 0 and 1.0
    DOUBLE Value;         // Between 0 and 1.0.  Corresponds to Value, Lightness or Brightness
+   DOUBLE Alpha;         // Alpha blending value from 0 to 1.0.
 };
 
 struct FRGB {
@@ -2796,6 +2797,11 @@ struct BaseClass { // Must be 64-bit aligned
       return obj ? true : false;
    }
 
+   inline ERR setArray(ULONG FieldID, FLOAT *Value, LONG Size)  { return SetArray(this, (FIELD)FieldID|TFLOAT, Value, Size); }
+   inline ERR setArray(ULONG FieldID, DOUBLE *Value, LONG Size) { return SetArray(this, (FIELD)FieldID|TDOUBLE, Value, Size); }
+   inline ERR setArray(ULONG FieldID, LONG *Value, LONG Size)   { return SetArray(this, (FIELD)FieldID|TLONG, Value, Size); }
+   inline ERR setArray(ULONG FieldID, LARGE *Value, LONG Size)  { return SetArray(this, (FIELD)FieldID|TLARGE, Value, Size); }
+
    inline ERR set(ULONG FieldID, int Value)             { return SetField(this, (FIELD)FieldID|TLONG, Value); }
    inline ERR set(ULONG FieldID, unsigned int Value)    { return SetField(this, (FIELD)FieldID|TLONG, Value); }
    inline ERR set(ULONG FieldID, LARGE Value)           { return SetField(this, (FIELD)FieldID|TLARGE, Value); }
@@ -3359,7 +3365,7 @@ class objMetaClass : public BaseClass {
 
    template <class T> inline ERR setName(T && Value) noexcept {
       auto target = this;
-      auto field = &this->Class->Dictionary[9];
+      auto field = &this->Class->Dictionary[10];
       return field->WriteValue(target, field, 0x08810500, to_cstring(Value), 1);
    }