Class

GKNoiseMap

A sample of procedural noise data from which you can read noise values directly or create noise textures.

Declaration

class GKNoiseMap : NSObject

Overview

Working with procedural noise involves three main steps, one of each of the three major GameplayKit noise classes:

  1. Noise sources (the GKNoiseSource class cluster) represent the core algorithms and parameters for generating noise. You choose a general style of noise by instantiating and configuring one of the concrete GKNoiseSource subclasses.

  2. Noise objects (GKNoise instances) represent the field of noise generated by a noise source. You create a noise object from a noise source, and can then process it or combine it with other noise objects to create more complex noise patterns. Noise objects are lightweight: GameplayKit defers the computation of generating noise and applying noise processing operations until you’re ready to create output.

  3. GKNoiseMap objects are the concrete output of noise generation and processing. Creating a noise map performs the computation described by the GKNoiseSource and GKNoise objects you create it from, filling a 2D grid of a specific size with noise values based on a slice of the noise object’s 3D noise field.

You can apply noise maps in many different ways. Some examples include :

  • Creating texture images resembling natural phenomena such as clouds, stone surfaces, and wood grain. You can also use noise textures as normal maps to make surfaces appear more natural under lighting. (See the SKTexture init(noiseMap:) method.)

  • Generating procedural game-world maps resembling natural terrain. You can create game world of infinite size by using procedural noise as its underlying representation, and manage storage and memory efficiently by creating noise maps (and their visual representations) only for the area around a player’s current position. (See the SKTileMap class.)

  • Adding a degree of randomness to otherwise smooth movements. For example, you can make game characters move in a jittery manner, or apply a hand-held motion effect to a game camera.

The content of a noise map is a field of floating-point values that, by default, range from -1.0 to 1.0. You can access these values individually with the value(at:) and interpolatedValue(at:) methods, or create SpriteKit resources from the entire noise map’s values with the methods mentioned above.

A noise map is finite and two-dimensional, but the the noise you sample to create it is three-dimensional and infinite in extent. You can create interesting effects by transforming noise in three dimensions before creating a noise map. For example:

  • By using a cylindrical noise source and applying the rotate(by:) method, you can sample a slice through the cylinders that creates a wood-grain effect.

  • By using a Perlin noise source and applying the move(by:) method between multiple samples, you can animate a noise map that simulates the way clouds form, billow, and dissipate over time.

Figure 1

Example texture images generated from noise maps

Topics

Creating a Noise Map

init(GKNoise)

Initializes a noise map by sampling from the specified noise object.

init(GKNoise, size: vector_double2, origin: vector_double2, sampleCount: vector_int2, seamless: Bool)

Initializes a noise map by sampling from the specified noise object, with the specified parameters.

init()

Initializes a noise map with a constant noise value of zero throughout.

Accessing Noise Values

func value(at: vector_int2) -> Float

Returns the value at the specified position in the noise map’s discrete sample grid.

func interpolatedValue(at: vector_float2) -> Float

Returns the value at the specified position in the noise map, interpolating results for positions not on the discrete sample grid.

func setValue(Float, at: vector_int2)

Sets the value at the specified position in the noise map.

Inspecting a Noise Map

var size: vector_double2

The size of the “slice” of noise samples contained in the noise map relative to the unit coordinate space of the noise object it was created from.

var origin: vector_double2

The position of the “slice” of noise samples contained in the noise map relative to the unit coordinate space of the noise object it was created from.

var sampleCount: vector_int2

The width and height of integer grid for which the noise map contains sampled noise values.

var isSeamless: Bool

A Boolean value indicating whether the noise map’s output can repeat seamlessly in all directions.

Relationships

Inherits From

Conforms To

See Also

Procedural Noise

class GKNoiseSource

The abstract superclass for procedural noise generators.

class GKNoise

A representation of procedural noise, generated by a noise source, that you can use to process, transform, or combine noise.

class GKCoherentNoiseSource

The abstract superclass for procedural noise generators that create coherent noise.

class GKBillowNoiseSource

A procedural noise generator whose output is a type of fractal coherent noise with smooth features.

class GKPerlinNoiseSource

A procedural noise generator whose output is a type of fractal coherent noise resembling natural phenomena such as clouds and terrain.

class GKRidgedNoiseSource

A procedural noise generator whose output is a type of multifractal coherent noise with sharply defined features.

class GKVoronoiNoiseSource

A procedural noise generator whose output (also called Worley noise or cellular noise) divides space into discrete cells surrounding random seed points.

class GKCylindersNoiseSource

A procedural noise generator whose output is a 3D field of concentric cylindrical shells.

class GKSpheresNoiseSource

A procedural noise generator whose output is a 3D field of concentric spherical shells.

class GKCheckerboardNoiseSource

A procedural noise generator whose output is an alternating square pattern.

class GKConstantNoiseSource

A procedural noise generator that outputs a field of a single constant value.