Gigi Labs

Please follow Gigi Labs for the latest articles.

Thursday, February 13, 2014

SDL2: Pixel Drawing

Greetings! :)

[Update 2015-11-14: This article is out of date. Check out the latest version at Gigi Labs.]

In yesterday's article, "SDL2: Keyboard and Mouse Movement (Events)", we saw how we could handle keyboard and mouse events to allow the user to interact with whatever we are displaying on the screen. In today's article, we'll learn how to draw individual pixels onto our window, and we'll use mouse events to create a drawing program similar to a limited version of Microsoft Paint.

You'll first want to create a project in Visual Studio and set it up for SDL2 (see "SDL2: Setting up SDL2 in Visual Studio (2013 or any other)"). We'll then need a bit of code to start off with, so let's take the code from "SDL2: Empty Window" and adapt it a little bit:

#include <SDL.h>

int main(int argc, char ** argv)
{
    bool quit = false;
    SDL_Event event;

    SDL_Init(SDL_INIT_VIDEO);

    SDL_Window * window = SDL_CreateWindow("SDL2 Pixel Drawing",
        SDL_WINDOWPOS_UNDEFINED, SDL_WINDOWPOS_UNDEFINED, 640, 480, 0);

    while (!quit)
    {
        SDL_WaitEvent(&event);

        switch (event.type)
        {
        case SDL_QUIT:
            quit = true;
            break;
        }
    }

    SDL_DestroyWindow(window);
    SDL_Quit();

    return 0;
}

As always, don't forget to put SDL2.dll in the same folder as your executable before running the program.

Since we're going to draw pixels directly rather load an image, our course of action in this article is going to be a little different from past articles. First, we need a renderer, so we use SDL_CreateRenderer() as we have been doing all along:

    SDL_Renderer * renderer = SDL_CreateRenderer(window, -1, 0);

But then, rather than creating a texture from a surface, we're now going to create one from scratch using SDL_CreateTexture():

    SDL_Texture * texture = SDL_CreateTexture(renderer,
        SDL_PIXELFORMAT_ARGB8888, SDL_TEXTUREACCESS_STATIC, 640, 480);

We pass in several parameters. The first one is the renderer, and the last two are the width and height of the texture.

The second parameter, which we have set to SDL_PIXELFORMAT_ARGB8888, is the pixel format. There are many possible formats (see SDL_CreateTexture() documentation), but in this case we're saying that each pixel a 32-bit value, where there are 8 bits for alpha (opacity/transparency), 8 bits for red, 8 bits for green and 8 bits for blue. These four items are collectively known as channels (e.g. the alpha channel), so each channel consists of one byte and it can range between 0 and 255. The arrangement below thus represents a single pixel:

Alpha Red Green Blue
8 bits 8 bits 8 bits 8 bits

The SDL_TEXTUREACCESS_STATIC defines a method of accessing the texture. Since we're storing our pixels in CPU memory and then copying them over to the GPU, static access is suitable. On the other hand, streaming access is used to allocate pixels in a back buffer in video memory, and that's suitable for more complex scenarios.

Finally, we initialise a set of pixels that we'll be copying onto the window. When we draw stuff, we'll modify these pixels, and then they'll be copied onto the window to reflect the update.

    Uint32 * pixels = new Uint32[640 * 480];

We'll need to clean up all the stuff we just allocated, so add the following just before the other cleanup calls at the end of the code:

    delete[] pixels;
    SDL_DestroyTexture(texture);
    SDL_DestroyRenderer(renderer);

At the beginning of the while loop, we may now add the following call:

        SDL_UpdateTexture(texture, NULL, pixels, 640 * sizeof(Uint32));

In this code, we are using SDL_UpdateTexture() to copy our pixels onto the window. We pass it our texture, a region of the texture to update (in our case NULL means to update the entire texture), our array of pixels, and the size in bytes of a single row of pixels (called the pitch). In our case, our window has a width of 640 pixels. Therefore a single row consists of 640 4-byte pixels, hence the multiplication.

At the end of our while loop, we may now render our texture as we have done in previous articles:

        SDL_RenderClear(renderer);
        SDL_RenderCopy(renderer, texture, NULL, NULL);
        SDL_RenderPresent(renderer);

Great. So far, we have... uh... this:


Let's clear the background to white, so that we can draw black pixels over it. We could do that using SDL_SetRenderDrawColor() as we did in yesterday's article, "SDL2: Keyboard and Mouse Movement (Events)". But since we can now manipulate pixels directly, let's try something. First, add this at the top:

#include <iostream>

Now, we can use the standard function memset() to overwrite our pixels. Add this right after the declaration of pixels:

memset(pixels, 255, 640 * 480 * sizeof(Uint32));

Good, it's white now:


Now, let's add some code to draw black pixels when the mouse is clicked. First, add the following flag at the beginning of main():

    bool leftMouseButtonDown = false;

Then, add this inside the switch statement:

        case SDL_MOUSEBUTTONUP:
            if (event.button.button == SDL_BUTTON_LEFT)
                leftMouseButtonDown = false;
            break;
        case SDL_MOUSEBUTTONDOWN:
            if (event.button.button == SDL_BUTTON_LEFT)
                leftMouseButtonDown = true;
        case SDL_MOUSEMOTION:
            if (leftMouseButtonDown)
            {
                int mouseX = event.motion.x;
                int mouseY = event.motion.y;
                pixels[mouseY * 640 + mouseX] = 0;
            }
            break;

