git.iko.soy/elk
on master help sign in
Merge pull request #610 from johnpmayer/webgl
82b7c0fEvan Czaplicki
libraries/Graphics/WebGL.elm+38−9
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,18 +6,37 @@ 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
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.
12+
13+```haskell
11−vertex : Shader { a | pos : V3 } {} {}
14+vertex : Shader { a | pos : V3 } { b | model : M4x4 } {}
12vertex = [glsl|
15vertex = [glsl|
13
16
14attribute vec3 pos;
17attribute vec3 pos;
18+uniform mat4 model;
15
19
16void main () {
20void main () {
17− gl_Position = vec4(pos,1.0);
21+ gl_Position = model * vec4(pos,1.0);
18}
22}
19
23
20−|]
24+\]
25+```
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
21
40
22# WebGL Element
41# WebGL Element
23@docs webgl
42@docs webgl
@@ -29,28 +48,38 @@ import Http (Response)
29import Native.Graphics.WebGL
48import Native.Graphics.WebGL
30import Signal (Signal)
49import Signal (Signal)
31
50
32−unsafeCoerceGLSL : String -> Shader attr unif vary
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.
33−unsafeCoerceGLSL = Native.Graphics.WebGL.unsafeCoerceGLSL
52+-}
34−
35type Triangle a = (a,a,a)
53type Triangle a = (a,a,a)
36
54
55+{-| Apply a function to each vertex -}
37mapTriangle : (a -> b) -> Triangle a -> Triangle b
56mapTriangle : (a -> b) -> Triangle a -> Triangle b
38mapTriangle f (x,y,z) = (f x, f y, f z)
57mapTriangle f (x,y,z) = (f x, f y, f z)
39
58
59+{-| Apply an arity-2 function element-wise on 2 triangles -}
40zipTriangle : (a -> b -> c) -> Triangle a -> Triangle b -> Triangle c
60zipTriangle : (a -> b -> c) -> Triangle a -> Triangle b -> Triangle c
41zipTriangle 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')
42
62
43data Shader attr unif vary = Shader
63data Shader attr unif vary = Shader
44
64
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+
45data Texture = Texture
69data Texture = Texture
46
70
71+{-| Loads a texture from the given url. PNG and JPEG are the preferred and tested-compatible source image format. -}
47loadTex : String -> Signal (Response Texture)
72loadTex : String -> Signal (Response Texture)
48loadTex = Native.Graphics.WebGL.loadTex
73loadTex = Native.Graphics.WebGL.loadTex
49
74
50data Model = Model
75data Model = Model
51
76
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+-}
52−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
53model = Native.Graphics.WebGL.model
81model = Native.Graphics.WebGL.model
54
82
83+{-| Render a WebGL scene with the given dimensions and models -}
55webgl : (Int,Int) -> [Model] -> Element
84webgl : (Int,Int) -> [Model] -> Element
56webgl = Native.Graphics.WebGL.webgl
85webgl = Native.Graphics.WebGL.webgl
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