include/SDL_pixels.h
author Sam Lantinga <slouken@libsdl.org>
Fri, 17 Aug 2007 00:54:53 +0000
changeset 2257 340942cfda48
parent 2208 b03710fb0333
child 2275 12ea0fdc0df2
permissions -rw-r--r--
Moved the colorkey and per-surface alpha into the blit info,
in preparation for support for general color channel modulation.

Removed and consolidated some data in the blit info.
slouken@1895
     1
/*
slouken@1895
     2
    SDL - Simple DirectMedia Layer
slouken@1895
     3
    Copyright (C) 1997-2006 Sam Lantinga
slouken@1895
     4
slouken@1895
     5
    This library is free software; you can redistribute it and/or
slouken@1895
     6
    modify it under the terms of the GNU Lesser General Public
slouken@1895
     7
    License as published by the Free Software Foundation; either
slouken@1895
     8
    version 2.1 of the License, or (at your option) any later version.
slouken@1895
     9
slouken@1895
    10
    This library is distributed in the hope that it will be useful,
slouken@1895
    11
    but WITHOUT ANY WARRANTY; without even the implied warranty of
slouken@1895
    12
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
slouken@1895
    13
    Lesser General Public License for more details.
slouken@1895
    14
slouken@1895
    15
    You should have received a copy of the GNU Lesser General Public
slouken@1895
    16
    License along with this library; if not, write to the Free Software
slouken@1895
    17
    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
slouken@1895
    18
slouken@1895
    19
    Sam Lantinga
slouken@1895
    20
    slouken@libsdl.org
slouken@1895
    21
*/
slouken@1895
    22
slouken@1895
    23
/**
slouken@1895
    24
 * \file SDL_pixels.h
slouken@1895
    25
 *
slouken@1895
    26
 * Header for the enumerated pixel format definitions
slouken@1895
    27
 */
slouken@1895
    28
slouken@1895
    29
#ifndef _SDL_pixels_h
slouken@1895
    30
#define _SDL_pixels_h
slouken@1895
    31
slouken@1895
    32
#include "begin_code.h"
slouken@1895
    33
/* Set up for C function definitions, even when using C++ */
slouken@1895
    34
#ifdef __cplusplus
slouken@1895
    35
/* *INDENT-OFF* */
slouken@1895
    36
