Lesson 7: Taking Advantage of Classes

Deprecation Notice:

I've been updating the lessons now that SDL2 is officially released, please visit my new site on Github that has updated lessons and improved code.


If you recall from the previous lessons we've used a global SDL_Window and SDL_Renderer so that we could access them from within our various functions throughout main.cpp, however using non-constant globals is a very bad idea, and when we start wanting to write more complicated programs this method will become unusable.

In this lesson we will look to object oriented programming to resolve these issues and put together a useful class to represent our Window that we can use for loading and drawing images and text. In addition to this we will discover SDL's more powerful rendering function, SDL_RenderCopyEx, which will allow us to specify rotations about points and flips to apply to the texture when it's drawn.

For this lesson you'll need to have at least some knowledge of C++ classes along with the C++11 std::unique_ptr, as we will be using both throughout the lesson.

Before we jump into coding we'll need to have a plan of how our class looks and how we want it to be used. For simplicity I've chosen to make all members of the class static, which enables us to call the functions on our window from anywhere in the program that includes its header file. It would be undesirable to do this if you plan to use SDL 2.0's new ability to support multiple windows, but for now this method will be acceptable.

Now we can move on to planning out individual functions for our class. Obviously we'll want to bring in our ApplySurface, LoadImage and RenderText functions from the previous lessons. In addition to this we will need some sort of initialization and quitting functions to create and close the window and start/exit SDL and SDL_ttf. We'll also need to be able to tell the window when to clear and present, and it would be useful to get the window's width and height, so we'll make a function for that as well.

So here's what we've got planned out for the Window class:

	#ifndef WINDOW_H
	#define WINDOW_H
	//What we think our window class should look like
	class Window {
	public:
	//Start SDL and TTF, create the window and renderer
	static void Init();
	//Quit SDL and TTF
	static void Quit();
	//Draw an SDL_Texture
	static void Draw(SDL_Texture*, ...);
	//Load an image
	static SDL_Texture* LoadImage(std::string file);
	//Render some text
	static SDL_Texture* RenderText(std::string, std::string, SDL_Color, int);
	//Clear window
	static void Clear();
	//Present renderer
	static void Present();
	//Get the window's box
	static SDL_Rect Box();
	private:
	static SDL_Window* mWindow;
	static SDL_Renderer* mRenderer;
	static SDL_Rect mBox;
	};
	#endif

view raw 1.h hosted with ❤ by GitHub

Where I've included the appropriate header guards and renamed ApplySurface to Draw and omitted most of its parameters as they'll be a good bit longer now that we also need to pass a rotation angle, point of rotation and flip to SDL_RenderCopyEx.

This looks pretty good for a simple Window class, so lets start turning it into real code.

The first thing I want to cover is how we'll be handling our SDL_Window and SDL_Renderer. Instead of using a raw pointer and calling SDL_DestroyX in the Quit function, we'll be using a new C++11 feature known as the std::unique_ptr. This pointer is included in the <memory> header and allows for use of lifetime managed objects. In the case of the unique_ptr it allows for only one pointer to use the object at a time and once that pointer goes out of scope it will call the destructor function chosen for the pointer, freeing the memory automatically.

It's easy to see how this unique_ptr can be useful, we don't need to worry about managing the objects memory and we don't need to worry about it not being freed in the case that an error arises. Suppose in our program we were to hit some runtime error and crash out of a function or the whole program without calling the necessary memory releasing functions. The memory would never be freed! However with a unique_ptr it would go out of scope, calling either the default destructor of the object, or a specified function passed to it to clean up the memory. Very handy indeed!

This is not to say that the new unique_ptr, shared_ptr and weak_ptr are a magical band-aid to resolve any memory issues in C++11 as they most certainly are not. Raw pointers still have their place and misuse of the new types will still result in memory issues. It's important to use the appropriate type for the application. In this case the unique_ptr is an excellent choice for our use.

