So far, we've learned how to create a window and fill it with a solid color. While useful, most applications need to draw more specific shapes and images.

One of the most fundamental shapes in 2D graphics is the rectangle. Rectangles are essential for user interfaces (buttons, text boxes), game elements (sprites, collision boxes), and defining areas on the screen (viewports, selection boxes).

SDL provides tools specifically for working with rectangles. We'll learn about the SDL_Rect type for defining position and size, and the SDL_Color type for managing colors independently of screen formats. We'll then combine these to draw rectangles and make them respond to basic mouse interaction.

Starting Point

We'll start with the basic SDL application structure we developed previously. This includes initializing SDL, creating a Window class to manage the SDL_Window and its surface, and running the main event loop.

Creating a Rectangle Class

Let's add a Rectangle class to manage our rectangles. We want our rectangle to render itself to the screen, so we'll add a Render() function that accepts an SDL_Surface pointer. This is the surface that our Rectangle instance will render itself to:

1// Rectangle.h
2#pragma once
3#include <SDL.h>
4
5class Rectangle {
6 public:
7  void Render(SDL_Surface* Surface) const {
8    // ...
9  }
10};

Over in our main function, let's construct a Rectangle and Render() it at the appropriate time.

As we covered in our double buffering lesson, the rendering process starts with the call to GameWindow.Render() - which fills the window surface with a solid color, and it ends with the call to GameWindow.Update() - which triggers the buffer swap.

All of our other objects, such as our Rectangle, should be rendered between these two steps:

1#include <SDL.h>
2#include "Window.h"
3#include "Rectangle.h"
4
5int main(int argc, char** argv) {
6  SDL_Init(SDL_INIT_VIDEO);
7  Window GameWindow;
8  Rectangle Rect;
9
10  SDL_Event E;
11  while (true) {
12    while (SDL_PollEvent(&E)) {
13      if (E.type == SDL_QUIT) {
14        SDL_Quit();
15        return 0;
16      }
17    }
18
19    GameWindow.Render();
20    Rect.Render(GameWindow.GetSurface());
21    GameWindow.Update();
22  }
23
24  return 0;
25}

Rendering the Rectangle

You may remember from our Window class that we can draw a rectangle using SDL_FillRect(), which requires three arguments:

The surface to draw to. This will be the argument provided to our Render() function.
The rectangular area to draw. In our Window class, we're passing a nullptr as this argument, indicating we want the color to fill the entire surface. In this lesson, we'll learn how to provide an argument here, in the form of an SDL_Rect
The color we want to use. Like we did before, we can generate this color using SDL_MapRGB().

1// Rectangle.h
2#pragma once
3#include <SDL.h>
4
5class Rectangle {
6 public:
7  void Render(SDL_Surface* Surface) const {
8    SDL_FillRect(
9      Surface,
10      
11      // We'll provide this later 
12      nullptr, 
13      
14      SDL_MapRGB(Surface->format, 255, 0, 0)
15    );
16  }
17};

The `SDL_Rect` Type

To represent a rectangle, SDL provides the SDL_Rect type. It is a simple struct with four integer members that store the position and dimensions of the rectangle:

The x and y members represent the position of the top-left corner of the rectangle
The w member represents the width of the rectangle
The h member represents the height of the rectangle

Visually, it looks like this:

Diagram showing the components of an SDL_Rect

Remember, SDL's coordinate system uses the "y-down" convention, so increasing the y value corresponds to moving the rectangle down.

Let's add an SDL_Rect to our Rectangle class. We'll also add it as a constructor parameter:

1// Rectangle.h
2#pragma once
3#include <SDL.h>
4
5class Rectangle {
6 public:
7  Rectangle(const SDL_Rect& Rect)
8  : Rect{Rect} {}
9  
10  void Render(SDL_Surface* Surface) {/*...*/}
21
22private:
23  SDL_Rect Rect;
24};

