SDL 3.0
|
#include <SDL3/SDL_stdinc.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_PixelFormat |
Header for the enumerated pixel format definitions.
SDL's pixel formats have the following naming convention:
* Names with a list of components and a single bit count, such as RGB24 and ABGR32, define a platform-independent encoding into bytes in the order specified. For example, in RGB24 data, each pixel is encoded in 3 bytes (red, green, blue) in that order, and in ABGR32 data, each pixel is encoded in 4 bytes (alpha, blue, green, red) in that order. Use these names if the property of a format that is important to you is the order of the bytes in memory or on disk. * Names with a bit count per component, such as ARGB8888 and XRGB1555, are "packed" into an appropriately-sized integer in the platform's native endianness. For example, ARGB8888 is a sequence of 32-bit integers; in each integer, the most significant bits are alpha, and the least significant bits are blue. On a little-endian CPU such as x86, the least significant bits of each integer are arranged first in memory, but on a big-endian CPU such as s390x, the most significant bits are arranged first. Use these names if the property of a format that is important to you is the meaning of each bit position within a native-endianness integer. * In indexed formats such as INDEX4LSB, each pixel is represented by encoding an index into the palette into the indicated number of bits, with multiple pixels packed into each byte if appropriate. In LSB formats, the first (leftmost) pixel is stored in the least-significant bits of the byte; in MSB formats, it's stored in the most-significant bits. INDEX8 does not need LSB/MSB variants, because each pixel exactly fills one byte.
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 in file SDL_pixels.h.
#define SDL_ALPHA_OPAQUE 255 |
Definition at line 82 of file SDL_pixels.h.
#define SDL_ALPHA_TRANSPARENT 0 |
Definition at line 83 of file SDL_pixels.h.
#define SDL_BITSPERPIXEL | ( | X | ) | (((X) >> 8) & 0xFF) |
Definition at line 163 of file SDL_pixels.h.
#define SDL_BYTESPERPIXEL | ( | X | ) |
Definition at line 164 of file SDL_pixels.h.
#define SDL_COLORSPACECHROMA | ( | X | ) | (SDL_ChromaLocation)(((X) >> 20) & 0x0F) |
Definition at line 553 of file SDL_pixels.h.
#define SDL_COLORSPACEMATRIX | ( | X | ) | (SDL_MatrixCoefficients)((X) & 0x1F) |
Definition at line 556 of file SDL_pixels.h.
#define SDL_COLORSPACEPRIMARIES | ( | X | ) | (SDL_ColorPrimaries)(((X) >> 10) & 0x1F) |
Definition at line 554 of file SDL_pixels.h.
#define SDL_COLORSPACERANGE | ( | X | ) | (SDL_ColorRange)(((X) >> 24) & 0x0F) |
Definition at line 552 of file SDL_pixels.h.
#define SDL_COLORSPACETRANSFER | ( | X | ) | (SDL_TransferCharacteristics)(((X) >> 5) & 0x1F) |
Definition at line 555 of file SDL_pixels.h.
#define SDL_COLORSPACETYPE | ( | X | ) | (SDL_ColorType)(((X) >> 28) & 0x0F) |
Definition at line 551 of file SDL_pixels.h.
#define SDL_Colour SDL_Color |
Definition at line 627 of file SDL_pixels.h.
#define SDL_DEFINE_COLORSPACE | ( | type, | |
range, | |||
primaries, | |||
transfer, | |||
matrix, | |||
chroma | |||
) |
Definition at line 547 of file SDL_pixels.h.
#define SDL_DEFINE_PIXELFORMAT | ( | type, | |
order, | |||
layout, | |||
bits, | |||
bytes | |||
) |
Definition at line 155 of file SDL_pixels.h.
#define SDL_DEFINE_PIXELFOURCC | ( | A, | |
B, | |||
C, | |||
D | |||
) | SDL_FOURCC(A, B, C, D) |
Definition at line 153 of file SDL_pixels.h.
#define SDL_FColour SDL_FColor |
Definition at line 640 of file SDL_pixels.h.
#define SDL_ISPIXELFORMAT_10BIT | ( | format | ) |
Definition at line 198 of file SDL_pixels.h.
#define SDL_ISPIXELFORMAT_ALPHA | ( | format | ) |
Definition at line 191 of file SDL_pixels.h.
#define SDL_ISPIXELFORMAT_ARRAY | ( | format | ) |
Definition at line 183 of file SDL_pixels.h.
#define SDL_ISPIXELFORMAT_FLOAT | ( | format | ) |
Definition at line 203 of file SDL_pixels.h.
#define SDL_ISPIXELFORMAT_FOURCC | ( | format | ) | ((format) && (SDL_PIXELFLAG(format) != 1)) |
Definition at line 209 of file SDL_pixels.h.
#define SDL_ISPIXELFORMAT_INDEXED | ( | format | ) |
Definition at line 170 of file SDL_pixels.h.
#define SDL_ISPIXELFORMAT_PACKED | ( | format | ) |
Definition at line 177 of file SDL_pixels.h.
#define SDL_PIXELFLAG | ( | X | ) | (((X) >> 28) & 0x0F) |
Definition at line 159 of file SDL_pixels.h.
#define SDL_PIXELLAYOUT | ( | X | ) | (((X) >> 16) & 0x0F) |
Definition at line 162 of file SDL_pixels.h.
#define SDL_PIXELORDER | ( | X | ) | (((X) >> 20) & 0x0F) |
Definition at line 161 of file SDL_pixels.h.
#define SDL_PIXELTYPE | ( | X | ) | (((X) >> 24) & 0x0F) |
Definition at line 160 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 128 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 106 of file SDL_pixels.h.
enum SDL_ChromaLocation |
The chroma sample location
Definition at line 537 of file SDL_pixels.h.
enum SDL_ColorPrimaries |
The color primaries, as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en
Definition at line 468 of file SDL_pixels.h.
enum SDL_ColorRange |
The color range, as described by https://www.itu.int/rec/R-REC-BT.2100-2-201807-I/en
Definition at line 458 of file SDL_pixels.h.
enum SDL_Colorspace |
Definition at line 558 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. The color type
Enumerator | |
---|---|
SDL_COLOR_TYPE_UNKNOWN | |
SDL_COLOR_TYPE_RGB | |
SDL_COLOR_TYPE_YCBCR |
Definition at line 448 of file SDL_pixels.h.
The matrix coefficients, as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en
Definition at line 515 of file SDL_pixels.h.
enum SDL_PackedLayout |
Packed component layout.
Definition at line 140 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 114 of file SDL_pixels.h.
enum SDL_PixelFormatEnum |
Definition at line 213 of file SDL_pixels.h.
enum SDL_PixelType |
Pixel type.
Definition at line 87 of file SDL_pixels.h.
The transfer characteristics, as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en
Definition at line 489 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 |
|
extern |
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.
pixel_format | one of the SDL_PixelFormatEnum values |
|
extern |
Free a palette created with SDL_CreatePalette().
palette | the SDL_Palette structure to be freed |
|
extern |
Free an SDL_PixelFormat structure allocated by SDL_CreatePixelFormat().
format | the SDL_PixelFormat structure to free |
|
extern |
Convert one of the enumerated pixel formats to a bpp value and RGBA masks.
format | one of the SDL_PixelFormatEnum 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 |
|
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 |
|
extern |
Get the human readable name of a pixel format.
format | the pixel format to query |
SDL_PIXELFORMAT_UNKNOWN
if the format isn't recognized.
|
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 | an SDL_PixelFormat structure describing the format of the pixel |
r | a pointer filled in with the red component |
g | a pointer filled in with the green component |
b | a pointer filled in with the blue component |
|
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 | an SDL_PixelFormat structure describing the format of the pixel |
r | a pointer filled in with the red component |
g | a pointer filled in with the green component |
b | a pointer filled in with the blue component |
a | a pointer filled in with the alpha component |
|
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 | an SDL_PixelFormat structure describing the pixel format |
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 |
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 | an SDL_PixelFormat structure describing the format of the pixel |
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 |
|
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 |
|
extern |
Set the palette for a pixel format structure.
format | the SDL_PixelFormat structure that will use the palette |
palette | the SDL_Palette structure that will be used |