Now that we have images loaded via our AssetManager, it's time to display them correctly in our game world. This lesson covers positioning entities, setting up a world coordinate system, transforming coordinates, and using SDL's blitting function to render images. Key steps include:

Defining a scene's world space dimensions.
Implementing ToScreenSpace() coordinate conversion.
Rendering ImageComponent surfaces using SDL_BlitSurface().
Adding relative offsets to ImageComponent for fine-tuning position.
Creating visual debug helpers for entity locations.

Starting Point

In the previous lesson, we refactored our ImageComponent to use an AssetManager and std::shared_ptr, simplifying its code and optimizing memory usage. Here's the state of our ImageComponent as we begin this lesson:

Positioning Entities

Currently, all of our entities are positioned at $(0, 0)$, the default value of our TransformComponent's Position vector.

We need a way to change this. Let's add a setter for this:

1// TransformComponent.h
2// ...
3
4class TransformComponent : public Component {
5public:
6  // ...
7  void SetPosition(const Vec2& NewPosition) { 
8    Position = NewPosition; 
9  } 
10  // ...
11};

Now, back in Scene.h, let's use this to position two entities in our scene. We'll also give them each an ImageComponent, which we'll render later in the lesson:

1// Scene.h
2// ...
3
4class Scene {
5 public:
6  Scene() {
7    EntityPtr& Player{Entities.emplace_back(
8      std::make_unique<Entity>(*this))};
9    Player->AddTransformComponent()
10          ->SetPosition({1, 2});  
11    Player->AddImageComponent("player.png");
12
13    EntityPtr& Enemy{Entities.emplace_back(
14      std::make_unique<Entity>(*this))};
15    Enemy->AddTransformComponent()
16         ->SetPosition({8, 5});  
17    Enemy->AddImageComponent("dragon.png");
18  }
19  // ...
20};

World Space

Within our scene, we want the freedom to position objects independendly of screen coordinates. Just like we did in our earlier chapter on spaces and transformations, let's define a world space for our scene.

We'll set it up in exactly the same way we did in the earlier. We will use the y-up, x-left convention and, in this case, we'll set it to be 14 meters wide and 6 meters tall:

Note that there's no real significance to his 14 x 6 decision. We could have choosen anything. Let's add variables to our Scene to store whichever values we choose:

1// Scene.h
2// ...
3
4class Scene {
5  // ...
6private:
7  // ...
8  float WorldSpaceWidth{14}; // meters
9  float WorldSpaceHeight{6}; // meters
10};

To render images to the screen, we need a way to convert their world space coordinates to screen space coordinates. Our screen space coordinates will use SDL's standard Y-Down convention. Our window's size is 700x300 in our screenshots, but the code we write will work with any window size.

To help us get the window size, our Scene will keep track of the viewport it is being rendered to. We'll use the same technique as before, updating an SDL_Rect using SDL_GetClipRect() before rendering anything in the scene:

1// Scene.h
2// ...
3
4class Scene {
5public:
6  // ...
7
8  void Render(SDL_Surface* Surface) {
9    SDL_GetClipRect(Surface, &Viewport);
10    for (EntityPtr& Entity : Entities) {
11      Entity->Render(Surface);
12    }
13  }
14
15private:
16  // ...
17  SDL_Rect Viewport;
18};

To keep things simple, we won't bother with a dynamic camera for now. We'll just map everything in our $(14 \times 6)$ world space to the corresponding screen space. This is the same transformation function we walked through creating earlier in the course:

1#pragma once
2#include <SDL.h>
3#include <vector>
4#include "GameObject.h"
5
6class Scene {
7public:
8  // ...
9
10  Vec2 ToScreenSpace(const Vec2& Pos) const {
11    auto [vx, vy, vw, vh]{Viewport};
12    float HorizontalScaling{vw / WorldSpaceWidth};
13    float VerticalScaling{vh / WorldSpaceHeight};
14
15    return {
16      vx + Pos.x * HorizontalScaling,
17      vy + (WorldSpaceHeight - Pos.y) * VerticalScaling
18    };
19  }
20
21  // ...
22};

Our ToSceenSpace() function in our Scene is public, so components can now access it through the GetScene() function defined on the Component base class:

1// Conceptual Example
2class SomeComponent : public Component {
3  void SomeFunction() {
4    GetScene().ToScreenSpace({1, 2});
5  }
6};

API Improvements

