render CircularWaveformRenderer .ring as a true annulus across all styles

The ring path is now built as two subpaths (outer envelope + inner circle),
and both the CGContext and SwiftUI rendering paths fill / clip it with the
even-odd rule so the inner disk is correctly excluded for filled and
gradient styles. The envelope also stays at least 1 device pixel thick at
silence, mirroring LinearWaveformRenderer's minimum-amplitude behavior, so
the ring remains visible regardless of input. Drops the "experimental"
label on .ring now that all styles render correctly.

Author: dmrschmidt

Sources/DSWaveformImage/Renderers/CircularWaveformRenderer.swift

@@ -5,7 +5,6 @@ import CoreGraphics
  Draws a circular 2D amplitude envelope of the samples provided.
 
  Draws either a filled circle, or a hollow ring, depending on the provided `Kind`. Defaults to drawing a `.circle`.
- `Kind.ring` is currently experimental.
  Can be customized further via the configuration `Waveform.Style`.
  */
 
@@ -14,17 +13,28 @@ public struct CircularWaveformRenderer: WaveformRenderer {
         /// Draws waveform as a circular amplitude envelope.
         case circle
 
-        /// **Experimental!** (Will) draw waveform as a ring-shaped amplitude envelope.
-        /// Associated value will define the percentage of desired "hollowness" inside, or in other words the ring's thickness / diameter in relation to the overall diameter.
+        /// Draws waveform as a ring-shaped amplitude envelope, where the modulated outer envelope
+        /// extends from a fixed inner circle outward toward the maximum radius.
+        /// The associated value sets the inner circle's radius as a fraction of the overall radius
+        /// (e.g. `0.5` = inner radius is half of the maximum). Clamped to `(0...1)` is the caller's
+        /// responsibility — `0` collapses to `.circle`, `1` collapses to a zero-thickness ring.
         case ring(CGFloat)
     }
 
-    private let kind: Kind
+    public let kind: Kind
 
     public init(kind: Kind = .circle) {
         self.kind = kind
     }
 
