Customising Mouse Cursors

When we’re working on a mouse-based game, creating an engaging user interface typically requires us to change the visual appearance of the cursor.

For example, we might customize the cursor to fit the theme of our game. We may also want to apply further modifications to the cursor based on what the user is pointing at, like changing the cursor to a sword if the pointer is hovering over an enemy. This helps players quickly understand what effect clicking will have.

This lesson will guide you through the various cursor customization options available in SDL2. We’ll cover:

• Simple visibility toggles to show and hide the cursor
• Switching between a range of default cursor options provided by the platform
• Implementing custom cursors from image files
• Completely replacing the cursor implementation to take full control on how mouse interaction is implemented

Showing and Hiding the Cursor

Similar to trapping the cursor, we also often want to hide it. That can be done with SDL_ShowCursor(). We pass SDL_ENABLE to show the cursor, or SDL_DISABLE to hide it:

1// Show the Cursor
2SDL_ShowCursor(SDL_ENABLE);
3
4// Hide the Cursor
5SDL_ShowCursor(SDL_DISABLE);

Querying Cursor Visibility

We can also use SDL_ShowCursor() to determine the current visibility of the cursor, without changing it. To do this, we pass SDL_QUERY as the argument, and examine the return value:

1if (SDL_ShowCursor(SDL_QUERY) == SDL_ENABLE) {
2  std::cout << "Cursor is visible";
3} else {
4  std::cout << "Cursor is hidden";
5}

1Cursor is visible

Error Handling

In addition to returning the new visibility of the cursor (SDL_ENABLE or SDL_DISABLE), the SDL_GetError() function can alternatively return a negative value. This happens when something goes wrong, and we can call SDL_GetError() to get an explanation of the error:

1if (SDL_ShowCursor(SDL_DISABLE) < 0) {
2  std::cout << "Error hiding cursor: "
3    << SDL_GetError();
4}

Premade System Cursors

We pass an SDL_SystemCursor enum value describing which cursor we’d like to create. For example, we can create the default arrow cursor by passing SDL_SYSTEM_CURSOR_ARROW:

1SDL_CreateSystemCursor(SDL_SYSTEM_CURSOR_ARROW);

The value returned by SDL_CreateSystemCursor() is an SDL_Cursor pointer (an SDL_Cursor*):

1SDL_Cursor* Cursor{
2  SDL_CreateSystemCursor(SDL_SYSTEM_CURSOR_ARROW)
3};

We should treat these SDL_Cursor objects as opaque - that is, they are not designed for us to read or modify their properties. However, we still need these SDL_Cursor pointers for use with other SDL functions that we’ll cover later.

SDL_SystemCursor Values

The SDL_SystemCursor enum includes a set of values that are commonly cursors. Its possible values are as follows:

• SDL_SYSTEM_CURSOR_ARROW: The default cursor, usually designed to look like an arrow
• SDL_SYSTEM_CURSOR_HAND: An alternative cursor designed to look like a hand
• SDL_SYSTEM_CURSOR_CROSSHAIR: An alternative cursor designed to look like a crosshair
• SDL_SYSTEM_CURSOR_IBEAM: The I-beam cursor, typically used for text editing
• SDL_SYSTEM_CURSOR_WAIT: A cursor designed to indicate something is loading
• SDL_SYSTEM_CURSOR_WAITARROW: An alternative design to the loading cursor
• SDL_SYSTEM_CURSOR_NO: Used to indicate blocked or disabled actions

Most systems have cursors designed to indicate resizing actions, such as when you move your pointer next to the edge of a resizable window. We can load these system cursors using the following enum values:

• SDL_SYSTEM_CURSOR_SIZENWSE: Double arrow pointing northwest and southeast,
• SDL_SYSTEM_CURSOR_SIZENESW: Double arrow pointing northeast and southwest
• SDL_SYSTEM_CURSOR_SIZEWE: Double arrow pointing west and east
• SDL_SYSTEM_CURSOR_SIZENS: Double arrow pointing north and south
• SDL_SYSTEM_CURSOR_SIZEALL: Four pointed arrow pointing north, south, east, and west

Error Handling

It is possible for the SDL_Cursor pointer returned by SDL_CreateSystemCursor() to be a nullptr. This represents an error, and we can call SDL_GetError() for an explanation:

1SDL_Cursor* Cursor{
2  SDL_CreateSystemCursor(SDL_SYSTEM_CURSOR_ARROW)
3};
4
5if (!Cursor) {
6  std::cout << "Failed to create cursor: "
7    << SDL_GetError();
8}

Setting Cursors

Once we’ve created a cursor and have access to it through an SDL_Cursor pointer, we can instruct SDL to use that cursor for our mouse. We do this by passing the pointer to SDL_SetCursor():

