1 /* 2 Simple DirectMedia Layer 3 Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org> 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 * Header for the enumerated pixel format definitions. 26 */ 27 28 #ifndef SDL_pixels_h_ 29 #define SDL_pixels_h_ 30 31 #include "SDL_stdinc.h" 32 #include "SDL_endian.h" 33 34 #include "begin_code.h" 35 /* Set up for C function definitions, even when using C++ */ 36 #ifdef __cplusplus 37 extern "C" { 38 #endif 39 40 /** 41 * \name Transparency definitions 42 * 43 * These define alpha as the opacity of a surface. 44 */ 45 /* @{ */ 46 #define SDL_ALPHA_OPAQUE 255 47 #define SDL_ALPHA_TRANSPARENT 0 48 /* @} */ 49 50 /** Pixel type. */ 51 typedef enum 52 { 53 SDL_PIXELTYPE_UNKNOWN, 54 SDL_PIXELTYPE_INDEX1, 55 SDL_PIXELTYPE_INDEX4, 56 SDL_PIXELTYPE_INDEX8, 57 SDL_PIXELTYPE_PACKED8, 58 SDL_PIXELTYPE_PACKED16, 59 SDL_PIXELTYPE_PACKED32, 60 SDL_PIXELTYPE_ARRAYU8, 61 SDL_PIXELTYPE_ARRAYU16, 62 SDL_PIXELTYPE_ARRAYU32, 63 SDL_PIXELTYPE_ARRAYF16, 64 SDL_PIXELTYPE_ARRAYF32, 65 66 /* This must be at the end of the list to avoid breaking the existing ABI */ 67 SDL_PIXELTYPE_INDEX2 68 } SDL_PixelType; 69 70 /** Bitmap pixel order, high bit -> low bit. */ 71 typedef enum 72 { 73 SDL_BITMAPORDER_NONE, 74 SDL_BITMAPORDER_4321, 75 SDL_BITMAPORDER_1234 76 } SDL_BitmapOrder; 77 78 /** Packed component order, high bit -> low bit. */ 79 typedef enum 80 { 81 SDL_PACKEDORDER_NONE, 82 SDL_PACKEDORDER_XRGB, 83 SDL_PACKEDORDER_RGBX, 84 SDL_PACKEDORDER_ARGB, 85 SDL_PACKEDORDER_RGBA, 86 SDL_PACKEDORDER_XBGR, 87 SDL_PACKEDORDER_BGRX, 88 SDL_PACKEDORDER_ABGR, 89 SDL_PACKEDORDER_BGRA 90 } SDL_PackedOrder; 91 92 /** Array component order, low byte -> high byte. */ 93 /* !!! FIXME: in 2.1, make these not overlap differently with 94 !!! FIXME: SDL_PACKEDORDER_*, so we can simplify SDL_ISPIXELFORMAT_ALPHA */ 95 typedef enum 96 { 97 SDL_ARRAYORDER_NONE, 98 SDL_ARRAYORDER_RGB, 99 SDL_ARRAYORDER_RGBA, 100 SDL_ARRAYORDER_ARGB, 101 SDL_ARRAYORDER_BGR, 102 SDL_ARRAYORDER_BGRA, 103 SDL_ARRAYORDER_ABGR 104 } SDL_ArrayOrder; 105 106 /** Packed component layout. */ 107 typedef enum 108 { 109 SDL_PACKEDLAYOUT_NONE, 110 SDL_PACKEDLAYOUT_332, 111 SDL_PACKEDLAYOUT_4444, 112 SDL_PACKEDLAYOUT_1555, 113 SDL_PACKEDLAYOUT_5551, 114 SDL_PACKEDLAYOUT_565, 115 SDL_PACKEDLAYOUT_8888, 116 SDL_PACKEDLAYOUT_2101010, 117 SDL_PACKEDLAYOUT_1010102 118 } SDL_PackedLayout; 119 120 #define SDL_DEFINE_PIXELFOURCC(A, B, C, D) SDL_FOURCC(A, B, C, D) 121 122 #define SDL_DEFINE_PIXELFORMAT(type, order, layout, bits, bytes) \ 123 ((1 << 28) | ((type) << 24) | ((order) << 20) | ((layout) << 16) | \ 124 ((bits) << 8) | ((bytes) << 0)) 125 126 #define SDL_PIXELFLAG(X) (((X) >> 28) & 0x0F) 127 #define SDL_PIXELTYPE(X) (((X) >> 24) & 0x0F) 128 #define SDL_PIXELORDER(X) (((X) >> 20) & 0x0F) 129 #define SDL_PIXELLAYOUT(X) (((X) >> 16) & 0x0F) 130 #define SDL_BITSPERPIXEL(X) (((X) >> 8) & 0xFF) 131 #define SDL_BYTESPERPIXEL(X) \ 132 (SDL_ISPIXELFORMAT_FOURCC(X) ? \ 133 ((((X) == SDL_PIXELFORMAT_YUY2) || \ 134 ((X) == SDL_PIXELFORMAT_UYVY) || \ 135 ((X) == SDL_PIXELFORMAT_YVYU)) ? 2 : 1) : (((X) >> 0) & 0xFF)) 136 137 #define SDL_ISPIXELFORMAT_INDEXED(format) \ 138 (!SDL_ISPIXELFORMAT_FOURCC(format) && \ 139 ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX1) || \ 140 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX2) || \ 141 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX4) || \ 142 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX8))) 143 144 #define SDL_ISPIXELFORMAT_PACKED(format) \ 145 (!SDL_ISPIXELFORMAT_FOURCC(format) && \ 146 ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED8) || \ 147 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED16) || \ 148 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED32))) 149 150 #define SDL_ISPIXELFORMAT_ARRAY(format) \ 151 (!SDL_ISPIXELFORMAT_FOURCC(format) && \ 152 ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYU8) || \ 153 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYU16) || \ 154 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYU32) || \ 155 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF16) || \ 156 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF32))) 157 158 #define SDL_ISPIXELFORMAT_ALPHA(format) \ 159 ((SDL_ISPIXELFORMAT_PACKED(format) && \ 160 ((SDL_PIXELORDER(format) == SDL_PACKEDORDER_ARGB) || \ 161 (SDL_PIXELORDER(format) == SDL_PACKEDORDER_RGBA) || \ 162 (SDL_PIXELORDER(format) == SDL_PACKEDORDER_ABGR) || \ 163 (SDL_PIXELORDER(format) == SDL_PACKEDORDER_BGRA))) || \ 164 (SDL_ISPIXELFORMAT_ARRAY(format) && \ 165 ((SDL_PIXELORDER(format) == SDL_ARRAYORDER_ARGB) || \ 166 (SDL_PIXELORDER(format) == SDL_ARRAYORDER_RGBA) || \ 167 (SDL_PIXELORDER(format) == SDL_ARRAYORDER_ABGR) || \ 168 (SDL_PIXELORDER(format) == SDL_ARRAYORDER_BGRA)))) 169 170 /* The flag is set to 1 because 0x1? is not in the printable ASCII range */ 171 #define SDL_ISPIXELFORMAT_FOURCC(format) \ 172 ((format) && (SDL_PIXELFLAG(format) != 1)) 173 174 /* Note: If you modify this list, update SDL_GetPixelFormatName() */ 175 typedef enum 176 { 177 SDL_PIXELFORMAT_UNKNOWN, 178 SDL_PIXELFORMAT_INDEX1LSB = 179 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX1, SDL_BITMAPORDER_4321, 0, 180 1, 0), 181 SDL_PIXELFORMAT_INDEX1MSB = 182 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX1, SDL_BITMAPORDER_1234, 0, 183 1, 0), 184 SDL_PIXELFORMAT_INDEX2LSB = 185 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX2, SDL_BITMAPORDER_4321, 0, 186 2, 0), 187 SDL_PIXELFORMAT_INDEX2MSB = 188 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX2, SDL_BITMAPORDER_1234, 0, 189 2, 0), 190 SDL_PIXELFORMAT_INDEX4LSB = 191 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX4, SDL_BITMAPORDER_4321, 0, 192 4, 0), 193 SDL_PIXELFORMAT_INDEX4MSB = 194 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX4, SDL_BITMAPORDER_1234, 0, 195 4, 0), 196 SDL_PIXELFORMAT_INDEX8 = 197 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX8, 0, 0, 8, 1), 198 SDL_PIXELFORMAT_RGB332 = 199 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED8, SDL_PACKEDORDER_XRGB, 200 SDL_PACKEDLAYOUT_332, 8, 1), 201 SDL_PIXELFORMAT_XRGB4444 = 202 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB, 203 SDL_PACKEDLAYOUT_4444, 12, 2), 204 SDL_PIXELFORMAT_RGB444 = SDL_PIXELFORMAT_XRGB4444, 205 SDL_PIXELFORMAT_XBGR4444 = 206 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XBGR, 207 SDL_PACKEDLAYOUT_4444, 12, 2), 208 SDL_PIXELFORMAT_BGR444 = SDL_PIXELFORMAT_XBGR4444, 209 SDL_PIXELFORMAT_XRGB1555 = 210 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB, 211 SDL_PACKEDLAYOUT_1555, 15, 2), 212 SDL_PIXELFORMAT_RGB555 = SDL_PIXELFORMAT_XRGB1555, 213 SDL_PIXELFORMAT_XBGR1555 = 214 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XBGR, 215 SDL_PACKEDLAYOUT_1555, 15, 2), 216 SDL_PIXELFORMAT_BGR555 = SDL_PIXELFORMAT_XBGR1555, 217 SDL_PIXELFORMAT_ARGB4444 = 218 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ARGB, 219 SDL_PACKEDLAYOUT_4444, 16, 2), 220 SDL_PIXELFORMAT_RGBA4444 = 221 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_RGBA, 222 SDL_PACKEDLAYOUT_4444, 16, 2), 223 SDL_PIXELFORMAT_ABGR4444 = 224 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ABGR, 225 SDL_PACKEDLAYOUT_4444, 16, 2), 226 SDL_PIXELFORMAT_BGRA4444 = 227 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_BGRA, 228 SDL_PACKEDLAYOUT_4444, 16, 2), 229 SDL_PIXELFORMAT_ARGB1555 = 230 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ARGB, 231 SDL_PACKEDLAYOUT_1555, 16, 2), 232 SDL_PIXELFORMAT_RGBA5551 = 233 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_RGBA, 234 SDL_PACKEDLAYOUT_5551, 16, 2), 235 SDL_PIXELFORMAT_ABGR1555 = 236 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ABGR, 237 SDL_PACKEDLAYOUT_1555, 16, 2), 238 SDL_PIXELFORMAT_BGRA5551 = 239 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_BGRA, 240 SDL_PACKEDLAYOUT_5551, 16, 2), 241 SDL_PIXELFORMAT_RGB565 = 242 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB, 243 SDL_PACKEDLAYOUT_565, 16, 2), 244 SDL_PIXELFORMAT_BGR565 = 245 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XBGR, 246 SDL_PACKEDLAYOUT_565, 16, 2), 247 SDL_PIXELFORMAT_RGB24 = 248 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU8, SDL_ARRAYORDER_RGB, 0, 249 24, 3), 250 SDL_PIXELFORMAT_BGR24 = 251 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU8, SDL_ARRAYORDER_BGR, 0, 252 24, 3), 253 SDL_PIXELFORMAT_XRGB8888 = 254 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XRGB, 255 SDL_PACKEDLAYOUT_8888, 24, 4), 256 SDL_PIXELFORMAT_RGB888 = SDL_PIXELFORMAT_XRGB8888, 257 SDL_PIXELFORMAT_RGBX8888 = 258 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_RGBX, 259 SDL_PACKEDLAYOUT_8888, 24, 4), 260 SDL_PIXELFORMAT_XBGR8888 = 261 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XBGR, 262 SDL_PACKEDLAYOUT_8888, 24, 4), 263 SDL_PIXELFORMAT_BGR888 = SDL_PIXELFORMAT_XBGR8888, 264 SDL_PIXELFORMAT_BGRX8888 = 265 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_BGRX, 266 SDL_PACKEDLAYOUT_8888, 24, 4), 267 SDL_PIXELFORMAT_ARGB8888 = 268 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ARGB, 269 SDL_PACKEDLAYOUT_8888, 32, 4), 270 SDL_PIXELFORMAT_RGBA8888 = 271 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_RGBA, 272 SDL_PACKEDLAYOUT_8888, 32, 4), 273 SDL_PIXELFORMAT_ABGR8888 = 274 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ABGR, 275 SDL_PACKEDLAYOUT_8888, 32, 4), 276 SDL_PIXELFORMAT_BGRA8888 = 277 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_BGRA, 278 SDL_PACKEDLAYOUT_8888, 32, 4), 279 SDL_PIXELFORMAT_ARGB2101010 = 280 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ARGB, 281 SDL_PACKEDLAYOUT_2101010, 32, 4), 282 283 /* Aliases for RGBA byte arrays of color data, for the current platform */ 284 #if SDL_BYTEORDER == SDL_BIG_ENDIAN 285 SDL_PIXELFORMAT_RGBA32 = SDL_PIXELFORMAT_RGBA8888, 286 SDL_PIXELFORMAT_ARGB32 = SDL_PIXELFORMAT_ARGB8888, 287 SDL_PIXELFORMAT_BGRA32 = SDL_PIXELFORMAT_BGRA8888, 288 SDL_PIXELFORMAT_ABGR32 = SDL_PIXELFORMAT_ABGR8888, 289 SDL_PIXELFORMAT_RGBX32 = SDL_PIXELFORMAT_RGBX8888, 290 SDL_PIXELFORMAT_XRGB32 = SDL_PIXELFORMAT_XRGB8888, 291 SDL_PIXELFORMAT_BGRX32 = SDL_PIXELFORMAT_BGRX8888, 292 SDL_PIXELFORMAT_XBGR32 = SDL_PIXELFORMAT_XBGR8888, 293 #else 294 SDL_PIXELFORMAT_RGBA32 = SDL_PIXELFORMAT_ABGR8888, 295 SDL_PIXELFORMAT_ARGB32 = SDL_PIXELFORMAT_BGRA8888, 296 SDL_PIXELFORMAT_BGRA32 = SDL_PIXELFORMAT_ARGB8888, 297 SDL_PIXELFORMAT_ABGR32 = SDL_PIXELFORMAT_RGBA8888, 298 SDL_PIXELFORMAT_RGBX32 = SDL_PIXELFORMAT_XBGR8888, 299 SDL_PIXELFORMAT_XRGB32 = SDL_PIXELFORMAT_BGRX8888, 300 SDL_PIXELFORMAT_BGRX32 = SDL_PIXELFORMAT_XRGB8888, 301 SDL_PIXELFORMAT_XBGR32 = SDL_PIXELFORMAT_RGBX8888, 302 #endif 303 304 SDL_PIXELFORMAT_YV12 = /**< Planar mode: Y + V + U (3 planes) */ 305 SDL_DEFINE_PIXELFOURCC('Y', 'V', '1', '2'), 306 SDL_PIXELFORMAT_IYUV = /**< Planar mode: Y + U + V (3 planes) */ 307 SDL_DEFINE_PIXELFOURCC('I', 'Y', 'U', 'V'), 308 SDL_PIXELFORMAT_YUY2 = /**< Packed mode: Y0+U0+Y1+V0 (1 plane) */ 309 SDL_DEFINE_PIXELFOURCC('Y', 'U', 'Y', '2'), 310 SDL_PIXELFORMAT_UYVY = /**< Packed mode: U0+Y0+V0+Y1 (1 plane) */ 311 SDL_DEFINE_PIXELFOURCC('U', 'Y', 'V', 'Y'), 312 SDL_PIXELFORMAT_YVYU = /**< Packed mode: Y0+V0+Y1+U0 (1 plane) */ 313 SDL_DEFINE_PIXELFOURCC('Y', 'V', 'Y', 'U'), 314 SDL_PIXELFORMAT_NV12 = /**< Planar mode: Y + U/V interleaved (2 planes) */ 315 SDL_DEFINE_PIXELFOURCC('N', 'V', '1', '2'), 316 SDL_PIXELFORMAT_NV21 = /**< Planar mode: Y + V/U interleaved (2 planes) */ 317 SDL_DEFINE_PIXELFOURCC('N', 'V', '2', '1'), 318 SDL_PIXELFORMAT_EXTERNAL_OES = /**< Android video texture format */ 319 SDL_DEFINE_PIXELFOURCC('O', 'E', 'S', ' ') 320 } SDL_PixelFormatEnum; 321 322 /** 323 * The bits of this structure can be directly reinterpreted as an 324 * integer-packed color which uses the SDL_PIXELFORMAT_RGBA32 format 325 * (SDL_PIXELFORMAT_ABGR8888 on little-endian systems and 326 * SDL_PIXELFORMAT_RGBA8888 on big-endian systems). 327 */ 328 typedef struct SDL_Color 329 { 330 Uint8 r; 331 Uint8 g; 332 Uint8 b; 333 Uint8 a; 334 } SDL_Color; 335 #define SDL_Colour SDL_Color 336 337 typedef struct SDL_Palette 338 { 339 int ncolors; 340 SDL_Color *colors; 341 Uint32 version; 342 int refcount; 343 } SDL_Palette; 344 345 /** 346 * A structure that contains pixel format information. 347 * 348 * Everything in the pixel format structure is read-only. 349 * 350 * A pixel format has either a palette or masks. If a palette is used `Rmask`, 351 * `Gmask`, `Bmask`, and `Amask` will be 0. 352 * 353 * An SDL_PixelFormat describes the format of the pixel data stored at the 354 * `pixels` field of an SDL_Surface. Every surface stores an SDL_PixelFormat 355 * in the `format` field. 356 * 357 * If you wish to do pixel level modifications on a surface, then 358 * understanding how SDL stores its color information is essential. 359 * 360 * For information on modern pixel color spaces, see the following Wikipedia 361 * article: http://en.wikipedia.org/wiki/RGBA_color_space 362 * 363 * \sa SDL_ConvertSurface 364 * \sa SDL_GetRGB 365 * \sa SDL_GetRGBA 366 * \sa SDL_MapRGB 367 * \sa SDL_MapRGBA 368 * \sa SDL_AllocFormat 369 * \sa SDL_FreeFormat 370 */ 371 typedef struct SDL_PixelFormat 372 { 373 Uint32 format; 374 SDL_Palette *palette; 375 Uint8 BitsPerPixel; 376 Uint8 BytesPerPixel; 377 Uint8 padding[2]; 378 Uint32 Rmask; 379 Uint32 Gmask; 380 Uint32 Bmask; 381 Uint32 Amask; 382 Uint8 Rloss; 383 Uint8 Gloss; 384 Uint8 Bloss; 385 Uint8 Aloss; 386 Uint8 Rshift; 387 Uint8 Gshift; 388 Uint8 Bshift; 389 Uint8 Ashift; 390 int refcount; 391 struct SDL_PixelFormat *next; 392 } SDL_PixelFormat; 393 394 /** 395 * Get the human readable name of a pixel format. 396 * 397 * \param format the pixel format to query. 398 * \returns the human readable name of the specified pixel format or 399 * `SDL_PIXELFORMAT_UNKNOWN` if the format isn't recognized. 400 * 401 * \since This function is available since SDL 2.0.0. 402 */ 403 extern DECLSPEC const char* SDLCALL SDL_GetPixelFormatName(Uint32 format); 404 405 /** 406 * Convert one of the enumerated pixel formats to a bpp value and RGBA masks. 407 * 408 * \param format one of the SDL_PixelFormatEnum values. 409 * \param bpp a bits per pixel value; usually 15, 16, or 32. 410 * \param Rmask a pointer filled in with the red mask for the format. 411 * \param Gmask a pointer filled in with the green mask for the format. 412 * \param Bmask a pointer filled in with the blue mask for the format. 413 * \param Amask a pointer filled in with the alpha mask for the format. 414 * \returns SDL_TRUE on success or SDL_FALSE if the conversion wasn't 415 * possible; call SDL_GetError() for more information. 416 * 417 * \since This function is available since SDL 2.0.0. 418 * 419 * \sa SDL_MasksToPixelFormatEnum 420 */ 421 extern DECLSPEC SDL_bool SDLCALL SDL_PixelFormatEnumToMasks(Uint32 format, 422 int *bpp, 423 Uint32 * Rmask, 424 Uint32 * Gmask, 425 Uint32 * Bmask, 426 Uint32 * Amask); 427 428 /** 429 * Convert a bpp value and RGBA masks to an enumerated pixel format. 430 * 431 * This will return `SDL_PIXELFORMAT_UNKNOWN` if the conversion wasn't 432 * possible. 433 * 434 * \param bpp a bits per pixel value; usually 15, 16, or 32. 435 * \param Rmask the red mask for the format. 436 * \param Gmask the green mask for the format. 437 * \param Bmask the blue mask for the format. 438 * \param Amask the alpha mask for the format. 439 * \returns one of the SDL_PixelFormatEnum values. 440 * 441 * \since This function is available since SDL 2.0.0. 442 * 443 * \sa SDL_PixelFormatEnumToMasks 444 */ 445 extern DECLSPEC Uint32 SDLCALL SDL_MasksToPixelFormatEnum(int bpp, 446 Uint32 Rmask, 447 Uint32 Gmask, 448 Uint32 Bmask, 449 Uint32 Amask); 450 451 /** 452 * Create an SDL_PixelFormat structure corresponding to a pixel format. 453 * 454 * Returned structure may come from a shared global cache (i.e. not newly 455 * allocated), and hence should not be modified, especially the palette. Weird 456 * errors such as `Blit combination not supported` may occur. 457 * 458 * \param pixel_format one of the SDL_PixelFormatEnum values. 459 * \returns the new SDL_PixelFormat structure or NULL on failure; call 460 * SDL_GetError() for more information. 461 * 462 * \since This function is available since SDL 2.0.0. 463 * 464 * \sa SDL_FreeFormat 465 */ 466 extern DECLSPEC SDL_PixelFormat * SDLCALL SDL_AllocFormat(Uint32 pixel_format); 467 468 /** 469 * Free an SDL_PixelFormat structure allocated by SDL_AllocFormat(). 470 * 471 * \param format the SDL_PixelFormat structure to free. 472 * 473 * \since This function is available since SDL 2.0.0. 474 * 475 * \sa SDL_AllocFormat 476 */ 477 extern DECLSPEC void SDLCALL SDL_FreeFormat(SDL_PixelFormat *format); 478 479 /** 480 * Create a palette structure with the specified number of color entries. 481 * 482 * The palette entries are initialized to white. 483 * 484 * \param ncolors represents the number of color entries in the color palette. 485 * \returns a new SDL_Palette structure on success or NULL on failure (e.g. if 486 * there wasn't enough memory); call SDL_GetError() for more 487 * information. 488 * 489 * \since This function is available since SDL 2.0.0. 490 * 491 * \sa SDL_FreePalette 492 */ 493 extern DECLSPEC SDL_Palette *SDLCALL SDL_AllocPalette(int ncolors); 494 495 /** 496 * Set the palette for a pixel format structure. 497 * 498 * \param format the SDL_PixelFormat structure that will use the palette. 499 * \param palette the SDL_Palette structure that will be used. 500 * \returns 0 on success or a negative error code on failure; call 501 * SDL_GetError() for more information. 502 * 503 * \since This function is available since SDL 2.0.0. 504 * 505 * \sa SDL_AllocPalette 506 * \sa SDL_FreePalette 507 */ 508 extern DECLSPEC int SDLCALL SDL_SetPixelFormatPalette(SDL_PixelFormat * format, 509 SDL_Palette *palette); 510 511 /** 512 * Set a range of colors in a palette. 513 * 514 * \param palette the SDL_Palette structure to modify. 515 * \param colors an array of SDL_Color structures to copy into the palette. 516 * \param firstcolor the index of the first palette entry to modify. 517 * \param ncolors the number of entries to modify. 518 * \returns 0 on success or a negative error code if not all of the colors 519 * could be set; call SDL_GetError() for more information. 520 * 521 * \since This function is available since SDL 2.0.0. 522 * 523 * \sa SDL_AllocPalette 524 * \sa SDL_CreateRGBSurface 525 */ 526 extern DECLSPEC int SDLCALL SDL_SetPaletteColors(SDL_Palette * palette, 527 const SDL_Color * colors, 528 int firstcolor, int ncolors); 529 530 /** 531 * Free a palette created with SDL_AllocPalette(). 532 * 533 * \param palette the SDL_Palette structure to be freed. 534 * 535 * \since This function is available since SDL 2.0.0. 536 * 537 * \sa SDL_AllocPalette 538 */ 539 extern DECLSPEC void SDLCALL SDL_FreePalette(SDL_Palette * palette); 540 541 /** 542 * Map an RGB triple to an opaque pixel value for a given pixel format. 543 * 544 * This function maps the RGB color value to the specified pixel format and 545 * returns the pixel value best approximating the given RGB color value for 546 * the given pixel format. 547 * 548 * If the format has a palette (8-bit) the index of the closest matching color 549 * in the palette will be returned. 550 * 551 * If the specified pixel format has an alpha component it will be returned as 552 * all 1 bits (fully opaque). 553 * 554 * If the pixel format bpp (color depth) is less than 32-bpp then the unused 555 * upper bits of the return value can safely be ignored (e.g., with a 16-bpp 556 * format the return value can be assigned to a Uint16, and similarly a Uint8 557 * for an 8-bpp format). 558 * 559 * \param format an SDL_PixelFormat structure describing the pixel format. 560 * \param r the red component of the pixel in the range 0-255. 561 * \param g the green component of the pixel in the range 0-255. 562 * \param b the blue component of the pixel in the range 0-255. 563 * \returns a pixel value. 564 * 565 * \since This function is available since SDL 2.0.0. 566 * 567 * \sa SDL_GetRGB 568 * \sa SDL_GetRGBA 569 * \sa SDL_MapRGBA 570 */ 571 extern DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormat * format, 572 Uint8 r, Uint8 g, Uint8 b); 573 574 /** 575 * Map an RGBA quadruple to a pixel value for a given pixel format. 576 * 577 * This function maps the RGBA color value to the specified pixel format and 578 * returns the pixel value best approximating the given RGBA color value for 579 * the given pixel format. 580 * 581 * If the specified pixel format has no alpha component the alpha value will 582 * be ignored (as it will be in formats with a palette). 583 * 584 * If the format has a palette (8-bit) the index of the closest matching color 585 * in the palette will be returned. 586 * 587 * If the pixel format bpp (color depth) is less than 32-bpp then the unused 588 * upper bits of the return value can safely be ignored (e.g., with a 16-bpp 589 * format the return value can be assigned to a Uint16, and similarly a Uint8 590 * for an 8-bpp format). 591 * 592 * \param format an SDL_PixelFormat structure describing the format of the 593 * pixel. 594 * \param r the red component of the pixel in the range 0-255. 595 * \param g the green component of the pixel in the range 0-255. 596 * \param b the blue component of the pixel in the range 0-255. 597 * \param a the alpha component of the pixel in the range 0-255. 598 * \returns a pixel value. 599 * 600 * \since This function is available since SDL 2.0.0. 601 * 602 * \sa SDL_GetRGB 603 * \sa SDL_GetRGBA 604 * \sa SDL_MapRGB 605 */ 606 extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormat * format, 607 Uint8 r, Uint8 g, Uint8 b, 608 Uint8 a); 609 610 /** 611 * Get RGB values from a pixel in the specified format. 612 * 613 * This function uses the entire 8-bit [0..255] range when converting color 614 * components from pixel formats with less than 8-bits per RGB component 615 * (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff, 616 * 0xff, 0xff] not [0xf8, 0xfc, 0xf8]). 617 * 618 * \param pixel a pixel value. 619 * \param format an SDL_PixelFormat structure describing the format of the 620 * pixel. 621 * \param r a pointer filled in with the red component. 622 * \param g a pointer filled in with the green component. 623 * \param b a pointer filled in with the blue component. 624 * 625 * \since This function is available since SDL 2.0.0. 626 * 627 * \sa SDL_GetRGBA 628 * \sa SDL_MapRGB 629 * \sa SDL_MapRGBA 630 */ 631 extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel, 632 const SDL_PixelFormat * format, 633 Uint8 * r, Uint8 * g, Uint8 * b); 634 635 /** 636 * Get RGBA values from a pixel in the specified format. 637 * 638 * This function uses the entire 8-bit [0..255] range when converting color 639 * components from pixel formats with less than 8-bits per RGB component 640 * (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff, 641 * 0xff, 0xff] not [0xf8, 0xfc, 0xf8]). 642 * 643 * If the surface has no alpha component, the alpha will be returned as 0xff 644 * (100% opaque). 645 * 646 * \param pixel a pixel value. 647 * \param format an SDL_PixelFormat structure describing the format of the 648 * pixel. 649 * \param r a pointer filled in with the red component. 650 * \param g a pointer filled in with the green component. 651 * \param b a pointer filled in with the blue component. 652 * \param a a pointer filled in with the alpha component. 653 * 654 * \since This function is available since SDL 2.0.0. 655 * 656 * \sa SDL_GetRGB 657 * \sa SDL_MapRGB 658 * \sa SDL_MapRGBA 659 */ 660 extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel, 661 const SDL_PixelFormat * format, 662 Uint8 * r, Uint8 * g, Uint8 * b, 663 Uint8 * a); 664 665 /** 666 * Calculate a 256 entry gamma ramp for a gamma value. 667 * 668 * \param gamma a gamma value where 0.0 is black and 1.0 is identity. 669 * \param ramp an array of 256 values filled in with the gamma ramp. 670 * 671 * \since This function is available since SDL 2.0.0. 672 * 673 * \sa SDL_SetWindowGammaRamp 674 */ 675 extern DECLSPEC void SDLCALL SDL_CalculateGammaRamp(float gamma, Uint16 * ramp); 676 677 678 /* Ends C function definitions when using C++ */ 679 #ifdef __cplusplus 680 } 681 #endif 682 #include "close_code.h" 683 684 #endif /* SDL_pixels_h_ */ 685 686 /* vi: set ts=4 sw=4 expandtab: */