devela::_dep::sdl3::sys::mouse

Function SDL_CreateCursor

pub unsafe extern "C" fn SDL_CreateCursor(
    data: *const u8,
    mask: *const u8,
    w: i32,
    h: i32,
    hot_x: i32,
    hot_y: i32,
) -> *mut SDL_Cursor
Available on crate feature dep_sdl3 only.
Expand description

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

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.

§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

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