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 |
Pixel management. A fully opaque 8-bit alpha value.
Definition at line 48 of file SDL_pixels.h.
#define SDL_ALPHA_OPAQUE_FLOAT 1.0f |
A fully opaque floating point alpha value.
Definition at line 57 of file SDL_pixels.h.
#define SDL_ALPHA_TRANSPARENT 0 |
A fully transparent 8-bit alpha value.
Definition at line 66 of file SDL_pixels.h.
#define SDL_ALPHA_TRANSPARENT_FLOAT 0.0f |
A fully transparent floating point alpha value.
Definition at line 75 of file SDL_pixels.h.
#define SDL_BITSPERPIXEL | ( | X | ) | (SDL_ISPIXELFORMAT_FOURCC(X) ? 0 : (((X) >> 8) & 0xFF)) |
Definition at line 174 of file SDL_pixels.h.
#define SDL_BYTESPERPIXEL | ( | X | ) |
Definition at line 176 of file SDL_pixels.h.
#define SDL_COLORSPACE_RGB_DEFAULT SDL_COLORSPACE_SRGB |
Definition at line 684 of file SDL_pixels.h.
#define SDL_COLORSPACE_YUV_DEFAULT SDL_COLORSPACE_JPEG |
Definition at line 687 of file SDL_pixels.h.
#define SDL_COLORSPACECHROMA | ( | X | ) | (SDL_ChromaLocation)(((X) >> 20) & 0x0F) |
Definition at line 567 of file SDL_pixels.h.
#define SDL_COLORSPACEMATRIX | ( | X | ) | (SDL_MatrixCoefficients)((X) & 0x1F) |
Definition at line 570 of file SDL_pixels.h.
#define SDL_COLORSPACEPRIMARIES | ( | X | ) | (SDL_ColorPrimaries)(((X) >> 10) & 0x1F) |
Definition at line 568 of file SDL_pixels.h.
#define SDL_COLORSPACERANGE | ( | X | ) | (SDL_ColorRange)(((X) >> 24) & 0x0F) |
Definition at line 566 of file SDL_pixels.h.
#define SDL_COLORSPACETRANSFER | ( | X | ) | (SDL_TransferCharacteristics)(((X) >> 5) & 0x1F) |
Definition at line 569 of file SDL_pixels.h.
#define SDL_COLORSPACETYPE | ( | X | ) | (SDL_ColorType)(((X) >> 28) & 0x0F) |
Definition at line 565 of file SDL_pixels.h.
#define SDL_DEFINE_COLORSPACE | ( | type, | |
range, | |||
primaries, | |||
transfer, | |||
matrix, | |||
chroma | |||
) |
Definition at line 561 of file SDL_pixels.h.
#define SDL_DEFINE_PIXELFORMAT | ( | type, | |
order, | |||
layout, | |||
bits, | |||
bytes | |||
) |
Definition at line 166 of file SDL_pixels.h.
#define SDL_DEFINE_PIXELFOURCC | ( | A, | |
B, | |||
C, | |||
D | |||
) | SDL_FOURCC(A, B, C, D) |
Definition at line 164 of file SDL_pixels.h.
#define SDL_ISCOLORSPACE_FULL_RANGE | ( | X | ) | (SDL_COLORSPACERANGE(X) == SDL_COLOR_RANGE_FULL) |
Definition at line 576 of file SDL_pixels.h.
#define SDL_ISCOLORSPACE_LIMITED_RANGE | ( | X | ) | (SDL_COLORSPACERANGE(X) != SDL_COLOR_RANGE_FULL) |
Definition at line 575 of file SDL_pixels.h.
#define SDL_ISCOLORSPACE_MATRIX_BT2020_NCL | ( | X | ) | (SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT2020_NCL) |
Definition at line 574 of file SDL_pixels.h.
#define SDL_ISCOLORSPACE_MATRIX_BT601 | ( | X | ) | (SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT601 || SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT470BG) |
Definition at line 572 of file SDL_pixels.h.
#define SDL_ISCOLORSPACE_MATRIX_BT709 | ( | X | ) | (SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT709) |
Definition at line 573 of file SDL_pixels.h.
#define SDL_ISPIXELFORMAT_10BIT | ( | format | ) |
Definition at line 211 of file SDL_pixels.h.
#define SDL_ISPIXELFORMAT_ALPHA | ( | format | ) |
Definition at line 204 of file SDL_pixels.h.
#define SDL_ISPIXELFORMAT_ARRAY | ( | format | ) |
Definition at line 196 of file SDL_pixels.h.
#define SDL_ISPIXELFORMAT_FLOAT | ( | format | ) |
Definition at line 216 of file SDL_pixels.h.
#define SDL_ISPIXELFORMAT_FOURCC | ( | format | ) | ((format) && (SDL_PIXELFLAG(format) != 1)) |
Definition at line 222 of file SDL_pixels.h.
#define SDL_ISPIXELFORMAT_INDEXED | ( | format | ) |
Definition at line 183 of file SDL_pixels.h.
#define SDL_ISPIXELFORMAT_PACKED | ( | format | ) |
Definition at line 190 of file SDL_pixels.h.
#define SDL_PIXELFLAG | ( | X | ) | (((X) >> 28) & 0x0F) |
Definition at line 170 of file SDL_pixels.h.
#define SDL_PIXELFORMAT_ABGR32 SDL_PIXELFORMAT_ABGR8888 |
Definition at line 401 of file SDL_pixels.h.
#define SDL_PIXELFORMAT_ARGB32 SDL_PIXELFORMAT_ARGB8888 |
Definition at line 399 of file SDL_pixels.h.
#define SDL_PIXELFORMAT_BGRA32 SDL_PIXELFORMAT_BGRA8888 |
Definition at line 400 of file SDL_pixels.h.
#define SDL_PIXELFORMAT_BGRX32 SDL_PIXELFORMAT_BGRX8888 |
Definition at line 404 of file SDL_pixels.h.
#define SDL_PIXELFORMAT_RGBA32 SDL_PIXELFORMAT_RGBA8888 |
Definition at line 398 of file SDL_pixels.h.
#define SDL_PIXELFORMAT_RGBX32 SDL_PIXELFORMAT_RGBX8888 |
Definition at line 402 of file SDL_pixels.h.
#define SDL_PIXELFORMAT_XBGR32 SDL_PIXELFORMAT_XBGR8888 |
Definition at line 405 of file SDL_pixels.h.
#define SDL_PIXELFORMAT_XRGB32 SDL_PIXELFORMAT_XRGB8888 |
Definition at line 403 of file SDL_pixels.h.
#define SDL_PIXELLAYOUT | ( | X | ) | (((X) >> 16) & 0x0F) |
Definition at line 173 of file SDL_pixels.h.
#define SDL_PIXELORDER | ( | X | ) | (((X) >> 20) & 0x0F) |
Definition at line 172 of file SDL_pixels.h.
#define SDL_PIXELTYPE | ( | X | ) | (((X) >> 24) & 0x0F) |
Definition at line 171 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 135 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 105 of file SDL_pixels.h.
enum SDL_ChromaLocation |
Colorspace chroma sample location.
Definition at line 551 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 472 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 459 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 593 of file SDL_pixels.h.
enum SDL_ColorType |
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. Colorspace color type.
Enumerator | |
---|---|
SDL_COLOR_TYPE_UNKNOWN | |
SDL_COLOR_TYPE_RGB | |
SDL_COLOR_TYPE_YCBCR |
Definition at line 446 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 527 of file SDL_pixels.h.
enum SDL_PackedLayout |
Packed component layout.
Definition at line 151 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 117 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 264 of file SDL_pixels.h.
enum SDL_PixelType |
Pixel type.
Definition at line 82 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 497 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.