We'll provide the argument to this constructor in our main.cpp:

1#include <SDL.h>
2#include "Window.h"
3#include "Rectangle.h"
4
5int main(int argc, char** argv) {
6  SDL_Init(SDL_INIT_VIDEO);
7  Window GameWindow;
8  Rectangle Rect{SDL_Rect{50, 50, 50, 50}};
9
10  SDL_Event E;
11  while (true) {/*...*/}
24
25  return 0;
26}

To use this rectangle for rendering, we provide a pointer to it as our second argument to SDL_FillRect():

1// Rectangle.h
2#pragma once
3#include <SDL.h>
4
5class Rectangle {
6 public:
7  Rectangle(const SDL_Rect& Rect)
8  : Rect{Rect} {}
9  
10  void Render(SDL_Surface* Surface) const {
11    SDL_FillRect(
12      Surface,
13      &Rect,
14      SDL_MapRGB(Surface->format, 255, 0, 0)
15    );
16  }
17
18private:
19  SDL_Rect Rect;
20};

With these changes, we should now see our red rectangle being rendered to the screen:

Screenshot of our program rendering a red rectangle

The `SDL_Color` Type

In our Render() function, we're currently generating a red color for our rectangle. However, what if we want to store this color as a member variable, such that we change it from other functions in our Rectangle class?

1// Rectangle.h
2#pragma once
3#include <SDL.h>
4
5class Rectangle {
6 public:
7  // ...
8
9  void SetColor(/* ??? */) {
10    // ???
11  }
12  
13  // ...
14};

Previously, we saw how we could store a specific color in a specific pixel format using a 32 bit unsigned integer. This is typically the value returned by a function such as SDL_MapRGB():

1Uint32 Red{SDL_MapRGB(Surface->format, 255, 0, 0)};

However, storing our color as a Uint32 in the correct pixel format may not be easy.

In our simple program, we know we're only ever rendering to one surface - the window surface - so, we could design the Rectangle class on that basis. However, this violates the design principle of encapsulation.

Ideally, our Rectangle should be a self-contained component that does not know or care about what is going on elsewhere in our code. In that context, our Rectangle doesn't know what surface it will be rendering to until Render() is invoked. At that point, the SDL_Surface is available as a parameter, and we can retrieve it's pixel format from the format member variable.

A simple option for storing a color in a way that lets us apply the pixel format later would be to use three integers - one for each of the red, green, and blue channels:

1// Rectangle.h
2#pragma once
3#include <SDL.h>
4
5class Rectangle {
6 public:
7  Rectangle(const SDL_Rect& Rect)
8  : Rect{Rect} {}
9
10  void Render(SDL_Surface* Surface) const {
11    SDL_FillRect(
12      Surface,
13      &Rect,
14      SDL_MapRGB(
15        Surface->format,
16        Red, Green, Blue
17      )
18    );
19  }
20
21  void SetColor(int R, int G, int B) {
22    Red = R;
23    Green = G;
24    Blue = B;
25  }
26
27private:
28  SDL_Rect Rect;
29  int Red, Green, Blue;
30};

This works, but is a little messy, and it makes writting the getter more difficult. We'd prefer to have a type that can represent a color as a single value. To help with this, SDL provides the SDL_Color type, which is useful for storing a color without locking that color down to a specific pixel format.

SDL_Color is a basic struct with 4 members - r, g, b, and a, representing the red, green, blue, and alpha channels respectively. Each variable is an 8-bit unsigned integer, meaning they can store values from 0 to 255:

1SDL_Color Black  {  0,   0,   0, 255};
2SDL_Color Gray   {100, 100, 100, 255};
3SDL_Color White  {255, 255, 255, 255};
4SDL_Color Red    {255,   0,   0, 255};
5SDL_Color Green  {  0, 255,   0, 255};
6SDL_Color Blue   {  0,   0, 255, 255};
7SDL_Color Orange {255, 165,   0, 255};

