juce_Path.h

Go to the documentation of this file.

/*
  ==============================================================================
 
   This file is part of the JUCE library.
   Copyright (c) 2022 - Raw Material Software Limited
 
   JUCE is an open source library subject to commercial or open-source
   licensing.
 
   By using JUCE, you agree to the terms of both the JUCE 7 End-User License
   Agreement and JUCE Privacy Policy.
 
   End User License Agreement: www.juce.com/juce-7-licence
   Privacy Policy: www.juce.com/juce-privacy-policy
 
   Or: You may also use this code under the terms of the GPL v3 (see
   www.gnu.org/licenses).
 
   JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
   EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
   DISCLAIMED.
 
  ==============================================================================
*/
 
namespace juce
{
 
//==============================================================================
class JUCE_API  Path  final
{
public:
    //==============================================================================
    Path();

    Path (const Path&);

    ~Path();

    Path& operator= (const Path&);

    Path (Path&&) noexcept;

    Path& operator= (Path&&) noexcept;
 
    bool operator== (const Path&) const noexcept;
    bool operator!= (const Path&) const noexcept;
 
    static const float defaultToleranceForTesting;
    static const float defaultToleranceForMeasurement;
 
    //==============================================================================
    bool isEmpty() const noexcept;

    Rectangle<float> getBounds() const noexcept;

    Rectangle<float> getBoundsTransformed (const AffineTransform& transform) const noexcept;

    bool contains (float x, float y,
                   float tolerance = defaultToleranceForTesting) const;

    bool contains (Point<float> point,
                   float tolerance = defaultToleranceForTesting) const;

    bool intersectsLine (Line<float> line,
                         float tolerance = defaultToleranceForTesting) const;

    Line<float> getClippedLine (Line<float> line, bool keepSectionOutsidePath) const;

    float getLength (const AffineTransform& transform = AffineTransform(),
                     float tolerance = defaultToleranceForMeasurement) const;

    Point<float> getPointAlongPath (float distanceFromStart,
                                    const AffineTransform& transform = AffineTransform(),
                                    float tolerance = defaultToleranceForMeasurement) const;

    float getNearestPoint (Point<float> targetPoint,
                           Point<float>& pointOnPath,
                           const AffineTransform& transform = AffineTransform(),
                           float tolerance = defaultToleranceForMeasurement) const;
 
    //==============================================================================
    void clear() noexcept;

    void startNewSubPath (float startX, float startY);

    void startNewSubPath (Point<float> start);

    void closeSubPath();

    void lineTo (float endX, float endY);

    void lineTo (Point<float> end);

    void quadraticTo (float controlPointX,
                      float controlPointY,
                      float endPointX,
                      float endPointY);

    void quadraticTo (Point<float> controlPoint,
                      Point<float> endPoint);

    void cubicTo (float controlPoint1X,
                  float controlPoint1Y,
                  float controlPoint2X,
                  float controlPoint2Y,
                  float endPointX,
                  float endPointY);

    void cubicTo (Point<float> controlPoint1,
                  Point<float> controlPoint2,
                  Point<float> endPoint);

    Point<float> getCurrentPosition() const;
 
    //==============================================================================
    void addRectangle (float x, float y, float width, float height);

    template <typename ValueType>
    void addRectangle (Rectangle<ValueType> rectangle)
    {
        addRectangle (static_cast<float> (rectangle.getX()), static_cast<float> (rectangle.getY()),
                      static_cast<float> (rectangle.getWidth()), static_cast<float> (rectangle.getHeight()));
    }

    void addRoundedRectangle (float x, float y, float width, float height,
                              float cornerSize);

    void addRoundedRectangle (float x, float y, float width, float height,
                              float cornerSizeX,
                              float cornerSizeY);

    void addRoundedRectangle (float x, float y, float width, float height,
                              float cornerSizeX, float cornerSizeY,
                              bool curveTopLeft, bool curveTopRight,
                              bool curveBottomLeft, bool curveBottomRight);

    template <typename ValueType>
    void addRoundedRectangle (Rectangle<ValueType> rectangle, float cornerSizeX, float cornerSizeY)
    {
        addRoundedRectangle (static_cast<float> (rectangle.getX()), static_cast<float> (rectangle.getY()),
                             static_cast<float> (rectangle.getWidth()), static_cast<float> (rectangle.getHeight()),
                             cornerSizeX, cornerSizeY);
    }

    template <typename ValueType>
    void addRoundedRectangle (Rectangle<ValueType> rectangle, float cornerSize)
    {
        addRoundedRectangle (rectangle, cornerSize, cornerSize);
    }

    void addTriangle (float x1, float y1,
                      float x2, float y2,
                      float x3, float y3);

