2 Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
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.
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:
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.
25 * Header for the enumerated pixel format definitions.
31 #include "SDL_stdinc.h"
32 #include "SDL_endian.h"
34 #include "begin_code.h"
35 /* Set up for C function definitions, even when using C++ */
41 * \name Transparency definitions
43 * These define alpha as the opacity of a surface.
46 #define SDL_ALPHA_OPAQUE 255
47 #define SDL_ALPHA_TRANSPARENT 0
53 SDL_PIXELTYPE_UNKNOWN,
57 SDL_PIXELTYPE_PACKED8,
58 SDL_PIXELTYPE_PACKED16,
59 SDL_PIXELTYPE_PACKED32,
60 SDL_PIXELTYPE_ARRAYU8,
61 SDL_PIXELTYPE_ARRAYU16,
62 SDL_PIXELTYPE_ARRAYU32,
63 SDL_PIXELTYPE_ARRAYF16,
64 SDL_PIXELTYPE_ARRAYF32
67 /** Bitmap pixel order, high bit -> low bit. */
75 /** Packed component order, high bit -> low bit. */
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 */
103 /** Packed component layout. */
106 SDL_PACKEDLAYOUT_NONE,
107 SDL_PACKEDLAYOUT_332,
108 SDL_PACKEDLAYOUT_4444,
109 SDL_PACKEDLAYOUT_1555,
110 SDL_PACKEDLAYOUT_5551,
111 SDL_PACKEDLAYOUT_565,
112 SDL_PACKEDLAYOUT_8888,
113 SDL_PACKEDLAYOUT_2101010,
114 SDL_PACKEDLAYOUT_1010102
117 #define SDL_DEFINE_PIXELFOURCC(A, B, C, D) SDL_FOURCC(A, B, C, D)
119 #define SDL_DEFINE_PIXELFORMAT(type, order, layout, bits, bytes) \
120 ((1 << 28) | ((type) << 24) | ((order) << 20) | ((layout) << 16) | \
121 ((bits) << 8) | ((bytes) << 0))
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))
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)))
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)))
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)))
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))))
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))
170 /* Note: If you modify this list, update SDL_GetPixelFormatName() */
173 SDL_PIXELFORMAT_UNKNOWN,
174 SDL_PIXELFORMAT_INDEX1LSB =
175 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX1, SDL_BITMAPORDER_4321, 0,
177 SDL_PIXELFORMAT_INDEX1MSB =
178 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX1, SDL_BITMAPORDER_1234, 0,
180 SDL_PIXELFORMAT_INDEX4LSB =
181 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX4, SDL_BITMAPORDER_4321, 0,
183 SDL_PIXELFORMAT_INDEX4MSB =
184 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX4, SDL_BITMAPORDER_1234, 0,
186 SDL_PIXELFORMAT_INDEX8 =
187 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX8, 0, 0, 8, 1),
188 SDL_PIXELFORMAT_RGB332 =
189 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED8, SDL_PACKEDORDER_XRGB,
190 SDL_PACKEDLAYOUT_332, 8, 1),
191 SDL_PIXELFORMAT_XRGB4444 =
192 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB,
193 SDL_PACKEDLAYOUT_4444, 12, 2),
194 SDL_PIXELFORMAT_RGB444 = SDL_PIXELFORMAT_XRGB4444,
195 SDL_PIXELFORMAT_XBGR4444 =
196 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XBGR,
197 SDL_PACKEDLAYOUT_4444, 12, 2),
198 SDL_PIXELFORMAT_BGR444 = SDL_PIXELFORMAT_XBGR4444,
199 SDL_PIXELFORMAT_XRGB1555 =
200 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB,
201 SDL_PACKEDLAYOUT_1555, 15, 2),
202 SDL_PIXELFORMAT_RGB555 = SDL_PIXELFORMAT_XRGB1555,
203 SDL_PIXELFORMAT_XBGR1555 =
204 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XBGR,
205 SDL_PACKEDLAYOUT_1555, 15, 2),
206 SDL_PIXELFORMAT_BGR555 = SDL_PIXELFORMAT_XBGR1555,
207 SDL_PIXELFORMAT_ARGB4444 =
208 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ARGB,
209 SDL_PACKEDLAYOUT_4444, 16, 2),
210 SDL_PIXELFORMAT_RGBA4444 =
211 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_RGBA,
212 SDL_PACKEDLAYOUT_4444, 16, 2),
213 SDL_PIXELFORMAT_ABGR4444 =
214 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ABGR,
215 SDL_PACKEDLAYOUT_4444, 16, 2),
216 SDL_PIXELFORMAT_BGRA4444 =
217 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_BGRA,
218 SDL_PACKEDLAYOUT_4444, 16, 2),
219 SDL_PIXELFORMAT_ARGB1555 =
220 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ARGB,
221 SDL_PACKEDLAYOUT_1555, 16, 2),
222 SDL_PIXELFORMAT_RGBA5551 =
223 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_RGBA,
224 SDL_PACKEDLAYOUT_5551, 16, 2),
225 SDL_PIXELFORMAT_ABGR1555 =
226 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ABGR,
227 SDL_PACKEDLAYOUT_1555, 16, 2),
228 SDL_PIXELFORMAT_BGRA5551 =
229 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_BGRA,
230 SDL_PACKEDLAYOUT_5551, 16, 2),
231 SDL_PIXELFORMAT_RGB565 =
232 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB,
233 SDL_PACKEDLAYOUT_565, 16, 2),
234 SDL_PIXELFORMAT_BGR565 =
235 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XBGR,
236 SDL_PACKEDLAYOUT_565, 16, 2),
237 SDL_PIXELFORMAT_RGB24 =
238 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU8, SDL_ARRAYORDER_RGB, 0,
240 SDL_PIXELFORMAT_BGR24 =
241 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU8, SDL_ARRAYORDER_BGR, 0,
243 SDL_PIXELFORMAT_XRGB8888 =
244 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XRGB,
245 SDL_PACKEDLAYOUT_8888, 24, 4),
246 SDL_PIXELFORMAT_RGB888 = SDL_PIXELFORMAT_XRGB8888,
247 SDL_PIXELFORMAT_RGBX8888 =
248 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_RGBX,
249 SDL_PACKEDLAYOUT_8888, 24, 4),
250 SDL_PIXELFORMAT_XBGR8888 =
251 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XBGR,
252 SDL_PACKEDLAYOUT_8888, 24, 4),
253 SDL_PIXELFORMAT_BGR888 = SDL_PIXELFORMAT_XBGR8888,
254 SDL_PIXELFORMAT_BGRX8888 =
255 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_BGRX,
256 SDL_PACKEDLAYOUT_8888, 24, 4),
257 SDL_PIXELFORMAT_ARGB8888 =
258 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ARGB,
259 SDL_PACKEDLAYOUT_8888, 32, 4),
260 SDL_PIXELFORMAT_RGBA8888 =
261 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_RGBA,
262 SDL_PACKEDLAYOUT_8888, 32, 4),
263 SDL_PIXELFORMAT_ABGR8888 =
264 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ABGR,
265 SDL_PACKEDLAYOUT_8888, 32, 4),
266 SDL_PIXELFORMAT_BGRA8888 =
267 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_BGRA,
268 SDL_PACKEDLAYOUT_8888, 32, 4),
269 SDL_PIXELFORMAT_ARGB2101010 =
270 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ARGB,
271 SDL_PACKEDLAYOUT_2101010, 32, 4),
273 /* Aliases for RGBA byte arrays of color data, for the current platform */
274 #if SDL_BYTEORDER == SDL_BIG_ENDIAN
275 SDL_PIXELFORMAT_RGBA32 = SDL_PIXELFORMAT_RGBA8888,
276 SDL_PIXELFORMAT_ARGB32 = SDL_PIXELFORMAT_ARGB8888,
277 SDL_PIXELFORMAT_BGRA32 = SDL_PIXELFORMAT_BGRA8888,
278 SDL_PIXELFORMAT_ABGR32 = SDL_PIXELFORMAT_ABGR8888,
280 SDL_PIXELFORMAT_RGBA32 = SDL_PIXELFORMAT_ABGR8888,
281 SDL_PIXELFORMAT_ARGB32 = SDL_PIXELFORMAT_BGRA8888,
282 SDL_PIXELFORMAT_BGRA32 = SDL_PIXELFORMAT_ARGB8888,
283 SDL_PIXELFORMAT_ABGR32 = SDL_PIXELFORMAT_RGBA8888,
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', ' ')
302 } SDL_PixelFormatEnum;
304 typedef struct SDL_Color
311 #define SDL_Colour SDL_Color
313 typedef struct SDL_Palette
322 * \note Everything in the pixel format structure is read-only.
324 typedef struct SDL_PixelFormat
327 SDL_Palette *palette;
344 struct SDL_PixelFormat *next;
348 * \brief Get the human readable name of a pixel format
350 extern DECLSPEC const char* SDLCALL SDL_GetPixelFormatName(Uint32 format);
353 * \brief Convert one of the enumerated pixel formats to a bpp and RGBA masks.
355 * \return SDL_TRUE, or SDL_FALSE if the conversion wasn't possible.
357 * \sa SDL_MasksToPixelFormatEnum()
359 extern DECLSPEC SDL_bool SDLCALL SDL_PixelFormatEnumToMasks(Uint32 format,
367 * \brief Convert a bpp and RGBA masks to an enumerated pixel format.
369 * \return The pixel format, or ::SDL_PIXELFORMAT_UNKNOWN if the conversion
372 * \sa SDL_PixelFormatEnumToMasks()
374 extern DECLSPEC Uint32 SDLCALL SDL_MasksToPixelFormatEnum(int bpp,
381 * \brief Create an SDL_PixelFormat structure from a pixel format enum.
383 extern DECLSPEC SDL_PixelFormat * SDLCALL SDL_AllocFormat(Uint32 pixel_format);
386 * \brief Free an SDL_PixelFormat structure.
388 extern DECLSPEC void SDLCALL SDL_FreeFormat(SDL_PixelFormat *format);
391 * \brief Create a palette structure with the specified number of color
394 * \return A new palette, or NULL if there wasn't enough memory.
396 * \note The palette entries are initialized to white.
398 * \sa SDL_FreePalette()
400 extern DECLSPEC SDL_Palette *SDLCALL SDL_AllocPalette(int ncolors);
403 * \brief Set the palette for a pixel format structure.
405 extern DECLSPEC int SDLCALL SDL_SetPixelFormatPalette(SDL_PixelFormat * format,
406 SDL_Palette *palette);
409 * \brief Set a range of colors in a palette.
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.
416 * \return 0 on success, or -1 if not all of the colors could be set.
418 extern DECLSPEC int SDLCALL SDL_SetPaletteColors(SDL_Palette * palette,
419 const SDL_Color * colors,
420 int firstcolor, int ncolors);
423 * \brief Free a palette created with SDL_AllocPalette().
425 * \sa SDL_AllocPalette()
427 extern DECLSPEC void SDLCALL SDL_FreePalette(SDL_Palette * palette);
430 * \brief Maps an RGB triple to an opaque pixel value for a given pixel format.
434 extern DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormat * format,
435 Uint8 r, Uint8 g, Uint8 b);
438 * \brief Maps an RGBA quadruple to a pixel value for a given pixel format.
442 extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormat * format,
443 Uint8 r, Uint8 g, Uint8 b,
447 * \brief Get the RGB components from a pixel of the specified format.
451 extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel,
452 const SDL_PixelFormat * format,
453 Uint8 * r, Uint8 * g, Uint8 * b);
456 * \brief Get the RGBA components from a pixel of the specified format.
460 extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel,
461 const SDL_PixelFormat * format,
462 Uint8 * r, Uint8 * g, Uint8 * b,
466 * \brief Calculate a 256 entry gamma ramp for a gamma value.
468 extern DECLSPEC void SDLCALL SDL_CalculateGammaRamp(float gamma, Uint16 * ramp);
471 /* Ends C function definitions when using C++ */
475 #include "close_code.h"
477 #endif /* SDL_pixels_h_ */
479 /* vi: set ts=4 sw=4 expandtab: */