git.iko.soy/elk
on b00a8cb help sign in
elk/libraries/Graphics/Collage.elm
261 lines 7.4 kB history raw
1module Graphics.Collage where
3{-| The collage API is for freeform graphics. You can move, rotate, scale, etc.
4all sorts of forms including lines, shapes, images, and elements.
6# Unstructured Graphics
7@docs collage
8
9# Creating Forms
10@docs toForm, filled, textured, gradient, outlined, traced
12# Transforming Forms
13@docs move, moveX, moveY, scale, rotate, alpha
15# Grouping Forms
16Grouping forms makes it easier to write modular graphics code. You can create
17a form that is a composite of many subforms. From there it is easy to transform
18it as a single unit.
20@docs group, groupTransform
22# Shapes
23@docs rect, oval, square, circle, ngon, polygon
25# Paths
26@docs segment, path
28# Line Styles
29@docs solid, dashed, dotted, LineStyle, LineCap, LineJoin, defaultLine
31-}
33import open Basics
34import List
35import Either (Either, Left, Right)
36import Transform2D (Transform2D, identity)
37import Native.Graphics.Collage
38import Graphics.Element (Element)
39import Color (Color, black, Gradient)
40import Maybe (Maybe)
41import JavaScript (JSString)
43type Form = {
44 theta : Float,
45 scale : Float,
46 x : Float,
47 y : Float,
48 alpha : Float,
49 form : BasicForm
50 }
52data FillStyle
53 = Solid Color
54 | Texture String
55 | Grad Gradient
57{-| The shape of the ends of a line. -}
58data LineCap = Flat | Round | Padded
60{-| The shape of the “joints” of a line, where each line segment
61meets. `Sharp` takes an argument to limit the length of the joint. This
62defaults to 10.
63-}
64data LineJoin = Smooth | Sharp Float | Clipped
66{-| All of the attributes of a line style. This lets you build up a line style
67however you want. You can also update existing line styles with record updates.
68-}
69type LineStyle = {
70 color : Color,
71 width : Float,
72 cap : LineCap,
73 join : LineJoin,
74 dashing : [Int],
75 dashOffset : Int
76 }
78{-| The default line style, which is solid black with flat caps and sharp joints.
79You can use record updates to build the line style you
80want. For example, to make a thicker line, you could say:
82 { defaultLine | width <- 10 }
83-}
84defaultLine : LineStyle
85defaultLine = {
86 color = black,
87 width = 1,
88 cap = Flat,
89 join = Sharp 10,
90 dashing = [],
91 dashOffset = 0
92 }
94{-| Create a solid line style with a given color. -}
95solid : Color -> LineStyle
96solid clr = { defaultLine | color <- clr }
98{-| Create a dashed line style with a given color. Dashing equals `[8,4]`. -}
99dashed : Color -> LineStyle
100dashed clr = { defaultLine | color <- clr, dashing <- [8,4] }
102{-| Create a dotted line style with a given color. Dashing equals `[3,3]`. -}
103dotted : Color -> LineStyle
104dotted clr = { defaultLine | color <- clr, dashing <- [3,3] }
106data BasicForm
107 = FPath LineStyle Path
108 | FShape (Either LineStyle FillStyle) Shape
109 | FImage Int Int (Int,Int) String
110 | FElement Element
111 | FGroup Transform2D [Form]
113form : BasicForm -> Form
114form f = { theta=0, scale=1, x=0, y=0, alpha=1, form=f }
116fill style shape = form (FShape (Right style) shape)
118{-| Create a filled in shape. -}
119filled : Color -> Shape -> Form
120filled color shape = fill (Solid color) shape
122{-| Create a textured shape. The texture is described by some url and is
123tiled to fill the entire shape.
124-}
125textured : String -> Shape -> Form
126textured src shape = fill (Texture src) shape
128{-| Fill a shape with a [gradient](/library/Color.elm#linear). -}
129gradient : Gradient -> Shape -> Form
130gradient grad shape = fill (Grad grad) shape
132{-| Outline a shape with a given line style. -}
133outlined : LineStyle -> Shape -> Form
134outlined style shape = form (FShape (Left style) shape)
136{-| Trace a path with a given line style. -}
137traced : LineStyle -> Path -> Form
138traced style path = form (FPath style path)
140{-| Create a sprite from a sprite sheet. It cuts out a rectangle
141at a given position.
142-}
143sprite : Int -> Int -> (Int,Int) -> String -> Form
144sprite w h pos src = form (FImage w h pos src)
146{-| Turn any `Element` into a `Form`. This lets you use text, gifs, and video
147in your collage. This means you can move, rotate, and scale
148an `Element` however you want.
149-}
150toForm : Element -> Form
151toForm e = form (FElement e)
153{-| Flatten many forms into a single `Form`. This lets you move and rotate them
154as a single unit, making it possible to build small, modular components.
155-}
156group : [Form] -> Form
157group fs = form (FGroup identity fs)
159{-| Flatten many forms into a single `Form` and then apply a matrix
160transformation.
161-}
162groupTransform : Transform2D -> [Form] -> Form
163groupTransform matrix fs = form (FGroup matrix fs)
165{-| Move a form by the given amount. This is a relative translation so
166`(move (10,10) form)` would move `form` ten pixels up and ten pixels to the
167right.
168-}
169move : (Float,Float) -> Form -> Form
170move (x,y) f = { f | x <- f.x + x, y <- f.y + y }
172{-| Move a shape in the x direction. This is relative so `(moveX 10 form)` moves
173`form` 10 pixels to the right.
174-}
175moveX : Float -> Form -> Form
176moveX x f = { f | x <- f.x + x }
178{-| Move a shape in the y direction. This is relative so `(moveY 10 form)` moves
179`form` upwards by 10 pixels.
180-}
181moveY : Float -> Form -> Form
182moveY y f = { f | y <- f.y + y }
184{-| Scale a form by a given factor. Scaling by 2 doubles the size.
185-}
186scale : Float -> Form -> Form
187scale s f = { f | scale <- f.scale * s }
189{-| Rotate a form by a given angle. Rotate takes standard Elm angles (radians)
190and turns things counterclockwise. So to turn `form` 30&deg; to the left
191you would say, `(rotate (degrees 30) form)`.
192-}
193rotate : Float -> Form -> Form
194rotate t f = { f | theta <- f.theta + t }
196{-| Set the alpha of a `Form`. The default is 1, and 0 is totally transparent. -}
197alpha : Float -> Form -> Form
198alpha a f = { f | alpha <- a }
200{-| A collage is a collection of 2D forms. There are no strict positioning
201relationships between forms, so you are free to do all kinds of 2D graphics.
202-}
203collage : Int -> Int -> [Form] -> Element
204collage = Native.Graphics.Collage.collage
207type Path = [(Float,Float)]
209{-| Create a path that follows a sequence of points. -}
210path : [(Float,Float)] -> Path
211path ps = ps
213{-| Create a path along a given line segment. -}
214segment : (Float,Float) -> (Float,Float) -> Path
215segment p1 p2 = [p1,p2]
217type Shape = [(Float,Float)]
219{-| Create an arbitrary polygon by specifying its corners in order.
220`polygon` will automatically close all shapes, so the given list
221of points does not need to start and end with the same position.
222-}
223polygon : [(Float,Float)] -> Shape
224polygon points = points
226{-| A rectangle with a given width and height. -}
227rect : Float -> Float -> Shape
228rect w h = let hw = w/2
229 hh = h/2
230 in [ (0-hw,0-hh), (0-hw,hh), (hw,hh), (hw,0-hh) ]
232{-| A square with a given edge length. -}
233square : Float -> Shape
234square n = rect n n
236{-| An oval with a given width and height. -}
237oval : Float -> Float -> Shape
238oval w h =
239 let n = 50
240 t = 2 * pi / n
241 hw = w/2
242 hh = h/2
243 f i = (hw * cos (t*i), hh * sin (t*i))
244 in List.map f [0..n-1]
246{-| A circle with a given radius. -}
247circle : Float -> Shape
248circle r = oval (2*r) (2*r)
250{-| A regular polygon with N sides. The first argument specifies the number
251of sides and the second is the radius. So to create a pentagon with radius
25230 you would say:
254 ngon 5 30
255-}
256ngon : Int -> Float -> Shape
257ngon n r =
258 let m = toFloat n
259 t = 2 * pi / m
260 f i = ( r * cos (t*i), r * sin (t*i) )
261 in List.map f [0..m-1]