SDL  2.0
SDL_pixels.h
Go to the documentation of this file.
1 /*
2  Simple DirectMedia Layer
3  Copyright (C) 1997-2020 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 typedef enum
52 {
66 
67 /** Bitmap pixel order, high bit -> low bit. */
68 typedef enum
69 {
74 
75 /** Packed component order, high bit -> low bit. */
76 typedef enum
77 {
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 typedef enum
93 {
102 
103 /** Packed component layout. */
104 typedef enum
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() */
171 typedef 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),
197  SDL_PACKEDLAYOUT_4444, 12, 2),
201  SDL_PACKEDLAYOUT_1555, 15, 2),
205  SDL_PACKEDLAYOUT_1555, 15, 2),
209  SDL_PACKEDLAYOUT_4444, 16, 2),
212  SDL_PACKEDLAYOUT_4444, 16, 2),
215  SDL_PACKEDLAYOUT_4444, 16, 2),
218  SDL_PACKEDLAYOUT_4444, 16, 2),
221  SDL_PACKEDLAYOUT_1555, 16, 2),
224  SDL_PACKEDLAYOUT_5551, 16, 2),
227  SDL_PACKEDLAYOUT_1555, 16, 2),
230  SDL_PACKEDLAYOUT_5551, 16, 2),
233  SDL_PACKEDLAYOUT_565, 16, 2),
236  SDL_PACKEDLAYOUT_565, 16, 2),
239  24, 3),
242  24, 3),
245  SDL_PACKEDLAYOUT_8888, 24, 4),
249  SDL_PACKEDLAYOUT_8888, 24, 4),
252  SDL_PACKEDLAYOUT_8888, 24, 4),
256  SDL_PACKEDLAYOUT_8888, 24, 4),
259  SDL_PACKEDLAYOUT_8888, 32, 4),
262  SDL_PACKEDLAYOUT_8888, 32, 4),
265  SDL_PACKEDLAYOUT_8888, 32, 4),
268  SDL_PACKEDLAYOUT_8888, 32, 4),
271  SDL_PACKEDLAYOUT_2101010, 32, 4),
272 
273  /* Aliases for RGBA byte arrays of color data, for the current platform */
274 #if SDL_BYTEORDER == SDL_BIG_ENDIAN
279 #else
281  SDL_PIXELFORMAT_ARGB32 = SDL_PIXELFORMAT_BGRA8888,
282  SDL_PIXELFORMAT_BGRA32 = SDL_PIXELFORMAT_ARGB8888,
283  SDL_PIXELFORMAT_ABGR32 = SDL_PIXELFORMAT_RGBA8888,
284 #endif
285 
286  SDL_PIXELFORMAT_YV12 = /**< Planar mode: Y + V + U (3 planes) */
287  SDL_DEFINE_PIXELFOURCC('Y', 'V', '1', '2'),
288  SDL_PIXELFORMAT_IYUV = /**< Planar mode: Y + U + V (3 planes) */
289  SDL_DEFINE_PIXELFOURCC('I', 'Y', 'U', 'V'),
290  SDL_PIXELFORMAT_YUY2 = /**< Packed mode: Y0+U0+Y1+V0 (1 plane) */
291  SDL_DEFINE_PIXELFOURCC('Y', 'U', 'Y', '2'),
292  SDL_PIXELFORMAT_UYVY = /**< Packed mode: U0+Y0+V0+Y1 (1 plane) */
293  SDL_DEFINE_PIXELFOURCC('U', 'Y', 'V', 'Y'),
294  SDL_PIXELFORMAT_YVYU = /**< Packed mode: Y0+V0+Y1+U0 (1 plane) */
295  SDL_DEFINE_PIXELFOURCC('Y', 'V', 'Y', 'U'),
296  SDL_PIXELFORMAT_NV12 = /**< Planar mode: Y + U/V interleaved (2 planes) */
297  SDL_DEFINE_PIXELFOURCC('N', 'V', '1', '2'),
298  SDL_PIXELFORMAT_NV21 = /**< Planar mode: Y + V/U interleaved (2 planes) */
299  SDL_DEFINE_PIXELFOURCC('N', 'V', '2', '1'),
300  SDL_PIXELFORMAT_EXTERNAL_OES = /**< Android video texture format */
301  SDL_DEFINE_PIXELFOURCC('O', 'E', 'S', ' ')
303 
304 typedef struct SDL_Color
305 {
310 } SDL_Color;
311 #define SDL_Colour SDL_Color
312 
313 typedef struct SDL_Palette
314 {
315  int ncolors;
318  int refcount;
319 } SDL_Palette;
320 
321 /**
322  * \note Everything in the pixel format structure is read-only.
323  */
324 typedef struct SDL_PixelFormat
325 {
330  Uint8 padding[2];
343  int refcount;
346 
347 /**
348  * \brief Get the human readable name of a pixel format
349  */
350 extern DECLSPEC const char* SDLCALL SDL_GetPixelFormatName(Uint32 format);
351 
352 /**
353  * \brief Convert one of the enumerated pixel formats to a bpp and RGBA masks.
354  *
355  * \return SDL_TRUE, or SDL_FALSE if the conversion wasn't possible.
356  *
357  * \sa SDL_MasksToPixelFormatEnum()
358  */
359 extern DECLSPEC SDL_bool SDLCALL SDL_PixelFormatEnumToMasks(Uint32 format,
360  int *bpp,
361  Uint32 * Rmask,
362  Uint32 * Gmask,
363  Uint32 * Bmask,
364  Uint32 * Amask);
365 
366 /**
367  * \brief Convert a bpp and RGBA masks to an enumerated pixel format.
368  *
369  * \return The pixel format, or ::SDL_PIXELFORMAT_UNKNOWN if the conversion
370  * wasn't possible.
371  *
372  * \sa SDL_PixelFormatEnumToMasks()
373  */
374 extern DECLSPEC Uint32 SDLCALL SDL_MasksToPixelFormatEnum(int bpp,
375  Uint32 Rmask,
376  Uint32 Gmask,
377  Uint32 Bmask,
378  Uint32 Amask);
379 
380 /**
381  * \brief Create an SDL_PixelFormat structure from a pixel format enum.
382  */
383 extern DECLSPEC SDL_PixelFormat * SDLCALL SDL_AllocFormat(Uint32 pixel_format);
384 
385 /**
386  * \brief Free an SDL_PixelFormat structure.
387  */
388 extern DECLSPEC void SDLCALL SDL_FreeFormat(SDL_PixelFormat *format);
389 
390 /**
391  * \brief Create a palette structure with the specified number of color
392  * entries.
393  *
394  * \return A new palette, or NULL if there wasn't enough memory.
395  *
396  * \note The palette entries are initialized to white.
397  *
398  * \sa SDL_FreePalette()
399  */
400 extern DECLSPEC SDL_Palette *SDLCALL SDL_AllocPalette(int ncolors);
401 
402 /**
403  * \brief Set the palette for a pixel format structure.
404  */
405 extern DECLSPEC int SDLCALL SDL_SetPixelFormatPalette(SDL_PixelFormat * format,
407 
408 /**
409  * \brief Set a range of colors in a palette.
410  *
411  * \param palette The palette to modify.
412  * \param colors An array of colors to copy into the palette.
413  * \param firstcolor The index of the first palette entry to modify.
414  * \param ncolors The number of entries to modify.
415  *
416  * \return 0 on success, or -1 if not all of the colors could be set.
417  */
418 extern DECLSPEC int SDLCALL SDL_SetPaletteColors(SDL_Palette * palette,
419  const SDL_Color * colors,
420  int firstcolor, int ncolors);
421 
422 /**
423  * \brief Free a palette created with SDL_AllocPalette().
424  *
425  * \sa SDL_AllocPalette()
426  */
427 extern DECLSPEC void SDLCALL SDL_FreePalette(SDL_Palette * palette);
428 
429 /**
430  * \brief Maps an RGB triple to an opaque pixel value for a given pixel format.
431  *
432  * \sa SDL_MapRGBA
433  */
434 extern DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormat * format,
435  Uint8 r, Uint8 g, Uint8 b);
436 
437 /**
438  * \brief Maps an RGBA quadruple to a pixel value for a given pixel format.
439  *
440  * \sa SDL_MapRGB
441  */
442 extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormat * format,
443  Uint8 r, Uint8 g, Uint8 b,
444  Uint8 a);
445 
446 /**
447  * \brief Get the RGB components from a pixel of the specified format.
448  *
449  * \sa SDL_GetRGBA
450  */
451 extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel,
452  const SDL_PixelFormat * format,
453  Uint8 * r, Uint8 * g, Uint8 * b);
454 
455 /**
456  * \brief Get the RGBA components from a pixel of the specified format.
457  *
458  * \sa SDL_GetRGB
459  */
460 extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel,
461  const SDL_PixelFormat * format,
462  Uint8 * r, Uint8 * g, Uint8 * b,
463  Uint8 * a);
464 
465 /**
466  * \brief Calculate a 256 entry gamma ramp for a gamma value.
467  */
468 extern DECLSPEC void SDLCALL SDL_CalculateGammaRamp(float gamma, Uint16 * ramp);
469 
470 
471 /* Ends C function definitions when using C++ */
472 #ifdef __cplusplus
473 }
474 #endif
475 #include "close_code.h"
476 
477 #endif /* SDL_pixels_h_ */
478 
479 /* 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.
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.
Uint32 version
Definition: SDL_pixels.h:317
SDL_PixelFormatEnum
Definition: SDL_pixels.h:171
SDL_PixelFormat * SDL_AllocFormat(Uint32 pixel_format)
Create an SDL_PixelFormat structure from a pixel format enum.
Uint8 g
Definition: SDL_pixels.h:307
SDL_bool
Definition: SDL_stdinc.h:167
Uint8 BytesPerPixel
Definition: SDL_pixels.h:329
void SDL_FreeFormat(SDL_PixelFormat *format)
Free an SDL_PixelFormat structure.
SDL_PixelType
Definition: SDL_pixels.h:51
SDL_PackedLayout
Definition: SDL_pixels.h:104
Uint8 b
Definition: SDL_pixels.h:308
uint32_t Uint32
Definition: SDL_stdinc.h:209
void SDL_FreePalette(SDL_Palette *palette)
Free a palette created with SDL_AllocPalette().
#define SDL_DEFINE_PIXELFOURCC(A, B, C, D)
Definition: SDL_pixels.h:117
Uint32 SDL_MasksToPixelFormatEnum(int bpp, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask)
Convert a bpp and RGBA masks to an enumerated pixel format.
uint16_t Uint16
Definition: SDL_stdinc.h:197
Uint8 r
Definition: SDL_pixels.h:306
int SDL_SetPixelFormatPalette(SDL_PixelFormat *format, SDL_Palette *palette)
Set the palette for a pixel format structure.
SDL_ArrayOrder
Definition: SDL_pixels.h:92
Uint8 a
Definition: SDL_pixels.h:309
Uint8 BitsPerPixel
Definition: SDL_pixels.h:328
SDL_Palette * SDL_AllocPalette(int ncolors)
Create a palette structure with the specified number of color entries.
int SDL_SetPaletteColors(SDL_Palette *palette, const SDL_Color *colors, int firstcolor, int ncolors)
Set a range of colors in a palette.
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.
SDL_Color * colors
Definition: SDL_pixels.h:316
SDL_BitmapOrder
Definition: SDL_pixels.h:68
#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.
void SDL_CalculateGammaRamp(float gamma, Uint16 *ramp)
Calculate a 256 entry gamma ramp for a gamma value.
SDL_PackedOrder
Definition: SDL_pixels.h:76
SDL_Palette * palette
Definition: SDL_pixels.h:327
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.
uint8_t Uint8
Definition: SDL_stdinc.h:185
struct SDL_PixelFormat * next
Definition: SDL_pixels.h:344
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.