sdl_introduction_copy&pastate

 Your first SDL2 application

---

This part will teach you the basic parts of SDL2 namely SDL_Renderer andSDL_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 oldSDL. 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 programmingSDL2 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 manySDL_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. TheSDL_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 aSDL_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 :

int SDL_Init( Uint32 flags)

1

2

3

4

intSDL_Init

(

    Uint32flags

)

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 withSLD_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 :

#include <SDL2/SDL.h>#include <iostream> int main( int argc, char* args[] ){ if ( SDL_Init( SDL_INIT_EVERYTHING ) == -1 ) { std::cout << " Failed to initialize SDL : " << SDL_GetError() << std::endl; return -1; }}

1

2

3

4

5

6

7

8

9

10

11

#include <SDL2/SDL.h>

#include <iostream>

int main(int argc,char*args[])

{

    if( SDL_Init(SDL_INIT_EVERYTHING) ==-1)

    {

        std::cout<< " Failed to initialize SDL : "<< SDL_GetError()<< std::endl;

        return-1;

    }

}

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 :

SDL_Window* SDL_CreateWindow( const char* title, int posX, int posY, int sizeW, int sizeH, Uint32 flags)

1

2

3

4

5

6

7

8

9

SDL_Window*SDL_CreateWindow

(

    constchar*title,

    intposX,

    intposY,

    intsizeW,

    intsizeH,

    Uint32 flags

)

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 themhere

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 passSDL_WINDOW_HIDDEN. Because of this, the SDL_WINDOW_SHOWN flag is ignore bySDL_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 :

// After initializing SDL.... int posX = 100;int posY = 200;int sizeX = 300;int sizeX = 400;SDL_Winow* window; window = SDL_CreateWindow( "Window Title", posX, posY, sizeX, sizeY, SDL_WINDOW_SHOWN );if ( window == nullptr ){ std::cout << "Failed to create window : " << SDL_GetError(); return -1;}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

// After initializing SDL....

intposX =100;

int posY= 200;

intsizeX =300;

int sizeX= 400;

SDL_Winow*window;

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

if (window ==nullptr )

{

    std::cout<< "Failed to create window : "<< SDL_GetError();

    return-1;

}

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 :

SDL_Renderer* SDL_CreateRenderer( SDL_Window* window, int index, Uint32 flags)

1

2

3

4

5

6

SDL_Renderer*SDL_CreateRenderer

(

    SDL_Window*window,

    intindex,

    Uint32flags

)

Parameters :

• window – the SDL_Window this renderer will be attached to. In our case, this is theSDL_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 useSDL_RENDERER_ACCELERATED which lets us use the graphics card to render quickly. You can read morehere.

Return value :

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

As always ; remember to handle any return of 0.

// After initializing SDL....int posX = 100;int posY = 200;int sizeX = 300;int sizeY = 400;SDL_Winow* window;SDL_Renderer* renderer;// Initialize SDL_Window here...renderer = SDL_CreateRenderer( window, -1, SDL_RENDERER_ACCELERATED );if ( renderer == nullptr ){ std::cout << "Failed to create renderer : " << SDL_GetError(); return -1;}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

// After initializing SDL....

 

intposX =100;

int posY= 200;

intsizeX =300;

int sizeY= 400;

SDL_Winow*window;

SDL_Renderer*renderer;

 

// Initialize SDL_Window here...

 

renderer =SDL_CreateRenderer(window,-1,SDL_RENDERER_ACCELERATED);

if( renderer== nullptr)

{

    std::cout<< "Failed to create renderer : "<< SDL_GetError();

    return-1;

}

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 :

int SDL_RenderSetLogicalSize( SDL_Renderer* renderer, int width, int height)

1

2

3

4

5

6

intSDL_RenderSetLogicalSize

(

    SDL_Renderer*renderer,

    intwidth,

    intheight

)

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 theSDL_Window.

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

int SDL_SetRenderDrawColor( SDL_Renderer* renderer, Uint8 red, Uint8 green, Uint8 blue, Uint8 alpha)

1

2

3

4

5

6

7

8

intSDL_SetRenderDrawColor

(

    SDL_Renderer*renderer,

    Uint8 red,

    Uint8green,

    Uint8 blue,

    Uint8alpha

)

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!

// After initializing SDL.... int posX = 100;int posY = 200;int sizeX = 300;int sizeY = 400;SDL_Winow* window;SDL_Renderer* renderer;// Initialize SDL_Window here...renderer = SDL_CreateRenderer( window, -1, 0 );if ( renderer == nullptr ){ std::cout << "Failed to create renderer : " << SDL_GetError(); return -1;}// Set size of renderer to the same as windowSDL_RenderSetLogicalSize( renderer, sizeX, sizeY ); // Set color of renderer to redSDL_SetRenderDrawColor( renderer, 255, 0, 0, 255 );

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

// After initializing SDL....

intposX =100;

int posY= 200;

intsizeX =300;

int sizeY= 400;

SDL_Winow*window;

SDL_Renderer*renderer;

 

// Initialize SDL_Window here...

 

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

if( renderer== nullptr)

{

    std::cout<< "Failed to create renderer : "<< SDL_GetError();

    return-1;

}

 

// Set size of renderer to the same as window

SDL_RenderSetLogicalSize(renderer,sizeX,sizeY );

// Set color of renderer to red

SDL_SetRenderDrawColor(renderer,255,0,0,255 );

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 usingSDL_SetRenderDrawColor()

This is done by calling :

int SDL_RenderClear( SDL_Renderer* renderer)

1

2

3

4

intSDL_RenderClear

(

    SDL_Renderer*renderer

)

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 ( includingSDL_RenderClear ) to take effect, we need to call another function.

int SDL_RenderPresent( SDL_Renderer* renderer)

1

2

3

4

intSDL_RenderPresent

(

    SDL_Renderer*renderer

)

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.

#include<SDL2/SDL.h>#include<iostream> intmain( int argc, char* args[] ){int posX =100;int posY =200;int sizeX =300;int sizeY =400;SDL_Window* window;SDL_Renderer* renderer; // Initialize SDL// ==========================================================if (SDL_Init( SDL_INIT_EVERYTHING ) != 0 ){// Something failed, print error and exit.std::cout <<" Failed to initialize SDL : " << SDL_GetError() << std::endl;return -1;} // Create and init the window// ==========================================================window =SDL_CreateWindow( "Server", posX, posY, sizeX, sizeY,0 ); if ( window ==nullptr ){std::cout <<"Failed to create window : " << SDL_GetError();return -1;} // Create and init the renderer// ==========================================================renderer =SDL_CreateRenderer( window, -1, SDL_RENDERER_ACCELERATED ); if ( renderer ==nullptr ){std::cout <<"Failed to create renderer : " << SDL_GetError();return -1;} // Render something// ========================================================== // Set size of renderer to the same as windowSDL_RenderSetLogicalSize( renderer, sizeX, sizeY ); // Set color of renderer to redSDL_SetRenderDrawColor( renderer,255, 0, 0, 255 ); // Clear the window and make it all redSDL_RenderClear( renderer ); // Render the changes above ( which up until now had just happened behind the scenes )SDL_RenderPresent( renderer); // Pause program so that the window doesn't disappear at once.// This willpause for 4000 milliseconds which is the same as 4 secondsSDL_Delay(4000 );}

view raw

---

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 : [e-mail]