include/SDL_pixels.h
author Sam Lantinga <slouken@libsdl.org>
Tue, 09 Jun 2009 04:34:50 +0000
changeset 3177 efe3b3971e4f
parent 3163 a252014ce27d
child 3407 d3baf5ac4e37
permissions -rw-r--r--
Fixed 4 bit-per-pixel definition. Thanks Mike!
     1 /*
     2     SDL - Simple DirectMedia Layer
     3     Copyright (C) 1997-2009 Sam Lantinga
     4 
     5     This library is free software; you can redistribute it and/or
     6     modify it under the terms of the GNU Lesser General Public
     7     License as published by the Free Software Foundation; either
     8     version 2.1 of the License, or (at your option) any later version.
     9 
    10     This library is distributed in the hope that it will be useful,
    11     but WITHOUT ANY WARRANTY; without even the implied warranty of
    12     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    13     Lesser General Public License for more details.
    14 
    15     You should have received a copy of the GNU Lesser General Public
    16     License along with this library; if not, write to the Free Software
    17     Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
    18 
    19     Sam Lantinga
    20     slouken@libsdl.org
    21 */
    22 
    23 /**
    24  * \file SDL_pixels.h
    25  *
    26  * Header for the enumerated pixel format definitions
    27  */
    28 
    29 #ifndef _SDL_pixels_h
    30 #define _SDL_pixels_h
    31 
    32 #include "begin_code.h"
    33 /* Set up for C function definitions, even when using C++ */
    34 #ifdef __cplusplus
    35 /* *INDENT-OFF* */
    36 extern "C" {
    37 /* *INDENT-ON* */
    38 #endif
    39 
    40 /* Transparency definitions: These define alpha as the opacity of a surface */
    41 #define SDL_ALPHA_OPAQUE 255
    42 #define SDL_ALPHA_TRANSPARENT 0
    43 
    44 enum
    45 {                               /* Pixel type */
    46     SDL_PIXELTYPE_UNKNOWN,
    47     SDL_PIXELTYPE_INDEX1,
    48     SDL_PIXELTYPE_INDEX4,
    49     SDL_PIXELTYPE_INDEX8,
    50     SDL_PIXELTYPE_PACKED8,
    51     SDL_PIXELTYPE_PACKED16,
    52     SDL_PIXELTYPE_PACKED32,
    53     SDL_PIXELTYPE_ARRAYU8,
    54     SDL_PIXELTYPE_ARRAYU16,
    55     SDL_PIXELTYPE_ARRAYU32,
    56     SDL_PIXELTYPE_ARRAYF16,
    57     SDL_PIXELTYPE_ARRAYF32
    58 };
    59 
    60 enum
    61 {                               /* bitmap pixel order, high bit -> low bit */
    62     SDL_BITMAPORDER_NONE,
    63     SDL_BITMAPORDER_4321,
    64     SDL_BITMAPORDER_1234
    65 };
    66 enum
    67 {                               /* packed component order, high bit -> low bit */
    68     SDL_PACKEDORDER_NONE,
    69     SDL_PACKEDORDER_XRGB,
    70     SDL_PACKEDORDER_RGBX,
    71     SDL_PACKEDORDER_ARGB,
    72     SDL_PACKEDORDER_RGBA,
    73     SDL_PACKEDORDER_XBGR,
    74     SDL_PACKEDORDER_BGRX,
    75     SDL_PACKEDORDER_ABGR,
    76     SDL_PACKEDORDER_BGRA
    77 };
    78 enum
    79 {                               /* array component order, low byte -> high byte */
    80     SDL_ARRAYORDER_NONE,
    81     SDL_ARRAYORDER_RGB,
    82     SDL_ARRAYORDER_RGBA,
    83     SDL_ARRAYORDER_ARGB,
    84     SDL_ARRAYORDER_BGR,
    85     SDL_ARRAYORDER_BGRA,
    86     SDL_ARRAYORDER_ABGR
    87 };
    88 
    89 enum
    90 {                               /* Packed component layout */
    91     SDL_PACKEDLAYOUT_NONE,
    92     SDL_PACKEDLAYOUT_332,
    93     SDL_PACKEDLAYOUT_4444,
    94     SDL_PACKEDLAYOUT_1555,
    95     SDL_PACKEDLAYOUT_5551,
    96     SDL_PACKEDLAYOUT_565,
    97     SDL_PACKEDLAYOUT_8888,
    98     SDL_PACKEDLAYOUT_2101010,
    99     SDL_PACKEDLAYOUT_1010102
   100 };
   101 
   102 #define SDL_DEFINE_PIXELFOURCC(A, B, C, D) \
   103     ((A) | ((B) << 8) | ((C) << 16) | ((D) << 24))
   104 
   105 #define SDL_DEFINE_PIXELFORMAT(type, order, layout, bits, bytes) \
   106     ((1 << 31) | ((type) << 24) | ((order) << 20) | ((layout) << 16) | \
   107      ((bits) << 8) | ((bytes) << 0))
   108 
   109 #define SDL_PIXELTYPE(X)	(((X) >> 24) & 0x0F)
   110 #define SDL_PIXELORDER(X)	(((X) >> 20) & 0x0F)
   111 #define SDL_PIXELLAYOUT(X)	(((X) >> 16) & 0x0F)
   112 #define SDL_BITSPERPIXEL(X)	(((X) >> 8) & 0xFF)
   113 #define SDL_BYTESPERPIXEL(X)	(((X) >> 0) & 0xFF)
   114 
   115 #define SDL_ISPIXELFORMAT_INDEXED(format)   \
   116     ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX1) || \
   117      (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX4) || \
   118      (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX8))
   119 
   120 #define SDL_ISPIXELFORMAT_ALPHA(format)   \
   121     ((SDL_PIXELORDER(format) == SDL_PACKEDORDER_ARGB) || \
   122      (SDL_PIXELORDER(format) == SDL_PACKEDORDER_RGBA) || \
   123      (SDL_PIXELORDER(format) == SDL_PACKEDORDER_ABGR) || \
   124      (SDL_PIXELORDER(format) == SDL_PACKEDORDER_BGRA))
   125 
   126 #define SDL_ISPIXELFORMAT_FOURCC(format)    \
   127     ((format) && !((format) & 0x80000000))
   128 
   129 enum
   130 {
   131     SDL_PIXELFORMAT_UNKNOWN,
   132     SDL_PIXELFORMAT_INDEX1LSB =
   133         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX1, SDL_BITMAPORDER_1234, 0,
   134                                1, 0),
   135     SDL_PIXELFORMAT_INDEX1MSB =
   136         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX1, SDL_BITMAPORDER_4321, 0,
   137                                1, 0),
   138     SDL_PIXELFORMAT_INDEX4LSB =
   139         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX4, SDL_BITMAPORDER_1234, 0,
   140                                4, 0),
   141     SDL_PIXELFORMAT_INDEX4MSB =
   142         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX4, SDL_BITMAPORDER_4321, 0,
   143                                4, 0),
   144     SDL_PIXELFORMAT_INDEX8 =
   145         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX8, 0, 0, 8, 1),
   146     SDL_PIXELFORMAT_RGB332 =
   147         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED8, SDL_PACKEDORDER_XRGB,
   148                                SDL_PACKEDLAYOUT_332, 8, 1),
   149     SDL_PIXELFORMAT_RGB444 =
   150         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB,
   151                                SDL_PACKEDLAYOUT_4444, 12, 2),
   152     SDL_PIXELFORMAT_RGB555 =
   153         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB,
   154                                SDL_PACKEDLAYOUT_1555, 15, 2),
   155     SDL_PIXELFORMAT_BGR555 =
   156         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XBGR,
   157                                SDL_PACKEDLAYOUT_1555, 15, 2),
   158     SDL_PIXELFORMAT_ARGB4444 =
   159         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ARGB,
   160                                SDL_PACKEDLAYOUT_4444, 16, 2),
   161     SDL_PIXELFORMAT_ABGR4444 =
   162         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ABGR,
   163                                SDL_PACKEDLAYOUT_4444, 16, 2),
   164     SDL_PIXELFORMAT_ARGB1555 =
   165         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ARGB,
   166                                SDL_PACKEDLAYOUT_1555, 16, 2),
   167     SDL_PIXELFORMAT_ABGR1555 =
   168         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ABGR,
   169                                SDL_PACKEDLAYOUT_1555, 16, 2),
   170     SDL_PIXELFORMAT_RGB565 =
   171         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB,
   172                                SDL_PACKEDLAYOUT_565, 16, 2),
   173     SDL_PIXELFORMAT_BGR565 =
   174         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XBGR,
   175                                SDL_PACKEDLAYOUT_565, 16, 2),
   176     SDL_PIXELFORMAT_RGB24 =
   177         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU8, SDL_ARRAYORDER_RGB, 0,
   178                                24, 3),
   179     SDL_PIXELFORMAT_BGR24 =
   180         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU8, SDL_ARRAYORDER_BGR, 0,
   181                                24, 3),
   182     SDL_PIXELFORMAT_RGB888 =
   183         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XRGB,
   184                                SDL_PACKEDLAYOUT_8888, 24, 4),
   185     SDL_PIXELFORMAT_BGR888 =
   186         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XBGR,
   187                                SDL_PACKEDLAYOUT_8888, 24, 4),
   188     SDL_PIXELFORMAT_ARGB8888 =
   189         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ARGB,
   190                                SDL_PACKEDLAYOUT_8888, 32, 4),
   191     SDL_PIXELFORMAT_RGBA8888 =
   192         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_RGBA,
   193                                SDL_PACKEDLAYOUT_8888, 32, 4),
   194     SDL_PIXELFORMAT_ABGR8888 =
   195         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ABGR,
   196                                SDL_PACKEDLAYOUT_8888, 32, 4),
   197     SDL_PIXELFORMAT_BGRA8888 =
   198         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_BGRA,
   199                                SDL_PACKEDLAYOUT_8888, 32, 4),
   200     SDL_PIXELFORMAT_ARGB2101010 =
   201         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ARGB,
   202                                SDL_PACKEDLAYOUT_2101010, 32, 4),
   203 
   204     SDL_PIXELFORMAT_YV12 =      /* Planar mode: Y + V + U  (3 planes) */
   205         SDL_DEFINE_PIXELFOURCC('Y', 'V', '1', '2'),
   206     SDL_PIXELFORMAT_IYUV =      /* Planar mode: Y + U + V  (3 planes) */
   207         SDL_DEFINE_PIXELFOURCC('I', 'Y', 'U', 'V'),
   208     SDL_PIXELFORMAT_YUY2 =      /* Packed mode: Y0+U0+Y1+V0 (1 plane) */
   209         SDL_DEFINE_PIXELFOURCC('Y', 'U', 'Y', '2'),
   210     SDL_PIXELFORMAT_UYVY =      /* Packed mode: U0+Y0+V0+Y1 (1 plane) */
   211         SDL_DEFINE_PIXELFOURCC('U', 'Y', 'V', 'Y'),
   212     SDL_PIXELFORMAT_YVYU =      /* Packed mode: Y0+V0+Y1+U0 (1 plane) */
   213         SDL_DEFINE_PIXELFOURCC('Y', 'V', 'Y', 'U')
   214 };
   215 
   216 typedef struct SDL_Color
   217 {
   218     Uint8 r;
   219     Uint8 g;
   220     Uint8 b;
   221     Uint8 unused;
   222 } SDL_Color;
   223 #define SDL_Colour SDL_Color
   224 
   225 typedef struct SDL_Palette SDL_Palette;
   226 typedef int (*SDL_PaletteChangedFunc) (void *userdata, SDL_Palette * palette);
   227 
   228 typedef struct SDL_PaletteWatch
   229 {
   230     SDL_PaletteChangedFunc callback;
   231     void *userdata;
   232     struct SDL_PaletteWatch *next;
   233 } SDL_PaletteWatch;
   234 
   235 struct SDL_Palette
   236 {
   237     int ncolors;
   238     SDL_Color *colors;
   239 
   240     int refcount;
   241     SDL_PaletteWatch *watch;
   242 };
   243 
   244 /* Everything in the pixel format structure is read-only */
   245 typedef struct SDL_PixelFormat
   246 {
   247     SDL_Palette *palette;
   248     Uint8 BitsPerPixel;
   249     Uint8 BytesPerPixel;
   250     Uint8 Rloss;
   251     Uint8 Gloss;
   252     Uint8 Bloss;
   253     Uint8 Aloss;
   254     Uint8 Rshift;
   255     Uint8 Gshift;
   256     Uint8 Bshift;
   257     Uint8 Ashift;
   258     Uint32 Rmask;
   259     Uint32 Gmask;
   260     Uint32 Bmask;
   261     Uint32 Amask;
   262 } SDL_PixelFormat;
   263 
   264 /**
   265  * \fn SDL_bool SDL_PixelFormatEnumToMasks(Uint32 format, int *bpp, Uint32 * Rmask, Uint32 * Gmask, Uint32 * Bmask, Uint32 * Amask)
   266  *
   267  * \brief Convert one of the enumerated pixel formats to a bpp and RGBA masks.
   268  *
   269  * \return SDL_TRUE, or SDL_FALSE if the conversion wasn't possible.
   270  *
   271  * \sa SDL_MasksToPixelFormatEnum()
   272  */
   273 extern DECLSPEC SDL_bool SDLCALL SDL_PixelFormatEnumToMasks(Uint32 format,
   274                                                             int *bpp,
   275                                                             Uint32 * Rmask,
   276                                                             Uint32 * Gmask,
   277                                                             Uint32 * Bmask,
   278                                                             Uint32 * Amask);
   279 
   280 /**
   281  * \fn Uint32 SDL_MasksToPixelFormatEnum(int bpp, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask)
   282  *
   283  * \brief Convert a bpp and RGBA masks to an enumerated pixel format.
   284  *
   285  * \return The pixel format, or SDL_PixelFormat_Unknown if the conversion wasn't possible.
   286  *
   287  * \sa SDL_PixelFormatEnumToMasks()
   288  */
   289 extern DECLSPEC Uint32 SDLCALL SDL_MasksToPixelFormatEnum(int bpp,
   290                                                           Uint32 Rmask,
   291                                                           Uint32 Gmask,
   292                                                           Uint32 Bmask,
   293                                                           Uint32 Amask);
   294 
   295 /**
   296  * \fn SDL_Palette *SDL_AllocPalette(int ncolors)
   297  *
   298  * \brief Create a palette structure with the specified number of color entries.
   299  *
   300  * \return A new palette, or NULL if there wasn't enough memory
   301  *
   302  * \note The palette entries are initialized to white.
   303  *
   304  * \sa SDL_FreePalette()
   305  */
   306 extern DECLSPEC SDL_Palette *SDLCALL SDL_AllocPalette(int ncolors);
   307 
   308 /**
   309  * \fn int SDL_AddPaletteWatch(SDL_Palette *palette, SDL_PaletteChangedFunc callback, void *userdata)
   310  *
   311  * \brief Add a callback function which is called when the palette changes.
   312  *
   313  * \sa SDL_DelPaletteWatch()
   314  */
   315 extern DECLSPEC int SDLCALL SDL_AddPaletteWatch(SDL_Palette * palette,
   316                                                 SDL_PaletteChangedFunc
   317                                                 callback, void *userdata);
   318 
   319 /**
   320  * \fn void SDL_DelPaletteWatch(SDL_Palette *palette, SDL_PaletteChangedFunc callback, void *userdata)
   321  *
   322  * \brief Remove a callback function previously added with SDL_AddPaletteWatch()
   323  *
   324  * \sa SDL_AddPaletteWatch()
   325  */
   326 extern DECLSPEC void SDLCALL SDL_DelPaletteWatch(SDL_Palette * palette,
   327                                                  SDL_PaletteChangedFunc
   328                                                  callback, void *userdata);
   329 
   330 /**
   331  * \fn int SDL_SetPaletteColors(SDL_Palette *palette, const SDL_Colors *colors, int firstcolor, int numcolors)
   332  *
   333  * \brief Set a range of colors in a palette.
   334  *
   335  * \param palette The palette to modify
   336  * \param colors An array of colors to copy into the palette
   337  * \param firstcolor The index of the first palette entry to modify
   338  * \param ncolors The number of entries to modify
   339  *
   340  * \return 0 on success, or -1 if not all of the colors could be set
   341  */
   342 extern DECLSPEC int SDLCALL SDL_SetPaletteColors(SDL_Palette * palette,
   343                                                  const SDL_Color * colors,
   344                                                  int firstcolor, int ncolors);
   345 
   346 /**
   347  * \fn void SDL_FreePalette(SDL_Palette *palette)
   348  *
   349  * \brief Free a palette created with SDL_AllocPalette()
   350  *
   351  * \sa SDL_AllocPalette()
   352  */
   353 extern DECLSPEC void SDLCALL SDL_FreePalette(SDL_Palette * palette);
   354 
   355 /**
   356  * \fn Uint32 SDL_MapRGB(const SDL_PixelFormat *format,
   357  *                       Uint8 r, Uint8 g, Uint8 b)
   358  *
   359  * \brief Maps an RGB triple to an opaque pixel value for a given pixel format
   360  *
   361  * \sa SDL_MapRGBA
   362  */
   363 extern DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormat * format,
   364                                           Uint8 r, Uint8 g, Uint8 b);
   365 
   366 /**
   367  * \fn Uint32 SDL_MapRGBA(const SDL_PixelFormat *fmt,
   368  *                        Uint8 r, Uint8 g, Uint8 b, Uint8 a)
   369  *
   370  * \brief Maps an RGBA quadruple to a pixel value for a given pixel format
   371  *
   372  * \sa SDL_MapRGB
   373  */
   374 extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormat * format,
   375                                            Uint8 r, Uint8 g, Uint8 b,
   376                                            Uint8 a);
   377 
   378 /**
   379  * \fn void SDL_GetRGB(Uint32 pixel, const SDL_PixelFormat * format,
   380  *                     Uint8 * r, Uint8 * g, Uint8 * b)
   381  *
   382  * \brief Maps a pixel value into the RGB components for a given pixel format
   383  *
   384  * \sa SDL_GetRGBA
   385  */
   386 extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel,
   387                                         const SDL_PixelFormat * format,
   388                                         Uint8 * r, Uint8 * g, Uint8 * b);
   389 
   390 /**
   391  * \fn void SDL_GetRGBA(Uint32 pixel, const SDL_PixelFormat * format,
   392  *                      Uint8 * r, Uint8 * g, Uint8 * b, Uint8 * a)
   393  *
   394  * \brief Maps a pixel value into the RGBA components for a given pixel format
   395  *
   396  * \sa SDL_GetRGB
   397  */
   398 extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel,
   399                                          const SDL_PixelFormat * format,
   400                                          Uint8 * r, Uint8 * g, Uint8 * b,
   401                                          Uint8 * a);
   402 
   403 /* Ends C function definitions when using C++ */
   404 #ifdef __cplusplus
   405 /* *INDENT-OFF* */
   406 }
   407 /* *INDENT-ON* */
   408 #endif
   409 #include "close_code.h"
   410 
   411 #endif /* _SDL_pixels_h */
   412 
   413 /* vi: set ts=4 sw=4 expandtab: */