    void addTriangle (Point<float> point1,
                      Point<float> point2,
                      Point<float> point3);

    void addQuadrilateral (float x1, float y1,
                           float x2, float y2,
                           float x3, float y3,
                           float x4, float y4);

    void addEllipse (float x, float y, float width, float height);

    void addEllipse (Rectangle<float> area);

    void addArc (float x, float y, float width, float height,
                 float fromRadians,
                 float toRadians,
                 bool startAsNewSubPath = false);

    void addCentredArc (float centreX, float centreY,
                        float radiusX, float radiusY,
                        float rotationOfEllipse,
                        float fromRadians,
                        float toRadians,
                        bool startAsNewSubPath = false);

    void addPieSegment (float x, float y,
                        float width, float height,
                        float fromRadians,
                        float toRadians,
                        float innerCircleProportionalSize);

    void addPieSegment (Rectangle<float> segmentBounds,
                        float fromRadians,
                        float toRadians,
                        float innerCircleProportionalSize);

    void addLineSegment (Line<float> line, float lineThickness);

    void addArrow (Line<float> line,
                   float lineThickness,
                   float arrowheadWidth,
                   float arrowheadLength);

    void addPolygon (Point<float> centre,
                     int numberOfSides,
                     float radius,
                     float startAngle = 0.0f);

    void addStar (Point<float> centre,
                  int numberOfPoints,
                  float innerRadius,
                  float outerRadius,
                  float startAngle = 0.0f);

    void addBubble (Rectangle<float> bodyArea,
                    Rectangle<float> maximumArea,
                    const Point<float> arrowTipPosition,
                    const float cornerSize,
                    const float arrowBaseWidth);

    void addPath (const Path& pathToAppend);

    void addPath (const Path& pathToAppend,
                  const AffineTransform& transformToApply);

    void swapWithPath (Path&) noexcept;
 
    //==============================================================================
    void preallocateSpace (int numExtraCoordsToMakeSpaceFor);
 
    //==============================================================================
    void applyTransform (const AffineTransform& transform) noexcept;

    void scaleToFit (float x, float y, float width, float height,
                     bool preserveProportions) noexcept;

    AffineTransform getTransformToScaleToFit (float x, float y, float width, float height,
                                              bool preserveProportions,
                                              Justification justificationType = Justification::centred) const;

    AffineTransform getTransformToScaleToFit (Rectangle<float> area,
                                              bool preserveProportions,
                                              Justification justificationType = Justification::centred) const;

    Path createPathWithRoundedCorners (float cornerRadius) const;
 
    //==============================================================================
    void setUsingNonZeroWinding (bool isNonZeroWinding) noexcept;

    bool isUsingNonZeroWinding() const                  { return useNonZeroWinding; }
 
 
    //==============================================================================
    class JUCE_API  Iterator
    {
    public:
        //==============================================================================
        Iterator (const Path& path) noexcept;
        ~Iterator() noexcept;
 
        //==============================================================================
        bool next() noexcept;
 
        //==============================================================================
        enum PathElementType
        {
            startNewSubPath,    
            lineTo,             
            quadraticTo,        
            cubicTo,            
            closePath           
        };
 
        PathElementType elementType;
 
        float x1 = 0, y1 = 0, x2 = 0, y2 = 0, x3 = 0, y3 = 0;
 
        //==============================================================================
    private:
        const Path& path;
        const float* index;
 
        JUCE_DECLARE_NON_COPYABLE (Iterator)
    };
 
    //==============================================================================
    void loadPathFromStream (InputStream& source);

    void loadPathFromData (const void* data, size_t numberOfBytes);

    void writePathToStream (OutputStream& destination) const;
 
    //==============================================================================
    String toString() const;

    void restoreFromString (StringRef stringVersion);
 
private:
    //==============================================================================
    friend class PathFlatteningIterator;
    friend class Path::Iterator;
    friend class EdgeTable;
 
    Array<float> data;
 
    struct PathBounds
    {
        PathBounds() noexcept;
        Rectangle<float> getRectangle() const noexcept;
        void reset() noexcept;
        void reset (float, float) noexcept;
        void extend (float, float) noexcept;
 
        template <typename... Coords>
        void extend (float x, float y, Coords... coords) noexcept
        {
            extend (x, y);
            extend (coords...);
        }
 
        float pathXMin = 0, pathXMax = 0, pathYMin = 0, pathYMax = 0;
    };
 
    PathBounds bounds;
    bool useNonZeroWinding = true;
 
    static const float lineMarker;
    static const float moveMarker;
    static const float quadMarker;
    static const float cubicMarker;
    static const float closeSubPathMarker;
 
    JUCE_LEAK_DETECTOR (Path)
};
 
} // namespace juce