Class BitNoise

java.lang.Object
com.github.yellowstonegames.grid.BitNoise
All Implemented Interfaces:
INoise, Externalizable, Serializable
public class BitNoise extends Object implements INoise
An unusual kind of INoise that typically only outputs -1 or 1, for cases where you want binary results of blobby noise, but can also produce more bits if constructed as such. If you shift the noise around and have multiple calls, you can use this to get approximately fair distributions of bits by getting just the sign bit from each -1 or 1 result and concatenating bits to make a 2-bit, 3-bit, etc. value.
In SquidLib, this was called MerlinNoise, and acted similarly. (Merlin because I felt like a wizard writing it.)
See Also:

  • Nested Class Summary

    Nested classes/interfaces inherited from interface INoise

    INoise.Serializer

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected int
    bits
     
    protected int
    resolution
     
    long
    seed
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    BitNoise()
    Constructor for a default BitNoise instance with 1-bit output and resolution 3 (yielding 8x8-cell zones that share their corners).
    BitNoise(long seed, int bits, int resolution)
    Constructor for a BitNoise instance that allows specification of all parameters.

  • Method Summary

    Modifier and Type
    Method
    Description
    BitNoise
    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.
    final boolean
    equals(Object o)
     
    int
    getBits()
     
    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.
    float
    getNoiseWithSeed(float x, float y, float z, float w, float u, float v, long seed)
    Gets 6D noise with a specific seed.
    float
    getNoiseWithSeed(float x, float y, float z, float w, float u, long seed)
    Gets 5D noise with a specific seed.
    float
    getNoiseWithSeed(float x, float y, float z, float w, long seed)
    Gets 4D noise with a specific seed.
    float
    getNoiseWithSeed(float x, float y, float z, long seed)
    Gets 3D noise with a specific seed.
    float
    getNoiseWithSeed(float x, float y, long seed)
    Gets 2D noise with a specific seed.
    int
    getResolution()
     
    long
    getSeed()
    Gets the current seed of the generator, as a long even if the seed is stored internally as an int.
    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 INoise.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.
    int
    hashCode()
     
    long
    noise2D(long x, long y)
    2D bit noise; black and white much of the time but curving instead of angular.
    long
    noise2D(long x, long y, long seed)
    2D bit noise; black and white much of the time but curving instead of angular.
    static long
    noise2D(long x, long y, long state, int resolution, int bits)
    2D bit noise; black and white much of the time but curving instead of angular.
    long
    noise3D(long x, long y, long z)
    3D bit noise; black and white much of the time but curving instead of angular.
    long
    noise3D(long x, long y, long z, long seed)
    3D bit noise; black and white much of the time but curving instead of angular.
    static long
    noise3D(long x, long y, long z, long state, int resolution, int bits)
    3D bit noise.
    long
    noise4D(long x, long y, long z, long w)
    4D bit noise; black and white much of the time but curving instead of angular.
    long
    noise4D(long x, long y, long z, long w, long seed)
    4D bit noise; black and white much of the time but curving instead of angular.
    static long
    noise4D(long x, long y, long z, long w, long state, int resolution, int bits)
    4D bit noise.
    long
    noise5D(long x, long y, long z, long w, long u)
    5D bit noise; black and white much of the time but curving instead of angular.
    long
    noise5D(long x, long y, long z, long w, long u, long seed)
    5D bit noise; black and white much of the time but curving instead of angular.
    static long
    noise5D(long x, long y, long z, long w, long u, long state, int resolution, int bits)
    5D bit noise.
    long
    noise6D(long x, long y, long z, long w, long u, long v)
    6D bit noise; black and white much of the time but curving instead of angular.
    long
    noise6D(long x, long y, long z, long w, long u, long v, long seed)
    6D bit noise; black and white much of the time but curving instead of angular.
    static long
    noise6D(long x, long y, long z, long w, long u, long v, long state, int resolution, int bits)
    6D bit noise.
    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.
    static BitNoise
    recreateFromString(String data)
     
    void
    setBits(int bits)
    Sets the number of bits this will output; 8 is common to produce byte-sized values between 0 and 255.
    void
    setResolution(int resolution)
    Sets the resolution, which is an exponent that determines the width/height of each zone that shares the same four corners (where only the corners have their own hashed values).
    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.
    BitNoise
    stringDeserialize(String data)
    Given a serialized String produced by stringSerialize(), reassigns this PerlinNoise to have the described state from the given String.
    String
    stringSerialize()
    Produces a String that describes everything needed to recreate this INoise in full.
    String
    toString()
     
    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.

    Methods inherited from class Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

    Methods inherited from interface INoise

    getNoise, getNoiseWithSeed

  • Field Details

    • seed

      public long seed

    • bits

      protected int bits

    • resolution

      protected int resolution

  • Constructor Details

    • BitNoise

      public BitNoise()
      Constructor for a default BitNoise instance with 1-bit output and resolution 3 (yielding 8x8-cell zones that share their corners). The seed can be set at any point, but it will start at 1.

    • BitNoise

      public BitNoise(long seed, int bits, int resolution)
      Constructor for a BitNoise instance that allows specification of all parameters.
      Parameters:
      seed - the seed to use to alter the generated noise in noise2D(long, long) and noise3D(long, long, long)
      bits - the number of bits to output; typically 1 to produce only -1 or 1
      resolution - an exponent that determines the size of a "zone" of cells that blend between the values at the zone's corners; commonly 1-6

  • Method Details

    • hasEfficientSetSeed

      public boolean hasEfficientSetSeed()
      Description copied from interface: INoise
      Returns true if this generator can be seeded with INoise.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 INoise.getNoiseWithSeed(float, float, long) changes the seed and how setSeed() does.
      Specified by:
      hasEfficientSetSeed in interface INoise
      Returns:
      whether INoise.setSeed(long) should be efficient to call in every INoise.getNoiseWithSeed(float, float, long) call

    • getSeed

      public long getSeed()
      Description copied from interface: INoise
      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.
      Specified by:
      getSeed in interface INoise
      Returns:
      the current seed, as a long

    • setSeed

      public void setSeed(long seed)
      Description copied from interface: INoise
      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 INoise.hasEfficientSetSeed() should return false. That method is checked in INoise.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 INoise.hasEfficientSetSeed().
      Specified by:
      setSeed in interface INoise
      Parameters:
      seed - a long or int seed, with no restrictions unless otherwise documented

    • getBits

      public int getBits()

    • setBits

      public void setBits(int bits)
      Sets the number of bits this will output; 8 is common to produce byte-sized values between 0 and 255. This value can be between 1 and 64. If bits is 8, then this should produce values of 255 or 0, plus or minus 1. If bits is some other value, then it may produce more than two values, or only produce one.
      Parameters:
      bits - the number of bits of output each call should generate.

    • getResolution

      public int getResolution()

    • setResolution

      public void setResolution(int resolution)
      Sets the resolution, which is an exponent that determines the width/height of each zone that shares the same four corners (where only the corners have their own hashed values). If resolution is 1, the size of a zone is 2x2, if it is 2, then the size of a zone is 4x4, if it is 3, then 8x8, and so on by powers of 2. The resolution can be as low as 0 (which won't blend corners' hashes at all) or as high as 63, but cannot easily be increased above that (10 is a really large size for a cell at 1024x1024, and 63 is over 9 quintillion square). This doesn't slow down significantly (or at all) if resolution is particularly high or low, but this is often between 1 and 6.
      Parameters:
      resolution - an int between 0 and 63

    • noise2D

      public long noise2D(long x, long y)
      2D bit noise; black and white much of the time but curving instead of angular.
      Parameters:
      x - x input
      y - y input

    • noise2D

      public long noise2D(long x, long y, long seed)
      2D bit noise; black and white much of the time but curving instead of angular.
      Parameters:
      x - x input
      y - y input
      seed - the seed to use to alter the generated noise

    • noise3D

      public long noise3D(long x, long y, long z)
      3D bit noise; black and white much of the time but curving instead of angular.
      Parameters:
      x - x input
      y - y input
      z - z input

    • noise3D

      public long noise3D(long x, long y, long z, long seed)
      3D bit noise; black and white much of the time but curving instead of angular.
      Parameters:
      x - x input
      y - y input
      z - z input
      seed - the seed to use to alter the generated noise

    • noise4D

      public long noise4D(long x, long y, long z, long w)
      4D bit noise; black and white much of the time but curving instead of angular.
      Parameters:
      x - x input
      y - y input
      z - z input
      w - w input

    • noise4D

      public long noise4D(long x, long y, long z, long w, long seed)
      4D bit noise; black and white much of the time but curving instead of angular.
      Parameters:
      x - x input
      y - y input
      z - z input
      w - w input
      seed - the seed to use to alter the generated noise

    • noise5D

      public long noise5D(long x, long y, long z, long w, long u)
      5D bit noise; black and white much of the time but curving instead of angular.
      Parameters:
      x - x input
      y - y input
      z - z input
      w - w input
      u - u input

    • noise5D

      public long noise5D(long x, long y, long z, long w, long u, long seed)
      5D bit noise; black and white much of the time but curving instead of angular.
      Parameters:
      x - x input
      y - y input
      z - z input
      w - w input
      u - u input
      seed - the seed to use to alter the generated noise

    • noise6D

      public long noise6D(long x, long y, long z, long w, long u, long v)
      6D bit noise; black and white much of the time but curving instead of angular.
      Parameters:
      x - x input
      y - y input
      z - z input
      w - w input
      u - u input
      v - v input

    • noise6D

      public long noise6D(long x, long y, long z, long w, long u, long v, long seed)
      6D bit noise; black and white much of the time but curving instead of angular.
      Parameters:
      x - x input
      y - y input
      z - z input
      w - w input
      u - u input
      v - v input
      seed - the seed to use to alter the generated noise

    • noise2D

      public static long noise2D(long x, long y, long state, int resolution, int bits)
      2D bit noise; black and white much of the time but curving instead of angular.
      Parameters:
      x - x input
      y - y input
      state - state to adjust the output
      resolution - the number of cells between "vertices" where one hashed value is used fully
      bits - how many bits should be used for each (signed long) output; often this is 8 to output a byte
      Returns:
      noise from -(1L << bits) to (1L << bits) - 1L, both inclusive

    • noise3D

      public static long noise3D(long x, long y, long z, long state, int resolution, int bits)
      3D bit noise.
      Parameters:
      x - x input
      y - y input
      z - z input
      state - state to adjust the output
      resolution - the number of cells between "vertices" where one hashed value is used fully
      bits - how many bits should be used for each (signed long) output; often this is 8 to output a byte
      Returns:
      noise from -(1L << bits) to (1L << bits) - 1L, both inclusive

    • noise4D

      public static long noise4D(long x, long y, long z, long w, long state, int resolution, int bits)
      4D bit noise.
      Parameters:
      x - x input
      y - y input
      z - z input
      w - w input
      state - state to adjust the output
      resolution - the number of cells between "vertices" where one hashed value is used fully
      bits - how many bits should be used for each (signed long) output; often this is 8 to output a byte
      Returns:
      noise from -(1L << bits) to (1L << bits) - 1L, both inclusive

    • noise5D

      public static long noise5D(long x, long y, long z, long w, long u, long state, int resolution, int bits)
      5D bit noise.
      Parameters:
      x - x input
      y - y input
      z - z input
      w - w input
      u - u input
      state - state to adjust the output
      resolution - the number of cells between "vertices" where one hashed value is used fully
      bits - how many bits should be used for each (signed long) output; often this is 8 to output a byte
      Returns:
      noise from -(1L << bits) to (1L << bits) - 1L, both inclusive

    • noise6D

      public static long noise6D(long x, long y, long z, long w, long u, long v, long state, int resolution, int bits)
      6D bit noise.
      Parameters:
      x - x input
      y - y input
      z - z input
      w - w input
      u - u input
      v - v input
      state - state to adjust the output
      resolution - the number of cells between "vertices" where one hashed value is used fully
      bits - how many bits should be used for each (signed long) output; often this is 8 to output a byte
      Returns:
      noise from -(1L << bits) to (1L << bits) - 1L, both inclusive

    • getNoise

      public float getNoise(float x, float y)
      Description copied from interface: INoise
      Gets 2D noise with a default or pre-set seed.
      Specified by:
      getNoise in interface INoise
      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

    • getNoiseWithSeed

      public float getNoiseWithSeed(float x, float y, long seed)
      Description copied from interface: INoise
      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 INoise.hasEfficientSetSeed().
      Specified by:
      getNoiseWithSeed in interface INoise
      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

    • getNoise

      public float getNoise(float x, float y, float z)
      Description copied from interface: INoise
      Gets 3D noise with a default or pre-set seed.
      Specified by:
      getNoise in interface INoise
      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

    • getNoiseWithSeed

      public float getNoiseWithSeed(float x, float y, float z, long seed)
      Description copied from interface: INoise
      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 INoise.hasEfficientSetSeed().
      Specified by:
      getNoiseWithSeed in interface INoise
      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

    • getNoise

      public float getNoise(float x, float y, float z, float w)
      Description copied from interface: INoise
      Gets 4D noise with a default or pre-set seed.
      Specified by:
      getNoise in interface INoise
      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

    • getNoiseWithSeed

      public float getNoiseWithSeed(float x, float y, float z, float w, long seed)
      Description copied from interface: INoise
      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 INoise.hasEfficientSetSeed().
      Specified by:
      getNoiseWithSeed in interface INoise
      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

    • getNoise

      public float getNoise(float x, float y, float z, float w, float u)
      Description copied from interface: INoise
      Gets 5D noise with a default or pre-set seed.
      Specified by:
      getNoise in interface INoise
      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

    • getNoiseWithSeed

      public float getNoiseWithSeed(float x, float y, float z, float w, float u, long seed)
      Description copied from interface: INoise
      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 INoise.hasEfficientSetSeed().
      Specified by:
      getNoiseWithSeed in interface INoise
      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

    • getNoise

      public float getNoise(float x, float y, float z, float w, float u, float v)
      Description copied from interface: INoise
      Gets 6D noise with a default or pre-set seed.
      Specified by:
      getNoise in interface INoise
      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

    • getNoiseWithSeed

      public float getNoiseWithSeed(float x, float y, float z, float w, float u, float v, long seed)
      Description copied from interface: INoise
      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 INoise.hasEfficientSetSeed().
      Specified by:
      getNoiseWithSeed in interface INoise
      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

    • getMinDimension

      public int getMinDimension()
      Description copied from interface: INoise
      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.
      Specified by:
      getMinDimension in interface INoise
      Returns:
      the minimum supported dimension, from 2 to 7 inclusive

    • getMaxDimension

      public int getMaxDimension()
      Description copied from interface: INoise
      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).
      Specified by:
      getMaxDimension in interface INoise
      Returns:
      the maximum supported dimension, from 2 to 7 inclusive

    • getTag

      public String getTag()
      Description copied from interface: INoise
      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.
      Specified by:
      getTag in interface INoise
      Returns:
      a short String constant that identifies this INoise type

    • stringSerialize

      public 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.
      Specified by:
      stringSerialize in interface INoise
      Returns:
      a String that describes this PerlinNoise for serialization

    • stringDeserialize

      public BitNoise stringDeserialize(String data)
      Given a serialized String produced by stringSerialize(), reassigns this PerlinNoise to have the described state from the given String. The serialized String must have been produced by a PerlinNoise.
      Specified by:
      stringDeserialize in interface INoise
      Parameters:
      data - a serialized String, typically produced by stringSerialize()
      Returns:
      this PerlinNoise, after being modified (if possible)

    • recreateFromString

      public static BitNoise recreateFromString(String data)

    • writeExternal

      public void writeExternal(ObjectOutput out) throws IOException
      Description copied from interface: INoise
      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
      Specified by:
      writeExternal in interface INoise
      Parameters:
      out - the stream to write the object to
      Throws:
      IOException - Includes any I/O exceptions that may occur

    • readExternal

      public void readExternal(ObjectInput in) throws IOException
      Description copied from interface: INoise
      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
      Specified by:
      readExternal in interface INoise
      Parameters:
      in - the stream to read data from in order to restore the object
      Throws:
      IOException - if I/O errors occur

    • copy

      public BitNoise copy()
      Description copied from interface: INoise
      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.
      Specified by:
      copy in interface INoise
      Returns:
      a copy of this INoise

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • equals

      public final boolean equals(Object o)
      Specified by:
      equals in interface INoise
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object