SDL 3.0
|
#include <SDL3/SDL_stdinc.h>
#include <SDL3/SDL_error.h>
#include <SDL3/SDL_endian.h>
#include <SDL3/SDL_begin_code.h>
#include <SDL3/SDL_close_code.h>
Go to the source code of this file.
Data Structures | |
struct | SDL_Color |
struct | SDL_FColor |
struct | SDL_Palette |
struct | SDL_PixelFormatDetails |
#define SDL_ALPHA_OPAQUE 255 |
SDL offers facilities for pixel management.
Largely these facilities deal with pixel format: what does this set of bits represent?
If you mostly want to think of a pixel as some combination of red, green, blue, and maybe alpha intensities, this is all pretty straightforward, and in many cases, is enough information to build a perfectly fine game.
However, the actual definition of a pixel is more complex than that:
Pixels are a representation of a color in a particular color space.
The first characteristic of a color space is the color type. SDL understands two different color types, RGB and YCbCr, or in SDL also referred to as YUV.
RGB colors consist of red, green, and blue channels of color that are added together to represent the colors we see on the screen.
https://en.wikipedia.org/wiki/RGB_color_model
YCbCr colors represent colors as a Y luma brightness component and red and blue chroma color offsets. This color representation takes advantage of the fact that the human eye is more sensitive to brightness than the color in an image. The Cb and Cr components are often compressed and have lower resolution than the luma component.
https://en.wikipedia.org/wiki/YCbCr
When the color information in YCbCr is compressed, the Y pixels are left at full resolution and each Cr and Cb pixel represents an average of the color information in a block of Y pixels. The chroma location determines where in that block of pixels the color information is coming from.
The color range defines how much of the pixel to use when converting a pixel into a color on the display. When the full color range is used, the entire numeric range of the pixel bits is significant. When narrow color range is used, for historical reasons, the pixel uses only a portion of the numeric range to represent colors.
The color primaries and white point are a definition of the colors in the color space relative to the standard XYZ color space.
https://en.wikipedia.org/wiki/CIE_1931_color_space
The transfer characteristic, or opto-electrical transfer function (OETF), is the way a color is converted from mathematically linear space into a non-linear output signals.
https://en.wikipedia.org/wiki/Rec._709#Transfer_characteristics
The matrix coefficients are used to convert between YCbCr and RGB colors. A fully opaque 8-bit alpha value.
Definition at line 100 of file SDL_pixels.h.
#define SDL_ALPHA_OPAQUE_FLOAT 1.0f |
A fully opaque floating point alpha value.
Definition at line 109 of file SDL_pixels.h.
#define SDL_ALPHA_TRANSPARENT 0 |
A fully transparent 8-bit alpha value.
Definition at line 118 of file SDL_pixels.h.
#define SDL_ALPHA_TRANSPARENT_FLOAT 0.0f |
A fully transparent floating point alpha value.
Definition at line 127 of file SDL_pixels.h.
#define SDL_BITSPERPIXEL | ( | format | ) | (SDL_ISPIXELFORMAT_FOURCC(format) ? 0 : (((format) >> 8) & 0xFF)) |
A macro to determine an SDL_PixelFormat's bits per pixel.
Note that this macro double-evaluates its parameter, so do not use expressions with side-effects here.
FourCC formats will report zero here, as it rarely makes sense to measure them per-pixel.
format | an SDL_PixelFormat to check. |
format
.\threadsafety It is safe to call this macro from any thread.
Definition at line 340 of file SDL_pixels.h.
#define SDL_BYTESPERPIXEL | ( | format | ) |
A macro to determine an SDL_PixelFormat's bytes per pixel.
Note that this macro double-evaluates its parameter, so do not use expressions with side-effects here.
FourCC formats do their best here, but many of them don't have a meaningful measurement of bytes per pixel.
format | an SDL_PixelFormat to check. |
format
.\threadsafety It is safe to call this macro from any thread.
Definition at line 361 of file SDL_pixels.h.
#define SDL_COLORSPACECHROMA | ( | cspace | ) | (SDL_ChromaLocation)(((cspace) >> 20) & 0x0F) |
A macro to retrieve the chroma sample location of an SDL_Colorspace.
cspace | an SDL_Colorspace to check. |
cspace
.\threadsafety It is safe to call this macro from any thread.
Definition at line 890 of file SDL_pixels.h.
#define SDL_COLORSPACEMATRIX | ( | cspace | ) | (SDL_MatrixCoefficients)((cspace) & 0x1F) |
A macro to retrieve the matrix coefficients of an SDL_Colorspace.
cspace | an SDL_Colorspace to check. |
cspace
.\threadsafety It is safe to call this macro from any thread.
Definition at line 926 of file SDL_pixels.h.
#define SDL_COLORSPACEPRIMARIES | ( | cspace | ) | (SDL_ColorPrimaries)(((cspace) >> 10) & 0x1F) |
A macro to retrieve the primaries of an SDL_Colorspace.
cspace | an SDL_Colorspace to check. |
cspace
.\threadsafety It is safe to call this macro from any thread.
Definition at line 902 of file SDL_pixels.h.
#define SDL_COLORSPACERANGE | ( | cspace | ) | (SDL_ColorRange)(((cspace) >> 24) & 0x0F) |
A macro to retrieve the range of an SDL_Colorspace.
cspace | an SDL_Colorspace to check. |
cspace
.\threadsafety It is safe to call this macro from any thread.
Definition at line 878 of file SDL_pixels.h.
#define SDL_COLORSPACETRANSFER | ( | cspace | ) | (SDL_TransferCharacteristics)(((cspace) >> 5) & 0x1F) |
A macro to retrieve the transfer characteristics of an SDL_Colorspace.
cspace | an SDL_Colorspace to check. |
cspace
.\threadsafety It is safe to call this macro from any thread.
Definition at line 914 of file SDL_pixels.h.
#define SDL_COLORSPACETYPE | ( | cspace | ) | (SDL_ColorType)(((cspace) >> 28) & 0x0F) |
A macro to retrieve the type of an SDL_Colorspace.
cspace | an SDL_Colorspace to check. |
cspace
.\threadsafety It is safe to call this macro from any thread.
Definition at line 866 of file SDL_pixels.h.
#define SDL_DEFINE_COLORSPACE | ( | type, | |
range, | |||
primaries, | |||
transfer, | |||
matrix, | |||
chroma | |||
) |
A macro for defining custom SDL_Colorspace formats.
For example, defining SDL_COLORSPACE_SRGB looks like this:
type | the type of the new format, probably an SDL_ColorType value. |
range | the range of the new format, probably a SDL_ColorRange value. |
primaries | the primaries of the new format, probably an SDL_ColorPrimaries value. |
transfer | the transfer characteristics of the new format, probably an SDL_TransferCharacteristics value. |
matrix | the matrix coefficients of the new format, probably an SDL_MatrixCoefficients value. |
chroma | the chroma sample location of the new format, probably an SDL_ChromaLocation value. |
\threadsafety It is safe to call this macro from any thread.
Definition at line 852 of file SDL_pixels.h.
#define SDL_DEFINE_PIXELFORMAT | ( | type, | |
order, | |||
layout, | |||
bits, | |||
bytes | |||
) |
A macro for defining custom non-FourCC pixel formats.
For example, defining SDL_PIXELFORMAT_RGBA8888 looks like this:
type | the type of the new format, probably a SDL_PixelType value. |
order | the order of the new format, probably a SDL_BitmapOrder, SDL_PackedOrder, or SDL_ArrayOrder value. |
layout | the layout of the new format, probably an SDL_PackedLayout value or zero. |
bits | the number of bits per pixel of the new format. |
bytes | the number of bytes per pixel of the new format. |
\threadsafety It is safe to call this macro from any thread.
Definition at line 259 of file SDL_pixels.h.
#define SDL_DEFINE_PIXELFOURCC | ( | A, | |
B, | |||
C, | |||
D | |||
) | SDL_FOURCC(A, B, C, D) |
A macro for defining custom FourCC pixel formats.
For example, defining SDL_PIXELFORMAT_YV12 looks like this:
A | the first character of the FourCC code. |
B | the second character of the FourCC code. |
C | the third character of the FourCC code. |
D | the fourth character of the FourCC code. |
\threadsafety It is safe to call this macro from any thread.
Definition at line 235 of file SDL_pixels.h.
#define SDL_ISCOLORSPACE_FULL_RANGE | ( | cspace | ) | (SDL_COLORSPACERANGE(cspace) == SDL_COLOR_RANGE_FULL) |
A macro to determine if an SDL_Colorspace has a full range.
cspace | an SDL_Colorspace to check. |
\threadsafety It is safe to call this macro from any thread.
Definition at line 991 of file SDL_pixels.h.
#define SDL_ISCOLORSPACE_LIMITED_RANGE | ( | cspace | ) | (SDL_COLORSPACERANGE(cspace) != SDL_COLOR_RANGE_FULL) |
A macro to determine if an SDL_Colorspace has a limited range.
cspace | an SDL_Colorspace to check. |
\threadsafety It is safe to call this macro from any thread.
Definition at line 979 of file SDL_pixels.h.
#define SDL_ISCOLORSPACE_MATRIX_BT2020_NCL | ( | cspace | ) | (SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT2020_NCL) |
A macro to determine if an SDL_Colorspace uses BT2020_NCL matrix coefficients.
cspace | an SDL_Colorspace to check. |
\threadsafety It is safe to call this macro from any thread.
Definition at line 967 of file SDL_pixels.h.
#define SDL_ISCOLORSPACE_MATRIX_BT601 | ( | cspace | ) | (SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT601 || SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT470BG) |
A macro to determine if an SDL_Colorspace uses BT601 (or BT470BG) matrix coefficients.
Note that this macro double-evaluates its parameter, so do not use expressions with side-effects here.
cspace | an SDL_Colorspace to check. |
\threadsafety It is safe to call this macro from any thread.
Definition at line 942 of file SDL_pixels.h.
#define SDL_ISCOLORSPACE_MATRIX_BT709 | ( | cspace | ) | (SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT709) |
A macro to determine if an SDL_Colorspace uses BT709 matrix coefficients.
cspace | an SDL_Colorspace to check. |
\threadsafety It is safe to call this macro from any thread.
Definition at line 954 of file SDL_pixels.h.
#define SDL_ISPIXELFORMAT_10BIT | ( | format | ) |
A macro to determine if an SDL_PixelFormat is a 10-bit format.
Note that this macro double-evaluates its parameter, so do not use expressions with side-effects here.
format | an SDL_PixelFormat to check. |
\threadsafety It is safe to call this macro from any thread.
Definition at line 442 of file SDL_pixels.h.
#define SDL_ISPIXELFORMAT_ALPHA | ( | format | ) |
A macro to determine if an SDL_PixelFormat has an alpha channel.
Note that this macro double-evaluates its parameter, so do not use expressions with side-effects here.
format | an SDL_PixelFormat to check. |
\threadsafety It is safe to call this macro from any thread.
Definition at line 478 of file SDL_pixels.h.
#define SDL_ISPIXELFORMAT_ARRAY | ( | format | ) |
A macro to determine if an SDL_PixelFormat is an array format.
Note that this macro double-evaluates its parameter, so do not use expressions with side-effects here.
format | an SDL_PixelFormat to check. |
\threadsafety It is safe to call this macro from any thread.
Definition at line 421 of file SDL_pixels.h.
#define SDL_ISPIXELFORMAT_FLOAT | ( | format | ) |
A macro to determine if an SDL_PixelFormat is a floating point format.
Note that this macro double-evaluates its parameter, so do not use expressions with side-effects here.
format | an SDL_PixelFormat to check. |
\threadsafety It is safe to call this macro from any thread.
Definition at line 460 of file SDL_pixels.h.
#define SDL_ISPIXELFORMAT_FOURCC | ( | format | ) |
A macro to determine if an SDL_PixelFormat is a "FourCC" format.
This covers custom and other unusual formats.
Note that this macro double-evaluates its parameter, so do not use expressions with side-effects here.
format | an SDL_PixelFormat to check. |
\threadsafety It is safe to call this macro from any thread.
Definition at line 506 of file SDL_pixels.h.
#define SDL_ISPIXELFORMAT_INDEXED | ( | format | ) |
A macro to determine if an SDL_PixelFormat is an indexed format.
Note that this macro double-evaluates its parameter, so do not use expressions with side-effects here.
format | an SDL_PixelFormat to check. |
\threadsafety It is safe to call this macro from any thread.
Definition at line 382 of file SDL_pixels.h.
#define SDL_ISPIXELFORMAT_PACKED | ( | format | ) |
A macro to determine if an SDL_PixelFormat is a packed format.
Note that this macro double-evaluates its parameter, so do not use expressions with side-effects here.
format | an SDL_PixelFormat to check. |
\threadsafety It is safe to call this macro from any thread.
Definition at line 402 of file SDL_pixels.h.
#define SDL_PIXELFLAG | ( | format | ) | (((format) >> 28) & 0x0F) |
A macro to retrieve the flags of an SDL_PixelFormat.
This macro is generally not needed directly by an app, which should use specific tests, like SDL_ISPIXELFORMAT_FOURCC, instead.
format | an SDL_PixelFormat to check. |
format
.\threadsafety It is safe to call this macro from any thread.
Definition at line 276 of file SDL_pixels.h.
#define SDL_PIXELLAYOUT | ( | format | ) | (((format) >> 16) & 0x0F) |
A macro to retrieve the layout of an SDL_PixelFormat.
This is usually a value from the SDL_PackedLayout enumeration, or zero if a layout doesn't make sense for the format type.
format | an SDL_PixelFormat to check. |
format
.\threadsafety It is safe to call this macro from any thread.
Definition at line 320 of file SDL_pixels.h.
#define SDL_PIXELORDER | ( | format | ) | (((format) >> 20) & 0x0F) |
A macro to retrieve the order of an SDL_PixelFormat.
This is usually a value from the SDL_BitmapOrder, SDL_PackedOrder, or SDL_ArrayOrder enumerations, depending on the format type.
format | an SDL_PixelFormat to check. |
format
.\threadsafety It is safe to call this macro from any thread.
Definition at line 305 of file SDL_pixels.h.
#define SDL_PIXELTYPE | ( | format | ) | (((format) >> 24) & 0x0F) |
A macro to retrieve the type of an SDL_PixelFormat.
This is usually a value from the SDL_PixelType enumeration.
format | an SDL_PixelFormat to check. |
format
.\threadsafety It is safe to call this macro from any thread.
Definition at line 290 of file SDL_pixels.h.
enum SDL_ArrayOrder |
Array component order, low byte -> high byte.
Enumerator | |
---|---|
SDL_ARRAYORDER_NONE | |
SDL_ARRAYORDER_RGB | |
SDL_ARRAYORDER_RGBA | |
SDL_ARRAYORDER_ARGB | |
SDL_ARRAYORDER_BGR | |
SDL_ARRAYORDER_BGRA | |
SDL_ARRAYORDER_ABGR |
Definition at line 187 of file SDL_pixels.h.
enum SDL_BitmapOrder |
Bitmap pixel order, high bit -> low bit.
Enumerator | |
---|---|
SDL_BITMAPORDER_NONE | |
SDL_BITMAPORDER_4321 | |
SDL_BITMAPORDER_1234 |
Definition at line 157 of file SDL_pixels.h.
enum SDL_ChromaLocation |
Colorspace chroma sample location.
Definition at line 811 of file SDL_pixels.h.
enum SDL_ColorPrimaries |
Colorspace color primaries, as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en
Definition at line 732 of file SDL_pixels.h.
enum SDL_ColorRange |
Colorspace color range, as described by https://www.itu.int/rec/R-REC-BT.2100-2-201807-I/en
Definition at line 719 of file SDL_pixels.h.
enum SDL_Colorspace |
Colorspace definitions.
Since similar colorspaces may vary in their details (matrix, transfer function, etc.), this is not an exhaustive list, but rather a representative sample of the kinds of colorspaces supported in SDL.
Definition at line 1008 of file SDL_pixels.h.
enum SDL_ColorType |
Colorspace color type.
Enumerator | |
---|---|
SDL_COLOR_TYPE_UNKNOWN | |
SDL_COLOR_TYPE_RGB | |
SDL_COLOR_TYPE_YCBCR |
Definition at line 706 of file SDL_pixels.h.
Colorspace matrix coefficients.
These are as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en
Definition at line 787 of file SDL_pixels.h.
enum SDL_PackedLayout |
Packed component layout.
Definition at line 203 of file SDL_pixels.h.
enum SDL_PackedOrder |
Packed component order, high bit -> low bit.
Enumerator | |
---|---|
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 |
Definition at line 169 of file SDL_pixels.h.
enum SDL_PixelFormat |
Pixel format.
SDL's pixel formats have the following naming convention:
The 32-bit byte-array encodings such as RGBA32 are aliases for the appropriate 8888 encoding for the current platform. For example, RGBA32 is an alias for ABGR8888 on little-endian CPUs like x86, or an alias for RGBA8888 on big-endian CPUs.
Definition at line 548 of file SDL_pixels.h.
enum SDL_PixelType |
Pixel type.
Definition at line 134 of file SDL_pixels.h.
Colorspace transfer characteristics.
These are as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en
Definition at line 757 of file SDL_pixels.h.
|
extern |
Create a palette structure with the specified number of color entries.
The palette entries are initialized to white.
ncolors | represents the number of color entries in the color palette. |
\threadsafety It is safe to call this function from any thread.
|
extern |
Free a palette created with SDL_CreatePalette().
palette | the SDL_Palette structure to be freed. |
\threadsafety It is safe to call this function from any thread, as long as the palette is not modified or destroyed in another thread.
|
extern |
Convert one of the enumerated pixel formats to a bpp value and RGBA masks.
format | one of the SDL_PixelFormat values. |
bpp | a bits per pixel value; usually 15, 16, or 32. |
Rmask | a pointer filled in with the red mask for the format. |
Gmask | a pointer filled in with the green mask for the format. |
Bmask | a pointer filled in with the blue mask for the format. |
Amask | a pointer filled in with the alpha mask for the format. |
\threadsafety It is safe to call this function from any thread.
|
extern |
Create an SDL_PixelFormatDetails 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.
format | one of the SDL_PixelFormat values. |
\threadsafety It is safe to call this function from any thread.
|
extern |
Convert a bpp value and RGBA masks to an enumerated pixel format.
This will return SDL_PIXELFORMAT_UNKNOWN
if the conversion wasn't possible.
bpp | a bits per pixel value; usually 15, 16, or 32. |
Rmask | the red mask for the format. |
Gmask | the green mask for the format. |
Bmask | the blue mask for the format. |
Amask | the alpha mask for the format. |
\threadsafety It is safe to call this function from any thread.
|
extern |
Get the human readable name of a pixel format.
format | the pixel format to query. |
\threadsafety It is safe to call this function from any thread.
|
extern |
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]).
pixel | a pixel value. |
format | a pointer to SDL_PixelFormatDetails describing the pixel format. |
palette | an optional palette for indexed formats, may be NULL. |
r | a pointer filled in with the red component, may be NULL. |
g | a pointer filled in with the green component, may be NULL. |
b | a pointer filled in with the blue component, may be NULL. |
\threadsafety It is safe to call this function from any thread, as long as the palette is not modified.
|
extern |
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).
pixel | a pixel value. |
format | a pointer to SDL_PixelFormatDetails describing the pixel format. |
palette | an optional palette for indexed formats, may be NULL. |
r | a pointer filled in with the red component, may be NULL. |
g | a pointer filled in with the green component, may be NULL. |
b | a pointer filled in with the blue component, may be NULL. |
a | a pointer filled in with the alpha component, may be NULL. |
\threadsafety It is safe to call this function from any thread, as long as the palette is not modified.
|
extern |
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).
format | a pointer to SDL_PixelFormatDetails describing the pixel format. |
palette | an optional palette for indexed formats, may be NULL. |
r | the red component of the pixel in the range 0-255. |
g | the green component of the pixel in the range 0-255. |
b | the blue component of the pixel in the range 0-255. |
\threadsafety It is safe to call this function from any thread, as long as the palette is not modified.
|
extern |
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).
format | a pointer to SDL_PixelFormatDetails describing the pixel format. |
palette | an optional palette for indexed formats, may be NULL. |
r | the red component of the pixel in the range 0-255. |
g | the green component of the pixel in the range 0-255. |
b | the blue component of the pixel in the range 0-255. |
a | the alpha component of the pixel in the range 0-255. |
\threadsafety It is safe to call this function from any thread, as long as the palette is not modified.
|
extern |
Set a range of colors in a palette.
palette | the SDL_Palette structure to modify. |
colors | an array of SDL_Color structures to copy into the palette. |
firstcolor | the index of the first palette entry to modify. |
ncolors | the number of entries to modify. |
\threadsafety It is safe to call this function from any thread, as long as the palette is not modified or destroyed in another thread.