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