1SDL_Cursor* Cursor{
2  SDL_CreateSystemCursor(SDL_SYSTEM_CURSOR_ARROW)
3};
4
5SDL_SetCursor(Cursor);

Freeing Cursors

When we create a cursor using a function like SDL_CreateSystemCursor(), SDL allocates the memory required for that cursor and manages it internally.

However, when we no longer need that cursor, we should communicate that to SDL so it can free the memory and prevent leaks. We do this by passing the SDL_Cursor* to SDL_FreeCursor():

1// Create the cursor
2SDL_Cursor* Cursor{
3  SDL_CreateSystemCursor(SDL_SYSTEM_CURSOR_ARROW)
4};
5
6// Use the cursor...
7
8// Free it
9SDL_FreeCursor(Cursor);

Note this only applies to cursors we create using functions like SDL_CreateSystemCursor() or SDL_CreateColorCursor(). Every invocation of a cursor creation function should be matched with an invocation to SDL_FreeCursor().

Functions that retrieve a pointer to an existing SDL_Cursor, such as SDL_GetCursor() and SDL_GetDefaultCursor(), do not allocate new memory, so we do not need to free the pointer they return.

Getting the Current Cursor

We can get the cursor we are currently using SDL_GetCursor(). This will return the SDL_Cursor pointer applied from our most recent call to SDL_SetCursor(), or the default cursor if we never changed it:

1SDL_Cursor* Cursor{
2  SDL_GetCursor()
3};

We can use this to check if a specific cursor is currently active:

1SDL_Cursor* Crosshair{
2  SDL_CreateSystemCursor(SDL_SYSTEM_CURSOR_CROSSHAIR)
3};
4
5if (SDL_GetCursor() != Crosshair) {
6  std::cout << "Crosshair cursor is not active";
7}
8
9SDL_SetCursor(Cursor);
10
11if (SDL_GetCursor() == Crosshair) {
12  std::cout << "\nBut now it is";
13}

1Crosshair cursor is not active
2But now it is

Getting the Default Cursor

We can get a pointer to the system’s default cursor using the SDL_GetDefaultCursor() function:

1SDL_Cursor* DefaultCursor{
2  SDL_GetDefaultCursor()
3};

This is primarily used when we need to revert a change we made using SDL_SetCursor():

1SDL_Cursor* Crosshair{
2  SDL_CreateSystemCursor(SDL_SYSTEM_CURSOR_CROSSHAIR)
3};
4
5// Use a non-default cursor
6SDL_SetCursor(Crosshair);
7
8// ...
9
10// Revert to the default
11SDL_SetCursor(SDL_GetDefaultCursor());

If SDL_GetDefaultCursor() fails, it will return a nullptr, and we can call SDL_GetError() to understand why:

1SDL_Cursor* DefaultCursor{
2  SDL_GetDefaultCursor()
3};
4
5if (!DefaultCursor) {
6  std::cout << "Unable to get default cursor: "
7    << SDL_GetError();
8}

Creating a Custom Cursor

The first step of creating a custom cursor is to get the pixel data for that cursor into an SDL_Surface. Remember, we can use the SDL_image library to load an image file into an SDL_Surface:

1#include <SDL.h>
2#include <SDL_image.h>
3#include <iostream>
4
5int main(int, char**) {
6  // 1. Initialize SDL
7  SDL_Init(SDL_INIT_VIDEO);
8  IMG_Init(IMG_INIT_PNG);
9
10  // 2. Load image into an SDL_Surface
11  SDL_Surface* Surface{IMG_Load("cursor.png")};
12  if (!Surface) {
13    std::cout << "IMG_Load Error: "
14      << SDL_GetError();
15  }
16
17  // 3. Use surface
18  // ...
19
20  // 4. Cleanup resources
21  SDL_FreeSurface(Surface);
22  IMG_Quit();
23  SDL_Quit();
24
25  return 0;
26}

Once we have our SDL_Surface, we can create a cursor from it using the SDL_CreateColorCursor() function. We pass the SDL_Surface pointer as the first argument, in addition to two integers representing horizontal (x) and vertical (y) coordinates:

1#include <SDL.h>
2#include <SDL_image.h>
3#include <iostream>
4
5int main(int, char**) {
6  // 1. Initialize SDL
7  SDL_Init(SDL_INIT_VIDEO);
8  IMG_Init(IMG_INIT_PNG);
9
10  // 2. Load image into an SDL_Surface
11  SDL_Surface* Surface{IMG_Load("cursor.png")};
12  if (!Surface) {
13    std::cout << "IMG_Load Error: "
14      << SDL_GetError();
15  }
16
17  // 3. Create and use cursor
18  SDL_Cursor* Cursor{SDL_CreateColorCursor(
19    Surface, 10, 20)};
20  SDL_SetCursor(Cursor);
21
22  // The SDL_CreateColorCursor() function copies
23  // the image data so we can safely free the
24  // surface after it completes
25  SDL_FreeSurface(Surface);
26
27  // 4. Game Loop
28  // ...
29
30  // 5. Cleanup resources
31  IMG_Quit();
32  SDL_Quit();
33
34  return 0;
35}

