include/SDL_pixels.h
author Sam Lantinga <slouken@libsdl.org>
Thu, 03 Feb 2011 00:19:40 -0800
changeset 5156 307ccc9c135e
parent 4982 660d3a432102
child 5262 b530ef003506
permissions -rw-r--r--
Made it possible to create a texture of any format, even if not supported by the renderer.
This allows me to reduce the set of formats supported by the renderers to the most optimal set, for a nice speed boost.
     1 /*
     2     SDL - Simple DirectMedia Layer
     3     Copyright (C) 1997-2010 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 /**
    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 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 
    67 /** Bitmap pixel order, high bit -> low bit. */
    68 enum
    69 {
    70     SDL_BITMAPORDER_NONE,
    71     SDL_BITMAPORDER_4321,
    72     SDL_BITMAPORDER_1234
    73 };
    74 
    75 /** Packed component order, high bit -> low bit. */
    76 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 };
    88 
    89 /** Array component order, low byte -> high byte. */
    90 enum
    91 {
    92     SDL_ARRAYORDER_NONE,
    93     SDL_ARRAYORDER_RGB,
    94     SDL_ARRAYORDER_RGBA,
    95     SDL_ARRAYORDER_ARGB,
    96     SDL_ARRAYORDER_BGR,
    97     SDL_ARRAYORDER_BGRA,
    98     SDL_ARRAYORDER_ABGR
    99 };
   100 
   101 /** Packed component layout. */
   102 enum
   103 {
   104     SDL_PACKEDLAYOUT_NONE,
   105     SDL_PACKEDLAYOUT_332,
   106     SDL_PACKEDLAYOUT_4444,
   107     SDL_PACKEDLAYOUT_1555,
   108     SDL_PACKEDLAYOUT_5551,
   109     SDL_PACKEDLAYOUT_565,
   110     SDL_PACKEDLAYOUT_8888,
   111     SDL_PACKEDLAYOUT_2101010,
   112     SDL_PACKEDLAYOUT_1010102
   113 };
   114 
   115 #define SDL_DEFINE_PIXELFOURCC(A, B, C, D) SDL_FOURCC(A, B, C, D)
   116 
   117 #define SDL_DEFINE_PIXELFORMAT(type, order, layout, bits, bytes) \
   118     ((1 << 31) | ((type) << 24) | ((order) << 20) | ((layout) << 16) | \
   119      ((bits) << 8) | ((bytes) << 0))
   120 
   121 #define SDL_PIXELTYPE(X)	(((X) >> 24) & 0x0F)
   122 #define SDL_PIXELORDER(X)	(((X) >> 20) & 0x0F)
   123 #define SDL_PIXELLAYOUT(X)	(((X) >> 16) & 0x0F)
   124 #define SDL_BITSPERPIXEL(X)	(((X) >> 8) & 0xFF)
   125 #define SDL_BYTESPERPIXEL(X) \
   126     (SDL_ISPIXELFORMAT_FOURCC(X) ? \
   127         ((((X) == SDL_PIXELFORMAT_YV12) || \
   128           ((X) == SDL_PIXELFORMAT_IYUV) || \
   129           ((X) == SDL_PIXELFORMAT_YUY2) || \
   130           ((X) == SDL_PIXELFORMAT_UYVY) || \
   131           ((X) == SDL_PIXELFORMAT_YVYU)) ? 2 : 1) : (((X) >> 0) & 0xFF))
   132 
   133 #define SDL_ISPIXELFORMAT_INDEXED(format)   \
   134     (!SDL_ISPIXELFORMAT_FOURCC(format) && \
   135      ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX1) || \
   136       (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX4) || \
   137       (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX8)))
   138 
   139 #define SDL_ISPIXELFORMAT_ALPHA(format)   \
   140     (!SDL_ISPIXELFORMAT_FOURCC(format) && \
   141      ((SDL_PIXELORDER(format) == SDL_PACKEDORDER_ARGB) || \
   142       (SDL_PIXELORDER(format) == SDL_PACKEDORDER_RGBA) || \
   143       (SDL_PIXELORDER(format) == SDL_PACKEDORDER_ABGR) || \
   144       (SDL_PIXELORDER(format) == SDL_PACKEDORDER_BGRA)))
   145 
   146 #define SDL_ISPIXELFORMAT_FOURCC(format)    \
   147     ((format) && !((format) & 0x80000000))
   148 
   149 /* Note: If you modify this list, update SDL_GetPixelFormatName() */
   150 enum
   151 {
   152     SDL_PIXELFORMAT_UNKNOWN,
   153     SDL_PIXELFORMAT_INDEX1LSB =
   154         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX1, SDL_BITMAPORDER_1234, 0,
   155                                1, 0),
   156     SDL_PIXELFORMAT_INDEX1MSB =
   157         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX1, SDL_BITMAPORDER_4321, 0,
   158                                1, 0),
   159     SDL_PIXELFORMAT_INDEX4LSB =
   160         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX4, SDL_BITMAPORDER_1234, 0,
   161                                4, 0),
   162     SDL_PIXELFORMAT_INDEX4MSB =
   163         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX4, SDL_BITMAPORDER_4321, 0,
   164                                4, 0),
   165     SDL_PIXELFORMAT_INDEX8 =
   166         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX8, 0, 0, 8, 1),
   167     SDL_PIXELFORMAT_RGB332 =
   168         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED8, SDL_PACKEDORDER_XRGB,
   169                                SDL_PACKEDLAYOUT_332, 8, 1),
   170     SDL_PIXELFORMAT_RGB444 =
   171         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB,
   172                                SDL_PACKEDLAYOUT_4444, 12, 2),
   173     SDL_PIXELFORMAT_RGB555 =
   174         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB,
   175                                SDL_PACKEDLAYOUT_1555, 15, 2),
   176     SDL_PIXELFORMAT_BGR555 =
   177         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XBGR,
   178                                SDL_PACKEDLAYOUT_1555, 15, 2),
   179     SDL_PIXELFORMAT_ARGB4444 =
   180         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ARGB,
   181                                SDL_PACKEDLAYOUT_4444, 16, 2),
   182     SDL_PIXELFORMAT_RGBA4444 =
   183         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_RGBA,
   184                                SDL_PACKEDLAYOUT_4444, 16, 2),
   185     SDL_PIXELFORMAT_ABGR4444 =
   186         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ABGR,
   187                                SDL_PACKEDLAYOUT_4444, 16, 2),
   188     SDL_PIXELFORMAT_BGRA4444 =
   189         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_BGRA,
   190                                SDL_PACKEDLAYOUT_4444, 16, 2),
   191     SDL_PIXELFORMAT_ARGB1555 =
   192         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ARGB,
   193                                SDL_PACKEDLAYOUT_1555, 16, 2),
   194     SDL_PIXELFORMAT_RGBA5551 =
   195         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_RGBA,
   196                                SDL_PACKEDLAYOUT_5551, 16, 2),
   197     SDL_PIXELFORMAT_ABGR1555 =
   198         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ABGR,
   199                                SDL_PACKEDLAYOUT_1555, 16, 2),
   200     SDL_PIXELFORMAT_BGRA5551 =
   201         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_BGRA,
   202                                SDL_PACKEDLAYOUT_5551, 16, 2),
   203     SDL_PIXELFORMAT_RGB565 =
   204         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB,
   205                                SDL_PACKEDLAYOUT_565, 16, 2),
   206     SDL_PIXELFORMAT_BGR565 =
   207         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XBGR,
   208                                SDL_PACKEDLAYOUT_565, 16, 2),
   209     SDL_PIXELFORMAT_RGB24 =
   210         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU8, SDL_ARRAYORDER_RGB, 0,
   211                                24, 3),
   212     SDL_PIXELFORMAT_BGR24 =
   213         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU8, SDL_ARRAYORDER_BGR, 0,
   214                                24, 3),
   215     SDL_PIXELFORMAT_RGB888 =
   216         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XRGB,
   217                                SDL_PACKEDLAYOUT_8888, 24, 4),
   218     SDL_PIXELFORMAT_BGR888 =
   219         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XBGR,
   220                                SDL_PACKEDLAYOUT_8888, 24, 4),
   221     SDL_PIXELFORMAT_ARGB8888 =
   222         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ARGB,
   223                                SDL_PACKEDLAYOUT_8888, 32, 4),
   224     SDL_PIXELFORMAT_RGBA8888 =
   225         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_RGBA,
   226                                SDL_PACKEDLAYOUT_8888, 32, 4),
   227     SDL_PIXELFORMAT_ABGR8888 =
   228         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ABGR,
   229                                SDL_PACKEDLAYOUT_8888, 32, 4),
   230     SDL_PIXELFORMAT_BGRA8888 =
   231         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_BGRA,
   232                                SDL_PACKEDLAYOUT_8888, 32, 4),
   233     SDL_PIXELFORMAT_ARGB2101010 =
   234         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ARGB,
   235                                SDL_PACKEDLAYOUT_2101010, 32, 4),
   236 
   237     SDL_PIXELFORMAT_YV12 =      /**< Planar mode: Y + V + U  (3 planes) */
   238         SDL_DEFINE_PIXELFOURCC('Y', 'V', '1', '2'),
   239     SDL_PIXELFORMAT_IYUV =      /**< Planar mode: Y + U + V  (3 planes) */
   240         SDL_DEFINE_PIXELFOURCC('I', 'Y', 'U', 'V'),
   241     SDL_PIXELFORMAT_YUY2 =      /**< Packed mode: Y0+U0+Y1+V0 (1 plane) */
   242         SDL_DEFINE_PIXELFOURCC('Y', 'U', 'Y', '2'),
   243     SDL_PIXELFORMAT_UYVY =      /**< Packed mode: U0+Y0+V0+Y1 (1 plane) */
   244         SDL_DEFINE_PIXELFOURCC('U', 'Y', 'V', 'Y'),
   245     SDL_PIXELFORMAT_YVYU =      /**< Packed mode: Y0+V0+Y1+U0 (1 plane) */
   246         SDL_DEFINE_PIXELFOURCC('Y', 'V', 'Y', 'U')
   247 };
   248 
   249 typedef struct SDL_Color
   250 {
   251     Uint8 r;
   252     Uint8 g;
   253     Uint8 b;
   254     Uint8 unused;
   255 } SDL_Color;
   256 #define SDL_Colour SDL_Color
   257 
   258 typedef struct SDL_Palette SDL_Palette;
   259 typedef int (*SDL_PaletteChangedFunc) (void *userdata, SDL_Palette * palette);
   260 typedef struct SDL_PaletteWatch SDL_PaletteWatch;
   261 
   262 struct SDL_Palette
   263 {
   264     int ncolors;
   265     SDL_Color *colors;
   266 
   267     int refcount;
   268     SDL_PaletteWatch *watch;
   269 };
   270 
   271 /**
   272  *  \note Everything in the pixel format structure is read-only.
   273  */
   274 typedef struct SDL_PixelFormat
   275 {
   276     SDL_Palette *palette;
   277     Uint8 BitsPerPixel;
   278     Uint8 BytesPerPixel;
   279     Uint8 Rloss;
   280     Uint8 Gloss;
   281     Uint8 Bloss;
   282     Uint8 Aloss;
   283     Uint8 Rshift;
   284     Uint8 Gshift;
   285     Uint8 Bshift;
   286     Uint8 Ashift;
   287     Uint32 Rmask;
   288     Uint32 Gmask;
   289     Uint32 Bmask;
   290     Uint32 Amask;
   291 } SDL_PixelFormat;
   292 
   293 /**
   294  * \brief Get the human readable name of a pixel format
   295  */
   296 extern DECLSPEC const char* SDLCALL SDL_GetPixelFormatName(Uint32 format);
   297 
   298 /**
   299  *  \brief Convert one of the enumerated pixel formats to a bpp and RGBA masks.
   300  *  
   301  *  \return SDL_TRUE, or SDL_FALSE if the conversion wasn't possible.
   302  *  
   303  *  \sa SDL_MasksToPixelFormatEnum()
   304  */
   305 extern DECLSPEC SDL_bool SDLCALL SDL_PixelFormatEnumToMasks(Uint32 format,
   306                                                             int *bpp,
   307                                                             Uint32 * Rmask,
   308                                                             Uint32 * Gmask,
   309                                                             Uint32 * Bmask,
   310                                                             Uint32 * Amask);
   311 
   312 /**
   313  *  \brief Convert a bpp and RGBA masks to an enumerated pixel format.
   314  *  
   315  *  \return The pixel format, or ::SDL_PIXELFORMAT_UNKNOWN if the conversion 
   316  *          wasn't possible.
   317  *  
   318  *  \sa SDL_PixelFormatEnumToMasks()
   319  */
   320 extern DECLSPEC Uint32 SDLCALL SDL_MasksToPixelFormatEnum(int bpp,
   321                                                           Uint32 Rmask,
   322                                                           Uint32 Gmask,
   323                                                           Uint32 Bmask,
   324                                                           Uint32 Amask);
   325 
   326 /**
   327  *  \brief Create a palette structure with the specified number of color 
   328  *         entries.
   329  *  
   330  *  \return A new palette, or NULL if there wasn't enough memory.
   331  *  
   332  *  \note The palette entries are initialized to white.
   333  *  
   334  *  \sa SDL_FreePalette()
   335  */
   336 extern DECLSPEC SDL_Palette *SDLCALL SDL_AllocPalette(int ncolors);
   337 
   338 /**
   339  *  \brief Add a callback function which is called when the palette changes.
   340  *  
   341  *  \sa SDL_DelPaletteWatch()
   342  */
   343 extern DECLSPEC int SDLCALL SDL_AddPaletteWatch(SDL_Palette * palette,
   344                                                 SDL_PaletteChangedFunc
   345                                                 callback, void *userdata);
   346 
   347 /**
   348  *  \brief Remove a callback function previously added with 
   349  *         SDL_AddPaletteWatch().
   350  *  
   351  *  \sa SDL_AddPaletteWatch()
   352  */
   353 extern DECLSPEC void SDLCALL SDL_DelPaletteWatch(SDL_Palette * palette,
   354                                                  SDL_PaletteChangedFunc
   355                                                  callback, void *userdata);
   356 
   357 /**
   358  *  \brief Set a range of colors in a palette.
   359  *  
   360  *  \param palette    The palette to modify.
   361  *  \param colors     An array of colors to copy into the palette.
   362  *  \param firstcolor The index of the first palette entry to modify.
   363  *  \param ncolors    The number of entries to modify.
   364  *  
   365  *  \return 0 on success, or -1 if not all of the colors could be set.
   366  */
   367 extern DECLSPEC int SDLCALL SDL_SetPaletteColors(SDL_Palette * palette,
   368                                                  const SDL_Color * colors,
   369                                                  int firstcolor, int ncolors);
   370 
   371 /**
   372  *  \brief Free a palette created with SDL_AllocPalette().
   373  *  
   374  *  \sa SDL_AllocPalette()
   375  */
   376 extern DECLSPEC void SDLCALL SDL_FreePalette(SDL_Palette * palette);
   377 
   378 /**
   379  *  \brief Maps an RGB triple to an opaque pixel value for a given pixel format.
   380  *  
   381  *  \sa SDL_MapRGBA
   382  */
   383 extern DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormat * format,
   384                                           Uint8 r, Uint8 g, Uint8 b);
   385 
   386 /**
   387  *  \brief Maps an RGBA quadruple to a pixel value for a given pixel format.
   388  *  
   389  *  \sa SDL_MapRGB
   390  */
   391 extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormat * format,
   392                                            Uint8 r, Uint8 g, Uint8 b,
   393                                            Uint8 a);
   394 
   395 /**
   396  *  \brief Get the RGB components from a pixel of the specified format.
   397  *  
   398  *  \sa SDL_GetRGBA
   399  */
   400 extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel,
   401                                         const SDL_PixelFormat * format,
   402                                         Uint8 * r, Uint8 * g, Uint8 * b);
   403 
   404 /**
   405  *  \brief Get the RGBA components from a pixel of the specified format.
   406  *  
   407  *  \sa SDL_GetRGB
   408  */
   409 extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel,
   410                                          const SDL_PixelFormat * format,
   411                                          Uint8 * r, Uint8 * g, Uint8 * b,
   412                                          Uint8 * a);
   413 
   414 /* Ends C function definitions when using C++ */
   415 #ifdef __cplusplus
   416 /* *INDENT-OFF* */
   417 }
   418 /* *INDENT-ON* */
   419 #endif
   420 #include "close_code.h"
   421 
   422 #endif /* _SDL_pixels_h */
   423 
   424 /* vi: set ts=4 sw=4 expandtab: */