My Project
Loading...
Searching...
No Matches
SDL_pixels.h File Reference
#include "SDL_stdinc.h"
#include "SDL_endian.h"
#include "begin_code.h"
#include "close_code.h"

Go to the source code of this file.

Data Structures

struct  SDL_Color
 
struct  SDL_Palette
 
struct  SDL_PixelFormat
 

Transparency definitions

These define alpha as the opacity of a surface.

#define SDL_ALPHA_OPAQUE   255
 
#define SDL_ALPHA_TRANSPARENT   0
 
#define SDL_DEFINE_PIXELFOURCC(A, B, C, D)   SDL_FOURCC(A, B, C, D)
 
#define SDL_DEFINE_PIXELFORMAT(type, order, layout, bits, bytes)
 
#define SDL_PIXELFLAG(X)   (((X) >> 28) & 0x0F)
 
#define SDL_PIXELTYPE(X)   (((X) >> 24) & 0x0F)
 
#define SDL_PIXELORDER(X)   (((X) >> 20) & 0x0F)
 
#define SDL_PIXELLAYOUT(X)   (((X) >> 16) & 0x0F)
 
#define SDL_BITSPERPIXEL(X)   (((X) >> 8) & 0xFF)
 
#define SDL_BYTESPERPIXEL(X)
 
#define SDL_ISPIXELFORMAT_INDEXED(format)
 
#define SDL_ISPIXELFORMAT_PACKED(format)
 
#define SDL_ISPIXELFORMAT_ARRAY(format)
 
#define SDL_ISPIXELFORMAT_ALPHA(format)
 
#define SDL_ISPIXELFORMAT_FOURCC(format)    ((format) && (SDL_PIXELFLAG(format) != 1))
 
#define SDL_Colour   SDL_Color
 
enum  SDL_PixelType {
  SDL_PIXELTYPE_UNKNOWN , SDL_PIXELTYPE_INDEX1 , SDL_PIXELTYPE_INDEX4 , SDL_PIXELTYPE_INDEX8 ,
  SDL_PIXELTYPE_PACKED8 , SDL_PIXELTYPE_PACKED16 , SDL_PIXELTYPE_PACKED32 , SDL_PIXELTYPE_ARRAYU8 ,
  SDL_PIXELTYPE_ARRAYU16 , SDL_PIXELTYPE_ARRAYU32 , SDL_PIXELTYPE_ARRAYF16 , SDL_PIXELTYPE_ARRAYF32
}
 
enum  SDL_BitmapOrder { SDL_BITMAPORDER_NONE , SDL_BITMAPORDER_4321 , SDL_BITMAPORDER_1234 }
 
enum  SDL_PackedOrder {
  SDL_PACKEDORDER_NONE , SDL_PACKEDORDER_XRGB , SDL_PACKEDORDER_RGBX , SDL_PACKEDORDER_ARGB ,
  SDL_PACKEDORDER_RGBA , SDL_PACKEDORDER_XBGR , SDL_PACKEDORDER_BGRX , SDL_PACKEDORDER_ABGR ,
  SDL_PACKEDORDER_BGRA
}
 
enum  SDL_ArrayOrder {
  SDL_ARRAYORDER_NONE , SDL_ARRAYORDER_RGB , SDL_ARRAYORDER_RGBA , SDL_ARRAYORDER_ARGB ,
  SDL_ARRAYORDER_BGR , SDL_ARRAYORDER_BGRA , SDL_ARRAYORDER_ABGR
}
 
enum  SDL_PackedLayout {
  SDL_PACKEDLAYOUT_NONE , SDL_PACKEDLAYOUT_332 , SDL_PACKEDLAYOUT_4444 , SDL_PACKEDLAYOUT_1555 ,
  SDL_PACKEDLAYOUT_5551 , SDL_PACKEDLAYOUT_565 , SDL_PACKEDLAYOUT_8888 , SDL_PACKEDLAYOUT_2101010 ,
  SDL_PACKEDLAYOUT_1010102
}
 
