Whenever you're utilizing a library of any sorts for your project, it's important to know what you can and cannot use it for. SFML is licensed under the zlib/libpng license, which is far from being restrictive. It allows anyone to use SFML for any purposes, even commercial applications, as well as alter and re-distribute it, given that the credit for writing the original software is left unchanged and the product is marked as an altered source. Giving credit for using the original software isn't required, but it would be appreciated. For more information, visit: http://opensource.org/licenses/Zlib.

You can download the latest stable pre-built version of the library at: http://www.sfml-dev.org/download.php. It is also possible for you to get the latest Git revision and compile it yourself from here: https://github.com/LaurentGomila/SFML. The former option is easier and recommended for beginners. You have to wait for major versions to be released, however they're more stable. To build SFML yourself, you will need to use CMake, which is a tool used to generate solutions or g++ Makefiles, depending on the software that will be used to compile it. The official SFML website provides tutorials on building it yourself at: http://www.sfml-dev.org/tutorials.

After either obtaining the pre-built version of SFML or compiling it yourself, it's a good idea to move it somewhere more permanent, hopefully with a short path. It's not unusual to dedicate a directory somewhere on your local drive that will hold SFML and potentially other libraries, which can be linked to quickly and at all times. This becomes useful when dealing with several versions of the same library as well. For the rest of this book, we will assume the location of our SFML library and header directories to be at C:\libs\SFML-2.3, consequently being C:\libs\SFML-2.3\lib and C:\libs\SFML-2.3\include. These directories have to be set up correctly in your compiler of choice for the project to build. We will be using Microsoft Visual Studio 2013 throughout the course of this book, however instructions on setting up projects for Code::Blocks can be found in the tutorials section of the SFML website.

As you probably know, drawing something on screen requires a window to be present. Luckily, SFML allows us to easily open and manage our very own window! Let's start out as usual by adding a file to our project, named Main.cpp. This will be the entry point to our application. The bare bones of a basic application look like this:

#include <SFML/Graphics.hpp>

void main(int argc, char** argv[]){
    
}

Note that we've already included the SFML graphics header. This will provide us with everything needed to open a window and draw to it, so without further ado, let's take a look at the code that opens our window:

#include <SFML/Graphics.hpp>

void main(int argc, char** argv[]){
  sf::RenderWindow window(sf::VideoMode(640,480), "First window!");

  while(window.isOpen()){
    sf::Event event;
    while(window.pollEvent(event)){
      if(event.type == sf::Event::Closed){
        // Close window button clicked.
        window.close();
      }
    }
    window.clear(sf::Color::Black);
    // Draw here.
    window.display();
  }
}

The first thing we did here is declare and initialize our window instance of type RenderWindow. In this case, we used its constructor, however it is possible to leave it blank and utilize its create method later on by passing in the exact same arguments, of which it can take as little as two: an sf::videoMode and an std::string title for the window. The video mode's constructor takes two arguments: the inner window width and height. There is a third optional argument that sets color depth in bits per pixel. It defaults to 32, which is more than enough for good rendering fitting our purposes, so let's not lose sleep over that now.

After the instance of our window is created, we enter a while loop that utilizes one of our window methods to check if it's still open, isOpen. This effectively creates our game loop, which is a central piece of all of our code.

Let's take a look at a diagram of a typical game:

The purpose of a game loop is to check for events and input, update our game world between frames, which means moving the player, enemies, checking for changes, and so on, and finally draw everything on the screen. This process needs to be repeated many times a second until the window is closed. The amount of times varies from application to application, sometimes going as high as thousands of iterations per second. Chapter 2, Give It Some Structure - Building the Game Framework will cover managing and capping the frame rate of our applications as well as making the game run at constant speeds.

Most applications need to have a way to check if a window has been closed, resized, or moved. That's where event processing comes in. SFML provides an event class that we can use to store our event information. During each iteration of our game loop, we need to check for the events that took place by utilizing the pollEvent method of our window instance and process them. In this case, we're only interested in the event that gets dispatched when a mouse clicks on the close window button. We can check if the public member type of class Event matches the proper enumeration member, in this case it's sf::Event::Closed. If it does, we can call the close method of our window instance and our program will terminate.

