include/SDL_pixels.h
author Sam Lantinga <slouken@libsdl.org>
Mon, 07 Mar 2011 00:30:05 -0800
changeset 5438 b705640cb34a
parent 5434 fb5e9db92a77
child 5466 006883d5fa51
permissions -rw-r--r--
Fixed bitmap order interpretation; SDL defaults to MSB ordering so a bitstream corresponds to a pixel stream.

The bitmap ordering is defined such that the numbering refers to the pixel index from left to right, and the number position refers to the bit position in the byte.

SDL_BITMAPORDER_4321 is the fourth pixel at the high bit and the first pixel at the low bit (LSBFirst)

SDL_BITMAPORDER_1234 is the first pixel at the high bit and the fourth pixel at the low bit (MSBFirst)
     1 /*
     2     SDL - Simple DirectMedia Layer
     3     Copyright (C) 1997-2011 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_YUY2) || \
   128           ((X) == SDL_PIXELFORMAT_UYVY) || \
   129           ((X) == SDL_PIXELFORMAT_YVYU)) ? 2 : 1) : (((X) >> 0) & 0xFF))
   130 
   131 #define SDL_ISPIXELFORMAT_INDEXED(format)   \
   132     (!SDL_ISPIXELFORMAT_FOURCC(format) && \
   133      ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX1) || \
   134       (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX4) || \
   135       (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX8)))
   136 
   137 #define SDL_ISPIXELFORMAT_ALPHA(format)   \
   138     (!SDL_ISPIXELFORMAT_FOURCC(format) && \
   139      ((SDL_PIXELORDER(format) == SDL_PACKEDORDER_ARGB) || \
   140       (SDL_PIXELORDER(format) == SDL_PACKEDORDER_RGBA) || \
   141       (SDL_PIXELORDER(format) == SDL_PACKEDORDER_ABGR) || \
   142       (SDL_PIXELORDER(format) == SDL_PACKEDORDER_BGRA)))
   143 
   144 #define SDL_ISPIXELFORMAT_FOURCC(format)    \
   145     ((format) && !((format) & 0x80000000))
   146 
   147 /* Note: If you modify this list, update SDL_GetPixelFormatName() */
   148 enum
   149 {
   150     SDL_PIXELFORMAT_UNKNOWN,
   151     SDL_PIXELFORMAT_INDEX1LSB =
   152         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX1, SDL_BITMAPORDER_4321, 0,
   153                                1, 0),
   154     SDL_PIXELFORMAT_INDEX1MSB =
   155         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX1, SDL_BITMAPORDER_1234, 0,
   156                                1, 0),
   157     SDL_PIXELFORMAT_INDEX4LSB =
   158         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX4, SDL_BITMAPORDER_4321, 0,
   159                                4, 0),
   160     SDL_PIXELFORMAT_INDEX4MSB =
   161         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX4, SDL_BITMAPORDER_1234, 0,
   162                                4, 0),
   163     SDL_PIXELFORMAT_INDEX8 =
   164         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX8, 0, 0, 8, 1),
   165     SDL_PIXELFORMAT_RGB332 =
   166         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED8, SDL_PACKEDORDER_XRGB,
   167                                SDL_PACKEDLAYOUT_332, 8, 1),
   168     SDL_PIXELFORMAT_RGB444 =
   169         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB,
   170                                SDL_PACKEDLAYOUT_4444, 12, 2),
   171     SDL_PIXELFORMAT_RGB555 =
   172         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB,
   173                                SDL_PACKEDLAYOUT_1555, 15, 2),
   174     SDL_PIXELFORMAT_BGR555 =
   175         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XBGR,
   176                                SDL_PACKEDLAYOUT_1555, 15, 2),
   177     SDL_PIXELFORMAT_ARGB4444 =
   178         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ARGB,
   179                                SDL_PACKEDLAYOUT_4444, 16, 2),
   180     SDL_PIXELFORMAT_RGBA4444 =
   181         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_RGBA,
   182                                SDL_PACKEDLAYOUT_4444, 16, 2),
   183     SDL_PIXELFORMAT_ABGR4444 =
   184         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ABGR,
   185                                SDL_PACKEDLAYOUT_4444, 16, 2),
   186     SDL_PIXELFORMAT_BGRA4444 =
   187         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_BGRA,
   188                                SDL_PACKEDLAYOUT_4444, 16, 2),
   189     SDL_PIXELFORMAT_ARGB1555 =
   190         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ARGB,
   191                                SDL_PACKEDLAYOUT_1555, 16, 2),
   192     SDL_PIXELFORMAT_RGBA5551 =
   193         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_RGBA,
   194                                SDL_PACKEDLAYOUT_5551, 16, 2),
   195     SDL_PIXELFORMAT_ABGR1555 =
   196         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ABGR,
   197                                SDL_PACKEDLAYOUT_1555, 16, 2),
   198     SDL_PIXELFORMAT_BGRA5551 =
   199         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_BGRA,
   200                                SDL_PACKEDLAYOUT_5551, 16, 2),
   201     SDL_PIXELFORMAT_RGB565 =
   202         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB,
   203                                SDL_PACKEDLAYOUT_565, 16, 2),
   204     SDL_PIXELFORMAT_BGR565 =
   205         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XBGR,
   206                                SDL_PACKEDLAYOUT_565, 16, 2),
   207     SDL_PIXELFORMAT_RGB24 =
   208         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU8, SDL_ARRAYORDER_RGB, 0,
   209                                24, 3),
   210     SDL_PIXELFORMAT_BGR24 =
   211         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU8, SDL_ARRAYORDER_BGR, 0,
   212                                24, 3),
   213     SDL_PIXELFORMAT_RGB888 =
   214         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XRGB,
   215                                SDL_PACKEDLAYOUT_8888, 24, 4),
   216     SDL_PIXELFORMAT_BGR888 =
   217         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XBGR,
   218                                SDL_PACKEDLAYOUT_8888, 24, 4),
   219     SDL_PIXELFORMAT_ARGB8888 =
   220         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ARGB,
   221                                SDL_PACKEDLAYOUT_8888, 32, 4),
   222     SDL_PIXELFORMAT_RGBA8888 =
   223         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_RGBA,
   224                                SDL_PACKEDLAYOUT_8888, 32, 4),
   225     SDL_PIXELFORMAT_ABGR8888 =
   226         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ABGR,
   227                                SDL_PACKEDLAYOUT_8888, 32, 4),
   228     SDL_PIXELFORMAT_BGRA8888 =
   229         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_BGRA,
   230                                SDL_PACKEDLAYOUT_8888, 32, 4),
   231     SDL_PIXELFORMAT_ARGB2101010 =
   232         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ARGB,
   233                                SDL_PACKEDLAYOUT_2101010, 32, 4),
   234 
   235     SDL_PIXELFORMAT_YV12 =      /**< Planar mode: Y + V + U  (3 planes) */
   236         SDL_DEFINE_PIXELFOURCC('Y', 'V', '1', '2'),
   237     SDL_PIXELFORMAT_IYUV =      /**< Planar mode: Y + U + V  (3 planes) */
   238         SDL_DEFINE_PIXELFOURCC('I', 'Y', 'U', 'V'),
   239     SDL_PIXELFORMAT_YUY2 =      /**< Packed mode: Y0+U0+Y1+V0 (1 plane) */
   240         SDL_DEFINE_PIXELFOURCC('Y', 'U', 'Y', '2'),
   241     SDL_PIXELFORMAT_UYVY =      /**< Packed mode: U0+Y0+V0+Y1 (1 plane) */
   242         SDL_DEFINE_PIXELFOURCC('U', 'Y', 'V', 'Y'),
   243     SDL_PIXELFORMAT_YVYU =      /**< Packed mode: Y0+V0+Y1+U0 (1 plane) */
   244         SDL_DEFINE_PIXELFOURCC('Y', 'V', 'Y', 'U')
   245 };
   246 
   247 typedef struct SDL_Color
   248 {
   249     Uint8 r;
   250     Uint8 g;
   251     Uint8 b;
   252     Uint8 unused;
   253 } SDL_Color;
   254 #define SDL_Colour SDL_Color
   255 
   256 typedef struct SDL_Palette
   257 {
   258     int ncolors;
   259     SDL_Color *colors;
   260     Uint32 version;
   261     int refcount;
   262 } SDL_Palette;
   263 
   264 /**
   265  *  \note Everything in the pixel format structure is read-only.
   266  */
   267 typedef struct SDL_PixelFormat
   268 {
   269     Uint32 format;
   270     SDL_Palette *palette;
   271     Uint8 BitsPerPixel;
   272     Uint8 BytesPerPixel;
   273     Uint8 padding[2];
   274     Uint32 Rmask;
   275     Uint32 Gmask;
   276     Uint32 Bmask;
   277     Uint32 Amask;
   278     Uint8 Rloss;
   279     Uint8 Gloss;
   280     Uint8 Bloss;
   281     Uint8 Aloss;
   282     Uint8 Rshift;
   283     Uint8 Gshift;
   284     Uint8 Bshift;
   285     Uint8 Ashift;
   286     int refcount;
   287     struct SDL_PixelFormat *next;
   288 } SDL_PixelFormat;
   289 
   290 /**
   291  * \brief Get the human readable name of a pixel format
   292  */
   293 extern DECLSPEC const char* SDLCALL SDL_GetPixelFormatName(Uint32 format);
   294 
   295 /**
   296  *  \brief Convert one of the enumerated pixel formats to a bpp and RGBA masks.
   297  *  
   298  *  \return SDL_TRUE, or SDL_FALSE if the conversion wasn't possible.
   299  *  
   300  *  \sa SDL_MasksToPixelFormatEnum()
   301  */
   302 extern DECLSPEC SDL_bool SDLCALL SDL_PixelFormatEnumToMasks(Uint32 format,
   303                                                             int *bpp,
   304                                                             Uint32 * Rmask,
   305                                                             Uint32 * Gmask,
   306                                                             Uint32 * Bmask,
   307                                                             Uint32 * Amask);
   308 
   309 /**
   310  *  \brief Convert a bpp and RGBA masks to an enumerated pixel format.
   311  *  
   312  *  \return The pixel format, or ::SDL_PIXELFORMAT_UNKNOWN if the conversion 
   313  *          wasn't possible.
   314  *  
   315  *  \sa SDL_PixelFormatEnumToMasks()
   316  */
   317 extern DECLSPEC Uint32 SDLCALL SDL_MasksToPixelFormatEnum(int bpp,
   318                                                           Uint32 Rmask,
   319                                                           Uint32 Gmask,
   320                                                           Uint32 Bmask,
   321                                                           Uint32 Amask);
   322 
   323 /**
   324  *  \brief Create an SDL_PixelFormat structure from a pixel format enum.
   325  */
   326 extern DECLSPEC SDL_PixelFormat * SDLCALL SDL_AllocFormat(Uint32 pixel_format);
   327 
   328 /**
   329  *  \brief Free an SDL_PixelFormat structure.
   330  */
   331 extern DECLSPEC void SDLCALL SDL_FreeFormat(SDL_PixelFormat *format);
   332 
   333 /**
   334  *  \brief Create a palette structure with the specified number of color 
   335  *         entries.
   336  *  
   337  *  \return A new palette, or NULL if there wasn't enough memory.
   338  *  
   339  *  \note The palette entries are initialized to white.
   340  *  
   341  *  \sa SDL_FreePalette()
   342  */
   343 extern DECLSPEC SDL_Palette *SDLCALL SDL_AllocPalette(int ncolors);
   344 
   345 /**
   346  *  \brief Set the palette for a pixel format structure.
   347  */
   348 extern DECLSPEC int SDLCALL SDL_SetPixelFormatPalette(SDL_PixelFormat * format,
   349                                                       SDL_Palette *palette);
   350 
   351 /**
   352  *  \brief Set a range of colors in a palette.
   353  *  
   354  *  \param palette    The palette to modify.
   355  *  \param colors     An array of colors to copy into the palette.
   356  *  \param firstcolor The index of the first palette entry to modify.
   357  *  \param ncolors    The number of entries to modify.
   358  *  
   359  *  \return 0 on success, or -1 if not all of the colors could be set.
   360  */
   361 extern DECLSPEC int SDLCALL SDL_SetPaletteColors(SDL_Palette * palette,
   362                                                  const SDL_Color * colors,
   363                                                  int firstcolor, int ncolors);
   364 
   365 /**
   366  *  \brief Free a palette created with SDL_AllocPalette().
   367  *  
   368  *  \sa SDL_AllocPalette()
   369  */
   370 extern DECLSPEC void SDLCALL SDL_FreePalette(SDL_Palette * palette);
   371 
   372 /**
   373  *  \brief Maps an RGB triple to an opaque pixel value for a given pixel format.
   374  *  
   375  *  \sa SDL_MapRGBA
   376  */
   377 extern DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormat * format,
   378                                           Uint8 r, Uint8 g, Uint8 b);
   379 
   380 /**
   381  *  \brief Maps an RGBA quadruple to a pixel value for a given pixel format.
   382  *  
   383  *  \sa SDL_MapRGB
   384  */
   385 extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormat * format,
   386                                            Uint8 r, Uint8 g, Uint8 b,
   387                                            Uint8 a);
   388 
   389 /**
   390  *  \brief Get the RGB components from a pixel of the specified format.
   391  *  
   392  *  \sa SDL_GetRGBA
   393  */
   394 extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel,
   395                                         const SDL_PixelFormat * format,
   396                                         Uint8 * r, Uint8 * g, Uint8 * b);
   397 
   398 /**
   399  *  \brief Get the RGBA components from a pixel of the specified format.
   400  *  
   401  *  \sa SDL_GetRGB
   402  */
   403 extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel,
   404                                          const SDL_PixelFormat * format,
   405                                          Uint8 * r, Uint8 * g, Uint8 * b,
   406                                          Uint8 * a);
   407 
   408 /* Ends C function definitions when using C++ */
   409 #ifdef __cplusplus
   410 /* *INDENT-OFF* */
   411 }
   412 /* *INDENT-ON* */
   413 #endif
   414 #include "close_code.h"
   415 
   416 #endif /* _SDL_pixels_h */
   417 
   418 /* vi: set ts=4 sw=4 expandtab: */