enum  SDL_PixelFormatEnum {
  SDL_PIXELFORMAT_UNKNOWN , SDL_PIXELFORMAT_INDEX1LSB , SDL_PIXELFORMAT_INDEX1MSB , SDL_PIXELFORMAT_INDEX4LSB ,
  SDL_PIXELFORMAT_INDEX4MSB , SDL_PIXELFORMAT_INDEX8 , SDL_PIXELFORMAT_RGB332 , SDL_PIXELFORMAT_XRGB4444 ,
  SDL_PIXELFORMAT_RGB444 = SDL_PIXELFORMAT_XRGB4444 , SDL_PIXELFORMAT_XBGR4444 , SDL_PIXELFORMAT_BGR444 = SDL_PIXELFORMAT_XBGR4444 , SDL_PIXELFORMAT_XRGB1555 ,
  SDL_PIXELFORMAT_RGB555 = SDL_PIXELFORMAT_XRGB1555 , SDL_PIXELFORMAT_XBGR1555 , SDL_PIXELFORMAT_BGR555 = SDL_PIXELFORMAT_XBGR1555 , SDL_PIXELFORMAT_ARGB4444 ,
  SDL_PIXELFORMAT_RGBA4444 , SDL_PIXELFORMAT_ABGR4444 , SDL_PIXELFORMAT_BGRA4444 , SDL_PIXELFORMAT_ARGB1555 ,
  SDL_PIXELFORMAT_RGBA5551 , SDL_PIXELFORMAT_ABGR1555 , SDL_PIXELFORMAT_BGRA5551 , SDL_PIXELFORMAT_RGB565 ,
  SDL_PIXELFORMAT_BGR565 , SDL_PIXELFORMAT_RGB24 , SDL_PIXELFORMAT_BGR24 , SDL_PIXELFORMAT_XRGB8888 ,
  SDL_PIXELFORMAT_RGB888 = SDL_PIXELFORMAT_XRGB8888 , SDL_PIXELFORMAT_RGBX8888 , SDL_PIXELFORMAT_XBGR8888 , SDL_PIXELFORMAT_BGR888 = SDL_PIXELFORMAT_XBGR8888 ,
  SDL_PIXELFORMAT_BGRX8888 , SDL_PIXELFORMAT_ARGB8888 , SDL_PIXELFORMAT_RGBA8888 , SDL_PIXELFORMAT_ABGR8888 ,
  SDL_PIXELFORMAT_BGRA8888 , SDL_PIXELFORMAT_ARGB2101010 , SDL_PIXELFORMAT_RGBA32 = SDL_PIXELFORMAT_ABGR8888 , SDL_PIXELFORMAT_ARGB32 = SDL_PIXELFORMAT_BGRA8888 ,
  SDL_PIXELFORMAT_BGRA32 = SDL_PIXELFORMAT_ARGB8888 , SDL_PIXELFORMAT_ABGR32 = SDL_PIXELFORMAT_RGBA8888 , SDL_PIXELFORMAT_YV12 , SDL_PIXELFORMAT_IYUV ,
  SDL_PIXELFORMAT_YUY2 , SDL_PIXELFORMAT_UYVY , SDL_PIXELFORMAT_YVYU , SDL_PIXELFORMAT_NV12 ,
  SDL_PIXELFORMAT_NV21 , SDL_PIXELFORMAT_EXTERNAL_OES =
}
 
typedef struct SDL_Color SDL_Color
 
typedef struct SDL_Palette SDL_Palette
 
typedef struct SDL_PixelFormat SDL_PixelFormat
 
DECLSPEC const char *SDLCALL SDL_GetPixelFormatName (Uint32 format)
 
DECLSPEC SDL_bool SDLCALL SDL_PixelFormatEnumToMasks (Uint32 format, int *bpp, Uint32 *Rmask, Uint32 *Gmask, Uint32 *Bmask, Uint32 *Amask)
 
DECLSPEC Uint32 SDLCALL SDL_MasksToPixelFormatEnum (int bpp, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask)
 