Let's update our Rectangle to store its color as this type, alongside a getter and setter:

1// Rectangle.h
2#pragma once
3#include <SDL.h>
4
5class Rectangle {
6 public:
7  Rectangle(const SDL_Rect& Rect)
8  : Rect{Rect} {}
9
10  void Render(SDL_Surface* Surface) const {
11    SDL_FillRect(
12      Surface,
13      &Rect,
14      SDL_MapRGB(
15        Surface->format,
16        Color.r, Color.g, Color.b
17      )
18    );
19  }
20
21  void SetColor(const SDL_Color& NewColor) {
22    Color = NewColor;
23  }
24
25  SDL_Color GetColor() const {
26    return Color;
27  }
28
29private:
30  SDL_Rect Rect;
31
32  // Default to red
33  SDL_Color Color{255, 0, 0, 255};
34};

Performance Considerations

A function like Render() is called on every frame of our program, so we should be cautious about performing too much work here. The more work our program needs to do on each frame, the longer it takes to generate that frame. This makes our program less responsive.

Instead, we may want to move the SDL_MapRGB() step out of the Render() function, and pass the required format to the constructor. This allows us to call SDL_MapRGB() a single time, rather than on every frame:

1// Rectangle.h
2#pragma once
3#include <SDL.h>
4
5class Rectangle {
6 public:
7  Rectangle(
8    const SDL_Rect& Rect,
9    const SDL_PixelFormat* Format
10  )
11  : Rect{Rect},
12    Color{SDL_MapRGB(Format, 255, 0, 0)}
13  {}
14
15  void Render(SDL_Surface* Surface) const {
16    SDL_FillRect(
17      Surface,
18      &Rect,
19      SDL_MapRGB(
20        Surface->format,
21        Color.r, Color.g, Color.b
22      )
23      Color
24    );
25  }
26
27private:
28  SDL_Rect Rect;
29  Uint32 Color{0};
30};

This is reasonable, however, we should equally be cautious about making changes like this too early, before we have sufficient information to make such decisions. This is a practice known as premature optimization, and has its own set of problems:

Optimization takes time, and time is a limited resource. Optimizing something now can mean less time to optimize something more important later, so premature optimization can indirectly make performance worse.
Optimization generally adds code complexity, which incurs yet more lost time in the future, and risks causing bugs. This is because it takes longer to add features or fix bugs in more complex code.
Heavily optimizing code typically involves making it less flexible. For example, our optimized Rectangle assumes that it only ever renders to surfaces that have the same pixel format. Our simpler, less optimized implementation had no such restriction.

Unless we're certain something will be a problem, optimization is generally best left until later in the project. This has a few advantages:

We're much more confident about what features the final project will have and how they work, so we're not wasting time optimizing something that might get deleted or changed
We can see the relative performance impact of all of our components in the near-final state of our program. This allows us to make more informed decisions, like which components have the biggest performance impact, so we can prioritize our time on those.

As we get more experienced, we'll develop better intuition about where early optimization is justified, and we'll get better at minimising the negative impact of those optimizations. But otherwise, if we're not sure, we should prioritise approaches that are quick to implement, simple to understand, and easy to change in the future.

Reacting to Mouse Motion Events

Let's give our Rectangle the ability to react to events. To set this up, we'll add a HandleEvent() function to our class:

1// Rectangle.h
2// ...
3
4class Rectangle {
5 public:
6  // ...
7
8  void HandleEvent(SDL_Event& E) {
9    // We'll implement this next
10  }
11
12  // ...
13};

We'll also forward events to this function from our event loop:

