Finish and document particle public API

Added factories to create particle binding objects, which were the only
piece that couldn't be generated programmatically.

Commented most of the things that a user needs to know to create an
effect from within code. (Except for all the details of SkSL).

Change-Id: I4003e536e46c77e0c1c9e83486cf99f0c2cf54d1
Reviewed-on: https://skia-review.googlesource.com/c/skia/+/230120
Reviewed-by: Ethan Nicholas <ethannicholas@google.com>
Commit-Queue: Brian Osman <brianosman@google.com>

modules/particles/include/SkParticleEffect.h

@@ -19,6 +19,8 @@
 #include <memory>
 
 class SkCanvas;
+struct SkCurve;
+struct SkColorCurve;
 class SkParticleDrawable;
 class SkParticleExternalValue;
 
@@ -38,6 +40,26 @@ public:
 
     static void RegisterBindingTypes();
 
+    /*
+     * All SkParticleBinding objects expose a particular native object to an effect's SkSL code.
+     * In all cases, the 'name' is the symbol that will be used to access the object from the SkSL.
+     * Each binding is a callable object, so the SkSL name behaves like a function. The behavior of
+     * each kind of binding is described below.
+     */
+
+    // Binds an SkCurve to an effect's SkSL. The curve is a one-dimensional function, described
+    // in SkCurve.h. It is called in the SkSL as 'name(t)', and returns a single float value.
+    static sk_sp<SkParticleBinding> MakeCurve(const char* name, const SkCurve& curve);
+
+    // Binds an SkColorCurve to an effect's SkSL. The curve is a one-dimensional, function,
+    // described in SkCurve.h. It is called in the SkSL as 'name(t)', and returns a float4 value.
+    static sk_sp<SkParticleBinding> MakeColorCurve(const char* name, const SkColorCurve& curve);
+
+    // Binds an SkPath to an effect's SkSL. The path is specified using SVG syntax. It is called
+    // in the SkSL as 'name(t)'. 't' is a normalized distance along the path. This returns a float4
+    // value, containing the position in .xy, and the normal in .zw.
+    static sk_sp<SkParticleBinding> MakePathBinding(const char* name, const char* path);
+
 protected:
     SkString fName;
 };