DECLSPEC SDL_PixelFormat *SDLCALL SDL_AllocFormat (Uint32 pixel_format)
 
DECLSPEC void SDLCALL SDL_FreeFormat (SDL_PixelFormat *format)
 
DECLSPEC SDL_Palette *SDLCALL SDL_AllocPalette (int ncolors)
 
DECLSPEC int SDLCALL SDL_SetPixelFormatPalette (SDL_PixelFormat *format, SDL_Palette *palette)
 
DECLSPEC int SDLCALL SDL_SetPaletteColors (SDL_Palette *palette, const SDL_Color *colors, int firstcolor, int ncolors)
 
DECLSPEC void SDLCALL SDL_FreePalette (SDL_Palette *palette)
 
DECLSPEC Uint32 SDLCALL SDL_MapRGB (const SDL_PixelFormat *format, Uint8 r, Uint8 g, Uint8 b)
 
DECLSPEC Uint32 SDLCALL SDL_MapRGBA (const SDL_PixelFormat *format, Uint8 r, Uint8 g, Uint8 b, Uint8 a)
 
DECLSPEC void SDLCALL SDL_GetRGB (Uint32 pixel, const SDL_PixelFormat *format, Uint8 *r, Uint8 *g, Uint8 *b)
 
DECLSPEC void SDLCALL SDL_GetRGBA (Uint32 pixel, const SDL_PixelFormat *format, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a)
 
DECLSPEC void SDLCALL SDL_CalculateGammaRamp (float gamma, Uint16 *ramp)
 

Detailed Description

Header for the enumerated pixel format definitions.

Macro Definition Documentation

◆ SDL_BYTESPERPIXEL

#define SDL_BYTESPERPIXEL (   X)
Value:
(SDL_ISPIXELFORMAT_FOURCC(X) ? \
((((X) == SDL_PIXELFORMAT_YUY2) || \
((X) == SDL_PIXELFORMAT_UYVY) || \
((X) == SDL_PIXELFORMAT_YVYU)) ? 2 : 1) : (((X) >> 0) & 0xFF))
@ SDL_PIXELFORMAT_YVYU
Definition: SDL_pixels.h:294
@ SDL_PIXELFORMAT_UYVY
Definition: SDL_pixels.h:292
@ SDL_PIXELFORMAT_YUY2
Definition: SDL_pixels.h:290

◆ SDL_DEFINE_PIXELFORMAT

#define SDL_DEFINE_PIXELFORMAT (   type,
  order,
  layout,
  bits,
  bytes 
)
Value:
((1 << 28) | ((type) << 24) | ((order) << 20) | ((layout) << 16) | \
((bits) << 8) | ((bytes) << 0))

◆ SDL_ISPIXELFORMAT_ALPHA

#define SDL_ISPIXELFORMAT_ALPHA (   format)
Value:
((SDL_ISPIXELFORMAT_PACKED(format) && \
((SDL_PIXELORDER(format) == SDL_PACKEDORDER_ARGB) || \
(SDL_PIXELORDER(format) == SDL_PACKEDORDER_RGBA) || \
(SDL_PIXELORDER(format) == SDL_PACKEDORDER_ABGR) || \
(SDL_PIXELORDER(format) == SDL_PACKEDORDER_BGRA))) || \
(SDL_ISPIXELFORMAT_ARRAY(format) && \
((SDL_PIXELORDER(format) == SDL_ARRAYORDER_ARGB) || \
(SDL_PIXELORDER(format) == SDL_ARRAYORDER_RGBA) || \
(SDL_PIXELORDER(format) == SDL_ARRAYORDER_ABGR) || \
(SDL_PIXELORDER(format) == SDL_ARRAYORDER_BGRA))))

◆ SDL_ISPIXELFORMAT_ARRAY

#define SDL_ISPIXELFORMAT_ARRAY (   format)
Value:
(!SDL_ISPIXELFORMAT_FOURCC(format) && \
((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYU8) || \
(SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYU16) || \
(SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYU32) || \
(SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF16) || \
(SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF32)))

