dom/svg/SVGPathData.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef DOM_SVG_SVGPATHDATA_H_
   8 #define DOM_SVG_SVGPATHDATA_H_
   9
  10 #include "nsCOMPtr.h"
  11 #include "nsDebug.h"
  12 #include "nsIContent.h"
  13 #include "nsINode.h"
  14 #include "nsIWeakReferenceUtils.h"
  15 #include "mozilla/dom/SVGElement.h"
  16 #include "mozilla/gfx/2D.h"
  17 #include "mozilla/gfx/Types.h"
  18 #include "mozilla/MemoryReporting.h"
  19 #include "mozilla/RefPtr.h"
  20 #include "nsTArray.h"
  21
  22 #include <string.h>
  23
  24 namespace mozilla {
  25
  26 struct StylePathCommand;
  27 struct SVGMark;
  28 enum class StyleStrokeLinecap : uint8_t;
  29
  30 class SVGPathDataParser;  // IWYU pragma: keep
  31
  32 namespace dom {
  33 class DOMSVGPathSeg;
  34 class DOMSVGPathSegList;
  35 }  // namespace dom
  36
  37 /**
  38  * ATTENTION! WARNING! WATCH OUT!!
  39  *
  40  * Consumers that modify objects of this type absolutely MUST keep the DOM
  41  * wrappers for those lists (if any) in sync!! That's why this class is so
  42  * locked down.
  43  *
  44  * The DOM wrapper class for this class is DOMSVGPathSegList.
  45  *
  46  * This class is not called |class SVGPathSegList| for one very good reason;
  47  * this class does not provide a list of "SVGPathSeg" items, it provides an
  48  * array of floats into which path segments are encoded. See the paragraphs
  49  * that follow for why. Note that the Length() method returns the number of
  50  * floats in our array, not the number of encoded segments, and the index
  51  * operator indexes floats in the array, not segments. If this class were
  52  * called SVGPathSegList the names of these methods would be very misleading.
  53  *
  54  * The reason this class is designed in this way is because there are many
  55  * different types of path segment, each taking a different numbers of
  56  * arguments. We want to store the segments in an nsTArray to avoid individual
  57  * allocations for each item, but the different size of segments means we can't
  58  * have one single segment type for the nsTArray (not without using a space
  59  * wasteful union or something similar). Since the internal code does not need
  60  * to index into the list (the DOM wrapper does, but it handles that itself)
  61  * the obvious solution is to have the items in this class take up variable
  62  * width and have the internal code iterate over these lists rather than index
  63  * into them.
  64  *
  65  * Implementing indexing to segments with O(1) performance would require us to
  66  * allocate and maintain a separate segment index table (keeping that table in
  67  * sync when items are inserted or removed from the list). So long as the
  68  * internal code doesn't require indexing to segments, we can avoid that
  69  * overhead and additional complexity.
  70  *
  71  * Segment encoding: the first float in the encoding of a segment contains the
  72  * segment's type. The segment's type is encoded to/decoded from this float
  73  * using the static methods SVGPathSegUtils::EncodeType(uint32_t)/
  74  * SVGPathSegUtils::DecodeType(float). If the path segment type in question
  75  * takes any arguments then these follow the first float, and are in the same
  76  * order as they are given in a <path> element's 'd' attribute (NOT in the
  77  * order of the createSVGPathSegXxx() methods' arguments from the SVG DOM
  78  * interface SVGPathElement, which are different...grr). Consumers can use
  79  * SVGPathSegUtils::ArgCountForType(type) to determine how many arguments
  80  * there are (if any), and thus where the current encoded segment ends, and
  81  * where the next segment (if any) begins.
  82  */
  83 class SVGPathData {
  84   friend class SVGAnimatedPathSegList;
  85   friend class dom::DOMSVGPathSeg;
  86   friend class dom::DOMSVGPathSegList;
  87   friend class SVGPathDataParser;
  88   // SVGPathDataParser will not keep wrappers in sync, so consumers
  89   // are responsible for that!
  90
  91   using DrawTarget = gfx::DrawTarget;
  92   using Path = gfx::Path;
  93   using PathBuilder = gfx::PathBuilder;
  94   using FillRule = gfx::FillRule;
  95   using Float = gfx::Float;
  96   using CapStyle = gfx::CapStyle;
  97
  98  public:
  99   using const_iterator = const float*;
 100
 101   SVGPathData() = default;
 102   ~SVGPathData() = default;
 103
 104   // Only methods that don't make/permit modification to this list are public.
 105   // Only our friend classes can access methods that may change us.
 106
 107   /// This may return an incomplete string on OOM, but that's acceptable.
 108   void GetValueAsString(nsAString& aValue) const;
 109
 110   bool IsEmpty() const { return mData.IsEmpty(); }
 111
 112 #ifdef DEBUG
 113   /**
 114    * This method iterates over the encoded segment data and counts the number
 115    * of segments we currently have.
 116    */
 117   uint32_t CountItems() const;
 118 #endif
 119
 120   /**
 121    * Returns the number of *floats* in the encoding array, and NOT the number
 122    * of segments encoded in this object. (For that, see CountItems() above.)
 123    */
 124   uint32_t Length() const { return mData.Length(); }
 125
 126   const float& operator[](uint32_t aIndex) const { return mData[aIndex]; }
 127
 128   // Used by SMILCompositor to check if the cached base val is out of date
 129   bool operator==(const SVGPathData& rhs) const {
 130     // We use memcmp so that we don't need to worry that the data encoded in
 131     // the first float may have the same bit pattern as a NaN.
 132     return mData.Length() == rhs.mData.Length() &&
 133            memcmp(mData.Elements(), rhs.mData.Elements(),
 134                   mData.Length() * sizeof(float)) == 0;
 135   }
 136
 137   bool SetCapacity(uint32_t aSize) {
 138     return mData.SetCapacity(aSize, fallible);
 139   }
 140
 141   void Compact() { mData.Compact(); }
 142
 143   float GetPathLength() const;
 144
 145   uint32_t GetPathSegAtLength(float aDistance) const;
 146
 147   void GetMarkerPositioningData(nsTArray<SVGMark>* aMarks) const;
 148
 149   /**
 150    * Returns true, except on OOM, in which case returns false.
 151    */
 152   bool GetDistancesFromOriginToEndsOfVisibleSegments(
 153       FallibleTArray<double>* aOutput) const;
 154
 155   /**
 156    * This returns a path without the extra little line segments that
 157    * ApproximateZeroLengthSubpathSquareCaps can insert if we have square-caps.
 158    * See the comment for that function for more info on that.
 159    */
 160   already_AddRefed<Path> BuildPathForMeasuring() const;
 161
 162   already_AddRefed<Path> BuildPath(PathBuilder* aBuilder,
 163                                    StyleStrokeLinecap aStrokeLineCap,
 164                                    Float aStrokeWidth) const;
 165   /**
 166    * This function tries to build the path from an array of StylePathCommand,
 167    * which is generated by cbindgen from Rust (see ServoStyleConsts.h).
 168    * Basically, this is a variant of the above BuildPath() functions.
 169    */
 170   static already_AddRefed<Path> BuildPath(Span<const StylePathCommand> aPath,
 171                                           PathBuilder* aBuilder,
 172                                           StyleStrokeLinecap aStrokeLineCap,
 173                                           Float aStrokeWidth,
 174                                           float aZoomFactor = 1.0);
 175
 176   const_iterator begin() const { return mData.Elements(); }
 177   const_iterator end() const { return mData.Elements() + mData.Length(); }
 178
 179   // memory reporting methods
 180   size_t SizeOfExcludingThis(mozilla::MallocSizeOf aMallocSizeOf) const;
 181   size_t SizeOfIncludingThis(mozilla::MallocSizeOf aMallocSizeOf) const;
 182
 183   // Access to methods that can modify objects of this type is deliberately
 184   // limited. This is to reduce the chances of someone modifying objects of
 185   // this type without taking the necessary steps to keep DOM wrappers in sync.
 186   // If you need wider access to these methods, consider adding a method to
 187   // SVGAnimatedPathSegList and having that class act as an intermediary so it
 188   // can take care of keeping DOM wrappers in sync.
 189
 190  protected:
 191   using iterator = float*;
 192
 193   /**
 194    * This may fail on OOM if the internal capacity needs to be increased, in
 195    * which case the list will be left unmodified.
 196    */
 197   nsresult CopyFrom(const SVGPathData& rhs);
 198
 199   float& operator[](uint32_t aIndex) { return mData[aIndex]; }
 200
 201   /**
 202    * This may fail (return false) on OOM if the internal capacity is being
 203    * increased, in which case the list will be left unmodified.
 204    */
 205   bool SetLength(uint32_t aLength) {
 206     return mData.SetLength(aLength, fallible);
 207   }
 208
 209   nsresult SetValueFromString(const nsAString& aValue);
 210
 211   void Clear() { mData.Clear(); }
 212
 213   // Our DOM wrappers have direct access to our mData, so they directly
 214   // manipulate it rather than us implementing:
 215   //
 216   // * InsertItem(uint32_t aDataIndex, uint32_t aType, const float *aArgs);
 217   // * ReplaceItem(uint32_t aDataIndex, uint32_t aType, const float *aArgs);
 218   // * RemoveItem(uint32_t aDataIndex);
 219   // * bool AppendItem(uint32_t aType, const float *aArgs);
 220
 221   nsresult AppendSeg(uint32_t aType, ...);  // variable number of float args
 222
 223   iterator begin() { return mData.Elements(); }
 224   iterator end() { return mData.Elements() + mData.Length(); }
 225
 226   FallibleTArray<float> mData;
 227 };
 228
 229 /**
 230  * This SVGPathData subclass is for SVGPathSegListSMILType which needs to
 231  * have write access to the lists it works with.
 232  *
 233  * Instances of this class do not have DOM wrappers that need to be kept in
 234  * sync, so we can safely expose any protected base class methods required by
 235  * the SMIL code.
 236  */
 237 class SVGPathDataAndInfo final : public SVGPathData {
 238  public:
 239   explicit SVGPathDataAndInfo(dom::SVGElement* aElement = nullptr)
 240       : mElement(do_GetWeakReference(static_cast<nsINode*>(aElement))) {}
 241
 242   void SetElement(dom::SVGElement* aElement) {
 243     mElement = do_GetWeakReference(static_cast<nsINode*>(aElement));
 244   }
 245
 246   dom::SVGElement* Element() const {
 247     nsCOMPtr<nsIContent> e = do_QueryReferent(mElement);
 248     return static_cast<dom::SVGElement*>(e.get());
 249   }
 250
 251   nsresult CopyFrom(const SVGPathDataAndInfo& rhs) {
 252     mElement = rhs.mElement;
 253     return SVGPathData::CopyFrom(rhs);
 254   }
 255
 256   /**
 257    * Returns true if this object is an "identity" value, from the perspective
 258    * of SMIL. In other words, returns true until the initial value set up in
 259    * SVGPathSegListSMILType::Init() has been changed with a SetElement() call.
 260    */
 261   bool IsIdentity() const {
 262     if (!mElement) {
 263       MOZ_ASSERT(IsEmpty(), "target element propagation failure");
 264       return true;
 265     }
 266     return false;
 267   }
 268
 269   /**
 270    * Exposed so that SVGPathData baseVals can be copied to
 271    * SVGPathDataAndInfo objects. Note that callers should also call
 272    * SetElement() when using this method!
 273    */
 274   using SVGPathData::CopyFrom;
 275
 276   // Exposed since SVGPathData objects can be modified.
 277   using SVGPathData::iterator;
 278   using SVGPathData::operator[];
 279   using SVGPathData::begin;
 280   using SVGPathData::end;
 281   using SVGPathData::SetLength;
 282
 283  private:
 284   // We must keep a weak reference to our element because we may belong to a
 285   // cached baseVal SMILValue. See the comments starting at:
 286   // https://bugzilla.mozilla.org/show_bug.cgi?id=515116#c15
 287   // See also https://bugzilla.mozilla.org/show_bug.cgi?id=653497
 288   nsWeakPtr mElement;
 289 };
 290
 291 }  // namespace mozilla
 292
 293 #endif  // DOM_SVG_SVGPATHDATA_H_