Class

GKNoise

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

Declaration

@interface GKNoise : NSObject

Overview

Using procedural noise requires three steps:

  1. Select the GKNoiseSource subclass that generates the style of noise you’d like, and configure its properties to customize the noise generation algorithm.

  2. Create a GKNoise object from that noise source. A noise source generates a field of floating-point noise values between -1.0 and 1.0 across an infinite, three-dimensional domain—a noise object represents this field. Using GKNoise methods you can process the values in the noise field or combine values from multiple noise fields.

  3. Create a GKNoiseMap object from the noise object. A noise map samples values from a finite, two-dimensional slice of the noise field to create a concrete output. You can then read those values directly, use the SKTexture class to generate texture images, or use the SKTileMap class to generate tile maps.

GKNoise objects are lightweight. Because each noise object represents only a specific configuration of noise generation and processing steps, there’s little computation cost to creating noise objects from noise sources and applying operations to process, transform, or combine them. After you create noise objects and apply operations, creating a GKNoiseMap object from the resulting noise object performs only the computation needed to generate final output.

Colorizing and Combining Noise

A noise object doesn’t contain noise values or pixel color values for the noise field it describes. However, because you can combine multiple noise objects before producing colorized textures from the result, the gradientColors property specifies the colors that the SKTexture class uses to colorize output. For example, you can generate a realistic terrain texture by creating several styles of noise representing different biomes such as water, grassland, forests and mountains, each with their own color gradient, then combining them with the noiseWithComponentNoises:selectionNoise: method. The selectionNoise parameter to that method determines which biomes shows through in which regions of the final output, and each retains its own color gradient.

Topics

Creating Noise

- initWithNoiseSource:

Initializes a noise object with the specified noise source.

- initWithNoiseSource:gradientColors:

Initializes a noise object with the specified noise source, with colors for later use in generating noise textures.

+ noiseWithNoiseSource:

Creates a noise object with the specified noise source.

+ noiseWithNoiseSource:gradientColors:

Creates a noise object with the specified noise source, with colors for later use in generating noise textures.

Creating Noise by Combining Noise

+ noiseWithComponentNoises:selectionNoise:

Creates a noise object by combining the specified noise objects, using another noise object to select which regions of the output correspond to which input noise.

+ noiseWithComponentNoises:selectionNoise:componentBoundaries:boundaryBlendDistances:

Creates a noise object by combining the specified noise objects, using another noise object and the specified boundaries to select which regions of the output correspond to which input noise.

Colorizing Noise

gradientColors

A dictionary mapping noise values to colors for use in colorizing generated noise.

Applying Operations to Noise Values

- applyAbsoluteValue

Replaces all negative values in the noise field with their positive absolute values.

- invert

Replaces all values in the noise field with their opposite, reversing the range of noise values.

- raiseToPower:

Replaces all values in the noise field by raising each value to the specified power.

- clampWithLowerBound:upperBound:

Replaces values in the noise field outside the specified range with the values at the endpoints of that range.

- remapValuesToCurveWithControlPoints:

Replaces values in the noise field by mapping them to a curve that passes through the specified control points.

- remapValuesToTerracesWithPeaks:terracesInverted:

Replaces values in the noise field by mapping them to a terrace-like curve that passes through the specified control points.

Applying Operations that Combine Noise

- addWithNoise:

Replaces values in the noise field by adding them to values from the specified noise object.

- multiplyWithNoise:

Replaces values in the noise field by multiplying them with values from the specified noise object.

- raiseToPowerWithNoise:

Replaces values in the noise field by exponentiating them with values from the specified noise object.

- maximumWithNoise:

Replaces values in the noise field by choosing the lesser of each value and a corresponding value in the specified noise object.

- minimumWithNoise:

Replaces values in the noise field by choosing the lesser of each value and a corresponding value in the specified noise object.

Applying Operations that Distort Noise

- displaceXWithNoise:yWithNoise:zWithNoise:

Replaces values in the noise field by shifting each value along a vector whose x-, y-, and z-components are based on the specified noise objects.

- applyTurbulenceWithFrequency:power:roughness:seed:

Replaces values in the noise field by applying a randomized distortion effect.

Applying Geometric Transformations

- moveBy:

Translates the entire noise field by the specified x, y, and z offsets.

- rotateBy:

Rotates the entire noise field by the specified x, y, and z angles.

- scaleBy:

Scales the entire noise field by the specified x, y, and z factors.

Initializers

Instance Methods

Relationships

Inherits From

See Also

Procedural Noise

GKNoiseSource

The abstract superclass for procedural noise generators.

GKNoiseMap

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

GKCoherentNoiseSource

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

GKBillowNoiseSource

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

GKPerlinNoiseSource

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

GKRidgedNoiseSource

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

GKVoronoiNoiseSource

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

GKCylindersNoiseSource

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

GKSpheresNoiseSource

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

GKCheckerboardNoiseSource

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

GKConstantNoiseSource

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