◆ SDL_ISPIXELFORMAT_INDEXED

#define SDL_ISPIXELFORMAT_INDEXED (   format)
Value:
(!SDL_ISPIXELFORMAT_FOURCC(format) && \
((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX1) || \
(SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX4) || \
(SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX8)))

◆ SDL_ISPIXELFORMAT_PACKED

#define SDL_ISPIXELFORMAT_PACKED (   format)
Value:
(!SDL_ISPIXELFORMAT_FOURCC(format) && \
((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED8) || \
(SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED16) || \
(SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED32)))

Typedef Documentation

◆ SDL_Color

typedef struct SDL_Color SDL_Color

The bits of this structure can be directly reinterpreted as an integer-packed color which uses the SDL_PIXELFORMAT_RGBA32 format (SDL_PIXELFORMAT_ABGR8888 on little-endian systems and SDL_PIXELFORMAT_RGBA8888 on big-endian systems).

◆ SDL_PixelFormat

Note
Everything in the pixel format structure is read-only.

Enumeration Type Documentation

◆ SDL_ArrayOrder

Array component order, low byte -> high byte.

◆ SDL_BitmapOrder

Bitmap pixel order, high bit -> low bit.

◆ SDL_PackedLayout

Packed component layout.

◆ SDL_PackedOrder

Packed component order, high bit -> low bit.

◆ SDL_PixelFormatEnum

Enumerator
SDL_PIXELFORMAT_YV12 

Planar mode: Y + V + U (3 planes)

SDL_PIXELFORMAT_IYUV 

Planar mode: Y + U + V (3 planes)

SDL_PIXELFORMAT_YUY2 

Packed mode: Y0+U0+Y1+V0 (1 plane)

SDL_PIXELFORMAT_UYVY 

Packed mode: U0+Y0+V0+Y1 (1 plane)

SDL_PIXELFORMAT_YVYU 

Packed mode: Y0+V0+Y1+U0 (1 plane)

SDL_PIXELFORMAT_NV12 

Planar mode: Y + U/V interleaved (2 planes)

SDL_PIXELFORMAT_NV21 

Planar mode: Y + V/U interleaved (2 planes)

SDL_PIXELFORMAT_EXTERNAL_OES 

Android video texture format

◆ SDL_PixelType

Pixel type.

Function Documentation

◆ SDL_AllocFormat()

DECLSPEC SDL_PixelFormat *SDLCALL SDL_AllocFormat ( Uint32  pixel_format)

Create an SDL_PixelFormat structure corresponding to a pixel format.

Returned structure may come from a shared global cache (i.e. not newly allocated), and hence should not be modified, especially the palette. Weird errors such as Blit combination not supported may occur.

Parameters
pixel_formatone of the SDL_PixelFormatEnum values
Returns
the new SDL_PixelFormat structure or NULL on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 2.0.0.
See also
SDL_FreeFormat

◆ SDL_AllocPalette()

DECLSPEC SDL_Palette *SDLCALL SDL_AllocPalette ( int  ncolors)

Create a palette structure with the specified number of color entries.

The palette entries are initialized to white.

