source: project/wiki/eggref/4/noise @ 32116

Last change on this file since 32116 was 32116, checked in by acharlton, 7 years ago

wiki/noise: Formatting

File size: 6.9 KB
Line 
1== noise
2[[toc:]]
3noise implements several coherent noise generation functions for the GLSL. Each type of noise is implemented as a [[http://wiki.call-cc.org/eggref/4/glls|glls]] shader. While it is not necessary to use glls in your application, it is recommended since it makes things much easier. It is also entirely possible to use this library to create noise for an application that doesn’t otherwise use OpenGL. In this case, noise can be generated (very quickly!) on the GPU and then saved as a texture for access by the CPU. See the [[#examples|Examples]] section for an example of this.
4
5noise is indebted to Stefan Gustavson and Ashima Arts who created the highly optimized shaders that this library re-implements. You can see a description of these shaders [[https://github.com/ashima/webgl-noise/wiki|in their own words]].
6
7
8=== Requirements
9* glls
10
11
12=== Documentation
13The following sections describe the shaders that noise exports and the symbols that they, in turn, export.
14
15<constant> simplex-noise-2d</constant>
16
17'''Exports'''
18
19    (snoise (POSITION #:vec2)) -> #:float
20
21Given a 2D position, return the simplex noise value at that point.
22
23    (fractal-snoise (POSITION #:vec2) (OCTAVES #:int) (FREQUENCY #:float)
24                    (AMPLITUDE #:float) (PERSISTENCE #:float) (LACUNARITY #:float)
25         -> #:float
26
27Given a 2D position, return the fractal simplex noise value at that point. {{OCTAVES}} is the number of octaves of noise to sample, {{FREQUENCY}} is the frequency of the first octave, {{AMPLITUDE}} is the amplitude of the first octave, {{PERSISTENCE}} is the amount by which the frequency is scaled over each octave, {{LACUNARITY}} is the amount by which the amplitude is scaled over each octave.
28
29<constant> simplex-noise-3d</constant>
30
31'''Exports'''
32
33    (snoise (POSITION #:vec3)) -> #:float
34
35Given a 3D position, return the simplex noise value at that point.
36
37    (fractal-snoise (POSITION #:vec3) (OCTAVES #:int) (FREQUENCY #:float)
38                     (AMPLITUDE #:float) (PERSISTENCE #:float) (LACUNARITY #:float)
39         -> #:float
40
41Given a 3D position, return the fractal simplex noise value at that point. {{OCTAVES}} is the number of octaves of noise to sample, {{FREQUENCY}} is the frequency of the first octave, {{AMPLITUDE}} is the amplitude of the first octave, {{PERSISTENCE}} is the amount by which the frequency is scaled over each octave, {{LACUNARITY}} is the amount by which the amplitude is scaled over each octave
42
43<constant> simplex-noise-4d</constant>
44
45'''Exports'''
46
47    (snoise (POSITION #:vec4)) -> #:float
48
49Given a 4D position, return the simplex noise value at that point.
50
51    (fractal-snoise (POSITION #:vec4) (OCTAVES #:int) (FREQUENCY #:float)
52                    (AMPLITUDE #:float) (PERSISTENCE #:float) (LACUNARITY #:float)
53         -> #:float
54
55Given a 4D position, return the fractal simplex noise value at that point. {{OCTAVES}} is the number of octaves of noise to sample, {{FREQUENCY}} is the frequency of the first octave, {{AMPLITUDE}} is the amplitude of the first octave, {{PERSISTENCE}} is the amount by which the frequency is scaled over each octave, {{LACUNARITY}} is the amount by which the amplitude is scaled over each octave
56
57<constant> cell-noise-2d</constant>
58
59'''Exports'''
60
61    jitter -> #:float
62
63A variable that sets the amount of possible “jitter” for each feature point. Should be a value between 0.0 and 1.0, with 0.0 creating a regular grid of points and 1.0 creating the greatest randomness. If there are problems with discontinuities, decrease the jitter. Defaults to 0.9.
64
65    (cell-noise (POSITION #:vec2)) -> #:float
66
67Given a 2D position, return the distance to the nearest feature point. This is fast, but lower-quality than {{cell-noise2}}
68
69    (cell-noise2 (POSITION #:vec2)) -> #:vec2
70
71Given a 2D position, return the a vector containing the distance to the nearest feature point and second nearest feature point ({{(F1 F2)}}).
72
73<constant> cell-noise-3d</constant>
74
75'''Exports'''
76
77    jitter -> #:float
78
79A variable that sets the amount of possible “jitter” for each feature point. Should be a value between 0.0 and 1.0, with 0.0 creating a regular grid of points and 1.0 creating the greatest randomness. If there are problems with discontinuities, decrease the jitter. Defaults to 0.9.
80
81    (cell-noise (POSITION #:vec3)) -> #:float
82
83Given a 3D position, return the distance to the nearest feature point. This is fast, but lower-quality than {{cell-noise2}}
84
85    (cell-noise2 (POSITION #:vec3)) -> #:vec2
86
87Given a 3D position, return the a vector containing the distance to the nearest feature point and second nearest feature point ({{(F1 F2)}}).
88
89<constant> flow-nosie-2d</constant>
90
91'''Exports'''
92
93    isotropic -> #:bool
94
95A variable that controls whether the noise created is faster but less isotropic (set to {{#f}}) or slower but more isotropic (set to {{#t}}). Defaults to {{#f}}.
96
97    (flow-noise (POSITION (in #:vec2)) (ROTATION (in #:float)) (GRADIENT (out #:vec2))
98      -> #:float
99
100Given a 2D position and rotation, returns the value of the flow-noise at that point as well as the gradient (via {{GRADIENT}}).
101
102
103==== Shader source
104<string> simplex-noise-2d-source</string>
105<string> simplex-noise-3d-source</string>
106<string> simplex-noise-4d-source</string>
107<string> cell-noise-2d-source</string>
108<string> cell-noise-3d-source</string>
109<string> flow-noise-2d-source</string>
110
111The source for each shader is provided in these strings, in the case that the user does not want to directly use glls.
112
113
114=== Examples
115An example of the use of each type of noise can be seen in [[https://github.com/AlexCharlton/noise/tree/master/examples|the examples directory]]. These examples rely on [[http://wiki.call-cc.org/eggref/4/opengl-glew|opengl-glew]], [[http://wiki.call-cc.org/eggref/4/gl-math|gl-math]], [[http://wiki.call-cc.org/eggref/4/gl-utils|gl-utils]], and [[http://wiki.call-cc.org/eggref/4/glfw3|glfw3]]. They can either be run directly with {{csi}} or, since they use {{glls-render}}, they can be compiled by linking with GL (e.g. {{csc -lGL 2d-simplex.scm}}).
116
117It is important to note how the noise shaders are being imported in these examples: through [[http://wiki.call-cc.org/eggref/4/glls#shaders-that-export|glls’ {{use}} keyword]]. This makes it so that the prototypes from the noise shaders are automatically added to the examples’ fragment shaders.
118
119[[https://github.com/AlexCharlton/noise/tree/master/examples/render-to-texture.scm|The render-to-texture example]] provides an additional example to illustrate how noise can be captured to a texture via a framebuffer. With the noise in a texture, it can then be retrieved to RAM if access to the noise from the CPU is desired.
120
121
122=== Version history
123
124==== Version 0.1.0
125* Initial release
126
127
128=== Source repository
129Source available on [[https://github.com/AlexCharlton/noise|GitHub]].
130
131Bug reports and patches welcome! Bugs can be reported via GitHub or to alex.n.charlton at gmail.
132
133
134=== Author
135Alex Charlton
136
137
138=== License
139BSD
Note: See TracBrowser for help on using the repository browser.