Atlas - SDL_pixels.h
Home / ext / SDL / include / SDL3 Lines: 1 | Size: 59712 bytes [Download] [Show on GitHub] [Search similar files] [Raw] [Raw (proxy)][FILE BEGIN]1/* 2 Simple DirectMedia Layer 3 Copyright (C) 1997-2025 Sam Lantinga <[email protected]> 4 5 This software is provided 'as-is', without any express or implied 6 warranty. In no event will the authors be held liable for any damages 7 arising from the use of this software. 8 9 Permission is granted to anyone to use this software for any purpose, 10 including commercial applications, and to alter it and redistribute it 11 freely, subject to the following restrictions: 12 13 1. The origin of this software must not be misrepresented; you must not 14 claim that you wrote the original software. If you use this software 15 in a product, an acknowledgment in the product documentation would be 16 appreciated but is not required. 17 2. Altered source versions must be plainly marked as such, and must not be 18 misrepresented as being the original software. 19 3. This notice may not be removed or altered from any source distribution. 20*/ 21 22/** 23 * # CategoryPixels 24 * 25 * SDL offers facilities for pixel management. 26 * 27 * Largely these facilities deal with pixel _format_: what does this set of 28 * bits represent? 29 * 30 * If you mostly want to think of a pixel as some combination of red, green, 31 * blue, and maybe alpha intensities, this is all pretty straightforward, and 32 * in many cases, is enough information to build a perfectly fine game. 33 * 34 * However, the actual definition of a pixel is more complex than that: 35 * 36 * Pixels are a representation of a color in a particular color space. 37 * 38 * The first characteristic of a color space is the color type. SDL 39 * understands two different color types, RGB and YCbCr, or in SDL also 40 * referred to as YUV. 41 * 42 * RGB colors consist of red, green, and blue channels of color that are added 43 * together to represent the colors we see on the screen. 44 * 45 * https://en.wikipedia.org/wiki/RGB_color_model 46 * 47 * YCbCr colors represent colors as a Y luma brightness component and red and 48 * blue chroma color offsets. This color representation takes advantage of the 49 * fact that the human eye is more sensitive to brightness than the color in 50 * an image. The Cb and Cr components are often compressed and have lower 51 * resolution than the luma component. 52 * 53 * https://en.wikipedia.org/wiki/YCbCr 54 * 55 * When the color information in YCbCr is compressed, the Y pixels are left at 56 * full resolution and each Cr and Cb pixel represents an average of the color 57 * information in a block of Y pixels. The chroma location determines where in 58 * that block of pixels the color information is coming from. 59 * 60 * The color range defines how much of the pixel to use when converting a 61 * pixel into a color on the display. When the full color range is used, the 62 * entire numeric range of the pixel bits is significant. When narrow color 63 * range is used, for historical reasons, the pixel uses only a portion of the 64 * numeric range to represent colors. 65 * 66 * The color primaries and white point are a definition of the colors in the 67 * color space relative to the standard XYZ color space. 68 * 69 * https://en.wikipedia.org/wiki/CIE_1931_color_space 70 * 71 * The transfer characteristic, or opto-electrical transfer function (OETF), 72 * is the way a color is converted from mathematically linear space into a 73 * non-linear output signals. 74 * 75 * https://en.wikipedia.org/wiki/Rec._709#Transfer_characteristics 76 * 77 * The matrix coefficients are used to convert between YCbCr and RGB colors. 78 */ 79 80#ifndef SDL_pixels_h_ 81#define SDL_pixels_h_ 82 83#include <SDL3/SDL_stdinc.h> 84#include <SDL3/SDL_error.h> 85#include <SDL3/SDL_endian.h> 86 87#include <SDL3/SDL_begin_code.h> 88/* Set up for C function definitions, even when using C++ */ 89#ifdef __cplusplus 90extern "C" { 91#endif 92 93/** 94 * A fully opaque 8-bit alpha value. 95 * 96 * \since This macro is available since SDL 3.2.0. 97 * 98 * \sa SDL_ALPHA_TRANSPARENT 99 */ 100#define SDL_ALPHA_OPAQUE 255 101 102/** 103 * A fully opaque floating point alpha value. 104 * 105 * \since This macro is available since SDL 3.2.0. 106 * 107 * \sa SDL_ALPHA_TRANSPARENT_FLOAT 108 */ 109#define SDL_ALPHA_OPAQUE_FLOAT 1.0f 110 111/** 112 * A fully transparent 8-bit alpha value. 113 * 114 * \since This macro is available since SDL 3.2.0. 115 * 116 * \sa SDL_ALPHA_OPAQUE 117 */ 118#define SDL_ALPHA_TRANSPARENT 0 119 120/** 121 * A fully transparent floating point alpha value. 122 * 123 * \since This macro is available since SDL 3.2.0. 124 * 125 * \sa SDL_ALPHA_OPAQUE_FLOAT 126 */ 127#define SDL_ALPHA_TRANSPARENT_FLOAT 0.0f 128 129/** 130 * Pixel type. 131 * 132 * \since This enum is available since SDL 3.2.0. 133 */ 134typedef enum SDL_PixelType 135{ 136 SDL_PIXELTYPE_UNKNOWN, 137 SDL_PIXELTYPE_INDEX1, 138 SDL_PIXELTYPE_INDEX4, 139 SDL_PIXELTYPE_INDEX8, 140 SDL_PIXELTYPE_PACKED8, 141 SDL_PIXELTYPE_PACKED16, 142 SDL_PIXELTYPE_PACKED32, 143 SDL_PIXELTYPE_ARRAYU8, 144 SDL_PIXELTYPE_ARRAYU16, 145 SDL_PIXELTYPE_ARRAYU32, 146 SDL_PIXELTYPE_ARRAYF16, 147 SDL_PIXELTYPE_ARRAYF32, 148 /* appended at the end for compatibility with sdl2-compat: */ 149 SDL_PIXELTYPE_INDEX2 150} SDL_PixelType; 151 152/** 153 * Bitmap pixel order, high bit -> low bit. 154 * 155 * \since This enum is available since SDL 3.2.0. 156 */ 157typedef enum SDL_BitmapOrder 158{ 159 SDL_BITMAPORDER_NONE, 160 SDL_BITMAPORDER_4321, 161 SDL_BITMAPORDER_1234 162} SDL_BitmapOrder; 163 164/** 165 * Packed component order, high bit -> low bit. 166 * 167 * \since This enum is available since SDL 3.2.0. 168 */ 169typedef enum SDL_PackedOrder 170{ 171 SDL_PACKEDORDER_NONE, 172 SDL_PACKEDORDER_XRGB, 173 SDL_PACKEDORDER_RGBX, 174 SDL_PACKEDORDER_ARGB, 175 SDL_PACKEDORDER_RGBA, 176 SDL_PACKEDORDER_XBGR, 177 SDL_PACKEDORDER_BGRX, 178 SDL_PACKEDORDER_ABGR, 179 SDL_PACKEDORDER_BGRA 180} SDL_PackedOrder; 181 182/** 183 * Array component order, low byte -> high byte. 184 * 185 * \since This enum is available since SDL 3.2.0. 186 */ 187typedef enum SDL_ArrayOrder 188{ 189 SDL_ARRAYORDER_NONE, 190 SDL_ARRAYORDER_RGB, 191 SDL_ARRAYORDER_RGBA, 192 SDL_ARRAYORDER_ARGB, 193 SDL_ARRAYORDER_BGR, 194 SDL_ARRAYORDER_BGRA, 195 SDL_ARRAYORDER_ABGR 196} SDL_ArrayOrder; 197 198/** 199 * Packed component layout. 200 * 201 * \since This enum is available since SDL 3.2.0. 202 */ 203typedef enum SDL_PackedLayout 204{ 205 SDL_PACKEDLAYOUT_NONE, 206 SDL_PACKEDLAYOUT_332, 207 SDL_PACKEDLAYOUT_4444, 208 SDL_PACKEDLAYOUT_1555, 209 SDL_PACKEDLAYOUT_5551, 210 SDL_PACKEDLAYOUT_565, 211 SDL_PACKEDLAYOUT_8888, 212 SDL_PACKEDLAYOUT_2101010, 213 SDL_PACKEDLAYOUT_1010102 214} SDL_PackedLayout; 215 216/** 217 * A macro for defining custom FourCC pixel formats. 218 * 219 * For example, defining SDL_PIXELFORMAT_YV12 looks like this: 220 * 221 * ```c 222 * SDL_DEFINE_PIXELFOURCC('Y', 'V', '1', '2') 223 * ``` 224 * 225 * \param A the first character of the FourCC code. 226 * \param B the second character of the FourCC code. 227 * \param C the third character of the FourCC code. 228 * \param D the fourth character of the FourCC code. 229 * \returns a format value in the style of SDL_PixelFormat. 230 * 231 * \threadsafety It is safe to call this macro from any thread. 232 * 233 * \since This macro is available since SDL 3.2.0. 234 */ 235#define SDL_DEFINE_PIXELFOURCC(A, B, C, D) SDL_FOURCC(A, B, C, D) 236 237/** 238 * A macro for defining custom non-FourCC pixel formats. 239 * 240 * For example, defining SDL_PIXELFORMAT_RGBA8888 looks like this: 241 * 242 * ```c 243 * SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_RGBA, SDL_PACKEDLAYOUT_8888, 32, 4) 244 * ``` 245 * 246 * \param type the type of the new format, probably a SDL_PixelType value. 247 * \param order the order of the new format, probably a SDL_BitmapOrder, 248 * SDL_PackedOrder, or SDL_ArrayOrder value. 249 * \param layout the layout of the new format, probably an SDL_PackedLayout 250 * value or zero. 251 * \param bits the number of bits per pixel of the new format. 252 * \param bytes the number of bytes per pixel of the new format. 253 * \returns a format value in the style of SDL_PixelFormat. 254 * 255 * \threadsafety It is safe to call this macro from any thread. 256 * 257 * \since This macro is available since SDL 3.2.0. 258 */ 259#define SDL_DEFINE_PIXELFORMAT(type, order, layout, bits, bytes) \ 260 ((1 << 28) | ((type) << 24) | ((order) << 20) | ((layout) << 16) | \ 261 ((bits) << 8) | ((bytes) << 0)) 262 263/** 264 * A macro to retrieve the flags of an SDL_PixelFormat. 265 * 266 * This macro is generally not needed directly by an app, which should use 267 * specific tests, like SDL_ISPIXELFORMAT_FOURCC, instead. 268 * 269 * \param format an SDL_PixelFormat to check. 270 * \returns the flags of `format`. 271 * 272 * \threadsafety It is safe to call this macro from any thread. 273 * 274 * \since This macro is available since SDL 3.2.0. 275 */ 276#define SDL_PIXELFLAG(format) (((format) >> 28) & 0x0F) 277 278/** 279 * A macro to retrieve the type of an SDL_PixelFormat. 280 * 281 * This is usually a value from the SDL_PixelType enumeration. 282 * 283 * \param format an SDL_PixelFormat to check. 284 * \returns the type of `format`. 285 * 286 * \threadsafety It is safe to call this macro from any thread. 287 * 288 * \since This macro is available since SDL 3.2.0. 289 */ 290#define SDL_PIXELTYPE(format) (((format) >> 24) & 0x0F) 291 292/** 293 * A macro to retrieve the order of an SDL_PixelFormat. 294 * 295 * This is usually a value from the SDL_BitmapOrder, SDL_PackedOrder, or 296 * SDL_ArrayOrder enumerations, depending on the format type. 297 * 298 * \param format an SDL_PixelFormat to check. 299 * \returns the order of `format`. 300 * 301 * \threadsafety It is safe to call this macro from any thread. 302 * 303 * \since This macro is available since SDL 3.2.0. 304 */ 305#define SDL_PIXELORDER(format) (((format) >> 20) & 0x0F) 306 307/** 308 * A macro to retrieve the layout of an SDL_PixelFormat. 309 * 310 * This is usually a value from the SDL_PackedLayout enumeration, or zero if a 311 * layout doesn't make sense for the format type. 312 * 313 * \param format an SDL_PixelFormat to check. 314 * \returns the layout of `format`. 315 * 316 * \threadsafety It is safe to call this macro from any thread. 317 * 318 * \since This macro is available since SDL 3.2.0. 319 */ 320#define SDL_PIXELLAYOUT(format) (((format) >> 16) & 0x0F) 321 322/** 323 * A macro to determine an SDL_PixelFormat's bits per pixel. 324 * 325 * Note that this macro double-evaluates its parameter, so do not use 326 * expressions with side-effects here. 327 * 328 * FourCC formats will report zero here, as it rarely makes sense to measure 329 * them per-pixel. 330 * 331 * \param format an SDL_PixelFormat to check. 332 * \returns the bits-per-pixel of `format`. 333 * 334 * \threadsafety It is safe to call this macro from any thread. 335 * 336 * \since This macro is available since SDL 3.2.0. 337 * 338 * \sa SDL_BYTESPERPIXEL 339 */ 340#define SDL_BITSPERPIXEL(format) \ 341 (SDL_ISPIXELFORMAT_FOURCC(format) ? 0 : (((format) >> 8) & 0xFF)) 342 343/** 344 * A macro to determine an SDL_PixelFormat's bytes per pixel. 345 * 346 * Note that this macro double-evaluates its parameter, so do not use 347 * expressions with side-effects here. 348 * 349 * FourCC formats do their best here, but many of them don't have a meaningful 350 * measurement of bytes per pixel. 351 * 352 * \param format an SDL_PixelFormat to check. 353 * \returns the bytes-per-pixel of `format`. 354 * 355 * \threadsafety It is safe to call this macro from any thread. 356 * 357 * \since This macro is available since SDL 3.2.0. 358 * 359 * \sa SDL_BITSPERPIXEL 360 */ 361#define SDL_BYTESPERPIXEL(format) \ 362 (SDL_ISPIXELFORMAT_FOURCC(format) ? \ 363 ((((format) == SDL_PIXELFORMAT_YUY2) || \ 364 ((format) == SDL_PIXELFORMAT_UYVY) || \ 365 ((format) == SDL_PIXELFORMAT_YVYU) || \ 366 ((format) == SDL_PIXELFORMAT_P010)) ? 2 : 1) : (((format) >> 0) & 0xFF)) 367 368 369/** 370 * A macro to determine if an SDL_PixelFormat is an indexed format. 371 * 372 * Note that this macro double-evaluates its parameter, so do not use 373 * expressions with side-effects here. 374 * 375 * \param format an SDL_PixelFormat to check. 376 * \returns true if the format is indexed, false otherwise. 377 * 378 * \threadsafety It is safe to call this macro from any thread. 379 * 380 * \since This macro is available since SDL 3.2.0. 381 */ 382#define SDL_ISPIXELFORMAT_INDEXED(format) \ 383 (!SDL_ISPIXELFORMAT_FOURCC(format) && \ 384 ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX1) || \ 385 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX2) || \ 386 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX4) || \ 387 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX8))) 388 389/** 390 * A macro to determine if an SDL_PixelFormat is a packed format. 391 * 392 * Note that this macro double-evaluates its parameter, so do not use 393 * expressions with side-effects here. 394 * 395 * \param format an SDL_PixelFormat to check. 396 * \returns true if the format is packed, false otherwise. 397 * 398 * \threadsafety It is safe to call this macro from any thread. 399 * 400 * \since This macro is available since SDL 3.2.0. 401 */ 402#define SDL_ISPIXELFORMAT_PACKED(format) \ 403 (!SDL_ISPIXELFORMAT_FOURCC(format) && \ 404 ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED8) || \ 405 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED16) || \ 406 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED32))) 407 408/** 409 * A macro to determine if an SDL_PixelFormat is an array format. 410 * 411 * Note that this macro double-evaluates its parameter, so do not use 412 * expressions with side-effects here. 413 * 414 * \param format an SDL_PixelFormat to check. 415 * \returns true if the format is an array, false otherwise. 416 * 417 * \threadsafety It is safe to call this macro from any thread. 418 * 419 * \since This macro is available since SDL 3.2.0. 420 */ 421#define SDL_ISPIXELFORMAT_ARRAY(format) \ 422 (!SDL_ISPIXELFORMAT_FOURCC(format) && \ 423 ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYU8) || \ 424 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYU16) || \ 425 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYU32) || \ 426 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF16) || \ 427 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF32))) 428 429/** 430 * A macro to determine if an SDL_PixelFormat is a 10-bit format. 431 * 432 * Note that this macro double-evaluates its parameter, so do not use 433 * expressions with side-effects here. 434 * 435 * \param format an SDL_PixelFormat to check. 436 * \returns true if the format is 10-bit, false otherwise. 437 * 438 * \threadsafety It is safe to call this macro from any thread. 439 * 440 * \since This macro is available since SDL 3.2.0. 441 */ 442#define SDL_ISPIXELFORMAT_10BIT(format) \ 443 (!SDL_ISPIXELFORMAT_FOURCC(format) && \ 444 ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED32) && \ 445 (SDL_PIXELLAYOUT(format) == SDL_PACKEDLAYOUT_2101010))) 446 447/** 448 * A macro to determine if an SDL_PixelFormat is a floating point format. 449 * 450 * Note that this macro double-evaluates its parameter, so do not use 451 * expressions with side-effects here. 452 * 453 * \param format an SDL_PixelFormat to check. 454 * \returns true if the format is a floating point, false otherwise. 455 * 456 * \threadsafety It is safe to call this macro from any thread. 457 * 458 * \since This macro is available since SDL 3.2.0. 459 */ 460#define SDL_ISPIXELFORMAT_FLOAT(format) \ 461 (!SDL_ISPIXELFORMAT_FOURCC(format) && \ 462 ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF16) || \ 463 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF32))) 464 465/** 466 * A macro to determine if an SDL_PixelFormat has an alpha channel. 467 * 468 * Note that this macro double-evaluates its parameter, so do not use 469 * expressions with side-effects here. 470 * 471 * \param format an SDL_PixelFormat to check. 472 * \returns true if the format has alpha, false otherwise. 473 * 474 * \threadsafety It is safe to call this macro from any thread. 475 * 476 * \since This macro is available since SDL 3.2.0. 477 */ 478#define SDL_ISPIXELFORMAT_ALPHA(format) \ 479 ((SDL_ISPIXELFORMAT_PACKED(format) && \ 480 ((SDL_PIXELORDER(format) == SDL_PACKEDORDER_ARGB) || \ 481 (SDL_PIXELORDER(format) == SDL_PACKEDORDER_RGBA) || \ 482 (SDL_PIXELORDER(format) == SDL_PACKEDORDER_ABGR) || \ 483 (SDL_PIXELORDER(format) == SDL_PACKEDORDER_BGRA))) || \ 484 (SDL_ISPIXELFORMAT_ARRAY(format) && \ 485 ((SDL_PIXELORDER(format) == SDL_ARRAYORDER_ARGB) || \ 486 (SDL_PIXELORDER(format) == SDL_ARRAYORDER_RGBA) || \ 487 (SDL_PIXELORDER(format) == SDL_ARRAYORDER_ABGR) || \ 488 (SDL_PIXELORDER(format) == SDL_ARRAYORDER_BGRA)))) 489 490 491/** 492 * A macro to determine if an SDL_PixelFormat is a "FourCC" format. 493 * 494 * This covers custom and other unusual formats. 495 * 496 * Note that this macro double-evaluates its parameter, so do not use 497 * expressions with side-effects here. 498 * 499 * \param format an SDL_PixelFormat to check. 500 * \returns true if the format has alpha, false otherwise. 501 * 502 * \threadsafety It is safe to call this macro from any thread. 503 * 504 * \since This macro is available since SDL 3.2.0. 505 */ 506#define SDL_ISPIXELFORMAT_FOURCC(format) /* The flag is set to 1 because 0x1? is not in the printable ASCII range */ \ 507 ((format) && (SDL_PIXELFLAG(format) != 1)) 508 509/* Note: If you modify this enum, update SDL_GetPixelFormatName() */ 510 511/** 512 * Pixel format. 513 * 514 * SDL's pixel formats have the following naming convention: 515 * 516 * - Names with a list of components and a single bit count, such as RGB24 and 517 * ABGR32, define a platform-independent encoding into bytes in the order 518 * specified. For example, in RGB24 data, each pixel is encoded in 3 bytes 519 * (red, green, blue) in that order, and in ABGR32 data, each pixel is 520 * encoded in 4 bytes (alpha, blue, green, red) in that order. Use these 521 * names if the property of a format that is important to you is the order 522 * of the bytes in memory or on disk. 523 * - Names with a bit count per component, such as ARGB8888 and XRGB1555, are 524 * "packed" into an appropriately-sized integer in the platform's native 525 * endianness. For example, ARGB8888 is a sequence of 32-bit integers; in 526 * each integer, the most significant bits are alpha, and the least 527 * significant bits are blue. On a little-endian CPU such as x86, the least 528 * significant bits of each integer are arranged first in memory, but on a 529 * big-endian CPU such as s390x, the most significant bits are arranged 530 * first. Use these names if the property of a format that is important to 531 * you is the meaning of each bit position within a native-endianness 532 * integer. 533 * - In indexed formats such as INDEX4LSB, each pixel is represented by 534 * encoding an index into the palette into the indicated number of bits, 535 * with multiple pixels packed into each byte if appropriate. In LSB 536 * formats, the first (leftmost) pixel is stored in the least-significant 537 * bits of the byte; in MSB formats, it's stored in the most-significant 538 * bits. INDEX8 does not need LSB/MSB variants, because each pixel exactly 539 * fills one byte. 540 * 541 * The 32-bit byte-array encodings such as RGBA32 are aliases for the 542 * appropriate 8888 encoding for the current platform. For example, RGBA32 is 543 * an alias for ABGR8888 on little-endian CPUs like x86, or an alias for 544 * RGBA8888 on big-endian CPUs. 545 * 546 * \since This enum is available since SDL 3.2.0. 547 */ 548typedef enum SDL_PixelFormat 549{ 550 SDL_PIXELFORMAT_UNKNOWN = 0, 551 SDL_PIXELFORMAT_INDEX1LSB = 0x11100100u, 552 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX1, SDL_BITMAPORDER_4321, 0, 1, 0), */ 553 SDL_PIXELFORMAT_INDEX1MSB = 0x11200100u, 554 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX1, SDL_BITMAPORDER_1234, 0, 1, 0), */ 555 SDL_PIXELFORMAT_INDEX2LSB = 0x1c100200u, 556 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX2, SDL_BITMAPORDER_4321, 0, 2, 0), */ 557 SDL_PIXELFORMAT_INDEX2MSB = 0x1c200200u, 558 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX2, SDL_BITMAPORDER_1234, 0, 2, 0), */ 559 SDL_PIXELFORMAT_INDEX4LSB = 0x12100400u, 560 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX4, SDL_BITMAPORDER_4321, 0, 4, 0), */ 561 SDL_PIXELFORMAT_INDEX4MSB = 0x12200400u, 562 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX4, SDL_BITMAPORDER_1234, 0, 4, 0), */ 563 SDL_PIXELFORMAT_INDEX8 = 0x13000801u, 564 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX8, 0, 0, 8, 1), */ 565 SDL_PIXELFORMAT_RGB332 = 0x14110801u, 566 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED8, SDL_PACKEDORDER_XRGB, SDL_PACKEDLAYOUT_332, 8, 1), */ 567 SDL_PIXELFORMAT_XRGB4444 = 0x15120c02u, 568 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB, SDL_PACKEDLAYOUT_4444, 12, 2), */ 569 SDL_PIXELFORMAT_XBGR4444 = 0x15520c02u, 570 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XBGR, SDL_PACKEDLAYOUT_4444, 12, 2), */ 571 SDL_PIXELFORMAT_XRGB1555 = 0x15130f02u, 572 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB, SDL_PACKEDLAYOUT_1555, 15, 2), */ 573 SDL_PIXELFORMAT_XBGR1555 = 0x15530f02u, 574 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XBGR, SDL_PACKEDLAYOUT_1555, 15, 2), */ 575 SDL_PIXELFORMAT_ARGB4444 = 0x15321002u, 576 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ARGB, SDL_PACKEDLAYOUT_4444, 16, 2), */ 577 SDL_PIXELFORMAT_RGBA4444 = 0x15421002u, 578 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_RGBA, SDL_PACKEDLAYOUT_4444, 16, 2), */ 579 SDL_PIXELFORMAT_ABGR4444 = 0x15721002u, 580 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ABGR, SDL_PACKEDLAYOUT_4444, 16, 2), */ 581 SDL_PIXELFORMAT_BGRA4444 = 0x15821002u, 582 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_BGRA, SDL_PACKEDLAYOUT_4444, 16, 2), */ 583 SDL_PIXELFORMAT_ARGB1555 = 0x15331002u, 584 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ARGB, SDL_PACKEDLAYOUT_1555, 16, 2), */ 585 SDL_PIXELFORMAT_RGBA5551 = 0x15441002u, 586 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_RGBA, SDL_PACKEDLAYOUT_5551, 16, 2), */ 587 SDL_PIXELFORMAT_ABGR1555 = 0x15731002u, 588 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ABGR, SDL_PACKEDLAYOUT_1555, 16, 2), */ 589 SDL_PIXELFORMAT_BGRA5551 = 0x15841002u, 590 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_BGRA, SDL_PACKEDLAYOUT_5551, 16, 2), */ 591 SDL_PIXELFORMAT_RGB565 = 0x15151002u, 592 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB, SDL_PACKEDLAYOUT_565, 16, 2), */ 593 SDL_PIXELFORMAT_BGR565 = 0x15551002u, 594 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XBGR, SDL_PACKEDLAYOUT_565, 16, 2), */ 595 SDL_PIXELFORMAT_RGB24 = 0x17101803u, 596 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU8, SDL_ARRAYORDER_RGB, 0, 24, 3), */ 597 SDL_PIXELFORMAT_BGR24 = 0x17401803u, 598 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU8, SDL_ARRAYORDER_BGR, 0, 24, 3), */ 599 SDL_PIXELFORMAT_XRGB8888 = 0x16161804u, 600 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XRGB, SDL_PACKEDLAYOUT_8888, 24, 4), */ 601 SDL_PIXELFORMAT_RGBX8888 = 0x16261804u, 602 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_RGBX, SDL_PACKEDLAYOUT_8888, 24, 4), */ 603 SDL_PIXELFORMAT_XBGR8888 = 0x16561804u, 604 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XBGR, SDL_PACKEDLAYOUT_8888, 24, 4), */ 605 SDL_PIXELFORMAT_BGRX8888 = 0x16661804u, 606 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_BGRX, SDL_PACKEDLAYOUT_8888, 24, 4), */ 607 SDL_PIXELFORMAT_ARGB8888 = 0x16362004u, 608 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ARGB, SDL_PACKEDLAYOUT_8888, 32, 4), */ 609 SDL_PIXELFORMAT_RGBA8888 = 0x16462004u, 610 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_RGBA, SDL_PACKEDLAYOUT_8888, 32, 4), */ 611 SDL_PIXELFORMAT_ABGR8888 = 0x16762004u, 612 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ABGR, SDL_PACKEDLAYOUT_8888, 32, 4), */ 613 SDL_PIXELFORMAT_BGRA8888 = 0x16862004u, 614 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_BGRA, SDL_PACKEDLAYOUT_8888, 32, 4), */ 615 SDL_PIXELFORMAT_XRGB2101010 = 0x16172004u, 616 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XRGB, SDL_PACKEDLAYOUT_2101010, 32, 4), */ 617 SDL_PIXELFORMAT_XBGR2101010 = 0x16572004u, 618 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XBGR, SDL_PACKEDLAYOUT_2101010, 32, 4), */ 619 SDL_PIXELFORMAT_ARGB2101010 = 0x16372004u, 620 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ARGB, SDL_PACKEDLAYOUT_2101010, 32, 4), */ 621 SDL_PIXELFORMAT_ABGR2101010 = 0x16772004u, 622 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ABGR, SDL_PACKEDLAYOUT_2101010, 32, 4), */ 623 SDL_PIXELFORMAT_RGB48 = 0x18103006u, 624 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU16, SDL_ARRAYORDER_RGB, 0, 48, 6), */ 625 SDL_PIXELFORMAT_BGR48 = 0x18403006u, 626 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU16, SDL_ARRAYORDER_BGR, 0, 48, 6), */ 627 SDL_PIXELFORMAT_RGBA64 = 0x18204008u, 628 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU16, SDL_ARRAYORDER_RGBA, 0, 64, 8), */ 629 SDL_PIXELFORMAT_ARGB64 = 0x18304008u, 630 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU16, SDL_ARRAYORDER_ARGB, 0, 64, 8), */ 631 SDL_PIXELFORMAT_BGRA64 = 0x18504008u, 632 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU16, SDL_ARRAYORDER_BGRA, 0, 64, 8), */ 633 SDL_PIXELFORMAT_ABGR64 = 0x18604008u, 634 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU16, SDL_ARRAYORDER_ABGR, 0, 64, 8), */ 635 SDL_PIXELFORMAT_RGB48_FLOAT = 0x1a103006u, 636 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF16, SDL_ARRAYORDER_RGB, 0, 48, 6), */ 637 SDL_PIXELFORMAT_BGR48_FLOAT = 0x1a403006u, 638 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF16, SDL_ARRAYORDER_BGR, 0, 48, 6), */ 639 SDL_PIXELFORMAT_RGBA64_FLOAT = 0x1a204008u, 640 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF16, SDL_ARRAYORDER_RGBA, 0, 64, 8), */ 641 SDL_PIXELFORMAT_ARGB64_FLOAT = 0x1a304008u, 642 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF16, SDL_ARRAYORDER_ARGB, 0, 64, 8), */ 643 SDL_PIXELFORMAT_BGRA64_FLOAT = 0x1a504008u, 644 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF16, SDL_ARRAYORDER_BGRA, 0, 64, 8), */ 645 SDL_PIXELFORMAT_ABGR64_FLOAT = 0x1a604008u, 646 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF16, SDL_ARRAYORDER_ABGR, 0, 64, 8), */ 647 SDL_PIXELFORMAT_RGB96_FLOAT = 0x1b10600cu, 648 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF32, SDL_ARRAYORDER_RGB, 0, 96, 12), */ 649 SDL_PIXELFORMAT_BGR96_FLOAT = 0x1b40600cu, 650 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF32, SDL_ARRAYORDER_BGR, 0, 96, 12), */ 651 SDL_PIXELFORMAT_RGBA128_FLOAT = 0x1b208010u, 652 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF32, SDL_ARRAYORDER_RGBA, 0, 128, 16), */ 653 SDL_PIXELFORMAT_ARGB128_FLOAT = 0x1b308010u, 654 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF32, SDL_ARRAYORDER_ARGB, 0, 128, 16), */ 655 SDL_PIXELFORMAT_BGRA128_FLOAT = 0x1b508010u, 656 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF32, SDL_ARRAYORDER_BGRA, 0, 128, 16), */ 657 SDL_PIXELFORMAT_ABGR128_FLOAT = 0x1b608010u, 658 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF32, SDL_ARRAYORDER_ABGR, 0, 128, 16), */ 659 660 SDL_PIXELFORMAT_YV12 = 0x32315659u, /**< Planar mode: Y + V + U (3 planes) */ 661 /* SDL_DEFINE_PIXELFOURCC('Y', 'V', '1', '2'), */ 662 SDL_PIXELFORMAT_IYUV = 0x56555949u, /**< Planar mode: Y + U + V (3 planes) */ 663 /* SDL_DEFINE_PIXELFOURCC('I', 'Y', 'U', 'V'), */ 664 SDL_PIXELFORMAT_YUY2 = 0x32595559u, /**< Packed mode: Y0+U0+Y1+V0 (1 plane) */ 665 /* SDL_DEFINE_PIXELFOURCC('Y', 'U', 'Y', '2'), */ 666 SDL_PIXELFORMAT_UYVY = 0x59565955u, /**< Packed mode: U0+Y0+V0+Y1 (1 plane) */ 667 /* SDL_DEFINE_PIXELFOURCC('U', 'Y', 'V', 'Y'), */ 668 SDL_PIXELFORMAT_YVYU = 0x55595659u, /**< Packed mode: Y0+V0+Y1+U0 (1 plane) */ 669 /* SDL_DEFINE_PIXELFOURCC('Y', 'V', 'Y', 'U'), */ 670 SDL_PIXELFORMAT_NV12 = 0x3231564eu, /**< Planar mode: Y + U/V interleaved (2 planes) */ 671 /* SDL_DEFINE_PIXELFOURCC('N', 'V', '1', '2'), */ 672 SDL_PIXELFORMAT_NV21 = 0x3132564eu, /**< Planar mode: Y + V/U interleaved (2 planes) */ 673 /* SDL_DEFINE_PIXELFOURCC('N', 'V', '2', '1'), */ 674 SDL_PIXELFORMAT_P010 = 0x30313050u, /**< Planar mode: Y + U/V interleaved (2 planes) */ 675 /* SDL_DEFINE_PIXELFOURCC('P', '0', '1', '0'), */ 676 SDL_PIXELFORMAT_EXTERNAL_OES = 0x2053454fu, /**< Android video texture format */ 677 /* SDL_DEFINE_PIXELFOURCC('O', 'E', 'S', ' ') */ 678 679 SDL_PIXELFORMAT_MJPG = 0x47504a4du, /**< Motion JPEG */ 680 /* SDL_DEFINE_PIXELFOURCC('M', 'J', 'P', 'G') */ 681 682 /* Aliases for RGBA byte arrays of color data, for the current platform */ 683 #if SDL_BYTEORDER == SDL_BIG_ENDIAN 684 SDL_PIXELFORMAT_RGBA32 = SDL_PIXELFORMAT_RGBA8888, 685 SDL_PIXELFORMAT_ARGB32 = SDL_PIXELFORMAT_ARGB8888, 686 SDL_PIXELFORMAT_BGRA32 = SDL_PIXELFORMAT_BGRA8888, 687 SDL_PIXELFORMAT_ABGR32 = SDL_PIXELFORMAT_ABGR8888, 688 SDL_PIXELFORMAT_RGBX32 = SDL_PIXELFORMAT_RGBX8888, 689 SDL_PIXELFORMAT_XRGB32 = SDL_PIXELFORMAT_XRGB8888, 690 SDL_PIXELFORMAT_BGRX32 = SDL_PIXELFORMAT_BGRX8888, 691 SDL_PIXELFORMAT_XBGR32 = SDL_PIXELFORMAT_XBGR8888 692 #else 693 SDL_PIXELFORMAT_RGBA32 = SDL_PIXELFORMAT_ABGR8888, 694 SDL_PIXELFORMAT_ARGB32 = SDL_PIXELFORMAT_BGRA8888, 695 SDL_PIXELFORMAT_BGRA32 = SDL_PIXELFORMAT_ARGB8888, 696 SDL_PIXELFORMAT_ABGR32 = SDL_PIXELFORMAT_RGBA8888, 697 SDL_PIXELFORMAT_RGBX32 = SDL_PIXELFORMAT_XBGR8888, 698 SDL_PIXELFORMAT_XRGB32 = SDL_PIXELFORMAT_BGRX8888, 699 SDL_PIXELFORMAT_BGRX32 = SDL_PIXELFORMAT_XRGB8888, 700 SDL_PIXELFORMAT_XBGR32 = SDL_PIXELFORMAT_RGBX8888 701 #endif 702} SDL_PixelFormat; 703 704/** 705 * Colorspace color type. 706 * 707 * \since This enum is available since SDL 3.2.0. 708 */ 709typedef enum SDL_ColorType 710{ 711 SDL_COLOR_TYPE_UNKNOWN = 0, 712 SDL_COLOR_TYPE_RGB = 1, 713 SDL_COLOR_TYPE_YCBCR = 2 714} SDL_ColorType; 715 716/** 717 * Colorspace color range, as described by 718 * https://www.itu.int/rec/R-REC-BT.2100-2-201807-I/en 719 * 720 * \since This enum is available since SDL 3.2.0. 721 */ 722typedef enum SDL_ColorRange 723{ 724 SDL_COLOR_RANGE_UNKNOWN = 0, 725 SDL_COLOR_RANGE_LIMITED = 1, /**< Narrow range, e.g. 16-235 for 8-bit RGB and luma, and 16-240 for 8-bit chroma */ 726 SDL_COLOR_RANGE_FULL = 2 /**< Full range, e.g. 0-255 for 8-bit RGB and luma, and 1-255 for 8-bit chroma */ 727} SDL_ColorRange; 728 729/** 730 * Colorspace color primaries, as described by 731 * https://www.itu.int/rec/T-REC-H.273-201612-S/en 732 * 733 * \since This enum is available since SDL 3.2.0. 734 */ 735typedef enum SDL_ColorPrimaries 736{ 737 SDL_COLOR_PRIMARIES_UNKNOWN = 0, 738 SDL_COLOR_PRIMARIES_BT709 = 1, /**< ITU-R BT.709-6 */ 739 SDL_COLOR_PRIMARIES_UNSPECIFIED = 2, 740 SDL_COLOR_PRIMARIES_BT470M = 4, /**< ITU-R BT.470-6 System M */ 741 SDL_COLOR_PRIMARIES_BT470BG = 5, /**< ITU-R BT.470-6 System B, G / ITU-R BT.601-7 625 */ 742 SDL_COLOR_PRIMARIES_BT601 = 6, /**< ITU-R BT.601-7 525, SMPTE 170M */ 743 SDL_COLOR_PRIMARIES_SMPTE240 = 7, /**< SMPTE 240M, functionally the same as SDL_COLOR_PRIMARIES_BT601 */ 744 SDL_COLOR_PRIMARIES_GENERIC_FILM = 8, /**< Generic film (color filters using Illuminant C) */ 745 SDL_COLOR_PRIMARIES_BT2020 = 9, /**< ITU-R BT.2020-2 / ITU-R BT.2100-0 */ 746 SDL_COLOR_PRIMARIES_XYZ = 10, /**< SMPTE ST 428-1 */ 747 SDL_COLOR_PRIMARIES_SMPTE431 = 11, /**< SMPTE RP 431-2 */ 748 SDL_COLOR_PRIMARIES_SMPTE432 = 12, /**< SMPTE EG 432-1 / DCI P3 */ 749 SDL_COLOR_PRIMARIES_EBU3213 = 22, /**< EBU Tech. 3213-E */ 750 SDL_COLOR_PRIMARIES_CUSTOM = 31 751} SDL_ColorPrimaries; 752 753/** 754 * Colorspace transfer characteristics. 755 * 756 * These are as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en 757 * 758 * \since This enum is available since SDL 3.2.0. 759 */ 760typedef enum SDL_TransferCharacteristics 761{ 762 SDL_TRANSFER_CHARACTERISTICS_UNKNOWN = 0, 763 SDL_TRANSFER_CHARACTERISTICS_BT709 = 1, /**< Rec. ITU-R BT.709-6 / ITU-R BT1361 */ 764 SDL_TRANSFER_CHARACTERISTICS_UNSPECIFIED = 2, 765 SDL_TRANSFER_CHARACTERISTICS_GAMMA22 = 4, /**< ITU-R BT.470-6 System M / ITU-R BT1700 625 PAL & SECAM */ 766 SDL_TRANSFER_CHARACTERISTICS_GAMMA28 = 5, /**< ITU-R BT.470-6 System B, G */ 767 SDL_TRANSFER_CHARACTERISTICS_BT601 = 6, /**< SMPTE ST 170M / ITU-R BT.601-7 525 or 625 */ 768 SDL_TRANSFER_CHARACTERISTICS_SMPTE240 = 7, /**< SMPTE ST 240M */ 769 SDL_TRANSFER_CHARACTERISTICS_LINEAR = 8, 770 SDL_TRANSFER_CHARACTERISTICS_LOG100 = 9, 771 SDL_TRANSFER_CHARACTERISTICS_LOG100_SQRT10 = 10, 772 SDL_TRANSFER_CHARACTERISTICS_IEC61966 = 11, /**< IEC 61966-2-4 */ 773 SDL_TRANSFER_CHARACTERISTICS_BT1361 = 12, /**< ITU-R BT1361 Extended Colour Gamut */ 774 SDL_TRANSFER_CHARACTERISTICS_SRGB = 13, /**< IEC 61966-2-1 (sRGB or sYCC) */ 775 SDL_TRANSFER_CHARACTERISTICS_BT2020_10BIT = 14, /**< ITU-R BT2020 for 10-bit system */ 776 SDL_TRANSFER_CHARACTERISTICS_BT2020_12BIT = 15, /**< ITU-R BT2020 for 12-bit system */ 777 SDL_TRANSFER_CHARACTERISTICS_PQ = 16, /**< SMPTE ST 2084 for 10-, 12-, 14- and 16-bit systems */ 778 SDL_TRANSFER_CHARACTERISTICS_SMPTE428 = 17, /**< SMPTE ST 428-1 */ 779 SDL_TRANSFER_CHARACTERISTICS_HLG = 18, /**< ARIB STD-B67, known as "hybrid log-gamma" (HLG) */ 780 SDL_TRANSFER_CHARACTERISTICS_CUSTOM = 31 781} SDL_TransferCharacteristics; 782 783/** 784 * Colorspace matrix coefficients. 785 * 786 * These are as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en 787 * 788 * \since This enum is available since SDL 3.2.0. 789 */ 790typedef enum SDL_MatrixCoefficients 791{ 792 SDL_MATRIX_COEFFICIENTS_IDENTITY = 0, 793 SDL_MATRIX_COEFFICIENTS_BT709 = 1, /**< ITU-R BT.709-6 */ 794 SDL_MATRIX_COEFFICIENTS_UNSPECIFIED = 2, 795 SDL_MATRIX_COEFFICIENTS_FCC = 4, /**< US FCC Title 47 */ 796 SDL_MATRIX_COEFFICIENTS_BT470BG = 5, /**< ITU-R BT.470-6 System B, G / ITU-R BT.601-7 625, functionally the same as SDL_MATRIX_COEFFICIENTS_BT601 */ 797 SDL_MATRIX_COEFFICIENTS_BT601 = 6, /**< ITU-R BT.601-7 525 */ 798 SDL_MATRIX_COEFFICIENTS_SMPTE240 = 7, /**< SMPTE 240M */ 799 SDL_MATRIX_COEFFICIENTS_YCGCO = 8, 800 SDL_MATRIX_COEFFICIENTS_BT2020_NCL = 9, /**< ITU-R BT.2020-2 non-constant luminance */ 801 SDL_MATRIX_COEFFICIENTS_BT2020_CL = 10, /**< ITU-R BT.2020-2 constant luminance */ 802 SDL_MATRIX_COEFFICIENTS_SMPTE2085 = 11, /**< SMPTE ST 2085 */ 803 SDL_MATRIX_COEFFICIENTS_CHROMA_DERIVED_NCL = 12, 804 SDL_MATRIX_COEFFICIENTS_CHROMA_DERIVED_CL = 13, 805 SDL_MATRIX_COEFFICIENTS_ICTCP = 14, /**< ITU-R BT.2100-0 ICTCP */ 806 SDL_MATRIX_COEFFICIENTS_CUSTOM = 31 807} SDL_MatrixCoefficients; 808 809/** 810 * Colorspace chroma sample location. 811 * 812 * \since This enum is available since SDL 3.2.0. 813 */ 814typedef enum SDL_ChromaLocation 815{ 816 SDL_CHROMA_LOCATION_NONE = 0, /**< RGB, no chroma sampling */ 817 SDL_CHROMA_LOCATION_LEFT = 1, /**< In MPEG-2, MPEG-4, and AVC, Cb and Cr are taken on midpoint of the left-edge of the 2x2 square. In other words, they have the same horizontal location as the top-left pixel, but is shifted one-half pixel down vertically. */ 818 SDL_CHROMA_LOCATION_CENTER = 2, /**< In JPEG/JFIF, H.261, and MPEG-1, Cb and Cr are taken at the center of the 2x2 square. In other words, they are offset one-half pixel to the right and one-half pixel down compared to the top-left pixel. */ 819 SDL_CHROMA_LOCATION_TOPLEFT = 3 /**< In HEVC for BT.2020 and BT.2100 content (in particular on Blu-rays), Cb and Cr are sampled at the same location as the group's top-left Y pixel ("co-sited", "co-located"). */ 820} SDL_ChromaLocation; 821 822 823/* Colorspace definition */ 824 825/** 826 * A macro for defining custom SDL_Colorspace formats. 827 * 828 * For example, defining SDL_COLORSPACE_SRGB looks like this: 829 * 830 * ```c 831 * SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_RGB, 832 * SDL_COLOR_RANGE_FULL, 833 * SDL_COLOR_PRIMARIES_BT709, 834 * SDL_TRANSFER_CHARACTERISTICS_SRGB, 835 * SDL_MATRIX_COEFFICIENTS_IDENTITY, 836 * SDL_CHROMA_LOCATION_NONE) 837 * ``` 838 * 839 * \param type the type of the new format, probably an SDL_ColorType value. 840 * \param range the range of the new format, probably a SDL_ColorRange value. 841 * \param primaries the primaries of the new format, probably an 842 * SDL_ColorPrimaries value. 843 * \param transfer the transfer characteristics of the new format, probably an 844 * SDL_TransferCharacteristics value. 845 * \param matrix the matrix coefficients of the new format, probably an 846 * SDL_MatrixCoefficients value. 847 * \param chroma the chroma sample location of the new format, probably an 848 * SDL_ChromaLocation value. 849 * \returns a format value in the style of SDL_Colorspace. 850 * 851 * \threadsafety It is safe to call this macro from any thread. 852 * 853 * \since This macro is available since SDL 3.2.0. 854 */ 855#define SDL_DEFINE_COLORSPACE(type, range, primaries, transfer, matrix, chroma) \ 856 (((Uint32)(type) << 28) | ((Uint32)(range) << 24) | ((Uint32)(chroma) << 20) | \ 857 ((Uint32)(primaries) << 10) | ((Uint32)(transfer) << 5) | ((Uint32)(matrix) << 0)) 858 859/** 860 * A macro to retrieve the type of an SDL_Colorspace. 861 * 862 * \param cspace an SDL_Colorspace to check. 863 * \returns the SDL_ColorType for `cspace`. 864 * 865 * \threadsafety It is safe to call this macro from any thread. 866 * 867 * \since This macro is available since SDL 3.2.0. 868 */ 869#define SDL_COLORSPACETYPE(cspace) (SDL_ColorType)(((cspace) >> 28) & 0x0F) 870 871/** 872 * A macro to retrieve the range of an SDL_Colorspace. 873 * 874 * \param cspace an SDL_Colorspace to check. 875 * \returns the SDL_ColorRange of `cspace`. 876 * 877 * \threadsafety It is safe to call this macro from any thread. 878 * 879 * \since This macro is available since SDL 3.2.0. 880 */ 881#define SDL_COLORSPACERANGE(cspace) (SDL_ColorRange)(((cspace) >> 24) & 0x0F) 882 883/** 884 * A macro to retrieve the chroma sample location of an SDL_Colorspace. 885 * 886 * \param cspace an SDL_Colorspace to check. 887 * \returns the SDL_ChromaLocation of `cspace`. 888 * 889 * \threadsafety It is safe to call this macro from any thread. 890 * 891 * \since This macro is available since SDL 3.2.0. 892 */ 893#define SDL_COLORSPACECHROMA(cspace) (SDL_ChromaLocation)(((cspace) >> 20) & 0x0F) 894 895/** 896 * A macro to retrieve the primaries of an SDL_Colorspace. 897 * 898 * \param cspace an SDL_Colorspace to check. 899 * \returns the SDL_ColorPrimaries of `cspace`. 900 * 901 * \threadsafety It is safe to call this macro from any thread. 902 * 903 * \since This macro is available since SDL 3.2.0. 904 */ 905#define SDL_COLORSPACEPRIMARIES(cspace) (SDL_ColorPrimaries)(((cspace) >> 10) & 0x1F) 906 907/** 908 * A macro to retrieve the transfer characteristics of an SDL_Colorspace. 909 * 910 * \param cspace an SDL_Colorspace to check. 911 * \returns the SDL_TransferCharacteristics of `cspace`. 912 * 913 * \threadsafety It is safe to call this macro from any thread. 914 * 915 * \since This macro is available since SDL 3.2.0. 916 */ 917#define SDL_COLORSPACETRANSFER(cspace) (SDL_TransferCharacteristics)(((cspace) >> 5) & 0x1F) 918 919/** 920 * A macro to retrieve the matrix coefficients of an SDL_Colorspace. 921 * 922 * \param cspace an SDL_Colorspace to check. 923 * \returns the SDL_MatrixCoefficients of `cspace`. 924 * 925 * \threadsafety It is safe to call this macro from any thread. 926 * 927 * \since This macro is available since SDL 3.2.0. 928 */ 929#define SDL_COLORSPACEMATRIX(cspace) (SDL_MatrixCoefficients)((cspace) & 0x1F) 930 931/** 932 * A macro to determine if an SDL_Colorspace uses BT601 (or BT470BG) matrix 933 * coefficients. 934 * 935 * Note that this macro double-evaluates its parameter, so do not use 936 * expressions with side-effects here. 937 * 938 * \param cspace an SDL_Colorspace to check. 939 * \returns true if BT601 or BT470BG, false otherwise. 940 * 941 * \threadsafety It is safe to call this macro from any thread. 942 * 943 * \since This macro is available since SDL 3.2.0. 944 */ 945#define SDL_ISCOLORSPACE_MATRIX_BT601(cspace) (SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT601 || SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT470BG) 946 947/** 948 * A macro to determine if an SDL_Colorspace uses BT709 matrix coefficients. 949 * 950 * \param cspace an SDL_Colorspace to check. 951 * \returns true if BT709, false otherwise. 952 * 953 * \threadsafety It is safe to call this macro from any thread. 954 * 955 * \since This macro is available since SDL 3.2.0. 956 */ 957#define SDL_ISCOLORSPACE_MATRIX_BT709(cspace) (SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT709) 958 959/** 960 * A macro to determine if an SDL_Colorspace uses BT2020_NCL matrix 961 * coefficients. 962 * 963 * \param cspace an SDL_Colorspace to check. 964 * \returns true if BT2020_NCL, false otherwise. 965 * 966 * \threadsafety It is safe to call this macro from any thread. 967 * 968 * \since This macro is available since SDL 3.2.0. 969 */ 970#define SDL_ISCOLORSPACE_MATRIX_BT2020_NCL(cspace) (SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT2020_NCL) 971 972/** 973 * A macro to determine if an SDL_Colorspace has a limited range. 974 * 975 * \param cspace an SDL_Colorspace to check. 976 * \returns true if limited range, false otherwise. 977 * 978 * \threadsafety It is safe to call this macro from any thread. 979 * 980 * \since This macro is available since SDL 3.2.0. 981 */ 982#define SDL_ISCOLORSPACE_LIMITED_RANGE(cspace) (SDL_COLORSPACERANGE(cspace) != SDL_COLOR_RANGE_FULL) 983 984/** 985 * A macro to determine if an SDL_Colorspace has a full range. 986 * 987 * \param cspace an SDL_Colorspace to check. 988 * \returns true if full range, false otherwise. 989 * 990 * \threadsafety It is safe to call this macro from any thread. 991 * 992 * \since This macro is available since SDL 3.2.0. 993 */ 994#define SDL_ISCOLORSPACE_FULL_RANGE(cspace) (SDL_COLORSPACERANGE(cspace) == SDL_COLOR_RANGE_FULL) 995 996/** 997 * Colorspace definitions. 998 * 999 * Since similar colorspaces may vary in their details (matrix, transfer 1000 * function, etc.), this is not an exhaustive list, but rather a 1001 * representative sample of the kinds of colorspaces supported in SDL. 1002 * 1003 * \since This enum is available since SDL 3.2.0. 1004 * 1005 * \sa SDL_ColorPrimaries 1006 * \sa SDL_ColorRange 1007 * \sa SDL_ColorType 1008 * \sa SDL_MatrixCoefficients 1009 * \sa SDL_TransferCharacteristics 1010 */ 1011typedef enum SDL_Colorspace 1012{ 1013 SDL_COLORSPACE_UNKNOWN = 0, 1014 1015 /* sRGB is a gamma corrected colorspace, and the default colorspace for SDL rendering and 8-bit RGB surfaces */ 1016 SDL_COLORSPACE_SRGB = 0x120005a0u, /**< Equivalent to DXGI_COLOR_SPACE_RGB_FULL_G22_NONE_P709 */ 1017 /* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_RGB, 1018 SDL_COLOR_RANGE_FULL, 1019 SDL_COLOR_PRIMARIES_BT709, 1020 SDL_TRANSFER_CHARACTERISTICS_SRGB, 1021 SDL_MATRIX_COEFFICIENTS_IDENTITY, 1022 SDL_CHROMA_LOCATION_NONE), */ 1023 1024 /* This is a linear colorspace and the default colorspace for floating point surfaces. On Windows this is the scRGB colorspace, and on Apple platforms this is kCGColorSpaceExtendedLinearSRGB for EDR content */ 1025 SDL_COLORSPACE_SRGB_LINEAR = 0x12000500u, /**< Equivalent to DXGI_COLOR_SPACE_RGB_FULL_G10_NONE_P709 */ 1026 /* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_RGB, 1027 SDL_COLOR_RANGE_FULL, 1028 SDL_COLOR_PRIMARIES_BT709, 1029 SDL_TRANSFER_CHARACTERISTICS_LINEAR, 1030 SDL_MATRIX_COEFFICIENTS_IDENTITY, 1031 SDL_CHROMA_LOCATION_NONE), */ 1032 1033 /* HDR10 is a non-linear HDR colorspace and the default colorspace for 10-bit surfaces */ 1034 SDL_COLORSPACE_HDR10 = 0x12002600u, /**< Equivalent to DXGI_COLOR_SPACE_RGB_FULL_G2084_NONE_P2020 */ 1035 /* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_RGB, 1036 SDL_COLOR_RANGE_FULL, 1037 SDL_COLOR_PRIMARIES_BT2020, 1038 SDL_TRANSFER_CHARACTERISTICS_PQ, 1039 SDL_MATRIX_COEFFICIENTS_IDENTITY, 1040 SDL_CHROMA_LOCATION_NONE), */ 1041 1042 SDL_COLORSPACE_JPEG = 0x220004c6u, /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_FULL_G22_NONE_P709_X601 */ 1043 /* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_YCBCR, 1044 SDL_COLOR_RANGE_FULL, 1045 SDL_COLOR_PRIMARIES_BT709, 1046 SDL_TRANSFER_CHARACTERISTICS_BT601, 1047 SDL_MATRIX_COEFFICIENTS_BT601, 1048 SDL_CHROMA_LOCATION_NONE), */ 1049 1050 SDL_COLORSPACE_BT601_LIMITED = 0x211018c6u, /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P601 */ 1051 /* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_YCBCR, 1052 SDL_COLOR_RANGE_LIMITED, 1053 SDL_COLOR_PRIMARIES_BT601, 1054 SDL_TRANSFER_CHARACTERISTICS_BT601, 1055 SDL_MATRIX_COEFFICIENTS_BT601, 1056 SDL_CHROMA_LOCATION_LEFT), */ 1057 1058 SDL_COLORSPACE_BT601_FULL = 0x221018c6u, /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P601 */ 1059 /* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_YCBCR, 1060 SDL_COLOR_RANGE_FULL, 1061 SDL_COLOR_PRIMARIES_BT601, 1062 SDL_TRANSFER_CHARACTERISTICS_BT601, 1063 SDL_MATRIX_COEFFICIENTS_BT601, 1064 SDL_CHROMA_LOCATION_LEFT), */ 1065 1066 SDL_COLORSPACE_BT709_LIMITED = 0x21100421u, /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P709 */ 1067 /* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_YCBCR, 1068 SDL_COLOR_RANGE_LIMITED, 1069 SDL_COLOR_PRIMARIES_BT709, 1070 SDL_TRANSFER_CHARACTERISTICS_BT709, 1071 SDL_MATRIX_COEFFICIENTS_BT709, 1072 SDL_CHROMA_LOCATION_LEFT), */ 1073 1074 SDL_COLORSPACE_BT709_FULL = 0x22100421u, /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P709 */ 1075 /* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_YCBCR, 1076 SDL_COLOR_RANGE_FULL, 1077 SDL_COLOR_PRIMARIES_BT709, 1078 SDL_TRANSFER_CHARACTERISTICS_BT709, 1079 SDL_MATRIX_COEFFICIENTS_BT709, 1080 SDL_CHROMA_LOCATION_LEFT), */ 1081 1082 SDL_COLORSPACE_BT2020_LIMITED = 0x21102609u, /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P2020 */ 1083 /* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_YCBCR, 1084 SDL_COLOR_RANGE_LIMITED, 1085 SDL_COLOR_PRIMARIES_BT2020, 1086 SDL_TRANSFER_CHARACTERISTICS_PQ, 1087 SDL_MATRIX_COEFFICIENTS_BT2020_NCL, 1088 SDL_CHROMA_LOCATION_LEFT), */ 1089 1090 SDL_COLORSPACE_BT2020_FULL = 0x22102609u, /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_FULL_G22_LEFT_P2020 */ 1091 /* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_YCBCR, 1092 SDL_COLOR_RANGE_FULL, 1093 SDL_COLOR_PRIMARIES_BT2020, 1094 SDL_TRANSFER_CHARACTERISTICS_PQ, 1095 SDL_MATRIX_COEFFICIENTS_BT2020_NCL, 1096 SDL_CHROMA_LOCATION_LEFT), */ 1097 1098 SDL_COLORSPACE_RGB_DEFAULT = SDL_COLORSPACE_SRGB, /**< The default colorspace for RGB surfaces if no colorspace is specified */ 1099 SDL_COLORSPACE_YUV_DEFAULT = SDL_COLORSPACE_BT601_LIMITED /**< The default colorspace for YUV surfaces if no colorspace is specified */ 1100} SDL_Colorspace; 1101 1102/** 1103 * A structure that represents a color as RGBA components. 1104 * 1105 * The bits of this structure can be directly reinterpreted as an 1106 * integer-packed color which uses the SDL_PIXELFORMAT_RGBA32 format 1107 * (SDL_PIXELFORMAT_ABGR8888 on little-endian systems and 1108 * SDL_PIXELFORMAT_RGBA8888 on big-endian systems). 1109 * 1110 * \since This struct is available since SDL 3.2.0. 1111 */ 1112typedef struct SDL_Color 1113{ 1114 Uint8 r; 1115 Uint8 g; 1116 Uint8 b; 1117 Uint8 a; 1118} SDL_Color; 1119 1120/** 1121 * The bits of this structure can be directly reinterpreted as a float-packed 1122 * color which uses the SDL_PIXELFORMAT_RGBA128_FLOAT format 1123 * 1124 * \since This struct is available since SDL 3.2.0. 1125 */ 1126typedef struct SDL_FColor 1127{ 1128 float r; 1129 float g; 1130 float b; 1131 float a; 1132} SDL_FColor; 1133 1134/** 1135 * A set of indexed colors representing a palette. 1136 * 1137 * \since This struct is available since SDL 3.2.0. 1138 * 1139 * \sa SDL_SetPaletteColors 1140 */ 1141typedef struct SDL_Palette 1142{ 1143 int ncolors; /**< number of elements in `colors`. */ 1144 SDL_Color *colors; /**< an array of colors, `ncolors` long. */ 1145 Uint32 version; /**< internal use only, do not touch. */ 1146 int refcount; /**< internal use only, do not touch. */ 1147} SDL_Palette; 1148 1149/** 1150 * Details about the format of a pixel. 1151 * 1152 * \since This struct is available since SDL 3.2.0. 1153 */ 1154typedef struct SDL_PixelFormatDetails 1155{ 1156 SDL_PixelFormat format; 1157 Uint8 bits_per_pixel; 1158 Uint8 bytes_per_pixel; 1159 Uint8 padding[2]; 1160 Uint32 Rmask; 1161 Uint32 Gmask; 1162 Uint32 Bmask; 1163 Uint32 Amask; 1164 Uint8 Rbits; 1165 Uint8 Gbits; 1166 Uint8 Bbits; 1167 Uint8 Abits; 1168 Uint8 Rshift; 1169 Uint8 Gshift; 1170 Uint8 Bshift; 1171 Uint8 Ashift; 1172} SDL_PixelFormatDetails; 1173 1174/** 1175 * Get the human readable name of a pixel format. 1176 * 1177 * \param format the pixel format to query. 1178 * \returns the human readable name of the specified pixel format or 1179 * "SDL_PIXELFORMAT_UNKNOWN" if the format isn't recognized. 1180 * 1181 * \threadsafety It is safe to call this function from any thread. 1182 * 1183 * \since This function is available since SDL 3.2.0. 1184 */ 1185extern SDL_DECLSPEC const char * SDLCALL SDL_GetPixelFormatName(SDL_PixelFormat format); 1186 1187/** 1188 * Convert one of the enumerated pixel formats to a bpp value and RGBA masks. 1189 * 1190 * \param format one of the SDL_PixelFormat values. 1191 * \param bpp a bits per pixel value; usually 15, 16, or 32. 1192 * \param Rmask a pointer filled in with the red mask for the format. 1193 * \param Gmask a pointer filled in with the green mask for the format. 1194 * \param Bmask a pointer filled in with the blue mask for the format. 1195 * \param Amask a pointer filled in with the alpha mask for the format. 1196 * \returns true on success or false on failure; call SDL_GetError() for more 1197 * information. 1198 * 1199 * \threadsafety It is safe to call this function from any thread. 1200 * 1201 * \since This function is available since SDL 3.2.0. 1202 * 1203 * \sa SDL_GetPixelFormatForMasks 1204 */ 1205extern SDL_DECLSPEC bool SDLCALL SDL_GetMasksForPixelFormat(SDL_PixelFormat format, int *bpp, Uint32 *Rmask, Uint32 *Gmask, Uint32 *Bmask, Uint32 *Amask); 1206 1207/** 1208 * Convert a bpp value and RGBA masks to an enumerated pixel format. 1209 * 1210 * This will return `SDL_PIXELFORMAT_UNKNOWN` if the conversion wasn't 1211 * possible. 1212 * 1213 * \param bpp a bits per pixel value; usually 15, 16, or 32. 1214 * \param Rmask the red mask for the format. 1215 * \param Gmask the green mask for the format. 1216 * \param Bmask the blue mask for the format. 1217 * \param Amask the alpha mask for the format. 1218 * \returns the SDL_PixelFormat value corresponding to the format masks, or 1219 * SDL_PIXELFORMAT_UNKNOWN if there isn't a match. 1220 * 1221 * \threadsafety It is safe to call this function from any thread. 1222 * 1223 * \since This function is available since SDL 3.2.0. 1224 * 1225 * \sa SDL_GetMasksForPixelFormat 1226 */ 1227extern SDL_DECLSPEC SDL_PixelFormat SDLCALL SDL_GetPixelFormatForMasks(int bpp, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask); 1228 1229/** 1230 * Create an SDL_PixelFormatDetails structure corresponding to a pixel format. 1231 * 1232 * Returned structure may come from a shared global cache (i.e. not newly 1233 * allocated), and hence should not be modified, especially the palette. Weird 1234 * errors such as `Blit combination not supported` may occur. 1235 * 1236 * \param format one of the SDL_PixelFormat values. 1237 * \returns a pointer to a SDL_PixelFormatDetails structure or NULL on 1238 * failure; call SDL_GetError() for more information. 1239 * 1240 * \threadsafety It is safe to call this function from any thread. 1241 * 1242 * \since This function is available since SDL 3.2.0. 1243 */ 1244extern SDL_DECLSPEC const SDL_PixelFormatDetails * SDLCALL SDL_GetPixelFormatDetails(SDL_PixelFormat format); 1245 1246/** 1247 * Create a palette structure with the specified number of color entries. 1248 * 1249 * The palette entries are initialized to white. 1250 * 1251 * \param ncolors represents the number of color entries in the color palette. 1252 * \returns a new SDL_Palette structure on success or NULL on failure (e.g. if 1253 * there wasn't enough memory); call SDL_GetError() for more 1254 * information. 1255 * 1256 * \threadsafety It is safe to call this function from any thread. 1257 * 1258 * \since This function is available since SDL 3.2.0. 1259 * 1260 * \sa SDL_DestroyPalette 1261 * \sa SDL_SetPaletteColors 1262 * \sa SDL_SetSurfacePalette 1263 */ 1264extern SDL_DECLSPEC SDL_Palette * SDLCALL SDL_CreatePalette(int ncolors); 1265 1266/** 1267 * Set a range of colors in a palette. 1268 * 1269 * \param palette the SDL_Palette structure to modify. 1270 * \param colors an array of SDL_Color structures to copy into the palette. 1271 * \param firstcolor the index of the first palette entry to modify. 1272 * \param ncolors the number of entries to modify. 1273 * \returns true on success or false on failure; call SDL_GetError() for more 1274 * information. 1275 * 1276 * \threadsafety It is safe to call this function from any thread, as long as 1277 * the palette is not modified or destroyed in another thread. 1278 * 1279 * \since This function is available since SDL 3.2.0. 1280 */ 1281extern SDL_DECLSPEC bool SDLCALL SDL_SetPaletteColors(SDL_Palette *palette, const SDL_Color *colors, int firstcolor, int ncolors); 1282 1283/** 1284 * Free a palette created with SDL_CreatePalette(). 1285 * 1286 * \param palette the SDL_Palette structure to be freed. 1287 * 1288 * \threadsafety It is safe to call this function from any thread, as long as 1289 * the palette is not modified or destroyed in another thread. 1290 * 1291 * \since This function is available since SDL 3.2.0. 1292 * 1293 * \sa SDL_CreatePalette 1294 */ 1295extern SDL_DECLSPEC void SDLCALL SDL_DestroyPalette(SDL_Palette *palette); 1296 1297/** 1298 * Map an RGB triple to an opaque pixel value for a given pixel format. 1299 * 1300 * This function maps the RGB color value to the specified pixel format and 1301 * returns the pixel value best approximating the given RGB color value for 1302 * the given pixel format. 1303 * 1304 * If the format has a palette (8-bit) the index of the closest matching color 1305 * in the palette will be returned. 1306 * 1307 * If the specified pixel format has an alpha component it will be returned as 1308 * all 1 bits (fully opaque). 1309 * 1310 * If the pixel format bpp (color depth) is less than 32-bpp then the unused 1311 * upper bits of the return value can safely be ignored (e.g., with a 16-bpp 1312 * format the return value can be assigned to a Uint16, and similarly a Uint8 1313 * for an 8-bpp format). 1314 * 1315 * \param format a pointer to SDL_PixelFormatDetails describing the pixel 1316 * format. 1317 * \param palette an optional palette for indexed formats, may be NULL. 1318 * \param r the red component of the pixel in the range 0-255. 1319 * \param g the green component of the pixel in the range 0-255. 1320 * \param b the blue component of the pixel in the range 0-255. 1321 * \returns a pixel value. 1322 * 1323 * \threadsafety It is safe to call this function from any thread, as long as 1324 * the palette is not modified. 1325 * 1326 * \since This function is available since SDL 3.2.0. 1327 * 1328 * \sa SDL_GetPixelFormatDetails 1329 * \sa SDL_GetRGB 1330 * \sa SDL_MapRGBA 1331 * \sa SDL_MapSurfaceRGB 1332 */ 1333extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormatDetails *format, const SDL_Palette *palette, Uint8 r, Uint8 g, Uint8 b); 1334 1335/** 1336 * Map an RGBA quadruple to a pixel value for a given pixel format. 1337 * 1338 * This function maps the RGBA color value to the specified pixel format and 1339 * returns the pixel value best approximating the given RGBA color value for 1340 * the given pixel format. 1341 * 1342 * If the specified pixel format has no alpha component the alpha value will 1343 * be ignored (as it will be in formats with a palette). 1344 * 1345 * If the format has a palette (8-bit) the index of the closest matching color 1346 * in the palette will be returned. 1347 * 1348 * If the pixel format bpp (color depth) is less than 32-bpp then the unused 1349 * upper bits of the return value can safely be ignored (e.g., with a 16-bpp 1350 * format the return value can be assigned to a Uint16, and similarly a Uint8 1351 * for an 8-bpp format). 1352 * 1353 * \param format a pointer to SDL_PixelFormatDetails describing the pixel 1354 * format. 1355 * \param palette an optional palette for indexed formats, may be NULL. 1356 * \param r the red component of the pixel in the range 0-255. 1357 * \param g the green component of the pixel in the range 0-255. 1358 * \param b the blue component of the pixel in the range 0-255. 1359 * \param a the alpha component of the pixel in the range 0-255. 1360 * \returns a pixel value. 1361 * 1362 * \threadsafety It is safe to call this function from any thread, as long as 1363 * the palette is not modified. 1364 * 1365 * \since This function is available since SDL 3.2.0. 1366 * 1367 * \sa SDL_GetPixelFormatDetails 1368 * \sa SDL_GetRGBA 1369 * \sa SDL_MapRGB 1370 * \sa SDL_MapSurfaceRGBA 1371 */ 1372extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormatDetails *format, const SDL_Palette *palette, Uint8 r, Uint8 g, Uint8 b, Uint8 a); 1373 1374/** 1375 * Get RGB values from a pixel in the specified format. 1376 * 1377 * This function uses the entire 8-bit [0..255] range when converting color 1378 * components from pixel formats with less than 8-bits per RGB component 1379 * (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff, 1380 * 0xff, 0xff] not [0xf8, 0xfc, 0xf8]). 1381 * 1382 * \param pixelvalue a pixel value. 1383 * \param format a pointer to SDL_PixelFormatDetails describing the pixel 1384 * format. 1385 * \param palette an optional palette for indexed formats, may be NULL. 1386 * \param r a pointer filled in with the red component, may be NULL. 1387 * \param g a pointer filled in with the green component, may be NULL. 1388 * \param b a pointer filled in with the blue component, may be NULL. 1389 * 1390 * \threadsafety It is safe to call this function from any thread, as long as 1391 * the palette is not modified. 1392 * 1393 * \since This function is available since SDL 3.2.0. 1394 * 1395 * \sa SDL_GetPixelFormatDetails 1396 * \sa SDL_GetRGBA 1397 * \sa SDL_MapRGB 1398 * \sa SDL_MapRGBA 1399 */ 1400extern SDL_DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixelvalue, const SDL_PixelFormatDetails *format, const SDL_Palette *palette, Uint8 *r, Uint8 *g, Uint8 *b); 1401 1402/** 1403 * Get RGBA values from a pixel in the specified format. 1404 * 1405 * This function uses the entire 8-bit [0..255] range when converting color 1406 * components from pixel formats with less than 8-bits per RGB component 1407 * (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff, 1408 * 0xff, 0xff] not [0xf8, 0xfc, 0xf8]). 1409 * 1410 * If the surface has no alpha component, the alpha will be returned as 0xff 1411 * (100% opaque). 1412 * 1413 * \param pixelvalue a pixel value. 1414 * \param format a pointer to SDL_PixelFormatDetails describing the pixel 1415 * format. 1416 * \param palette an optional palette for indexed formats, may be NULL. 1417 * \param r a pointer filled in with the red component, may be NULL. 1418 * \param g a pointer filled in with the green component, may be NULL. 1419 * \param b a pointer filled in with the blue component, may be NULL. 1420 * \param a a pointer filled in with the alpha component, may be NULL. 1421 * 1422 * \threadsafety It is safe to call this function from any thread, as long as 1423 * the palette is not modified. 1424 * 1425 * \since This function is available since SDL 3.2.0. 1426 * 1427 * \sa SDL_GetPixelFormatDetails 1428 * \sa SDL_GetRGB 1429 * \sa SDL_MapRGB 1430 * \sa SDL_MapRGBA 1431 */ 1432extern SDL_DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixelvalue, const SDL_PixelFormatDetails *format, const SDL_Palette *palette, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a); 1433 1434 1435/* Ends C function definitions when using C++ */ 1436#ifdef __cplusplus 1437} 1438#endif 1439#include <SDL3/SDL_close_code.h> 1440 1441#endif /* SDL_pixels_h_ */ 1442[FILE END](C) 2025 0x4248 (C) 2025 4248 Media and 4248 Systems, All part of 0x4248 See LICENCE files for more information. Not all files are by 0x4248 always check Licencing.