include/SDL_pixels.h
author Gabriel Jacobo <gabomdq@gmail.com>
Wed, 21 Aug 2013 09:43:09 -0300
changeset 7677 871d43c6968a
parent 7191 75360622e65f
child 7678 286c42d7c5ed
permissions -rw-r--r--
OCD fixes: Adds a space before */
     1 /*
     2   Simple DirectMedia Layer
     3   Copyright (C) 1997-2013 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 "begin_code.h"
    32 /* Set up for C function definitions, even when using C++ */
    33 #ifdef __cplusplus
    34 extern "C" {
    35 #endif
    36 
    37 /**
    38  *  \name Transparency definitions
    39  *
    40  *  These define alpha as the opacity of a surface.
    41  */
    42 /*@{ */
    43 #define SDL_ALPHA_OPAQUE 255
    44 #define SDL_ALPHA_TRANSPARENT 0
    45 /*@} */
    46 
    47 /** Pixel type. */
    48 enum
    49 {
    50     SDL_PIXELTYPE_UNKNOWN,
    51     SDL_PIXELTYPE_INDEX1,
    52     SDL_PIXELTYPE_INDEX4,
    53     SDL_PIXELTYPE_INDEX8,
    54     SDL_PIXELTYPE_PACKED8,
    55     SDL_PIXELTYPE_PACKED16,
    56     SDL_PIXELTYPE_PACKED32,
    57     SDL_PIXELTYPE_ARRAYU8,
    58     SDL_PIXELTYPE_ARRAYU16,
    59     SDL_PIXELTYPE_ARRAYU32,
    60     SDL_PIXELTYPE_ARRAYF16,
    61     SDL_PIXELTYPE_ARRAYF32
    62 };
    63 
    64 /** Bitmap pixel order, high bit -> low bit. */
    65 enum
    66 {
    67     SDL_BITMAPORDER_NONE,
    68     SDL_BITMAPORDER_4321,
    69     SDL_BITMAPORDER_1234
    70 };
    71 
    72 /** Packed component order, high bit -> low bit. */
    73 enum
    74 {
    75     SDL_PACKEDORDER_NONE,
    76     SDL_PACKEDORDER_XRGB,
    77     SDL_PACKEDORDER_RGBX,
    78     SDL_PACKEDORDER_ARGB,
    79     SDL_PACKEDORDER_RGBA,
    80     SDL_PACKEDORDER_XBGR,
    81     SDL_PACKEDORDER_BGRX,
    82     SDL_PACKEDORDER_ABGR,
    83     SDL_PACKEDORDER_BGRA
    84 };
    85 
    86 /** Array component order, low byte -> high byte. */
    87 enum
    88 {
    89     SDL_ARRAYORDER_NONE,
    90     SDL_ARRAYORDER_RGB,
    91     SDL_ARRAYORDER_RGBA,
    92     SDL_ARRAYORDER_ARGB,
    93     SDL_ARRAYORDER_BGR,
    94     SDL_ARRAYORDER_BGRA,
    95     SDL_ARRAYORDER_ABGR
    96 };
    97 
    98 /** Packed component layout. */
    99 enum
   100 {
   101     SDL_PACKEDLAYOUT_NONE,
   102     SDL_PACKEDLAYOUT_332,
   103     SDL_PACKEDLAYOUT_4444,
   104     SDL_PACKEDLAYOUT_1555,
   105     SDL_PACKEDLAYOUT_5551,
   106     SDL_PACKEDLAYOUT_565,
   107     SDL_PACKEDLAYOUT_8888,
   108     SDL_PACKEDLAYOUT_2101010,
   109     SDL_PACKEDLAYOUT_1010102
   110 };
   111 
   112 #define SDL_DEFINE_PIXELFOURCC(A, B, C, D) SDL_FOURCC(A, B, C, D)
   113 
   114 #define SDL_DEFINE_PIXELFORMAT(type, order, layout, bits, bytes) \
   115     ((1 << 28) | ((type) << 24) | ((order) << 20) | ((layout) << 16) | \
   116      ((bits) << 8) | ((bytes) << 0))
   117 
   118 #define SDL_PIXELFLAG(X)    (((X) >> 28) & 0x0F)
   119 #define SDL_PIXELTYPE(X)    (((X) >> 24) & 0x0F)
   120 #define SDL_PIXELORDER(X)   (((X) >> 20) & 0x0F)
   121 #define SDL_PIXELLAYOUT(X)  (((X) >> 16) & 0x0F)
   122 #define SDL_BITSPERPIXEL(X) (((X) >> 8) & 0xFF)
   123 #define SDL_BYTESPERPIXEL(X) \
   124     (SDL_ISPIXELFORMAT_FOURCC(X) ? \
   125         ((((X) == SDL_PIXELFORMAT_YUY2) || \
   126           ((X) == SDL_PIXELFORMAT_UYVY) || \
   127           ((X) == SDL_PIXELFORMAT_YVYU)) ? 2 : 1) : (((X) >> 0) & 0xFF))
   128 
   129 #define SDL_ISPIXELFORMAT_INDEXED(format)   \
   130     (!SDL_ISPIXELFORMAT_FOURCC(format) && \
   131      ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX1) || \
   132       (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX4) || \
   133       (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX8)))
   134 
   135 #define SDL_ISPIXELFORMAT_ALPHA(format)   \
   136     (!SDL_ISPIXELFORMAT_FOURCC(format) && \
   137      ((SDL_PIXELORDER(format) == SDL_PACKEDORDER_ARGB) || \
   138       (SDL_PIXELORDER(format) == SDL_PACKEDORDER_RGBA) || \
   139       (SDL_PIXELORDER(format) == SDL_PACKEDORDER_ABGR) || \
   140       (SDL_PIXELORDER(format) == SDL_PACKEDORDER_BGRA)))
   141 
   142 /* The flag is set to 1 because 0x1? is not in the printable ASCII range */
   143 #define SDL_ISPIXELFORMAT_FOURCC(format)    \
   144     ((format) && (SDL_PIXELFLAG(format) != 1))
   145 
   146 /* Note: If you modify this list, update SDL_GetPixelFormatName() */
   147 enum
   148 {
   149     SDL_PIXELFORMAT_UNKNOWN,
   150     SDL_PIXELFORMAT_INDEX1LSB =
   151         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX1, SDL_BITMAPORDER_4321, 0,
   152                                1, 0),
   153     SDL_PIXELFORMAT_INDEX1MSB =
   154         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX1, SDL_BITMAPORDER_1234, 0,
   155                                1, 0),
   156     SDL_PIXELFORMAT_INDEX4LSB =
   157         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX4, SDL_BITMAPORDER_4321, 0,
   158                                4, 0),
   159     SDL_PIXELFORMAT_INDEX4MSB =
   160         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX4, SDL_BITMAPORDER_1234, 0,
   161                                4, 0),
   162     SDL_PIXELFORMAT_INDEX8 =
   163         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX8, 0, 0, 8, 1),
   164     SDL_PIXELFORMAT_RGB332 =
   165         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED8, SDL_PACKEDORDER_XRGB,
   166                                SDL_PACKEDLAYOUT_332, 8, 1),
   167     SDL_PIXELFORMAT_RGB444 =
   168         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB,
   169                                SDL_PACKEDLAYOUT_4444, 12, 2),
   170     SDL_PIXELFORMAT_RGB555 =
   171         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB,
   172                                SDL_PACKEDLAYOUT_1555, 15, 2),
   173     SDL_PIXELFORMAT_BGR555 =
   174         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XBGR,
   175                                SDL_PACKEDLAYOUT_1555, 15, 2),
   176     SDL_PIXELFORMAT_ARGB4444 =
   177         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ARGB,
   178                                SDL_PACKEDLAYOUT_4444, 16, 2),
   179     SDL_PIXELFORMAT_RGBA4444 =
   180         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_RGBA,
   181                                SDL_PACKEDLAYOUT_4444, 16, 2),
   182     SDL_PIXELFORMAT_ABGR4444 =
   183         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ABGR,
   184                                SDL_PACKEDLAYOUT_4444, 16, 2),
   185     SDL_PIXELFORMAT_BGRA4444 =
   186         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_BGRA,
   187                                SDL_PACKEDLAYOUT_4444, 16, 2),
   188     SDL_PIXELFORMAT_ARGB1555 =
   189         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ARGB,
   190                                SDL_PACKEDLAYOUT_1555, 16, 2),
   191     SDL_PIXELFORMAT_RGBA5551 =
   192         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_RGBA,
   193                                SDL_PACKEDLAYOUT_5551, 16, 2),
   194     SDL_PIXELFORMAT_ABGR1555 =
   195         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ABGR,
   196                                SDL_PACKEDLAYOUT_1555, 16, 2),
   197     SDL_PIXELFORMAT_BGRA5551 =
   198         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_BGRA,
   199                                SDL_PACKEDLAYOUT_5551, 16, 2),
   200     SDL_PIXELFORMAT_RGB565 =
   201         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB,
   202                                SDL_PACKEDLAYOUT_565, 16, 2),
   203     SDL_PIXELFORMAT_BGR565 =
   204         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XBGR,
   205                                SDL_PACKEDLAYOUT_565, 16, 2),
   206     SDL_PIXELFORMAT_RGB24 =
   207         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU8, SDL_ARRAYORDER_RGB, 0,
   208                                24, 3),
   209     SDL_PIXELFORMAT_BGR24 =
   210         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU8, SDL_ARRAYORDER_BGR, 0,
   211                                24, 3),
   212     SDL_PIXELFORMAT_RGB888 =
   213         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XRGB,
   214                                SDL_PACKEDLAYOUT_8888, 24, 4),
   215     SDL_PIXELFORMAT_RGBX8888 =
   216         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_RGBX,
   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_BGRX8888 =
   222         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_BGRX,
   223                                SDL_PACKEDLAYOUT_8888, 24, 4),
   224     SDL_PIXELFORMAT_ARGB8888 =
   225         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ARGB,
   226                                SDL_PACKEDLAYOUT_8888, 32, 4),
   227     SDL_PIXELFORMAT_RGBA8888 =
   228         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_RGBA,
   229                                SDL_PACKEDLAYOUT_8888, 32, 4),
   230     SDL_PIXELFORMAT_ABGR8888 =
   231         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ABGR,
   232                                SDL_PACKEDLAYOUT_8888, 32, 4),
   233     SDL_PIXELFORMAT_BGRA8888 =
   234         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_BGRA,
   235                                SDL_PACKEDLAYOUT_8888, 32, 4),
   236     SDL_PIXELFORMAT_ARGB2101010 =
   237         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ARGB,
   238                                SDL_PACKEDLAYOUT_2101010, 32, 4),
   239 
   240     SDL_PIXELFORMAT_YV12 =      /**< Planar mode: Y + V + U  (3 planes) */
   241         SDL_DEFINE_PIXELFOURCC('Y', 'V', '1', '2'),
   242     SDL_PIXELFORMAT_IYUV =      /**< Planar mode: Y + U + V  (3 planes) */
   243         SDL_DEFINE_PIXELFOURCC('I', 'Y', 'U', 'V'),
   244     SDL_PIXELFORMAT_YUY2 =      /**< Packed mode: Y0+U0+Y1+V0 (1 plane) */
   245         SDL_DEFINE_PIXELFOURCC('Y', 'U', 'Y', '2'),
   246     SDL_PIXELFORMAT_UYVY =      /**< Packed mode: U0+Y0+V0+Y1 (1 plane) */
   247         SDL_DEFINE_PIXELFOURCC('U', 'Y', 'V', 'Y'),
   248     SDL_PIXELFORMAT_YVYU =      /**< Packed mode: Y0+V0+Y1+U0 (1 plane) */
   249         SDL_DEFINE_PIXELFOURCC('Y', 'V', 'Y', 'U')
   250 };
   251 
   252 typedef struct SDL_Color
   253 {
   254     Uint8 r;
   255     Uint8 g;
   256     Uint8 b;
   257     Uint8 a;
   258 } SDL_Color;
   259 #define SDL_Colour SDL_Color
   260 
   261 typedef struct SDL_Palette
   262 {
   263     int ncolors;
   264     SDL_Color *colors;
   265     Uint32 version;
   266     int refcount;
   267 } SDL_Palette;
   268 
   269 /**
   270  *  \note Everything in the pixel format structure is read-only.
   271  */
   272 typedef struct SDL_PixelFormat
   273 {
   274     Uint32 format;
   275     SDL_Palette *palette;
   276     Uint8 BitsPerPixel;
   277     Uint8 BytesPerPixel;
   278     Uint8 padding[2];
   279     Uint32 Rmask;
   280     Uint32 Gmask;
   281     Uint32 Bmask;
   282     Uint32 Amask;
   283     Uint8 Rloss;
   284     Uint8 Gloss;
   285     Uint8 Bloss;
   286     Uint8 Aloss;
   287     Uint8 Rshift;
   288     Uint8 Gshift;
   289     Uint8 Bshift;
   290     Uint8 Ashift;
   291     int refcount;
   292     struct SDL_PixelFormat *next;
   293 } SDL_PixelFormat;
   294 
   295 /**
   296  * \brief Get the human readable name of a pixel format
   297  */
   298 extern DECLSPEC const char* SDLCALL SDL_GetPixelFormatName(Uint32 format);
   299 
   300 /**
   301  *  \brief Convert one of the enumerated pixel formats to a bpp and RGBA masks.
   302  *
   303  *  \return SDL_TRUE, or SDL_FALSE if the conversion wasn't possible.
   304  *
   305  *  \sa SDL_MasksToPixelFormatEnum()
   306  */
   307 extern DECLSPEC SDL_bool SDLCALL SDL_PixelFormatEnumToMasks(Uint32 format,
   308                                                             int *bpp,
   309                                                             Uint32 * Rmask,
   310                                                             Uint32 * Gmask,
   311                                                             Uint32 * Bmask,
   312                                                             Uint32 * Amask);
   313 
   314 /**
   315  *  \brief Convert a bpp and RGBA masks to an enumerated pixel format.
   316  *
   317  *  \return The pixel format, or ::SDL_PIXELFORMAT_UNKNOWN if the conversion
   318  *          wasn't possible.
   319  *
   320  *  \sa SDL_PixelFormatEnumToMasks()
   321  */
   322 extern DECLSPEC Uint32 SDLCALL SDL_MasksToPixelFormatEnum(int bpp,
   323                                                           Uint32 Rmask,
   324                                                           Uint32 Gmask,
   325                                                           Uint32 Bmask,
   326                                                           Uint32 Amask);
   327 
   328 /**
   329  *  \brief Create an SDL_PixelFormat structure from a pixel format enum.
   330  */
   331 extern DECLSPEC SDL_PixelFormat * SDLCALL SDL_AllocFormat(Uint32 pixel_format);
   332 
   333 /**
   334  *  \brief Free an SDL_PixelFormat structure.
   335  */
   336 extern DECLSPEC void SDLCALL SDL_FreeFormat(SDL_PixelFormat *format);
   337 
   338 /**
   339  *  \brief Create a palette structure with the specified number of color
   340  *         entries.
   341  *
   342  *  \return A new palette, or NULL if there wasn't enough memory.
   343  *
   344  *  \note The palette entries are initialized to white.
   345  *
   346  *  \sa SDL_FreePalette()
   347  */
   348 extern DECLSPEC SDL_Palette *SDLCALL SDL_AllocPalette(int ncolors);
   349 
   350 /**
   351  *  \brief Set the palette for a pixel format structure.
   352  */
   353 extern DECLSPEC int SDLCALL SDL_SetPixelFormatPalette(SDL_PixelFormat * format,
   354                                                       SDL_Palette *palette);
   355 
   356 /**
   357  *  \brief Set a range of colors in a palette.
   358  *
   359  *  \param palette    The palette to modify.
   360  *  \param colors     An array of colors to copy into the palette.
   361  *  \param firstcolor The index of the first palette entry to modify.
   362  *  \param ncolors    The number of entries to modify.
   363  *
   364  *  \return 0 on success, or -1 if not all of the colors could be set.
   365  */
   366 extern DECLSPEC int SDLCALL SDL_SetPaletteColors(SDL_Palette * palette,
   367                                                  const SDL_Color * colors,
   368                                                  int firstcolor, int ncolors);
   369 
   370 /**
   371  *  \brief Free a palette created with SDL_AllocPalette().
   372  *
   373  *  \sa SDL_AllocPalette()
   374  */
   375 extern DECLSPEC void SDLCALL SDL_FreePalette(SDL_Palette * palette);
   376 
   377 /**
   378  *  \brief Maps an RGB triple to an opaque pixel value for a given pixel format.
   379  *
   380  *  \sa SDL_MapRGBA
   381  */
   382 extern DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormat * format,
   383                                           Uint8 r, Uint8 g, Uint8 b);
   384 
   385 /**
   386  *  \brief Maps an RGBA quadruple to a pixel value for a given pixel format.
   387  *
   388  *  \sa SDL_MapRGB
   389  */
   390 extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormat * format,
   391                                            Uint8 r, Uint8 g, Uint8 b,
   392                                            Uint8 a);
   393 
   394 /**
   395  *  \brief Get the RGB components from a pixel of the specified format.
   396  *
   397  *  \sa SDL_GetRGBA
   398  */
   399 extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel,
   400                                         const SDL_PixelFormat * format,
   401                                         Uint8 * r, Uint8 * g, Uint8 * b);
   402 
   403 /**
   404  *  \brief Get the RGBA components from a pixel of the specified format.
   405  *
   406  *  \sa SDL_GetRGB
   407  */
   408 extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel,
   409                                          const SDL_PixelFormat * format,
   410                                          Uint8 * r, Uint8 * g, Uint8 * b,
   411                                          Uint8 * a);
   412 
   413 /**
   414  *  \brief Calculate a 256 entry gamma ramp for a gamma value.
   415  */
   416 extern DECLSPEC void SDLCALL SDL_CalculateGammaRamp(float gamma, Uint16 * ramp);
   417 
   418 
   419 /* Ends C function definitions when using C++ */
   420 #ifdef __cplusplus
   421 }
   422 #endif
   423 #include "close_code.h"
   424 
   425 #endif /* _SDL_pixels_h */
   426 
   427 /* vi: set ts=4 sw=4 expandtab: */