SDL 2.0
SDL_pixels.h
Go to the documentation of this file.
1/*
2 Simple DirectMedia Layer
3 Copyright (C) 1997-2019 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#include "SDL_endian.h"
33
34#include "begin_code.h"
35/* Set up for C function definitions, even when using C++ */
36#ifdef __cplusplus
37extern "C" {
38#endif
39
40/**
41 * \name Transparency definitions
42 *
43 * These define alpha as the opacity of a surface.
44 */
45/* @{ */
46#define SDL_ALPHA_OPAQUE 255
47#define SDL_ALPHA_TRANSPARENT 0
48/* @} */
49
50/** Pixel type. */
51enum
52{
65};
66
67/** Bitmap pixel order, high bit -> low bit. */
68enum
69{
73};
74
75/** Packed component order, high bit -> low bit. */
76enum
77{
87};
88
89/** Array component order, low byte -> high byte. */
90/* !!! FIXME: in 2.1, make these not overlap differently with
91 !!! FIXME: SDL_PACKEDORDER_*, so we can simplify SDL_ISPIXELFORMAT_ALPHA */
92enum
93{
102
103/** Packed component layout. */
104enum
105{
116
117#define SDL_DEFINE_PIXELFOURCC(A, B, C, D) SDL_FOURCC(A, B, C, D)
118
119#define SDL_DEFINE_PIXELFORMAT(type, order, layout, bits, bytes) \
120 ((1 << 28) | ((type) << 24) | ((order) << 20) | ((layout) << 16) | \
121 ((bits) << 8) | ((bytes) << 0))
122
123#define SDL_PIXELFLAG(X) (((X) >> 28) & 0x0F)
124#define SDL_PIXELTYPE(X) (((X) >> 24) & 0x0F)
125#define SDL_PIXELORDER(X) (((X) >> 20) & 0x0F)
126#define SDL_PIXELLAYOUT(X) (((X) >> 16) & 0x0F)
127#define SDL_BITSPERPIXEL(X) (((X) >> 8) & 0xFF)
128#define SDL_BYTESPERPIXEL(X) \
129 (SDL_ISPIXELFORMAT_FOURCC(X) ? \
130 ((((X) == SDL_PIXELFORMAT_YUY2) || \
131 ((X) == SDL_PIXELFORMAT_UYVY) || \
132 ((X) == SDL_PIXELFORMAT_YVYU)) ? 2 : 1) : (((X) >> 0) & 0xFF))
133
134#define SDL_ISPIXELFORMAT_INDEXED(format) \
135 (!SDL_ISPIXELFORMAT_FOURCC(format) && \
136 ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX1) || \
137 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX4) || \
138 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX8)))
139
140#define SDL_ISPIXELFORMAT_PACKED(format) \
141 (!SDL_ISPIXELFORMAT_FOURCC(format) && \
142 ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED8) || \
143 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED16) || \
144 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED32)))
145
146#define SDL_ISPIXELFORMAT_ARRAY(format) \
147 (!SDL_ISPIXELFORMAT_FOURCC(format) && \
148 ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYU8) || \
149 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYU16) || \
150 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYU32) || \
151 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF16) || \
152 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF32)))
153
154#define SDL_ISPIXELFORMAT_ALPHA(format) \
155 ((SDL_ISPIXELFORMAT_PACKED(format) && \
156 ((SDL_PIXELORDER(format) == SDL_PACKEDORDER_ARGB) || \
157 (SDL_PIXELORDER(format) == SDL_PACKEDORDER_RGBA) || \
158 (SDL_PIXELORDER(format) == SDL_PACKEDORDER_ABGR) || \
159 (SDL_PIXELORDER(format) == SDL_PACKEDORDER_BGRA))) || \
160 (SDL_ISPIXELFORMAT_ARRAY(format) && \
161 ((SDL_PIXELORDER(format) == SDL_ARRAYORDER_ARGB) || \
162 (SDL_PIXELORDER(format) == SDL_ARRAYORDER_RGBA) || \
163 (SDL_PIXELORDER(format) == SDL_ARRAYORDER_ABGR) || \
164 (SDL_PIXELORDER(format) == SDL_ARRAYORDER_BGRA))))
165
166/* The flag is set to 1 because 0x1? is not in the printable ASCII range */
167#define SDL_ISPIXELFORMAT_FOURCC(format) \
168 ((format) && (SDL_PIXELFLAG(format) != 1))
169
170/* Note: If you modify this list, update SDL_GetPixelFormatName() */
171typedef enum
172{
176 1, 0),
179 1, 0),
182 4, 0),
185 4, 0),
232 24, 3),
235 24, 3),
263
264 /* Aliases for RGBA byte arrays of color data, for the current platform */
265#if SDL_BYTEORDER == SDL_BIG_ENDIAN
270#else
275#endif
276
277 SDL_PIXELFORMAT_YV12 = /**< Planar mode: Y + V + U (3 planes) */
278 SDL_DEFINE_PIXELFOURCC('Y', 'V', '1', '2'),
279 SDL_PIXELFORMAT_IYUV = /**< Planar mode: Y + U + V (3 planes) */
280 SDL_DEFINE_PIXELFOURCC('I', 'Y', 'U', 'V'),
281 SDL_PIXELFORMAT_YUY2 = /**< Packed mode: Y0+U0+Y1+V0 (1 plane) */
282 SDL_DEFINE_PIXELFOURCC('Y', 'U', 'Y', '2'),
283 SDL_PIXELFORMAT_UYVY = /**< Packed mode: U0+Y0+V0+Y1 (1 plane) */
284 SDL_DEFINE_PIXELFOURCC('U', 'Y', 'V', 'Y'),
285 SDL_PIXELFORMAT_YVYU = /**< Packed mode: Y0+V0+Y1+U0 (1 plane) */
286 SDL_DEFINE_PIXELFOURCC('Y', 'V', 'Y', 'U'),
287 SDL_PIXELFORMAT_NV12 = /**< Planar mode: Y + U/V interleaved (2 planes) */
288 SDL_DEFINE_PIXELFOURCC('N', 'V', '1', '2'),
289 SDL_PIXELFORMAT_NV21 = /**< Planar mode: Y + V/U interleaved (2 planes) */
290 SDL_DEFINE_PIXELFOURCC('N', 'V', '2', '1'),
291 SDL_PIXELFORMAT_EXTERNAL_OES = /**< Android video texture format */
292 SDL_DEFINE_PIXELFOURCC('O', 'E', 'S', ' ')
294
295typedef struct SDL_Color
296{
301} SDL_Color;
302#define SDL_Colour SDL_Color
303
304typedef struct SDL_Palette
305{
311
312/**
313 * \note Everything in the pixel format structure is read-only.
314 */
315typedef struct SDL_PixelFormat
316{
337
338/**
339 * \brief Get the human readable name of a pixel format
340 */
342
343/**
344 * \brief Convert one of the enumerated pixel formats to a bpp and RGBA masks.
345 *
346 * \return SDL_TRUE, or SDL_FALSE if the conversion wasn't possible.
347 *
348 * \sa SDL_MasksToPixelFormatEnum()
349 */
351 int *bpp,
352 Uint32 * Rmask,
353 Uint32 * Gmask,
354 Uint32 * Bmask,
355 Uint32 * Amask);
356
357/**
358 * \brief Convert a bpp and RGBA masks to an enumerated pixel format.
359 *
360 * \return The pixel format, or ::SDL_PIXELFORMAT_UNKNOWN if the conversion
361 * wasn't possible.
362 *
363 * \sa SDL_PixelFormatEnumToMasks()
364 */
369 Uint32 Amask);
370
371/**
372 * \brief Create an SDL_PixelFormat structure from a pixel format enum.
373 */
375
376/**
377 * \brief Free an SDL_PixelFormat structure.
378 */
380
381/**
382 * \brief Create a palette structure with the specified number of color
383 * entries.
384 *
385 * \return A new palette, or NULL if there wasn't enough memory.
386 *
387 * \note The palette entries are initialized to white.
388 *
389 * \sa SDL_FreePalette()
390 */
391extern DECLSPEC SDL_Palette *SDLCALL SDL_AllocPalette(int ncolors);
392
393/**
394 * \brief Set the palette for a pixel format structure.
395 */
398
399/**
400 * \brief Set a range of colors in a palette.
401 *
402 * \param palette The palette to modify.
403 * \param colors An array of colors to copy into the palette.
404 * \param firstcolor The index of the first palette entry to modify.
405 * \param ncolors The number of entries to modify.
406 *
407 * \return 0 on success, or -1 if not all of the colors could be set.
408 */
410 const SDL_Color * colors,
411 int firstcolor, int ncolors);
412
413/**
414 * \brief Free a palette created with SDL_AllocPalette().
415 *
416 * \sa SDL_AllocPalette()
417 */
419
420/**
421 * \brief Maps an RGB triple to an opaque pixel value for a given pixel format.
422 *
423 * \sa SDL_MapRGBA
424 */
426 Uint8 r, Uint8 g, Uint8 b);
427
428/**
429 * \brief Maps an RGBA quadruple to a pixel value for a given pixel format.
430 *
431 * \sa SDL_MapRGB
432 */
434 Uint8 r, Uint8 g, Uint8 b,
435 Uint8 a);
436
437/**
438 * \brief Get the RGB components from a pixel of the specified format.
439 *
440 * \sa SDL_GetRGBA
441 */
442extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel,
443 const SDL_PixelFormat * format,
444 Uint8 * r, Uint8 * g, Uint8 * b);
445
446/**
447 * \brief Get the RGBA components from a pixel of the specified format.
448 *
449 * \sa SDL_GetRGB
450 */
451extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel,
452 const SDL_PixelFormat * format,
453 Uint8 * r, Uint8 * g, Uint8 * b,
454 Uint8 * a);
455
456/**
457 * \brief Calculate a 256 entry gamma ramp for a gamma value.
458 */
459extern DECLSPEC void SDLCALL SDL_CalculateGammaRamp(float gamma, Uint16 * ramp);
460
461
462/* Ends C function definitions when using C++ */
463#ifdef __cplusplus
464}
465#endif
466#include "close_code.h"
467
468#endif /* SDL_pixels_h_ */
469
470/* vi: set ts=4 sw=4 expandtab: */
#define SDLCALL
Definition: SDL_internal.h:49
#define DECLSPEC
Definition: SDL_internal.h:48
GLdouble GLdouble GLdouble r
Definition: SDL_opengl.h:2079
GLint GLint GLsizei GLsizei GLsizei GLint GLenum format
Definition: SDL_opengl.h:1572
GLboolean GLboolean GLboolean b
GLboolean GLboolean GLboolean GLboolean a
GLboolean GLboolean g
int SDL_SetPaletteColors(SDL_Palette *palette, const SDL_Color *colors, int firstcolor, int ncolors)
Set a range of colors in a palette.
Definition: SDL_pixels.c:698
@ SDL_ARRAYORDER_RGB
Definition: SDL_pixels.h:95
@ SDL_ARRAYORDER_NONE
Definition: SDL_pixels.h:94
@ SDL_ARRAYORDER_ARGB
Definition: SDL_pixels.h:97
@ SDL_ARRAYORDER_BGRA
Definition: SDL_pixels.h:99
@ SDL_ARRAYORDER_ABGR
Definition: SDL_pixels.h:100
@ SDL_ARRAYORDER_RGBA
Definition: SDL_pixels.h:96
@ SDL_ARRAYORDER_BGR
Definition: SDL_pixels.h:98
int SDL_SetPixelFormatPalette(SDL_PixelFormat *format, SDL_Palette *palette)
Set the palette for a pixel format structure.
Definition: SDL_pixels.c:670
void SDL_CalculateGammaRamp(float gamma, Uint16 *ramp)
Calculate a 256 entry gamma ramp for a gamma value.
Definition: SDL_pixels.c:1086
void SDL_FreeFormat(SDL_PixelFormat *format)
Free an SDL_PixelFormat structure.
Definition: SDL_pixels.c:602
SDL_bool SDL_PixelFormatEnumToMasks(Uint32 format, int *bpp, Uint32 *Rmask, Uint32 *Gmask, Uint32 *Bmask, Uint32 *Amask)
Convert one of the enumerated pixel formats to a bpp and RGBA masks.
Definition: SDL_pixels.c:134
SDL_PixelFormat * SDL_AllocFormat(Uint32 pixel_format)
Create an SDL_PixelFormat structure from a pixel format enum.
Definition: SDL_pixels.c:496
const char * SDL_GetPixelFormatName(Uint32 format)
Get the human readable name of a pixel format.
Definition: SDL_pixels.c:86
Uint32 SDL_MapRGBA(const SDL_PixelFormat *format, Uint8 r, Uint8 g, Uint8 b, Uint8 a)
Maps an RGBA quadruple to a pixel value for a given pixel format.
Definition: SDL_pixels.c:812
Uint32 SDL_MasksToPixelFormatEnum(int bpp, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask)
Convert a bpp and RGBA masks to an enumerated pixel format.
Definition: SDL_pixels.c:293
Uint32 SDL_MapRGB(const SDL_PixelFormat *format, Uint8 r, Uint8 g, Uint8 b)
Maps an RGB triple to an opaque pixel value for a given pixel format.
Definition: SDL_pixels.c:799
@ SDL_BITMAPORDER_1234
Definition: SDL_pixels.h:72
@ SDL_BITMAPORDER_NONE
Definition: SDL_pixels.h:70
@ SDL_BITMAPORDER_4321
Definition: SDL_pixels.h:71
@ SDL_PACKEDORDER_NONE
Definition: SDL_pixels.h:78
@ SDL_PACKEDORDER_RGBX
Definition: SDL_pixels.h:80
@ SDL_PACKEDORDER_BGRX
Definition: SDL_pixels.h:84
@ SDL_PACKEDORDER_XBGR
Definition: SDL_pixels.h:83
@ SDL_PACKEDORDER_RGBA
Definition: SDL_pixels.h:82
@ SDL_PACKEDORDER_ABGR
Definition: SDL_pixels.h:85
@ SDL_PACKEDORDER_BGRA
Definition: SDL_pixels.h:86
@ SDL_PACKEDORDER_XRGB
Definition: SDL_pixels.h:79
@ SDL_PACKEDORDER_ARGB
Definition: SDL_pixels.h:81
#define SDL_DEFINE_PIXELFOURCC(A, B, C, D)
Definition: SDL_pixels.h:117
SDL_Palette * SDL_AllocPalette(int ncolors)
Create a palette structure with the specified number of color entries.
Definition: SDL_pixels.c:639
SDL_PixelFormatEnum
Definition: SDL_pixels.h:172
@ SDL_PIXELFORMAT_BGR565
Definition: SDL_pixels.h:227
@ SDL_PIXELFORMAT_EXTERNAL_OES
Definition: SDL_pixels.h:291
@ SDL_PIXELFORMAT_YVYU
Definition: SDL_pixels.h:285
@ SDL_PIXELFORMAT_RGB332
Definition: SDL_pixels.h:188
@ SDL_PIXELFORMAT_INDEX1LSB
Definition: SDL_pixels.h:174
@ SDL_PIXELFORMAT_ABGR4444
Definition: SDL_pixels.h:206
@ SDL_PIXELFORMAT_BGRA4444
Definition: SDL_pixels.h:209
@ SDL_PIXELFORMAT_BGR24
Definition: SDL_pixels.h:233
@ SDL_PIXELFORMAT_INDEX4MSB
Definition: SDL_pixels.h:183
@ SDL_PIXELFORMAT_BGRA32
Definition: SDL_pixels.h:273
@ SDL_PIXELFORMAT_RGB555
Definition: SDL_pixels.h:194
@ SDL_PIXELFORMAT_RGB444
Definition: SDL_pixels.h:191
@ SDL_PIXELFORMAT_RGBA8888
Definition: SDL_pixels.h:251
@ SDL_PIXELFORMAT_RGBA5551
Definition: SDL_pixels.h:215
@ SDL_PIXELFORMAT_ARGB1555
Definition: SDL_pixels.h:212
@ SDL_PIXELFORMAT_INDEX8
Definition: SDL_pixels.h:186
@ SDL_PIXELFORMAT_UYVY
Definition: SDL_pixels.h:283
@ SDL_PIXELFORMAT_BGR888
Definition: SDL_pixels.h:242
@ SDL_PIXELFORMAT_YV12
Definition: SDL_pixels.h:277
@ SDL_PIXELFORMAT_ABGR32
Definition: SDL_pixels.h:274
@ SDL_PIXELFORMAT_BGRX8888
Definition: SDL_pixels.h:245
@ SDL_PIXELFORMAT_RGB24
Definition: SDL_pixels.h:230
@ SDL_PIXELFORMAT_RGB888
Definition: SDL_pixels.h:236
@ SDL_PIXELFORMAT_ABGR8888
Definition: SDL_pixels.h:254
@ SDL_PIXELFORMAT_YUY2
Definition: SDL_pixels.h:281
@ SDL_PIXELFORMAT_NV12
Definition: SDL_pixels.h:287
@ SDL_PIXELFORMAT_BGRA8888
Definition: SDL_pixels.h:257
@ SDL_PIXELFORMAT_ARGB32
Definition: SDL_pixels.h:272
@ SDL_PIXELFORMAT_ABGR1555
Definition: SDL_pixels.h:218
@ SDL_PIXELFORMAT_NV21
Definition: SDL_pixels.h:289
@ SDL_PIXELFORMAT_IYUV
Definition: SDL_pixels.h:279
@ SDL_PIXELFORMAT_ARGB8888
Definition: SDL_pixels.h:248
@ SDL_PIXELFORMAT_ARGB4444
Definition: SDL_pixels.h:200
@ SDL_PIXELFORMAT_RGBA32
Definition: SDL_pixels.h:271
@ SDL_PIXELFORMAT_INDEX1MSB
Definition: SDL_pixels.h:177
@ SDL_PIXELFORMAT_INDEX4LSB
Definition: SDL_pixels.h:180
@ SDL_PIXELFORMAT_RGBX8888
Definition: SDL_pixels.h:239
@ SDL_PIXELFORMAT_BGRA5551
Definition: SDL_pixels.h:221
@ SDL_PIXELFORMAT_RGB565
Definition: SDL_pixels.h:224
@ SDL_PIXELFORMAT_ARGB2101010
Definition: SDL_pixels.h:260
@ SDL_PIXELFORMAT_BGR555
Definition: SDL_pixels.h:197
@ SDL_PIXELFORMAT_UNKNOWN
Definition: SDL_pixels.h:173
@ SDL_PIXELFORMAT_RGBA4444
Definition: SDL_pixels.h:203
#define SDL_DEFINE_PIXELFORMAT(type, order, layout, bits, bytes)
Definition: SDL_pixels.h:119
void SDL_GetRGBA(Uint32 pixel, const SDL_PixelFormat *format, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a)
Get the RGBA components from a pixel of the specified format.
Definition: SDL_pixels.c:849
@ SDL_PACKEDLAYOUT_NONE
Definition: SDL_pixels.h:106
@ SDL_PACKEDLAYOUT_8888
Definition: SDL_pixels.h:112
@ SDL_PACKEDLAYOUT_1010102
Definition: SDL_pixels.h:114
@ SDL_PACKEDLAYOUT_565
Definition: SDL_pixels.h:111
@ SDL_PACKEDLAYOUT_332
Definition: SDL_pixels.h:107
@ SDL_PACKEDLAYOUT_5551
Definition: SDL_pixels.h:110
@ SDL_PACKEDLAYOUT_1555
Definition: SDL_pixels.h:109
@ SDL_PACKEDLAYOUT_4444
Definition: SDL_pixels.h:108
@ SDL_PACKEDLAYOUT_2101010
Definition: SDL_pixels.h:113
void SDL_GetRGB(Uint32 pixel, const SDL_PixelFormat *format, Uint8 *r, Uint8 *g, Uint8 *b)
Get the RGB components from a pixel of the specified format.
Definition: SDL_pixels.c:826
void SDL_FreePalette(SDL_Palette *palette)
Free a palette created with SDL_AllocPalette().
Definition: SDL_pixels.c:725
@ SDL_PIXELTYPE_UNKNOWN
Definition: SDL_pixels.h:53
@ SDL_PIXELTYPE_ARRAYU16
Definition: SDL_pixels.h:61
@ SDL_PIXELTYPE_PACKED32
Definition: SDL_pixels.h:59
@ SDL_PIXELTYPE_ARRAYU8
Definition: SDL_pixels.h:60
@ SDL_PIXELTYPE_INDEX4
Definition: SDL_pixels.h:55
@ SDL_PIXELTYPE_PACKED8
Definition: SDL_pixels.h:57
@ SDL_PIXELTYPE_ARRAYF16
Definition: SDL_pixels.h:63
@ SDL_PIXELTYPE_ARRAYU32
Definition: SDL_pixels.h:62
@ SDL_PIXELTYPE_INDEX1
Definition: SDL_pixels.h:54
@ SDL_PIXELTYPE_ARRAYF32
Definition: SDL_pixels.h:64
@ SDL_PIXELTYPE_INDEX8
Definition: SDL_pixels.h:56
@ SDL_PIXELTYPE_PACKED16
Definition: SDL_pixels.h:58
SDL_bool
Definition: SDL_stdinc.h:162
uint32_t Uint32
Definition: SDL_stdinc.h:203
uint16_t Uint16
Definition: SDL_stdinc.h:191
uint8_t Uint8
Definition: SDL_stdinc.h:179
Uint8 r
Definition: SDL_pixels.h:297
Uint8 b
Definition: SDL_pixels.h:299
Uint8 a
Definition: SDL_pixels.h:300
Uint8 g
Definition: SDL_pixels.h:298
Uint32 version
Definition: SDL_pixels.h:308
SDL_Color * colors
Definition: SDL_pixels.h:307
struct SDL_PixelFormat * next
Definition: SDL_pixels.h:335
Uint8 padding[2]
Definition: SDL_pixels.h:321
Uint8 BytesPerPixel
Definition: SDL_pixels.h:320
Uint8 BitsPerPixel
Definition: SDL_pixels.h:319
SDL_Palette * palette
Definition: SDL_pixels.h:318
static int colors[7]
Definition: testgesture.c:41