extern "C" {
slouken@1895
    37
/* *INDENT-ON* */
slouken@1895
    38
#endif
slouken@1895
    39
slouken@1895
    40
enum
slouken@1895
    41
{                               /* Pixel type */
slouken@1965
    42
    SDL_PIXELTYPE_UNKNOWN,
slouken@1965
    43
    SDL_PIXELTYPE_INDEX1,
slouken@1965
    44
    SDL_PIXELTYPE_INDEX4,
slouken@1965
    45
    SDL_PIXELTYPE_INDEX8,
slouken@1965
    46
    SDL_PIXELTYPE_PACKED8,
slouken@1965
    47
    SDL_PIXELTYPE_PACKED16,
slouken@1965
    48
    SDL_PIXELTYPE_PACKED32,
slouken@1965
    49
    SDL_PIXELTYPE_ARRAYU8,
slouken@1965
    50
    SDL_PIXELTYPE_ARRAYU16,
slouken@1965
    51
    SDL_PIXELTYPE_ARRAYU32,
slouken@1965
    52
    SDL_PIXELTYPE_ARRAYF16,
slouken@2208
    53
    SDL_PIXELTYPE_ARRAYF32
slouken@1895
    54
};
slouken@1895
    55
slouken@1895
    56
enum
slouken@1895
    57
{                               /* bitmap pixel order, high bit -> low bit */
slouken@1965
    58
    SDL_BITMAPORDER_NONE,
slouken@1965
    59
    SDL_BITMAPORDER_4321,
slouken@2208
    60
    SDL_BITMAPORDER_1234
slouken@1895
    61
};
slouken@1895
    62
enum
slouken@1895
    63
{                               /* packed component order, high bit -> low bit */
slouken@1965
    64
    SDL_PACKEDORDER_NONE,
slouken@1965
    65
    SDL_PACKEDORDER_XRGB,
slouken@1965
    66
    SDL_PACKEDORDER_RGBX,
slouken@1965
    67
    SDL_PACKEDORDER_ARGB,
slouken@1965
    68
    SDL_PACKEDORDER_RGBA,
slouken@1965
    69
    SDL_PACKEDORDER_XBGR,
slouken@1965
    70
    SDL_PACKEDORDER_BGRX,
slouken@1965
    71
    SDL_PACKEDORDER_ABGR,
slouken@2208
    72
    SDL_PACKEDORDER_BGRA
slouken@1895
    73
};
slouken@1895
    74
enum
slouken@1895
    75
{                               /* array component order, low byte -> high byte */
slouken@1965
    76
    SDL_ARRAYORDER_NONE,
slouken@1965
    77
    SDL_ARRAYORDER_RGB,
slouken@1965
    78
    SDL_ARRAYORDER_RGBA,
slouken@1965
    79
    SDL_ARRAYORDER_ARGB,
slouken@1965
    80
    SDL_ARRAYORDER_BGR,
slouken@1965
    81
    SDL_ARRAYORDER_BGRA,
slouken@2208
    82
    SDL_ARRAYORDER_ABGR
slouken@1895
    83
};
slouken@1895
    84
slouken@1895
    85
enum
slouken@1895
    86
{                               /* Packed component layout */
slouken@1965
    87
    SDL_PACKEDLAYOUT_NONE,
slouken@1965
    88
    SDL_PACKEDLAYOUT_332,
slouken@1965
    89
    SDL_PACKEDLAYOUT_4444,
slouken@1965
    90
    SDL_PACKEDLAYOUT_1555,
slouken@1965
    91
    SDL_PACKEDLAYOUT_5551,
slouken@1965
    92
    SDL_PACKEDLAYOUT_565,
slouken@1965
    93
    SDL_PACKEDLAYOUT_8888,
slouken@1965
    94
    SDL_PACKEDLAYOUT_2101010,
slouken@2208
    95
    SDL_PACKEDLAYOUT_1010102
slouken@1895
    96
};
slouken@1895
    97
slouken@1895
    98
#define SDL_DEFINE_PIXELFOURCC(A, B, C, D) \
slouken@1895
    99
    ((A) | ((B) << 8) | ((C) << 16) | ((D) << 24))
slouken@1895
   100
slouken@1895
   101
#define SDL_DEFINE_PIXELFORMAT(type, order, layout, bits, bytes) \
slouken@1895
   102
    ((1 << 31) | ((type) << 24) | ((order) << 20) | ((layout) << 16) | \
slouken@1895
   103
     ((bits) << 8) | ((bytes) << 0))
slouken@1895
   104
slouken@1895
   105
#define SDL_PIXELTYPE(X)	(((X) >> 24) & 0x0F)
slouken@1895
   106
#define SDL_PIXELORDER(X)	(((X) >> 20) & 0x0F)
slouken@1895
   107
#define SDL_PIXELLAYOUT(X)	(((X) >> 16) & 0x0F)
slouken@1895
   108
#define SDL_BITSPERPIXEL(X)	(((X) >> 8) & 0xFF)
slouken@1895
   109
#define SDL_BYTESPERPIXEL(X)	(((X) >> 0) & 0xFF)
slouken@1895
   110
slouken@1895
   111
#define SDL_ISPIXELFORMAT_INDEXED(format)   \
slouken@1965
   112
    ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX1) || \
slouken@1965
   113
     (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX4) || \
slouken@1965
   114
     (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX8))
slouken@1895
   115
slouken@1895
   116
#define SDL_ISPIXELFORMAT_FOURCC(format)    \
slouken@1895
   117
    ((format) && !((format) & 0x80000000))
slouken@1895
   118
slouken@1895
   119
enum
slouken@1895
   120
{
slouken@1965
   121
    SDL_PIXELFORMAT_UNKNOWN,
slouken@1965
   122
    SDL_PIXELFORMAT_INDEX1LSB =
slouken@1965
   123
        SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX1, SDL_BITMAPORDER_1234, 0,
slouken@1895
   124
                               1, 0),
slouken@1965
   125
    SDL_PIXELFORMAT_INDEX1MSB =
slouken@1965
   126
        SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX1, SDL_BITMAPORDER_4321, 0,
slouken@1895
   127
                               1, 0),
slouken@1965
   128
    SDL_PIXELFORMAT_INDEX4LSB =
slouken@1965
   129
        SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX4, SDL_BITMAPORDER_1234, 0,
slouken@1895
   130
                               2, 0),
slouken@1965
   131
    SDL_PIXELFORMAT_INDEX4MSB =
slouken@1965
   132
        SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX4, SDL_BITMAPORDER_4321, 0,
slouken@1895
   133
                               2, 0),
slouken@1965
   134
    SDL_PIXELFORMAT_INDEX8 =
slouken@1965
   135
        SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX8, 0, 0, 8, 1),
slouken@1965
   136
    SDL_PIXELFORMAT_RGB332 =
