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 #include "SDL_endian.h"
33 
34 #include "begin_code.h"
35 /* Set up for C function definitions, even when using C++ */
36 #ifdef __cplusplus
37 extern "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. */
51 enum
52 {
65 };
66 
67 /** Bitmap pixel order, high bit -> low bit. */
68 enum
69 {
73 };
74 
75 /** Packed component order, high bit -> low bit. */
76 enum
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 */
92 enum
93 {
101 };
102 
103 /** Packed component layout. */
104 enum
105 {
115 };
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() */
171 enum
172 {
176  1, 0),
179  1, 0),
182  4, 0),
185  4, 0),
190  SDL_PACKEDLAYOUT_332, 8, 1),
193  SDL_PACKEDLAYOUT_4444, 12, 2),
196  SDL_PACKEDLAYOUT_1555, 15, 2),
199  SDL_PACKEDLAYOUT_1555, 15, 2),
202  SDL_PACKEDLAYOUT_4444, 16, 2),
205  SDL_PACKEDLAYOUT_4444, 16, 2),
208  SDL_PACKEDLAYOUT_4444, 16, 2),
211  SDL_PACKEDLAYOUT_4444, 16, 2),
214  SDL_PACKEDLAYOUT_1555, 16, 2),
217  SDL_PACKEDLAYOUT_5551, 16, 2),
220  SDL_PACKEDLAYOUT_1555, 16, 2),
223  SDL_PACKEDLAYOUT_5551, 16, 2),
226  SDL_PACKEDLAYOUT_565, 16, 2),
229  SDL_PACKEDLAYOUT_565, 16, 2),
232  24, 3),
235  24, 3),
238  SDL_PACKEDLAYOUT_8888, 24, 4),
241  SDL_PACKEDLAYOUT_8888, 24, 4),
244  SDL_PACKEDLAYOUT_8888, 24, 4),
247  SDL_PACKEDLAYOUT_8888, 24, 4),
250  SDL_PACKEDLAYOUT_8888, 32, 4),
253  SDL_PACKEDLAYOUT_8888, 32, 4),
256  SDL_PACKEDLAYOUT_8888, 32, 4),
259  SDL_PACKEDLAYOUT_8888, 32, 4),
262  SDL_PACKEDLAYOUT_2101010, 32, 4),
263 
264  /* Aliases for RGBA byte arrays of color data, for the current platform */
265 #if SDL_BYTEORDER == SDL_BIG_ENDIAN
270 #else
272  SDL_PIXELFORMAT_ARGB32 = SDL_PIXELFORMAT_BGRA8888,
273  SDL_PIXELFORMAT_BGRA32 = SDL_PIXELFORMAT_ARGB8888,
274  SDL_PIXELFORMAT_ABGR32 = SDL_PIXELFORMAT_RGBA8888,
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 };
292 
293 typedef struct SDL_Color
294 {
299 } SDL_Color;
300 #define SDL_Colour SDL_Color
301 
302 typedef struct SDL_Palette
303 {
304  int ncolors;
307  int refcount;
308 } SDL_Palette;
309 
310 /**
311  * \note Everything in the pixel format structure is read-only.
312  */
313 typedef struct SDL_PixelFormat
314 {
319  Uint8 padding[2];
332  int refcount;
335 
336 /**
337  * \brief Get the human readable name of a pixel format
338  */
340 
341 /**
342  * \brief Convert one of the enumerated pixel formats to a bpp and RGBA masks.
343  *
344  * \return SDL_TRUE, or SDL_FALSE if the conversion wasn't possible.
345  *
346  * \sa SDL_MasksToPixelFormatEnum()
347  */
349  int *bpp,
350  Uint32 * Rmask,
351  Uint32 * Gmask,
352  Uint32 * Bmask,
353  Uint32 * Amask);
354 
355 /**
356  * \brief Convert a bpp and RGBA masks to an enumerated pixel format.
357  *
358  * \return The pixel format, or ::SDL_PIXELFORMAT_UNKNOWN if the conversion
359  * wasn't possible.
360  *
361  * \sa SDL_PixelFormatEnumToMasks()
362  */
364  Uint32 Rmask,
365  Uint32 Gmask,
366  Uint32 Bmask,
367  Uint32 Amask);
368 
369 /**
370  * \brief Create an SDL_PixelFormat structure from a pixel format enum.
371  */
373 
374 /**
375  * \brief Free an SDL_PixelFormat structure.
376  */
378 
379 /**
380  * \brief Create a palette structure with the specified number of color
381  * entries.
382  *
383  * \return A new palette, or NULL if there wasn't enough memory.
384  *
385  * \note The palette entries are initialized to white.
386  *
387  * \sa SDL_FreePalette()
388  */
389 extern DECLSPEC SDL_Palette *SDLCALL SDL_AllocPalette(int ncolors);
390 
391 /**
392  * \brief Set the palette for a pixel format structure.
393  */
396 
397 /**
398  * \brief Set a range of colors in a palette.
399  *
400  * \param palette The palette to modify.
401  * \param colors An array of colors to copy into the palette.
402  * \param firstcolor The index of the first palette entry to modify.
403  * \param ncolors The number of entries to modify.
404  *
405  * \return 0 on success, or -1 if not all of the colors could be set.
406  */
408  const SDL_Color * colors,
409  int firstcolor, int ncolors);
410 
411 /**
412  * \brief Free a palette created with SDL_AllocPalette().
413  *
414  * \sa SDL_AllocPalette()
415  */
417 
418 /**
419  * \brief Maps an RGB triple to an opaque pixel value for a given pixel format.
420  *
421  * \sa SDL_MapRGBA
422  */
424  Uint8 r, Uint8 g, Uint8 b);
425 
426 /**
427  * \brief Maps an RGBA quadruple to a pixel value for a given pixel format.
428  *
429  * \sa SDL_MapRGB
430  */
432  Uint8 r, Uint8 g, Uint8 b,
433  Uint8 a);
434 
435 /**
436  * \brief Get the RGB components from a pixel of the specified format.
437  *
438  * \sa SDL_GetRGBA
439  */
440 extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel,
441  const SDL_PixelFormat * format,
442  Uint8 * r, Uint8 * g, Uint8 * b);
443 
444 /**
445  * \brief Get the RGBA components from a pixel of the specified format.
446  *
447  * \sa SDL_GetRGB
448  */
449 extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel,
450  const SDL_PixelFormat * format,
451  Uint8 * r, Uint8 * g, Uint8 * b,
452  Uint8 * a);
453 
454 /**
455  * \brief Calculate a 256 entry gamma ramp for a gamma value.
456  */
457 extern DECLSPEC void SDLCALL SDL_CalculateGammaRamp(float gamma, Uint16 * ramp);
458 
459 
460 /* Ends C function definitions when using C++ */
461 #ifdef __cplusplus
462 }
463 #endif
464 #include "close_code.h"
465 
466 #endif /* _SDL_pixels_h */
467 
468 /* 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
GLint GLint GLsizei GLsizei GLsizei GLint GLenum format
Definition: SDL_opengl.h:1565
Uint32 version
Definition: SDL_pixels.h:306
GLdouble GLdouble GLdouble r
Definition: SDL_opengl.h:2072
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:296
Uint8 BytesPerPixel
Definition: SDL_pixels.h:318
void SDL_FreeFormat(SDL_PixelFormat *format)
Free an SDL_PixelFormat structure.
Definition: SDL_pixels.c:586
Uint8 b
Definition: SDL_pixels.h:297
uint32_t Uint32
An unsigned 32-bit integer type.
Definition: SDL_stdinc.h:161
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:117
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:295
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:298
uint8_t Uint8
An unsigned 8-bit integer type.
Definition: SDL_stdinc.h:143
Uint8 BitsPerPixel
Definition: SDL_pixels.h:317
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_bool
Definition: SDL_stdinc.h:130
SDL_Color * colors
Definition: SDL_pixels.h:305
#define SDL_DEFINE_PIXELFORMAT(type, order, layout, bits, bytes)
Definition: SDL_pixels.h:119
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:151
Uint32 pixel_format
Definition: testoverlay2.c:152
SDL_Palette * palette
Definition: SDL_pixels.h:316
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:333
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