cl-SDL2 Loading Images Tutorial

This Tutorial will continue on from cl-SDL2 Creating a Window Tutorial using code you wrote in the previous tutorial. Because of this if you have not completed the first tutorial I recommend that you do so now.

There are two ways we will be loading images, the first being “load-bmp” which is part of SDL2 and can as the name suggests can only load .bmp files. As you will likely want to use other image formats such as .jpg and .png I will also show you how to use cl-SDL2-image, which can be retrieved using quicklisp.

Note: you will also need the SDL2-image library as cl-SDL2-image is only a wrapper to allow it to work with common lisp.

(let ((image (sdl2:load-bmp "image-file.bmp")))
(sdl2:blit-surface image nil surf nil)
(sdl2:update-window win)
(sdl2:delay 2000)
(sdl2:free-surface image))

Note: “image-file.bmp” represents the path to your .bmp file.

The above code loads the image “image-file.bmp” as a surface into the “image” variable created by “let”. We then load that surface into our buffer using “blit-surface” which uses the surface we retrieved earlier from our main window (see the previous tutorial to see how that was done). The other arguments you don’t have to worry about just yet.

The next line you should be familiar to you with only the last line being new. This line of code frees the surface that was used for our image that we loaded. Because SDL2 is written in C it does not have garbage collection like lisp, due to this we need to do the garbage collection ourselves. When a surface is created (unless it is created using one of the available macros with cleanup built in) we need to free up the memory that was used when it is no longer needed. If this is not done you can end up with what is called a memory leak, where memory keeps getting put aside for surfaces you are not using. So when we are finished with a surface we call “free-surface” on it.

That is all that is required to load a .bmp image. But to use other formats we need to add a bit more code. At this point you should be able to run your code and see a window with your image. Do not worry if the image does not fit perfectly into the window as this will be fixed in a later tutorial.

(require :sdl2-image)

Put this line of code below the other require at the top of your lisp file, this will allow you to use the image library sdl2-image.

(sdl2-image:init '(:jpg))

Before we load an image we first need to initialise “sdl2-image” and tell it what formats we will be using. Above I have listed the .jpg format but you can use others, also you can add more than one format to the list. The full list of available image formats can be found int the cl-sdl2-image source code.

This code should be placed at the start of your code in the “main” function.


At some point we also need to stop sdl2-image, this can easily be accomplished with the “quit” function show above. This should be placed near the end of your code when you no longer need sdl2-image.

(let ((image (sdl2:load-bmp "image-file.bmp")))
(let ((image (sdl2-image:load-image "image-file.jpg")))

As you can see using sdl2-image only requires a small change to your code and like “sdl2:load-bmp” “sdl2-image:load-image” returns a surface which can be loaded into the buffer.

If you now run your code you should now see the image displayed for a short time.

The full code is listed bellow.

(require :sdl2)
(require :sdl2-image)

(defun main ()
(sdl2:with-init (:everything)
(sdl2:with-window (win :title "sdl2-tutorial" :flags '(:shown))
(sdl2-image:init '(:jpg))
(let ((surf (sdl2:get-window-surface win))
(image (sdl2-image:load-image "image-file.jpg")))
(sdl2:blit-surface image nil surf nil )
(sdl2:update-window win)
(sdl2:delay 2000)
(sdl2:free-surface image)


Leave a Reply

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

You are commenting using your 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