Since we want to use the SDL_DestroyX function instead of the object's destructor to free the managed object, we need to specify the function signature of  the desired destruction function to our unique_ptr, which in this case is the signature for SDL_DestroyX, which is void(*)(SDL_X*). So mWindow and mRenderer will end up being:

	private:
	static std::unique_ptr<SDL_Window, void (*)(SDL_Window*)> mWindow;
	static std::unique_ptr<SDL_Renderer, void (*)(SDL_Renderer*)> mRenderer;
	static SDL_Rect mBox;
	};

view raw 2.h hosted with ❤ by GitHub

Now that we know how mWindow and mRenderer will be implemented we can move on to writing our functions, and declaring the static member variables in window.cpp.

First, the declaration of our variables: mWindow, mRenderer and mBox.

	//Initialize the unique_ptr's deleters here
	std::unique_ptr<SDL_Window, void (*)(SDL_Window*)> Window::mWindow
	= std::unique_ptr<SDL_Window, void (*)(SDL_Window*)>(nullptr, SDL_DestroyWindow);
	std::unique_ptr<SDL_Renderer, void (*)(SDL_Renderer*)> Window::mRenderer
	= std::unique_ptr<SDL_Renderer, void (*)(SDL_Renderer*)>(nullptr, SDL_DestroyRenderer);
	//Other static members
	SDL_Rect Window::mBox;

view raw 3.cpp hosted with ❤ by GitHub

It looks a bit messy, but it really isn't so bad. We simply set our unique_ptrs to be pointing to the appropriate destructor function and set the data to nullptr.

As mentioned earlier, our constructor and destructor do nothing, so we'll skip covering writing those, as there's nothing to write and jump into putting together our Init function.

For Init we just want to start up SDL and TTF and create our SDL_Window and SDL_Renderer, so we just want to take lines 75-97 of Lesson6 main.cpp and put them into their own function, and allow for a string to be passed that will be set as the window title. Simple enough! So our function definition will look like:

	//In window.h
	/**
	* Initialize SDL, setup the window and renderer
	* @param title The window title
	*/
	static void Init(std::string title = "Window");

view raw 4.h hosted with ❤ by GitHub

Where I have used doxygen style comments, to enable usage of doxygen to generate easy to understand documentation for the code. Our implementation of the function is simply lines 75-97 of the previous lesson:

	//In window.cpp
	void Window::Init(std::string title){
	//initialize all SDL subsystems
	if (SDL_Init(SDL_INIT_EVERYTHING) == -1)
	throw std::runtime_error("SDL Init Failed");
	if (TTF_Init() == -1)
	throw std::runtime_error("TTF Init Failed");
	//Setup our window size
	mBox.x = 0;
	mBox.y = 0;
	mBox.w = 640;
	mBox.h = 480;
	//Create our window
	mWindow.reset(SDL_CreateWindow(title.c_str(), SDL_WINDOWPOS_CENTERED,
	SDL_WINDOWPOS_CENTERED, mBox.w, mBox.h, SDL_WINDOW_SHOWN));
	//Make sure it created ok
	if (mWindow == nullptr)
	throw std::runtime_error("Failed to create window");
	//Create the renderer
	mRenderer.reset(SDL_CreateRenderer(mWindow.get(), -1,
	SDL_RENDERER_ACCELERATED | SDL_RENDERER_PRESENTVSYNC));
	//Make sure it created ok
	if (mRenderer == nullptr)
	throw std::runtime_error("Failed to create renderer");
	}

view raw 4.cpp hosted with ❤ by GitHub

This function should look very familiar, the only difference being that we use the unique_ptr reset function to change the data that it points to, instead of the previous methods used. In this case we simply change the nullptr they're currently managing to the created SDL_Window or SDL_Renderer that they should be managing.

The Quit function is very simple, we just take the SDL_Quit and TTF_Quit calls and put them into the function.

	//In window.h
	///Quit SDL and destroy the window and renderer
	static void Quit();

