---
name: "SDL_CreateCursor"
section: "3"
platform: "linux"
package: "libsdl3-doc"
version: "3.2.10+ds-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/SDL_CreateCursor"
---

# SDL\_CreateCursor(3)

Create a cursor using the specified bitmap data and mask (in MSB format).

## NAME

SDL\_CreateCursor - Create a cursor using the specified bitmap data and mask (in MSB format).

## HEADER FILE

Defined in SDL3/SDL\_mouse.h

## SYNOPSIS

```
#include "SDL3/SDL.h"
```

**SDL\_Cursor \* SDL\_CreateCursor(const Uint8 \*data,**                          **const Uint8 \*mask,**                          **int w, int h, int hot\_x,**                          **int hot\_y);**

## DESCRIPTION

**mask** has to be in MSB (Most Significant Bit) format.

The cursor width ( **w** ) must be a multiple of 8 bits.

The cursor is created in black and white according to the following:

• data=0, mask=1: white

• data=1, mask=1: black

• data=0, mask=0: transparent

• data=1, mask=0: inverted color if possible, black if not.

Cursors created with this function must be freed with

**SDL\_DestroyCursor** ().

If you want to have a color cursor, or create your cursor from an

**SDL\_Surface** , you should use

**SDL\_CreateColorCursor** (). Alternately, you can hide the cursor and draw your own as part of your game's rendering, but it will be bound to the framerate.

Also,  **SDL\_CreateSystemCursor** () is available, which provides several readily-available system cursors to pick from.

## FUNCTION PARAMETERS

- *data*

  the color value for each pixel of the cursor.

- *mask*

  the mask value for each pixel of the cursor.

- *w*

  the width of the cursor.

- *h*

  the height of the cursor.

- *hot\_x*

  the x-axis offset from the left of the cursor image to the mouse x position, in the range of 0 to **w**

  • 1.

- *hot\_y*

  the y-axis offset from the top of the cursor image to the mouse y position, in the range of 0 to **h**

  • 1.

## RETURN VALUE

( **SDL\_Cursor**\
  \*) Returns a new cursor with the specified parameters on success or NULL on failure; call

**SDL\_GetError** () for more information.

## THREAD SAFETY

This function should only be called on the main thread.

## AVAILABILITY

This function is available since SDL 3.2.0.

## SEE ALSO

**•**(3), [**SDL\_CreateColorCursor**(3)](/SDL_CreateColorCursor/3.md), **•**(3), [**SDL\_CreateSystemCursor**(3)](/SDL_CreateSystemCursor/3.md), **•**(3), [**SDL\_DestroyCursor**(3)](/SDL_DestroyCursor/3.md), **•**(3), [**SDL\_SetCursor**(3)](/SDL_SetCursor/3.md)