include/SDL_pixels.h
author Sam Lantinga <slouken@libsdl.org>
Sat, 17 Jun 2006 06:45:14 +0000
branchSDL-1.3
changeset 1683 396a35389351
parent 1682 7ae8018b2e5d
child 1684 c4aa1a2f48f1
permissions -rw-r--r--
Finished palettized display handling.
Added support for surface palette sharing.
slouken@1662
     1
/*
slouken@1662
     2
    SDL - Simple DirectMedia Layer
slouken@1662
     3
    Copyright (C) 1997-2006 Sam Lantinga
slouken@1662
     4
slouken@1662
     5
    This library is free software; you can redistribute it and/or
slouken@1662
     6
    modify it under the terms of the GNU Lesser General Public
slouken@1662
     7
    License as published by the Free Software Foundation; either
slouken@1662
     8
    version 2.1 of the License, or (at your option) any later version.
slouken@1662
     9
slouken@1662
    10
    This library is distributed in the hope that it will be useful,
slouken@1662
    11
    but WITHOUT ANY WARRANTY; without even the implied warranty of
slouken@1662
    12
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
slouken@1662
    13
    Lesser General Public License for more details.
slouken@1662
    14
slouken@1662
    15
    You should have received a copy of the GNU Lesser General Public
slouken@1662
    16
    License along with this library; if not, write to the Free Software
slouken@1662
    17
    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
slouken@1662
    18
slouken@1662
    19
    Sam Lantinga
slouken@1662
    20
    slouken@libsdl.org
slouken@1662
    21
*/
slouken@1662
    22
slouken@1662
    23
/**
slouken@1662
    24
 * \file SDL_pixels.h
slouken@1662
    25
 *
slouken@1662
    26
 * Header for the enumerated pixel format definitions
slouken@1662
    27
 */
slouken@1662
    28
slouken@1662
    29
#ifndef _SDL_pixels_h
slouken@1662
    30
#define _SDL_pixels_h
slouken@1662
    31
slouken@1662
    32
#include "begin_code.h"
slouken@1662
    33
/* Set up for C function definitions, even when using C++ */
slouken@1662
    34
#ifdef __cplusplus
slouken@1662
    35
/* *INDENT-OFF* */
slouken@1662
    36
