SDL  2.0
SDL_pixels.h
Go to the documentation of this file.
1 /*
2  Simple DirectMedia Layer
3  Copyright (C) 1997-2021 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  * Get the human readable name of a pixel format.
349  *
350  * \param format the pixel format to query
351  * \returns the human readable name of the specified pixel format or
352  * `SDL_PIXELFORMAT_UNKNOWN` if the format isn't recognized.
353  *
354  * \since This function is available since SDL 2.0.0.
355  */
356 extern DECLSPEC const char* SDLCALL SDL_GetPixelFormatName(Uint32 format);
357 
358 /**
359  * Convert one of the enumerated pixel formats to a bpp value and RGBA masks.
360  *
361  * \param format one of the SDL_PixelFormatEnum values
362  * \param bpp a bits per pixel value; usually 15, 16, or 32
363  * \param Rmask a pointer filled in with the red mask for the format
364  * \param Gmask a pointer filled in with the green mask for the format
365  * \param Bmask a pointer filled in with the blue mask for the format
366  * \param Amask a pointer filled in with the alpha mask for the format
367  * \returns SDL_TRUE on success or SDL_FALSE if the conversion wasn't
368  * possible; call SDL_GetError() for more information.
369  *
370  * \sa SDL_MasksToPixelFormatEnum
371  */
372 extern DECLSPEC SDL_bool SDLCALL SDL_PixelFormatEnumToMasks(Uint32 format,
373  int *bpp,
374  Uint32 * Rmask,
375  Uint32 * Gmask,
376  Uint32 * Bmask,
377  Uint32 * Amask);
378 
379 /**
380  * Convert a bpp value and RGBA masks to an enumerated pixel format.
381  *
382  * This will return `SDL_PIXELFORMAT_UNKNOWN` if the conversion wasn't
383  * possible.
384  *
385  * \param bpp a bits per pixel value; usually 15, 16, or 32
386  * \param Rmask the red mask for the format
387  * \param Gmask the green mask for the format
388  * \param Bmask the blue mask for the format
389  * \param Amask the alpha mask for the format
390  * \returns one of the SDL_PixelFormatEnum values
391  *
392  * \sa SDL_PixelFormatEnumToMasks
393  */
394 extern DECLSPEC Uint32 SDLCALL SDL_MasksToPixelFormatEnum(int bpp,
395  Uint32 Rmask,
396  Uint32 Gmask,
397  Uint32 Bmask,
398  Uint32 Amask);
399 
400 /**
401  * Create an SDL_PixelFormat structure corresponding to a pixel format.
402  *
403  * Returned structure may come from a shared global cache (i.e. not newly
404  * allocated), and hence should not be modified, especially the palette. Weird
405  * errors such as `Blit combination not supported` may occur.
406  *
407  * \param pixel_format one of the SDL_PixelFormatEnum values
408  * \returns the new SDL_PixelFormat structure or NULL on failure; call
409  * SDL_GetError() for more information.
410  *
411  * \sa SDL_FreeFormat
412  */
413 extern DECLSPEC SDL_PixelFormat * SDLCALL SDL_AllocFormat(Uint32 pixel_format);
414 
415 /**
416  * Free an SDL_PixelFormat structure allocated by SDL_AllocFormat().
417  *
418  * \param format the SDL_PixelFormat structure to free
419  *
420  * \sa SDL_AllocFormat
421  */
422 extern DECLSPEC void SDLCALL SDL_FreeFormat(SDL_PixelFormat *format);
423 
424 /**
425  * Create a palette structure with the specified number of color entries.
426  *
427  * The palette entries are initialized to white.
428  *
429  * \param ncolors represents the number of color entries in the color palette
430  * \returns a new SDL_Palette structure on success or NULL on failure (e.g. if
431  * there wasn't enough memory); call SDL_GetError() for more
432  * information.
433  *
434  * \sa SDL_FreePalette
435  */
436 extern DECLSPEC SDL_Palette *SDLCALL SDL_AllocPalette(int ncolors);
437 
438 /**
439  * Set the palette for a pixel format structure.
440  *
441  * \param format the SDL_PixelFormat structure that will use the palette
442  * \param palette the SDL_Palette structure that will be used
443  * \returns 0 on success or a negative error code on failure; call
444  * SDL_GetError() for more information.
445  *
446  * \sa SDL_AllocPalette
447  * \sa SDL_FreePalette
448  */
449 extern DECLSPEC int SDLCALL SDL_SetPixelFormatPalette(SDL_PixelFormat * format,
451 
452 /**
453  * Set a range of colors in a palette.
454  *
455  * \param palette the SDL_Palette structure to modify
456  * \param colors an array of SDL_Color structures to copy into the palette
457  * \param firstcolor the index of the first palette entry to modify
458  * \param ncolors the number of entries to modify
459  * \returns 0 on success or a negative error code if not all of the colors
460  * could be set; call SDL_GetError() for more information.
461  *
462  * \sa SDL_AllocPalette
463  * \sa SDL_CreateRGBSurface
464  */
465 extern DECLSPEC int SDLCALL SDL_SetPaletteColors(SDL_Palette * palette,
466  const SDL_Color * colors,
467  int firstcolor, int ncolors);
468 
469 /**
470  * Free a palette created with SDL_AllocPalette().
471  *
472  * \param palette the SDL_Palette structure to be freed
473  *
474  * \sa SDL_AllocPalette
475  */
476 extern DECLSPEC void SDLCALL SDL_FreePalette(SDL_Palette * palette);
477 
478 /**
479  * Map an RGB triple to an opaque pixel value for a given pixel format.
480  *
481  * This function maps the RGB color value to the specified pixel format and
482  * returns the pixel value best approximating the given RGB color value for
483  * the given pixel format.
484  *
485  * If the format has a palette (8-bit) the index of the closest matching color
486  * in the palette will be returned.
487  *
488  * If the specified pixel format has an alpha component it will be returned as
489  * all 1 bits (fully opaque).
490  *
491  * If the pixel format bpp (color depth) is less than 32-bpp then the unused
492  * upper bits of the return value can safely be ignored (e.g., with a 16-bpp
493  * format the return value can be assigned to a Uint16, and similarly a Uint8
494  * for an 8-bpp format).
495  *
496  * \param format an SDL_PixelFormat structure describing the pixel format
497  * \param r the red component of the pixel in the range 0-255
498  * \param g the green component of the pixel in the range 0-255
499  * \param b the blue component of the pixel in the range 0-255
500  * \returns a pixel value
501  *
502  * \sa SDL_GetRGB
503  * \sa SDL_GetRGBA
504  * \sa SDL_MapRGBA
505  */
506 extern DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormat * format,
507  Uint8 r, Uint8 g, Uint8 b);
508 
509 /**
510  * Map an RGBA quadruple to a pixel value for a given pixel format.
511  *
512  * This function maps the RGBA color value to the specified pixel format and
513  * returns the pixel value best approximating the given RGBA color value for
514  * the given pixel format.
515  *
516  * If the specified pixel format has no alpha component the alpha value will
517  * be ignored (as it will be in formats with a palette).
518  *
519  * If the format has a palette (8-bit) the index of the closest matching color
520  * in the palette will be returned.
521  *
522  * If the pixel format bpp (color depth) is less than 32-bpp then the unused
523  * upper bits of the return value can safely be ignored (e.g., with a 16-bpp
524  * format the return value can be assigned to a Uint16, and similarly a Uint8
525  * for an 8-bpp format).
526  *
527  * \param format an SDL_PixelFormat structure describing the format of the
528  * pixel
529  * \param r the red component of the pixel in the range 0-255
530  * \param g the green component of the pixel in the range 0-255
531  * \param b the blue component of the pixel in the range 0-255
532  * \param a the alpha component of the pixel in the range 0-255
533  * \returns a pixel value
534  *
535  * \sa SDL_GetRGB
536  * \sa SDL_GetRGBA
537  * \sa SDL_MapRGB
538  */
539 extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormat * format,
540  Uint8 r, Uint8 g, Uint8 b,
541  Uint8 a);
542 
543 /**
544  * Get RGB values from a pixel in the specified format.
545  *
546  * This function uses the entire 8-bit [0..255] range when converting color
547  * components from pixel formats with less than 8-bits per RGB component
548  * (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff,
549  * 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).
550  *
551  * \param pixel a pixel value
552  * \param format an SDL_PixelFormat structure describing the format of the
553  * pixel
554  * \param r a pointer filled in with the red component
555  * \param g a pointer filled in with the green component
556  * \param b a pointer filled in with the blue component
557  *
558  * \sa SDL_GetRGBA
559  * \sa SDL_MapRGB
560  * \sa SDL_MapRGBA
561  */
562 extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel,
563  const SDL_PixelFormat * format,
564  Uint8 * r, Uint8 * g, Uint8 * b);
565 
566 /**
567  * Get RGBA values from a pixel in the specified format.
568  *
569  * This function uses the entire 8-bit [0..255] range when converting color
570  * components from pixel formats with less than 8-bits per RGB component
571  * (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff,
572  * 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).
573  *
574  * If the surface has no alpha component, the alpha will be returned as 0xff
575  * (100% opaque).
576  *
577  * \param pixel a pixel value
578  * \param format an SDL_PixelFormat structure describing the format of the
579  * pixel
580  * \param r a pointer filled in with the red component
581  * \param g a pointer filled in with the green component
582  * \param b a pointer filled in with the blue component
583  * \param a a pointer filled in with the alpha component
584  *
585  * \sa SDL_GetRGB
586  * \sa SDL_MapRGB
587  * \sa SDL_MapRGBA
588  */
589 extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel,
590  const SDL_PixelFormat * format,
591  Uint8 * r, Uint8 * g, Uint8 * b,
592  Uint8 * a);
593 
594 /**
595  * Calculate a 256 entry gamma ramp for a gamma value.
596  *
597  * \param gamma a gamma value where 0.0 is black and 1.0 is identity
598  * \param ramp an array of 256 values filled in with the gamma ramp
599  *
600  * \sa SDL_SetWindowGammaRamp
601  */
602 extern DECLSPEC void SDLCALL SDL_CalculateGammaRamp(float gamma, Uint16 * ramp);
603 
604 
605 /* Ends C function definitions when using C++ */
606 #ifdef __cplusplus
607 }
608 #endif
609 #include "close_code.h"
610 
611 #endif /* SDL_pixels_h_ */
612 
613 /* vi: set ts=4 sw=4 expandtab: */
Uint32 SDL_MapRGBA(const SDL_PixelFormat *format, Uint8 r, Uint8 g, Uint8 b, Uint8 a)
void SDL_GetRGBA(Uint32 pixel, const SDL_PixelFormat *format, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a)
Uint32 version
Definition: SDL_pixels.h:317
SDL_PixelFormatEnum
Definition: SDL_pixels.h:171
SDL_PixelFormat * SDL_AllocFormat(Uint32 pixel_format)
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)
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)
#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)
uint16_t Uint16
Definition: SDL_stdinc.h:197
Uint8 r
Definition: SDL_pixels.h:306
int SDL_SetPixelFormatPalette(SDL_PixelFormat *format, SDL_Palette *palette)
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)
int SDL_SetPaletteColors(SDL_Palette *palette, const SDL_Color *colors, int firstcolor, int ncolors)
Uint32 SDL_MapRGB(const SDL_PixelFormat *format, Uint8 r, Uint8 g, Uint8 b)
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)
void SDL_CalculateGammaRamp(float gamma, Uint16 *ramp)
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)
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)