git.iko.soy/elk
on master help sign in
Imported and organized MJS docs. Added to Graphics.WebGL docs
42ae81aJohn P Mayer Jr
libraries/Graphics/WebGL.elm+31−14
compare with master
unifiedsplit
@@ -1,4 +1,4 @@
1−module Graphics.WebGL (mapTriangle, zipTriangle, loadTex, model, webgl) where
1+module Graphics.WebGL (Triangle, Shader, mapTriangle, zipTriangle, unsafeCoerceGLSL, loadTex, model, webgl) where
2
2
3{-| The WebGL API is for high performance drawing.
3{-| The WebGL API is for high performance drawing.
4
4
@@ -6,23 +6,40 @@ module Graphics.WebGL (mapTriangle, zipTriangle, loadTex, model, webgl) where
6@docs Triangle, mapTriangle, zipTriangle
6@docs Triangle, mapTriangle, zipTriangle
7
7
8# Shaders
8# Shaders
9−Shaders are created using glsl blocks.
9+@docs Shader
10+
11+Shaders are created using inline GLSL blocks. The type of the Shader is determined by the top-level attribute, uniform, and varying declarations of the parsed GLSL source code. The type parameters to Shader are records with field names matching the names of the declarations.
10
12
11```haskell
13```haskell
12−vertex : Shader { a | pos : V3 } {} {}
14+vertex : Shader { a | pos : V3 } { b | model : M4x4 } {}
13vertex = [glsl|
15vertex = [glsl|
14
16
15attribute vec3 pos;
17attribute vec3 pos;
18+uniform mat4 model;
16
19
17void main () {
20void main () {
18− gl_Position = vec4(pos,1.0);
21+ gl_Position = model * vec4(pos,1.0);
19}
22}
20
23
21\]
24\]
22```
25```
23
26
27+GLSL attribute variables are per-vertex values. For example, it could hold the position or color of a specific vertex of a specific triangle in your model.
28+
29+GLSL uniform variables are global values which will be applied for all vertices of all triangles of the model.
30+
31+GLSL varying variables are shared between stages; they are output variables for vertex shaders, and input variables for fragment shaders.
32+
33+@docs unsafeCoerceGLSL
34+
35+# Loading Textures
36+@docs loadTex
37+
38+# Packaging Models
39+@docs model
40+
24# WebGL Element
41# WebGL Element
25−@docs loadTex, model, webgl
42+@docs webgl
26
43
27-}
44-}
28
45
@@ -31,9 +48,6 @@ import Http (Response)
31import Native.Graphics.WebGL
48import Native.Graphics.WebGL
32import Signal (Signal)
49import Signal (Signal)
33
50
34−unsafeCoerceGLSL : String -> Shader attr unif vary
35−unsafeCoerceGLSL = Native.Graphics.WebGL.unsafeCoerceGLSL
36−
37{-| Triangles are only homogenous 3-tuples. Each element describes something about each vertex, and must be a record to be used with GLSL shaders.
51{-| Triangles are only homogenous 3-tuples. Each element describes something about each vertex, and must be a record to be used with GLSL shaders.
38-}
52-}
39type Triangle a = (a,a,a)
53type Triangle a = (a,a,a)
@@ -46,21 +60,24 @@ mapTriangle f (x,y,z) = (f x, f y, f z)
46zipTriangle : (a -> b -> c) -> Triangle a -> Triangle b -> Triangle c
60zipTriangle : (a -> b -> c) -> Triangle a -> Triangle b -> Triangle c
47zipTriangle f (x,y,z) (x',y',z') = (f x x', f y y', f z z')
61zipTriangle f (x,y,z) (x',y',z') = (f x x', f y y', f z z')
48
62
49−{-| Opaque Shader Type -}
50data Shader attr unif vary = Shader
63data Shader attr unif vary = Shader
51
64
52−{-| Opaque Texture Type -}
65+{-| Libary writers can use this function to create shader combinators. -}
66+unsafeCoerceGLSL : String -> Shader attribute uniform varying
67+unsafeCoerceGLSL = Native.Graphics.WebGL.unsafeCoerceGLSL
68+
53data Texture = Texture
69data Texture = Texture
54
70
55−{-| Load an image url as a texture -}
71+{-| Loads a texture from the given url. PNG and JPEG are the preferred and tested-compatible source image format. -}
56loadTex : String -> Signal (Response Texture)
72loadTex : String -> Signal (Response Texture)
57loadTex = Native.Graphics.WebGL.loadTex
73loadTex = Native.Graphics.WebGL.loadTex
58
74
59−{-| Opaque Model Type -}
60data Model = Model
75data Model = Model
61
76
62−{-| A model is a collection of a fragment shader, a vertex shader, attribute data, and uniform data. -}
77+{-| Packages a vertex shader, a fragment shader, triangle data, and uniform variables as a opaque Model.
78+This is a simple container; however, externally there is no type information.
79+-}
63−model : Shader attr unif vary -> Shader {} unif vary -> [Triangle attr] -> unif -> Model
80+model : Shader attribute uniform varying -> Shader {} uniform varying -> [Triangle attribute] -> uniform -> Model
64model = Native.Graphics.WebGL.model
81model = Native.Graphics.WebGL.model
65
82
66{-| Render a WebGL scene with the given dimensions and models -}
83{-| Render a WebGL scene with the given dimensions and models -}
libraries/MJS.elm+174−9
@@ -8,6 +8,30 @@ and use with Graphics.WebGL.
8
8
9Both vectors and matrices are immutable.
9Both vectors and matrices are immutable.
10
10
11+# Constructing and Destructing Vectors
12+
13+@docs v3, toTuple3
14+
15+# Vector Math
16+
17+@docs add, sub, neg, direction, length, lengthSquared, normalize, scale
18+
19+# Vector Operations
20+
21+@docs dot, cross, mul4x4
22+
23+Matrix operations
24+
25+@docs identity, inverseOrthonormal, mul, mulAffine, transpose, makeBasis
26+
27+Matrix projections
28+
29+@docs makeFrustrum, makePerspective, makeOrtho, makeOrtho2D, makeLookAt
30+
31+Matrix transforms
32+
33+@docs makeRotate, rotate, makeScale3, makeScale, scaleM3, scaleM, makeTranslate3, makeTranslate, translate3, translate
34+
11-}
35-}
12
36
13import Native.MJS
37import Native.MJS
@@ -15,115 +39,256 @@ import Native.MJS
15data V2 = V2
39data V2 = V2
16data V3 = V3
40data V3 = V3
17data V4 = V4
41data V4 = V4
18−data M4x4 = M4x4
19
42
43+{-|
44+Creates a new 3-element vector with the given values
45+-}
20v3 : Float -> Float -> Float -> V3
46v3 : Float -> Float -> Float -> V3
21v3 = Native.MJS.v3
47v3 = Native.MJS.v3
22
48
49+{-|
50+Convert to a native tuple
51+-}
23toTuple3 : V3 -> (Float,Float,Float)
52toTuple3 : V3 -> (Float,Float,Float)
24toTuple3 = Native.MJS.toTuple3
53toTuple3 = Native.MJS.toTuple3
25
54
55+{-|
56+Vector addition: a + b
57+-}
26add : V3 -> V3 -> V3
58add : V3 -> V3 -> V3
27add = Native.MJS.v3add
59add = Native.MJS.v3add
28
60
61+{-|
62+Vector subtraction: a - b
63+-}
29sub : V3 -> V3 -> V3
64sub : V3 -> V3 -> V3
30sub = Native.MJS.v3sub
65sub = Native.MJS.v3sub
31
66
67+{-|
68+Vector negation: -a
69+-}
32neg : V3 -> V3
70neg : V3 -> V3
33neg = Native.MJS.v3neg
71neg = Native.MJS.v3neg
34
72
73+{-|
35−{- The normalized direction from v1 to v2 -}
74+The normalized direction from a to b: (a - b) / |a - b|
75+-}
36direction : V3 -> V3 -> V3
76direction : V3 -> V3 -> V3
37direction = Native.MJS.v3direction
77direction = Native.MJS.v3direction
38
78
79+{-|
80+The length of the given vector: |a|
81+-}
39length : V3 -> Float
82length : V3 -> Float
40length = Native.MJS.v3length
83length = Native.MJS.v3length
41
84
85+{-|
86+The square of the length of the given vector: |a|*|a|
87+-}
42lengthSquared : V3 -> Float
88lengthSquared : V3 -> Float
43lengthSquared = Native.MJS.v3lengthSquared
89lengthSquared = Native.MJS.v3lengthSquared
44
90
91+{-|
92+A unit vector with the same direction as the given vector: a / |a|
93+-}
45normalize : V3 -> V3
94normalize : V3 -> V3
46normalize = Native.MJS.v3normalize
95normalize = Native.MJS.v3normalize
47
96
97+{-|
98+Multiply the vector by a scalar: a * k
99+-}
48scale : V3 -> Float -> V3
100scale : V3 -> Float -> V3
49scale = Native.MJS.v3scale
101scale = Native.MJS.v3scale
50
102
103+{-|
104+The dot product of a and b
105+-}
51dot : V3 -> V3 -> Float
106dot : V3 -> V3 -> Float
52dot = Native.MJS.v3dot
107dot = Native.MJS.v3dot
53
108
109+{-|
110+The cross product of a and b
111+-}
54cross : V3 -> V3 -> V3
112cross : V3 -> V3 -> V3
55cross = Native.MJS.v3cross
113cross = Native.MJS.v3cross
56
114
115+{-|
116+Methods for working with 4x4 matrices.
117+-}
118+data M4x4 = M4x4
119+
120+{-|
121+Multiple the vector by the 4x4 matrix: m * v
122+-}
57mul4x4 : M4x4 -> V3 -> V3
123mul4x4 : M4x4 -> V3 -> V3
58mul4x4 = Native.MJS.v3mul4x4
124mul4x4 = Native.MJS.v3mul4x4
59
125
60−--m4x4 : V3[16] -> M4x4 ?
126+{-|
61−
127+A matrix with all 0s, except 1s on the diagonal
128+-}
62identity : M4x4
129identity : M4x4
63identity = Native.MJS.m4x4identity
130identity = Native.MJS.m4x4identity
64
131
65−--topLeft3x3 : M4x4 -> M3x3 ?
132+{-|
66−
133+Computes the inverse of the given matrix m, assuming that
67−{- Assumes that m is orthonormal -}
134+the matrix is orthonormal
135+-}
68inverseOrthonormal : M4x4 -> M4x4
136inverseOrthonormal : M4x4 -> M4x4
69inverseOrthonormal = Native.MJS.m4x4inverseOrthonormal
137inverseOrthonormal = Native.MJS.m4x4inverseOrthonormal
70
138
71−--inverseTo3x3 : M4x4 -> M3x3 ?
139+{-|
140+Creates a matrix for a projection frustum with the given parameters.
141+
142+Parameters:
72
143
144+ left - the left coordinate of the frustum
145+ right- the right coordinate of the frustum
146+ bottom - the bottom coordinate of the frustum
147+ top - the top coordinate of the frustum
148+ znear - the near z distance of the frustum
149+ zfar - the far z distance of the frustum
150+-}
73makeFrustrum : Float -> Float -> Float -> Float -> Float -> Float -> Float -> M4x4
151makeFrustrum : Float -> Float -> Float -> Float -> Float -> Float -> Float -> M4x4
74makeFrustrum = Native.MJS.m4x4makeFrustrum
152makeFrustrum = Native.MJS.m4x4makeFrustrum
75
153
154+{-|
155+Creates a matrix for a perspective projection with the given parameters.
156+
157+Parameters:
158+
159+ fovy - field of view in the y axis, in degrees
160+ aspect - aspect ratio
161+ znear - the near z distance of the projection
162+ zfar - the far z distance of the projection
163+-}
76makePerspective : Float -> Float -> Float -> Float -> M4x4
164makePerspective : Float -> Float -> Float -> Float -> M4x4
77makePerspective = Native.MJS.m4x4makePerspective
165makePerspective = Native.MJS.m4x4makePerspective
78
166
167+{-|
168+Creates a matrix for an orthogonal frustum projection with the given parameters.
169+
170+Parameters:
171+
172+ left - the left coordinate of the frustum
173+ right- the right coordinate of the frustum
174+ bottom - the bottom coordinate of the frustum
175+ top - the top coordinate of the frustum
176+ znear - the near z distance of the frustum
177+ zfar - the far z distance of the frustum
178+-}
79makeOrtho : Float -> Float -> Float -> Float -> Float -> Float -> Float -> M4x4
179makeOrtho : Float -> Float -> Float -> Float -> Float -> Float -> Float -> M4x4
80makeOrtho = Native.MJS.m4x4makeOrtho
180makeOrtho = Native.MJS.m4x4makeOrtho
81
181
182+{-|
183+Creates a matrix for a 2D orthogonal frustum projection with the given parameters.
184+znear and zfar are assumed to be -1 and 1, respectively.
185+
186+Parameters:
187+
188+ left - the left coordinate of the frustum
189+ right- the right coordinate of the frustum
190+ bottom - the bottom coordinate of the frustum
191+ top - the top coordinate of the frustum
192+-}
82makeOrtho2D : Float -> Float -> Float -> Float -> M4x4
193makeOrtho2D : Float -> Float -> Float -> Float -> M4x4
83makeOrtho2D = Native.MJS.m4x4makeOrtho2D
194makeOrtho2D = Native.MJS.m4x4makeOrtho2D
84
195
196+{-|
197+Matrix multiplcation: a * b
198+-}
85mul : M4x4 -> M4x4 -> M4x4
199mul : M4x4 -> M4x4 -> M4x4
86mul = Native.MJS.m4x4mul
200mul = Native.MJS.m4x4mul
87
201
202+{-|
203+Matrix multiplication, assuming a and b are affine: a * b
204+-}
88mulAffine : M4x4 -> M4x4 -> M4x4
205mulAffine : M4x4 -> M4x4 -> M4x4
89mulAffine = Native.MJS.m4x4mulAffine
206mulAffine = Native.MJS.m4x4mulAffine
90
207
208+{-|
209+Creates a transformation matrix for rotation by angle radians about the 3-element vector axis.
210+-}
91makeRotate : Float -> V3 -> M4x4
211makeRotate : Float -> V3 -> M4x4
92makeRotate = Native.MJS.m4x4makeRotate
212makeRotate = Native.MJS.m4x4makeRotate
93
213
214+{-|
215+Concatenates a rotation of angle radians about the axis to the given matrix.
216+-}
94rotate : Float -> V3 -> M4x4 -> M4x4
217rotate : Float -> V3 -> M4x4 -> M4x4
95rotate = Native.MJS.m4x4rotate
218rotate = Native.MJS.m4x4rotate
96
219
220+{-|
221+Creates a transformation matrix for scaling by 3 scalar values, one for
222+each of the x, y, and z directions.
223+-}
97makeScale3 : Float -> Float -> Float -> M4x4
224makeScale3 : Float -> Float -> Float -> M4x4
98makeScale3 = Native.MJS.m4x4makeScale3
225makeScale3 = Native.MJS.m4x4makeScale3
99
226
227+{-|
228+Creates a transformation matrix for scaling each of the x, y, and z axes by the amount
229+given in the corresponding element of the 3-element vector.
230+-}
100makeScale : V3 -> M4x4
231makeScale : V3 -> M4x4
101makeScale = Native.MJS.m4x4makeScale
232makeScale = Native.MJS.m4x4makeScale
102
233
234+{-|
235+Concatenates a scaling to the given matrix.
236+-}
103scaleM3 : Float -> Float -> Float -> M4x4 -> M4x4
237scaleM3 : Float -> Float -> Float -> M4x4 -> M4x4
104scaleM3 = Native.MJS.m4x4scale3
238scaleM3 = Native.MJS.m4x4scale3
105
239
240+{-|
241+Concatenates a scaling to the given matrix.
242+-}
106scaleM : V3 -> M4x4 -> M4x4
243scaleM : V3 -> M4x4 -> M4x4
107scaleM = Native.MJS.m4x4scale
244scaleM = Native.MJS.m4x4scale
108
245
246+{-|
247+Creates a transformation matrix for translating by 3 scalar values, one for
248+each of the x, y, and z directions.
249+-}
109makeTranslate3 : Float -> Float -> Float -> M4x4
250makeTranslate3 : Float -> Float -> Float -> M4x4
110makeTranslate3 = Native.MJS.m4x4makeTranslate3
251makeTranslate3 = Native.MJS.m4x4makeTranslate3
111
252
253+{-|
254+Creates a transformation matrix for translating each of the x, y, and z axes by the amount
255+given in the corresponding element of the 3-element vector.
256+-}
112makeTranslate : V3 -> M4x4
257makeTranslate : V3 -> M4x4
113makeTranslate = Native.MJS.m4x4makeTranslate
258makeTranslate = Native.MJS.m4x4makeTranslate
114
259
260+{-|
261+Concatenates a translation to the given matrix.
262+-}
115translate3 : Float -> Float -> Float -> M4x4 -> M4x4
263translate3 : Float -> Float -> Float -> M4x4 -> M4x4
116translate3 = Native.MJS.m4x4translate3
264translate3 = Native.MJS.m4x4translate3
117
265
266+{-|
267+Concatenates a translation to the given matrix.
268+-}
118translate : V3 -> M4x4 -> M4x4
269translate : V3 -> M4x4 -> M4x4
119translate = Native.MJS.m4x4translate
270translate = Native.MJS.m4x4translate
120
271
272+{-|
273+Creates a transformation matrix for a camera.
274+
275+Parameters:
276+
277+ eye - The location of the camera
278+ center - The location of the focused object
279+ up - The "up" direction according to the camera
280+-}
121makeLookAt : V3 -> V3 -> V3 -> M4x4
281makeLookAt : V3 -> V3 -> V3 -> M4x4
122makeLookAt = Native.MJS.m4x4makeLookAt
282makeLookAt = Native.MJS.m4x4makeLookAt
123
283
284+{-|
285+"Flip" the matrix across the diagonal by swapping row index and column index.
286+-}
124transpose : M4x4 -> M4x4
287transpose : M4x4 -> M4x4
125transpose = Native.MJS.m4x4transpose
288transpose = Native.MJS.m4x4transpose
126
289
127−{- Custom constructor for supplying arbitrary x,y,z axis -}
290+{-|
291+Creates a transform from a basis consisting of 3 linearly independent vectors.
292+-}
128makeBasis : V3 -> V3 -> V3 -> M4x4
293makeBasis : V3 -> V3 -> V3 -> M4x4
129makeBasis = Native.MJS.m4x4makeBasis
294makeBasis = Native.MJS.m4x4makeBasis