Right, so we're keeping track of whether the left mouse button is pressed. When it's pressed (SDL_MOUSEBUTTONDOWN), leftMouseButtonDown is set to true, and when it's released (SDL_MOUSEBUTTONUP), leftMouseButtonDown is set to false.

If the mouse is moving (SDL_MOUSEMOTION) and the left mouse button is currently down, then the pixel at its location is set to black (or zero, which is the same thing). Note that I intentionally left out a break statement at the end of the SDL_MOUSEBUTTONDOWN case, so that the drawing code in SDL_MOUSEMOTION is executed along with its own.

So now we can draw our hearts out:


Sweet! That was all we needed in order to draw pixels directly onto our window. Before I wrap up, here's the full code I'm using:

#include <iostream>
#include <SDL.h>

int main(int argc, char ** argv)
{
    bool leftMouseButtonDown = false;
    bool quit = false;
    SDL_Event event;

    SDL_Init(SDL_INIT_VIDEO);

    SDL_Window * window = SDL_CreateWindow("SDL2 Pixel Drawing",
        SDL_WINDOWPOS_UNDEFINED, SDL_WINDOWPOS_UNDEFINED, 640, 480, 0);

    SDL_Renderer * renderer = SDL_CreateRenderer(window, -1, 0);
    SDL_Texture * texture = SDL_CreateTexture(renderer,
        SDL_PIXELFORMAT_ARGB8888, SDL_TEXTUREACCESS_STATIC, 640, 480);
    Uint32 * pixels = new Uint32[640 * 480];
    memset(pixels, 255, 640 * 480 * sizeof(Uint32));

    while (!quit)
    {
        SDL_UpdateTexture(texture, NULL, pixels, 640 * sizeof(Uint32));
        SDL_WaitEvent(&event);

        switch (event.type)
        {
        case SDL_MOUSEBUTTONUP:
            if (event.button.button == SDL_BUTTON_LEFT)
                leftMouseButtonDown = false;
            break;
        case SDL_MOUSEBUTTONDOWN:
            if (event.button.button == SDL_BUTTON_LEFT)
                leftMouseButtonDown = true;
        case SDL_MOUSEMOTION:
            if (leftMouseButtonDown)
            {
                int mouseX = event.motion.x;
                int mouseY = event.motion.y;
                pixels[mouseY * 640 + mouseX] = 0;
            }
            break;
        case SDL_QUIT:
            quit = true;
            break;
        }

        SDL_RenderClear(renderer);
        SDL_RenderCopy(renderer, texture, NULL, NULL);
        SDL_RenderPresent(renderer);
    }

    delete[] pixels;
    SDL_DestroyTexture(texture);
    SDL_DestroyRenderer(renderer);
    SDL_DestroyWindow(window);
    SDL_Quit();

    return 0;
}

Fantastic! In this article, we learned how to draw pixels directly using SDL2. This involved first creating an SDL2 texture with a specified pixel format, then allocating an array to store those pixels, and finally copying the pixels from the array to the texture. We also used a variety of mouse events to allow the user to actually draw pixels onto the window with the mouse, which is like a simplified version of Microsoft Paint.

I hope you find this useful. Check back for more SDL2 and programming goodness! :)

7 comments:

  1. Hi Daniel, I'm having a bit of trouble. I'm running this code on XCode5, and I'm not exactly sure if I translated everything to C correctly. You can see my code here: https://github.com/karadon/gameOfLife/blob/master/gameOfLife/main.c
    I get the white screen, but nothing is being drawn on screen when I click around. Also, the program does not exit when I click the red quit button (OSX). Any insight would be appreciated.

    ReplyDelete
    Replies
    1. Hi karadon, I've tried your code on my Windows machine and (except for a missing cast to (Uint32 *) before the call to calloc()) it works fine and draws pixels. What you are seeing may be some bug in SDL2 specific to Mac OS X (or possibly something wrong with your setup... who knows) - I'm guessing it is tripping up with events since it isn't even catching the SDL_QUIT (red quit button). Unfortunately I don't have a Mac setup, so your best bet would be to ask at the SDL Development forum ( https://forums.libsdl.org/viewforum.php?f=1 ) to try and get additional insight into the problem.

      Oh, what you can also try is... stick an SDL_GetError() at various parts of the program and see whether it gives you anything. Refer to http://www.programmersranch.com/2013/11/sdl2-displaying-image-in-window.html for how to do this.

      Delete
  2. Isn't it better to make sure to fully process the event queue on each iteration? It's what everyone else seems to do, and it makes sense since updating the texture is an expensive operation (in this context). If you do that, it also works properly on OSX. Right now you wait for >= 1 event, then you process exactly 1 event. If you initially got 2 events, process 1, then get yet another one while updating the texture, you'll still only process 1. It makes sense to put a loop around the switch-case, and poll for events there.

    ReplyDelete
    Replies
    1. You raise a valid point. How does this affect OSX though?

      Delete
  3. so nice thanks ,this will help alot of people

    ReplyDelete
  4. Good tutorial, Thanks!!!

    ReplyDelete

Note: Only a member of this blog may post a comment.