SDL 3.0
SDL_pixels.h
Go to the documentation of this file.
1/*
2 Simple DirectMedia Layer
3 Copyright (C) 1997-2024 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 * # CategoryPixels
24 *
25 * Pixel management.
26 */
27
28#ifndef SDL_pixels_h_
29#define SDL_pixels_h_
30
31#include <SDL3/SDL_stdinc.h>
32#include <SDL3/SDL_error.h>
33#include <SDL3/SDL_endian.h>
34
35#include <SDL3/SDL_begin_code.h>
36/* Set up for C function definitions, even when using C++ */
37#ifdef __cplusplus
38extern "C" {
39#endif
40
41/**
42 * A fully opaque 8-bit alpha value.
43 *
44 * \since This macro is available since SDL 3.0.0.
45 *
46 * \sa SDL_ALPHA_TRANSPARENT
47 */
48#define SDL_ALPHA_OPAQUE 255
49
50/**
51 * A fully opaque floating point alpha value.
52 *
53 * \since This macro is available since SDL 3.0.0.
54 *
55 * \sa SDL_ALPHA_TRANSPARENT_FLOAT
56 */
57#define SDL_ALPHA_OPAQUE_FLOAT 1.0f
58
59/**
60 * A fully transparent 8-bit alpha value.
61 *
62 * \since This macro is available since SDL 3.0.0.
63 *
64 * \sa SDL_ALPHA_OPAQUE
65 */
66#define SDL_ALPHA_TRANSPARENT 0
67
68/**
69 * A fully transparent floating point alpha value.
70 *
71 * \since This macro is available since SDL 3.0.0.
72 *
73 * \sa SDL_ALPHA_OPAQUE_FLOAT
74 */
75#define SDL_ALPHA_TRANSPARENT_FLOAT 0.0f
76
77/** Pixel type. */
95
96/** Bitmap pixel order, high bit -> low bit. */
103
104/** Packed component order, high bit -> low bit. */
117
118/** Array component order, low byte -> high byte. */
129
130/** Packed component layout. */
143
144#define SDL_DEFINE_PIXELFOURCC(A, B, C, D) SDL_FOURCC(A, B, C, D)
145
146#define SDL_DEFINE_PIXELFORMAT(type, order, layout, bits, bytes) \
147 ((1 << 28) | ((type) << 24) | ((order) << 20) | ((layout) << 16) | \
148 ((bits) << 8) | ((bytes) << 0))
149
150#define SDL_PIXELFLAG(X) (((X) >> 28) & 0x0F)
151#define SDL_PIXELTYPE(X) (((X) >> 24) & 0x0F)
152#define SDL_PIXELORDER(X) (((X) >> 20) & 0x0F)
153#define SDL_PIXELLAYOUT(X) (((X) >> 16) & 0x0F)
154#define SDL_BITSPERPIXEL(X) \
155 (SDL_ISPIXELFORMAT_FOURCC(X) ? 0 : (((X) >> 8) & 0xFF))
156#define SDL_BYTESPERPIXEL(X) \
157 (SDL_ISPIXELFORMAT_FOURCC(X) ? \
158 ((((X) == SDL_PIXELFORMAT_YUY2) || \
159 ((X) == SDL_PIXELFORMAT_UYVY) || \
160 ((X) == SDL_PIXELFORMAT_YVYU) || \
161 ((X) == SDL_PIXELFORMAT_P010)) ? 2 : 1) : (((X) >> 0) & 0xFF))
162
163#define SDL_ISPIXELFORMAT_INDEXED(format) \
164 (!SDL_ISPIXELFORMAT_FOURCC(format) && \
165 ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX1) || \
166 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX2) || \
167 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX4) || \
168 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX8)))
169
170#define SDL_ISPIXELFORMAT_PACKED(format) \
171 (!SDL_ISPIXELFORMAT_FOURCC(format) && \
172 ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED8) || \
173 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED16) || \
174 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED32)))
175
176#define SDL_ISPIXELFORMAT_ARRAY(format) \
177 (!SDL_ISPIXELFORMAT_FOURCC(format) && \
178 ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYU8) || \
179 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYU16) || \
180 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYU32) || \
181 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF16) || \
182 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF32)))
183
184#define SDL_ISPIXELFORMAT_ALPHA(format) \
185 ((SDL_ISPIXELFORMAT_PACKED(format) && \
186 ((SDL_PIXELORDER(format) == SDL_PACKEDORDER_ARGB) || \
187 (SDL_PIXELORDER(format) == SDL_PACKEDORDER_RGBA) || \
188 (SDL_PIXELORDER(format) == SDL_PACKEDORDER_ABGR) || \
189 (SDL_PIXELORDER(format) == SDL_PACKEDORDER_BGRA))))
190
191#define SDL_ISPIXELFORMAT_10BIT(format) \
192 (!SDL_ISPIXELFORMAT_FOURCC(format) && \
193 ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED32) && \
194 (SDL_PIXELLAYOUT(format) == SDL_PACKEDLAYOUT_2101010)))
195
196#define SDL_ISPIXELFORMAT_FLOAT(format) \
197 (!SDL_ISPIXELFORMAT_FOURCC(format) && \
198 ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF16) || \
199 (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF32)))
200
201/* The flag is set to 1 because 0x1? is not in the printable ASCII range */
202#define SDL_ISPIXELFORMAT_FOURCC(format) \
203 ((format) && (SDL_PIXELFLAG(format) != 1))
204
205/* Note: If you modify this enum, update SDL_GetPixelFormatName() */
206
207/**
208 * Pixel format.
209 *
210 * SDL's pixel formats have the following naming convention:
211 *
212 * - Names with a list of components and a single bit count, such as RGB24 and
213 * ABGR32, define a platform-independent encoding into bytes in the order
214 * specified. For example, in RGB24 data, each pixel is encoded in 3 bytes
215 * (red, green, blue) in that order, and in ABGR32 data, each pixel is
216 * encoded in 4 bytes alpha, blue, green, red) in that order. Use these
217 * names if the property of a format that is important to you is the order
218 * of the bytes in memory or on disk.
219 * - Names with a bit count per component, such as ARGB8888 and XRGB1555, are
220 * "packed" into an appropriately-sized integer in the platform's native
221 * endianness. For example, ARGB8888 is a sequence of 32-bit integers; in
222 * each integer, the most significant bits are alpha, and the least
223 * significant bits are blue. On a little-endian CPU such as x86, the least
224 * significant bits of each integer are arranged first in memory, but on a
225 * big-endian CPU such as s390x, the most significant bits are arranged
226 * first. Use these names if the property of a format that is important to
227 * you is the meaning of each bit position within a native-endianness
228 * integer.
229 * - In indexed formats such as INDEX4LSB, each pixel is represented by
230 * encoding an index into the palette into the indicated number of bits,
231 * with multiple pixels packed into each byte if appropriate. In LSB
232 * formats, the first (leftmost) pixel is stored in the least-significant
233 * bits of the byte; in MSB formats, it's stored in the most-significant
234 * bits. INDEX8 does not need LSB/MSB variants, because each pixel exactly
235 * fills one byte.
236 *
237 * The 32-bit byte-array encodings such as RGBA32 are aliases for the
238 * appropriate 8888 encoding for the current platform. For example, RGBA32 is
239 * an alias for ABGR8888 on little-endian CPUs like x86, or an alias for
240 * RGBA8888 on big-endian CPUs.
241 *
242 * \since This enum is available since SDL 3.0.0.
243 */
244typedef enum SDL_PixelFormat
245{
248 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX1, SDL_BITMAPORDER_4321, 0, 1, 0), */
250 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX1, SDL_BITMAPORDER_1234, 0, 1, 0), */
252 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX2, SDL_BITMAPORDER_4321, 0, 2, 0), */
254 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX2, SDL_BITMAPORDER_1234, 0, 2, 0), */
256 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX4, SDL_BITMAPORDER_4321, 0, 4, 0), */
258 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX4, SDL_BITMAPORDER_1234, 0, 4, 0), */
260 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX8, 0, 0, 8, 1), */
262 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED8, SDL_PACKEDORDER_XRGB, SDL_PACKEDLAYOUT_332, 8, 1), */
264 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB, SDL_PACKEDLAYOUT_4444, 12, 2), */
266 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XBGR, SDL_PACKEDLAYOUT_4444, 12, 2), */
268 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB, SDL_PACKEDLAYOUT_1555, 15, 2), */
270 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XBGR, SDL_PACKEDLAYOUT_1555, 15, 2), */
272 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ARGB, SDL_PACKEDLAYOUT_4444, 16, 2), */
274 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_RGBA, SDL_PACKEDLAYOUT_4444, 16, 2), */
276 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ABGR, SDL_PACKEDLAYOUT_4444, 16, 2), */
278 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_BGRA, SDL_PACKEDLAYOUT_4444, 16, 2), */
280 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ARGB, SDL_PACKEDLAYOUT_1555, 16, 2), */
282 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_RGBA, SDL_PACKEDLAYOUT_5551, 16, 2), */
284 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ABGR, SDL_PACKEDLAYOUT_1555, 16, 2), */
286 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_BGRA, SDL_PACKEDLAYOUT_5551, 16, 2), */
288 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB, SDL_PACKEDLAYOUT_565, 16, 2), */
290 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XBGR, SDL_PACKEDLAYOUT_565, 16, 2), */
292 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU8, SDL_ARRAYORDER_RGB, 0, 24, 3), */
294 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU8, SDL_ARRAYORDER_BGR, 0, 24, 3), */
296 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XRGB, SDL_PACKEDLAYOUT_8888, 24, 4), */
298 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_RGBX, SDL_PACKEDLAYOUT_8888, 24, 4), */
300 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XBGR, SDL_PACKEDLAYOUT_8888, 24, 4), */
302 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_BGRX, SDL_PACKEDLAYOUT_8888, 24, 4), */
304 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ARGB, SDL_PACKEDLAYOUT_8888, 32, 4), */
306 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_RGBA, SDL_PACKEDLAYOUT_8888, 32, 4), */
308 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ABGR, SDL_PACKEDLAYOUT_8888, 32, 4), */
310 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_BGRA, SDL_PACKEDLAYOUT_8888, 32, 4), */
312 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XRGB, SDL_PACKEDLAYOUT_2101010, 32, 4), */
314 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XBGR, SDL_PACKEDLAYOUT_2101010, 32, 4), */
316 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ARGB, SDL_PACKEDLAYOUT_2101010, 32, 4), */
318 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ABGR, SDL_PACKEDLAYOUT_2101010, 32, 4), */
320 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU16, SDL_ARRAYORDER_RGB, 0, 48, 6), */
322 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU16, SDL_ARRAYORDER_BGR, 0, 48, 6), */
324 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU16, SDL_ARRAYORDER_RGBA, 0, 64, 8), */
326 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU16, SDL_ARRAYORDER_ARGB, 0, 64, 8), */
328 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU16, SDL_ARRAYORDER_BGRA, 0, 64, 8), */
330 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU16, SDL_ARRAYORDER_ABGR, 0, 64, 8), */
332 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF16, SDL_ARRAYORDER_RGB, 0, 48, 6), */
334 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF16, SDL_ARRAYORDER_BGR, 0, 48, 6), */
336 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF16, SDL_ARRAYORDER_RGBA, 0, 64, 8), */
338 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF16, SDL_ARRAYORDER_ARGB, 0, 64, 8), */
340 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF16, SDL_ARRAYORDER_BGRA, 0, 64, 8), */
342 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF16, SDL_ARRAYORDER_ABGR, 0, 64, 8), */
344 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF32, SDL_ARRAYORDER_RGB, 0, 96, 12), */
346 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF32, SDL_ARRAYORDER_BGR, 0, 96, 12), */
348 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF32, SDL_ARRAYORDER_RGBA, 0, 128, 16), */
350 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF32, SDL_ARRAYORDER_ARGB, 0, 128, 16), */
352 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF32, SDL_ARRAYORDER_BGRA, 0, 128, 16), */
354 /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF32, SDL_ARRAYORDER_ABGR, 0, 128, 16), */
355
356 SDL_PIXELFORMAT_YV12 = 0x32315659u, /**< Planar mode: Y + V + U (3 planes) */
357 /* SDL_DEFINE_PIXELFOURCC('Y', 'V', '1', '2'), */
358 SDL_PIXELFORMAT_IYUV = 0x56555949u, /**< Planar mode: Y + U + V (3 planes) */
359 /* SDL_DEFINE_PIXELFOURCC('I', 'Y', 'U', 'V'), */
360 SDL_PIXELFORMAT_YUY2 = 0x32595559u, /**< Packed mode: Y0+U0+Y1+V0 (1 plane) */
361 /* SDL_DEFINE_PIXELFOURCC('Y', 'U', 'Y', '2'), */
362 SDL_PIXELFORMAT_UYVY = 0x59565955u, /**< Packed mode: U0+Y0+V0+Y1 (1 plane) */
363 /* SDL_DEFINE_PIXELFOURCC('U', 'Y', 'V', 'Y'), */
364 SDL_PIXELFORMAT_YVYU = 0x55595659u, /**< Packed mode: Y0+V0+Y1+U0 (1 plane) */
365 /* SDL_DEFINE_PIXELFOURCC('Y', 'V', 'Y', 'U'), */
366 SDL_PIXELFORMAT_NV12 = 0x3231564eu, /**< Planar mode: Y + U/V interleaved (2 planes) */
367 /* SDL_DEFINE_PIXELFOURCC('N', 'V', '1', '2'), */
368 SDL_PIXELFORMAT_NV21 = 0x3132564eu, /**< Planar mode: Y + V/U interleaved (2 planes) */
369 /* SDL_DEFINE_PIXELFOURCC('N', 'V', '2', '1'), */
370 SDL_PIXELFORMAT_P010 = 0x30313050u, /**< Planar mode: Y + U/V interleaved (2 planes) */
371 /* SDL_DEFINE_PIXELFOURCC('P', '0', '1', '0'), */
372 SDL_PIXELFORMAT_EXTERNAL_OES = 0x2053454fu /**< Android video texture format */
373 /* SDL_DEFINE_PIXELFOURCC('O', 'E', 'S', ' ') */
375
376/* Aliases for RGBA byte arrays of color data, for the current platform */
377#if SDL_BYTEORDER == SDL_BIG_ENDIAN
378#define SDL_PIXELFORMAT_RGBA32 SDL_PIXELFORMAT_RGBA8888
379#define SDL_PIXELFORMAT_ARGB32 SDL_PIXELFORMAT_ARGB8888
380#define SDL_PIXELFORMAT_BGRA32 SDL_PIXELFORMAT_BGRA8888
381#define SDL_PIXELFORMAT_ABGR32 SDL_PIXELFORMAT_ABGR8888
382#define SDL_PIXELFORMAT_RGBX32 SDL_PIXELFORMAT_RGBX8888
383#define SDL_PIXELFORMAT_XRGB32 SDL_PIXELFORMAT_XRGB8888
384#define SDL_PIXELFORMAT_BGRX32 SDL_PIXELFORMAT_BGRX8888
385#define SDL_PIXELFORMAT_XBGR32 SDL_PIXELFORMAT_XBGR8888
386#else
387#define SDL_PIXELFORMAT_RGBA32 SDL_PIXELFORMAT_ABGR8888
388#define SDL_PIXELFORMAT_ARGB32 SDL_PIXELFORMAT_BGRA8888
389#define SDL_PIXELFORMAT_BGRA32 SDL_PIXELFORMAT_ARGB8888
390#define SDL_PIXELFORMAT_ABGR32 SDL_PIXELFORMAT_RGBA8888
391#define SDL_PIXELFORMAT_RGBX32 SDL_PIXELFORMAT_XBGR8888
392#define SDL_PIXELFORMAT_XRGB32 SDL_PIXELFORMAT_BGRX8888
393#define SDL_PIXELFORMAT_BGRX32 SDL_PIXELFORMAT_XRGB8888
394#define SDL_PIXELFORMAT_XBGR32 SDL_PIXELFORMAT_RGBX8888
395#endif
396
397/**
398 * Pixels are a representation of a color in a particular color space.
399 *
400 * The first characteristic of a color space is the color type. SDL understands two different color types, RGB and YCbCr, or in SDL also referred to as YUV.
401 *
402 * RGB colors consist of red, green, and blue channels of color that are added together to represent the colors we see on the screen.
403 * https://en.wikipedia.org/wiki/RGB_color_model
404 *
405 * YCbCr colors represent colors as a Y luma brightness component and red and blue chroma color offsets. This color representation takes advantage of the fact that the human eye is more sensitive to brightness than the color in an image. The Cb and Cr components are often compressed and have lower resolution than the luma component.
406 * https://en.wikipedia.org/wiki/YCbCr
407 *
408 * When the color information in YCbCr is compressed, the Y pixels are left at full resolution and each Cr and Cb pixel represents an average of the color information in a block of Y pixels. The chroma location determines where in that block of pixels the color information is coming from.
409 *
410 * The color range defines how much of the pixel to use when converting a pixel into a color on the display. When the full color range is used, the entire numeric range of the pixel bits is significant. When narrow color range is used, for historical reasons, the pixel uses only a portion of the numeric range to represent colors.
411 *
412 * The color primaries and white point are a definition of the colors in the color space relative to the standard XYZ color space.
413 * https://en.wikipedia.org/wiki/CIE_1931_color_space
414 *
415 * The transfer characteristic, or opto-electrical transfer function (OETF), is the way a color is converted from mathematically linear space into a non-linear output signals.
416 * https://en.wikipedia.org/wiki/Rec._709#Transfer_characteristics
417 *
418 * The matrix coefficients are used to convert between YCbCr and RGB colors.
419 */
420
421/**
422 * Colorspace color type.
423 *
424 * \since This enum is available since SDL 3.0.0.
425 */
432
433/**
434 * Colorspace color range, as described by
435 * https://www.itu.int/rec/R-REC-BT.2100-2-201807-I/en
436 *
437 * \since This enum is available since SDL 3.0.0.
438 */
439typedef enum SDL_ColorRange
440{
442 SDL_COLOR_RANGE_LIMITED = 1, /**< Narrow range, e.g. 16-235 for 8-bit RGB and luma, and 16-240 for 8-bit chroma */
443 SDL_COLOR_RANGE_FULL = 2 /**< Full range, e.g. 0-255 for 8-bit RGB and luma, and 1-255 for 8-bit chroma */
445
446/**
447 * Colorspace color primaries, as described by
448 * https://www.itu.int/rec/T-REC-H.273-201612-S/en
449 *
450 * \since This enum is available since SDL 3.0.0.
451 */
453{
455 SDL_COLOR_PRIMARIES_BT709 = 1, /**< ITU-R BT.709-6 */
457 SDL_COLOR_PRIMARIES_BT470M = 4, /**< ITU-R BT.470-6 System M */
458 SDL_COLOR_PRIMARIES_BT470BG = 5, /**< ITU-R BT.470-6 System B, G / ITU-R BT.601-7 625 */
459 SDL_COLOR_PRIMARIES_BT601 = 6, /**< ITU-R BT.601-7 525, SMPTE 170M */
460 SDL_COLOR_PRIMARIES_SMPTE240 = 7, /**< SMPTE 240M, functionally the same as SDL_COLOR_PRIMARIES_BT601 */
461 SDL_COLOR_PRIMARIES_GENERIC_FILM = 8, /**< Generic film (color filters using Illuminant C) */
462 SDL_COLOR_PRIMARIES_BT2020 = 9, /**< ITU-R BT.2020-2 / ITU-R BT.2100-0 */
463 SDL_COLOR_PRIMARIES_XYZ = 10, /**< SMPTE ST 428-1 */
464 SDL_COLOR_PRIMARIES_SMPTE431 = 11, /**< SMPTE RP 431-2 */
465 SDL_COLOR_PRIMARIES_SMPTE432 = 12, /**< SMPTE EG 432-1 / DCI P3 */
466 SDL_COLOR_PRIMARIES_EBU3213 = 22, /**< EBU Tech. 3213-E */
469
470/**
471 * Colorspace transfer characteristics.
472 *
473 * These are as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en
474 *
475 * \since This enum is available since SDL 3.0.0.
476 */
478{
480 SDL_TRANSFER_CHARACTERISTICS_BT709 = 1, /**< Rec. ITU-R BT.709-6 / ITU-R BT1361 */
482 SDL_TRANSFER_CHARACTERISTICS_GAMMA22 = 4, /**< ITU-R BT.470-6 System M / ITU-R BT1700 625 PAL & SECAM */
483 SDL_TRANSFER_CHARACTERISTICS_GAMMA28 = 5, /**< ITU-R BT.470-6 System B, G */
484 SDL_TRANSFER_CHARACTERISTICS_BT601 = 6, /**< SMPTE ST 170M / ITU-R BT.601-7 525 or 625 */
485 SDL_TRANSFER_CHARACTERISTICS_SMPTE240 = 7, /**< SMPTE ST 240M */
489 SDL_TRANSFER_CHARACTERISTICS_IEC61966 = 11, /**< IEC 61966-2-4 */
490 SDL_TRANSFER_CHARACTERISTICS_BT1361 = 12, /**< ITU-R BT1361 Extended Colour Gamut */
491 SDL_TRANSFER_CHARACTERISTICS_SRGB = 13, /**< IEC 61966-2-1 (sRGB or sYCC) */
492 SDL_TRANSFER_CHARACTERISTICS_BT2020_10BIT = 14, /**< ITU-R BT2020 for 10-bit system */
493 SDL_TRANSFER_CHARACTERISTICS_BT2020_12BIT = 15, /**< ITU-R BT2020 for 12-bit system */
494 SDL_TRANSFER_CHARACTERISTICS_PQ = 16, /**< SMPTE ST 2084 for 10-, 12-, 14- and 16-bit systems */
495 SDL_TRANSFER_CHARACTERISTICS_SMPTE428 = 17, /**< SMPTE ST 428-1 */
496 SDL_TRANSFER_CHARACTERISTICS_HLG = 18, /**< ARIB STD-B67, known as "hybrid log-gamma" (HLG) */
499
500/**
501 * Colorspace matrix coefficients.
502 *
503 * These are as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en
504 *
505 * \since This enum is available since SDL 3.0.0.
506 */
508{
510 SDL_MATRIX_COEFFICIENTS_BT709 = 1, /**< ITU-R BT.709-6 */
512 SDL_MATRIX_COEFFICIENTS_FCC = 4, /**< US FCC Title 47 */
513 SDL_MATRIX_COEFFICIENTS_BT470BG = 5, /**< ITU-R BT.470-6 System B, G / ITU-R BT.601-7 625, functionally the same as SDL_MATRIX_COEFFICIENTS_BT601 */
514 SDL_MATRIX_COEFFICIENTS_BT601 = 6, /**< ITU-R BT.601-7 525 */
515 SDL_MATRIX_COEFFICIENTS_SMPTE240 = 7, /**< SMPTE 240M */
517 SDL_MATRIX_COEFFICIENTS_BT2020_NCL = 9, /**< ITU-R BT.2020-2 non-constant luminance */
518 SDL_MATRIX_COEFFICIENTS_BT2020_CL = 10, /**< ITU-R BT.2020-2 constant luminance */
519 SDL_MATRIX_COEFFICIENTS_SMPTE2085 = 11, /**< SMPTE ST 2085 */
522 SDL_MATRIX_COEFFICIENTS_ICTCP = 14, /**< ITU-R BT.2100-0 ICTCP */
525
526/**
527 * Colorspace chroma sample location.
528 *
529 * \since This enum is available since SDL 3.0.0.
530 */
532{
533 SDL_CHROMA_LOCATION_NONE = 0, /**< RGB, no chroma sampling */
534 SDL_CHROMA_LOCATION_LEFT = 1, /**< In MPEG-2, MPEG-4, and AVC, Cb and Cr are taken on midpoint of the left-edge of the 2x2 square. In other words, they have the same horizontal location as the top-left pixel, but is shifted one-half pixel down vertically. */
535 SDL_CHROMA_LOCATION_CENTER = 2, /**< In JPEG/JFIF, H.261, and MPEG-1, Cb and Cr are taken at the center of the 2x2 square. In other words, they are offset one-half pixel to the right and one-half pixel down compared to the top-left pixel. */
536 SDL_CHROMA_LOCATION_TOPLEFT = 3 /**< In HEVC for BT.2020 and BT.2100 content (in particular on Blu-rays), Cb and Cr are sampled at the same location as the group's top-left Y pixel ("co-sited", "co-located"). */
538
539
540/* Colorspace definition */
541#define SDL_DEFINE_COLORSPACE(type, range, primaries, transfer, matrix, chroma) \
542 (((Uint32)(type) << 28) | ((Uint32)(range) << 24) | ((Uint32)(chroma) << 20) | \
543 ((Uint32)(primaries) << 10) | ((Uint32)(transfer) << 5) | ((Uint32)(matrix) << 0))
544
545#define SDL_COLORSPACETYPE(X) (SDL_ColorType)(((X) >> 28) & 0x0F)
546#define SDL_COLORSPACERANGE(X) (SDL_ColorRange)(((X) >> 24) & 0x0F)
547#define SDL_COLORSPACECHROMA(X) (SDL_ChromaLocation)(((X) >> 20) & 0x0F)
548#define SDL_COLORSPACEPRIMARIES(X) (SDL_ColorPrimaries)(((X) >> 10) & 0x1F)
549#define SDL_COLORSPACETRANSFER(X) (SDL_TransferCharacteristics)(((X) >> 5) & 0x1F)
550#define SDL_COLORSPACEMATRIX(X) (SDL_MatrixCoefficients)((X) & 0x1F)
551
552#define SDL_ISCOLORSPACE_MATRIX_BT601(X) (SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT601 || SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT470BG)
553#define SDL_ISCOLORSPACE_MATRIX_BT709(X) (SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT709)
554#define SDL_ISCOLORSPACE_MATRIX_BT2020_NCL(X) (SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT2020_NCL)
555#define SDL_ISCOLORSPACE_LIMITED_RANGE(X) (SDL_COLORSPACERANGE(X) != SDL_COLOR_RANGE_FULL)
556#define SDL_ISCOLORSPACE_FULL_RANGE(X) (SDL_COLORSPACERANGE(X) == SDL_COLOR_RANGE_FULL)
557
558/**
559 * Colorspace definitions.
560 *
561 * Since similar colorspaces may vary in their details (matrix, transfer
562 * function, etc.), this is not an exhaustive list, but rather a
563 * representative sample of the kinds of colorspaces supported in SDL.
564 *
565 * \since This enum is available since SDL 3.0.0.
566 *
567 * \sa SDL_ColorPrimaries
568 * \sa SDL_ColorRange
569 * \sa SDL_ColorType
570 * \sa SDL_MatrixCoefficients
571 * \sa SDL_TransferCharacteristics
572 */
573typedef enum SDL_Colorspace
574{
576
577 /* sRGB is a gamma corrected colorspace, and the default colorspace for SDL rendering and 8-bit RGB surfaces */
578 SDL_COLORSPACE_SRGB = 0x120005a0u, /**< Equivalent to DXGI_COLOR_SPACE_RGB_FULL_G22_NONE_P709 */
579 /* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_RGB,
580 SDL_COLOR_RANGE_FULL,
581 SDL_COLOR_PRIMARIES_BT709,
582 SDL_TRANSFER_CHARACTERISTICS_SRGB,
583 SDL_MATRIX_COEFFICIENTS_IDENTITY,
584 SDL_CHROMA_LOCATION_NONE), */
585
586 /* This is a linear colorspace and the default colorspace for floating point surfaces. On Windows this is the scRGB colorspace, and on Apple platforms this is kCGColorSpaceExtendedLinearSRGB for EDR content */
587 SDL_COLORSPACE_SRGB_LINEAR = 0x12000500u, /**< Equivalent to DXGI_COLOR_SPACE_RGB_FULL_G10_NONE_P709 */
588 /* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_RGB,
589 SDL_COLOR_RANGE_FULL,
590 SDL_COLOR_PRIMARIES_BT709,
591 SDL_TRANSFER_CHARACTERISTICS_LINEAR,
592 SDL_MATRIX_COEFFICIENTS_IDENTITY,
593 SDL_CHROMA_LOCATION_NONE), */
594
595 /* HDR10 is a non-linear HDR colorspace and the default colorspace for 10-bit surfaces */
596 SDL_COLORSPACE_HDR10 = 0x12002600u, /**< Equivalent to DXGI_COLOR_SPACE_RGB_FULL_G2084_NONE_P2020 */
597 /* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_RGB,
598 SDL_COLOR_RANGE_FULL,
599 SDL_COLOR_PRIMARIES_BT2020,
600 SDL_TRANSFER_CHARACTERISTICS_PQ,
601 SDL_MATRIX_COEFFICIENTS_IDENTITY,
602 SDL_CHROMA_LOCATION_NONE), */
603
604 SDL_COLORSPACE_JPEG = 0x220004c6u, /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_FULL_G22_NONE_P709_X601 */
605 /* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_YCBCR,
606 SDL_COLOR_RANGE_FULL,
607 SDL_COLOR_PRIMARIES_BT709,
608 SDL_TRANSFER_CHARACTERISTICS_BT601,
609 SDL_MATRIX_COEFFICIENTS_BT601,
610 SDL_CHROMA_LOCATION_NONE), */
611
612 SDL_COLORSPACE_BT601_LIMITED = 0x211018c6u, /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P601 */
613 /* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_YCBCR,
614 SDL_COLOR_RANGE_LIMITED,
615 SDL_COLOR_PRIMARIES_BT601,
616 SDL_TRANSFER_CHARACTERISTICS_BT601,
617 SDL_MATRIX_COEFFICIENTS_BT601,
618 SDL_CHROMA_LOCATION_LEFT), */
619
620 SDL_COLORSPACE_BT601_FULL = 0x221018c6u, /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P601 */
621 /* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_YCBCR,
622 SDL_COLOR_RANGE_FULL,
623 SDL_COLOR_PRIMARIES_BT601,
624 SDL_TRANSFER_CHARACTERISTICS_BT601,
625 SDL_MATRIX_COEFFICIENTS_BT601,
626 SDL_CHROMA_LOCATION_LEFT), */
627
628 SDL_COLORSPACE_BT709_LIMITED = 0x21100421u, /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P709 */
629 /* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_YCBCR,
630 SDL_COLOR_RANGE_LIMITED,
631 SDL_COLOR_PRIMARIES_BT709,
632 SDL_TRANSFER_CHARACTERISTICS_BT709,
633 SDL_MATRIX_COEFFICIENTS_BT709,
634 SDL_CHROMA_LOCATION_LEFT), */
635
636 SDL_COLORSPACE_BT709_FULL = 0x22100421u, /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P709 */
637 /* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_YCBCR,
638 SDL_COLOR_RANGE_FULL,
639 SDL_COLOR_PRIMARIES_BT709,
640 SDL_TRANSFER_CHARACTERISTICS_BT709,
641 SDL_MATRIX_COEFFICIENTS_BT709,
642 SDL_CHROMA_LOCATION_LEFT), */
643
644 SDL_COLORSPACE_BT2020_LIMITED = 0x21102609u, /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P2020 */
645 /* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_YCBCR,
646 SDL_COLOR_RANGE_LIMITED,
647 SDL_COLOR_PRIMARIES_BT2020,
648 SDL_TRANSFER_CHARACTERISTICS_PQ,
649 SDL_MATRIX_COEFFICIENTS_BT2020_NCL,
650 SDL_CHROMA_LOCATION_LEFT), */
651
652 SDL_COLORSPACE_BT2020_FULL = 0x22102609u /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_FULL_G22_LEFT_P2020 */
653 /* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_YCBCR,
654 SDL_COLOR_RANGE_FULL,
655 SDL_COLOR_PRIMARIES_BT2020,
656 SDL_TRANSFER_CHARACTERISTICS_PQ,
657 SDL_MATRIX_COEFFICIENTS_BT2020_NCL,
658 SDL_CHROMA_LOCATION_LEFT), */
659
661
662
663/* The default colorspace for RGB surfaces if no colorspace is specified */
664#define SDL_COLORSPACE_RGB_DEFAULT SDL_COLORSPACE_SRGB
665
666/* The default colorspace for YUV surfaces if no colorspace is specified */
667#define SDL_COLORSPACE_YUV_DEFAULT SDL_COLORSPACE_JPEG
668
669/**
670 * A structure that represents a color as RGBA components.
671 *
672 * The bits of this structure can be directly reinterpreted as an
673 * integer-packed color which uses the SDL_PIXELFORMAT_RGBA32 format
674 * (SDL_PIXELFORMAT_ABGR8888 on little-endian systems and
675 * SDL_PIXELFORMAT_RGBA8888 on big-endian systems).
676 *
677 * \since This struct is available since SDL 3.0.0.
678 */
686
687/**
688 * The bits of this structure can be directly reinterpreted as a float-packed
689 * color which uses the SDL_PIXELFORMAT_RGBA128_FLOAT format
690 *
691 * \since This struct is available since SDL 3.0.0.
692 */
693typedef struct SDL_FColor
694{
695 float r;
696 float g;
697 float b;
698 float a;
699} SDL_FColor;
700
701/**
702 * A set of indexed colors representing a palette.
703 *
704 * \since This struct is available since SDL 3.0.0.
705 *
706 * \sa SDL_SetPaletteColors
707 */
708typedef struct SDL_Palette
709{
710 int ncolors; /**< number of elements in `colors`. */
711 SDL_Color *colors; /**< an array of colors, `ncolors` long. */
712 Uint32 version; /**< internal use only, do not touch. */
713 int refcount; /**< internal use only, do not touch. */
715
716/**
717 * Details about the format of a pixel.
718 *
719 * \since This struct is available since SDL 3.0.0.
720 */
740
741/**
742 * Get the human readable name of a pixel format.
743 *
744 * \param format the pixel format to query.
745 * \returns the human readable name of the specified pixel format or
746 * "SDL_PIXELFORMAT_UNKNOWN" if the format isn't recognized.
747 *
748 * \threadsafety It is safe to call this function from any thread.
749 *
750 * \since This function is available since SDL 3.0.0.
751 */
752extern SDL_DECLSPEC const char * SDLCALL SDL_GetPixelFormatName(SDL_PixelFormat format);
753
754/**
755 * Convert one of the enumerated pixel formats to a bpp value and RGBA masks.
756 *
757 * \param format one of the SDL_PixelFormat values.
758 * \param bpp a bits per pixel value; usually 15, 16, or 32.
759 * \param Rmask a pointer filled in with the red mask for the format.
760 * \param Gmask a pointer filled in with the green mask for the format.
761 * \param Bmask a pointer filled in with the blue mask for the format.
762 * \param Amask a pointer filled in with the alpha mask for the format.
763 * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
764 * for more information.
765 *
766 * \threadsafety It is safe to call this function from any thread.
767 *
768 * \since This function is available since SDL 3.0.0.
769 *
770 * \sa SDL_GetPixelFormatForMasks
771 */
772extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetMasksForPixelFormat(SDL_PixelFormat format, int *bpp, Uint32 *Rmask, Uint32 *Gmask, Uint32 *Bmask, Uint32 *Amask);
773
774/**
775 * Convert a bpp value and RGBA masks to an enumerated pixel format.
776 *
777 * This will return `SDL_PIXELFORMAT_UNKNOWN` if the conversion wasn't
778 * possible.
779 *
780 * \param bpp a bits per pixel value; usually 15, 16, or 32.
781 * \param Rmask the red mask for the format.
782 * \param Gmask the green mask for the format.
783 * \param Bmask the blue mask for the format.
784 * \param Amask the alpha mask for the format.
785 * \returns the SDL_PixelFormat value corresponding to the format masks, or
786 * SDL_PIXELFORMAT_UNKNOWN if there isn't a match.
787 *
788 * \threadsafety It is safe to call this function from any thread.
789 *
790 * \since This function is available since SDL 3.0.0.
791 *
792 * \sa SDL_GetMasksForPixelFormat
793 */
794extern SDL_DECLSPEC SDL_PixelFormat SDLCALL SDL_GetPixelFormatForMasks(int bpp, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
795
796/**
797 * Create an SDL_PixelFormatDetails structure corresponding to a pixel format.
798 *
799 * Returned structure may come from a shared global cache (i.e. not newly
800 * allocated), and hence should not be modified, especially the palette. Weird
801 * errors such as `Blit combination not supported` may occur.
802 *
803 * \param format one of the SDL_PixelFormat values.
804 * \returns a pointer to a SDL_PixelFormatDetails structure or NULL on
805 * failure; call SDL_GetError() for more information.
806 *
807 * \threadsafety It is safe to call this function from any thread.
808 *
809 * \since This function is available since SDL 3.0.0.
810 */
811extern SDL_DECLSPEC const SDL_PixelFormatDetails * SDLCALL SDL_GetPixelFormatDetails(SDL_PixelFormat format);
812
813/**
814 * Create a palette structure with the specified number of color entries.
815 *
816 * The palette entries are initialized to white.
817 *
818 * \param ncolors represents the number of color entries in the color palette.
819 * \returns a new SDL_Palette structure on success or NULL on failure (e.g. if
820 * there wasn't enough memory); call SDL_GetError() for more
821 * information.
822 *
823 * \threadsafety It is safe to call this function from any thread.
824 *
825 * \since This function is available since SDL 3.0.0.
826 *
827 * \sa SDL_DestroyPalette
828 * \sa SDL_SetPaletteColors
829 * \sa SDL_SetSurfacePalette
830 */
831extern SDL_DECLSPEC SDL_Palette * SDLCALL SDL_CreatePalette(int ncolors);
832
833/**
834 * Set a range of colors in a palette.
835 *
836 * \param palette the SDL_Palette structure to modify.
837 * \param colors an array of SDL_Color structures to copy into the palette.
838 * \param firstcolor the index of the first palette entry to modify.
839 * \param ncolors the number of entries to modify.
840 * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
841 * for more information.
842 *
843 * \threadsafety It is safe to call this function from any thread, as long as
844 * the palette is not modified or destroyed in another thread.
845 *
846 * \since This function is available since SDL 3.0.0.
847 */
848extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPaletteColors(SDL_Palette *palette, const SDL_Color *colors, int firstcolor, int ncolors);
849
850/**
851 * Free a palette created with SDL_CreatePalette().
852 *
853 * \param palette the SDL_Palette structure to be freed.
854 *
855 * \threadsafety It is safe to call this function from any thread, as long as
856 * the palette is not modified or destroyed in another thread.
857 *
858 * \since This function is available since SDL 3.0.0.
859 *
860 * \sa SDL_CreatePalette
861 */
862extern SDL_DECLSPEC void SDLCALL SDL_DestroyPalette(SDL_Palette *palette);
863
864/**
865 * Map an RGB triple to an opaque pixel value for a given pixel format.
866 *
867 * This function maps the RGB color value to the specified pixel format and
868 * returns the pixel value best approximating the given RGB color value for
869 * the given pixel format.
870 *
871 * If the format has a palette (8-bit) the index of the closest matching color
872 * in the palette will be returned.
873 *
874 * If the specified pixel format has an alpha component it will be returned as
875 * all 1 bits (fully opaque).
876 *
877 * If the pixel format bpp (color depth) is less than 32-bpp then the unused
878 * upper bits of the return value can safely be ignored (e.g., with a 16-bpp
879 * format the return value can be assigned to a Uint16, and similarly a Uint8
880 * for an 8-bpp format).
881 *
882 * \param format a pointer to SDL_PixelFormatDetails describing the pixel
883 * format.
884 * \param palette an optional palette for indexed formats, may be NULL.
885 * \param r the red component of the pixel in the range 0-255.
886 * \param g the green component of the pixel in the range 0-255.
887 * \param b the blue component of the pixel in the range 0-255.
888 * \returns a pixel value.
889 *
890 * \threadsafety It is safe to call this function from any thread, as long as
891 * the palette is not modified.
892 *
893 * \since This function is available since SDL 3.0.0.
894 *
895 * \sa SDL_GetPixelFormatDetails
896 * \sa SDL_GetRGB
897 * \sa SDL_MapRGBA
898 * \sa SDL_MapSurfaceRGB
899 */
900extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormatDetails *format, const SDL_Palette *palette, Uint8 r, Uint8 g, Uint8 b);
901
902/**
903 * Map an RGBA quadruple to a pixel value for a given pixel format.
904 *
905 * This function maps the RGBA color value to the specified pixel format and
906 * returns the pixel value best approximating the given RGBA color value for
907 * the given pixel format.
908 *
909 * If the specified pixel format has no alpha component the alpha value will
910 * be ignored (as it will be in formats with a palette).
911 *
912 * If the format has a palette (8-bit) the index of the closest matching color
913 * in the palette will be returned.
914 *
915 * If the pixel format bpp (color depth) is less than 32-bpp then the unused
916 * upper bits of the return value can safely be ignored (e.g., with a 16-bpp
917 * format the return value can be assigned to a Uint16, and similarly a Uint8
918 * for an 8-bpp format).
919 *
920 * \param format a pointer to SDL_PixelFormatDetails describing the pixel
921 * format.
922 * \param palette an optional palette for indexed formats, may be NULL.
923 * \param r the red component of the pixel in the range 0-255.
924 * \param g the green component of the pixel in the range 0-255.
925 * \param b the blue component of the pixel in the range 0-255.
926 * \param a the alpha component of the pixel in the range 0-255.
927 * \returns a pixel value.
928 *
929 * \threadsafety It is safe to call this function from any thread, as long as
930 * the palette is not modified.
931 *
932 * \since This function is available since SDL 3.0.0.
933 *
934 * \sa SDL_GetPixelFormatDetails
935 * \sa SDL_GetRGBA
936 * \sa SDL_MapRGB
937 * \sa SDL_MapSurfaceRGBA
938 */
939extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormatDetails *format, const SDL_Palette *palette, Uint8 r, Uint8 g, Uint8 b, Uint8 a);
940
941/**
942 * Get RGB values from a pixel in the specified format.
943 *
944 * This function uses the entire 8-bit [0..255] range when converting color
945 * components from pixel formats with less than 8-bits per RGB component
946 * (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff,
947 * 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).
948 *
949 * \param pixel a pixel value.
950 * \param format a pointer to SDL_PixelFormatDetails describing the pixel
951 * format.
952 * \param palette an optional palette for indexed formats, may be NULL.
953 * \param r a pointer filled in with the red component, may be NULL.
954 * \param g a pointer filled in with the green component, may be NULL.
955 * \param b a pointer filled in with the blue component, may be NULL.
956 *
957 * \threadsafety It is safe to call this function from any thread, as long as
958 * the palette is not modified.
959 *
960 * \since This function is available since SDL 3.0.0.
961 *
962 * \sa SDL_GetPixelFormatDetails
963 * \sa SDL_GetRGBA
964 * \sa SDL_MapRGB
965 * \sa SDL_MapRGBA
966 */
967extern SDL_DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel, const SDL_PixelFormatDetails *format, const SDL_Palette *palette, Uint8 *r, Uint8 *g, Uint8 *b);
968
969/**
970 * Get RGBA values from a pixel in the specified format.
971 *
972 * This function uses the entire 8-bit [0..255] range when converting color
973 * components from pixel formats with less than 8-bits per RGB component
974 * (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff,
975 * 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).
976 *
977 * If the surface has no alpha component, the alpha will be returned as 0xff
978 * (100% opaque).
979 *
980 * \param pixel a pixel value.
981 * \param format a pointer to SDL_PixelFormatDetails describing the pixel
982 * format.
983 * \param palette an optional palette for indexed formats, may be NULL.
984 * \param r a pointer filled in with the red component, may be NULL.
985 * \param g a pointer filled in with the green component, may be NULL.
986 * \param b a pointer filled in with the blue component, may be NULL.
987 * \param a a pointer filled in with the alpha component, may be NULL.
988 *
989 * \threadsafety It is safe to call this function from any thread, as long as
990 * the palette is not modified.
991 *
992 * \since This function is available since SDL 3.0.0.
993 *
994 * \sa SDL_GetPixelFormatDetails
995 * \sa SDL_GetRGB
996 * \sa SDL_MapRGB
997 * \sa SDL_MapRGBA
998 */
999extern SDL_DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel, const SDL_PixelFormatDetails *format, const SDL_Palette *palette, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a);
1000
1001
1002/* Ends C function definitions when using C++ */
1003#ifdef __cplusplus
1004}
1005#endif
1006#include <SDL3/SDL_close_code.h>
1007
1008#endif /* SDL_pixels_h_ */
SDL_MatrixCoefficients
Definition SDL_pixels.h:508
@ SDL_MATRIX_COEFFICIENTS_BT709
Definition SDL_pixels.h:510
@ SDL_MATRIX_COEFFICIENTS_BT2020_CL
Definition SDL_pixels.h:518
@ SDL_MATRIX_COEFFICIENTS_BT601
Definition SDL_pixels.h:514
@ SDL_MATRIX_COEFFICIENTS_BT2020_NCL
Definition SDL_pixels.h:517
@ SDL_MATRIX_COEFFICIENTS_SMPTE240
Definition SDL_pixels.h:515
@ SDL_MATRIX_COEFFICIENTS_YCGCO
Definition SDL_pixels.h:516
@ SDL_MATRIX_COEFFICIENTS_CHROMA_DERIVED_NCL
Definition SDL_pixels.h:520
@ SDL_MATRIX_COEFFICIENTS_CHROMA_DERIVED_CL
Definition SDL_pixels.h:521
@ SDL_MATRIX_COEFFICIENTS_UNSPECIFIED
Definition SDL_pixels.h:511
@ SDL_MATRIX_COEFFICIENTS_CUSTOM
Definition SDL_pixels.h:523
@ SDL_MATRIX_COEFFICIENTS_ICTCP
Definition SDL_pixels.h:522
@ SDL_MATRIX_COEFFICIENTS_IDENTITY
Definition SDL_pixels.h:509
@ SDL_MATRIX_COEFFICIENTS_FCC
Definition SDL_pixels.h:512
@ SDL_MATRIX_COEFFICIENTS_BT470BG
Definition SDL_pixels.h:513
@ SDL_MATRIX_COEFFICIENTS_SMPTE2085
Definition SDL_pixels.h:519
SDL_PixelType
Definition SDL_pixels.h:79
@ SDL_PIXELTYPE_UNKNOWN
Definition SDL_pixels.h:80
@ SDL_PIXELTYPE_ARRAYU16
Definition SDL_pixels.h:88
@ SDL_PIXELTYPE_PACKED32
Definition SDL_pixels.h:86
@ SDL_PIXELTYPE_INDEX2
Definition SDL_pixels.h:93
@ SDL_PIXELTYPE_ARRAYU8
Definition SDL_pixels.h:87
@ SDL_PIXELTYPE_INDEX4
Definition SDL_pixels.h:82
@ SDL_PIXELTYPE_PACKED8
Definition SDL_pixels.h:84
@ SDL_PIXELTYPE_ARRAYF16
Definition SDL_pixels.h:90
@ SDL_PIXELTYPE_ARRAYU32
Definition SDL_pixels.h:89
@ SDL_PIXELTYPE_INDEX1
Definition SDL_pixels.h:81
@ SDL_PIXELTYPE_ARRAYF32
Definition SDL_pixels.h:91
@ SDL_PIXELTYPE_INDEX8
Definition SDL_pixels.h:83
@ SDL_PIXELTYPE_PACKED16
Definition SDL_pixels.h:85
SDL_ColorRange
Definition SDL_pixels.h:440
@ SDL_COLOR_RANGE_LIMITED
Definition SDL_pixels.h:442
@ SDL_COLOR_RANGE_FULL
Definition SDL_pixels.h:443
@ SDL_COLOR_RANGE_UNKNOWN
Definition SDL_pixels.h:441
SDL_ColorPrimaries
Definition SDL_pixels.h:453
@ SDL_COLOR_PRIMARIES_SMPTE431
Definition SDL_pixels.h:464
@ SDL_COLOR_PRIMARIES_CUSTOM
Definition SDL_pixels.h:467
@ SDL_COLOR_PRIMARIES_EBU3213
Definition SDL_pixels.h:466
@ SDL_COLOR_PRIMARIES_GENERIC_FILM
Definition SDL_pixels.h:461
@ SDL_COLOR_PRIMARIES_BT601
Definition SDL_pixels.h:459
@ SDL_COLOR_PRIMARIES_UNSPECIFIED
Definition SDL_pixels.h:456
@ SDL_COLOR_PRIMARIES_SMPTE240
Definition SDL_pixels.h:460
@ SDL_COLOR_PRIMARIES_XYZ
Definition SDL_pixels.h:463
@ SDL_COLOR_PRIMARIES_UNKNOWN
Definition SDL_pixels.h:454
@ SDL_COLOR_PRIMARIES_SMPTE432
Definition SDL_pixels.h:465
@ SDL_COLOR_PRIMARIES_BT2020
Definition SDL_pixels.h:462
@ SDL_COLOR_PRIMARIES_BT470BG
Definition SDL_pixels.h:458
@ SDL_COLOR_PRIMARIES_BT709
Definition SDL_pixels.h:455
@ SDL_COLOR_PRIMARIES_BT470M
Definition SDL_pixels.h:457
Uint32 SDL_MapRGB(const SDL_PixelFormatDetails *format, const SDL_Palette *palette, Uint8 r, Uint8 g, Uint8 b)
SDL_PackedLayout
Definition SDL_pixels.h:132
@ SDL_PACKEDLAYOUT_NONE
Definition SDL_pixels.h:133
@ SDL_PACKEDLAYOUT_8888
Definition SDL_pixels.h:139
@ SDL_PACKEDLAYOUT_1010102
Definition SDL_pixels.h:141
@ SDL_PACKEDLAYOUT_565
Definition SDL_pixels.h:138
@ SDL_PACKEDLAYOUT_332
Definition SDL_pixels.h:134
@ SDL_PACKEDLAYOUT_5551
Definition SDL_pixels.h:137
@ SDL_PACKEDLAYOUT_1555
Definition SDL_pixels.h:136
@ SDL_PACKEDLAYOUT_4444
Definition SDL_pixels.h:135
@ SDL_PACKEDLAYOUT_2101010
Definition SDL_pixels.h:140
SDL_Palette * SDL_CreatePalette(int ncolors)
SDL_BitmapOrder
Definition SDL_pixels.h:98
@ SDL_BITMAPORDER_1234
Definition SDL_pixels.h:101
@ SDL_BITMAPORDER_NONE
Definition SDL_pixels.h:99
@ SDL_BITMAPORDER_4321
Definition SDL_pixels.h:100
SDL_ChromaLocation
Definition SDL_pixels.h:532
@ SDL_CHROMA_LOCATION_NONE
Definition SDL_pixels.h:533
@ SDL_CHROMA_LOCATION_TOPLEFT
Definition SDL_pixels.h:536
@ SDL_CHROMA_LOCATION_CENTER
Definition SDL_pixels.h:535
@ SDL_CHROMA_LOCATION_LEFT
Definition SDL_pixels.h:534
Uint32 SDL_MapRGBA(const SDL_PixelFormatDetails *format, const SDL_Palette *palette, Uint8 r, Uint8 g, Uint8 b, Uint8 a)
void SDL_DestroyPalette(SDL_Palette *palette)
SDL_ColorType
Definition SDL_pixels.h:427
@ SDL_COLOR_TYPE_RGB
Definition SDL_pixels.h:429
@ SDL_COLOR_TYPE_YCBCR
Definition SDL_pixels.h:430
@ SDL_COLOR_TYPE_UNKNOWN
Definition SDL_pixels.h:428
SDL_TransferCharacteristics
Definition SDL_pixels.h:478
@ SDL_TRANSFER_CHARACTERISTICS_BT709
Definition SDL_pixels.h:480
@ SDL_TRANSFER_CHARACTERISTICS_BT1361
Definition SDL_pixels.h:490
@ SDL_TRANSFER_CHARACTERISTICS_CUSTOM
Definition SDL_pixels.h:497
@ SDL_TRANSFER_CHARACTERISTICS_HLG
Definition SDL_pixels.h:496
@ SDL_TRANSFER_CHARACTERISTICS_LOG100_SQRT10
Definition SDL_pixels.h:488
@ SDL_TRANSFER_CHARACTERISTICS_UNKNOWN
Definition SDL_pixels.h:479
@ SDL_TRANSFER_CHARACTERISTICS_BT601
Definition SDL_pixels.h:484
@ SDL_TRANSFER_CHARACTERISTICS_IEC61966
Definition SDL_pixels.h:489
@ SDL_TRANSFER_CHARACTERISTICS_UNSPECIFIED
Definition SDL_pixels.h:481
@ SDL_TRANSFER_CHARACTERISTICS_SMPTE428
Definition SDL_pixels.h:495
@ SDL_TRANSFER_CHARACTERISTICS_LOG100
Definition SDL_pixels.h:487
@ SDL_TRANSFER_CHARACTERISTICS_GAMMA28
Definition SDL_pixels.h:483
@ SDL_TRANSFER_CHARACTERISTICS_SMPTE240
Definition SDL_pixels.h:485
@ SDL_TRANSFER_CHARACTERISTICS_BT2020_10BIT
Definition SDL_pixels.h:492
@ SDL_TRANSFER_CHARACTERISTICS_SRGB
Definition SDL_pixels.h:491
@ SDL_TRANSFER_CHARACTERISTICS_PQ
Definition SDL_pixels.h:494
@ SDL_TRANSFER_CHARACTERISTICS_LINEAR
Definition SDL_pixels.h:486
@ SDL_TRANSFER_CHARACTERISTICS_BT2020_12BIT
Definition SDL_pixels.h:493
@ SDL_TRANSFER_CHARACTERISTICS_GAMMA22
Definition SDL_pixels.h:482
SDL_ArrayOrder
Definition SDL_pixels.h:120
@ SDL_ARRAYORDER_RGB
Definition SDL_pixels.h:122
@ SDL_ARRAYORDER_NONE
Definition SDL_pixels.h:121
@ SDL_ARRAYORDER_ARGB
Definition SDL_pixels.h:124
@ SDL_ARRAYORDER_BGRA
Definition SDL_pixels.h:126
@ SDL_ARRAYORDER_ABGR
Definition SDL_pixels.h:127
@ SDL_ARRAYORDER_RGBA
Definition SDL_pixels.h:123
@ SDL_ARRAYORDER_BGR
Definition SDL_pixels.h:125
const char * SDL_GetPixelFormatName(SDL_PixelFormat format)
SDL_Colorspace
Definition SDL_pixels.h:574
@ SDL_COLORSPACE_BT2020_LIMITED
Definition SDL_pixels.h:644
@ SDL_COLORSPACE_BT601_LIMITED
Definition SDL_pixels.h:612
@ SDL_COLORSPACE_BT709_FULL
Definition SDL_pixels.h:636
@ SDL_COLORSPACE_HDR10
Definition SDL_pixels.h:596
@ SDL_COLORSPACE_BT601_FULL
Definition SDL_pixels.h:620
@ SDL_COLORSPACE_UNKNOWN
Definition SDL_pixels.h:575
@ SDL_COLORSPACE_BT2020_FULL
Definition SDL_pixels.h:652
@ SDL_COLORSPACE_JPEG
Definition SDL_pixels.h:604
@ SDL_COLORSPACE_BT709_LIMITED
Definition SDL_pixels.h:628
@ SDL_COLORSPACE_SRGB_LINEAR
Definition SDL_pixels.h:587
@ SDL_COLORSPACE_SRGB
Definition SDL_pixels.h:578
SDL_PixelFormat
Definition SDL_pixels.h:245
@ SDL_PIXELFORMAT_BGR48_FLOAT
Definition SDL_pixels.h:333
@ SDL_PIXELFORMAT_RGBA128_FLOAT
Definition SDL_pixels.h:347
@ SDL_PIXELFORMAT_BGR565
Definition SDL_pixels.h:289
@ SDL_PIXELFORMAT_P010
Definition SDL_pixels.h:370
@ SDL_PIXELFORMAT_EXTERNAL_OES
Definition SDL_pixels.h:372
@ SDL_PIXELFORMAT_ARGB64
Definition SDL_pixels.h:325
@ SDL_PIXELFORMAT_YVYU
Definition SDL_pixels.h:364
@ SDL_PIXELFORMAT_RGB332
Definition SDL_pixels.h:261
@ SDL_PIXELFORMAT_INDEX2LSB
Definition SDL_pixels.h:251
@ SDL_PIXELFORMAT_INDEX1LSB
Definition SDL_pixels.h:247
@ SDL_PIXELFORMAT_RGB96_FLOAT
Definition SDL_pixels.h:343
@ SDL_PIXELFORMAT_ABGR4444
Definition SDL_pixels.h:275
@ SDL_PIXELFORMAT_BGRA4444
Definition SDL_pixels.h:277
@ SDL_PIXELFORMAT_BGR24
Definition SDL_pixels.h:293
@ SDL_PIXELFORMAT_INDEX4MSB
Definition SDL_pixels.h:257
@ SDL_PIXELFORMAT_ABGR2101010
Definition SDL_pixels.h:317
@ SDL_PIXELFORMAT_XBGR2101010
Definition SDL_pixels.h:313
@ SDL_PIXELFORMAT_RGBA64_FLOAT
Definition SDL_pixels.h:335
@ SDL_PIXELFORMAT_INDEX2MSB
Definition SDL_pixels.h:253
@ SDL_PIXELFORMAT_BGRA64_FLOAT
Definition SDL_pixels.h:339
@ SDL_PIXELFORMAT_RGBA8888
Definition SDL_pixels.h:305
@ SDL_PIXELFORMAT_RGBA5551
Definition SDL_pixels.h:281
@ SDL_PIXELFORMAT_ARGB1555
Definition SDL_pixels.h:279
@ SDL_PIXELFORMAT_XBGR4444
Definition SDL_pixels.h:265
@ SDL_PIXELFORMAT_RGBA64
Definition SDL_pixels.h:323
@ SDL_PIXELFORMAT_INDEX8
Definition SDL_pixels.h:259
@ SDL_PIXELFORMAT_XRGB2101010
Definition SDL_pixels.h:311
@ SDL_PIXELFORMAT_XRGB8888
Definition SDL_pixels.h:295
@ SDL_PIXELFORMAT_UYVY
Definition SDL_pixels.h:362
@ SDL_PIXELFORMAT_YV12
Definition SDL_pixels.h:356
@ SDL_PIXELFORMAT_BGRX8888
Definition SDL_pixels.h:301
@ SDL_PIXELFORMAT_RGB24
Definition SDL_pixels.h:291
@ SDL_PIXELFORMAT_BGRA64
Definition SDL_pixels.h:327
@ SDL_PIXELFORMAT_ABGR8888
Definition SDL_pixels.h:307
@ SDL_PIXELFORMAT_YUY2
Definition SDL_pixels.h:360
@ SDL_PIXELFORMAT_NV12
Definition SDL_pixels.h:366
@ SDL_PIXELFORMAT_BGRA8888
Definition SDL_pixels.h:309
@ SDL_PIXELFORMAT_ABGR128_FLOAT
Definition SDL_pixels.h:353
@ SDL_PIXELFORMAT_ABGR1555
Definition SDL_pixels.h:283
@ SDL_PIXELFORMAT_NV21
Definition SDL_pixels.h:368
@ SDL_PIXELFORMAT_IYUV
Definition SDL_pixels.h:358
@ SDL_PIXELFORMAT_ARGB8888
Definition SDL_pixels.h:303
@ SDL_PIXELFORMAT_ABGR64_FLOAT
Definition SDL_pixels.h:341
@ SDL_PIXELFORMAT_ABGR64
Definition SDL_pixels.h:329
@ SDL_PIXELFORMAT_XBGR1555
Definition SDL_pixels.h:269
@ SDL_PIXELFORMAT_RGB48
Definition SDL_pixels.h:319
@ SDL_PIXELFORMAT_XRGB4444
Definition SDL_pixels.h:263
@ SDL_PIXELFORMAT_BGR96_FLOAT
Definition SDL_pixels.h:345
@ SDL_PIXELFORMAT_ARGB4444
Definition SDL_pixels.h:271
@ SDL_PIXELFORMAT_RGB48_FLOAT
Definition SDL_pixels.h:331
@ SDL_PIXELFORMAT_BGR48
Definition SDL_pixels.h:321
@ SDL_PIXELFORMAT_BGRA128_FLOAT
Definition SDL_pixels.h:351
@ SDL_PIXELFORMAT_ARGB64_FLOAT
Definition SDL_pixels.h:337
@ SDL_PIXELFORMAT_INDEX1MSB
Definition SDL_pixels.h:249
@ SDL_PIXELFORMAT_INDEX4LSB
Definition SDL_pixels.h:255
@ SDL_PIXELFORMAT_RGBX8888
Definition SDL_pixels.h:297
@ SDL_PIXELFORMAT_BGRA5551
Definition SDL_pixels.h:285
@ SDL_PIXELFORMAT_ARGB128_FLOAT
Definition SDL_pixels.h:349
@ SDL_PIXELFORMAT_XRGB1555
Definition SDL_pixels.h:267
@ SDL_PIXELFORMAT_RGB565
Definition SDL_pixels.h:287
@ SDL_PIXELFORMAT_XBGR8888
Definition SDL_pixels.h:299
@ SDL_PIXELFORMAT_ARGB2101010
Definition SDL_pixels.h:315
@ SDL_PIXELFORMAT_UNKNOWN
Definition SDL_pixels.h:246
@ SDL_PIXELFORMAT_RGBA4444
Definition SDL_pixels.h:273
void SDL_GetRGB(Uint32 pixel, const SDL_PixelFormatDetails *format, const SDL_Palette *palette, Uint8 *r, Uint8 *g, Uint8 *b)
const SDL_PixelFormatDetails * SDL_GetPixelFormatDetails(SDL_PixelFormat format)
SDL_PackedOrder
Definition SDL_pixels.h:106
@ SDL_PACKEDORDER_NONE
Definition SDL_pixels.h:107
@ SDL_PACKEDORDER_RGBX
Definition SDL_pixels.h:109
@ SDL_PACKEDORDER_BGRX
Definition SDL_pixels.h:113
@ SDL_PACKEDORDER_XBGR
Definition SDL_pixels.h:112
@ SDL_PACKEDORDER_RGBA
Definition SDL_pixels.h:111
@ SDL_PACKEDORDER_ABGR
Definition SDL_pixels.h:114
@ SDL_PACKEDORDER_BGRA
Definition SDL_pixels.h:115
@ SDL_PACKEDORDER_XRGB
Definition SDL_pixels.h:108
@ SDL_PACKEDORDER_ARGB
Definition SDL_pixels.h:110
SDL_PixelFormat SDL_GetPixelFormatForMasks(int bpp, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask)
SDL_bool SDL_SetPaletteColors(SDL_Palette *palette, const SDL_Color *colors, int firstcolor, int ncolors)
void SDL_GetRGBA(Uint32 pixel, const SDL_PixelFormatDetails *format, const SDL_Palette *palette, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a)
SDL_bool SDL_GetMasksForPixelFormat(SDL_PixelFormat format, int *bpp, Uint32 *Rmask, Uint32 *Gmask, Uint32 *Bmask, Uint32 *Amask)
uint8_t Uint8
Definition SDL_stdinc.h:232
uint32_t Uint32
Definition SDL_stdinc.h:268
bool SDL_bool
Definition SDL_stdinc.h:216
Uint32 version
Definition SDL_pixels.h:712
SDL_Color * colors
Definition SDL_pixels.h:711
SDL_PixelFormat format
Definition SDL_pixels.h:723