slouken@1965
   137
        SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED8, SDL_PACKEDORDER_XRGB,
slouken@1965
   138
                               SDL_PACKEDLAYOUT_332, 8, 1),
slouken@1965
   139
    SDL_PIXELFORMAT_RGB444 =
slouken@1965
   140
        SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB,
slouken@1965
   141
                               SDL_PACKEDLAYOUT_4444, 12, 2),
slouken@1965
   142
    SDL_PIXELFORMAT_RGB555 =
slouken@1965
   143
        SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB,
slouken@1965
   144
                               SDL_PACKEDLAYOUT_1555, 15, 2),
slouken@1965
   145
    SDL_PIXELFORMAT_ARGB4444 =
slouken@1965
   146
        SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ARGB,
slouken@1965
   147
                               SDL_PACKEDLAYOUT_4444, 16, 2),
slouken@1965
   148
    SDL_PIXELFORMAT_ARGB1555 =
slouken@1965
   149
        SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ARGB,
slouken@1965
   150
                               SDL_PACKEDLAYOUT_1555, 16, 2),
slouken@1965
   151
    SDL_PIXELFORMAT_RGB565 =
slouken@1965
   152
        SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB,
slouken@1965
   153
                               SDL_PACKEDLAYOUT_565, 16, 2),
slouken@1965
   154
    SDL_PIXELFORMAT_RGB24 =
slouken@1965
   155
        SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU8, SDL_ARRAYORDER_RGB, 0,
slouken@1895
   156
                               24, 3),
slouken@1965
   157
    SDL_PIXELFORMAT_BGR24 =
slouken@1965
   158
        SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU8, SDL_ARRAYORDER_BGR, 0,
slouken@1895
   159
                               24, 3),
slouken@1965
   160
    SDL_PIXELFORMAT_RGB888 =
slouken@1965
   161
        SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XRGB,
slouken@1965
   162
                               SDL_PACKEDLAYOUT_8888, 24, 4),
slouken@1965
   163
    SDL_PIXELFORMAT_BGR888 =
slouken@1965
   164
        SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XBGR,
slouken@1965
   165
                               SDL_PACKEDLAYOUT_8888, 24, 4),
slouken@1965
   166
    SDL_PIXELFORMAT_ARGB8888 =
slouken@1965
   167
        SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ARGB,
slouken@1965
   168
                               SDL_PACKEDLAYOUT_8888, 32, 4),
slouken@1965
   169
    SDL_PIXELFORMAT_RGBA8888 =
slouken@1965
   170
        SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_RGBA,
slouken@1965
   171
                               SDL_PACKEDLAYOUT_8888, 32, 4),
slouken@1965
   172
    SDL_PIXELFORMAT_ABGR8888 =
slouken@1965
   173
        SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ABGR,
slouken@1965
   174
                               SDL_PACKEDLAYOUT_8888, 32, 4),
slouken@1965
   175
    SDL_PIXELFORMAT_BGRA8888 =
slouken@1965
   176
        SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_BGRA,
slouken@1965
   177
                               SDL_PACKEDLAYOUT_8888, 32, 4),
slouken@1965
   178
    SDL_PIXELFORMAT_ARGB2101010 =
slouken@1965
   179
        SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ARGB,
slouken@1965
   180
                               SDL_PACKEDLAYOUT_2101010, 32, 4),
slouken@1895
   181
slouken@1965
   182
    SDL_PIXELFORMAT_YV12 =      /* Planar mode: Y + V + U  (3 planes) */
slouken@1895
   183
        SDL_DEFINE_PIXELFOURCC('Y', 'V', '1', '2'),
slouken@1965
   184
    SDL_PIXELFORMAT_IYUV =      /* Planar mode: Y + U + V  (3 planes) */
slouken@1895
   185
        SDL_DEFINE_PIXELFOURCC('I', 'Y', 'U', 'V'),
slouken@1965
   186
    SDL_PIXELFORMAT_YUY2 =      /* Packed mode: Y0+U0+Y1+V0 (1 plane) */
slouken@1895
   187
        SDL_DEFINE_PIXELFOURCC('Y', 'U', 'Y', '2'),
slouken@1965
   188
    SDL_PIXELFORMAT_UYVY =      /* Packed mode: U0+Y0+V0+Y1 (1 plane) */
slouken@1895
   189
        SDL_DEFINE_PIXELFOURCC('U', 'Y', 'V', 'Y'),
slouken@1965
   190
    SDL_PIXELFORMAT_YVYU =      /* Packed mode: Y0+V0+Y1+U0 (1 plane) */
slouken@2208
   191
        SDL_DEFINE_PIXELFOURCC('Y', 'V', 'Y', 'U')