After all of that is done, it's necessary to clear the window from the previous iteration. Failing to do so would result in everything we draw on it stacking and creating a mess. Imagine the screen is a whiteboard and you want to draw something new on it after someone else already scribbled all over it. Instead of grabbing the eraser, however, we need to call the clear method of our window instance, which takes a sf::Color data type as an argument and defaults to the color black if an argument isn't provided. The screen can be cleared to any of its enumerated colors that the sf::Color class provides as static members or we can pass an instance of sf::Color, which has a constructor that takes unsigned integer values for individual color channels: red, green, blue, and optionally alpha. The latter gives us a way to explicitly specify the color of our desired range, like so:

window.clear(sf::Color(0,0,0,255));

Finally, we call the window.display() method to show everything that was drawn. This utilizes a technique known as double buffering, which is standard in games nowadays. Basically, anything that is drawn isn't drawn on the screen instantly, but instead to a hidden buffer which then gets copied to our window once display is called. Double buffering is used to prevent graphical artifacts, such as tearing, which occurs due to video card drivers pulling from the frame buffer while it's still being written to, resulting in a partially drawn image being displayed. Calling the display method is mandatory and cannot be avoided, otherwise the window will show up as a static square with no changes taking place.

Upon compilation and execution of the code, we will find ourselves with a blank console window and a black 640x480 px window sitting over it, fewer than 20 lines of code, and an open window. Not very exciting, but it's still better than E.T. for Atari 2600. Let's draw something on the screen!

Much like in kindergarten, we will start with basic shapes and make our way up to more complex types. Let's work on rendering a rectangle shape by first declaring it and setting it up:

sf::RectangleShape rectangle(sf::Vector2f(128.0f,128.0f));
rectangle.setFillColor(sf::Color::Red);
rectangle.setPosition(320,240);

sf::RectangleShape is a derived class of sf::Shape that inherits from sf::Drawable, which is an abstract base class that all entities must inherit from and implement its virtual methods in order to be able to be drawn on screen. It also inherits from sf::Transformable, which provides all the necessary functionality in order to move, scale, and rotate an entity. This relationship allows our rectangle to be transformed, as well as rendered to the screen. In its constructor, we've introduced a new data type: sf::Vector2f. It's essentially just a struct of two floats, x and y, that represent a point in a two-dimensional universe, not to be confused with the std::vector, which is a data container.

sf::Vector2<long> m_vector;

The rectangle constructor takes a single argument of sf::Vector2f which represents the size of the rectangle in pixels and is optional. On the second line, we set the fill color of the rectangle by providing one of SFML's predefined colors this time. Lastly, we set the position of our shape by calling the setPosition method and passing its position in pixels alongside the x and y axis, which in this case is the centre of our window. There is only one more thing missing until we can draw the rectangle:

window.draw(rectangle); // Render our shape.

This line goes right before we call window.display(); and is responsible for bringing our shape to the screen. Let's run our revised application and take a look at the result:

Now we have a red square drawn on the screen, but it's not quite centered. This is because the default origin of any sf::Transformable, which is just a 2D point that represents the global position of the object, is at the local coordinates (0,0), which is the top left corner. In this case, it means that the top left corner of this rectangle is set to the position of the screen centre. That can easily be resolved by calling the setOrigin method and passing in the desired local coordinates of our shape that will represent the new origin, which we want to be right in the middle:

rectangle.setOrigin(64.0f,64.0f);

If the size of a shape is unknown for whatever reason, the rectangle class provides a nice method getSize, which returns a float vector containing the size:

rectangle.setOrigin(rectangle.getSize().x / 2, rectangle.getSize().y / 2);

Now our shape is sitting happily in the very middle of the black screen. The entire segment of code that makes this possible looks a little something like this:

#include <SFML/Graphics.hpp>

