dep/sdl/include/SDL_pixels.h

   1 /*
   2   Simple DirectMedia Layer
   3   Copyright (C) 1997-2023 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 /**
 305  * The bits of this structure can be directly reinterpreted as an integer-packed
 306  * color which uses the SDL_PIXELFORMAT_RGBA32 format (SDL_PIXELFORMAT_ABGR8888
 307  * on little-endian systems and SDL_PIXELFORMAT_RGBA8888 on big-endian systems).
 308  */
 309 typedef struct SDL_Color
 310 {
 311     Uint8 r;
 312     Uint8 g;
 313     Uint8 b;
 314     Uint8 a;
 315 } SDL_Color;
 316 #define SDL_Colour SDL_Color
 317
 318 typedef struct SDL_Palette
 319 {
 320     int ncolors;
 321     SDL_Color *colors;
 322     Uint32 version;
 323     int refcount;
 324 } SDL_Palette;
 325
 326 /**
 327  *  \note Everything in the pixel format structure is read-only.
 328  */
 329 typedef struct SDL_PixelFormat
 330 {
 331     Uint32 format;
 332     SDL_Palette *palette;
 333     Uint8 BitsPerPixel;
 334     Uint8 BytesPerPixel;
 335     Uint8 padding[2];
 336     Uint32 Rmask;
 337     Uint32 Gmask;
 338     Uint32 Bmask;
 339     Uint32 Amask;
 340     Uint8 Rloss;
 341     Uint8 Gloss;
 342     Uint8 Bloss;
 343     Uint8 Aloss;
 344     Uint8 Rshift;
 345     Uint8 Gshift;
 346     Uint8 Bshift;
 347     Uint8 Ashift;
 348     int refcount;
 349     struct SDL_PixelFormat *next;
 350 } SDL_PixelFormat;
 351
 352 /**
 353  * Get the human readable name of a pixel format.
 354  *
 355  * \param format the pixel format to query
 356  * \returns the human readable name of the specified pixel format or
 357  *          `SDL_PIXELFORMAT_UNKNOWN` if the format isn't recognized.
 358  *
 359  * \since This function is available since SDL 2.0.0.
 360  */
 361 extern DECLSPEC const char* SDLCALL SDL_GetPixelFormatName(Uint32 format);
 362
 363 /**
 364  * Convert one of the enumerated pixel formats to a bpp value and RGBA masks.
 365  *
 366  * \param format one of the SDL_PixelFormatEnum values
 367  * \param bpp a bits per pixel value; usually 15, 16, or 32
 368  * \param Rmask a pointer filled in with the red mask for the format
 369  * \param Gmask a pointer filled in with the green mask for the format
 370  * \param Bmask a pointer filled in with the blue mask for the format
 371  * \param Amask a pointer filled in with the alpha mask for the format
 372  * \returns SDL_TRUE on success or SDL_FALSE if the conversion wasn't
 373  *          possible; call SDL_GetError() for more information.
 374  *
 375  * \since This function is available since SDL 2.0.0.
 376  *
 377  * \sa SDL_MasksToPixelFormatEnum
 378  */
 379 extern DECLSPEC SDL_bool SDLCALL SDL_PixelFormatEnumToMasks(Uint32 format,
 380                                                             int *bpp,
 381                                                             Uint32 * Rmask,
 382                                                             Uint32 * Gmask,
 383                                                             Uint32 * Bmask,
 384                                                             Uint32 * Amask);
 385
 386 /**
 387  * Convert a bpp value and RGBA masks to an enumerated pixel format.
 388  *
 389  * This will return `SDL_PIXELFORMAT_UNKNOWN` if the conversion wasn't
 390  * possible.
 391  *
 392  * \param bpp a bits per pixel value; usually 15, 16, or 32
 393  * \param Rmask the red mask for the format
 394  * \param Gmask the green mask for the format
 395  * \param Bmask the blue mask for the format
 396  * \param Amask the alpha mask for the format
 397  * \returns one of the SDL_PixelFormatEnum values
 398  *
 399  * \since This function is available since SDL 2.0.0.
 400  *
 401  * \sa SDL_PixelFormatEnumToMasks
 402  */
 403 extern DECLSPEC Uint32 SDLCALL SDL_MasksToPixelFormatEnum(int bpp,
 404                                                           Uint32 Rmask,
 405                                                           Uint32 Gmask,
 406                                                           Uint32 Bmask,
 407                                                           Uint32 Amask);
 408
 409 /**
 410  * Create an SDL_PixelFormat structure corresponding to a pixel format.
 411  *
 412  * Returned structure may come from a shared global cache (i.e. not newly
 413  * allocated), and hence should not be modified, especially the palette. Weird
 414  * errors such as `Blit combination not supported` may occur.
 415  *
 416  * \param pixel_format one of the SDL_PixelFormatEnum values
 417  * \returns the new SDL_PixelFormat structure or NULL on failure; call
 418  *          SDL_GetError() for more information.
 419  *
 420  * \since This function is available since SDL 2.0.0.
 421  *
 422  * \sa SDL_FreeFormat
 423  */
 424 extern DECLSPEC SDL_PixelFormat * SDLCALL SDL_AllocFormat(Uint32 pixel_format);
 425
 426 /**
 427  * Free an SDL_PixelFormat structure allocated by SDL_AllocFormat().
 428  *
 429  * \param format the SDL_PixelFormat structure to free
 430  *
 431  * \since This function is available since SDL 2.0.0.
 432  *
 433  * \sa SDL_AllocFormat
 434  */
 435 extern DECLSPEC void SDLCALL SDL_FreeFormat(SDL_PixelFormat *format);
 436
 437 /**
 438  * Create a palette structure with the specified number of color entries.
 439  *
 440  * The palette entries are initialized to white.
 441  *
 442  * \param ncolors represents the number of color entries in the color palette
 443  * \returns a new SDL_Palette structure on success or NULL on failure (e.g. if
 444  *          there wasn't enough memory); call SDL_GetError() for more
 445  *          information.
 446  *
 447  * \since This function is available since SDL 2.0.0.
 448  *
 449  * \sa SDL_FreePalette
 450  */
 451 extern DECLSPEC SDL_Palette *SDLCALL SDL_AllocPalette(int ncolors);
 452
 453 /**
 454  * Set the palette for a pixel format structure.
 455  *
 456  * \param format the SDL_PixelFormat structure that will use the palette
 457  * \param palette the SDL_Palette structure that will be used
 458  * \returns 0 on success or a negative error code on failure; call
 459  *          SDL_GetError() for more information.
 460  *
 461  * \since This function is available since SDL 2.0.0.
 462  *
 463  * \sa SDL_AllocPalette
 464  * \sa SDL_FreePalette
 465  */
 466 extern DECLSPEC int SDLCALL SDL_SetPixelFormatPalette(SDL_PixelFormat * format,
 467                                                       SDL_Palette *palette);
 468
 469 /**
 470  * Set a range of colors in a palette.
 471  *
 472  * \param palette the SDL_Palette structure to modify
 473  * \param colors an array of SDL_Color structures to copy into the palette
 474  * \param firstcolor the index of the first palette entry to modify
 475  * \param ncolors the number of entries to modify
 476  * \returns 0 on success or a negative error code if not all of the colors
 477  *          could be set; call SDL_GetError() for more information.
 478  *
 479  * \since This function is available since SDL 2.0.0.
 480  *
 481  * \sa SDL_AllocPalette
 482  * \sa SDL_CreateRGBSurface
 483  */
 484 extern DECLSPEC int SDLCALL SDL_SetPaletteColors(SDL_Palette * palette,
 485                                                  const SDL_Color * colors,
 486                                                  int firstcolor, int ncolors);
 487
 488 /**
 489  * Free a palette created with SDL_AllocPalette().
 490  *
 491  * \param palette the SDL_Palette structure to be freed
 492  *
 493  * \since This function is available since SDL 2.0.0.
 494  *
 495  * \sa SDL_AllocPalette
 496  */
 497 extern DECLSPEC void SDLCALL SDL_FreePalette(SDL_Palette * palette);
 498
 499 /**
 500  * Map an RGB triple to an opaque pixel value for a given pixel format.
 501  *
 502  * This function maps the RGB color value to the specified pixel format and
 503  * returns the pixel value best approximating the given RGB color value for
 504  * the given pixel format.
 505  *
 506  * If the format has a palette (8-bit) the index of the closest matching color
 507  * in the palette will be returned.
 508  *
 509  * If the specified pixel format has an alpha component it will be returned as
 510  * all 1 bits (fully opaque).
 511  *
 512  * If the pixel format bpp (color depth) is less than 32-bpp then the unused
 513  * upper bits of the return value can safely be ignored (e.g., with a 16-bpp
 514  * format the return value can be assigned to a Uint16, and similarly a Uint8
 515  * for an 8-bpp format).
 516  *
 517  * \param format an SDL_PixelFormat structure describing the pixel format
 518  * \param r the red component of the pixel in the range 0-255
 519  * \param g the green component of the pixel in the range 0-255
 520  * \param b the blue component of the pixel in the range 0-255
 521  * \returns a pixel value
 522  *
 523  * \since This function is available since SDL 2.0.0.
 524  *
 525  * \sa SDL_GetRGB
 526  * \sa SDL_GetRGBA
 527  * \sa SDL_MapRGBA
 528  */
 529 extern DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormat * format,
 530                                           Uint8 r, Uint8 g, Uint8 b);
 531
 532 /**
 533  * Map an RGBA quadruple to a pixel value for a given pixel format.
 534  *
 535  * This function maps the RGBA color value to the specified pixel format and
 536  * returns the pixel value best approximating the given RGBA color value for
 537  * the given pixel format.
 538  *
 539  * If the specified pixel format has no alpha component the alpha value will
 540  * be ignored (as it will be in formats with a palette).
 541  *
 542  * If the format has a palette (8-bit) the index of the closest matching color
 543  * in the palette will be returned.
 544  *
 545  * If the pixel format bpp (color depth) is less than 32-bpp then the unused
 546  * upper bits of the return value can safely be ignored (e.g., with a 16-bpp
 547  * format the return value can be assigned to a Uint16, and similarly a Uint8
 548  * for an 8-bpp format).
 549  *
 550  * \param format an SDL_PixelFormat structure describing the format of the
 551  *               pixel
 552  * \param r the red component of the pixel in the range 0-255
 553  * \param g the green component of the pixel in the range 0-255
 554  * \param b the blue component of the pixel in the range 0-255
 555  * \param a the alpha component of the pixel in the range 0-255
 556  * \returns a pixel value
 557  *
 558  * \since This function is available since SDL 2.0.0.
 559  *
 560  * \sa SDL_GetRGB
 561  * \sa SDL_GetRGBA
 562  * \sa SDL_MapRGB
 563  */
 564 extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormat * format,
 565                                            Uint8 r, Uint8 g, Uint8 b,
 566                                            Uint8 a);
 567
 568 /**
 569  * Get RGB values from a pixel in the specified format.
 570  *
 571  * This function uses the entire 8-bit [0..255] range when converting color
 572  * components from pixel formats with less than 8-bits per RGB component
 573  * (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff,
 574  * 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).
 575  *
 576  * \param pixel a pixel value
 577  * \param format an SDL_PixelFormat structure describing the format of the
 578  *               pixel
 579  * \param r a pointer filled in with the red component
 580  * \param g a pointer filled in with the green component
 581  * \param b a pointer filled in with the blue component
 582  *
 583  * \since This function is available since SDL 2.0.0.
 584  *
 585  * \sa SDL_GetRGBA
 586  * \sa SDL_MapRGB
 587  * \sa SDL_MapRGBA
 588  */
 589 extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel,
 590                                         const SDL_PixelFormat * format,
 591                                         Uint8 * r, Uint8 * g, Uint8 * b);
 592
 593 /**
 594  * Get RGBA values from a pixel in the specified format.
 595  *
 596  * This function uses the entire 8-bit [0..255] range when converting color
 597  * components from pixel formats with less than 8-bits per RGB component
 598  * (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff,
 599  * 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).
 600  *
 601  * If the surface has no alpha component, the alpha will be returned as 0xff
 602  * (100% opaque).
 603  *
 604  * \param pixel a pixel value
 605  * \param format an SDL_PixelFormat structure describing the format of the
 606  *               pixel
 607  * \param r a pointer filled in with the red component
 608  * \param g a pointer filled in with the green component
 609  * \param b a pointer filled in with the blue component
 610  * \param a a pointer filled in with the alpha component
 611  *
 612  * \since This function is available since SDL 2.0.0.
 613  *
 614  * \sa SDL_GetRGB
 615  * \sa SDL_MapRGB
 616  * \sa SDL_MapRGBA
 617  */
 618 extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel,
 619                                          const SDL_PixelFormat * format,
 620                                          Uint8 * r, Uint8 * g, Uint8 * b,
 621                                          Uint8 * a);
 622
 623 /**
 624  * Calculate a 256 entry gamma ramp for a gamma value.
 625  *
 626  * \param gamma a gamma value where 0.0 is black and 1.0 is identity
 627  * \param ramp an array of 256 values filled in with the gamma ramp
 628  *
 629  * \since This function is available since SDL 2.0.0.
 630  *
 631  * \sa SDL_SetWindowGammaRamp
 632  */
 633 extern DECLSPEC void SDLCALL SDL_CalculateGammaRamp(float gamma, Uint16 * ramp);
 634
 635
 636 /* Ends C function definitions when using C++ */
 637 #ifdef __cplusplus
 638 }
 639 #endif
 640 #include "close_code.h"
 641
 642 #endif /* SDL_pixels_h_ */
 643
 644 /* vi: set ts=4 sw=4 expandtab: */