[ SDL2 – Part 2 ] Your first SDL2 application

Your first SDL2 application


This part will teach you the basic parts of SDL2 namely SDL_Renderer and SDL_Window, what they do and how we use them in order to create a simple window.

SDL2 structures


The SDL2 library has a substantially improved rendering structure from the old SDL. The new structure is very simple and easy to understand. This is a short tutorial / reference guide that will teach you everything you need to know in order to start programming SDL2 applications.

The two major objects you need to know :

SDL_Window


This is the physical window you see on your screen. One SDL_Window represents one physical window on your screen. You can have as many SDL_Windows as you like. The structs holds info about the window like position, size, window state and window style.

SDL_Renderer


The SDL_Renderer is basically what you use to render to the screen. The renderer is usually tied to a window. One renderer can only render within one window. The SDL_Renderer also contains info about the rending itself like hardware acceleration and v-sync prevention.

This tutorial will focus on creating and setting up these so we can start drawing to our screen.

Setting up SDL2


Before you can use SDL2, you must set it up by initializing it and creating a SDL_Window and a SDL_Renderer This section will help you to just that.

Initializing SDL2


The first thing you need to do is to initialize SDL. This is done using the following function :

Parameters :

  • flags – specifies what you want to initialize. Set it to SDL_INIT_EVERYTHING to initialize everything.

Return value

0 on success -1 oterwise

Since the function can fail ( though it probably won’t ) you should add code that handles this. I also recommend you print an error message with SLD_GetError() because it will tell you what went wrong. This tutorial will do this for the most important setup functions.

This makes our code so far look something like this :

Setting up the SDL_Window


Now that we have initialized SDL2, we can can start creating our window, this is done by using the following function :

Parameters :

  • title -the window caption/title that appears on the top of the window
  • posX – x position of the window.
  • posY – y position of the window.
  • sizeW – width of the window
  • sizeH – height of the window
  • flags – specifies window state or properties. More info here

The flags parameters has a few different possible values I will not go through all of them, but you can read about them here

Here are the flags that are most revelant to us now.

  • SDL_WINDOW_FULLSCREEN -the window will start out in fullscreen mode
  • SDL_WINDOW_FULLSCREEN_DESKTOP -the window will start out in fullscreen mode with the same resoltion as your desktop currently has
  • SDL_WINDOW_OPENGL -for use with OpenGL, see my tutorial on OpenGL
  • SDL_WINDOW_SHOWN -the window will start out being visible
  • SDL_WINDOW_HIDDEN -the window will start out being invisible

The window will always start out visible, regardless of whether SDL_WINDOW_SHOWN is set. The only way to make a window start out as hidden is to pass SDL_WINDOW_HIDDEN. Because of this, the SDL_WINDOW_SHOWN flag is ignore by SDL_CreateWindow, and we can just pass 0 here.

Return value

A valid pointer on success. nullptr / NULL on oterwise

We’ll set the flag parameter to 0 for now. This simply means we’ll end up with a standard window that’s not maximized, minimized or fullscreen.

Remember to handle it if the function returns NULL. So we end up with something like this :

Creating the SDL_Renderer


Now for the last object we need to start rendering. This time it’s a little bit more work involved, but nothing too scary. We begin by creating the renderer. This is done using the following function :

Parameters :

  • window – the SDL_Window this renderer will be attached to. In our case, this is the SDL_Window we just created.
  • index - specifies which rendering driver to use. It sounds complicated, but we can just specify -1. This means we’ll use the first driver we can find.
  • flags - species how the rendering should be done. For now, we’ll just use SDL_RENDERER_ACCELERATED which lets us use the graphics card to render quickly. You can read more here.

Return value :

Window a valid pointer on success. Otherwise nullptr / NULL.

As always ; remember to handle any return of 0.

Setting up the renderer


Now that we have created the SDL_Renderer we are technically ready to start rendering. But there are a few more things we should do first…

First of all we should set the resolution of the renderer :

Parameters :

  • renderer – the SDL_Renderer we want to set the resolution on.
  • width - the desired width in pixels
  • height - the desired height in pixels

Return value

0 on success -1 oterwise

This is pretty straight forward, the first argument is the renderer on which to set the resolution on. The second and third is the width and height. Normally these are the same as the width and height of the SDL_Window.

And now the time has come to set the color. Here is the function for doing that :

Parameters :

  • renderer – the SDL_Renderer on which to set render color
  • red - specifies amount of red ( 0 – 255 )
  • green - specifies amount of green ( 0 – 255 )
  • blue - specifies amount of blue ( 0 – 255 )
  • alpha - specifies amount of alpha ( 0 – 255 ) 0 = completely transparent

Return value

0 on success -1 oterwise

That’s it! We’re done with the setup. And now we can start using the renderer for fun stuff!

Rendering something


Now it’s time to get started on the renderng.
The first thing we need to do before drawing something, is to clear our window. This means we fill our window with the color we set using SDL_SetRenderDrawColor()

