---
name: "SDL_CreateSurfacePalette"
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_CreateSurfacePalette"
---

# SDL\_CreateSurfacePalette(3)

Create a palette and associate it with a surface.

## NAME

SDL\_CreateSurfacePalette - Create a palette and associate it with a surface.

## HEADER FILE

Defined in SDL3/SDL\_surface.h

## SYNOPSIS

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

**SDL\_Palette \* SDL\_CreateSurfacePalette(SDL\_Surface \*surface);**

## DESCRIPTION

This function creates a palette compatible with the provided surface. The palette is then returned for you to modify, and the surface will automatically use the new palette in future operations. You do not need to destroy the returned palette, it will be freed when the reference count reaches 0, usually when the surface is destroyed.

Bitmap surfaces (with format

**SDL\_PIXELFORMAT\_INDEX1LSB**\
  or

**SDL\_PIXELFORMAT\_INDEX1MSB** ) will have the palette initialized with 0 as white and 1 as black. Other surfaces will get a palette initialized with white in every entry.

If this function is called for a surface that already has a palette, a new palette will be created to replace it.

## FUNCTION PARAMETERS

- *surface*

  the  **SDL\_Surface**\
    structure to update.

## RETURN VALUE

( **SDL\_Palette**\
  \*) Returns a new  **SDL\_Palette**

structure on success or NULL on failure (e.g. if the surface didn't have an index format); call  **SDL\_GetError** () for more information.

## THREAD SAFETY

This function is not thread safe.

## AVAILABILITY

This function is available since SDL 3.2.0.

## SEE ALSO

**•**(3), [**SDL\_SetPaletteColors**(3)](/SDL_SetPaletteColors/3.md)