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