Implement cancelValuesAndHoldAtTime

third_party/WebKit/Source/modules/webaudio/AudioParamTimeline.h

 /*
  * Copyright (C) 2011 Google Inc. All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
  * are met:
  *
  * 1.  Redistributions of source code must retain the above copyright
  *     notice, this list of conditions and the following disclaimer.
  * 2.  Redistributions in binary form must reproduce the above copyright
@@ skipping 46 matching lines @@
                                     ExceptionState&);
   void setTargetAtTime(float target,
                        double time,
                        double timeConstant,
                        ExceptionState&);
   void setValueCurveAtTime(DOMFloat32Array* curve,
                            double time,
                            double duration,
                            ExceptionState&);
   void cancelScheduledValues(double startTime, ExceptionState&);
+  void cancelValuesAndHoldAtTime(double cancelTime, ExceptionState&);
 
   // hasValue is set to true if a valid timeline value is returned.
   // otherwise defaultValue is returned.
   float valueForContextTime(AudioDestinationHandler&,
                             float defaultValue,
                             bool& hasValue,
                             float minValue,
                             float maxValue);
 
   // Given the time range in frames, calculates parameter values into the values
@@ skipping 21 matching lines @@
 
  private:
   class ParamEvent {
    public:
     enum Type {
       SetValue,
       LinearRampToValue,
       ExponentialRampToValue,
       SetTarget,
       SetValueCurve,
+      // This type is not exposed to Javascript. It's meant to handle the
+      // cancelValuesAndHoldAtTime() API.

[hongchan, 2016/12/22 18:41:37]

Just a thought: how about renaming this variable to 'CancelValuesInternal'?

[Raymond Toy, 2016/12/22 19:06:23]

Actually, the comment is kind of wrong. None of these are actually exposed to
Javascript.  So internal or external doesn't really mean anything.

+      CancelValues,
       LastType
     };
 
-    static ParamEvent createLinearRampEvent(float value,
-                                            double time,
-                                            float initialValue,
-                                            double callTime);
-    static ParamEvent createExponentialRampEvent(float value,
-                                                 double time,
-                                                 float initialValue,
-                                                 double callTime);
-    static ParamEvent createSetValueEvent(float value, double time);
-    static ParamEvent createSetTargetEvent(float value,
-                                           double time,
-                                           double timeConstant);
-    static ParamEvent createSetValueCurveEvent(const DOMFloat32Array* curve,
-                                               double time,
-                                               double duration);
+    static std::unique_ptr<ParamEvent> createLinearRampEvent(float value,
+                                                             double time,
+                                                             float initialValue,
+                                                             double callTime);
+    static std::unique_ptr<ParamEvent> createExponentialRampEvent(
+        float value,
+        double time,
+        float initialValue,
+        double callTime);
+    static std::unique_ptr<ParamEvent> createSetValueEvent(float value,
+                                                           double time);
+    static std::unique_ptr<ParamEvent>
+    createSetTargetEvent(float value, double time, double timeConstant);
+    static std::unique_ptr<ParamEvent> createSetValueCurveEvent(
+        const DOMFloat32Array* curve,
+        double time,
+        double duration);
+    static std::unique_ptr<ParamEvent> createCancelValuesEvent(
+        double time,
+        std::unique_ptr<ParamEvent> savedEvent);
+    static std::unique_ptr<ParamEvent> createGeneralEvent(

[hongchan, 2016/12/22 18:41:37]

Can we have a comment why this method is needed? Perhaps the adjective 'Base' or
'Abstract' is better than 'General'?

[Raymond Toy, 2016/12/22 19:06:23]

It's needed to create a saved event (which is basically a copy of the event). 
Not sure how this would be "Abstract", since it's a real event, and there's now
"Base" event.  There's just the ParamEvent.

+        Type,
+        float value,
+        double time,
+        float initialValue,
+        double callTime,
+        double timeConstant,
+        double duration,
+        Vector<float>& curve,
+        double curvePointsPerSecond,
+        float curveEndValue,
+        std::unique_ptr<ParamEvent> savedEvent);
 
     Type getType() const { return m_type; }
     float value() const { return m_value; }
     double time() const { return m_time; }
     void setTime(double newTime) { m_time = newTime; }
     double timeConstant() const { return m_timeConstant; }
     double duration() const { return m_duration; }
     Vector<float>& curve() { return m_curve; }
     float initialValue() const { return m_initialValue; }
     double callTime() const { return m_callTime; }
     bool needsTimeClampCheck() const { return m_needsTimeClampCheck; }
     void clearTimeClampCheck() { m_needsTimeClampCheck = false; }
 
+    double curvePointsPerSecond() const { return m_curvePointsPerSecond; }
+    float curveEndValue() const { return m_curveEndValue; }
+
+    // For CancelValues events. Not valid for any other event

[hongchan, 2016/12/22 18:41:37]

nit: a missing period. Also there is a couple of missing periods in the comments
below.

[Raymond Toy, 2016/12/22 19:21:34]

Done.

+    ParamEvent* savedEvent() const;
+    bool hasDefaultCancelledValue() const;
+    void setCancelledValue(float);
+
    private:
+    // General event
     ParamEvent(Type type,
                float value,
                double time,
+               float initialValue,
+               double callTime,
                double timeConstant,
                double duration,
+               Vector<float>& curve,
+               double curvePointsPerSecond,
+               float curveEndValue,
+               std::unique_ptr<ParamEvent> savedEvent);
+
+    // Create simplest event needing just a value and time, like setValueAtTime

[hongchan, 2016/12/22 18:41:37]

nit: a missing period.

[Raymond Toy, 2016/12/22 19:21:34]

Done.

+    ParamEvent(Type, float value, double time);
+
+    // Create a linear or exponential ramp that requires an initial value and
+    // time in case

[hongchan, 2016/12/22 18:41:37]

nit: the line breaks at the wrong position?

[Raymond Toy, 2016/12/22 19:21:34]

Done.

+    // there is no actual event that preceeds this event.
+    ParamEvent(Type,
+               float value,
+               double time,
+               float initialValue,
+               double callTime);
+
+    // Create an event needing a time constant (setTargetAtTime)
+    ParamEvent(Type, float value, double time, double timeConstant);
+
+    // Create a setValueCurve event
+    ParamEvent(Type,
+               double time,
+               double duration,
                const DOMFloat32Array* curve,
-               float initialValue = 0,
-               double callTime = 0);
+               double curvePointsPerSecond,
+               float curveEndValue);
+
+    // Create CancelValues event
+    ParamEvent(Type, double time, std::unique_ptr<ParamEvent> savedEvent);
 
     Type m_type;
+
+    // The value for the event.  The interpretation of this depends on
+    // the event type. Not used for SetValueCurve. For CancelValues,
+    // it is the end value to use when cancelling a LinearRampToValue
+    // or ExponentialRampToValue event.
     float m_value;
+
+    // The time for the event. The interpretation of this depends on
+    // the event type.
     double m_time;
-    // Only used for SetTarget events
-    double m_timeConstant;
-    // Only used for SetValueCurve events.
-    double m_duration;
-    Vector<float> m_curve;
+
     // Initial value and time to use for linear and exponential ramps that don't
     // have a preceding event.
     float m_initialValue;
     double m_callTime;
+
+    // Only used for SetTarget events
+    double m_timeConstant;
+
+    // The following items are only used for SetValueCurve events

[hongchan, 2016/12/22 18:41:37]

nit: perhaps a colon at the end?

+    //
+    //   m_duration is the duration of the curve.
+    //   m_curve is the array of curve poitns.
+    //   m_curvePointsPerSecond is the number of curve points per second. it
+    //     is used to compute the curve index step when running the
+    //     automation.
+    //   m_curveEndValue is the default value to use at the end of the
+    //     curve.  Normally it's the last entry in m_curve, but cancelling a
+    //     SetValueCurve will set this to a new value.  // Only used for
+    //     SetValueCurve events.

[hongchan, 2016/12/22 18:41:37]

These comments should be located just above each variable. I think that's our
convention. No?

[Raymond Toy, 2016/12/22 19:21:34]

Done.

+    double m_duration;
+    Vector<float> m_curve;
+    double m_curvePointsPerSecond;
+    float m_curveEndValue;
+
+    // For CancelValues. If CancelValues is in the middle of an event, this
+    // holds the event that is being cancelled, so that processing can
+    // continue as if the event still existed up until we reach the actual
+    // scheduled cancel time.
+    std::unique_ptr<ParamEvent> m_savedEvent;
+
     // True if the start time needs to be checked against current time
     // to implement clamping.
     bool m_needsTimeClampCheck;
+
+    // True if a default value has been assigned to the CancelValues event.
+    bool m_hasDefaultCancelledValue;
   };
 
-  void insertEvent(const ParamEvent&, ExceptionState&);
+  void insertEvent(std::unique_ptr<ParamEvent>, ExceptionState&);
   float valuesForFrameRangeImpl(size_t startFrame,
                                 size_t endFrame,
                                 float defaultValue,
                                 float* values,
                                 unsigned numberOfValues,
                                 double sampleRate,
                                 double controlRate);
 
   // Produce a nice string describing the event in human-readable form.
   String eventToString(const ParamEvent&);
-  Vector<ParamEvent> m_events;
+
+  // Automation functions that compute the vlaue of the specified
+  // automation at the specified time.
+  float linearRampAtTime(double t,
+                         float value1,
+                         double time1,
+                         float value2,
+                         double time2);
+  float exponentialRampAtTime(double t,
+                              float value1,
+                              double time1,
+                              float value2,
+                              double time2);
+  float targetValueAtTime(double t,
+                          float value1,
+                          double time1,
+                          float value2,
+                          float timeConstant);
+  float valueCurveAtTime(double t,
+                         double time1,
+                         double duration,
+                         const float* curveData,
+                         unsigned curveLength);
+
+  // Vector of all automation events for the AudioParam.  Access must
+  // be locked via m_eventsLock.
+  Vector<std::unique_ptr<ParamEvent>> m_events;
 
   mutable Mutex m_eventsLock;
 
   // Smoothing (de-zippering)
   float m_smoothedValue;
 };
 
 }  // namespace blink
 
 #endif  // AudioParamTimeline_h