#pragma section-numbers off
#pragma disable-camelcase
||<tablewidth="100%" style="color: #FF0000;" :> DRAFT||

= SDL_CreateCursor =
Use this function to create a cursor using the specified bitmap data and mask (in MSB format).

<<TableOfContents()>>

== Syntax ==
{{{#!highlight cpp
SDL_Cursor* SDL_CreateCursor(const Uint8* data,
                             const Uint8* mask,
                             int          w,
                             int          h,
                             int          hot_x,
                             int          hot_y)
}}}

== Function Parameters ==
||'''data'''||the color value for each pixel of the cursor; see [[#Remarks|Remarks]] for details||
||'''mask'''||the mask value for each pixel of the cursor; see [[#Remarks|Remarks]] for details||
||'''w'''||the width of the cursor; see [[#Remarks|Remarks]] for details||
||'''h'''||the height of the cursor ''(same restrictions as w?)''||
||'''hot_x'''||the X-axis location of the upper left corner of the cursor relative to the actual mouse position||
||'''hot_y'''||the Y-axis location of the upper left corner of the cursor relative to the actual mouse position||

== Return Value ==
Returns a new cursor with the specified parameters on success or NULL on failure; call [[SDL_GetError]]() for more information.

== Code Examples ==

{{{#!highlight cpp
/* Stolen from the mailing list */
/* Creates a new mouse cursor from an XPM */


/* XPM */
static const char *arrow[] = {
  /* width height num_colors chars_per_pixel */
  "    32    32        3            1",
  /* colors */
  "X c #000000",
  ". c #ffffff",
  "  c None",
  /* pixels */
  "X                               ",
  "XX                              ",
  "X.X                             ",
  "X..X                            ",
  "X...X                           ",
  "X....X                          ",
  "X.....X                         ",
  "X......X                        ",
  "X.......X                       ",
  "X........X                      ",
  "X.....XXXXX                     ",
  "X..X..X                         ",
  "X.X X..X                        ",
  "XX  X..X                        ",
  "X    X..X                       ",
  "     X..X                       ",
  "      X..X                      ",
  "      X..X                      ",
  "       XX                       ",
  "                                ",
  "                                ",
  "                                ",
  "                                ",
  "                                ",
  "                                ",
  "                                ",
  "                                ",
  "                                ",
  "                                ",
  "                                ",
  "                                ",
  "                                ",
  "0,0"
};

static SDL_Cursor *init_system_cursor(const char *image[])
{
  int i, row, col;
  Uint8 data[4*32];
  Uint8 mask[4*32];
  int hot_x, hot_y;

  i = -1;
  for (row=0; row<32; ++row) {
    for (col=0; col<32; ++col) {
      if (col % 8) {
        data[i] <<= 1;
        mask[i] <<= 1;
      } else {
        ++i;
        data[i] = mask[i] = 0;
      }
      switch (image[4+row][col]) {
        case 'X':
          data[i] |= 0x01;
          mask[i] |= 0x01;
          break;
        case '.':
          mask[i] |= 0x01;
          break;
        case ' ':
          break;
      }
    }
  }
  sscanf(image[4+row], "%d,%d", &hot_x, &hot_y);
  return SDL_CreateCursor(data, mask, 32, 32, hot_x, hot_y);
}
}}}

== Remarks ==
'''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'''||<:> '''mask'''||<:> Resulting Pixel on Screen||
||<:> 0||<:> 1||<:> White||
||<:> 1||<:> 1||<:> Black||
||<:> 0||<:> 0||<:> Transparent||
||<:> 1||<:> 0||<:> Inverted color if possible, black if not||

Cursors created with this function must be freed with [[SDL_FreeCursor]]().

If you want to have a color cursor, then this function is not for you; instead, you must hide the normal system cursor using [[SDL_ShowCursor]]() and in your main loop, when you draw graphics, also draw a [[SDL_Surface]] at the location of the mouse cursor.

Or use [[SDL_CreateColorCursor]]().

/* <<Color2(col=green,text="Should the above comment about color cursors be rephrased to be less conversational?  Example below:")>> */

/* ^To create a color cursor hide the normal system cursor (use [[SDL_ShowCursor]]() to find it???) and, along with your other graphics, draw an [[SDL_Surface]] at the location of the mouse cursor in your main loop.^ */

Note that, since SDL 2.0.0, [[SDL_CreateSystemCursor]]() is available, which provides twelve readily available system cursors to pick from.

== Related Functions ==
 .[[SDL_FreeCursor]]
 .[[SDL_SetCursor]]
 .[[SDL_ShowCursor]]

----
[[CategoryAPI]], [[CategoryMouse]]