view raw 5.h hosted with ❤ by GitHub

	//In window.cpp
	void Window::Quit(){
	TTF_Quit();
	SDL_Quit();
	}

view raw 5.cpp hosted with ❤ by GitHub

The most changed function is our former ApplySurface function (now named Draw), which we'll need to rework to enable us to pass the extra parameters needed by SDL_RenderCopyEx. If we take a look at the documentation for the function we can see that in addition to a texture pointer, destination rect and clip rect we need an angle (in degrees), a pivot point and a flip value.

So now we know what we need, and can write the function, however I've chosen to pass the pivot point values as separate ints instead of an SDL_Point, in the future we'll create a 2d vector class and use that instead, which will also enable us to perform more advanced vector math. So our function will look like so:

	//In window.h
	/**
	* Draw a SDL_Texture to the screen at dstRect with various other options
	* @param tex The SDL_Texture to draw
	* @param dstRect The destination position and width/height to draw the texture with
	* @param clip The clip to apply to the image, if desired
	* @param angle The rotation angle to apply to the texture, default is 0
	* @param xPivot The x coordinate of the pivot, relative to (0, 0) being center of dstRect
	* @param yPivot The y coordinate of the pivot, relative to (0, 0) being center of dstRect
	* @param flip The flip to apply to the image, default is none
	*/
	static void Draw(SDL_Texture *tex, SDL_Rect &dstRect, SDL_Rect *clip = NULL,
	float angle = 0.0, int xPivot = 0, int yPivot = 0,
	SDL_RendererFlip flip = SDL_FLIP_NONE);

view raw 6.h hosted with ❤ by GitHub

Be sure to note the default parameters we've chosen, if we pass just a texture and destination, we'll get an upright drawing of the texture within the destination rectangle, with the rest of the parameters defaulting to no change.

Our function is quite easy to write as it's simply serving as a wrapper around SDL_RenderCopyEx, with one extra thing. For simplicity we want the pivot point we pass to be relative to the center of the dstRect, while SDL will consider the point relative to the texture's X and Y coordinates, so we must add an offset to center it. Alternatively, if NULL is passed as the SDL_Point* parameter it will set the rotation about the destination rect's center.

	void Window::Draw(SDL_Texture *tex, SDL_Rect &dstRect, SDL_Rect *clip, float angle,
	int xPivot, int yPivot, SDL_RendererFlip flip)
	{
	//Convert pivot pos from relative to object's center to screen space
	xPivot += dstRect.w / 2;
	yPivot += dstRect.h / 2;
	//SDL expects an SDL_Point as the pivot location
	SDL_Point pivot = { xPivot, yPivot };
	//Draw the texture
	SDL_RenderCopyEx(mRenderer.get(), tex, clip, &dstRect, angle, &pivot, flip);
	}

view raw 6.cpp hosted with ❤ by GitHub

There's one other new thing tucked away in the call to SDL_RenderCopyEx, which is that in order to access the raw SDL_Renderer pointer that the function expects we use mRenderer.get() to get it from the unique_ptr.

Next we define our LoadImage and RenderText functions:

	//In window.h
	/**
	* Loads an image directly to texture using SDL_image's
	* built in function IMG_LoadTexture
	* @param file The image file to load
	* @return SDL_Texture* to the loaded texture
	*/
	static SDL_Texture* LoadImage(const std::string &file);
	/**
	* Generate a texture containing the message we want to display
	* @param message The message we want to display
	* @param fontFile The font we want to use to render the text
	* @param color The color we want the text to be
	* @param fontSize The size we want the font to be
	* @return An SDL_Texture* to the rendered message
	*/
	static SDL_Texture* RenderText(const std::string &message, const std::string &fontFile,
	SDL_Color color, int fontSize);

view raw 7.h hosted with ❤ by GitHub

I leave writing the function to you as it's the same as the definitions in Lesson 7 with the small change to passing mRenderer.get() in place of renderer.