slouken@1895
   192
};
slouken@1895
   193
slouken@1895
   194
typedef struct SDL_Color
slouken@1895
   195
{
slouken@1895
   196
    Uint8 r;
slouken@1895
   197
    Uint8 g;
slouken@1895
   198
    Uint8 b;
slouken@1895
   199
    Uint8 unused;
slouken@1895
   200
} SDL_Color;
slouken@1895
   201
#define SDL_Colour SDL_Color
slouken@1895
   202
slouken@1895
   203
typedef struct SDL_Palette SDL_Palette;
slouken@1895
   204
typedef int (*SDL_PaletteChangedFunc) (void *userdata, SDL_Palette * palette);
slouken@1895
   205
slouken@1895
   206
typedef struct SDL_PaletteWatch
slouken@1895
   207
{
slouken@1895
   208
    SDL_PaletteChangedFunc callback;
slouken@1895
   209
    void *userdata;
slouken@1895
   210
    struct SDL_PaletteWatch *next;
slouken@1895
   211
} SDL_PaletteWatch;
slouken@1895
   212
slouken@1895
   213
struct SDL_Palette
slouken@1895
   214
{
slouken@1895
   215
    int ncolors;
slouken@1895
   216
    SDL_Color *colors;
slouken@1895
   217
slouken@1895
   218
    int refcount;
slouken@1895
   219
    SDL_PaletteWatch *watch;
slouken@1895
   220
};
slouken@1895
   221
slouken@1895
   222
/* Everything in the pixel format structure is read-only */
slouken@1895
   223
typedef struct SDL_PixelFormat
slouken@1895
   224
{
slouken@1895
   225
    SDL_Palette *palette;
slouken@1895
   226
    Uint8 BitsPerPixel;
slouken@1895
   227
    Uint8 BytesPerPixel;
slouken@1895
   228
    Uint8 Rloss;
slouken@1895
   229
    Uint8 Gloss;
slouken@1895
   230
    Uint8 Bloss;
slouken@1895
   231
    Uint8 Aloss;
slouken@1895
   232
    Uint8 Rshift;
slouken@1895
   233
    Uint8 Gshift;
slouken@1895
   234
    Uint8 Bshift;
slouken@1895
   235
    Uint8 Ashift;
slouken@1895
   236
    Uint32 Rmask;
slouken@1895
   237
    Uint32 Gmask;
slouken@1895
   238
    Uint32 Bmask;
slouken@1895
   239
    Uint32 Amask;
slouken@1895
   240
} SDL_PixelFormat;
slouken@1895
   241
slouken@1895
   242
/**
slouken@1895
   243
 * \fn SDL_bool SDL_PixelFormatEnumToMasks(Uint32 format, int *bpp, Uint32 * Rmask, Uint32 * Gmask, Uint32 * Bmask, Uint32 * Amask)
slouken@1895
   244
 *
slouken@1895
   245
 * \brief Convert one of the enumerated pixel formats to a bpp and RGBA masks.
slouken@1895
   246
 *
slouken@1895
   247
 * \return SDL_TRUE, or SDL_FALSE if the conversion wasn't possible.
slouken@1895
   248
 *
slouken@1895
   249
 * \sa SDL_MasksToPixelFormatEnum()
slouken@1895
   250
 */
slouken@1895
   251
extern DECLSPEC SDL_bool SDLCALL SDL_PixelFormatEnumToMasks(Uint32 format,
slouken@1895
   252
                                                            int *bpp,
slouken@1895
   253
                                                            Uint32 * Rmask,
slouken@1895
   254
                                                            Uint32 * Gmask,
slouken@1895
   255
                                                            Uint32 * Bmask,
slouken@1895
   256
                                                            Uint32 * Amask);
slouken@1895
   257
slouken@1895
   258
/**
slouken@1895
   259
 * \fn Uint32 SDL_MasksToPixelFormatEnum(int bpp, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask)
slouken@1895
   260
 *
slouken@1895
   261
 * \brief Convert a bpp and RGBA masks to an enumerated pixel format.
slouken@1895
   262
 *
slouken@1895
   263
 * \return The pixel format, or SDL_PixelFormat_Unknown if the conversion wasn't possible.
slouken@1895
   264
 *
slouken@1895
   265
 * \sa SDL_PixelFormatEnumToMasks()
slouken@1895
   266
 */
slouken@1895
   267