This is done by calling :

Parameters :

  • renderer – the SDL_Renderer that we’ll clear

Return value

0 on success -1 oterwise

This function should be called at the beginning on every frame to clear the screen and make it ready for more stuff.


But… SDL_RenderClear ( and any other SDL_Render functions ) works behind the scenes. They don’t actually draw anything on the screen. So, in order for he drawing ( including SDL_RenderClear ) to take effect, we need to call another function.

Parameters :

  • renderer – the SDL_Renderer on which to render

Return value

0 on success -1 oterwise

This function takes whatever you have drawn to the screen using SDL_Render* and actually puts it on the screen. So that after calling this, the screen will be all nice and red. And that’s it for now. In the next part I’ll go into rectangles and actually rendering something interesting ( yes, I assume red screens doesn’t catch your interest. )

Conclusion


That’s if for part 2. We now have a nice red window. Next time we’ll be rendering rects and other neat stuff.

Here is all the code so far. You should be able to just copy paste and compile.


Feel free to comment if you have anything to say or ask questions if anything is unclear. I always appreciate getting comments.

You can also email me : olevegard@headerphile.com

14 thoughts on “[ SDL2 – Part 2 ] Your first SDL2 application”

  1. Thanks for your nice tutorial and your great effort!!
    Just let me make a petittion to improve your work and to make it more comprehensible.
    for example in the case of (there are more cases):
    window = SDL_CreateWindow( “Window Title”, posX, posY, sizeX, sizeY, 0 );

    I think it’s a good habit to use the predefined value if exists, instead a number. It should clarify the code 🙂

    window = SDL_CreateWindow( “Window Title”, posX, posY, sizeX, sizeY, SDL_WINDOW_SHOWN );

    and just a ‘type mistake’ int the 4th code window, just before Creating the SDL_Renderer

    SDL_Winow* window;

    It’s included in the rest of the code

    Keep up the good work!! and thanks for the tutorial!! 😉

    1. Hello and thank you, always nice to see that people are enjoying my tutorials.

      I completely agree with you, hard-coded values are bad, and predefined values helps code clarity ( which is something I try to hugely focus on. ) I will update my posts with the predefined values as soon as I can.

      I will also correct the typo, I tend to make a few of thoose.

      Thank you for both suggestions =)

    2. No, no, no! 0 is a perfectly clear way to indicate “no flags”, and SDL_WINDOW_SHOWN is NOT zero. It is a non-zero value which happens to be ignored by SDL_CreateWindow. It is perhaps a little unfortunate that there isn’t an SDL_WINDOW_NOFLAGS or something, but there isn’t. So just use zero. Don’t confuse the issue by using SDL_WINDOW_SHOWN.

      1. I’m a bit conflicted in this case. The definition of what’s clear varies from person to person. To me, having a random 0 argument confuses me a little. The flag helps describe what this function is for.

        My intention with the blog is to give basic understanding of every aspects of the functions, including the unused arguments.

        I probably will use 0 for the sake of simplicity and instead expand my explanation of SDL_CreateWindow to also include a list of the possible arguments. And yes, there really should be a SDL_WINDOW_NOFLAGS flag

        Again ; thank you for your feedback : )

        1. Well yes, neither of them is ideal. But think about it this way: if you read 0, it’s clear that there’s information you’re missing (and you know that it probably means “none” or “nothing” or “default value”, so if you’re skimming it’s likely safe to ignore it).

          If you read SDL_WINDOW_SHOWN, that encourages you to believe things that are *false* (that it is required, and that you could create a hidden window by leaving it out).

          To me, the latter is clearly the greater evil.

  2. Thank you for your tutorial 🙂

    I just wanted to point out a typo : you wrote the SDL_CreateRenderer parameters two times (look for “parameters window – the SDL_Window this renderer will be attached to”).

    1. Glad my tutorials are of helping 🙂

      And thank you for helping me fix my typos. Should be fixed now along with some other minor annoyances with text formating.

  3. Small typo here:
    The SDL2 library has a substantially improved rendering structure from SDL2.

    I think you want to drop the ‘2’ at the end.
    Your tutorial is helping me significantly.
    js

    1. Yup, you are correct Sir. Fixed now, thanks for poiting it out.

      Glad to see my turorials are helping people. It motivates me to write more 🙂

  4. First of all thanks for that tutorial, it`s the best I have ever seen on that topic, and I was searching for a long time.
    But I have a problem running your code:
    I always get the error that the compiler cannot find a matching render driver.
    Do you have any advice for me?
    Thanks.

    1. Hello 🙂

      Could you copy the error in here? It’s a lot easier to help when I can see the exact error.

  5. Good article!
    You point people to API explanations.

    Just a typo(or few) to point out.
    “Return value
    0 on success -1 oterwise ”
    It occurs in the text in a few places.

    Thank you for the effort!

Leave a Reply

Your email address will not be published. Required fields are marked *