@@ -46,16 +68,50 @@ class SkParticleEffectParams : public SkRefCnt {
 public:
     SkParticleEffectParams();
 
-    int       fMaxCount;
-    float     fEffectDuration;
-    float     fRate;
+    int   fMaxCount;        // Maximum number of particles per instance of the effect
+    float fEffectDuration;  // How long does the effect last after being played, in seconds?
+    float fRate;            // How many particles are emitted per second?
 
-    // Drawable (image, sprite sheet, etc.)
+    // What is drawn for each particle? (Image, shape, sprite sheet, etc.)
+    // See SkParticleDrawable::Make*
     sk_sp<SkParticleDrawable> fDrawable;
 
-    // Code with spawn() and update() functions
+    // Particle behavior is driven by two SkSL functions defined in the fCode string.
+    // Both functions get a mutable Particle struct:
+    //
+    // struct Particle {
+    //   float  age;
+    //   float  lifetime;
+    //   float2 pos   = { 0, 0 };        // Local position, relative to the effect.
+    //   float2 dir   = { 0, -1 };       // Heading. Should be a normalized vector.
+    //   float  scale = 1;               // Size, normalized relative to the drawable's native size
+    //   float2 vel   = { 0, 0 };        // Linear velocity, in (units / second)
+    //   float  spin  = 0;               // Angular velocity, in (radians / second)
+    //   float4 color = { 1, 1, 1, 1 };  // RGBA color
+    //   float  frame = 0;               // Normalized sprite index for multi-frame drawables
+    // };
+    //
+    // In addition, both functions have access to a global variable named 'rand'. Every read of
+    // 'rand' returns a random floating point value in [0, 1). The random generator is stored
+    // per-particle, and the state is rewound after each update, so calls to 'rand' will return
+    // consistent values from one update to the next.
+    //
+    // Finally, there are two global uniform values available. The first is 'dt', a floating point
+    // number of seconds that have elapsed since the last update. The second is 'effectAge', which
+    // is the normalized age of the effect (not particle). For looping effects, this will wrap
+    // back to zero when the effect's age exceeds its duration.
+    //
+    // 'void spawn(inout Particle p)' is called once for each particle when it is first created,
+    // to set initial values. At a minimum, this should set 'lifetime' to the number of seconds
+    // that the particle will exist. Other parameters have defaults shown above.
+    //
+    // 'void update(inout Particle p)' is called for each particle on every call to the running
+    // SkParticleEffect's update() method. It can animate any of the particle's values. Note that
+    // the 'lifetime' field has a different meaning in 'update', and should not be used or changed.
     SkString fCode;
 
+    // External objects accessible by the effect's SkSL code. Each binding is a name and particular
+    // kind of object. See SkParticleBinding::Make* for details.
     SkTArray<sk_sp<SkParticleBinding>> fBindings;
 
     void visitFields(SkFieldVisitor* v);

modules/particles/src/SkParticleEffect.cpp

@@ -139,9 +139,15 @@ struct SkPathContours {
     SkScalar fTotalLength;
     SkTArray<sk_sp<SkContourMeasure>> fContours;
 
-    void reset() {
+    void rebuild(const SkPath& path) {
         fTotalLength = 0;
         fContours.reset();
+
+        SkContourMeasureIter iter(path, false);
+        while (auto contour = iter.next()) {
+            fContours.push_back(contour);
+            fTotalLength += contour->length();
+        }
     }
 };
 
@@ -206,18 +212,11 @@ public:
 
 private:
     SkString fPath;
+
     void rebuild() {
         SkPath path;
-        if (!SkParsePath::FromSVGString(fPath.c_str(), &path)) {
-            return;
-        }
-
-        fContours.reset();
-
-        SkContourMeasureIter iter(path, false);
-        while (auto contour = iter.next()) {
-            fContours.fContours.push_back(contour);
-            fContours.fTotalLength += contour->length();
+        if (SkParsePath::FromSVGString(fPath.c_str(), &path)) {
+            fContours.rebuild(path);
         }
     }
 
@@ -257,27 +256,35 @@ public:
 private:
     SkString fText;
     SkScalar fFontSize;
+
     void rebuild() {
         if (fText.isEmpty()) {
             return;
         }
 
-        fContours.reset();
-
         SkFont font(nullptr, fFontSize);
         SkPath path;
         SkTextUtils::GetPath(fText.c_str(), fText.size(), SkTextEncoding::kUTF8, 0, 0, font, &path);
-        SkContourMeasureIter iter(path, false);
-        while (auto contour = iter.next()) {
-            fContours.fContours.push_back(contour);
-            fContours.fTotalLength += contour->length();
-        }
+        fContours.rebuild(path);
     }
 
     // Cached
     SkPathContours fContours;
 };
 
+sk_sp<SkParticleBinding> SkParticleBinding::MakeCurve(const char* name, const SkCurve& curve) {
+    return sk_sp<SkParticleBinding>(new SkCurveBinding(name, curve));
+}
+
+sk_sp<SkParticleBinding> SkParticleBinding::MakeColorCurve(const char* name,
+                                                           const SkColorCurve& curve) {
+    return sk_sp<SkParticleBinding>(new SkColorCurveBinding(name, curve));
+}
+
+sk_sp<SkParticleBinding> SkParticleBinding::MakePathBinding(const char* name, const char* path) {
+    return sk_sp<SkParticleBinding>(new SkPathBinding(name, path));
+}
+
 void SkParticleBinding::RegisterBindingTypes() {
     REGISTER_REFLECTED(SkParticleBinding);
     REGISTER_REFLECTED(SkCurveBinding);