40 | This is a tutorial
41 | for Quil,
42 | a visual programming system that combines the powers
43 | of ClojureScript
44 | and Processing.js.
45 |
46 |
47 | A Quil program is called a sketch. A sketch can be a simple drawing,
48 | but it can also be a rich animation or an interactive visualization.
49 |
50 |
51 | You'll find many sketches in this tutorial. All of them are "live" —
52 | change the code and you should immediately see the sketch change.
53 | Hover over a Quil function name to see what it does.
54 |
55 |
56 |
A Taste of Quil
57 |
58 | These first few sketches will give you a taste of things to come. They
59 | are presented without much explanation. We'll dive into the details
60 | later. Play around with them, there's nothing you can break. Should
61 | you happen to make a mess, simply hit the red "revert" button, and
62 | you'll get the original code back.
63 |
64 |
65 |
The Pine Forest
66 |
67 |
68 | The road to Quil starts in the Pine Forest. Try changing some numbers
69 | and see what happens!
70 |
71 |
72 |
73 |
97 |
98 |
99 | That's already a lovely pattern we've got going. Knit it into a
100 | turtleneck and aunt Juliet will envy you forever. But there's more.
101 | How about we get things moving?
102 |
103 |
104 |
The Carousel
105 |
106 | Time to make your head spin! This is an example of an animation. Think
107 | of it like an old fashioned film projector, spinning through a
108 | sequence of images. Quil calls your draw function many times in rapid
109 | succession to draw the individual images, called frames.
110 |
111 |
112 | Quil keeps a count of how many frames have passed. This sketch uses
113 | that frame-count to determine the position of the circle.
114 |
115 |
133 |
134 |
Paint Blotches
135 |
136 |
137 | Quil also lets you make interactive sketches. Move your mouse
138 | over the canvas to smear it with thick blotches of paint that run down
139 | the screen.
140 |
141 |
142 |
143 | This is an example of a sketch that has state. This means
144 | that how it looks depends on its history, in this case, the past
145 | positions of the mouse.
146 |
147 |
148 |
190 |
191 |
Creating a sketch
192 |
193 |
194 | To get Quil to draw something on the screen, you need a :draw
195 | function. You pass this function on to Quil when you call (sketch
196 | ...). Quil accepts other functions as well, like
197 | a :setup function, which is called once when your sketch
198 | starts to run.
199 |
200 |
201 | The :host is the HTML id of the canvas element,
202 | which is where Quil will draw your sketch. In this tutorial, all the
203 | canvases are already set up for you, so no need to worry about that.
204 |
205 |
206 |
The Quil API
207 |
208 |
209 | Inside the :draw function you have access to a long list of functions
210 | provided by Quil. Keep the Quil API
211 | reference close to you at all times. Hang it above your bed, keep
212 | it under your pillow. It's a magical toolbox providing endless
213 | opportunities for your creations.
214 |
215 |
216 |
Drawing shapes
217 |
218 |
219 | When you draw a shape, it stays on the canvas until you draw something
220 | on top of it. You can see this well in the last example, where the new
221 | "paint" is drawn on top of the old..
222 |
223 |
224 |
225 | With (background ...) you can get it a clean slate, since it
226 | will refill the whole canvas with a solid color. You can use it in
227 | your draw function to clear the canvas before drawing the new frame.
228 |
229 |
230 |
231 | One of the easiest things you can draw is a rectangle. Quil's rect
232 | function takes four parameters, x, y, width
233 | and height. The first two arguments represent the location of the top
234 | left corner of rectangle on the canvas. Remember that in Quil, as in computer
235 | graphics in general, the origin (0, 0) of the coordinate system represents
236 | the top left corner of the drawing surface. In this example, we're drawing a
237 | centered equilateral rectangle or square.
238 |
239 |
240 |
250 |
251 |
252 | By default Quil draws shapes with a light gray fill color, and a thin black
253 | border, on a dark gray background. Unless normcore becomes even more... norm,
254 | this color scheme won't win many prizes.
255 |
256 |
257 |
258 | To spice things up let's add some color! We already talked
259 | about background, which is really a lot like a draw function in its
260 | own right, since it refills the whole canvas. Shapes like rectangles or
261 | triangles on the other hand depend on a fill color, and
262 | a stroke. The stroke has a color and
263 | a stroke-weight, the width of the stroke in pixels.
264 |
265 |
266 |
267 | By default all colors are specified
268 | in the RGB color space, meaning
269 | red - green - blue, with values between 0 and 255. Try and
270 | see how the colors change as you modify the three numbers!
271 |
272 |
273 |
291 |
292 |
293 | Drawing a circle isn't any harder. While Quil does not come with a
294 | special function for drawing circles, it supplies a function for the general
295 | case of drawing ovals (or ellipses). That will work well — after all, a
296 | circle is just an ellipse that is as high as it is wide.
297 |
298 |
299 | The ellipse function takes the same arguments
300 | as rect: x, y, width and height.
301 | However, whereas in the case of rect the point (x,y)
302 | reprents the top-left corner of the figure, in ellipse it represents
303 | its center. This decision of Quil's authors makes sense: an ellipse doesn't
304 | have corners.
305 |
306 |
307 |
320 |
321 |
Animation and State
322 |
323 |
324 |
325 | Don't just draw something, make it move! — Winston Churchill
326 |
327 |
328 |
329 |
Slider
330 |
331 |
332 | There are a few different ways you can create animations in Quil. You already
333 | saw the Carrousel example above, which used the current (frame-count)
334 | and based the rendering of each frame on that.
335 |
336 |
337 |
338 | You can change the frame rate, the number of frames Quil renders per second, with (frame-rate n). This will change the speed of animations based on frame-count.
339 |
340 |
341 |
342 | Another approach is the use the current time in milliseconds, this way we have a way to measure passing time independent of the the current frame rate. Quil provides the handy (millis) function for that.
343 |
344 |
345 |
346 | In this next example we use (millis) to calculate a horizontal position.
347 | With Clojure's mod function (modulo, in other words the remainder after
348 | division), we let the animation wrap around again.
349 |
376 | This is an example of a sketch that uses state. The initial state is returned
377 | by setup And update-state continually updates that state, in
378 | this case growing the radius, or changing the color. Draw in turn can then use that state.
379 |
380 |
381 |
419 |
420 |
421 |
Advanced Examples
422 |
423 |
424 | These examples are taken from the Quil site. Can you find out how they work?
425 |
A short intro to Clojure, many thanks to Clojure Bridge for most of the material.
16 |
17 |
18 |
19 | Notice the parentheses. Parentheses enclose instructions to the computer
20 | in Clojure. A left parenthesis is the start of the instruction, and a
21 | matching right parenthesis is the end of the enclosing instruction. Clojure code has a lot of nested parentheses.
22 |
23 |
24 |
27 |
28 | Next to the parentheses, we see the instructions to the computer. That instruction is normally what we call a function. The functions do all the hard work in Clojure. print-str, + and forward are all functions. When these functions get run, they return a some type of value. Clojure functions always return a value.
29 |
30 |
31 | Simple Values
32 |
33 |
34 | Strings
35 |
36 |
What is a string? A string is just a piece of text. To make a string, you enclose it in quotation marks. Look at the last example. A backslash is how we put a quotation mark inside a string. Do not try using single quotes to make a string.
37 |
38 | "Hello, World!"
39 | "Aubrey said, \"I think we should go to the Orange Julius.\""
40 |
41 |
42 |
43 | Booleans and nil
44 |
45 |
46 | A boolean is a true or false value, and you type them just like that, true and false. Often in programming, we need to ask a true or false question, like “Is this class in the current semester?” or “Is this person’s birthday today?” When we ask those questions, we get a boolean back.
47 | There is another value nil, which behaves like a boolean in terms of truthiness. But, nil means no value at all and not a boolean
48 |
49 | true
50 | false
51 | nil
52 |
53 |
54 |
55 | Keywords
56 |
57 |
58 | Keywords are the strangest of the basic value types. Some computer languages have similar one. However, keywords don’t have a real world analog like numbers, strings, or booleans. You can think of them as a special type of string, one that’s used for labels. They are often used as keys of key-value pair for maps (data structure; will learn later).
59 |
60 | :trinity
61 | :first
62 | :last
63 |
64 |
65 |
66 | Numbers
67 |
68 |
69 | Clojure has several different types of numbers.
70 | First up are integers. Integers include zero, the positive whole numbers, and the negative whole numbers, and you write them just like we write them normally.
71 |
72 |
73 | 0, 12, -42
74 |
75 |
Then we have decimal numbers, which are also called floats. They include any numbers that have a decimal point in them.
76 |
77 |
78 | 0.0000072725, 10.5, -99.9
79 |
80 |
Finally, we have fractions, which are also called ratios. Computers cannot perfectly represent all floats, but ratios are always exact. We write them with a slash, like so:
81 | Note that, just like with pen-and-paper math, the denominator of your ratio cannot be equal to 0.
82 |
83 | 1/2, -7/3
84 |
85 |
86 |
87 | Infix vs. prefix notation
88 |
89 |
90 | In Clojure, +, -, * and / appear before two numbers. This is called prefx
91 | notation. What you’re used to seeing is called infx notation, as the arithmetic
92 | operator is in-between the two operands.
93 |
94 |
97 |
98 | Explicit precedence
99 |
100 |
101 | Imagine both are unclear, but notice that in the prefix version, you do not have to ever think about the precedence of operators. Because each expression has the operator before all the operands and the entire expression is wrapped in parentheses, all precendence is explicit.
102 |
103 |
104 | This example uses integers but try changing the numbers to floats, decimals, or fractions and see what happens.
105 |
106 |
107 | See how this infix example is written in Clojure in the editor below.
108 | Infix: 1 + 2 / 3
109 |
110 |
113 |
114 | Less repetitive
115 |
116 |
117 | Another reason prefix notation can be nice is that it can make long expressions less repetitive. With prefix notation, if we plan to use the same operator on many operands, we do not have to repeat the operator between them.
118 |
119 |
120 | See how this infix example is written in Clojure in the editor below
121 | Infix: 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9
122 |
123 |
126 |
127 | Some basic Clojure functions
128 |
129 |
130 | str this example combines two strings, but try changing one of them to a number.
131 |
132 |
135 |
136 | inc
137 |
138 |
141 |
142 | Data Structures
143 |
144 |
145 | So far, we’ve dealt with discrete pieces of data: one number, one string, one value. When programming, it is more often the case that you want to work with groups of data.
146 |
147 |
148 | Vectors
149 |
150 |
151 | A vector is a sequential collection of values. A vector may be empty. A vector may contain values of different types. Each value in a vector is numbered starting at 0, that number is called its index. The index is used to refer to each value when looking them up.
152 |
153 |
154 | Vectors are written using square brackets with any number of pieces of data inside them, separated by spaces. Here are some examples of vectors:
155 |
156 |
157 | The next two functions are used to make new vectors. The vector function takes any number of items and puts them in a new vector. conj is an interesting function that you’ll see used with all the data structures. With vectors, it takes a vector and an item and returns a new vector with that item added to the end of the vector. Why the name conj? conj is short for conjoin, which means to join or combine. This is what we’re doing: we’re joining the new item to the vector.
158 |
159 |
162 |
165 |
166 | Now, take a look at these four functions.
167 |
168 |
169 | count gives us a count of the number of items in a vector.
170 |
171 |
174 |
175 | nth gives us the nth item in the vector. Note that we start counting at 0, so in the example, calling nth with the number 1 gives us what we’d call the second element when we aren’t programming.
176 |
177 |
180 |
181 | first returns the first item in the collection.
182 |
183 |
186 |
187 | rest returns all except the first item.
188 |
189 |
192 |
193 | concat
194 |
195 |
198 |
199 | Maps
200 |
201 |
202 | Maps hold a set of keys and values associated with them. You can think of it like a dictionary: you look up things using a word (a keyword) and see the definition (its value). If you’ve programmed in another language, you might have seen something like maps–maybe called dictionaries, hashes, or associative arrays.
203 |
204 |
205 | We write maps by enclosing alternating keys and values in curly braces, like so.
206 | {:first "Sally" :last "Brown"}
207 | Maps are useful because they can hold data in a way we normally think about it.
208 | Take our made up example, Sally Brown. A map can hold her first name and last name, her address, her favorite food,
209 | or anything else. It’s a simple way to collect that data and make it easy to look up.
210 |
211 | This is an empty map. Add some key-value pairs!
212 |
213 |
216 |
217 | assoc and dissoc are paired functions: they associate and disassociate items from a map.
218 | See how we add the last name “Mitchell” to the map with assoc, and then we remove it with dissoc.
219 |
220 |
223 |
226 |
227 | merge merges two maps together to make a new map.
228 |
229 |
232 |
233 | count every collection has this function. Why do you think the answer is two? count is returning the number of associations.
234 |
235 |
238 |
239 | Since map is a key-value pair, the key is used to get a value from a map. One of the ways often used in Clojure is the examples below. We can use a keyword like using a function in order to look up values in a map.
240 |
241 |
244 |
245 | Then we have keys and vals, which are pretty simple: they return the keys and values in the map. The order is not guaranteed, so we could have gotten (:first :last) or (:last :first).
246 |
247 |
250 |
253 |
254 | Simple values such as numbers, keywords, and strings are not the only types of things you can put into collections. You can also put other collections into collections, so you can have a vector of maps, or a list of vectors, or whatever combination fits your data.
255 |
259 | At the request of the survivors, the names have been changed. Out of respect for the dead,
260 | the rest has been told exactly as it occurred
261 |
72 |
73 |
97 |
98 |