Cropping and Positioning Images

Let's demonstrate how we can update our SourceRectangle to cause our Render() method to blit only a portion of the image:

To make our rectangle smaller, we reduce the w and h values:

1// ...
2class Image {
3public:
4  Image(const std::string& File)
5  : ImageSurface{SDL_LoadBMP(File.c_str())} {
6    if (!ImageSurface) {
7      // ...
8    } else {
9      SourceRectangle = {
10        0, 0,
11        ImageSurface->w - 50,
12        ImageSurface->h - 100
13      };
14    }
15  }
16// ...
17};

Our output now looks like this:

Let's move our SourceRectangle to the bottom right of our image:

Our SDL_Rect is currently 50 pixels narrower and 100 pixels shorter than our image so, to move it to the bottom right edge, we use those values for the x and y positions:

1// ...
2class Image {
3public:
4  Image(const std::string& File)
5  : ImageSurface{SDL_LoadBMP(File.c_str())} {
6    if (!ImageSurface) {
7      // ...
8    } else {
9      SourceRectangle = {
10        50, 100,
11        ImageSurface->w - 50,
12        ImageSurface->h - 100
13      };
14    }
15  }
16// ...
17};

Our output looks like this:

As a final example, let's crop from all edges. We'll exclude 50 pixels from the left and right edges, and 100 pixels from the top and bottom edges:

Our SourceRectangle looks like this:

1// ...
2class Image {
3public:
4  Image(const std::string& File)
5  : ImageSurface{SDL_LoadBMP(File.c_str())} {
6    if (!ImageSurface) {
7      // ...
8    } else {
9      SourceRectangle = {
10        50, 100,
11        ImageSurface->w - 100,
12        ImageSurface->h - 200
13      };
14    }
15  }
16// ...
17};

Our output now looks like this:

The fourth argument to SDL_BlitSurface() is an SDL_Rect representing where we want the image to be blitted on our destination surface. The x and y properties specify where we want the image positioned within the destination surface. The w and h properties of the destination rectangle are ignored.

To replicate the default behavior of SDL_BlitSurface(), we'd set the x and y values to 0. This places the image at the top left edge of the surface:

1// ...
2class Image {
3public:
4  // ...
5  void Render(SDL_Surface* DestinationSurface) {
6    if (!ImageSurface) return;
7    SDL_BlitSurface(
8      ImageSurface, &SourceRectangle,
9      DestinationSurface, &DestinationRectangle
10    );
11  }
12// ...
13private:
14  SDL_Surface* ImageSurface{nullptr};
15  SDL_Rect SourceRectangle{};
16  SDL_Rect DestinationRectangle{0, 0, 0, 0};
17};

To move the image away from the top-left edge, we'd update the x and y components of the destination rectangle accordingly:

1// ...
2class Image {
3  //...
4private:
5  SDL_Surface* ImageSurface{nullptr};
6  SDL_Rect SourceRectangle{};
7  SDL_Rect DestinationRectangle{50, 100, 0, 0};
8};

As we can see in the previous examples, we sometimes copy fewer pixels than our source rectangle contains. Clipping occurs when SDL needs to adjust what's being rendered. This happens in two main scenarios:

Source clipping: When the source rectangle extends beyond the boundaries of the source image. In this case, SDL3 only renders the part of the rectangle that's within the image.

Destination clipping: When the image (or part of it) would be rendered outside the boundaries of the destination surface. This can happen if:

• The destination position would place the image partially or fully off-screen.
• The image is larger than the destination surface.

In both cases, SDL automatically adjusts the rendering to show only the visible portion of the image.

In SDL2, SDL_BlitSurface() would modify the destination rectangle to tell us the final dimensions of the blitted area. This feature has been removed in SDL3. If we need to detect and react to clipping, we must now do it manually.

We can do this using SDL_GetRectIntersection(). This function calculates the overlapping area between two rectangles. We can check the intersection between our intended blit area and the boundaries of the destination surface.

1// ...
2class Image {
3public:
4  // ...
5  void Render(SDL_Surface* DestinationSurface) {
6    if (!ImageSurface) return;
7
8    SDL_BlitSurface(
9      ImageSurface, &SourceRectangle,
10      DestinationSurface, &DestinationRectangle
11    );
12
13    // Manually check for clipping
14    SDL_Rect IntendedDestRect{
15      DestinationRectangle.x, DestinationRectangle.y,
16      SourceRectangle.w, SourceRectangle.h
17    };
18
19    SDL_Rect DestBounds{
20      0, 0, DestinationSurface->w, DestinationSurface->h
21    };
22
23    SDL_Rect ClippedRect;
24    SDL_GetRectIntersection(
25      &IntendedDestRect, &DestBounds, &ClippedRect
26    );
27
28    if (ClippedRect.w != SourceRectangle.w) {
29      std::cout << "Clipping Horizontally\n";
30    }
31    if (ClippedRect.h != SourceRectangle.h) {
32      std::cout << "Clipping Vertically\n";
33    }
34  }
35  // ...
36};

In our current example, our destination surface (the window) is 600x300, and we are trying to blit a 512x288 image at position (50, 100). The bottom of the image (100 + 288 = 388) extends beyond the bottom of the window (300)

Because of this, we should see vertical clipping both in the visual output of our program, and reported from our code:

1Clipping Vertically
2Clipping Vertically
3Clipping Vertically
4...

Here are the final versions of our files after applying the cropping, positioning, and clipping logic from this lesson.

In this lesson, we've explored several concepts for manipulating images in SDL3:

• Source and Destination Rectangles: We learned how to use SDL_Rect structures to control which parts of an image are rendered (source) and where they appear on screen (destination).
• Cropping: We practiced selecting specific portions of an image by adjusting the source rectangle's dimensions and position.
• Positioning: We discovered how to place images at different locations on the screen by modifying the destination rectangle's x and y coordinates.
• Clipping: We understood how SDL3 handles situations where images don't fit entirely on the screen and learned to detect when clipping occurs manually using SDL_GetRectIntersection().

In the next lesson, we'll see how we can control the size of our rendering, by blitting a larger or smaller copy of our image onto the destination surface.