Sketch

• Sketch

[[http://quickdocs.org/sketch/][file:http://quickdocs.org/badge/sketch.svg]]

Sketch is a Common Lisp environment for the creation of electronic art, visual design, game prototyping, game making, computer graphics, exploration of human-computer interaction and more. It is inspired by [[https://processing.org][Processing Language]] and shares some of the API.

[[http://i.imgur.com/MNZUwz8.png]]

** Installation

Sketch is available through [[https://www.quicklisp.org/beta/][Quicklisp]], Common Lisp's de facto package manager. From your REPL, run:

#+BEGIN_SRC lisp (ql:quickload :sketch) #+END_SRC

To make Sketch run correctly, however, a few requirements must be met.

*** Requirements **** Common Lisp Implementation Sketch should be compatible with all major Common Lisp implementations and all major operating systems - more specifically, all CL implementations and operating systems that [[https://github.com/lispgames/cl-sdl2][cl-sdl2]] runs on. Incompatibility with any of these is considered a bug.

Sketch is known to work with:

• CCL 1.11 on Mac OS X El Capitan
• CCL 1.12.1 on MacOS 13.1 ([[https://github.com/vydd/sketch/issues/67][steps]])
• CCL SVN 1.12.dev.r16617 on Arch Linux
• CCL 1.11 on Windows 10 64bit
• SBCL on Debian Unstable
• SBCL 1.2.16 on Arch Linux
• SBCL 1.3.1 on Linux Mint 17
• SBCL 1.3.6 on Windows 10 64bit

Workarounds, or extra steps, may be required on some systems:

• Arch Linux, [[https://github.com/vydd/sketch/issues/16][issue]].
• OpenSuse, [[https://github.com/vydd/sketch/issues/17][issue]].
• CCL on OSX: Make sure to use the 64-bit version of CCL ([[https://github.com/vydd/sketch/issues/23][issue]]).
• Quickload fails with libffi error, [[https://github.com/vydd/sketch/issues/47][issue]].

Sketch is known to not work with:

• SBCL 1.2.15 on Mac OS X /Sketch can't handle input and the window's titlebar is black. These kinds of issues are a known problem with Mac OS X, because it needs its GUI threads to be main, and CCL is the only lisp that accounts for that out of the box. There are ways to counter this, but until a solution finds its way into this repository, SBCL on Mac OS X will stay on this list. In the meantime, use CCL./

If you test Sketch on other systems, please send a pull request to include your results.

**** Foreign dependencies ***** SDL2 SDL2 is currently Sketch's only backend. It is a C library which you will need to download manually from [[https://www.libsdl.org][libsdl webpage]]. Select the release compatible with your operating system, or compile from the source code.

***** SDL2 Image & SDL2 TTF For loading image and font files, Sketch relies on SDL2 Image and SDL2 TTF, respectively, both part of the SDL project.

***** libffi Some users have reported that [[https://sourceware.org/libffi/][libffi]] needed to be installed to make Sketch work.

***** OpenGL Sketch requires graphics hardware and drivers with support for GL version 3.3.

**** Installing and running Sketch on Windows Sketch works on both CCL and SBCL, but installing all prerequisites might not be as straightforward as it is on the other platforms.

***** Libraries Download SDL2, SDL2_IMAGE and SDL2_TTF dlls from [[https://www.libsdl.org][libsdl webpage]] and copy them somewhere Windows can find them - =\Windows\System32= will work. When copying SDL2_TTF, make sure to copy all of the dlls provided in the archive, and not just the TTF one.

Now you will need to get a libffi dll. One of the ways of doing this is compiling from the source, but for a quick and easy solution, you can just find a trusted source and use their version. For example, if you are using Emacs on Windows, you can find =libffi-6.dll= in =emacs\bin=. Copy it to the same directory you copied sdl2 dlls to earlier.

***** GCC To bootstrap cffi-libffi, you are going to need a C compiler, more specifically the one from the GNU Compiler Collection. Also, libffi headers and pkg-config are needed. Luckily, you can get all these things (and more) with MSYS2. Go to [[https://msys2.github.io]] and follow the instructions for installing the 64bit version.

From its console, install gcc, libffi headers and pkg-config by running =pacman -S gcc libffi libffi-devel pkg-config=.

***** Environment variables From the Control Panel, open System properties, go to the Advanced tab, and click "Environment Variables..." - or click the Start button, start typing "environment" and select "Edit the system environment variables".

Double click "Path" from the list of System variables and make sure that both your lisp implementation's path (something like =C:\Program Files\Steel Bank Common Lisp\1.3.6=) and MSYS path (probably =C:\msys64\usr\bin=) are listed. If not, click "New" and add them now.

If you needed to change anything here, restart the computer now.

***** SLIME If you are using SLIME, you won't be able to load or run Sketch if you start SWANK from emacs (by running =M-x slime=). Instead, you should open the Command Prompt (the regular one, not MSYS), start your lisp and eval =(ql:quickload :swank)= =(swank:create-server)=. From Emacs, type =M-x slime-connect=, and finally, press enter twice (for localhost and port 4005).

If you did everything correctly, you should be able to =(ql:quickload :sketch)= and move on to the tutorial.

*** Running provided examples To get a feel for what Sketch can do, and also to make sure that everything has been installed correctly, run the examples as follows.

#+BEGIN_SRC lisp CL-USER> (ql:quickload :sketch-examples) CL-USER> (make-instance 'sketch-examples:hello-world) CL-USER> (make-instance 'sketch-examples:sinewave) CL-USER> (make-instance 'sketch-examples:brownian) CL-USER> (make-instance 'sketch-examples:life) ; Click to toggle cells, ; any key to toggle iteration CL-USER> (make-instance 'sketch-examples:input) CL-USER> (make-instance 'sketch-examples:stars) #+END_SRC

*** Running example code from this page In all the following examples, we're going to assume that Sketch is loaded with =(ql:quickload :sketch)=, and that we're in package =:TUTORIAL=, which is set to use =:SKETCH=.

#+BEGIN_SRC lisp CL-USER> (ql:quickload :sketch) CL-USER> (defpackage :tutorial (:use :cl :sketch)) CL-USER> (in-package :tutorial) TUTORIAL> ;; ready #+END_SRC

** Tutorial Defining sketches is done with the =defsketch= macro, which is essentially a wrapper for =defclass=.

#+BEGIN_SRC lisp (defsketch tutorial ()) (make-instance 'tutorial) #+END_SRC

If all goes well, this should give you an unremarkable gray window. From now on, assuming you're using Emacs + SLIME, or a similarly capable environment, you can just re-evaluate =(defsketch tutorial () <insert drawing code here>)= and the sketch will be restarted without you having to close the window or make another instance of the class.

*** Shapes Let's draw something! Drawing code goes inside the body of =defsketch=.

=(rect x y w h)= draws a rectangle where =x= and =y= specify the top-left corner of the rectangle, and =w= and =h= are the width and height. By default, the origin (0, 0) is at the top-left corner of the drawing area, and the positive y direction is facing down.

#+BEGIN_SRC lisp (defsketch tutorial () (rect 100 100 200 200)) #+END_SRC

#+BEGIN_SRC lisp (defsketch tutorial () (dotimes (i 10) (rect 0 (* i 40) (* (+ i 1) 40) 40))) #+END_SRC

Something to note: drawing code doesn't need to go into a special function or method, or be explicitly binded to a sketch. =defsketch= is defined as =(defsketch sketch-name bindings &body body)=: that body, and any functions it calls to, is your drawing code. We will get to =bindings= later.

Circles and ellipses are drawn with =(circle x y r)= and =(ellipse cx cy rx ry)=:

#+BEGIN_SRC lisp (defsketch tutorial () (circle 300 100 50) (ellipse 200 200 100 50)) #+END_SRC

Lines with =(line x1 y1 x2 y2)=:

#+BEGIN_SRC lisp (defsketch tutorial () (line 0 0 400 400) (line 400 0 0 400)) #+END_SRC

Lines with an arbitrary number of segments with =polyline=:

#+BEGIN_SRC lisp (defsketch tutorial () (polyline 100 100 200 150 300 100 200 200 100 100)) #+END_SRC

Arbitrary polygons can be drawn using =(polygon x1 y1 x2 y2 ...)=, the winding rule (how the "inside parts" and "outside parts" are determined) is specified as a pen property (pens will be described in more detail later) and can be one of =(:odd :nonzero :positive :negative :abs-geq-two)=. By default, it's =:nonzero=.

#+BEGIN_SRC lisp (defsketch tutorial () (with-pen (make-pen :fill +blue+ :winding-rule :odd) (polygon 100 100 200 150 300 100 200 200))) #+END_SRC

To draw a regular polygon with =n= sides, call =(ngon n cx cy rx ry &optional (angle 0))=; =cx= and =cy= are the coordinates of the center of the shape, while =rx= and =ry= are height of an ellipse that the shape is inscribed inside.

#+BEGIN_SRC lisp (defsketch tutorial () (dotimes (i 4) (ngon (+ i 3) (+ 50 (* i 100)) 200 20 20 (* i 20)))) #+END_SRC

Bezier curves with 4 control points are drawn with =(bezier x1 y1 bx1 by1 bx2 by2 x2 y2)=; =x1=, =y1=, =x2= and =y2= determine the start and end points.

#+BEGIN_SRC lisp (defsketch tutorial () (bezier 0 400 100 100 300 100 400 400)) #+END_SRC

The resolution of a curve can be controlled with the pen property =:curve-steps=, for example:

#+BEGIN_SRC lisp (defsketch tutorial () (with-pen (make-pen :curve-steps 4 :stroke +white+) (bezier 0 400 100 100 300 100 400 400))) #+END_SRC

*** Configuring your sketch The first form in =defsketch= after the name of your sketch, and before the body, is a list of bindings that will be available in the sketch body. This is also where a number of configuration options can be set:

• =title= (string): window title.
• =width= and =height= (in pixels): window dimensions, 400 x 400 by default.
• =fullscreen= (=t= or =nil=): whether window is fullscreen.
• =resizable= (=t= or =nil=