void main(int argc, char** argv[]){
  sf::RenderWindow window(sf::VideoMode(640,480),
    "Rendering the rectangle.");

  // Creating our shape.
  sf::RectangleShape rectangle(sf::Vector2f(128.0f,128.0f));
  rectangle.setFillColor(sf::Color::Red);
  rectangle.setPosition(320,240);
  rectangle.setOrigin(rectangle.getSize().x / 2, rectangle.getSize().y / 2);

  while(window.isOpen()){
    sf::Event event;
    while(window.pollEvent(event)){
      if(event.type == sf::Event::Closed){
        // Close window button clicked.
        window.close();
      }
    }
    window.clear(sf::Color::Black);
    window.draw(rectangle); // Drawing our shape.
    window.display();
  }
}

In order to draw an image on screen, we need to become familiar with two classes: sf::Texture and sf::Sprite. A texture is essentially just an image that lives on the graphics card for the purpose of making it fast to draw. Any given picture on your hard drive can be turned into a texture by loading it:

sf::Texture texture;
if(!texture.loadFromFile("filename.png"){
    // Handle an error.
}

The loadFromFile method returns a Boolean value, which serves as a simple way of handling loading errors, such as the file not being found. If you have a console window open along with your SFML window, you will notice some information being printed out in case the texture loading did fail:

Failed to load image "filename.png". Reason : Unable to open file

It's also possible to load your textures from memory, custom input streams, or sf::Image utility classes, which help store and manipulate image data as raw pixels, which will be covered more broadly in later chapters.

What is a sprite?

A sprite, much like the sf::Shape derivatives we've worked with so far, is a sf::Drawable object, which in this case represents a sf::Texture and also supports a list of transformations, both physical and graphical. Think of it as a simple rectangle with a texture applied to it:

sf::Sprite provides the means of rendering a texture, or a part of it, on screen, as well as means of transforming it, which makes the sprite dependent on the use of textures. Since sf::Texture isn't a lightweight object, sf::Sprite comes in for performance reasons to use the pixel data of a texture it's bound to, which means that as long as a sprite is using the texture it's bound to, the texture has to be alive in memory and can only be de-allocated once it's no longer being used. After we have our texture set up, it's really easy to set up the sprite and draw it:

sf::Sprite sprite(texture);
...
window.draw(sprite);

It's optional to pass the texture by reference to the sprite constructor. The texture it's bound to can be changed at any time by using the setTexture method:

sprite.setTexture(texture);

Since sf::Sprite, just like sf::Shape, inherits from sf::Transformable, we have access to the same methods of manipulating and obtaining origin, position, scale, and rotation.

It's time to apply all the knowledge we've gained so far and write a basic application that utilizes it:

void main(int argc, char** argv[]){
  sf::RenderWindow window(sf::VideoMode(640,480),
    "Bouncing mushroom.");

  sf::Texture mushroomTexture;
  mushroomTexture.loadFromFile("Mushroom.png");
  sf::Sprite mushroom(mushroomTexture);
  sf::Vector2u size = mushroomTexture.getSize();
  mushroom.setOrigin(size.x / 2, size.y / 2);
  sf::Vector2f increment(0.4f, 0.4f);

  while(window.isOpen()){
    sf::Event event;
    while(window.pollEvent(event)){
      if(event.type == sf::Event::Closed){
        window.close();
      }
    }

    if((mushroom.getPosition().x + (size.x / 2) >
      window.getSize().x && increment.x > 0) ||
      (mushroom.getPosition().x - (size.x / 2) < 0 &&
      increment.x < 0))
    {
        // Reverse the direction on X axis.
        increment.x = -increment.x;
    }

    if((mushroom.getPosition().y + (size.y / 2) >
      window.getSize().y && increment.y > 0) ||
      (mushroom.getPosition().y - (size.y / 2) < 0 &&
      increment.y < 0))
    {
         // Reverse the direction on Y axis.
        increment.y = -increment.y;
    }

    mushroom.setPosition(mushroom.getPosition() + increment);

    window.clear(sf::Color(16,16,16,255)); // Dark gray.
    window.draw(mushroom); // Drawing our sprite.
    window.display();
  }
}

The code above will produce a sprite bouncing around the window, reversing in direction every time it hits the window boundaries. Error checking for loading the texture is omitted in this case in order to keep the code shorter. The two if statements after the event handling portion in the main loop are responsible for checking the current position of our sprite and updating the direction of the increment value represented by a plus or minus sign, since you can only go towards the positive or negative end on a single axis. Remember that the origin of a shape by default is its top-left corner, as shown here:

Because of this, we must either compensate for the entire width and height of a shape when checking if it's out-of-bounds on the bottom or the right side, or make sure its origin is in the middle. In this case, we do the latter and either add or subtract half of the texture's size from the mushroom's position to check if it is still within our desired space. If it's not, simply invert the sign of the increment float vector on the axis that is outside the screen and voila! We have bouncing!

For extra credit, feel free to play around with the sf::Sprite's setColor method, which can be used to tint a sprite with a desired color, as well as make it transparent, by adjusting the fourth argument of the sf::Color type, which corresponds to the alpha channel:

mushroom.setColor(sf::Color(255, 0, 0, 255)); // Red tint.

Oftentimes, new users of SFML attempt to do something like this:

sf::Sprite CreateSprite(std::string l_path){
    sf::Texture texture;
    texture.loadFromFile(l_path);
    . . .
    return sf::Sprite(texture);
}

When attempting to draw the returned sprite, a white square pops out where the sprite is supposed to be located. What happened? Well, take a look back at the section where we covered textures. The texture needs to be within scope as long as it's being used by a sprite because it stores a pointer to the texture instance. From the example above, we can see that it is statically allocated, so when the function returns, the texture that got allocated on the stack is now out of scope and gets popped. Poof. Gone. Now the sprite is pointing to an invalid resource that it cannot use and instead draws a white rectangle. Now this is not to say that you can't just allocate memory on the heap instead by making a new call, but that's not the point of this example. The point to take away from this is that proper resource management is paramount when it comes to any application, so pay attention to the life span of your resources. In Chapter 6, Set It in Motion! – Animating and Moving around Your World, we will cover designing your own resource manager and automatically dealing with situations like this.

Another common mistake is keeping too many texture instances around. A single texture can be used by as many sprites as one's heart desires. sf::Texture is not a lightweight object at all, where it's possible to keep tons of sf::Sprite instances using the same texture and still achieve great performance. Reloading textures is also expensive for the graphics card, so keeping as few textures as possible is one of the things you really need to remember if you want your application to run fast. That's the idea behind using tile sheets, which are just large textures with small images packed within them. This grants better performance, since instead of keeping around hundreds of texture instances and loading files one by one, we get to simply load a single texture and access any desired tile by specifying the area to read from. That will also receive more attention in later chapters.

Using unsupported image formats or format options is another fairly common issue. It's always best to consult the official website for the most up to date information on file format support. A short list can be found here: http://www.sfml-dev.org/documentation/2.2/classsf_1_1Image.php#a9e4f2aa8e36d0cabde5ed5a4ef80290b

Finally, the LNK2019 errors deserve a mention. It doesn't matter how many times a guide, tutorial, or book mentions how to properly set up and link your project to any given library. Nothing is perfect in this world, especially not a human being. Your IDE output may get flooded by messages that look something like this when trying to compile your project:

error LNK2019: unresolved external symbol. . .

Do not panic, and please, don't make a new forum post somewhere posting hundreds of lines of code. You simply forgot to include all the required additional dependencies in the linker input. Revisit the part where we covered setting up the project for use with SFML and make sure that everything is correct there. Also, remember that you need to include libraries that other libraries are dependent on. For example, the system library always has to be included, the window library has to be included if the graphics module is being used, and so on. Statically linked libraries require their dependencies to be linked as well.

A lot of ground has been covered in this chapter. Some of it may be a little bit difficult to grasp at first if you're just starting, but don't be discouraged just yet. Applying this knowledge practically is the key to understanding it better. It's important that you are competent with everything that has been introduced so far before proceeding onto the next chapter.

If you can truly look throughout this chapter and say with utmost confidence that you're ready to move forward, we would like to congratulate you on taking your first major step towards becoming a successful SFML game developer! Why stop there? In the next chapter, we will be covering a better way to structure code for our first game project. On top of that, time management will be introduced and we'll practically apply everything covered so far by building a major chunk of your first, fully functional game. There's a lot of work ahead of us, so get the lead out! Your software isn't going to write itself.