Merge branch 'tayloraswift:master' into main

Author: heckj

.github/workflows/build.yml

@@ -2,9 +2,9 @@ name: build
 
 on:
     push:
-        branches: [ main ]
+        branches: [ master ]
     pull_request:
-        branches: [ main ]
+        branches: [ master ]
 
 jobs:
     build-macos:
@@ -51,3 +51,4 @@ jobs:
               run: |
                 swift --version
                 swift build
+                swift build -c release

.gitignore

@@ -1,4 +1,5 @@
 /.build
+/.build.ssgc
 /.vscode
 /Packages
 .swiftpm

README.md

@@ -1,24 +1,23 @@
 <div align="center">
-  
-***`noise`***<br>`2.0.0`
-  
-[![ci build status](https://github.com/kelvin13/swift-noise/actions/workflows/build.yml/badge.svg)](https://github.com/kelvin13/swift-noise/actions/workflows/build.yml)
 
-[![swift package index versions](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fkelvin13%2Fswift-noise%2Fbadge%3Ftype%3Dswift-versions)](https://swiftpackageindex.com/kelvin13/swift-noise)
-[![swift package index platforms](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fkelvin13%2Fswift-noise%2Fbadge%3Ftype%3Dplatforms)](https://swiftpackageindex.com/kelvin13/swift-noise)
+***`noise`***<br>`2.0`
+
+[![ci build status](https://github.com/tayloraswift/swift-noise/actions/workflows/build.yml/badge.svg)](https://github.com/tayloraswift/swift-noise/actions/workflows/build.yml)
+[![swift package index versions](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Ftayloraswift%2Fswift-noise%2Fbadge%3Ftype%3Dswift-versions)](https://swiftpackageindex.com/tayloraswift/swift-noise)
+[![swift package index platforms](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Ftayloraswift%2Fswift-noise%2Fbadge%3Ftype%3Dplatforms)](https://swiftpackageindex.com/tayloraswift/swift-noise)
 
 </div>
 
-![](doc/1.0.0/png/banner_FBM.png)
+![](Sources/Noise/docs.docc/png/banner_FBM.png)
 
-**`swift-noise`** is a free, pure Swift procedural noise generation library. The library product has no dependencies and does not import Foundation or any system frameworks. 
+**`swift-noise`** is a free, pure Swift procedural noise generation library. The library product has no dependencies and does not import Foundation or any system frameworks.
 
-All popular types of procedural noise are supported, including three [gradient noises](https://en.wikipedia.org/wiki/Perlin_noise) (often called Perlin or simplex noises), and two [cellular noises](https://en.wikipedia.org/wiki/Worley_noise) (sometimes called Worley or Voronoi noises). 
+All popular types of procedural noise are supported, including three [gradient noises](https://en.wikipedia.org/wiki/Perlin_noise) (often called Perlin or simplex noises), and two [cellular noises](https://en.wikipedia.org/wiki/Worley_noise) (sometimes called Worley or Voronoi noises).
 
 `swift-noise` includes a [fractal brownian motion](https://thebookofshaders.com/13/) (FBM) noise composition framework, and a [disk point sampler](https://en.wikipedia.org/wiki/Supersampling#Poisson_disc) (often called a Poisson sampler), for generating visually even point distributions in the plane. `swift-noise` also includes pseudo-random number generation and hashing tools.
 
-`swift-noise`’s entire public API is [documented](doc/1.0.0).
+`swift-noise`’s entire public API is [documented](https://swiftinit.org/hist/swift-noise:master/noise).
 
 ## Building
 
-Build *Noise* with the Swift Package Manager. *Noise* itself has no dependencies, but the tests use [`swift-png`](https://github.com/kelvin13/swift-png) to view the generated noise.
+Build *Noise* with the Swift Package Manager. *Noise* itself has no dependencies, but the tests use [`swift-png`](https://github.com/tayloraswift/swift-png) to view the generated noise.

Sources/Noise/cell.swift

@@ -166,6 +166,18 @@ extension _CellNoise2D
     }
 }
 
+/// A type of two-dimensional cellular noise (sometimes called
+/// [Worley noise](https://en.wikipedia.org/wiki/Worley_noise), or Voronoi noise), suitable for
+/// texturing two-dimensional planes.
+///
+/// ![preview](png/banner_cell2d.png)
+///
+/// Unlike many other cell noise implementations, *Noise*’s implementation samples all relevant
+/// generating-points, preventing artifacts or discontinuities from ever appearing in the noise.
+/// Accordingly, *Noise*’s implementation is heavily optimized to prevent the additional edge
+/// cases from impacting the performance of the cell noise.
+///
+/// Cell noise has a three-dimensional version, ``CellNoise3D``.
 public
 struct CellNoise2D:_CellNoise2D, HashedNoise
 {
@@ -180,6 +192,14 @@ struct CellNoise2D:_CellNoise2D, HashedNoise
         self.permutation_table = permutation_table
     }
 
+    /// Creates an instance with the given `amplitude`, `frequency`, and random `seed` values.
+    /// Creating an instance generates a new pseudo-random permutation table for that instance,
+    /// and a new instance does not need to be regenerated to sample the same procedural noise
+    /// field.
+    ///
+    /// The given amplitude is adjusted internally to produce output *exactly* within the range
+    /// of `0 ... amplitude`. However, in practice the cell noise rarely reaches the maximum
+    /// threshold, as it is often useful to inflate the amplitude to get the desired appearance.
     public
     init(amplitude:Double, frequency:Double, seed:Int = 0)
     {
@@ -188,25 +208,34 @@ struct CellNoise2D:_CellNoise2D, HashedNoise
         self.permutation_table = PermutationTable(seed: seed)
     }
 
+    /// Returns the index numbers of the closest feature point to the given coordinate, and the
+    /// squared distance from the given coordinate to the feature point. These index numbers can
+    /// be fed to a color hashing function to produce a
+    /// [Voronoi diagram](https://en.wikipedia.org/wiki/Voronoi_diagram).
     public
     func closest_point(_ x:Double, _ y:Double) -> (point:(Int, Int), r2:Double)
     {
         return self._closest_point(x, y)
     }
 
+    /// Evaluates the cell noise field at the given coordinates.
     public
     func evaluate(_ x:Double, _ y:Double) -> Double
     {
         let (_, r2):((Int, Int), Double) = self.closest_point(x, y)
         return self.amplitude * r2
     }
 
+    /// Evaluates the cell noise field at the given coordinates. The third coordinate is
+    /// ignored.
     public
     func evaluate(_ x:Double, _ y:Double, _:Double) -> Double
     {
         return self.evaluate(x, y)
     }
 
+    /// Evaluates the cell noise field at the given coordinates. The third and fourth
+    /// coordinates are ignored.
     public
     func evaluate(_ x:Double, _ y:Double, _:Double, _:Double) -> Double
     {
@@ -518,6 +547,26 @@ extension _CellNoise3D
     }
 }
 
+/// A type of three-dimensional cellular noise (sometimes called
+/// [Worley noise](https://en.wikipedia.org/wiki/Worley_noise), or Voronoi noise), suitable for
+/// texturing arbitrary three-dimensional objects.
+///
+/// ![preview](png/banner_cell3d.png)
+///
+/// Unlike many other cell noise implementations, *Noise*’s implementation samples all relevant
+/// generating-points, preventing artifacts or discontinuities from ever appearing in the noise.
+/// Accordingly, *Noise*’s implementation is heavily optimized to prevent the additional edge
+/// cases from impacting the performance of the cell noise.
+///
+/// Three dimensional cell noise is approximately three to four times slower than its
+/// [two-dimensional version](doc:CellNoise2D), but has a vastly superior visual appearance,
+/// even when sampled in two dimensions.
+///
+/// `CellNoise3D` is analogous to
+/// [Blender Voronoi noise](https://docs.blender.org/manual/en/dev/render/cycles/nodes/types/textures/voronoi.html),
+/// with the *Distance Squared* metric. The *Scale* of Blender Voronoi noise is identical to the
+/// ``frequency`` of `CellNoise3D`; its range is approximately `0 ... 10/3` in `CellNoise3D`
+/// units.
 public
 struct CellNoise3D:_CellNoise3D, HashedNoise
 {
@@ -532,6 +581,14 @@ struct CellNoise3D:_CellNoise3D, HashedNoise
         self.permutation_table = permutation_table
     }
 
+    /// Creates an instance with the given `amplitude`, `frequency`, and random `seed` values.
+    /// Creating an instance generates a new pseudo-random permutation table for that instance,
+    /// and a new instance does not need to be regenerated to sample the same procedural noise
+    /// field.
+    ///
+    /// The given amplitude is adjusted internally to produce output *exactly* within the range
+    /// of `0 ... amplitude`. However, in practice the cell noise rarely reaches the maximum
+    /// threshold, as it is often useful to inflate the amplitude to get the desired appearance.
     public
     init(amplitude:Double, frequency:Double, seed:Int = 0)
     {
@@ -540,25 +597,34 @@ struct CellNoise3D:_CellNoise3D, HashedNoise
         self.permutation_table = PermutationTable(seed: seed)
     }
 
+    /// Returns the index numbers of the closest feature point to the given coordinate, and the
+    /// squared distance from the given coordinate to the feature point. These index numbers can
+    /// be fed to a color hashing function to produce a
+    /// [Voronoi diagram](https://en.wikipedia.org/wiki/Voronoi_diagram).
     public
     func closest_point(_ x:Double, _ y:Double, _ z:Double) -> (point:(Int, Int, Int), r2:Double)
     {
         return self._closest_point(x, y, z)
     }
 
+    /// Evaluates the cell noise field at the given `x, y` coordinates, supplying `0` for the
+    /// missing `z` coordinate.
     public
     func evaluate(_ x:Double, _ y:Double) -> Double
     {
         return self.evaluate(x, y, 0)
     }
 
+    /// Evaluates the cell noise field at the given coordinates.
     public
     func evaluate(_ x:Double, _ y:Double, _ z:Double) -> Double
     {
         let (_, r2):((Int, Int, Int), Double) = self.closest_point(x, y, z)
         return self.amplitude * r2
     }
 
+    /// Evaluates the cell noise field at the given coordinates. The fourth coordinate is
+    /// ignored.
     public
     func evaluate(_ x:Double, _ y:Double, _ z:Double, _:Double) -> Double
     {

Sources/Noise/compounds.swift

@@ -1,3 +1,7 @@
+/// A generic [fractal brownian motion](https://thebookofshaders.com/13/) noise generator,
+/// capable of overlaying multiple instances of procedural ``Noise`` at increasing frequencies.
+///
+/// ![preview](png/banner_FBM.png)
 public
 struct FBM<Source>:Noise where Source:Noise
 {
@@ -34,6 +38,12 @@ struct FBM<Source>:Noise where Source:Noise
         self.generators = []
     }
 
+    /// Creates an instance with the given number of `octaves` of noise. The given `amplitude`
+    /// is the amplitude of the first octave of noise, and is multiplied by `persistence` for
+    /// each successive octave. The given `frequency` is the frequency of the first octave of
+    /// noise, and is multiplied by the `lacunarity` for each successive octave. The `seed`
+    /// value is passed through to the first octave of noise, and is incremented for each
+    /// successive octave.
     @available(*, unavailable, message: "use init(_:octaves:persistence:lacunarity:) instead")
     public
     init(amplitude:Double, frequency:Double, octaves:Int, persistence:Double = 0.75, lacunarity:Double = 2, seed:Int = 0)

Sources/Noise/disk.swift

@@ -1,3 +1,16 @@
+/// A point sampler capable of producing uniform and roughly-evenly spaced pseudo-random point
+/// distributions in the plane. Disk sampling is sometimes referred to as
+/// [Poisson sampling](https://en.wikipedia.org/wiki/Supersampling#Poisson_disc).
+///
+/// ![preview](png/banner_disk2d.png)
+///
+/// Disk samples are not a noise field — its generation is inherently sequential, as opposed to
+/// most procedural noise fields which are embarrassingly parallel. Thus, disk samples have no
+/// concept of *evaluation*; the entire sample set must be generated as a whole.
+///
+/// Disk samples have an internal state, which is advanced every time the point generator runs.
+/// In many ways, disk samples have more in common with pseudo-random number generators than
+/// they do with procedural noise fields.
 public
 struct DiskSampler2D
 {
@@ -17,6 +30,9 @@ struct DiskSampler2D
     private static
     let candidate_table_bitmask:Int = 0b1111111111 // 1023
 
+    /// Creates an instance with the given fixed random `seed`. This process calculates a random
+    /// table used internally in the sample generation step. The same instance can be reused to
+    /// generate multiple, different point distributions.
     public
     init(seed:Int = 0)
     {
@@ -46,6 +62,13 @@ struct DiskSampler2D
         self.candidate_ring = candidate_ring
     }
 
+    /// Generates a set of sample points that are spaced no less than `radius` apart over a
+    /// region sized `width` by `height` . Up to `k` candidate points will be used to generate
+    /// each sample point; higher values of `k` yield more compact point distributions, but take
+    /// longer to run. The `seed` point specifies the first point that is added to the
+    /// distribution, and influences where subsequent sample points are added. This `seed` is
+    /// orthogonal to the `seed` supplied in the initializer. If `seed` is left `nil`, the seed
+    /// point is placed at the center of the region.
     public mutating
     func generate(radius:Double, width:Int, height:Int, k:Int = 32, seed:(Double, Double)? = nil) -> [(Double, Double)]
     {

Sources/Noise/docs.docc/CellNoise2D.md

@@ -0,0 +1,10 @@
+# ``CellNoise2D``
+
+## Topics
+
+### Evaluating noise
+
+-   ``closest_point(_:_:)``
+-   ``evaluate(_:_:)``
+-   ``evaluate(_:_:_:)``
+-   ``evaluate(_:_:_:_:)``

Sources/Noise/docs.docc/CellNoise3D.md

@@ -0,0 +1,10 @@
+# ``CellNoise3D``
+
+## Topics
+
+### Evaluating noise
+
+-   ``closest_point(_:_:_:)``
+-   ``evaluate(_:_:)``
+-   ``evaluate(_:_:_:)``
+-   ``evaluate(_:_:_:_:)``

Sources/Noise/docs.docc/README.md

@@ -0,0 +1,30 @@
+# ``/Noise``
+
+Generate and combine commonly used procedural noise patterns and distributions.
+
+## Topics
+
+### Protocols
+
+-   ``Noise``
+
+### Noise generators
+
+-   ``SimplexNoise2D``
+-   ``GradientNoise2D``
+-   ``GradientNoise3D``
+-   ``CellNoise2D``
+-   ``CellNoise3D``
+
+### Noise composition
+
+-   ``FBM``
+
+### Pattern generators
+
+-   ``DiskSampler2D``
+
+### Psuedo-random number generators
+
+-   ``PermutationTable``
+-   ``RandomXorshift``