+    /// Whether `fill` / `clip` over this renderer's path needs the even-odd rule to produce the
+    /// intended region. `true` for `.ring`, because the path consists of an outer envelope and an
+    /// inner circle subpath whose subtraction can't be guaranteed by winding direction alone.
+    public var prefersEvenOddFillRule: Bool {
+        if case .ring = kind { return true }
+        return false
+    }
+
     public func path(samples: [Float], with configuration: Waveform.Configuration, lastOffset: Int, position: Waveform.Position = .middle) -> CGPath {
         switch kind {
         case .circle: return circlePath(samples: samples, with: configuration, lastOffset: lastOffset, position: position)
@@ -40,16 +50,33 @@ public struct CircularWaveformRenderer: WaveformRenderer {
     }
 
     func style(context: CGContext, with configuration: Waveform.Configuration) {
-        if case let .gradient(colors) = configuration.style {
-            context.clip()
+        // The ring path is two subpaths (outer envelope + inner circle). Region-based ops (fill,
+        // clip) must use even-odd so the annulus is produced regardless of subpath direction —
+        // non-zero winding would require both subpaths to wind opposite ways, which we can't
+        // guarantee across CG versions for `addEllipse`.
+        let isRing: Bool = { if case .ring = kind { return true } else { return false } }()
+
+        switch configuration.style {
+        case let .gradient(colors):
+            if isRing {
+                context.clip(using: .evenOdd)
+            } else {
+                context.clip()
+            }
             let colors = NSArray(array: colors.map { (color: DSColor) -> CGColor in color.cgColor }) as CFArray
             let colorSpace = CGColorSpaceCreateDeviceRGB()
             let gradient = CGGradient(colorsSpace: colorSpace, colors: colors, locations: nil)!
             context.drawLinearGradient(gradient,
                                        start: CGPoint(x: 0, y: 0),
                                        end: CGPoint(x: 0, y: configuration.size.height),
                                        options: .drawsAfterEndLocation)
-        } else {
+
+        case let .filled(color) where isRing:
+            context.setLineWidth(1.0 / configuration.scale)
+            context.setFillColor(color.cgColor)
+            context.fillPath(using: .evenOdd)
+
+        default:
             defaultStyle(context: context, with: configuration)
         }
     }
@@ -93,45 +120,77 @@ public struct CircularWaveformRenderer: WaveformRenderer {
         guard case let .ring(config) = kind else {
             fatalError("called with wrong kind")
         }
+        guard !samples.isEmpty else { return CGMutablePath() }
 
         let graphRect = CGRect(origin: .zero, size: configuration.size)
         let maxRadius = CGFloat(min(graphRect.maxX, graphRect.maxY) / 2.0) * configuration.verticalScalingFactor
         let innerRadius: CGFloat = maxRadius * config
+        let ringThickness = maxRadius - innerRadius
+        // Mirrors `LinearWaveformRenderer`'s `minimumGraphAmplitude` — guarantees the ring stays
+        // at least 1 device pixel thick at silence (sample == 1 → invertedDbSample == 0), so the
+        // ring is always visible. Clamped to `ringThickness` for the degenerate `.ring(1)` case
+        // where there's no room to extend outward at all.
+        let minimumRadialAmplitude: CGFloat = min(ringThickness, 1 / configuration.scale)
         let center = CGPoint(
             x: graphRect.maxX * position.offset(),
             y: graphRect.maxY * position.offset()
         )
         let path = CGMutablePath()
 
-        path.move(to: CGPoint(
-            x: center.x + innerRadius * cos(0),
-            y: center.y + innerRadius * sin(0)
-        ))
-
-        for (index, sample) in samples.enumerated() {
-            let x = index + lastOffset
-            let angle = CGFloat.pi * 2 * (CGFloat(index) / CGFloat(samples.count))
-
-            if case .striped = configuration.style, x % Int(configuration.scale) != 0 || x % stripeBucket(configuration) != 0 {
-                // skip sub-pixels - any x value not scale aligned
-                // skip any point that is not a multiple of our bucket width (width + spacing)
-                path.move(to: CGPoint(
+        if case .striped = configuration.style {
+            // Each visible stripe is its own move(inner) + line(outer) subpath — drawn radially
+            // at the sample's angle, with `defaultStyle` translating it into a stroked stripe.
+            for (index, sample) in samples.enumerated() {
+                let x = index + lastOffset
+                if x % Int(configuration.scale) != 0 || x % stripeBucket(configuration) != 0 {
+                    continue
+                }
+
+                let angle = CGFloat.pi * 2 * (CGFloat(index) / CGFloat(samples.count))
+                let invertedDbSample = 1 - CGFloat(sample)
+                let radialAmplitude = max(minimumRadialAmplitude, ringThickness * invertedDbSample)
+                let inner = CGPoint(
                     x: center.x + innerRadius * cos(angle),
                     y: center.y + innerRadius * sin(angle)
-                ))
-                continue
+                )
+                let outer = CGPoint(
+                    x: inner.x + radialAmplitude * cos(angle),
+                    y: inner.y + radialAmplitude * sin(angle)
+                )
+                path.move(to: inner)
+                path.addLine(to: outer)
             }
+            return path
+        }
 
+        // Non-striped: build an annulus from two subpaths — the outer envelope and the inner
+        // circle. `style(...)` uses the even-odd fill rule for filled/gradient so the inner
+        // disk is excluded regardless of subpath winding direction; outlined / gradientOutlined
+        // simply stroke both subpaths' outlines.
+        for (index, sample) in samples.enumerated() {
+            let angle = CGFloat.pi * 2 * (CGFloat(index) / CGFloat(samples.count))
             let invertedDbSample = 1 - CGFloat(sample) // sample is in dB, linearly normalized to [0, 1] (1 -> -50 dB)
-            let pointOnCircle = CGPoint(
-                x: center.x + innerRadius * cos(angle) + (maxRadius - innerRadius) * invertedDbSample * cos(angle),
-                y: center.y + innerRadius * sin(angle) + (maxRadius - innerRadius) * invertedDbSample * sin(angle)
+            let radialAmplitude = max(minimumRadialAmplitude, ringThickness * invertedDbSample)
+            let radius = innerRadius + radialAmplitude
+            let pointOnEnvelope = CGPoint(
+                x: center.x + radius * cos(angle),
+                y: center.y + radius * sin(angle)
             )
-
-            path.addLine(to: pointOnCircle)
+            if index == 0 {
+                path.move(to: pointOnEnvelope)
+            } else {
+                path.addLine(to: pointOnEnvelope)
+            }
         }
-
         path.closeSubpath()
+
+        path.addEllipse(in: CGRect(
+            x: center.x - innerRadius,
+            y: center.y - innerRadius,
+            width: innerRadius * 2,
+            height: innerRadius * 2
+        ))
+
         return path
     }
 

Sources/DSWaveformImageViews/SwiftUI/DefaultShapeStyler.swift

@@ -7,7 +7,7 @@ struct DefaultShapeStyler {
     func style(shape: WaveformShape, with configuration: Waveform.Configuration) -> some View {
         switch configuration.style {
         case let .filled(color):
-            shape.fill(Color(color))
+            shape.fill(Color(color), style: shape.fillStyle)
 
         case let .outlined(color, lineWidth):
             shape.stroke(
@@ -20,7 +20,10 @@ struct DefaultShapeStyler {
 
         case let .gradient(colors):
             shape
-                .fill(LinearGradient(colors: colors.map(Color.init), startPoint: .bottom, endPoint: .top))
+                .fill(
+                    LinearGradient(colors: colors.map(Color.init), startPoint: .bottom, endPoint: .top),
+                    style: shape.fillStyle
+                )
 
         case let .gradientOutlined(colors, lineWidth):
             shape.stroke(

Sources/DSWaveformImageViews/SwiftUI/WaveformShape.swift

@@ -44,6 +44,14 @@ public struct WaveformShape: Shape {
     var isEmpty: Bool {
         samples.isEmpty
     }
+
+    /// SwiftUI fill style this shape's path expects. Uses even-odd when the renderer's path is
+    /// built from multiple subpaths that need region subtraction (e.g. `CircularWaveformRenderer`
+    /// in `.ring` kind). Defaults to non-zero for everyone else.
+    public var fillStyle: FillStyle {
+        let eoFill = (renderer as? CircularWaveformRenderer)?.prefersEvenOddFillRule ?? false
+        return FillStyle(eoFill: eoFill)
+    }
 }
 
 private extension WaveformShape {