Customising Mouse Cursors

This lesson builds on our earlier work. To focus on cursor customization, we will start with a minimal project containing a Window class and a main function with a basic application loop.

In SDL3, cursor visibility is controlled by two distinct functions: SDL_ShowCursor() and SDL_HideCursor():

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

Handling Errors When Toggling the Cursor

Both SDL_ShowCursor() and SDL_HideCursor() return true on success and false on failure. This allows us to check for errors and use SDL_GetError() for an explanation:

1if (!SDL_HideCursor()) {
2  std::cout << "Error hiding cursor: "
3    << SDL_GetError();
4}

Querying Cursor Visibility

We can use SDL_CursorVisible() to determine the current visibility of the cursor without changing it. It returns true if the cursor is visible and false otherwise:

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

1Cursor is visible

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_DEFAULT:

1SDL_CreateSystemCursor(SDL_SYSTEM_CURSOR_DEFAULT);

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

1SDL_Cursor* Cursor{
2  SDL_CreateSystemCursor(SDL_SYSTEM_CURSOR_DEFAULT)
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.

Using SDL_SystemCursor Values

The SDL_SystemCursor enum includes a set of values for common cursors. Note that the names have changed from SDL2 to align with CSS cursor names. Its possible values are as follows:

• SDL_SYSTEM_CURSOR_DEFAULT: The default cursor, usually an arrow.
• SDL_SYSTEM_CURSOR_POINTER: An alternative cursor designed to look like a hand.
• SDL_SYSTEM_CURSOR_CROSSHAIR: A cursor designed to look like a crosshair.
• SDL_SYSTEM_CURSOR_TEXT: The I-beam cursor, typically used for text editing.
• SDL_SYSTEM_CURSOR_PROGRESS: A cursor designed to indicate something is loading.
• SDL_SYSTEM_CURSOR_NOT_ALLOWED: Used to indicate blocked or disabled actions.

Most systems have cursors designed to indicate resizing actions. We can load these system cursors using the following enum values:

• SDL_SYSTEM_CURSOR_NWSE_RESIZE: Double arrow pointing northwest and southeast.
• SDL_SYSTEM_CURSOR_NESW_RESIZE: Double arrow pointing northeast and southwest.
• SDL_SYSTEM_CURSOR_EW_RESIZE: Double arrow pointing east and west.
• SDL_SYSTEM_CURSOR_NS_RESIZE: Double arrow pointing north and south.
• SDL_SYSTEM_CURSOR_MOVE: Four-pointed arrow pointing north, south, east, and west.

Errors When Creating System Cursors

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_DEFAULT)
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_DEFAULT)
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. In SDL3, we do this by passing the SDL_Cursor* to SDL_DestroyCursor():

1// Create the cursor
2SDL_Cursor* Cursor{
3  SDL_CreateSystemCursor(SDL_SYSTEM_CURSOR_DEFAULT)
4};
5
6// Use the cursor...
7
8// Free it
9SDL_DestroyCursor(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_DestroyCursor(). We cover constructors and destructors in more detail in our introductory course.

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:

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "Window.h"
5
6int main(int, char**) {
7  SDL_Init(SDL_INIT_VIDEO);
8  Window GameWindow;
9
10  SDL_Cursor* Crosshair{
11    SDL_CreateSystemCursor(SDL_SYSTEM_CURSOR_CROSSHAIR)
12  };
13
14  if (SDL_GetCursor() != Crosshair) {
15    std::cout << "Crosshair cursor is not active";
16  }
17
18  SDL_SetCursor(Crosshair);
19
20  if (SDL_GetCursor() == Crosshair) {
21    std::cout << "\nBut now it is";
22  }
23  
24  SDL_Event Event;
25  bool IsRunning = true;
26  while (IsRunning) {
27    while (SDL_PollEvent(&Event)) {
28      if (Event.type == SDL_EVENT_QUIT) {
29        IsRunning = false;
30      }
31    }
32    GameWindow.Render();
33    GameWindow.Update();
34  }
35
36  SDL_Quit();
37  return 0;
38}

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}

It's not necessary to call SDL_DestroyCursor() on the default cursor, but it is safe to do so.

Creating a Custom Cursor