extern "C" {
slouken@1662
    37
/* *INDENT-ON* */
slouken@1662
    38
#endif
slouken@1662
    39
slouken@1662
    40
enum
slouken@1662
    41
{                               /* Pixel type */
slouken@1662
    42
    SDL_PixelType_Unknown,
slouken@1662
    43
    SDL_PixelType_Index1,
slouken@1662
    44
    SDL_PixelType_Index4,
slouken@1662
    45
    SDL_PixelType_Index8,
slouken@1662
    46
    SDL_PixelType_Packed8,
slouken@1662
    47
    SDL_PixelType_Packed16,
slouken@1662
    48
    SDL_PixelType_Packed32,
slouken@1662
    49
    SDL_PixelType_ArrayU8,
slouken@1662
    50
    SDL_PixelType_ArrayU16,
slouken@1662
    51
    SDL_PixelType_ArrayU32,
slouken@1662
    52
    SDL_PixelType_ArrayF16,
slouken@1662
    53
    SDL_PixelType_ArrayF32,
slouken@1662
    54
};
slouken@1662
    55
slouken@1662
    56
enum
slouken@1662
    57
{                               /* bitmap pixel order, high bit -> low bit */
slouken@1662
    58
    SDL_BitmapOrder_None,
slouken@1662
    59
    SDL_BitmapOrder_4321,
slouken@1662
    60
    SDL_BitmapOrder_1234,
slouken@1662
    61
};
slouken@1662
    62
enum
slouken@1662
    63
{                               /* packed component order, high bit -> low bit */
slouken@1662
    64
    SDL_PackedOrder_None,
slouken@1662
    65
    SDL_PackedOrder_XRGB,
slouken@1662
    66
    SDL_PackedOrder_RGBX,
slouken@1662
    67
    SDL_PackedOrder_ARGB,
slouken@1662
    68
    SDL_PackedOrder_RGBA,
slouken@1662
    69
    SDL_PackedOrder_XBGR,
slouken@1662
    70
    SDL_PackedOrder_BGRX,
slouken@1662
    71
    SDL_PackedOrder_ABGR,
slouken@1662
    72
    SDL_PackedOrder_BGRA,
slouken@1662
    73
};
slouken@1662
    74
enum
slouken@1662
    75
{                               /* array component order, low byte -> high byte */
slouken@1662
    76
    SDL_ArrayOrder_None,
slouken@1662
    77
    SDL_ArrayOrder_RGB,
slouken@1662
    78
    SDL_ArrayOrder_RGBA,
slouken@1662
    79
    SDL_ArrayOrder_ARGB,
slouken@1662
    80
    SDL_ArrayOrder_BGR,
slouken@1662
    81
    SDL_ArrayOrder_BGRA,
slouken@1662
    82
    SDL_ArrayOrder_ABGR,
slouken@1662
    83
};
slouken@1662
    84
slouken@1662
    85
enum
slouken@1662
    86
{                               /* Packed component layout */
slouken@1662
    87
    SDL_PackedLayout_None,
slouken@1662
    88
    SDL_PackedLayout_332,
slouken@1662
    89
    SDL_PackedLayout_4444,
slouken@1662
    90
    SDL_PackedLayout_1555,
slouken@1662
    91
    SDL_PackedLayout_5551,
slouken@1662
    92
    SDL_PackedLayout_565,
slouken@1662
    93
    SDL_PackedLayout_8888,
slouken@1662
    94
    SDL_PackedLayout_2101010,
slouken@1662
    95
    SDL_PackedLayout_1010102,
slouken@1662
    96
};
slouken@1662
    97
slouken@1675
    98
#define SDL_DEFINE_PIXELFOURCC(A, B, C, D) \
slouken@1675
    99
    ((A) | ((B) << 8) | ((C) << 16) | ((D) << 24))
slouken@1675
   100
slouken@1662
   101
#define SDL_DEFINE_PIXELFORMAT(type, order, layout, bits, bytes) \
slouken@1662
   102
    ((1 << 31) | ((type) << 24) | ((order) << 20) | ((layout) << 16) | \
slouken@1662
   103
     ((bits) << 8) | ((bytes) << 0))
slouken@1662
   104
slouken@1662
   105
#define SDL_PIXELTYPE(X)	(((X) >> 24) & 0x0F)
slouken@1662
   106
#define SDL_PIXELORDER(X)	(((X) >> 20) & 0x0F)
slouken@1662
   107
#define SDL_PIXELLAYOUT(X)	(((X) >> 16) & 0x0F)
slouken@1662
   108
#define SDL_BITSPERPIXEL(X)	(((X) >> 8) & 0xFF)
slouken@1662
   109
#define SDL_BYTESPERPIXEL(X)	(((X) >> 0) & 0xFF)
slouken@1662
   110
slouken@1681
   111
#define SDL_ISPIXELFORMAT_INDEXED(format)   \
slouken@1681
   112
    ((SDL_PIXELTYPE(format) == SDL_PixelType_Index1) || \
slouken@1681
   113
     (SDL_PIXELTYPE(format) == SDL_PixelType_Index4) || \
slouken@1681
   114
     (SDL_PIXELTYPE(format) == SDL_PixelType_Index8))
slouken@1681
   115
slouken@1681
   116
#define SDL_ISPIXELFORMAT_FOURCC(format)    \
slouken@1682
   117
    ((format) && !((format) & 0x80000000))
slouken@1676
   118
slouken@1662
   119
enum
slouken@1662
   120
{
slouken@1662
   121
    SDL_PixelFormat_Unknown,
slouken@1662
   122
    SDL_PixelFormat_Index1LSB =
slouken@1668
   123
        SDL_DEFINE_PIXELFORMAT(SDL_PixelType_Index1, SDL_BitmapOrder_1234, 0,
slouken@1668
   124
                               1, 0),
slouken@1662
   125
    SDL_PixelFormat_Index1MSB =
slouken@1668
   126
        SDL_DEFINE_PIXELFORMAT(SDL_PixelType_Index1, SDL_BitmapOrder_4321, 0,
slouken@1668
   127
                               1, 0),
slouken@1662
   128
    SDL_PixelFormat_Index4LSB =
slouken@1668
   129
        SDL_DEFINE_PIXELFORMAT(SDL_PixelType_Index4, SDL_BitmapOrder_1234, 0,
slouken@1668
   130
                               2, 0),
slouken@1662
   131
    SDL_PixelFormat_Index4MSB =
slouken@1668
   132
        SDL_DEFINE_PIXELFORMAT(SDL_PixelType_Index4, SDL_BitmapOrder_4321, 0,
slouken@1668
   133
                               2, 0),
slouken@1662
   134
    SDL_PixelFormat_Index8 =
slouken@1668
   135
        SDL_DEFINE_PIXELFORMAT(SDL_PixelType_Index8, 0, 0, 8, 1),
slouken@1662
   136
    SDL_PixelFormat_RGB332 =
slouken@1668
   137
        SDL_DEFINE_PIXELFORMAT(SDL_PixelType_Packed8, SDL_PackedOrder_XRGB,
slouken@1668
   138
                               SDL_PackedLayout_332, 8, 1),
slouken@1662
   139
    SDL_PixelFormat_RGB444 =
slouken@1668
   140
        SDL_DEFINE_PIXELFORMAT(SDL_PixelType_Packed16, SDL_PackedOrder_XRGB,
slouken@1668
   141
                               SDL_PackedLayout_4444, 12, 2),
slouken@1662
   142
    SDL_PixelFormat_RGB555 =
slouken@1668
   143
        SDL_DEFINE_PIXELFORMAT(SDL_PixelType_Packed16, SDL_PackedOrder_XRGB,
slouken@1668
   144
                               SDL_PackedLayout_1555, 15, 2),
slouken@1662
   145
    SDL_PixelFormat_ARGB4444 =
slouken@1668
   146
        SDL_DEFINE_PIXELFORMAT(SDL_PixelType_Packed16, SDL_PackedOrder_ARGB,
slouken@1668
   147
                               SDL_PackedLayout_4444, 16, 2),
slouken@1662
   148
    SDL_PixelFormat_ARGB1555 =
slouken@1668
   149
        SDL_DEFINE_PIXELFORMAT(SDL_PixelType_Packed16, SDL_PackedOrder_ARGB,
slouken@1668
   150
                               SDL_PackedLayout_1555, 16, 2),
slouken@1662
   151
    SDL_PixelFormat_RGB565 =
slouken@1668
   152
        SDL_DEFINE_PIXELFORMAT(SDL_PixelType_Packed16, SDL_PackedOrder_XRGB,
slouken@1668
   153
                               SDL_PackedLayout_565, 16, 2),
slouken@1662
   154
    SDL_PixelFormat_RGB24 =
slouken@1668
   155
        SDL_DEFINE_PIXELFORMAT(SDL_PixelType_ArrayU8, SDL_ArrayOrder_RGB, 0,
slouken@1668
   156
                               24, 3),
slouken@1662
   157
    SDL_PixelFormat_BGR24 =
slouken@1668
   158
        SDL_DEFINE_PIXELFORMAT(SDL_PixelType_ArrayU8, SDL_ArrayOrder_BGR, 0,
slouken@1668
   159
                               24, 3),
slouken@1662
   160
    SDL_PixelFormat_RGB888 =
slouken@1668
   161
        SDL_DEFINE_PIXELFORMAT(SDL_PixelType_Packed32, SDL_PackedOrder_XRGB,
slouken@1668
   162
                               SDL_PackedLayout_8888, 24, 4),
slouken@1662
   163
    SDL_PixelFormat_BGR888 =
slouken@1668
   164
        SDL_DEFINE_PIXELFORMAT(SDL_PixelType_Packed32, SDL_PackedOrder_XBGR,
slouken@1668
   165
                               SDL_PackedLayout_8888, 24, 4),
slouken@1662
   166
    SDL_PixelFormat_ARGB8888 =
slouken@1668
   167
        SDL_DEFINE_PIXELFORMAT(SDL_PixelType_Packed32, SDL_PackedOrder_ARGB,
slouken@1668
   168
                               SDL_PackedLayout_8888, 32, 4),
slouken@1662
   169
    SDL_PixelFormat_RGBA8888 =
slouken@1668
   170
        SDL_DEFINE_PIXELFORMAT(SDL_PixelType_Packed32, SDL_PackedOrder_RGBA,
slouken@1668
   171
                               SDL_PackedLayout_8888, 32, 4),
slouken@1662
   172
    SDL_PixelFormat_ABGR8888 =
slouken@1668
   173
        SDL_DEFINE_PIXELFORMAT(SDL_PixelType_Packed32, SDL_PackedOrder_ABGR,
slouken@1668
   174
                               SDL_PackedLayout_8888, 32, 4),
slouken@1662
   175
    SDL_PixelFormat_BGRA8888 =
slouken@1668
   176
        SDL_DEFINE_PIXELFORMAT(SDL_PixelType_Packed32, SDL_PackedOrder_BGRA,
slouken@1668
   177
                               SDL_PackedLayout_8888, 32, 4),
slouken@1662
   178
    SDL_PixelFormat_ARGB2101010 =
slouken@1668
   179
        SDL_DEFINE_PIXELFORMAT(SDL_PixelType_Packed32, SDL_PackedOrder_ARGB,
slouken@1668
   180
                               SDL_PackedLayout_2101010, 32, 4),
slouken@1675
   181
slouken@1675
   182
    SDL_PixelFormat_YV12 = SDL_DEFINE_PIXELFOURCC('Y', 'V', '1', '2'),
slouken@1675
   183
    SDL_PixelFormat_IYUV = SDL_DEFINE_PIXELFOURCC('I', 'Y', 'U', 'V'),
slouken@1675
   184
    SDL_PixelFormat_YUY2 = SDL_DEFINE_PIXELFOURCC('Y', 'U', 'Y', '2'),
slouken@1675
   185
    SDL_PixelFormat_UYVY = SDL_DEFINE_PIXELFOURCC('U', 'Y', 'V', 'Y'),
slouken@1675
   186
    SDL_PixelFormat_YVYU = SDL_DEFINE_PIXELFOURCC('Y', 'V', 'Y', 'U'),
slouken@1662
   187
};
slouken@1662
   188
slouken@1662
   189
typedef struct SDL_Color
slouken@1662
   190
{
slouken@1662
   191
    Uint8 r;
slouken@1662
   192
    Uint8 g;
slouken@1662
   193
    Uint8 b;
slouken@1662
   194
    Uint8 unused;
slouken@1662
   195
} SDL_Color;
slouken@1662
   196
#define SDL_Colour SDL_Color
slouken@1662
   197
slouken@1683
   198
typedef struct SDL_Palette SDL_Palette;
slouken@1683
   199
typedef int (*SDL_PaletteChangedFunc) (void *userdata, SDL_Palette * palette);
slouken@1683
   200
slouken@1683
   201
typedef struct SDL_PaletteWatch
slouken@1683
   202
{
slouken@1683
   203
    SDL_PaletteChangedFunc callback;
slouken@1683
   204
    void *userdata;
slouken@1683
   205
    struct SDL_PaletteWatch *next;
slouken@1683
   206
} SDL_PaletteWatch;
slouken@1683
   207
slouken@1683
   208
struct SDL_Palette
slouken@1662
   209
{
slouken@1662
   210
    int ncolors;
slouken@1662
   211
    SDL_Color *colors;
slouken@1683
   212
slouken@1683
   213
    int refcount;
slouken@1683
   214
    SDL_PaletteWatch *watch;
slouken@1683
   215
};
slouken@1662
   216
slouken@1662
   217
/* Everything in the pixel format structure is read-only */
slouken@1662
   218
typedef struct SDL_PixelFormat
slouken@1662
   219
{
slouken@1662
   220
    SDL_Palette *palette;
slouken@1662
   221
    Uint8 BitsPerPixel;
slouken@1662
   222
    Uint8 BytesPerPixel;
slouken@1662
   223
    Uint8 Rloss;
slouken@1662
   224
    Uint8 Gloss;
slouken@1662
   225
    Uint8 Bloss;
slouken@1662
   226
    Uint8 Aloss;
slouken@1662
   227
    Uint8 Rshift;
slouken@1662
   228
    Uint8 Gshift;
slouken@1662
   229
    Uint8 Bshift;
slouken@1662
   230
    Uint8 Ashift;
slouken@1662
   231
    Uint32 Rmask;
slouken@1662
   232
    Uint32 Gmask;
slouken@1662
   233
    Uint32 Bmask;
slouken@1662
   234
    Uint32 Amask;
slouken@1662
   235
slouken@1662
   236
    /* RGB color key information */
slouken@1662
   237
    Uint32 colorkey;
slouken@1662
   238
    /* Alpha value information (per-surface alpha) */
slouken@1662
   239
    Uint8 alpha;
slouken@1662
   240
} SDL_PixelFormat;
slouken@1662
   241
slouken@1683
   242
/**
slouken@1683
   243
 * \fn SDL_bool SDL_PixelFormatEnumToMasks(Uint32 format, int *bpp, Uint32 * Rmask, Uint32 * Gmask, Uint32 * Bmask, Uint32 * Amask)
slouken@1683
   244
 *
slouken@1683
   245
 * \brief Convert one of the enumerated pixel formats to a bpp and RGBA masks.
slouken@1683
   246
 *
slouken@1683
   247
 * \return SDL_TRUE, or SDL_FALSE if the conversion wasn't possible.
slouken@1683
   248
 *
slouken@1683
   249
 * \sa SDL_MasksToPixelFormatEnum()
slouken@1662
   250
 */
slouken@1683
   251
extern DECLSPEC SDL_bool SDLCALL SDL_PixelFormatEnumToMasks(Uint32 format,
slouken@1683
   252
                                                            int *bpp,
slouken@1683
   253
                                                            Uint32 * Rmask,
slouken@1683
   254
                                                            Uint32 * Gmask,
slouken@1683
   255
                                                            Uint32 * Bmask,
slouken@1683
   256
                                                            Uint32 * Amask);
slouken@1662
   257
slouken@1683
   258
/**
slouken@1683
   259
 * \fn Uint32 SDL_MasksToPixelFormatEnum(int bpp, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask)
slouken@1683
   260
 *
slouken@1683
   261
 * \brief Convert a bpp and RGBA masks to an enumerated pixel format.
slouken@1683
   262
 *
slouken@1683
   263
 * \return The pixel format, or SDL_PixelFormat_Unknown if the conversion wasn't possible.
slouken@1683
   264
 *
slouken@1683
   265
 * \sa SDL_PixelFormatEnumToMasks()
slouken@1662
   266
 */
slouken@1683
   267
extern DECLSPEC Uint32 SDLCALL SDL_MasksToPixelFormatEnum(int bpp,
slouken@1683
   268
                                                          Uint32 Rmask,
slouken@1683
   269
                                                          Uint32 Gmask,
slouken@1683
   270
                                                          Uint32 Bmask,
slouken@1683
   271
                                                          Uint32 Amask);
slouken@1683
   272
slouken@1683
   273
/**
slouken@1683
   274
 * \fn SDL_Palette *SDL_AllocPalette(int ncolors)
slouken@1683
   275
 *
slouken@1683
   276
 * \brief Create a palette structure with the specified number of color entries.
slouken@1683
   277
 *
slouken@1683
   278
 * \return A new palette, or NULL if there wasn't enough memory
slouken@1683
   279
 *
slouken@1683
   280
 * \note The palette entries are initialized to white.
slouken@1683
   281
 *
slouken@1683
   282
 * \sa SDL_FreePalette()
slouken@1683
   283
 */
slouken@1683
   284
extern DECLSPEC SDL_Palette *SDLCALL SDL_AllocPalette(int ncolors);
slouken@1683
   285
slouken@1683
   286
/**
slouken@1683
   287
 * \fn int SDL_AddPaletteWatch(SDL_Palette *palette, SDL_PaletteChangedFunc callback, void *userdata)
slouken@1683
   288
 *
slouken@1683
   289
 * \brief Add a callback function which is called when the palette changes.
slouken@1683
   290
 *
slouken@1683
   291
 * \sa SDL_DelPaletteWatch()
slouken@1683
   292
 */
slouken@1683
   293
extern DECLSPEC int SDLCALL SDL_AddPaletteWatch(SDL_Palette * palette,
slouken@1683
   294
                                                SDL_PaletteChangedFunc
slouken@1683
   295
                                                callback, void *userdata);
slouken@1683
   296
slouken@1683
   297
/**
slouken@1683
   298
 * \fn void SDL_DelPaletteWatch(SDL_Palette *palette, SDL_PaletteChangedFunc callback, void *userdata)
slouken@1683
   299
 *
slouken@1683
   300
 * \brief Remove a callback function previously added with SDL_AddPaletteWatch()
slouken@1683
   301
 *
slouken@1683
   302
 * \sa SDL_AddPaletteWatch()
slouken@1683
   303
 */
slouken@1683
   304
extern DECLSPEC void SDLCALL SDL_DelPaletteWatch(SDL_Palette * palette,
slouken@1683
   305
                                                 SDL_PaletteChangedFunc
slouken@1683
   306
                                                 callback, void *userdata);
slouken@1683
   307
slouken@1683
   308
/**
slouken@1683
   309
 * \fn int SDL_SetPaletteColors(SDL_Palette *palette, const SDL_Colors *colors, int firstcolor, int numcolors)
slouken@1683
   310
 *
slouken@1683
   311
 * \brief Set a range of colors in a palette.
slouken@1683
   312
 *
slouken@1683
   313
 * \param palette The palette to modify
slouken@1683
   314
 * \param colors An array of colors to copy into the palette
slouken@1683
   315
 * \param firstcolor The index of the first palette entry to modify
slouken@1683
   316
 * \param ncolors The number of entries to modify
slouken@1683
   317
 *
slouken@1683
   318
 * \return 0 on success, or -1 if not all of the colors could be set
slouken@1683
   319
 */
slouken@1683
   320
extern DECLSPEC int SDLCALL SDL_SetPaletteColors(SDL_Palette * palette,
slouken@1683
   321
                                                 const SDL_Color * colors,
slouken@1683
   322
                                                 int firstcolor, int ncolors);
slouken@1683
   323
slouken@1683
   324
/**
slouken@1683
   325
 * \fn void SDL_FreePalette(SDL_Palette *palette)
slouken@1683
   326
 *
slouken@1683
   327
 * \brief Free a palette created with SDL_AllocPalette()
slouken@1683
   328
 *
slouken@1683
   329
 * \sa SDL_AllocPalette()
slouken@1683
   330
 */
slouken@1683
   331
extern DECLSPEC void SDLCALL SDL_FreePalette(SDL_Palette * palette);
slouken@1662
   332
slouken@1662
   333
/* Ends C function definitions when using C++ */
slouken@1662
   334
#ifdef __cplusplus
slouken@1662
   335
/* *INDENT-OFF* */
slouken@1662
   336
}
slouken@1662
   337
/* *INDENT-ON* */
slouken@1662
   338
#endif
slouken@1662
   339
#include "close_code.h"
slouken@1662
   340
slouken@1662
   341
#endif /* _SDL_pixels_h */
slouken@1662
   342
slouken@1662
   343
/* vi: set ts=4 sw=4 expandtab: */