diff --git a/CubicNoise/Contracts/INoiseEngine.cs b/CubicNoise/Contracts/INoiseEngine.cs index 40e2943..15f9140 100644 --- a/CubicNoise/Contracts/INoiseEngine.cs +++ b/CubicNoise/Contracts/INoiseEngine.cs @@ -4,10 +4,24 @@ using System.Text; namespace CubicNoise.Contracts { + /// + /// An interface which each noise generator must implement. + /// public interface INoiseEngine { + /// + /// Producing a one-dimensional based noise value. + /// + /// The x coordinate. + /// The noise value. float Get(float x); + /// + /// Produces a two-dimensional based noise value. + /// + /// The x coordinate. + /// The y coordinate. + /// The noise value. float Get(float x, float y); } } diff --git a/CubicNoise/Contracts/IParameterName.cs b/CubicNoise/Contracts/IParameterName.cs index 6c7398f..89cf4d2 100644 --- a/CubicNoise/Contracts/IParameterName.cs +++ b/CubicNoise/Contracts/IParameterName.cs @@ -1,5 +1,11 @@ namespace CubicNoise.Contracts { + /// + /// An interface which gets used to provide arbitrary parameter names + /// to the general noise engine class. It is a way to abstract the + /// concrete (but to the general noise engine class unknown) parameters + /// for different noise generators. + /// public interface IParameterName { } diff --git a/CubicNoise/CubicNoise.csproj b/CubicNoise/CubicNoise.csproj index e6c458a..1d49885 100644 --- a/CubicNoise/CubicNoise.csproj +++ b/CubicNoise/CubicNoise.csproj @@ -16,6 +16,10 @@ C:\Users\Thorsten\Downloads\repos\CubicNoise\CubicNoise\CubicNoise.xml + + C:\Users\Thorsten\Downloads\repos\CubicNoise\CubicNoise\CubicNoise.xml + + True diff --git a/CubicNoise/CubicNoise.xml b/CubicNoise/CubicNoise.xml index a5432eb..f0d302e 100644 --- a/CubicNoise/CubicNoise.xml +++ b/CubicNoise/CubicNoise.xml @@ -4,5 +4,165 @@ CubicNoise + + + An interface which each noise generator must implement. + + + + + Producing a one-dimensional based noise value. + + The x coordinate. + The noise value. + + + + Produces a two-dimensional based noise value. + + The x coordinate. + The y coordinate. + The noise value. + + + + An interface which gets used to provide arbitrary parameter names + to the general noise engine class. It is a way to abstract the + concrete (but to the general noise engine class unknown) parameters + for different noise generators. + + + + + This class stores all parameters needed to create a noise engine instance. + + + + + The engine's seed value. To use a string value as seed, use the GetDeterministicHashCode() method + which gets provided by this library. A different seed value results in a complete different result. + When you generate e.g. a landscape, two different seeds will produce different landscapes. + + + + + The desired kind of noise generator. + + + + + A dictionary of additional parameters needed by the chosen noise generator. + + + + + Extension methods for this library. + + + + + This is a deterministic hash function for strings. The official hash methods in .NET Core are no longer + deterministic due to possible hashing attacks, cf. https://youtu.be/R2Cq3CLI6H8. + + The source for this implementation: https://andrewlock.net/why-is-string-gethashcode-different-each-time-i-run-my-program-in-net-core/. + Thanks Andrew for providing such a hash function. + + Aware: Never use this hash function for any security-related task or for any hashtable storage, etc. + + Please use it only in the case, that you really need a deterministic value. In the context of this + library, the hash values are usually used for media, games, art, or simulations in order to share + results with others. This is the only valid use case! + + The string for which a hash value is to be computed. + A deterministic 32 bit / 4 byte hash value of the given string. + + + + The main class of the library. You should use it to generate a noise engine. This class is thread-safe. + You can use all methods from as many threads, as you want. There a no async methods, because the + performance is very high. Even on a 2019 mid-size business laptop with Intel i5 CPU, each core + is able to produce > 6 million values per second (2 dimensions). + + Not only the factory method is thread-safe. Each instance of the class is thread-safe as well. + + + + + The factory method to use for generating a noise engine. This method is thread-safe. Call it from as many threads + as you want. + + The parameters for the desired noise engine. + The desired noise engine instance. + + + + Yields a one-dimensional based noise value. This method is thread-safe as well. Call it from as + many threads as you want. You can expect about 16 million calls per CPU core per second (year 2019). + + The x coordinate. + The corresponding noise value for the given coordinate. + + + + Yields a two-dimensional based noise value. This method is thread-safe as well. Call it from as + many threads as you want. You can expect about 6 million calls per CPU core per second (year 2019). + + The x coordinate. + The y coordinate. + The corresponding noise value for the given 2d coordinate. + + + + This is the cubic noise engine by Job Talle, cf. https://jobtalle.com/cubic_noise.html. It based on the + C# version which was provided at Github: https://github.com/jobtalle/CubicNoise/blob/master/c%23/CubicNoise.cs. + + Thanks Job for your implementation. + + Compared to Job's version, this implementation is a bit optimized and + used useful C# 8.0 / .NET Core 3.1 LTS features. + + + + + This class contains all known cubic noise's parameters. + + + + + Cubic noise's octave parameter. + + + + + Cubic noise's period x parameter. + + + + + Cubic noise's period y parameter. + + + + + This is the random number engine which gets used in case that the UNKNOWN type was used. + This engine is not meant for production. It is a placeholder for empty values, where a type + is needed. The engine will generate a random value each time. + + + + + All implemented noise generators. + + + + + The UNKNOWN generator is a placeholder for empty values. You should not use it in production. It generates random numbers on every call. + + + + + This is the cubic noise generator by Job Talle, cf. https://jobtalle.com/cubic_noise.html and https://github.com/jobtalle. + + diff --git a/CubicNoise/EngineParameters.cs b/CubicNoise/EngineParameters.cs index 1ebaf04..bb4cd25 100644 --- a/CubicNoise/EngineParameters.cs +++ b/CubicNoise/EngineParameters.cs @@ -5,12 +5,26 @@ using CubicNoise.Contracts; namespace CubicNoise { + /// + /// This class stores all parameters needed to create a noise engine instance. + /// public sealed class EngineParameters { + /// + /// The engine's seed value. To use a string value as seed, use the GetDeterministicHashCode() method + /// which gets provided by this library. A different seed value results in a complete different result. + /// When you generate e.g. a landscape, two different seeds will produce different landscapes. + /// public int Seed { get; set; } = new Random().Next(); + /// + /// The desired kind of noise generator. + /// public NoiseTypes Type { get; set; } = NoiseTypes.UNKNOWN; + /// + /// A dictionary of additional parameters needed by the chosen noise generator. + /// public IReadOnlyDictionary IntParameters { get; set; } } } diff --git a/CubicNoise/Extensions.cs b/CubicNoise/Extensions.cs index f9e4530..d77fcc8 100644 --- a/CubicNoise/Extensions.cs +++ b/CubicNoise/Extensions.cs @@ -5,9 +5,27 @@ using CubicNoise.Noisers; namespace CubicNoise { + /// + /// Extension methods for this library. + /// public static class Extensions { - // Source: https://andrewlock.net/why-is-string-gethashcode-different-each-time-i-run-my-program-in-net-core/ + // + /// + /// This is a deterministic hash function for strings. The official hash methods in .NET Core are no longer + /// deterministic due to possible hashing attacks, cf. https://youtu.be/R2Cq3CLI6H8. + /// + /// The source for this implementation: https://andrewlock.net/why-is-string-gethashcode-different-each-time-i-run-my-program-in-net-core/. + /// Thanks Andrew for providing such a hash function. + /// + /// Aware: Never use this hash function for any security-related task or for any hashtable storage, etc. + /// + /// Please use it only in the case, that you really need a deterministic value. In the context of this + /// library, the hash values are usually used for media, games, art, or simulations in order to share + /// results with others. This is the only valid use case! + /// + /// The string for which a hash value is to be computed. + /// A deterministic 32 bit / 4 byte hash value of the given string. public static int GetDeterministicHashCode(this string str) { unchecked diff --git a/CubicNoise/NoiseEngine.cs b/CubicNoise/NoiseEngine.cs index 9e448f7..4d8d763 100644 --- a/CubicNoise/NoiseEngine.cs +++ b/CubicNoise/NoiseEngine.cs @@ -6,6 +6,14 @@ using CubicNoise.Noisers; namespace CubicNoise { + /// + /// The main class of the library. You should use it to generate a noise engine. This class is thread-safe. + /// You can use all methods from as many threads, as you want. There a no async methods, because the + /// performance is very high. Even on a 2019 mid-size business laptop with Intel i5 CPU, each core + /// is able to produce > 6 million values per second (2 dimensions). + /// + /// Not only the factory method is thread-safe. Each instance of the class is thread-safe as well. + /// public sealed class NoiseEngine : INoiseEngine { private readonly INoiseEngine engine; @@ -22,10 +30,29 @@ namespace CubicNoise }; } + /// + /// The factory method to use for generating a noise engine. This method is thread-safe. Call it from as many threads + /// as you want. + /// + /// The parameters for the desired noise engine. + /// The desired noise engine instance. public static NoiseEngine Create(EngineParameters parameters) => new NoiseEngine(parameters.Type, parameters.Seed, parameters?.IntParameters); + /// + /// Yields a one-dimensional based noise value. This method is thread-safe as well. Call it from as + /// many threads as you want. You can expect about 16 million calls per CPU core per second (year 2019). + /// + /// The x coordinate. + /// The corresponding noise value for the given coordinate. public float Get(float x) => this.engine.Get(x); + /// + /// Yields a two-dimensional based noise value. This method is thread-safe as well. Call it from as + /// many threads as you want. You can expect about 6 million calls per CPU core per second (year 2019). + /// + /// The x coordinate. + /// The y coordinate. + /// The corresponding noise value for the given 2d coordinate. public float Get(float x, float y) => this.engine.Get(x, y); } } diff --git a/CubicNoise/NoiseTypes.cs b/CubicNoise/NoiseTypes.cs index 0306436..ef1d55d 100644 --- a/CubicNoise/NoiseTypes.cs +++ b/CubicNoise/NoiseTypes.cs @@ -4,9 +4,19 @@ using System.Text; namespace CubicNoise { + /// + /// All implemented noise generators. + /// public enum NoiseTypes { + /// + /// The UNKNOWN generator is a placeholder for empty values. You should not use it in production. It generates random numbers on every call. + /// UNKNOWN = 0, + + /// + /// This is the cubic noise generator by Job Talle, cf. https://jobtalle.com/cubic_noise.html and https://github.com/jobtalle. + /// CUBIC_NOISE = 1_000, } } diff --git a/CubicNoise/Noisers/CubicNoiseEngine.cs b/CubicNoise/Noisers/CubicNoiseEngine.cs index 51498dc..4c0fd68 100644 --- a/CubicNoise/Noisers/CubicNoiseEngine.cs +++ b/CubicNoise/Noisers/CubicNoiseEngine.cs @@ -6,7 +6,16 @@ using CubicNoise.Contracts; namespace CubicNoise.Noisers { - public sealed class CubicNoiseEngine : INoiseEngine + /// + /// This is the cubic noise engine by Job Talle, cf. https://jobtalle.com/cubic_noise.html. It based on the + /// C# version which was provided at Github: https://github.com/jobtalle/CubicNoise/blob/master/c%23/CubicNoise.cs. + /// + /// Thanks Job for your implementation. + /// + /// Compared to Job's version, this implementation is a bit optimized and + /// used useful C# 8.0 / .NET Core 3.1 LTS features. + /// + internal sealed class CubicNoiseEngine : INoiseEngine { private const int RANDOM_NUMBER_A = 134_775_813; private const int RANDOM_NUMBER_B = 1_103_515_245; @@ -16,7 +25,7 @@ namespace CubicNoise.Noisers private readonly int periodY; private readonly int seed; - public CubicNoiseEngine(int seed, IReadOnlyDictionary intParameters) + internal CubicNoiseEngine(int seed, IReadOnlyDictionary intParameters) { this.seed = seed; this.octave = intParameters?.ContainsKey(CubicNoiseIntParameters.OCTAVE) == true ? intParameters[CubicNoiseIntParameters.OCTAVE] : 16; diff --git a/CubicNoise/Noisers/CubicNoiseIntParameters.cs b/CubicNoise/Noisers/CubicNoiseIntParameters.cs index c9f0741..811ee7f 100644 --- a/CubicNoise/Noisers/CubicNoiseIntParameters.cs +++ b/CubicNoise/Noisers/CubicNoiseIntParameters.cs @@ -5,10 +5,24 @@ using CubicNoise.Contracts; namespace CubicNoise.Noisers { + /// + /// This class contains all known cubic noise's parameters. + /// public class CubicNoiseIntParameters : IParameterName { + /// + /// Cubic noise's octave parameter. + /// public static readonly IParameterName OCTAVE = new CubicNoiseIntParameters(); + + /// + /// Cubic noise's period x parameter. + /// public static readonly IParameterName PERIOD_X = new CubicNoiseIntParameters(); + + /// + /// Cubic noise's period y parameter. + /// public static readonly IParameterName PERIOD_Y = new CubicNoiseIntParameters(); private CubicNoiseIntParameters() diff --git a/CubicNoise/Noisers/RandomNumberEngine.cs b/CubicNoise/Noisers/RandomNumberEngine.cs index 3e8afca..a98b021 100644 --- a/CubicNoise/Noisers/RandomNumberEngine.cs +++ b/CubicNoise/Noisers/RandomNumberEngine.cs @@ -5,11 +5,16 @@ using CubicNoise.Contracts; namespace CubicNoise.Noisers { - public sealed class RandomNumberEngine : INoiseEngine + /// + /// This is the random number engine which gets used in case that the UNKNOWN type was used. + /// This engine is not meant for production. It is a placeholder for empty values, where a type + /// is needed. The engine will generate a random value each time. + /// + internal sealed class RandomNumberEngine : INoiseEngine { - private Random rng; + private readonly Random rng; - public RandomNumberEngine(int seed) + internal RandomNumberEngine(int seed) { this.rng = new Random(seed); }