Restore support for using faster dotted pens in wxMSW

Changes of d245dc9e1f (Fix drawing of dotted lines with wxDC in wxMSW,
2020-03-27) improved the appearance of dotted and dashed lines in wxMSW
but at the expense of significant (up to a factor of 300) slowdown.

Allow the applications for which the drawing performance is important to
explicitly request the old behaviour, with uglier, but faster, pens by
choosing to use low quality pens.

Update the graphics benchmark to allow specifying the pen quality and
verify that the performance when using it is the same as before 3.1.4.

See https://github.com/wxWidgets/wxWidgets/pull/2218

See #7097.

Closes #18875.

interface/wx/pen.h

@@ -70,6 +70,31 @@ enum wxPenStyle
         /**< Last of the hatch styles (inclusive). */
 };
 
+/**
+    Possible values for pen quality.
+
+    Pen quality is currently only used in wxMSW, the other ports ignore it and
+    always use the same default pen quality.
+
+    In wxMSW the choice of quality affects whether "cosmetic" or "geometric"
+    native pens are used in situations when both are usable. Notably, for
+    dotted and dashed pens of width 1, high quality geometric pens are used by
+    default since wxWidgets 3.1.4, while previous versions used lower quality
+    but much faster cosmetic pens. If drawing performance is more important
+    than the exact appearance of the lines drawn using this pen, low quality
+    may be explicitly selected.
+
+    See wxPenInfo::Quality() and wxPen::SetQuality().
+
+    @since 3.1.5
+ */
+enum wxPenQuality
+{
+    wxPEN_QUALITY_DEFAULT,  ///< Select the appropriate quality automatically.
+    wxPEN_QUALITY_LOW,      ///< Less good looking but faster.
+    wxPEN_QUALITY_HIGH      ///< Best looking, at the expense of speed.
+};
+
 /**
     The possible join values of a wxPen.
 
@@ -138,11 +163,42 @@ public:
 
     wxPenInfo& Cap(wxPenCap cap);
 
+    /**
+        Set the pen quality.
+
+        Using LowQuality() or HighQuality() is usually more convenient.
+
+        @see wxPen::SetQuality()
+
+        @since 3.1.5
+     */
+    wxPenInfo& Quality(wxPenQuality quality);
+
+    /**
+        Set low pen quality.
+
+        This is the same as calling Quality() with ::wxPEN_QUALITY_LOW.
+
+        @since 3.1.5
+     */
+    wxPenInfo& LowQuality();
+
+    /**
+        Set high pen quality.
+
+        This is the same as calling Quality() with ::wxPEN_QUALITY_HIGH.
+
+        @since 3.1.5
+     */
+    wxPenInfo& HighQuality();
+
+    wxPenInfo& LowQuality();
     wxColour GetColour() const;
     wxBitmap GetStipple() const;
     wxPenStyle GetStyle() const;
     wxPenJoin GetJoin() const;
     wxPenCap GetCap() const;
+    wxPenQuality GetQuality() const;
     int GetDashes(wxDash **ptr);
     int GetDashCount() const;
     wxDash* GetDash() const;
@@ -279,6 +335,15 @@ public:
     */
     virtual wxPenCap GetCap() const;
 
+    /**
+        Returns the pen quality.
+
+        The default is ::wxPEN_QUALITY_DEFAULT.
+
+        @see wxPenQuality, SetQuality()
+     */
+    wxPenQuality GetQuality() const;
+
     /**
         Returns a reference to the pen colour.
 
@@ -375,6 +440,19 @@ public:
     */
     virtual void SetCap(wxPenCap capStyle);
 
+    /**
+        Sets the pen quality.
+
+        Explicitly selecting low pen quality may be useful in wxMSW if drawing
+        performance is more important than the exact appearance of the lines
+        drawn with this pen.
+
+        @see wxPenQuality
+
+        @since 3.1.5
+     */
+    void SetQuality(wxPenQuality quality);
+
     //@{
     /**
         The pen's colour is changed to the given colour.