Parameters
ncolorsrepresents the number of color entries in the color palette
Returns
a new SDL_Palette structure on success or NULL on failure (e.g. if there wasn't enough memory); call SDL_GetError() for more information.
Since
This function is available since SDL 2.0.0.
See also
SDL_FreePalette

◆ SDL_CalculateGammaRamp()

DECLSPEC void SDLCALL SDL_CalculateGammaRamp ( float  gamma,
Uint16 *  ramp 
)

Calculate a 256 entry gamma ramp for a gamma value.

Parameters
gammaa gamma value where 0.0 is black and 1.0 is identity
rampan array of 256 values filled in with the gamma ramp
Since
This function is available since SDL 2.0.0.
See also
SDL_SetWindowGammaRamp

◆ SDL_FreeFormat()

DECLSPEC void SDLCALL SDL_FreeFormat ( SDL_PixelFormat format)

Free an SDL_PixelFormat structure allocated by SDL_AllocFormat().

Parameters
formatthe SDL_PixelFormat structure to free
Since
This function is available since SDL 2.0.0.
See also
SDL_AllocFormat

◆ SDL_FreePalette()

DECLSPEC void SDLCALL SDL_FreePalette ( SDL_Palette palette)

Free a palette created with SDL_AllocPalette().

Parameters
palettethe SDL_Palette structure to be freed
Since
This function is available since SDL 2.0.0.
See also
SDL_AllocPalette

◆ SDL_GetPixelFormatName()

DECLSPEC const char *SDLCALL SDL_GetPixelFormatName ( Uint32  format)

Get the human readable name of a pixel format.

Parameters
formatthe pixel format to query
Returns
the human readable name of the specified pixel format or SDL_PIXELFORMAT_UNKNOWN if the format isn't recognized.
Since
This function is available since SDL 2.0.0.

◆ SDL_GetRGB()

DECLSPEC void SDLCALL SDL_GetRGB ( Uint32  pixel,
const SDL_PixelFormat format,
Uint8 *  r,
Uint8 *  g,
Uint8 *  b 
)

Get RGB values from a pixel in the specified format.

This function uses the entire 8-bit [0..255] range when converting color components from pixel formats with less than 8-bits per RGB component (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff, 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).

Parameters
pixela pixel value
formatan SDL_PixelFormat structure describing the format of the pixel
ra pointer filled in with the red component
ga pointer filled in with the green component
ba pointer filled in with the blue component
Since
This function is available since SDL 2.0.0.
See also
SDL_GetRGBA
SDL_MapRGB
SDL_MapRGBA

◆ SDL_GetRGBA()

DECLSPEC void SDLCALL SDL_GetRGBA ( Uint32  pixel,
const SDL_PixelFormat format,
Uint8 *  r,
Uint8 *  g,
Uint8 *  b,
Uint8 *  a 
)

Get RGBA values from a pixel in the specified format.

This function uses the entire 8-bit [0..255] range when converting color components from pixel formats with less than 8-bits per RGB component (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff, 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).

If the surface has no alpha component, the alpha will be returned as 0xff (100% opaque).

Parameters
pixela pixel value
formatan SDL_PixelFormat structure describing the format of the pixel
ra pointer filled in with the red component
ga pointer filled in with the green component
ba pointer filled in with the blue component
aa pointer filled in with the alpha component
Since
This function is available since SDL 2.0.0.
See also
SDL_GetRGB
SDL_MapRGB
SDL_MapRGBA

◆ SDL_MapRGB()

DECLSPEC Uint32 SDLCALL SDL_MapRGB ( const SDL_PixelFormat format,
Uint8  r,
Uint8  g,
Uint8  b 
)

Map an RGB triple to an opaque pixel value for a given pixel format.

This function maps the RGB color value to the specified pixel format and returns the pixel value best approximating the given RGB color value for the given pixel format.

If the format has a palette (8-bit) the index of the closest matching color in the palette will be returned.

If the specified pixel format has an alpha component it will be returned as all 1 bits (fully opaque).

If the pixel format bpp (color depth) is less than 32-bpp then the unused upper bits of the return value can safely be ignored (e.g., with a 16-bpp format the return value can be assigned to a Uint16, and similarly a Uint8 for an 8-bpp format).

Parameters
formatan SDL_PixelFormat structure describing the pixel format
rthe red component of the pixel in the range 0-255
gthe green component of the pixel in the range 0-255
bthe blue component of the pixel in the range 0-255
Returns
a pixel value
Since
This function is available since SDL 2.0.0.
See also
SDL_GetRGB
SDL_GetRGBA
SDL_MapRGBA

◆ SDL_MapRGBA()

DECLSPEC Uint32 SDLCALL SDL_MapRGBA ( const SDL_PixelFormat format,
Uint8  r,
Uint8  g,
Uint8  b,
Uint8  a 
)

Map an RGBA quadruple to a pixel value for a given pixel format.

This function maps the RGBA color value to the specified pixel format and returns the pixel value best approximating the given RGBA color value for the given pixel format.

If the specified pixel format has no alpha component the alpha value will be ignored (as it will be in formats with a palette).

If the format has a palette (8-bit) the index of the closest matching color in the palette will be returned.

If the pixel format bpp (color depth) is less than 32-bpp then the unused upper bits of the return value can safely be ignored (e.g., with a 16-bpp format the return value can be assigned to a Uint16, and similarly a Uint8 for an 8-bpp format).

Parameters
formatan SDL_PixelFormat structure describing the format of the pixel
rthe red component of the pixel in the range 0-255
gthe green component of the pixel in the range 0-255
bthe blue component of the pixel in the range 0-255
athe alpha component of the pixel in the range 0-255
Returns
a pixel value
Since
This function is available since SDL 2.0.0.
See also
SDL_GetRGB
SDL_GetRGBA
SDL_MapRGB

◆ SDL_MasksToPixelFormatEnum()

DECLSPEC Uint32 SDLCALL SDL_MasksToPixelFormatEnum ( int  bpp,
Uint32  Rmask,
Uint32  Gmask,
Uint32  Bmask,
Uint32  Amask 
)

Convert a bpp value and RGBA masks to an enumerated pixel format.

This will return SDL_PIXELFORMAT_UNKNOWN if the conversion wasn't possible.

Parameters
bppa bits per pixel value; usually 15, 16, or 32
Rmaskthe red mask for the format
Gmaskthe green mask for the format
Bmaskthe blue mask for the format
Amaskthe alpha mask for the format
Returns
one of the SDL_PixelFormatEnum values
Since
This function is available since SDL 2.0.0.
See also
SDL_PixelFormatEnumToMasks

◆ SDL_PixelFormatEnumToMasks()

DECLSPEC SDL_bool SDLCALL SDL_PixelFormatEnumToMasks ( Uint32  format,
int *  bpp,
Uint32 *  Rmask,
Uint32 *  Gmask,
Uint32 *  Bmask,
Uint32 *  Amask 
)

Convert one of the enumerated pixel formats to a bpp value and RGBA masks.

Parameters
formatone of the SDL_PixelFormatEnum values
bppa bits per pixel value; usually 15, 16, or 32
Rmaska pointer filled in with the red mask for the format
Gmaska pointer filled in with the green mask for the format
Bmaska pointer filled in with the blue mask for the format
Amaska pointer filled in with the alpha mask for the format
Returns
SDL_TRUE on success or SDL_FALSE if the conversion wasn't possible; call SDL_GetError() for more information.
Since
This function is available since SDL 2.0.0.
See also
SDL_MasksToPixelFormatEnum

◆ SDL_SetPaletteColors()

DECLSPEC int SDLCALL SDL_SetPaletteColors ( SDL_Palette palette,
const SDL_Color colors,
int  firstcolor,
int  ncolors 
)

Set a range of colors in a palette.

Parameters
palettethe SDL_Palette structure to modify
colorsan array of SDL_Color structures to copy into the palette
firstcolorthe index of the first palette entry to modify
ncolorsthe number of entries to modify
Returns
0 on success or a negative error code if not all of the colors could be set; call SDL_GetError() for more information.
Since
This function is available since SDL 2.0.0.
See also
SDL_AllocPalette
SDL_CreateRGBSurface

◆ SDL_SetPixelFormatPalette()

DECLSPEC int SDLCALL SDL_SetPixelFormatPalette ( SDL_PixelFormat format,
SDL_Palette palette 
)

Set the palette for a pixel format structure.

Parameters
formatthe SDL_PixelFormat structure that will use the palette
palettethe SDL_Palette structure that will be used
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 2.0.0.
See also
SDL_AllocPalette
SDL_FreePalette