1// main.cpp
2#include <SDL.h>
3#include "Window.h"
4#include "Rectangle.h"
5
6int main(int argc, char** argv) {
7  SDL_Init(SDL_INIT_VIDEO);
8  Window GameWindow;
9  Rectangle Rect{SDL_Rect{50, 50, 50, 50}};
10
11  SDL_Event E;
12  while (true) {
13    while (SDL_PollEvent(&E)) {
14      Rect.HandleEvent(E);
15      if (E.type == SDL_QUIT) {
16        SDL_Quit();
17        return 0;
18      }
19    }
20
21    GameWindow.Render();
22    Rect.Render(GameWindow.GetSurface());
23    GameWindow.Update();
24  }
25
26  return 0;
27}

To detect when the user hovers their mouse over the rectangle, we'll apply the techniques we introduced earlier in the chapter. We'll check for SDL_MOUSEMOTION events and, when they occur, we'll update an isPointerHovering boolean to true if the cursor was moved over our rectangle:

1// Rectangle.h
2// ...
3
4class Rectangle {
5 public:
6  // ...
7  void HandleEvent(SDL_Event& E) {
8    if (E.type == SDL_MOUSEMOTION) {
9      isPointerHovering = isWithinRect(
10        E.motion.x, E.motion.y
11      );
12    }
13  }
14  // ...
15
16private:
17  // ...
18
19  bool isPointerHovering{false};
20  bool isWithinRect(int x, int y) {
21    // We'll implement this next
22    return false;
23  }
24};

Detecting if a Point is within an `SDL_Rect`

Our isWithinRect() function needs to return true if the x and y coordinates are within the bounds of our Rect variable. There are a few ways of determining this this. One approach is to check if the point is not outside the bounds in all 4 directions:

Diagram showing the logic of calculating if a point is inside a rectangle

If the point is not in any of the areas we marked in red, we can deduce that it must be within the rectangle. In code, we can implement the check like this:

1// Rectangle.h
2// ...
3
4class Rectangle {
5 // ...
6
7private:
8  // ...
9  bool isWithinRect(int x, int y) {
10    // Too far left
11    if (x < Rect.x) return false;
12    // Too far right
13    if (x > Rect.x + Rect.w) return false;
14    // Too far up
15    if (y < Rect.y) return false;
16    // Too far down
17    if (y > Rect.y + Rect.h) return false;
18
19    // If we got this far, that means the
20    // point is within the rectangle
21    return true;
22  }
23};

Changing Color on Hover

Now that our Rectangle is keeping track of whether the user's cursor is hovering over it, other functions in our class can react to it. For example, let's have our rectangle change color when hovered. We'll add a new member variable, getter, and setter:

1// Rectangle.h
2// ...
3
4class Rectangle {
5 public:
6  // ...
7
8  void SetHoverColor(const SDL_Color& NewColor) {
9    HoverColor = NewColor;
10  }
11
12  SDL_Color GetHoverColor() const {
13    return HoverColor;
14  }
15
16private:
17  // ...
18  SDL_Color HoverColor{0, 0, 255, 255};
19};

Let's update our Render() function to select a color based on the isPointerHovering state. This is an ideal place to use structured binding:

1// Rectangle.h
2// ...
3
4class Rectangle {
5public:
6  // ...
7
8  void Render(SDL_Surface* Surface) const {
9    auto [r, g, b, a]{
10      isPointerHovering ? HoverColor : Color
11    };
12    
13    SDL_FillRect(
14      Surface, &Rect,
15      SDL_MapRGB(Surface->format, r, g, b)
16    );
17  }
18  // ...
19};

Note that, to use structured binding, we need to use all the variables of the SDL_Color type, even though we don't need the a (alpha) channel in this scenario.

Structured Binding

This lesson introduces Structured Binding, a handy tool for unpacking simple data structures

View Related Lesson

Now, when we hover our rectangle, it should change color from red to blue:

Screenshot showing the program rendering a blue rectangle

Rendering Coordinates vs Mouse Coordinates

Note that, in the previous example, we're comparing the x and y coordinates from the mouse motion event to the x and y coordinates of SDL_Rect controlling where our rectangle is rendered.