We expect to be accessing this ToScreenSpace() function a lot within our components, so let's add a helper function to the Component base class that makes accessing this function a little friendlier:

1// Component.h
2// ...
3class Vec2; 
4
5class Component {
6 public:
7  // ...
8  Vec2 ToScreenSpace(const Vec2& Pos) const;
9  // ...
10};

1// Component.cpp
2// ...
3
4Vec2 Component::ToScreenSpace(const Vec2& Pos) const {
5  return GetScene().ToScreenSpace(Pos);
6}

Any of our components can now use a simpler API to transform a Vec2 to screen space:

1// Conceptual Example
2class SomeComponent : public Component {
3  void SomeFunction() {
4    // Before
5    GetScene().ToScreenSpace({1, 2}); 
6
7    // After
8    ToScreenSpace({1, 2});
9  }
10};

Our components are likely to also frequently get and set the position of their owning Entity, we can add further helpers to make that easier:

1// Component.h
2// ...
3
4class Component {
5 public:
6  // ...
7  Vec2 GetOwnerPosition() const;
8  void SetOwnerPosition(const Vec2& Pos) const;
9  Vec2 GetOwnerScreenSpacePosition() const;
10  // ...
11};

1// Component.cpp
2// ...
3
4Vec2 Component::GetOwnerPosition() const {
5  TransformComponent* Transform{
6    GetOwner()->GetTransformComponent()};
7  if (!Transform) {
8    std::cerr << "Error: attempted to get position"
9      " of an entity with no transform component\n";
10    return {0, 0};
11  }
12  return Transform->GetPosition();
13}
14
15void Component::SetOwnerPosition(const Vec2& Pos) const {
16  TransformComponent* Transform{
17    GetOwner()->GetTransformComponent()};
18  if (!Transform) {
19    std::cerr << "Error: attempted to set position"
20      " of an entity with no transform component\n";
21  } else {
22    Transform->SetPosition(Pos);
23  }
24}
25
26Vec2 Component::GetOwnerScreenSpacePosition() const {
27  return ToScreenSpace(GetOwnerPosition());
28}

This further simplifies our API:

1// Conceptual Example
2class SomeComponent : public Component {
3  void SomeFunction() {
4    // Before
5    GetOwner()->GetTransformComponent()
6      ->GetPosition();
7    // After
8    GetOwnerPosition();
9
10    // Before
11    GetOwner()->GetTransformComponent()
12      ->SetPosition({1, 2});
13    // After
14    SetOwnerPosition({1, 2}); 
15
16    // Before
17    ToScreenSpace(GetOwner()
18      ->GetTransformComponent()->GetPosition());
19    // After
20    GetOwnerScreenSpacePosition(); 
21  }
22};

Rendering Debug Helpers

It's often useful to "see" the invisible data in our game world, like the exact point our TransformComponent represents. We can achieve this using debug helpers: temporary graphics rendered only for developers. Let's create a way for components to draw their own debug information.

To set this up, we'll add a virtual function to our Component base class, including an SDL_Surface* argument specifying where the helpers should be drawn:

1// Component.h
2// ...
3
4class Component {
5 public:
6  // ...
7  virtual void DrawDebugHelpers(
8    SDL_Surface* Surface) {}
9  // ...
10};

If our build has enabled debug helpers through a preprocessor flag, our Entity will call this new DrawDebugHelpers() on all of it's components. We typically draw debug helpers after everything else has rendered, as this ensures the helpers are drawn on top of the objects in our scene.

1// Entity.h
2// ...
3
4#define DRAW_DEBUG_HELPERS 
5
6class Entity {
7public:
8  // ...
9  virtual void Render(SDL_Surface* Surface) {
10    for (ComponentPtr& C : Components) {
11      C->Render(Surface);
12    }
13    #ifdef DRAW_DEBUG_HELPERS
14    for (ComponentPtr& C : Components) {
15      C->DrawDebugHelpers(Surface);
16    }
17    #endif
18  }
19  // ...
20};

Rendering Entity Positions

To render world space positions to the screen, we need to perform two conversions:

Convert them from world space to screen space
Convert them from floating point numbers to integers

We already have the ToScreenSpace() function in our Scene, so we just need to tackle rounding them to integers.

Let's add a function to convert SDL_FRect objects to SDL_Rect by rounding its four values. We'll define this function in a new Utilities header file and namespace so we can easily include it wherever it is needed:

1// Utilities.h
2#pragma once
3#include <SDL.h>
4
5namespace Utilities{
6inline SDL_Rect Round(const SDL_FRect& R) {
7  return {
8    static_cast<int>(SDL_round(R.x)),
9    static_cast<int>(SDL_round(R.y)),
10    static_cast<int>(SDL_round(R.w)),
11    static_cast<int>(SDL_round(R.h)),
12  };
13}
14}

Note that the function in this header file includes the inline keyword. This will prevent future issues when we #include it in multiple files.

Let's now combine the Component::ToScreenSpace() and Utilities::Round() functions to overload the DrawDebugHelpers() function in our TransformComponent. We'll have it draw a 20 x 20 pixel square, centered at its screen space position:

1// TransformComponent.h
2// ...
3#include <SDL.h> // for SDL_Surface
4#include "Utilities.h" // for Round
5
6class TransformComponent : public Component {
7 public:
8  // ...
9  void DrawDebugHelpers(SDL_Surface* S) override {
10    auto [x, y]{ToScreenSpace(Position)};
11    SDL_Rect Square{Utilities::Round({
12      x - 10, y - 10, 20, 20
13    })};
14    SDL_FillRect(S, &Square, SDL_MapRGB(
15      S->format, 255, 0, 0));
16  }
17  // ...
18};

We should now see the the position of the player and enemy entities we added to our Scene:

Screenshot showing our Transform Component's debug helpers rendering

Rendering Images

In the previous section, we successfully loaded our images into SDL_Surfaces within our AssetManager, and our ImageComponent instances have a shared pointer to those surfaces. Now, let's get use them to render our images to the screen!

The SDL function we need is SDL_BlitSurface().

Reminder: Blitting and `SDL_BlitSurface()`