We'll walk through the underlying mechanics for creating custom cursors here, but will create a full implementation in a dedicated class in the next section.

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 SDL3_image library to load an image file into an SDL_Surface:

1SDL_Surface* Surface{IMG_Load("cursor.png")};
2if (!Surface) {
3  std::cout << "IMG_Load Error: " << SDL_GetError();
4}
5  
6// ...
7  
8// Remember to free resources when no longer needed
9SDL_DestroySurface(Surface);

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:

1SDL_Cursor* Cursor{SDL_CreateColorCursor(
2  Surface, 10, 20
3)};
4SDL_SetCursor(Cursor);
5
6// ...
7
8// Remember to free resources when no longer needed
9SDL_DestroyCursor(Cursor)

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.

Errors When Creating Cursors

If SDL_CreateColorCursor() 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

The following class combines these image and cursor management techniques behind a friendly interface:

src/Cursor.h

1#pragma once
2#include <SDL3/SDL.h>
3#include <SDL3_image/SDL_image.h>
4#include <iostream>
5#include <string>
6
7class Cursor {
8public:
9  Cursor(const 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() << '\n';
18      return;
19    }
20
21    CursorPtr = SDL_CreateColorCursor(
22      CursorSurface, HotspotX, HotspotY
23    );
24      
25    if (!CursorPtr) {
26      std::cout << "SDL_CreateColorCursor Error: "
27        << SDL_GetError() << '\n';
28      SDL_DestroySurface(CursorSurface);
29      CursorSurface = nullptr;
30    }
31  }
32
33  void Activate() const {
34    if (CursorPtr) {
35      SDL_SetCursor(CursorPtr);
36    }
37  }
38
39  static void Deactivate() {
40    SDL_SetCursor(SDL_GetDefaultCursor());
41  }
42
43  bool IsValid() const {
44    return CursorPtr != nullptr;
45  }
46  
47  // Memory management
48  ~Cursor() {
49    if (CursorPtr) {
50      SDL_DestroyCursor(CursorPtr);
51    }
52    if (CursorSurface) {
53      SDL_DestroySurface(CursorSurface);
54    }
55  }
56  
57  // Disabling copying to simplify memory management
58  Cursor(const Cursor&) = delete;
59  Cursor& operator=(const Cursor&) = delete;
60
61private:
62  SDL_Cursor* CursorPtr;
63  SDL_Surface* CursorSurface;
64  int HotspotX, HotspotY;
65};

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:

Files

src

Select a file to view its content

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_HideCursor(), 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_EVENT_MOUSE_MOTION events coming through our event loop, or SDL_GetMouseState() calls within a tick function. We cover this in more detail in our lesson on mouse state .

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:

src/Cursor.h

1#pragma once
2#include <SDL3/SDL.h>
3#include <SDL3_image/SDL_image.h>
4#include <iostream>
5#include <string>
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_DestroySurface(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      (int)(CursorX - HotspotX),
48      (int)(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  float CursorX = 0.0f, CursorY = 0.0f;
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:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "Cursor.h"
5#include "Window.h"
6
7int main(int, char**) {
8  SDL_Init(SDL_INIT_VIDEO);
9  Window GameWindow;
10  Cursor CustomCursor{"cursor.png", 16, 16};
11  SDL_HideCursor();
12
13  SDL_Event E;
14  bool IsRunning = true;
15  while (IsRunning) {
16    while (SDL_PollEvent(&E)) {
17      if (E.type == SDL_EVENT_QUIT) {
18        IsRunning = false;
19      } else if (E.type == SDL_EVENT_MOUSE_MOTION) {
20        CustomCursor.HandleMouseMotion(E.motion);
21      }
22    }
23
24    CustomCursor.Tick();
25
26    GameWindow.Render();
27    CustomCursor.Render(GameWindow.GetSurface());
28
29    GameWindow.Update();
30  }
31
32  SDL_Quit();
33  return 0;
34}

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 noticeable to players when it affects their cursor motion, so we should be careful here. We should only use this approach if 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 SDL3. Here are the key points:

• Controlling cursor visibility using SDL_ShowCursor() and SDL_HideCursor().
• Using system-provided cursors through SDL_CreateSystemCursor().
• Managing cursor resources with proper cleanup using SDL_DestroyCursor().
• 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.