extern DECLSPEC Uint32 SDLCALL SDL_MasksToPixelFormatEnum(int bpp,
slouken@1895
   268
                                                          Uint32 Rmask,
slouken@1895
   269
                                                          Uint32 Gmask,
slouken@1895
   270
                                                          Uint32 Bmask,
slouken@1895
   271
                                                          Uint32 Amask);
slouken@1895
   272
slouken@1895
   273
/**
slouken@1895
   274
 * \fn SDL_Palette *SDL_AllocPalette(int ncolors)
slouken@1895
   275
 *
slouken@1895
   276
 * \brief Create a palette structure with the specified number of color entries.
slouken@1895
   277
 *
slouken@1895
   278
 * \return A new palette, or NULL if there wasn't enough memory
slouken@1895
   279
 *
slouken@1895
   280
 * \note The palette entries are initialized to white.
slouken@1895
   281
 *
slouken@1895
   282
 * \sa SDL_FreePalette()
slouken@1895
   283
 */
slouken@1895
   284
extern DECLSPEC SDL_Palette *SDLCALL SDL_AllocPalette(int ncolors);
slouken@1895
   285
slouken@1895
   286
/**
slouken@1895
   287
 * \fn int SDL_AddPaletteWatch(SDL_Palette *palette, SDL_PaletteChangedFunc callback, void *userdata)
slouken@1895
   288
 *
slouken@1895
   289
 * \brief Add a callback function which is called when the palette changes.
slouken@1895
   290
 *
slouken@1895
   291
 * \sa SDL_DelPaletteWatch()
slouken@1895
   292
 */
slouken@1895
   293
extern DECLSPEC int SDLCALL SDL_AddPaletteWatch(SDL_Palette * palette,
slouken@1895
   294
                                                SDL_PaletteChangedFunc
slouken@1895
   295
                                                callback, void *userdata);
slouken@1895
   296
slouken@1895
   297
/**
slouken@1895
   298
 * \fn void SDL_DelPaletteWatch(SDL_Palette *palette, SDL_PaletteChangedFunc callback, void *userdata)
slouken@1895
   299
 *
slouken@1895
   300
 * \brief Remove a callback function previously added with SDL_AddPaletteWatch()
slouken@1895
   301
 *
slouken@1895
   302
 * \sa SDL_AddPaletteWatch()
slouken@1895
   303
 */
slouken@1895
   304
extern DECLSPEC void SDLCALL SDL_DelPaletteWatch(SDL_Palette * palette,
slouken@1895
   305
                                                 SDL_PaletteChangedFunc
slouken@1895
   306
                                                 callback, void *userdata);
slouken@1895
   307
slouken@1895
   308
/**
slouken@1895
   309
 * \fn int SDL_SetPaletteColors(SDL_Palette *palette, const SDL_Colors *colors, int firstcolor, int numcolors)
slouken@1895
   310
 *
slouken@1895
   311
 * \brief Set a range of colors in a palette.
slouken@1895
   312
 *
slouken@1895
   313
 * \param palette The palette to modify
slouken@1895
   314
 * \param colors An array of colors to copy into the palette
slouken@1895
   315
 * \param firstcolor The index of the first palette entry to modify
slouken@1895
   316
 * \param ncolors The number of entries to modify
slouken@1895
   317
 *
slouken@1895
   318
 * \return 0 on success, or -1 if not all of the colors could be set
slouken@1895
   319
 */
slouken@1895
   320
extern DECLSPEC int SDLCALL SDL_SetPaletteColors(SDL_Palette * palette,
slouken@1895
   321
                                                 const SDL_Color * colors,
slouken@1895
   322
                                                 int firstcolor, int ncolors);
slouken@1895
   323
slouken@1895
   324
/**
slouken@1895
   325
 * \fn void SDL_FreePalette(SDL_Palette *palette)
slouken@1895
   326
 *
slouken@1895
   327
 * \brief Free a palette created with SDL_AllocPalette()
slouken@1895
   328
 *
slouken@1895
   329
 * \sa SDL_AllocPalette()
slouken@1895
   330
 */
slouken@1895
   331
extern DECLSPEC void SDLCALL SDL_FreePalette(SDL_Palette * palette);
slouken@1895
   332
slouken@1895
   333
/* Ends C function definitions when using C++ */
slouken@1895
   334
#ifdef __cplusplus
slouken@1895
   335
/* *INDENT-OFF* */
slouken@1895
   336
}
slouken@1895
   337
/* *INDENT-ON* */
slouken@1895
   338
#endif
slouken@1895
   339
#include "close_code.h"
slouken@1895
   340
slouken@1895
   341
#endif /* _SDL_pixels_h */
slouken@1895
   342
slouken@1895
   343
/* vi: set ts=4 sw=4 expandtab: */