SDL  2.0
SDL_pixels.h
Go to the documentation of this file.
1 /*
2  Simple DirectMedia Layer
3  Copyright (C) 1997-2016 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 {
64 };
65 
66 /** Bitmap pixel order, high bit -> low bit. */
67 enum
68 {
72 };
73 
74 /** Packed component order, high bit -> low bit. */
75 enum
76 {
86 };
87 
88 /** Array component order, low byte -> high byte. */
89 /* !!! FIXME: in 2.1, make these not overlap differently with
90  !!! FIXME: SDL_PACKEDORDER_*, so we can simplify SDL_ISPIXELFORMAT_ALPHA */
91 enum
92 {
100 };
101 
102 /** Packed component layout. */
103 enum
104 {
114 };
115 
116 #define SDL_DEFINE_PIXELFOURCC(A, B, C, D) SDL_FOURCC(A, B, C, D)
117 
118 #define SDL_DEFINE_PIXELFORMAT(type, order, layout, bits, bytes) \
119  ((1 << 28) | ((type) << 24) | ((order) << 20) | ((layout) << 16) | \
120  ((bits) << 8) | ((bytes) << 0))
121 
122 #define SDL_PIXELFLAG(X) (((X) >> 28) & 0x0F)
123 #define SDL_PIXELTYPE(X) (((X) >> 24) & 0x0F)
124 #define SDL_PIXELORDER(X) (((X) >> 20) & 0x0F)
125 #define SDL_PIXELLAYOUT(X) (((X) >> 16) & 0x0F)
126 #define SDL_BITSPERPIXEL(X) (((X) >> 8) & 0xFF)
127 #define SDL_BYTESPERPIXEL(X) \
128  (SDL_ISPIXELFORMAT_FOURCC(X) ? \
129  ((((X) == SDL_PIXELFORMAT_YUY2) || \
130  ((X) == SDL_PIXELFORMAT_UYVY) || \
131  ((X) == SDL_PIXELFORMAT_YVYU)) ? 2 : 1) : (((X) >> 0) & 0xFF))
132 
133 #define SDL_ISPIXELFORMAT_INDEXED(format) \
134  (!SDL_ISPIXELFORMAT_FOURCC(format) && \
135  ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX1) || \
136  (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX4) || \
137  (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX8)))
138 
139 #define SDL_ISPIXELFORMAT_PACKED(format) \
140  (!SDL_ISPIXELFORMAT_FOURCC(format) && \
141  ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED8) || \
142  (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED16) || \
143  (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED32)))
144 
145 #define SDL_ISPIXELFORMAT_ARRAY(format) \
146  (!SDL_ISPIXELFORMAT_FOURCC(format) && \
147  ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYU8) || \
148  (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYU16) || \
149  (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYU32) || \
150  (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF16) || \
151  (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF32)))
152 
153 #define SDL_ISPIXELFORMAT_ALPHA(format) \
154  ((SDL_ISPIXELFORMAT_PACKED(format) && \
155  ((SDL_PIXELORDER(format) == SDL_PACKEDORDER_ARGB) || \
156  (SDL_PIXELORDER(format) == SDL_PACKEDORDER_RGBA) || \
157  (SDL_PIXELORDER(format) == SDL_PACKEDORDER_ABGR) || \
158  (SDL_PIXELORDER(format) == SDL_PACKEDORDER_BGRA))) || \
159  (SDL_ISPIXELFORMAT_ARRAY(format) && \
160  ((SDL_PIXELORDER(format) == SDL_ARRAYORDER_ARGB) || \
161  (SDL_PIXELORDER(format) == SDL_ARRAYORDER_RGBA) || \
162  (SDL_PIXELORDER(format) == SDL_ARRAYORDER_ABGR) || \
163  (SDL_PIXELORDER(format) == SDL_ARRAYORDER_BGRA))))
164 
165 /* The flag is set to 1 because 0x1? is not in the printable ASCII range */
166 #define SDL_ISPIXELFORMAT_FOURCC(format) \
167  ((format) && (SDL_PIXELFLAG(format) != 1))
168 
169 /* Note: If you modify this list, update SDL_GetPixelFormatName() */
170 enum
171 {
175  1, 0),
178  1, 0),
181  4, 0),
184  4, 0),
189  SDL_PACKEDLAYOUT_332, 8, 1),
192  SDL_PACKEDLAYOUT_4444, 12, 2),
195  SDL_PACKEDLAYOUT_1555, 15, 2),
198  SDL_PACKEDLAYOUT_1555, 15, 2),
201  SDL_PACKEDLAYOUT_4444, 16, 2),
204  SDL_PACKEDLAYOUT_4444, 16, 2),
207  SDL_PACKEDLAYOUT_4444, 16, 2),
210  SDL_PACKEDLAYOUT_4444, 16, 2),
213  SDL_PACKEDLAYOUT_1555, 16, 2),
216  SDL_PACKEDLAYOUT_5551, 16, 2),
219  SDL_PACKEDLAYOUT_1555, 16, 2),
222  SDL_PACKEDLAYOUT_5551, 16, 2),
225  SDL_PACKEDLAYOUT_565, 16, 2),
228  SDL_PACKEDLAYOUT_565, 16, 2),
231  24, 3),
234  24, 3),
237  SDL_PACKEDLAYOUT_8888, 24, 4),
240  SDL_PACKEDLAYOUT_8888, 24, 4),
243  SDL_PACKEDLAYOUT_8888, 24, 4),
246  SDL_PACKEDLAYOUT_8888, 24, 4),
249  SDL_PACKEDLAYOUT_8888, 32, 4),
252  SDL_PACKEDLAYOUT_8888, 32, 4),
255  SDL_PACKEDLAYOUT_8888, 32, 4),
258  SDL_PACKEDLAYOUT_8888, 32, 4),
261  SDL_PACKEDLAYOUT_2101010, 32, 4),
262 
263  SDL_PIXELFORMAT_YV12 = /**< Planar mode: Y + V + U (3 planes) */
264  SDL_DEFINE_PIXELFOURCC('Y', 'V', '1', '2'),
265  SDL_PIXELFORMAT_IYUV = /**< Planar mode: Y + U + V (3 planes) */
266  SDL_DEFINE_PIXELFOURCC('I', 'Y', 'U', 'V'),
267  SDL_PIXELFORMAT_YUY2 = /**< Packed mode: Y0+U0+Y1+V0 (1 plane) */
268  SDL_DEFINE_PIXELFOURCC('Y', 'U', 'Y', '2'),
269  SDL_PIXELFORMAT_UYVY = /**< Packed mode: U0+Y0+V0+Y1 (1 plane) */
270  SDL_DEFINE_PIXELFOURCC('U', 'Y', 'V', 'Y'),
271  SDL_PIXELFORMAT_YVYU = /**< Packed mode: Y0+V0+Y1+U0 (1 plane) */
272  SDL_DEFINE_PIXELFOURCC('Y', 'V', 'Y', 'U'),
273  SDL_PIXELFORMAT_NV12 = /**< Planar mode: Y + U/V interleaved (2 planes) */
274  SDL_DEFINE_PIXELFOURCC('N', 'V', '1', '2'),
275  SDL_PIXELFORMAT_NV21 = /**< Planar mode: Y + V/U interleaved (2 planes) */
276  SDL_DEFINE_PIXELFOURCC('N', 'V', '2', '1')
277 };
278 
279 typedef struct SDL_Color
280 {
285 } SDL_Color;
286 #define SDL_Colour SDL_Color
287 
288 typedef struct SDL_Palette
289 {
290  int ncolors;
293  int refcount;
294 } SDL_Palette;
295 
296 /**
297  * \note Everything in the pixel format structure is read-only.
298  */
299 typedef struct SDL_PixelFormat
300 {
305  Uint8 padding[2];
318  int refcount;
321 
322 /**
323  * \brief Get the human readable name of a pixel format
324  */
326 
327 /**
328  * \brief Convert one of the enumerated pixel formats to a bpp and RGBA masks.
329  *
330  * \return SDL_TRUE, or SDL_FALSE if the conversion wasn't possible.
331  *
332  * \sa SDL_MasksToPixelFormatEnum()
333  */
335  int *bpp,
336  Uint32 * Rmask,
337  Uint32 * Gmask,
338  Uint32 * Bmask,
339  Uint32 * Amask);
340 
341 /**
342  * \brief Convert a bpp and RGBA masks to an enumerated pixel format.
343  *
344  * \return The pixel format, or ::SDL_PIXELFORMAT_UNKNOWN if the conversion
345  * wasn't possible.
346  *
347  * \sa SDL_PixelFormatEnumToMasks()
348  */
350  Uint32 Rmask,
351  Uint32 Gmask,
352  Uint32 Bmask,
353  Uint32 Amask);
354 
355 /**
356  * \brief Create an SDL_PixelFormat structure from a pixel format enum.
357  */
359 
360 /**
361  * \brief Free an SDL_PixelFormat structure.
362  */
364 
365 /**
366  * \brief Create a palette structure with the specified number of color
367  * entries.
368  *
369  * \return A new palette, or NULL if there wasn't enough memory.
370  *
371  * \note The palette entries are initialized to white.
372  *
373  * \sa SDL_FreePalette()
374  */
375 extern DECLSPEC SDL_Palette *SDLCALL SDL_AllocPalette(int ncolors);
376 
377 /**
378  * \brief Set the palette for a pixel format structure.
379  */
382 
383 /**
384  * \brief Set a range of colors in a palette.
385  *
386  * \param palette The palette to modify.
387  * \param colors An array of colors to copy into the palette.
388  * \param firstcolor The index of the first palette entry to modify.
389  * \param ncolors The number of entries to modify.
390  *
391  * \return 0 on success, or -1 if not all of the colors could be set.
392  */
394  const SDL_Color * colors,
395  int firstcolor, int ncolors);
396 
397 /**
398  * \brief Free a palette created with SDL_AllocPalette().
399  *
400  * \sa SDL_AllocPalette()
401  */
403 
404 /**
405  * \brief Maps an RGB triple to an opaque pixel value for a given pixel format.
406  *
407  * \sa SDL_MapRGBA
408  */
410  Uint8 r, Uint8 g, Uint8 b);
411 
412 /**
413  * \brief Maps an RGBA quadruple to a pixel value for a given pixel format.
414  *
415  * \sa SDL_MapRGB
416  */
418  Uint8 r, Uint8 g, Uint8 b,
419  Uint8 a);
420 
421 /**
422  * \brief Get the RGB components from a pixel of the specified format.
423  *
424  * \sa SDL_GetRGBA
425  */
426 extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel,
427  const SDL_PixelFormat * format,
428  Uint8 * r, Uint8 * g, Uint8 * b);
429 
430 /**
431  * \brief Get the RGBA components from a pixel of the specified format.
432  *
433  * \sa SDL_GetRGB
434  */
435 extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel,
436  const SDL_PixelFormat * format,
437  Uint8 * r, Uint8 * g, Uint8 * b,
438  Uint8 * a);
439 
440 /**
441  * \brief Calculate a 256 entry gamma ramp for a gamma value.
442  */
443 extern DECLSPEC void SDLCALL SDL_CalculateGammaRamp(float gamma, Uint16 * ramp);
444 
445 
446 /* Ends C function definitions when using C++ */
447 #ifdef __cplusplus
448 }
449 #endif
450 #include "close_code.h"
451 
452 #endif /* _SDL_pixels_h */
453 
454 /* vi: set ts=4 sw=4 expandtab: */
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:814
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:851
GLdouble GLdouble GLdouble r
Definition: SDL_opengl.h:2072
Uint32 version
Definition: SDL_pixels.h:292
uint32_t Uint32
An unsigned 32-bit integer type.
Definition: SDL_stdinc.h:155
SDL_PixelFormat * SDL_AllocFormat(Uint32 pixel_format)
Create an SDL_PixelFormat structure from a pixel format enum.
Definition: SDL_pixels.c:488
Uint8 g
Definition: SDL_pixels.h:282
Uint8 BytesPerPixel
Definition: SDL_pixels.h:304
void SDL_FreeFormat(SDL_PixelFormat *format)
Free an SDL_PixelFormat structure.
Definition: SDL_pixels.c:586
Uint8 b
Definition: SDL_pixels.h:283
void SDL_FreePalette(SDL_Palette *palette)
Free a palette created with SDL_AllocPalette().
Definition: SDL_pixels.c:703
#define SDL_DEFINE_PIXELFOURCC(A, B, C, D)
Definition: SDL_pixels.h:116
SDL_bool
Definition: SDL_stdinc.h:126
GLboolean GLboolean g
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
#define DECLSPEC
Definition: SDL_internal.h:30
Uint8 r
Definition: SDL_pixels.h:281
int SDL_SetPixelFormatPalette(SDL_PixelFormat *format, SDL_Palette *palette)
Set the palette for a pixel format structure.
Definition: SDL_pixels.c:648
Uint8 a
Definition: SDL_pixels.h:284
uint8_t Uint8
An unsigned 8-bit integer type.
Definition: SDL_stdinc.h:139
Uint8 BitsPerPixel
Definition: SDL_pixels.h:303
SDL_Palette * SDL_AllocPalette(int ncolors)
Create a palette structure with the specified number of color entries.
Definition: SDL_pixels.c:617
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:676
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:801
SDL_Color * colors
Definition: SDL_pixels.h:291
GLint GLint GLsizei GLsizei GLsizei GLint GLenum format
Definition: SDL_opengl.h:1565
#define SDL_DEFINE_PIXELFORMAT(type, order, layout, bits, bytes)
Definition: SDL_pixels.h:118
const char * SDL_GetPixelFormatName(Uint32 format)
Get the human readable name of a pixel format.
Definition: SDL_pixels.c:86
void SDL_CalculateGammaRamp(float gamma, Uint16 *ramp)
Calculate a 256 entry gamma ramp for a gamma value.
Definition: SDL_pixels.c:1088
uint16_t Uint16
An unsigned 16-bit integer type.
Definition: SDL_stdinc.h:147
Uint32 pixel_format
Definition: testoverlay2.c:152
SDL_Palette * palette
Definition: SDL_pixels.h:302
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:828
static int colors[7]
Definition: testgesture.c:40
GLboolean GLboolean GLboolean GLboolean a
#define SDLCALL
Definition: SDL_internal.h:31
GLboolean GLboolean GLboolean b
struct SDL_PixelFormat * next
Definition: SDL_pixels.h:319
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