The x and y coordinates of the event represent the distance from the top left corner of the window, whilst the x and y coordinates of the SDL_Rect represent the distance from the top-left corner of the surface we're rendering on.

Our logic is assuming that these values are equivalent. In our simple program, they are. That is because the surface we're rendering to is the window surface. In more complicated programs where this is not always the case, we would need more advanced logic that accounts for the fact that these positions may be in different coordinate spaces.

We cover coordinate spaces and mapping between them in more detail later in the course.

We're also assuming our program only has a single window, so we're not checking which window the event came from.

The `SDL_Point` Type

SDL includes a simple SDL_Point type that stores an x and y integer:

1SDL_Point SomePoint{100, 200};

SDL also includes a few functions that work with SDL_Point objects. This includes SDL_PointInRect(), which can replicate our isWithinRect() method. To use SDL_PointInRect(), we pass a pointer to an SDL_Point and a pointer to an SDL_Rect:

1// Rectangle.h
2#pragma once
3#include <SDL.h>
4
5class Rectangle {
6 public:
7  // ...
8
9  void HandleEvent(SDL_Event& E) {
10    if (E.type == SDL_MOUSEMOTION) {
11      // Before
12      isPointerHovering = isWithinRect(
13        E.motion.x, E.motion.y
14      );
15      
16      // After
17      SDL_Point MousePosition{
18        E.motion.x, E.motion.y};
19      isPointerHovering = SDL_PointInRect(
20        &MousePosition, &Rect
21      );
22    }
23  }
24  // ...
25};

However, SDL_Point is rarely used, even within the SDL API itself. As we've seen, SDL events represent positions as individual x and y values, rather than as SDL_Points.

We'll also stick to representing points as individual x and y coordinates in our own examples for now. Later in the course, we'll create a more powerful Vec2 type that uses concepts that are more common in the industry.

Reacting to Window Events

By default, SDL stops sending us mouse motion events once the pointer leaves our window.

If the rectangle is at the edge of the window, or the mouse is moving quickly, this means we may not be notified that the cursor has left our rectangle through leaving the window entirely.

To address this, we can additionally keep track of SDL_WINDOWEVENT_LEAVE events, using the techniques we covered in the previous lesson:

1// Rectangle.h
2// ...
3
4class Rectangle {
5 public:
6  // ...
7  void HandleEvent(SDL_Event& E) {
8    if (E.type == SDL_MOUSEMOTION) {
9      isPointerHovering = isWithinRect(
10        E.motion.x, E.motion.y
11      );
12    } else if (
13      E.type == SDL_WINDOWEVENT &&
14      E.window.event == SDL_WINDOWEVENT_LEAVE
15    ) {
16      isPointerHovering = false;
17    }
18  }
19  // ...
20
21};

Reacting to Mouse Click Events

Let's also allow our Rectangle objects to react to mouse click events - that is, events with a type of SDL_MOUSEBUTTONDOWN:

1// Rectangle.h
2// ...
3
4class Rectangle {
5 public:
6  // ...
7
8  void HandleEvent(SDL_Event& E) {
9    if (E.type == SDL_MOUSEMOTION) {
10      isPointerHovering = isWithinRect(
11        E.motion.x, E.motion.y
12      );
13    } else if (
14      E.type == SDL_WINDOWEVENT &&
15      E.window.event == SDL_WINDOWEVENT_LEAVE
16    ) {
17      isPointerHovering = false;
18    } else if (E.type == SDL_MOUSEBUTTONDOWN) {
19      if (E.button.button == SDL_BUTTON_LEFT) {
20        std::cout << "A left-click happened "
21          "somewhere in the window\n";
22      }
23    }
24  }
25  // ...
26};

The click events include x and y members, informing us of where the cursor was when the user clicked on our window. We can use this to determine whether they specifically clicked on the Rectangle instance:

1// Rectangle.h
2// ...
3
4class Rectangle {
5 public:
6  // ...
7
8  void HandleEvent(SDL_Event& E) {
9    if (E.type == SDL_MOUSEMOTION) {
10      isPointerHovering = isWithinRect(
11        E.motion.x, E.motion.y
12      );
13    } else if (
14      E.type == SDL_WINDOWEVENT &&
15      E.window.event == SDL_WINDOWEVENT_LEAVE
16    ) {
17      isPointerHovering = false;
18    } else if (E.type == SDL_MOUSEBUTTONDOWN) {
19      if (isWithinRect(E.button.x, E.button.y)
20          && E.button.button == SDL_BUTTON_LEFT
21      ) {
22        std::cout << "A left-click happened "
23          "on me!\n";
24      }
25    }
26  }
27  // ...
28};

Alternatively, we can use the isHovering boolean we added in the previous section:

1// Rectangle.h
2// ...
3
4class Rectangle {
5 public:
6  // ...
7
8  void HandleEvent(SDL_Event& E) {
9    if (E.type == SDL_MOUSEMOTION) {
10      isPointerHovering = isWithinRect(
11        E.motion.x, E.motion.y
12      );
13    } else if (
14      E.type == SDL_WINDOWEVENT &&
15      E.window.event == SDL_WINDOWEVENT_LEAVE
16    ) {
17      isPointerHovering = false;
18    } else if (E.type == SDL_MOUSEBUTTONDOWN) {
19      if (isPointerHovering && 
20          E.button.button == SDL_BUTTON_LEFT
21      ) {
22        std::cout << "A left-click happened "
23          "on me!\n";
24      }
25    }
26  }
27  // ...
28};

Complete Code

Our program now includes a dedicated Rectangle.h file defining our Rectangle class. The main.cpp file creates an instance of this class and integrates its rendering and event handling into the main loop. This setup provides a good starting point for adding more complex features through the rest of this chapter.

Summary

In this lesson, we learned how to define, render, and interact with rectangles in SDL2. We created a Rectangle class encapsulating an SDL_Rect for geometry and an SDL_Color for appearance, allowing us to draw shapes and respond to mouse input.

Key Takeaways:

SDL_Rect defines a rectangle using x, y (top-left corner), w (width), and h (height).
SDL_Color stores RGBA color values (0-255) independently of pixel formats.
SDL_FillRect() draws a filled rectangle onto an SDL_Surface.
SDL_MapRGB() converts RGBA values into a surface-specific color format.
We can check if a point is inside an SDL_Rect by comparing its coordinates against the rectangle's boundaries.
Mouse motion (SDL_MOUSEMOTION) and click (SDL_MOUSEBUTTONDOWN) events provide cursor coordinates.
Window events (SDL_WINDOWEVENT_LEAVE) help track when the cursor leaves the window.

Rectangles and `SDL_Rect`

Starting Point

Creating a Rectangle Class

Rendering the Rectangle

The `SDL_Rect` Type

The `SDL_Color` Type

Reacting to Mouse Motion Events

Detecting if a Point is within an `SDL_Rect`

Changing Color on Hover

Structured Binding

Reacting to Window Events

Reacting to Mouse Click Events

Complete Code

Summary

Structuring SDL Programs

Game Development with SDL2

Questions & Answers

Rectangles and SDL_Rect

Starting Point

Creating a Rectangle Class

Rendering the Rectangle

The SDL_Rect Type

The SDL_Color Type

Reacting to Mouse Motion Events

Detecting if a Point is within an SDL_Rect

Changing Color on Hover

Structured Binding

Reacting to Window Events

Reacting to Mouse Click Events

Complete Code

Summary

Structuring SDL Programs

Questions & Answers

Rectangles and `SDL_Rect`

The `SDL_Rect` Type

The `SDL_Color` Type

Detecting if a Point is within an `SDL_Rect`