Finally we define our Clear, Present and Box functions. Clear simply calls SDL_RenderClear on mRenderer and Present does the same for SDL_RenderPresent. Box lets us return an SDL_Rect containing the window's width and height, which we can query using SDL_GetWindowSize. Our functions will look like:

	//In window.h
	///Clear the renderer
	static void Clear();
	///Present the renderer, ie. update screen
	static void Present();
	///Get the window's box
	static SDL_Rect Box();

view raw 8.h hosted with ❤ by GitHub

	//In window.cpp
	void Window::Clear(){
	SDL_RenderClear(mRenderer.get());
	}
	void Window::Present(){
	SDL_RenderPresent(mRenderer.get());
	}
	SDL_Rect Window::Box(){
	//Update mBox to match the current window size
	SDL_GetWindowSize(mWindow.get(), &mBox.w, &mBox.h);
	return mBox;
	}

view raw 8.cpp hosted with ❤ by GitHub

If you have issues working out the class, my implementation can be found at the Github repo, window.h and window.cpp. Now that we've got our Window class written, it's time to try it out in an application and make sure it works.

In main.cpp we now will also need to include our window header, "window.h" in order to use the class. Instead of calling SDL_Init and etc. as done previously we can now call Window::Init and catch any errors it may throw to create our window and make sure it went ok.

	//In main()
	//Start our window
	try {
	Window::Init("Lesson 7");
	}
	catch (const std::runtime_error &e){
	std::cout << e.what() << std::endl;
	Window::Quit();
	return -1;
	}

view raw 9.cpp hosted with ❤ by GitHub

We can then load images and render text using the LoadImage and RenderText functions from our class.

	//Load up an image and some text
	SDL_Texture *img, *msg;
	try {
	//Load the image
	std::string imgFile = "../res/Lesson7/image.png";
	img = Window::LoadImage(imgFile);
	//Load the font and message
	std::string fontFile = "../res/Lesson7/SourceSansPro-Regular.ttf";
	std::string text = "TTF Fonts too!";
	SDL_Color color = { 255, 255, 255 };
	msg = Window::RenderText(text, fontFile, color, 25);
	}
	catch (const std::runtime_error &e){
	//Catch error and crash
	std::cout << e.what() << std::endl;
	Window::Quit();
	return -1;
	}

view raw 10.cpp hosted with ❤ by GitHub

Here we also perform error catching to respond appropriately to any errors that may be thrown by the functions. Now we can make use of our Box function to find the center of the window and set a position rect to draw our image and text too.

	//Set a position to draw it with
	SDL_Rect pos = { Window::Box().w / 2 - 150 / 2,
	Window::Box().h / 2 - 150 / 2, 150, 150 };
	//The angle to draw at, so we can play with it
	int angle = 0;

view raw 11.cpp hosted with ❤ by GitHub

In addition we create a variable called angle so that we can test out drawing things with some rotation. To change the variable we add some keydown checks to increase or decrease the value of angle.

	//Inside the SDL_KEYDOWN sym switch, within the event polling loop
	//For rotating image
	case SDLK_d:
	angle += 2;
	break;
	case SDLK_a:
	angle -= 2;
	break;

view raw 12.cpp hosted with ❤ by GitHub

Finally we can use the new Window functions to Clear, Draw and Present our screen with a simple call:

	//RENDERING
	Window::Clear();
	Window::Draw(img, pos, NULL, angle);
	Window::Draw(msg, pos, NULL, angle, 0, 0, SDL_FLIP_VERTICAL);
	Window::Present();

view raw 13.cpp hosted with ❤ by GitHub

And before exiting the program, we simply call Destroy on the textures and Window::Quit to exit SDL and TTF.

Lesson 7 Extra Challenge!

Make it possible to set the window width and height when calling Init

Hint

Super simple! Just pass a width and height to Init.

End of Lesson 7

Thanks for joining me! See you again soon in Lesson 8: Timers.