Interface INoise

All Superinterfaces:
Externalizable, Serializable
All Known Implementing Classes:
BadgerNoise, BasicHashNoise, BitNoise, CellularNoise, CyclicNoise, DualMutantNoiseWrapper, FlanNoise, FoamNoise, FoamplexNoise, HighDimensionalValueNoise, HoneyNoise, HuskyNoise, MutantNoiseWrapper, Noise, NoiseAdjustment, NoiseWrapper, OpenSimplex2, OpenSimplex2Smooth, PerlinNoise, PerlueNoise, PhantomNoise, PuffyNoise, RadialNoiseWrapper, ShapedFoamNoise, SimplexNoise, SimplexNoiseHard, SimplexNoiseScaled, SnakeNoise, SorbetNoise, TaffyNoise, ValueNoise, VroomNoise, WhiteNoise
public interface INoise extends Externalizable
Shared interface for all continuous noise algorithms that can produce at least one dimensionality of noise between 2D and 7D. An INoise can be used as the base algorithm by NoiseWrapper, which adds functionality like changing the frequency, using multiple octaves and having different ways of combining those octaves. You can also manipulate an INoise with NoiseAdjustment. An INoise can be serialized to a String or using Externalizable. INoise.Serializer.deserialize(String) allows returning an arbitrary INoise from the String serialized format, as long as the INoise type was registered with INoise.Serializer.register(INoise).
The class Noise also implements INoise, and so it can be used wherever a single algorithm can be, but it has a much larger and more complex API because it also does what a NoiseWrapper does. Using an INoise class along with a NoiseWrapper is usually preferred because it's easier to serialize.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static class 
    INoise.Serializer
     

  • Method Summary

    Modifier and Type
    Method
    Description
    default INoise
    copy()
    Creates a copy of this INoise, which should be a deep copy for any mutable state but can be shallow for immutable types such as functions.
    boolean
    equals(Object other)
     
    int
    getMaxDimension()
    Gets the maximum dimension supported by this generator, such as 2 for a generator that only is defined for flat surfaces, or 7 for one that is defined up to the highest dimension this interface knows about (7D).
    int
    getMinDimension()
    Gets the minimum dimension supported by this generator, such as 2 for a generator that only is defined for flat surfaces, or 3 for one that is only defined for 3D or higher-dimensional spaces.
    float
    getNoise(float x, float y)
    Gets 2D noise with a default or pre-set seed.
    float
    getNoise(float x, float y, float z)
    Gets 3D noise with a default or pre-set seed.
    float
    getNoise(float x, float y, float z, float w)
    Gets 4D noise with a default or pre-set seed.
    float
    getNoise(float x, float y, float z, float w, float u)
    Gets 5D noise with a default or pre-set seed.
    float
    getNoise(float x, float y, float z, float w, float u, float v)
    Gets 6D noise with a default or pre-set seed.
    default float
    getNoise(float x, float y, float z, float w, float u, float v, float m)
    Gets 7D noise with a default or pre-set seed.
    default float
    getNoiseWithSeed(float x, float y, float z, float w, float u, float v, float m, long seed)
    Gets 7D noise with a specific seed.
    default float
    getNoiseWithSeed(float x, float y, float z, float w, float u, float v, long seed)
    Gets 6D noise with a specific seed.
    default float
    getNoiseWithSeed(float x, float y, float z, float w, float u, long seed)
    Gets 5D noise with a specific seed.
    default float
    getNoiseWithSeed(float x, float y, float z, float w, long seed)
    Gets 4D noise with a specific seed.
    default float
    getNoiseWithSeed(float x, float y, float z, long seed)
    Gets 3D noise with a specific seed.
    default float
    getNoiseWithSeed(float x, float y, long seed)
    Gets 2D noise with a specific seed.
    long
    getSeed()
    Gets the current seed of the generator, as a long even if the seed is stored internally as an int.
    default String
    getTag()
    Returns a typically-four-character String constant that should uniquely identify this INoise as well as possible.
    boolean
    hasEfficientSetSeed()
    Returns true if this generator can be seeded with setSeed(long) during each call to obtain noise, or false if calling setSeed() is slow enough or allocates enough that alternative approaches should be used.
    default void
    readExternal(ObjectInput in)
    The object implements the readExternal method to restore its contents by calling the methods of DataInput for primitive types and readObject for objects, strings and arrays.
    void
    setSeed(long seed)
    Sets the seed to the given long, if long seeds are supported, or (int)seed if only int seeds are supported.
    default INoise
    stringDeserialize(String data)
    Given a serialized String produced by stringSerialize(), reassigns this INoise to have the described state from the given String.
    default String
    stringSerialize()
    Produces a String that describes everything needed to recreate this INoise in full.
    default void
    writeExternal(ObjectOutput out)
    The object implements the writeExternal method to save its contents by calling the methods of DataOutput for its primitive values or calling the writeObject method of ObjectOutput for objects, strings, and arrays.

  • Method Details

    • getMinDimension

      int getMinDimension()
      Gets the minimum dimension supported by this generator, such as 2 for a generator that only is defined for flat surfaces, or 3 for one that is only defined for 3D or higher-dimensional spaces.
      Returns:
      the minimum supported dimension, from 2 to 7 inclusive

    • getMaxDimension

      int getMaxDimension()
      Gets the maximum dimension supported by this generator, such as 2 for a generator that only is defined for flat surfaces, or 7 for one that is defined up to the highest dimension this interface knows about (7D).
      Returns:
      the maximum supported dimension, from 2 to 7 inclusive

    • hasEfficientSetSeed

      boolean hasEfficientSetSeed()
      Returns true if this generator can be seeded with setSeed(long) during each call to obtain noise, or false if calling setSeed() is slow enough or allocates enough that alternative approaches should be used. You can always call setSeed() on your own, but generators that don't have any seed won't do anything. Generators that return false for this method will generally behave differently when comparing how getNoiseWithSeed(float, float, long) changes the seed and how setSeed() does.
      Returns:
      whether setSeed(long) should be efficient to call in every getNoiseWithSeed(float, float, long) call

    • getNoise

      float getNoise(float x, float y)
      Gets 2D noise with a default or pre-set seed.
      Parameters:
      x - x position; can be any finite float
      y - y position; can be any finite float
      Returns:
      a noise value between -1.0f and 1.0f, both inclusive
      Throws:
      UnsupportedOperationException - if 2D noise cannot be produced by this generator

    • getNoise

      float getNoise(float x, float y, float z)
      Gets 3D noise with a default or pre-set seed.
      Parameters:
      x - x position; can be any finite float
      y - y position; can be any finite float
      z - z position; can be any finite float
      Returns:
      a noise value between -1.0f and 1.0f, both inclusive
      Throws:
      UnsupportedOperationException - if 3D noise cannot be produced by this generator

    • getNoise

      float getNoise(float x, float y, float z, float w)
      Gets 4D noise with a default or pre-set seed.
      Parameters:
      x - x position; can be any finite float
      y - y position; can be any finite float
      z - z position; can be any finite float
      w - w position; can be any finite float
      Returns:
      a noise value between -1.0f and 1.0f, both inclusive
      Throws:
      UnsupportedOperationException - if 4D noise cannot be produced by this generator

    • getNoise

      float getNoise(float x, float y, float z, float w, float u)
      Gets 5D noise with a default or pre-set seed.
      Parameters:
      x - x position; can be any finite float
      y - y position; can be any finite float
      z - z position; can be any finite float
      w - w position; can be any finite float
      u - u position; can be any finite float
      Returns:
      a noise value between -1.0f and 1.0f, both inclusive
      Throws:
      UnsupportedOperationException - if 5D noise cannot be produced by this generator

    • getNoise

      float getNoise(float x, float y, float z, float w, float u, float v)
      Gets 6D noise with a default or pre-set seed.
      Parameters:
      x - x position; can be any finite float
      y - y position; can be any finite float
      z - z position; can be any finite float
      w - w position; can be any finite float
      u - u position; can be any finite float
      v - v position; can be any finite float
      Returns:
      a noise value between -1.0f and 1.0f, both inclusive
      Throws:
      UnsupportedOperationException - if 6D noise cannot be produced by this generator

    • getNoise

      default float getNoise(float x, float y, float z, float w, float u, float v, float m)
      Gets 7D noise with a default or pre-set seed.
      Parameters:
      x - x position; can be any finite float
      y - y position; can be any finite float
      z - z position; can be any finite float
      w - w position; can be any finite float
      u - u position; can be any finite float
      v - v position; can be any finite float
      m - m position; can be any finite float
      Returns:
      a noise value between -1.0f and 1.0f, both inclusive
      Throws:
      UnsupportedOperationException - if 7D noise cannot be produced by this generator

    • setSeed

      void setSeed(long seed)
      Sets the seed to the given long, if long seeds are supported, or (int)seed if only int seeds are supported. If this generator cannot be seeded, this should do nothing, and should not throw an exception. If this operation allocates or is time-intensive, then hasEfficientSetSeed() should return false. That method is checked in getNoiseWithSeed(float, float, long), and if it returns false, the noise call will avoid calling setSeed(). You can always at least try to set the seed, even if it does nothing or is heavy on performance, and doing it a few times each frame should typically be fine for any generator. In the case this is called thousands of times each frame, check hasEfficientSetSeed().
      Parameters:
      seed - a long or int seed, with no restrictions unless otherwise documented

    • getSeed

      long getSeed()
      Gets the current seed of the generator, as a long even if the seed is stored internally as an int. This must be implemented, but if the generator doesn't have a seed that can be expressed as a long (potentially using BitConversion.floatToIntBits(float)), this can just return 0.
      Returns:
      the current seed, as a long

    • getTag

      default String getTag()
      Returns a typically-four-character String constant that should uniquely identify this INoise as well as possible. If a duplicate tag is already registered and INoise.Serializer.register(INoise) attempts to register the same tag again, a message is printed to System.err. The default implementation returns the String (NO), which is essentially an invalid tag, meant to indicate that this was not fully implemented. Implementing this is required for any usage of Serializer.
      Returns:
      a short String constant that identifies this INoise type

    • stringSerialize

      default String stringSerialize()
      Produces a String that describes everything needed to recreate this INoise in full. This String can be read back in by stringDeserialize(String) to reassign the described state to another INoise. The syntax here should always start and end with the ` character, which is used by stringDeserialize(String) to identify the portion of a String that can be read back. The ` character should not be otherwise used unless to serialize another INoise that this uses.
      If you use Base to produce String representations for numeric fields in an INoise, Base.BASE10 is strongly recommended; in most cases, you can just use string concatenation with the fields separated by the tilde character, "~". For printing a float field with Base to a StringBuilder sb, use Base.BASE10.appendGeneral(sb, field).
      The default implementation throws an UnsupportedOperationException only. INoise classes do not have to implement any serialization methods, but they aren't serializable by the methods in this class or in INoise.Serializer unless they do implement this, getTag(), stringDeserialize(String), and copy().
      Returns:
      a String that describes this INoise for serialization

    • stringDeserialize

      default INoise stringDeserialize(String data)
      Given a serialized String produced by stringSerialize(), reassigns this INoise to have the described state from the given String. The serialized String must have been produced by the same class as this object is.
      Any class that implements stringSerialize() should also implement this method in a compatible way. Using base-10 is expected for most uses. Using Base.BASE10.readFloat(data, start, end) may be useful to parse only the part of data between start and end.
      The default implementation throws an UnsupportedOperationException only. INoise classes do not have to implement any serialization methods, but they aren't serializable by the methods in this class or in INoise.Serializer unless they do implement this, getTag(), stringSerialize(), and copy().
      Parameters:
      data - a serialized String, typically produced by stringSerialize()
      Returns:
      this INoise, after being modified (if possible)

    • writeExternal

      default void writeExternal(ObjectOutput out) throws IOException
      The object implements the writeExternal method to save its contents by calling the methods of DataOutput for its primitive values or calling the writeObject method of ObjectOutput for objects, strings, and arrays.
      Specified by:
      writeExternal in interface Externalizable
      Parameters:
      out - the stream to write the object to
      Throws:
      IOException - Includes any I/O exceptions that may occur

    • readExternal

      default void readExternal(ObjectInput in) throws IOException
      The object implements the readExternal method to restore its contents by calling the methods of DataInput for primitive types and readObject for objects, strings and arrays. The readExternal method must read the values in the same sequence and with the same types as were written by writeExternal.
      Specified by:
      readExternal in interface Externalizable
      Parameters:
      in - the stream to read data from in order to restore the object
      Throws:
      IOException - if I/O errors occur

    • copy

      default INoise copy()
      Creates a copy of this INoise, which should be a deep copy for any mutable state but can be shallow for immutable types such as functions. This almost always just calls a copy constructor.
      The default implementation throws an UnsupportedOperationException only. Implementors are strongly encouraged to implement this in general, and that is required to use an INoise class with INoise.Serializer.
      Returns:
      a copy of this INoise

    • equals

      boolean equals(Object other)
      Overrides:
      equals in class Object

    • getNoiseWithSeed

      default float getNoiseWithSeed(float x, float y, long seed)
      Gets 2D noise with a specific seed. If the seed cannot be retrieved or changed per-call, then this falls back to changing the position instead of the seed; you can check if this will happen with hasEfficientSetSeed().
      Parameters:
      x - x position; can be any finite float
      y - y position; can be any finite float
      seed - can be any long
      Returns:
      a noise value between -1.0f and 1.0f, both inclusive
      Throws:
      UnsupportedOperationException - if 2D noise cannot be produced by this generator

    • getNoiseWithSeed

      default float getNoiseWithSeed(float x, float y, float z, long seed)
      Gets 3D noise with a specific seed. If the seed cannot be retrieved or changed per-call, then this falls back to changing the position instead of the seed; you can check if this will happen with hasEfficientSetSeed().
      Parameters:
      x - x position; can be any finite float
      y - y position; can be any finite float
      z - z position; can be any finite float
      seed - can be any long
      Returns:
      a noise value between -1.0f and 1.0f, both inclusive
      Throws:
      UnsupportedOperationException - if 3D noise cannot be produced by this generator

    • getNoiseWithSeed

      default float getNoiseWithSeed(float x, float y, float z, float w, long seed)
      Gets 4D noise with a specific seed. If the seed cannot be retrieved or changed per-call, then this falls back to changing the position instead of the seed; you can check if this will happen with hasEfficientSetSeed().
      Parameters:
      x - x position; can be any finite float
      y - y position; can be any finite float
      z - z position; can be any finite float
      w - w position; can be any finite float
      seed - can be any long
      Returns:
      a noise value between -1.0f and 1.0f, both inclusive
      Throws:
      UnsupportedOperationException - if 4D noise cannot be produced by this generator

    • getNoiseWithSeed

      default float getNoiseWithSeed(float x, float y, float z, float w, float u, long seed)
      Gets 5D noise with a specific seed. If the seed cannot be retrieved or changed per-call, then this falls back to changing the position instead of the seed; you can check if this will happen with hasEfficientSetSeed().
      Parameters:
      x - x position; can be any finite float
      y - y position; can be any finite float
      z - z position; can be any finite float
      w - w position; can be any finite float
      u - u position; can be any finite float
      seed - can be any long
      Returns:
      a noise value between -1.0f and 1.0f, both inclusive
      Throws:
      UnsupportedOperationException - if 5D noise cannot be produced by this generator

    • getNoiseWithSeed

      default float getNoiseWithSeed(float x, float y, float z, float w, float u, float v, long seed)
      Gets 6D noise with a specific seed. If the seed cannot be retrieved or changed per-call, then this falls back to changing the position instead of the seed; you can check if this will happen with hasEfficientSetSeed().
      Parameters:
      x - x position; can be any finite float
      y - y position; can be any finite float
      z - z position; can be any finite float
      w - w position; can be any finite float
      u - u position; can be any finite float
      v - v position; can be any finite float
      seed - can be any long
      Returns:
      a noise value between -1.0f and 1.0f, both inclusive
      Throws:
      UnsupportedOperationException - if 6D noise cannot be produced by this generator

    • getNoiseWithSeed

      default float getNoiseWithSeed(float x, float y, float z, float w, float u, float v, float m, long seed)
      Gets 7D noise with a specific seed. If the seed cannot be retrieved or changed per-call, then this falls back to changing the position instead of the seed; you can check if this will happen with hasEfficientSetSeed().
      Parameters:
      x - x position; can be any finite float
      y - y position; can be any finite float
      z - z position; can be any finite float
      w - w position; can be any finite float
      u - u position; can be any finite float
      v - v position; can be any finite float
      m - m position; can be any finite float
      seed - can be any long
      Returns:
      a noise value between -1.0f and 1.0f, both inclusive
      Throws:
      UnsupportedOperationException - if 7D noise cannot be produced by this generator