The integer x and y arguments tell SDL where the "hot spot" is within the cursor image. The hot spot is the exact part of the cursor image that corresponds to what the user is pointing at.

For example, if our cursor was an image of an arrow, the hot spot would be the exact tip of that arrow. For a cursor designed to look like a hand, the hot spot would be the tip of the finger.

The x value is the distance of this pixel from the left edge of the image, and the y value is the distance from the top edge.

Error Handling

If SDL_CreateCursor() is unable to create a cursor, it will return a nullptr. We can react accordingly to this, and call SDL_GetError() if we want an explanation of what went wrong:

1SDL_Cursor* Cursor{SDL_CreateColorCursor(
2  nullptr, // Passing nullptr as surface 
3  10, 20
4)};
5
6if (!Cursor) {
7  std::cout << "Error creating cursor: "
8    << SDL_GetError();
9}

1Error creating cursor: Parameter 'surface' is invalid

Creating a Cursor Class

To manage custom cursors and take care of all the memory management required, we’d commonly want to create a dedicated class for this. For example:

1// Cursor.h
2#pragma once
3#include <SDL.h>
4#include <SDL_image.h>
5#include <iostream>
6
7class Cursor {
8public:
9  Cursor(std::string Path, int HotX, int HotY)
10    : CursorSurface{IMG_Load(Path.c_str())},
11      CursorPtr{nullptr},
12      HotspotX{HotX},
13      HotspotY{HotY}
14  {
15    if (!CursorSurface) {
16      std::cout << "IMG_Load Error: "
17        << SDL_GetError();
18      return;
19    }
20
21    CursorPtr = SDL_CreateColorCursor(
22      CursorSurface, HotspotX, HotspotY);
23
24    if (!CursorPtr) {
25      std::cout <<
26        "SDL_CreateColorCursor Error: "
27        << SDL_GetError();
28      SDL_FreeSurface(CursorSurface);
29      CursorSurface = nullptr;
30    }
31  }
32
33  ~Cursor() {
34    if (CursorPtr) {
35      SDL_FreeCursor(CursorPtr);
36    }
37    if (CursorSurface) {
38      SDL_FreeSurface(CursorSurface);
39    }
40  }
41
42  void Activate() const {
43    if (CursorPtr) {
44      SDL_SetCursor(CursorPtr);
45    }
46  }
47
48  void Deactivate() {
49    SDL_SetCursor(SDL_GetDefaultCursor());
50  }
51
52private:
53  SDL_Cursor* CursorPtr;
54  SDL_Surface* CursorSurface;
55  int HotspotX, HotspotY;
56};

The following program uses this class to create a custom cursor. The cursor is applied when the player presses 1, and reverted to the default when they press 2:

1// main.cpp
2#include <SDL.h>
3#include <SDL_image.h>
4#include <iostream>
5#include "Cursor.h"
6
7int main(int, char**) {
8  SDL_Init(SDL_INIT_VIDEO);
9  IMG_Init(IMG_INIT_PNG);
10
11  // Create a window
12  SDL_Window* Window{SDL_CreateWindow(
13    "Cursor Example",
14    SDL_WINDOWPOS_UNDEFINED,
15    SDL_WINDOWPOS_UNDEFINED,
16    800, 600, 0
17  )};
18
19  // Create a Cursor instance
20  Cursor CustomCursor{"cursor.png", 16, 16};
21
22  // Event loop
23  SDL_Event E;
24  while (true) {
25    while (SDL_PollEvent(&E)) {
26      if (E.type == SDL_QUIT) {
27        SDL_DestroyWindow(Window);
28        IMG_Quit();
29        SDL_Quit();
30        return 0;
31      }
32      if (E.type == SDL_KEYDOWN) {
33        if (E.key.keysym.sym == SDLK_1) {
34          CustomCursor.Activate();
35        } else if (E.key.keysym.sym == SDLK_2) {
36          CustomCursor.Deactivate();
37        }
38      }
39    }
40  }
41}

Bespoke Cursor Rendering

We’re not forced to use SDL’s mechanisms for cursor customization if we don’t want to. We can take on full responsibility for cursor rendering within our code. This allows us to do more advanced things with the cursor, such as animation or physics-based motion

To set this up, we’d hide the system-managed cursor using SDL_ShowCursor(SDL_DISABLE), and then render our object on the screen using, for example, the surface blitting techniques we covered earlier.

We’d update the blitting position based on SDL_MouseMotion events coming through our event loop, or SDL_GetMouseState() calls within a tick function.

