cl-SDL2 Creating a Window Tutorial

In this tutorial I will show you how to create a simple window using cl-sdl2 and common lisp. This window will then act as a base that you will add to in later tutorials. Before you start you will need to have an IDE, a lisp implementation, cl-sdl2 (which can be installed using quicklisp) and the SDL2 library that cl-sdl2 uses. While there are other ways to install cl-sdl2, quicklisp is the easiest and the one that I recommend that you use. The process for how to do this can be found on quicklisp’s website.

(require :sdl2)
(defun main ()
(sdl2:with-init (:everything)))

First we need to say that we will be using cl-sdl2 using “(require :sdl2)”. Next we create the function called “main” that will hold our sdl2 code and act as the start of our application. To use sdl2 we first have to initialise it, this is done with the macro “(sdl2:with-init (:everything))”. “:everything” as you can probably guess tells sdl2 to initialise with everything.

Note that the rest of the sdl2 code we will be writing will go within the closing “)” of the with-init macro.

(defun main ()
(sdl2:with-init (:everything)
(sdl2:with-window (win :title "cl-sdl2 tutorial" :flags '(:shown)))))

Now that sdl2 has been initialised we need to create a window, which can be done easily with another macro “with-window”. This is used in a similar way to the “with-init” macro in that all the code that will use the window will be placed inside the closing “)” of the macro. To create the window you need to pass it some values, above I have included only a few of what is available. First there is the variable that will hold our window which in this case is “win”. Next is what we want the window to be called which is passed using the :title key (in this case “cl-sdl2 tutorial”) and following that a list of flags. You can also include the window position using the “:x” and “:y” keys or the size of the window using “:w” “:h”, for now the default width and height will do.

Now that we have a window we need to do something with it.

(sdl2:with-window (win :title "cl-sdl2 tutorial" :flags '(:shown))
(let ((surf (sdl2:get-window-surface win))))

First we need to retrieve the surface that is used by our window, as this is what we are going to use to change what is displayed on the screen. The code should not be too hard to understand, all it does is set “surf” to the surface which is retrieved from the window we created (“win”) using the function “get-window-surface”.

(let ((surf (sdl2:get-window-surface win)))
(sdl2:fill-rect surf nil (sdl2:map-rgb (sdl2:surface-format surf) #xff #xff #xff)))

Here we will set the color (in this case white) of the surface using the function “fill-rect”. you need to pass to “fill-rect” the surface that you will be modifying, which in this case is “surf”, the next value you will set to nil and then we need the color. What we need is a color rect which can be gained by using “map-rgb”.

“map-rgb” needs the surface format and three color values. The surface format can be retrieved using the “surface-format” function and by passing in the surface that you want the format from in this case “surf”. The color values are represented using values from 0 to 255 for each of the colors red, green and blue (note above I have used hex values).

Combining these three functions as shown above you can set the color of a surface.

(let ((surf (sdl2:get-window-surface win)))
(sdl2:fill-rect surf nil (sdl2:map-rgb (sdl2:surface-format surf) #xff #xff #xff))
(sdl2:update-window win))

sdl uses buffers to load images that will be displayed on the computers screen, in fact sdl does not only use one but two of these buffers (also refereed to as double buffering) this mean that images are loaded onto a buffer that is in the background and then once everything has been loaded they are swapped. This prevents the user seeing the buffer being refreshed and makes for a more pleasant experience for the user. So far we have changed the back buffer when we set the color, so to get the buffers to swap we use the “update-window” function and pass in the window we want to be updated (sdl2 allows for more than one window).

(sdl2:update-window win)
(sdl2:delay 2000)

Because we want our window to stay on the screen for longer than a few milliseconds we need something to make it wait. Usually this would be handled by a game loop, which put simply is an endless loop that continually refreshes the screen and looks for input from the user. As you would need to accept input from the user to escape such a loop, which will be covered in a later tutorial, instead we will add a small delay to make the window stay on the screen for a few seconds before disappearing.

You now have all the code you need to display a simple window on the screen. Below is the full code for you to check against.

(require :sdl2)
(defun main ()
(sdl2:with-init (:everything)
(sdl2:with-window (win :title "cl-sdl2 tutorial" :flags '(:shown))
(let ((surf (sdl2:get-window-surface win)))
(sdl2:fill-rect surf nil (sdl2:map-rgb (sdl2:surface-format surf) #xff #xff #xff))
(sdl2:update-window win)
(sdl2:delay 2000)))))

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s