SDL_pixels.h

00001 /*
00002   Simple DirectMedia Layer
00003   Copyright (C) 1997-2014 Sam Lantinga <slouken@libsdl.org>
00004 
00005   This software is provided 'as-is', without any express or implied
00006   warranty.  In no event will the authors be held liable for any damages
00007   arising from the use of this software.
00008 
00009   Permission is granted to anyone to use this software for any purpose,
00010   including commercial applications, and to alter it and redistribute it
00011   freely, subject to the following restrictions:
00012 
00013   1. The origin of this software must not be misrepresented; you must not
00014      claim that you wrote the original software. If you use this software
00015      in a product, an acknowledgment in the product documentation would be
00016      appreciated but is not required.
00017   2. Altered source versions must be plainly marked as such, and must not be
00018      misrepresented as being the original software.
00019   3. This notice may not be removed or altered from any source distribution.
00020 */
00021 
00022 /**
00023  *  \file SDL_pixels.h
00024  *
00025  *  Header for the enumerated pixel format definitions.
00026  */
00027 
00028 #ifndef _SDL_pixels_h
00029 #define _SDL_pixels_h
00030 
00031 #include "SDL_stdinc.h"
00032 
00033 #include "begin_code.h"
00034 /* Set up for C function definitions, even when using C++ */
00035 #ifdef __cplusplus
00036 extern "C" {
00037 #endif
00038 
00039 /**
00040  *  \name Transparency definitions
00041  *
00042  *  These define alpha as the opacity of a surface.
00043  */
00044 /* @{ */
00045 #define SDL_ALPHA_OPAQUE 255
00046 #define SDL_ALPHA_TRANSPARENT 0
00047 /* @} */
00048 
00049 /** Pixel type. */
00050 enum
00051 {
00052     SDL_PIXELTYPE_UNKNOWN,
00053     SDL_PIXELTYPE_INDEX1,
00054     SDL_PIXELTYPE_INDEX4,
00055     SDL_PIXELTYPE_INDEX8,
00056     SDL_PIXELTYPE_PACKED8,
00057     SDL_PIXELTYPE_PACKED16,
00058     SDL_PIXELTYPE_PACKED32,
00059     SDL_PIXELTYPE_ARRAYU8,
00060     SDL_PIXELTYPE_ARRAYU16,
00061     SDL_PIXELTYPE_ARRAYU32,
00062     SDL_PIXELTYPE_ARRAYF16,
00063     SDL_PIXELTYPE_ARRAYF32
00064 };
00065 
00066 /** Bitmap pixel order, high bit -> low bit. */
00067 enum
00068 {
00069     SDL_BITMAPORDER_NONE,
00070     SDL_BITMAPORDER_4321,
00071     SDL_BITMAPORDER_1234
00072 };
00073 
00074 /** Packed component order, high bit -> low bit. */
00075 enum
00076 {
00077     SDL_PACKEDORDER_NONE,
00078     SDL_PACKEDORDER_XRGB,
00079     SDL_PACKEDORDER_RGBX,
00080     SDL_PACKEDORDER_ARGB,
00081     SDL_PACKEDORDER_RGBA,
00082     SDL_PACKEDORDER_XBGR,
00083     SDL_PACKEDORDER_BGRX,
00084     SDL_PACKEDORDER_ABGR,
00085     SDL_PACKEDORDER_BGRA
00086 };
00087 
00088 /** Array component order, low byte -> high byte. */
00089 enum
00090 {
00091     SDL_ARRAYORDER_NONE,
00092     SDL_ARRAYORDER_RGB,
00093     SDL_ARRAYORDER_RGBA,
00094     SDL_ARRAYORDER_ARGB,
00095     SDL_ARRAYORDER_BGR,
00096     SDL_ARRAYORDER_BGRA,
00097     SDL_ARRAYORDER_ABGR
00098 };
00099 
00100 /** Packed component layout. */
00101 enum
00102 {
00103     SDL_PACKEDLAYOUT_NONE,
00104     SDL_PACKEDLAYOUT_332,
00105     SDL_PACKEDLAYOUT_4444,
00106     SDL_PACKEDLAYOUT_1555,
00107     SDL_PACKEDLAYOUT_5551,
00108     SDL_PACKEDLAYOUT_565,
00109     SDL_PACKEDLAYOUT_8888,
00110     SDL_PACKEDLAYOUT_2101010,
00111     SDL_PACKEDLAYOUT_1010102
00112 };
00113 
00114 #define SDL_DEFINE_PIXELFOURCC(A, B, C, D) SDL_FOURCC(A, B, C, D)
00115 
00116 #define SDL_DEFINE_PIXELFORMAT(type, order, layout, bits, bytes) \
00117     ((1 << 28) | ((type) << 24) | ((order) << 20) | ((layout) << 16) | \
00118      ((bits) << 8) | ((bytes) << 0))
00119 
00120 #define SDL_PIXELFLAG(X)    (((X) >> 28) & 0x0F)
00121 #define SDL_PIXELTYPE(X)    (((X) >> 24) & 0x0F)
00122 #define SDL_PIXELORDER(X)   (((X) >> 20) & 0x0F)
00123 #define SDL_PIXELLAYOUT(X)  (((X) >> 16) & 0x0F)
00124 #define SDL_BITSPERPIXEL(X) (((X) >> 8) & 0xFF)
00125 #define SDL_BYTESPERPIXEL(X) \
00126     (SDL_ISPIXELFORMAT_FOURCC(X) ? \
00127         ((((X) == SDL_PIXELFORMAT_YUY2) || \
00128           ((X) == SDL_PIXELFORMAT_UYVY) || \
00129           ((X) == SDL_PIXELFORMAT_YVYU)) ? 2 : 1) : (((X) >> 0) & 0xFF))
00130 
00131 #define SDL_ISPIXELFORMAT_INDEXED(format)   \
00132     (!SDL_ISPIXELFORMAT_FOURCC(format) && \
00133      ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX1) || \
00134       (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX4) || \
00135       (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX8)))
00136 
00137 #define SDL_ISPIXELFORMAT_ALPHA(format)   \
00138     (!SDL_ISPIXELFORMAT_FOURCC(format) && \
00139      ((SDL_PIXELORDER(format) == SDL_PACKEDORDER_ARGB) || \
00140       (SDL_PIXELORDER(format) == SDL_PACKEDORDER_RGBA) || \
00141       (SDL_PIXELORDER(format) == SDL_PACKEDORDER_ABGR) || \
00142       (SDL_PIXELORDER(format) == SDL_PACKEDORDER_BGRA)))
00143 
00144 /* The flag is set to 1 because 0x1? is not in the printable ASCII range */
00145 #define SDL_ISPIXELFORMAT_FOURCC(format)    \
00146     ((format) && (SDL_PIXELFLAG(format) != 1))
00147 
00148 /* Note: If you modify this list, update SDL_GetPixelFormatName() */
00149 enum
00150 {
00151     SDL_PIXELFORMAT_UNKNOWN,
00152     SDL_PIXELFORMAT_INDEX1LSB =
00153         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX1, SDL_BITMAPORDER_4321, 0,
00154                                1, 0),
00155     SDL_PIXELFORMAT_INDEX1MSB =
00156         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX1, SDL_BITMAPORDER_1234, 0,
00157                                1, 0),
00158     SDL_PIXELFORMAT_INDEX4LSB =
00159         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX4, SDL_BITMAPORDER_4321, 0,
00160                                4, 0),
00161     SDL_PIXELFORMAT_INDEX4MSB =
00162         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX4, SDL_BITMAPORDER_1234, 0,
00163                                4, 0),
00164     SDL_PIXELFORMAT_INDEX8 =
00165         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX8, 0, 0, 8, 1),
00166     SDL_PIXELFORMAT_RGB332 =
00167         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED8, SDL_PACKEDORDER_XRGB,
00168                                SDL_PACKEDLAYOUT_332, 8, 1),
00169     SDL_PIXELFORMAT_RGB444 =
00170         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB,
00171                                SDL_PACKEDLAYOUT_4444, 12, 2),
00172     SDL_PIXELFORMAT_RGB555 =
00173         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB,
00174                                SDL_PACKEDLAYOUT_1555, 15, 2),
00175     SDL_PIXELFORMAT_BGR555 =
00176         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XBGR,
00177                                SDL_PACKEDLAYOUT_1555, 15, 2),
00178     SDL_PIXELFORMAT_ARGB4444 =
00179         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ARGB,
00180                                SDL_PACKEDLAYOUT_4444, 16, 2),
00181     SDL_PIXELFORMAT_RGBA4444 =
00182         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_RGBA,
00183                                SDL_PACKEDLAYOUT_4444, 16, 2),
00184     SDL_PIXELFORMAT_ABGR4444 =
00185         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ABGR,
00186                                SDL_PACKEDLAYOUT_4444, 16, 2),
00187     SDL_PIXELFORMAT_BGRA4444 =
00188         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_BGRA,
00189                                SDL_PACKEDLAYOUT_4444, 16, 2),
00190     SDL_PIXELFORMAT_ARGB1555 =
00191         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ARGB,
00192                                SDL_PACKEDLAYOUT_1555, 16, 2),
00193     SDL_PIXELFORMAT_RGBA5551 =
00194         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_RGBA,
00195                                SDL_PACKEDLAYOUT_5551, 16, 2),
00196     SDL_PIXELFORMAT_ABGR1555 =
00197         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ABGR,
00198                                SDL_PACKEDLAYOUT_1555, 16, 2),
00199     SDL_PIXELFORMAT_BGRA5551 =
00200         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_BGRA,
00201                                SDL_PACKEDLAYOUT_5551, 16, 2),
00202     SDL_PIXELFORMAT_RGB565 =
00203         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB,
00204                                SDL_PACKEDLAYOUT_565, 16, 2),
00205     SDL_PIXELFORMAT_BGR565 =
00206         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XBGR,
00207                                SDL_PACKEDLAYOUT_565, 16, 2),
00208     SDL_PIXELFORMAT_RGB24 =
00209         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU8, SDL_ARRAYORDER_RGB, 0,
00210                                24, 3),
00211     SDL_PIXELFORMAT_BGR24 =
00212         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU8, SDL_ARRAYORDER_BGR, 0,
00213                                24, 3),
00214     SDL_PIXELFORMAT_RGB888 =
00215         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XRGB,
00216                                SDL_PACKEDLAYOUT_8888, 24, 4),
00217     SDL_PIXELFORMAT_RGBX8888 =
00218         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_RGBX,
00219                                SDL_PACKEDLAYOUT_8888, 24, 4),
00220     SDL_PIXELFORMAT_BGR888 =
00221         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XBGR,
00222                                SDL_PACKEDLAYOUT_8888, 24, 4),
00223     SDL_PIXELFORMAT_BGRX8888 =
00224         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_BGRX,
00225                                SDL_PACKEDLAYOUT_8888, 24, 4),
00226     SDL_PIXELFORMAT_ARGB8888 =
00227         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ARGB,
00228                                SDL_PACKEDLAYOUT_8888, 32, 4),
00229     SDL_PIXELFORMAT_RGBA8888 =
00230         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_RGBA,
00231                                SDL_PACKEDLAYOUT_8888, 32, 4),
00232     SDL_PIXELFORMAT_ABGR8888 =
00233         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ABGR,
00234                                SDL_PACKEDLAYOUT_8888, 32, 4),
00235     SDL_PIXELFORMAT_BGRA8888 =
00236         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_BGRA,
00237                                SDL_PACKEDLAYOUT_8888, 32, 4),
00238     SDL_PIXELFORMAT_ARGB2101010 =
00239         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ARGB,
00240                                SDL_PACKEDLAYOUT_2101010, 32, 4),
00241 
00242     SDL_PIXELFORMAT_YV12 =      /**< Planar mode: Y + V + U  (3 planes) */
00243         SDL_DEFINE_PIXELFOURCC('Y', 'V', '1', '2'),
00244     SDL_PIXELFORMAT_IYUV =      /**< Planar mode: Y + U + V  (3 planes) */
00245         SDL_DEFINE_PIXELFOURCC('I', 'Y', 'U', 'V'),
00246     SDL_PIXELFORMAT_YUY2 =      /**< Packed mode: Y0+U0+Y1+V0 (1 plane) */
00247         SDL_DEFINE_PIXELFOURCC('Y', 'U', 'Y', '2'),
00248     SDL_PIXELFORMAT_UYVY =      /**< Packed mode: U0+Y0+V0+Y1 (1 plane) */
00249         SDL_DEFINE_PIXELFOURCC('U', 'Y', 'V', 'Y'),
00250     SDL_PIXELFORMAT_YVYU =      /**< Packed mode: Y0+V0+Y1+U0 (1 plane) */
00251         SDL_DEFINE_PIXELFOURCC('Y', 'V', 'Y', 'U')
00252 };
00253 
00254 typedef struct SDL_Color
00255 {
00256     Uint8 r;
00257     Uint8 g;
00258     Uint8 b;
00259     Uint8 a;
00260 } SDL_Color;
00261 #define SDL_Colour SDL_Color
00262 
00263 typedef struct SDL_Palette
00264 {
00265     int ncolors;
00266     SDL_Color *colors;
00267     Uint32 version;
00268     int refcount;
00269 } SDL_Palette;
00270 
00271 /**
00272  *  \note Everything in the pixel format structure is read-only.
00273  */
00274 typedef struct SDL_PixelFormat 
00275 {
00276     Uint32 format;
00277     SDL_Palette *palette;
00278     Uint8 BitsPerPixel;
00279     Uint8 BytesPerPixel;
00280     Uint8 padding[2];
00281     Uint32 Rmask;
00282     Uint32 Gmask;
00283     Uint32 Bmask;
00284     Uint32 Amask;
00285     Uint8 Rloss;
00286     Uint8 Gloss;
00287     Uint8 Bloss;
00288     Uint8 Aloss;
00289     Uint8 Rshift;
00290     Uint8 Gshift;
00291     Uint8 Bshift;
00292     Uint8 Ashift;
00293     int refcount;
00294     struct SDL_PixelFormat  *next;
00295 } SDL_PixelFormat ;
00296 
00297 /**
00298  * \brief Get the human readable name of a pixel format
00299  */
00300 extern DECLSPEC const char* SDLCALL SDL_GetPixelFormatName(Uint32 format);
00301 
00302 /**
00303  *  \brief Convert one of the enumerated pixel formats to a bpp and RGBA masks.
00304  *
00305  *  \return SDL_TRUE, or SDL_FALSE if the conversion wasn't possible.
00306  *
00307  *  \sa SDL_MasksToPixelFormatEnum()
00308  */
00309 extern DECLSPEC SDL_bool SDLCALL SDL_PixelFormatEnumToMasks(Uint32 format,
00310                                                             int *bpp,
00311                                                             Uint32 * Rmask,
00312                                                             Uint32 * Gmask,
00313                                                             Uint32 * Bmask,
00314                                                             Uint32 * Amask);
00315 
00316 /**
00317  *  \brief Convert a bpp and RGBA masks to an enumerated pixel format.
00318  *
00319  *  \return The pixel format, or ::SDL_PIXELFORMAT_UNKNOWN if the conversion
00320  *          wasn't possible.
00321  *
00322  *  \sa SDL_PixelFormatEnumToMasks()
00323  */
00324 extern DECLSPEC Uint32 SDLCALL SDL_MasksToPixelFormatEnum(int bpp,
00325                                                           Uint32 Rmask,
00326                                                           Uint32 Gmask,
00327                                                           Uint32 Bmask,
00328                                                           Uint32 Amask);
00329 
00330 /**
00331  *  \brief Create an SDL_PixelFormat structure from a pixel format enum.
00332  */
00333 extern DECLSPEC SDL_PixelFormat  * SDLCALL SDL_AllocFormat(Uint32 pixel_format);
00334 
00335 /**
00336  *  \brief Free an SDL_PixelFormat structure.
00337  */
00338 extern DECLSPEC void SDLCALL SDL_FreeFormat(SDL_PixelFormat  *format);
00339 
00340 /**
00341  *  \brief Create a palette structure with the specified number of color
00342  *         entries.
00343  *
00344  *  \return A new palette, or NULL if there wasn't enough memory.
00345  *
00346  *  \note The palette entries are initialized to white.
00347  *
00348  *  \sa SDL_FreePalette()
00349  */
00350 extern DECLSPEC SDL_Palette *SDLCALL SDL_AllocPalette(int ncolors);
00351 
00352 /**
00353  *  \brief Set the palette for a pixel format structure.
00354  */
00355 extern DECLSPEC int SDLCALL SDL_SetPixelFormatPalette(SDL_PixelFormat  * format,
00356                                                       SDL_Palette *palette);
00357 
00358 /**
00359  *  \brief Set a range of colors in a palette.
00360  *
00361  *  \param palette    The palette to modify.
00362  *  \param colors     An array of colors to copy into the palette.
00363  *  \param firstcolor The index of the first palette entry to modify.
00364  *  \param ncolors    The number of entries to modify.
00365  *
00366  *  \return 0 on success, or -1 if not all of the colors could be set.
00367  */
00368 extern DECLSPEC int SDLCALL SDL_SetPaletteColors(SDL_Palette * palette,
00369                                                  const SDL_Color * colors,
00370                                                  int firstcolor, int ncolors);
00371 
00372 /**
00373  *  \brief Free a palette created with SDL_AllocPalette().
00374  *
00375  *  \sa SDL_AllocPalette()
00376  */
00377 extern DECLSPEC void SDLCALL SDL_FreePalette(SDL_Palette * palette);
00378 
00379 /**
00380  *  \brief Maps an RGB triple to an opaque pixel value for a given pixel format.
00381  *
00382  *  \sa SDL_MapRGBA
00383  */
00384 extern DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormat  * format,
00385                                           Uint8 r, Uint8 g, Uint8 b);
00386 
00387 /**
00388  *  \brief Maps an RGBA quadruple to a pixel value for a given pixel format.
00389  *
00390  *  \sa SDL_MapRGB
00391  */
00392 extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormat  * format,
00393                                            Uint8 r, Uint8 g, Uint8 b,
00394                                            Uint8 a);
00395 
00396 /**
00397  *  \brief Get the RGB components from a pixel of the specified format.
00398  *
00399  *  \sa SDL_GetRGBA
00400  */
00401 extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel,
00402                                         const SDL_PixelFormat  * format,
00403                                         Uint8 * r, Uint8 * g, Uint8 * b);
00404 
00405 /**
00406  *  \brief Get the RGBA components from a pixel of the specified format.
00407  *
00408  *  \sa SDL_GetRGB
00409  */
00410 extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel,
00411                                          const SDL_PixelFormat  * format,
00412                                          Uint8 * r, Uint8 * g, Uint8 * b,
00413                                          Uint8 * a);
00414 
00415 /**
00416  *  \brief Calculate a 256 entry gamma ramp for a gamma value.
00417  */
00418 extern DECLSPEC void SDLCALL SDL_CalculateGammaRamp(float gamma, Uint16 * ramp);
00419 
00420 
00421 /* Ends C function definitions when using C++ */
00422 #ifdef __cplusplus
00423 }
00424 #endif
00425 #include "close_code.h"
00426 
00427 #endif /* _SDL_pixels_h */
00428 
00429 /* vi: set ts=4 sw=4 expandtab: */