Below, we’ve updated our Cursor class to use this technique. We also included a Tick() function as an example, but it’s not currently doing anything:

1// Cursor.h
2#pragma once
3#include <SDL.h>
4#include <SDL_image.h>
5#include <iostream>
6
7class Cursor {
8public:
9  Cursor(std::string Path, int HotX, int HotY)
10    : CursorSurface{IMG_Load(Path.c_str())},
11      HotspotX{HotX},
12      HotspotY{HotY} {
13    if (!CursorSurface) {
14      std::cout << "IMG_Load Error: "
15        << SDL_GetError();
16    }
17  }
18
19  ~Cursor() {
20    if (CursorSurface) {
21      SDL_FreeSurface(CursorSurface);
22    }
23  }
24  
25  void Tick() {
26    // Do tick things - eg animation
27    // ...
28  }
29
30  void HandleMouseMotion(
31    const SDL_MouseMotionEvent& E
32  ) {
33    // Update the cursor position such that the next
34    // render blits the image in the correct place
35    CursorX = E.x;
36    CursorY = E.y;
37  }
38
39  void Render(SDL_Surface* targetSurface) const {
40    if (!CursorSurface || !targetSurface) {
41      return;
42    }
43    
44    // Position the blitting such that the image's
45    // hotspot matches the last reported cursor position
46    SDL_Rect Destination{
47      CursorX - HotspotX,
48      CursorY - HotspotY,
49      0, 0
50    };
51
52    SDL_BlitSurface(
53      CursorSurface, nullptr,
54      targetSurface, &Destination
55    );
56  }
57
58private:
59  SDL_Surface* CursorSurface;
60  int HotspotX, HotspotY;
61  int CursorX, CursorY;
62};

Our event loop now needs to forward mouse motion events to our custom Cursor object, and our application loop needs to Tick() and Render() the cursor at the appropriate time.

Here’s an example:

1// main.cpp
2#include <SDL.h>
3#include <SDL_image.h>
4#include <iostream>
5#include "Cursor.h"
6
7int main(int, char**) {
8  SDL_Init(SDL_INIT_VIDEO);
9  IMG_Init(IMG_INIT_PNG);
10
11  // Create a window
12  SDL_Window* Window{SDL_CreateWindow(
13    "Cursor Example",
14    SDL_WINDOWPOS_UNDEFINED,
15    SDL_WINDOWPOS_UNDEFINED,
16    800, 600, 0
17  )};
18
19  SDL_Surface* WindowSurface{
20    SDL_GetWindowSurface(Window)};
21
22  // Create a Cursor instance
23  Cursor CustomCursor{"cursor.png", 16, 16};
24
25  // Application loop
26  SDL_Event E;
27  while (true) {
28    // 1. HANDLE EVENTS
29    while (SDL_PollEvent(&E)) {
30      if (E.type == SDL_QUIT) {
31        SDL_DestroyWindow(Window);
32        IMG_Quit();
33        SDL_Quit();
34        return 0;
35      }
36
37      if (E.type == SDL_MOUSEMOTION) {
38        CustomCursor.HandleMouseMotion(E.motion);
39      }
40    }
41    
42    // 2. TICK
43    CustomCursor.Tick();
44    
45    // 3. RENDER
46    // Start a new frame by clearing the surface
47    SDL_FillRect(
48      WindowSurface,
49      nullptr,
50      SDL_MapRGB(WindowSurface->format, 0, 0, 0
51    ));
52    
53    // Render the game objects and UI elements
54    // ...
55
56    // Render the cursor last to ensure it is on
57    // top of the other content
58    CustomCursor.Render(WindowSurface);
59
60    // Display the new frame
61    SDL_UpdateWindowSurface(Window);
62  }
63}

Note that, whilst rendering the cursor through our application loop gives us more flexibility, there is a downside compared to using the native cursor rendering approach provided by functions like SDL_CreateColorCursor() and SDL_SetCursor().

When we render the cursor as part of our regular game loop, it means cursor updates are constrained by how fast our loop can output each frame.

Reduced frame rates are particularly noticable to players when it affects their cursor motion, so we should be careful here. We should only use this approach if it we require the more advanced capabilities it unlocks, or if we’re certain our application will run quickly enough to ensure the user’s mouse actions remain highly responsive.

Summary

In this lesson, we covered all the main cursor management techniques available within SDL games. Here are the key points:

• Controlling cursor visibility using SDL_ShowCursor()
• Using system-provided cursors through SDL_CreateSystemCursor()
• Managing cursor resources with proper cleanup
• Creating custom cursors from images with SDL_CreateColorCursor()
• Understanding cursor hotspots and their importance
• Creating a reusable Cursor class for better organization
• Implementing custom cursor rendering for advanced effects

Next Lesson

Working with Data

Learn techniques for managing game data, including save systems, configuration, and networked multiplayer.

ContinueView Course