source: project/wiki/eggref/5/noise @ 37384

Last change on this file since 37384 was 37384, checked in by Kooda, 3 years ago

Document noise for CHICKEN 5

File size: 6.9 KB
Line 
1
2== noise
3[[toc:]]
4noise implements several coherent noise generation functions for the GLSL. Each type of noise is implemented as a [[https://wiki.call-cc.org/egg/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.
5
6noise 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]].
7
8
9=== Requirements
10* glls
11
12
13=== Documentation
14The following sections describe the shaders that noise exports and the symbols that they, in turn, export.
15
16<constant> simplex-noise-2d</constant>
17
18'''Exports'''
19
20    (snoise (POSITION #:vec2)) -> #:float
21
22Given a 2D position, return the simplex noise value at that point.
23
24    (fractal-snoise (POSITION #:vec2) (OCTAVES #:int) (FREQUENCY #:float)
25                    (AMPLITUDE #:float) (PERSISTENCE #:float) (LACUNARITY #:float)
26         -> #:float
27
28Given 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.
29
30<constant> simplex-noise-3d</constant>
31
32'''Exports'''
33
34    (snoise (POSITION #:vec3)) -> #:float
35
36Given a 3D position, return the simplex noise value at that point.
37
38    (fractal-snoise (POSITION #:vec3) (OCTAVES #:int) (FREQUENCY #:float)
39                     (AMPLITUDE #:float) (PERSISTENCE #:float) (LACUNARITY #:float)
40         -> #:float
41
42Given 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
43
44<constant> simplex-noise-4d</constant>
45
46'''Exports'''
47
48    (snoise (POSITION #:vec4)) -> #:float
49
50Given a 4D position, return the simplex noise value at that point.
51
52    (fractal-snoise (POSITION #:vec4) (OCTAVES #:int) (FREQUENCY #:float)
53                    (AMPLITUDE #:float) (PERSISTENCE #:float) (LACUNARITY #:float)
54         -> #:float
55
56Given 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
57
58<constant> cell-noise-2d</constant>
59
60'''Exports'''
61
62    jitter -> #:float
63
64A 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.
65
66    (cell-noise (POSITION #:vec2)) -> #:float
67
68Given a 2D position, return the distance to the nearest feature point. This is fast, but lower-quality than {{cell-noise2}}
69
70    (cell-noise2 (POSITION #:vec2)) -> #:vec2
71
72Given a 2D position, return the a vector containing the distance to the nearest feature point and second nearest feature point ({{(F1 F2)}}).
73
74<constant> cell-noise-3d</constant>
75
76'''Exports'''
77
78    jitter -> #:float
79
80A 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.
81
82    (cell-noise (POSITION #:vec3)) -> #:float
83
84Given a 3D position, return the distance to the nearest feature point. This is fast, but lower-quality than {{cell-noise2}}
85
86    (cell-noise2 (POSITION #:vec3)) -> #:vec2
87
88Given a 3D position, return the a vector containing the distance to the nearest feature point and second nearest feature point ({{(F1 F2)}}).
89
90<constant> flow-nosie-2d</constant>
91
92'''Exports'''
93
94    isotropic -> #:bool
95
96A 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}}.
97
98    (flow-noise (POSITION (in #:vec2)) (ROTATION (in #:float)) (GRADIENT (out #:vec2))
99      -> #:float
100
101Given a 2D position and rotation, returns the value of the flow-noise at that point as well as the gradient (via {{GRADIENT}}).
102
103
104==== Shader source
105<string> simplex-noise-2d-source</string>
106<string> simplex-noise-3d-source</string>
107<string> simplex-noise-4d-source</string>
108<string> cell-noise-2d-source</string>
109<string> cell-noise-3d-source</string>
110<string> flow-noise-2d-source</string>
111
112The source for each shader is provided in these strings, in the case that the user does not want to directly use glls.
113
114
115=== Examples
116An example of the use of each type of noise can be seen in [[https://www.upyum.com/cgit.cgi/noise/tree/examples|the examples directory]]. These examples rely on [[https://wiki.call-cc.org/egg/epoxy|epoxy]], [[https://wiki.call-cc.org/egg/gl-math|gl-math]], [[https://wiki.call-cc.org/egg/gl-utils|gl-utils]], and [[https://wiki.call-cc.org/egg/glfw3|glfw3]]. They can either be run directly with {{csi}} or, since they use {{glls-render}}, they can be compiled by linking with libepoxy (e.g. {{csc -L -lepoxy 2d-simplex.scm}}).
117
118It is important to note how the noise shaders are being imported in these examples: through [[https://wiki.call-cc.org/egg/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.
119
120[[https://www.upyum.com/cgit.cgi/noise/tree/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.
121
122
123=== Version history
124
125==== Version 0.2.0
126* Maintenance given to [[/users/kooda|Kooda]]
127* Port to CHICKEN 5
128
129
130==== Version 0.1.0
131* Initial release
132
133
134=== Source repository
135Source available [[https://www.upyum.com/cgit.cgi/noise/|here]].
136
137Bug reports and patches welcome! Bugs can be reported to kooda@upyum.com
138
139
140=== Authors
141Alex Charlton
142
143Adrien (Kooda) Ramos
144
145
146=== License
147BSD
148
Note: See TracBrowser for help on using the repository browser.