Think of "blitting" as efficiently copying a rectangular block of pixels from one place (our loaded image surface) to another (our window's surface).

To tell SDL_BlitSurface() what and where to draw, we need to provide 4 arguments:

The source surface: A pointer to the SDL_Surface containing the image we want to copy
The source rectangle: A pointer to an SDL_Rect representing the rectangular area of the source surface that we want to copy. This can be a nullptr if we want to copy the entire surface
The destination surface: A pointer to the SDL_Surface where we want the content blitted to
The destination rectangle: A pointer to an SDL_Rect controlling where on the destination surface we will blit to. The x and y specify the top-left corner. The w and h do not influence the blit but, after calling SDL_BlitSurface(), they will be updated with the width and height of the area that was blitted. This might be useful information for follow-up operations.

Note that the w and h values that SDL_BlitSurface() writes to our destination rectangle will not necessarily the same as the values in our source rectangle (or the width and height of our image, if we didn't supply a source rectangle)

The values may be smaller, and that is because if the source data didn't entirely fit within the destination surface at the x, y position provided, then our image will have been cropped. The w and h in the destination rectangle contains the values after any cropping has occured.

SDL_BlitSurface() returns a boolean indicating whether the blit was successful. If it was unsuccessful, we can call SDL_GetError() for more information.

We covered blitting in a dedicated lesson earlier in the course:

Loading and Displaying Images

Learn how to load, display, and optimize image rendering in your applications

View Related Lesson

Let's delete everything in ImageComponent::Render() and start by building the destination rectangle. We can get these coordinates we need for our blitting operation using our new GetEntityScreenSpacePosition() function in the Component base class and the Round function in our Utilities namespace.

Only the x and y values of our destination rectangle are relevant for SDL_BlitSurface(), so we'll just set w and h to 0:

1// ImageComponent.cpp
2// ...
3#include "Utilities.h"
4
5// ...
6
7void ImageComponent::Render(
8  SDL_Surface* Surface
9) {
10  if (!ImageSurface) return;
11  
12  auto [x, y]{GetOwnerScreenSpacePosition()};
13  SDL_Rect Destination{
14    Utilities::Round({x, y, 0, 0})
15  };
16}
17
18// ...

We now have everything we need for our call to SDL_BlitSurface(). Our arguments are:

A pointer to the SDL_Surface containing our image data. We're storing this as the ImageSurface member variable. ImageSurface is a shared pointer whilst SDL_BlitSurface() requires a raw pointer. We can get this using the shared pointer's get() function.
The source rectangle specifying where we want to copy data from we want to copy data from. We want to blit the entire image, so we pass nullptr
The target surface. This is the Surface argument provided to Render(), which is the window surface in our program.
The destination rectangle, which we created above.

Let's put all of this together. We'll also check the return value of SDL_BlitSurface() for errors, just in case:

1// ImageComponent.cpp
2// ...
3
4void ImageComponent::Render(
5  SDL_Surface* Surface
6) {
7  if (!ImageSurface) return;
8  auto [x, y]{GetOwnerScreenSpacePosition()};
9  SDL_Rect Destination{Utilities::Round({x, y, 0, 0})};
10  
11  if (SDL_BlitSurface(
12    ImageSurface.get(),
13    nullptr,
14    Surface,
15    &Destination
16  ) < 0) {
17    std::cerr << "Error: Blit failed: "
18      << SDL_GetError() << '\n';
19  }
20}
21
22// ...

Let's compile and run our project, and confirm that everything is working:

Screenshot showing our image components rendering

Positioning Images

Drawing our images at the entity's exact top-left position works, but what if we want the entity's TransformComponent position to represent its center instead? Or maybe its feet for ground alignment? Maybe our Entity has multiple ImageComponents, which we need to position relative to each other.

To solve either problem, we need a way to draw the image with an offset relative to the entity's main position.

Let's add a Vec2 Offset member to ImageComponent. We'll also need a SetOffset() method so other code can control this offset:

1// ImageComponent.h
2// ...
3#include "Vec2.h" 
4
5class ImageComponent : public Component {
6 public:
7  // ...
8
9  void SetOffset(const Vec2& NewOffset) { 
10    Offset = NewOffset; 
11  } 
12
13private:
14  // ...
15  Vec2 Offset{0, 0}; // Default to no offset 
16};

Next, we need to use this offset when rendering. We'll modify the Render() method in ImageComponent.cpp.

In this case, we're assuming our offset is defined in screen space, which tends to be more useful for image data, but we could also add a WorldSpaceOffset variable if we wanted to support both.

To offset our image in world space, we add our offset to the screen space position of our entity:

1// ImageComponent.cpp
2// ...
3
4void ImageComponent::Render(
5  SDL_Surface* Surface
6) {
7  if (!ImageSurface) return;
8
9  auto [x, y]{
10    // Before:
11    GetOwnerScreenSpacePosition() 
12    // After:
13    GetOwnerScreenSpacePosition() + Offset 
14  };
15  
28}
29
30// ...

Drawing Debug Helpers

Let's add some debug helpers to our ImageComponent class, too. We'll draw a small blue rectangle at our rendering position, factoring in the Offset value.

We'll override the DrawDebugHelpers() function in our header file:

1// ImageComponent.h
2// ...
3
4class ImageComponent : public Component {
5 public:
6  // ...
7  void DrawDebugHelpers(SDL_Surface*) override; 
8  // ...
9};

And implement it in our source file:

1// ImageComponent.cpp
2// ...
3
4void ImageComponent::DrawDebugHelpers(
5  SDL_Surface* Surface
6){
7  if (!ImageSurface) return;
8
9  auto [x, y]{GetOwnerScreenSpacePosition() + Offset};
10
11  SDL_Rect DebugRect{Utilities::Round({
12      x - 5, y - 5, 10, 10 })};
13
14  SDL_FillRect(Surface, &DebugRect, SDL_MapRGB(
15    Surface->format, 0, 0, 255));
16}
17
18// ...

With our offset set to {0, 0}, we should see our TransformComponent and ImageComponent render their debug output in the same position:

Screenshot showing our image components debug helpers rendering

Getting Image Dimensions

Calculating offsets often requires knowing the dimensions of the image being drawn (e.g., to find its center). Let's add helper methods GetSurfaceWidth() and GetSurfaceHeight() to ImageComponent so it can provide this information.

Let's add the declarations in ImageComponent.h:

1// ImageComponent.h
2// ...
3
4class ImageComponent : public Component {
5 public:
6  // ...
7
8  int GetSurfaceWidth() const;
9  int GetSurfaceHeight() const;
10
11  // ...
12};

And implement them in ImageComponent.cpp. They'll log an error message and safely return 0 if ImageSurface is nullptr.

1// ImageComponent.cpp
2// ...
3
4int ImageComponent::GetSurfaceWidth() const {
5  if (!ImageSurface) {
6    std::cerr << "Warning: Attempted to get "
7      "width from null ImageSurface.\n";
8    return 0;
9  }
10  return ImageSurface->w;
11}
12
13int ImageComponent::GetSurfaceHeight() const {
14  if (!ImageSurface) {
15    std::cerr << "Warning: Attempted to get "
16      "height from null ImageSurface.\n";
17    return 0;
18  }
19  return ImageSurface->h;
20}
21
22// ...

Fantastic! We now have all the pieces to easily control our image positions. Let's go back to Scene.h one more time.

We'll use the functions we added to update the Offset of the ImageComponent used by our player:

1// Scene.h
2// ...
3
4class Scene {
5 public:
6  Scene() {
7    EntityPtr& Player{Entities.emplace_back(
8      std::make_unique<Entity>(*this))};
9
10    Player->AddTransformComponent()
11          ->SetPosition({2, 1});
12    
13    ImageComponent* PlayerImage{
14      Player->AddImageComponent("player.png")
15    };
16
17    PlayerImage->SetOffset({
18      PlayerImage->GetSurfaceWidth() * -0.5f,
19      PlayerImage->GetSurfaceHeight() * -1.0f
20    });
21
22    EntityPtr& Enemy{Entities.emplace_back(
23      std::make_unique<Entity>(*this))};
24
25    Enemy->AddTransformComponent()
26         ->SetPosition({8, 5});
27    Enemy->AddImageComponent("dragon.png");
28  }
29
30  // ...
31};

This will make the player image appear centered on it's TransformComponent's position. The dragon will still be drawn from its top-left:

Screenshot showing our image components rendering with an offset

Reminder: Entity Subtypes

For simplicity in these lessons, we're configuring our entities within our Scene constructor. However we can (and, in larger projects, should) introduce new classes for the various types of entities that we have.

This gives us a natural place to configure those entities, such as the components they should have by default, and the configuration of those components:

1// Character.h
2#pragma once
3#include "Entity.h"
4#include "ImageComponent.h"
5#include "TransformComponent.h"
6
7class Scene;
8class Character : public Entity {
9 public:
10  Character(Scene& Scene, Vec2 InitialPosition)
11    : Entity{Scene}
12  {
13    AddTransformComponent()
14      ->SetPosition(InitialPosition);
15      
16    ImageComponent* Image{
17      AddImageComponent("player.png")};
18      
19    Image->SetOffset({
20      Image->GetSurfaceWidth() * -0.5f,
21      Image->GetSurfaceHeight() * -1.0f
22    });
23  }
24};

This let's us remove low-level noise from the much more important Scene class:

1// Scene.h
2// ...
3#include "Character.h" 
4// ...
5
6class Scene {
7 public:
8  Scene() {
9    Entities.emplace_back(
10      std::make_unique<Character>(
11        *this, Vec2{2, 1}));
12      
13    EntityPtr& Player{Entities.emplace_back(
14      std::make_unique<Entity>(*this))};
15
16    Player->AddTransformComponent()
17          ->SetPosition({2, 1});
18    
19    ImageComponent* PlayerImage{
20      Player->AddImageComponent("player.png")
21    };
22
23    PlayerImage->SetOffset({
24      PlayerImage->GetSurfaceWidth() * -0.5f,
25      PlayerImage->GetSurfaceHeight() * -1.0f
26    });
27
28    // ...
29  }
30
31  // ...
32};

Complete Code

Below, we've provided complete versions of the files we changed in this lesson. We'll continue working on these in the next lesson

Summary

We bridged the gap between having loaded images and displaying them in our game world. This involved setting up world dimensions in the Scene, creating a conversion function from world to screen space, and using SDL_BlitSurface() in ImageComponent to draw the image pixels.

We further refined this by adding an offset property to ImageComponent for better control over placement and implemented debug visuals for transforms and image render points.

Key Takeaways:

Game scenes typically operate in a world coordinate system (e.g., meters).
Rendering requires converting world coordinates to the window's screen coordinates, considering viewport position and scaling.
SDL_BlitSurface() copies pixel data; the destination SDL_Rect's x and y define the top-left corner on the target surface.
Components can have offsets to adjust their visual representation relative to the owner entity's transform.
Helper functions in base classes like Component::ToScreenSpace() and GetOwnerPosition() simplify common tasks for derived components.
Debug helpers using DrawDebugHelpers() are invaluable for verifying positioning and transformations.

Positioning and Rendering Entities