2015-06-21 09:33:46 -06:00
/*
Simple DirectMedia Layer
2024-01-01 14:15:26 -07:00
Copyright ( C ) 1997 - 2024 Sam Lantinga < slouken @ libsdl . org >
2015-06-21 09:33:46 -06:00
This software is provided ' as - is ' , without any express or implied
warranty . In no event will the authors be held liable for any damages
arising from the use of this software .
Permission is granted to anyone to use this software for any purpose ,
including commercial applications , and to alter it and redistribute it
freely , subject to the following restrictions :
1. The origin of this software must not be misrepresented ; you must not
claim that you wrote the original software . If you use this software
in a product , an acknowledgment in the product documentation would be
appreciated but is not required .
2. Altered source versions must be plainly marked as such , and must not be
misrepresented as being the original software .
3. This notice may not be removed or altered from any source distribution .
*/
/**
* \ file SDL_pixels . h
*
2023-11-06 08:26:06 -07:00
* Header for the enumerated pixel format definitions .
2023-09-29 08:49:24 -06:00
*
* SDL ' s pixel formats have the following naming convention :
*
* * Names with a list of components and a single bit count , such as
* RGB24 and ABGR32 , define a platform - independent encoding into
* bytes in the order specified . For example , in RGB24 data , each
* pixel is encoded in 3 bytes ( red , green , blue ) in that order ,
* and in ABGR32 data , each pixel is encoded in 4 bytes
* ( alpha , blue , green , red ) in that order . Use these names if the
* property of a format that is important to you is the order of
* the bytes in memory or on disk .
*
* * Names with a bit count per component , such as ARGB8888 and
* XRGB1555 , are " packed " into an appropriately - sized integer in
* the platform ' s native endianness . For example , ARGB8888 is
* a sequence of 32 - bit integers ; in each integer , the most
* significant bits are alpha , and the least significant bits are
* blue . On a little - endian CPU such as x86 , the least significant
* bits of each integer are arranged first in memory , but on a
* big - endian CPU such as s390x , the most significant bits are
* arranged first . Use these names if the property of a format that
* is important to you is the meaning of each bit position within a
* native - endianness integer .
*
* * In indexed formats such as INDEX4LSB , each pixel is represented
* by encoding an index into the palette into the indicated number
* of bits , with multiple pixels packed into each byte if appropriate .
* In LSB formats , the first ( leftmost ) pixel is stored in the
* least - significant bits of the byte ; in MSB formats , it ' s stored
* in the most - significant bits . INDEX8 does not need LSB / MSB
* variants , because each pixel exactly fills one byte .
*
* The 32 - bit byte - array encodings such as RGBA32 are aliases for the
* appropriate 8888 encoding for the current platform . For example ,
* RGBA32 is an alias for ABGR8888 on little - endian CPUs like x86 ,
* or an alias for RGBA8888 on big - endian CPUs .
2015-06-21 09:33:46 -06:00
*/
2016-11-20 22:34:54 -07:00
# ifndef SDL_pixels_h_
# define SDL_pixels_h_
2015-06-21 09:33:46 -06:00
2022-11-26 21:43:38 -07:00
# include <SDL3/SDL_stdinc.h>
2024-04-04 10:38:21 -06:00
# include <SDL3/SDL_error.h>
2022-11-26 21:43:38 -07:00
# include <SDL3/SDL_endian.h>
2015-06-21 09:33:46 -06:00
2022-12-22 09:38:59 -07:00
# include <SDL3/SDL_begin_code.h>
2015-06-21 09:33:46 -06:00
/* Set up for C function definitions, even when using C++ */
# ifdef __cplusplus
extern " C " {
# endif
/**
* \ name Transparency definitions
*
* These define alpha as the opacity of a surface .
*/
/* @{ */
# define SDL_ALPHA_OPAQUE 255
# define SDL_ALPHA_TRANSPARENT 0
/* @} */
/** Pixel type. */
2024-04-08 20:36:57 -06:00
typedef enum SDL_PixelType
2015-06-21 09:33:46 -06:00
{
SDL_PIXELTYPE_UNKNOWN ,
SDL_PIXELTYPE_INDEX1 ,
SDL_PIXELTYPE_INDEX4 ,
SDL_PIXELTYPE_INDEX8 ,
SDL_PIXELTYPE_PACKED8 ,
SDL_PIXELTYPE_PACKED16 ,
SDL_PIXELTYPE_PACKED32 ,
SDL_PIXELTYPE_ARRAYU8 ,
SDL_PIXELTYPE_ARRAYU16 ,
SDL_PIXELTYPE_ARRAYU32 ,
SDL_PIXELTYPE_ARRAYF16 ,
2023-11-20 09:46:12 -07:00
SDL_PIXELTYPE_ARRAYF32 ,
/* appended at the end for compatibility with sdl2-compat: */
SDL_PIXELTYPE_INDEX2
2019-10-10 22:18:24 -06:00
} SDL_PixelType ;
2015-06-21 09:33:46 -06:00
/** Bitmap pixel order, high bit -> low bit. */
2024-04-08 20:36:57 -06:00
typedef enum SDL_BitmapOrder
2015-06-21 09:33:46 -06:00
{
SDL_BITMAPORDER_NONE ,
SDL_BITMAPORDER_4321 ,
SDL_BITMAPORDER_1234
2019-10-10 22:18:24 -06:00
} SDL_BitmapOrder ;
2015-06-21 09:33:46 -06:00
/** Packed component order, high bit -> low bit. */
2024-04-08 20:36:57 -06:00
typedef enum SDL_PackedOrder
2015-06-21 09:33:46 -06:00
{
SDL_PACKEDORDER_NONE ,
SDL_PACKEDORDER_XRGB ,
SDL_PACKEDORDER_RGBX ,
SDL_PACKEDORDER_ARGB ,
SDL_PACKEDORDER_RGBA ,
SDL_PACKEDORDER_XBGR ,
SDL_PACKEDORDER_BGRX ,
SDL_PACKEDORDER_ABGR ,
SDL_PACKEDORDER_BGRA
2019-10-10 22:18:24 -06:00
} SDL_PackedOrder ;
2015-06-21 09:33:46 -06:00
/** Array component order, low byte -> high byte. */
2024-04-08 20:36:57 -06:00
typedef enum SDL_ArrayOrder
2015-06-21 09:33:46 -06:00
{
SDL_ARRAYORDER_NONE ,
SDL_ARRAYORDER_RGB ,
2024-01-25 17:39:53 -07:00
SDL_ARRAYORDER_RGBA ,
SDL_ARRAYORDER_ARGB ,
SDL_ARRAYORDER_BGR ,
SDL_ARRAYORDER_BGRA ,
SDL_ARRAYORDER_ABGR
2019-10-10 22:18:24 -06:00
} SDL_ArrayOrder ;
2015-06-21 09:33:46 -06:00
/** Packed component layout. */
2024-04-08 20:36:57 -06:00
typedef enum SDL_PackedLayout
2015-06-21 09:33:46 -06:00
{
SDL_PACKEDLAYOUT_NONE ,
SDL_PACKEDLAYOUT_332 ,
SDL_PACKEDLAYOUT_4444 ,
SDL_PACKEDLAYOUT_1555 ,
SDL_PACKEDLAYOUT_5551 ,
SDL_PACKEDLAYOUT_565 ,
SDL_PACKEDLAYOUT_8888 ,
SDL_PACKEDLAYOUT_2101010 ,
SDL_PACKEDLAYOUT_1010102
2019-10-10 22:18:24 -06:00
} SDL_PackedLayout ;
2015-06-21 09:33:46 -06:00
# define SDL_DEFINE_PIXELFOURCC(A, B, C, D) SDL_FOURCC(A, B, C, D)
# define SDL_DEFINE_PIXELFORMAT(type, order, layout, bits, bytes) \
( ( 1 < < 28 ) | ( ( type ) < < 24 ) | ( ( order ) < < 20 ) | ( ( layout ) < < 16 ) | \
( ( bits ) < < 8 ) | ( ( bytes ) < < 0 ) )
# define SDL_PIXELFLAG(X) (((X) >> 28) & 0x0F)
# define SDL_PIXELTYPE(X) (((X) >> 24) & 0x0F)
# define SDL_PIXELORDER(X) (((X) >> 20) & 0x0F)
# define SDL_PIXELLAYOUT(X) (((X) >> 16) & 0x0F)
# define SDL_BITSPERPIXEL(X) (((X) >> 8) & 0xFF)
# define SDL_BYTESPERPIXEL(X) \
( SDL_ISPIXELFORMAT_FOURCC ( X ) ? \
( ( ( ( X ) = = SDL_PIXELFORMAT_YUY2 ) | | \
( ( X ) = = SDL_PIXELFORMAT_UYVY ) | | \
2024-02-04 23:19:28 -07:00
( ( X ) = = SDL_PIXELFORMAT_YVYU ) | | \
2024-02-27 13:26:09 -07:00
( ( X ) = = SDL_PIXELFORMAT_P010 ) ) ? 2 : 1 ) : ( ( ( X ) > > 0 ) & 0xFF ) )
2015-06-21 09:33:46 -06:00
# define SDL_ISPIXELFORMAT_INDEXED(format) \
( ! SDL_ISPIXELFORMAT_FOURCC ( format ) & & \
( ( SDL_PIXELTYPE ( format ) = = SDL_PIXELTYPE_INDEX1 ) | | \
2023-11-17 04:43:39 -07:00
( SDL_PIXELTYPE ( format ) = = SDL_PIXELTYPE_INDEX2 ) | | \
2015-06-21 09:33:46 -06:00
( SDL_PIXELTYPE ( format ) = = SDL_PIXELTYPE_INDEX4 ) | | \
( SDL_PIXELTYPE ( format ) = = SDL_PIXELTYPE_INDEX8 ) ) )
# define SDL_ISPIXELFORMAT_PACKED(format) \
( ! SDL_ISPIXELFORMAT_FOURCC ( format ) & & \
( ( SDL_PIXELTYPE ( format ) = = SDL_PIXELTYPE_PACKED8 ) | | \
( SDL_PIXELTYPE ( format ) = = SDL_PIXELTYPE_PACKED16 ) | | \
( SDL_PIXELTYPE ( format ) = = SDL_PIXELTYPE_PACKED32 ) ) )
# define SDL_ISPIXELFORMAT_ARRAY(format) \
( ! SDL_ISPIXELFORMAT_FOURCC ( format ) & & \
( ( SDL_PIXELTYPE ( format ) = = SDL_PIXELTYPE_ARRAYU8 ) | | \
( SDL_PIXELTYPE ( format ) = = SDL_PIXELTYPE_ARRAYU16 ) | | \
( SDL_PIXELTYPE ( format ) = = SDL_PIXELTYPE_ARRAYU32 ) | | \
( SDL_PIXELTYPE ( format ) = = SDL_PIXELTYPE_ARRAYF16 ) | | \
( SDL_PIXELTYPE ( format ) = = SDL_PIXELTYPE_ARRAYF32 ) ) )
# define SDL_ISPIXELFORMAT_ALPHA(format) \
( ( SDL_ISPIXELFORMAT_PACKED ( format ) & & \
( ( SDL_PIXELORDER ( format ) = = SDL_PACKEDORDER_ARGB ) | | \
( SDL_PIXELORDER ( format ) = = SDL_PACKEDORDER_RGBA ) | | \
( SDL_PIXELORDER ( format ) = = SDL_PACKEDORDER_ABGR ) | | \
2022-11-28 09:53:48 -07:00
( SDL_PIXELORDER ( format ) = = SDL_PACKEDORDER_BGRA ) ) ) )
2015-06-21 09:33:46 -06:00
2023-11-06 01:21:26 -07:00
# define SDL_ISPIXELFORMAT_10BIT(format) \
2024-01-29 19:32:27 -07:00
( ! SDL_ISPIXELFORMAT_FOURCC ( format ) & & \
( ( SDL_PIXELTYPE ( format ) = = SDL_PIXELTYPE_PACKED32 ) & & \
( SDL_PIXELLAYOUT ( format ) = = SDL_PACKEDLAYOUT_2101010 ) ) )
# define SDL_ISPIXELFORMAT_FLOAT(format) \
( ! SDL_ISPIXELFORMAT_FOURCC ( format ) & & \
( ( SDL_PIXELTYPE ( format ) = = SDL_PIXELTYPE_ARRAYF16 ) | | \
( SDL_PIXELTYPE ( format ) = = SDL_PIXELTYPE_ARRAYF32 ) ) )
2023-11-06 01:21:26 -07:00
2015-06-21 09:33:46 -06:00
/* The flag is set to 1 because 0x1? is not in the printable ASCII range */
# define SDL_ISPIXELFORMAT_FOURCC(format) \
( ( format ) & & ( SDL_PIXELFLAG ( format ) ! = 1 ) )
/* Note: If you modify this list, update SDL_GetPixelFormatName() */
2024-04-08 20:36:57 -06:00
typedef enum SDL_PixelFormatEnum
2015-06-21 09:33:46 -06:00
{
SDL_PIXELFORMAT_UNKNOWN ,
SDL_PIXELFORMAT_INDEX1LSB =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_INDEX1 , SDL_BITMAPORDER_4321 , 0 ,
1 , 0 ) ,
SDL_PIXELFORMAT_INDEX1MSB =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_INDEX1 , SDL_BITMAPORDER_1234 , 0 ,
1 , 0 ) ,
2023-11-17 04:43:39 -07:00
SDL_PIXELFORMAT_INDEX2LSB =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_INDEX2 , SDL_BITMAPORDER_4321 , 0 ,
2 , 0 ) ,
SDL_PIXELFORMAT_INDEX2MSB =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_INDEX2 , SDL_BITMAPORDER_1234 , 0 ,
2 , 0 ) ,
2015-06-21 09:33:46 -06:00
SDL_PIXELFORMAT_INDEX4LSB =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_INDEX4 , SDL_BITMAPORDER_4321 , 0 ,
4 , 0 ) ,
SDL_PIXELFORMAT_INDEX4MSB =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_INDEX4 , SDL_BITMAPORDER_1234 , 0 ,
4 , 0 ) ,
SDL_PIXELFORMAT_INDEX8 =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_INDEX8 , 0 , 0 , 8 , 1 ) ,
SDL_PIXELFORMAT_RGB332 =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_PACKED8 , SDL_PACKEDORDER_XRGB ,
SDL_PACKEDLAYOUT_332 , 8 , 1 ) ,
Fixed bug 4938 - Suggestion: rename SDL_PIXELFORMAT_BGR888 to SDL_PIXELFORMAT_XBGR8888
Ellie
I just tripped over this: stb_image when requesting 3 channels with 8-bit actually returns them as 3 bytes per pixel with no alignment, so basically 4 pixels are 12 bytes with no padding (0...2, 3...5, 6...8, and 9...11). This I would have naively expected to be called RGB888 or BGR888, since there is no "dead" unused byte as I would expect for something called e.g. RGBX8888.
However, SDL2's SDL_PIXELFORMAT_BGR888 uses 4 bytes, same as SDL_PIXELFORMAT_BGRX8888, even though the latter appears to be a longer storage format - which it isn't, internally. It's just swapped, in byte order X, B, G, R (instead of BGRX). So why isn't the macro name also swapped, as "XBGR888" instead of just "BGR888"?
I find the formats therefore named inconsistently, and unless there is a reason for this I suggest these changes:
1. deprecate SDL_PIXELFORMAT_BGR888 in favor of a new SDL_PIXELFORMAT_XBGR8888
and
2. deprecate SDL_PIXELFORMAT_RGB888 in favor of a new SDL_PIXELFORMAT_XRGB8888
2020-06-12 11:30:46 -06:00
SDL_PIXELFORMAT_XRGB4444 =
2015-06-21 09:33:46 -06:00
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_PACKED16 , SDL_PACKEDORDER_XRGB ,
SDL_PACKEDLAYOUT_4444 , 12 , 2 ) ,
Fixed bug 4938 - Suggestion: rename SDL_PIXELFORMAT_BGR888 to SDL_PIXELFORMAT_XBGR8888
Ellie
I just tripped over this: stb_image when requesting 3 channels with 8-bit actually returns them as 3 bytes per pixel with no alignment, so basically 4 pixels are 12 bytes with no padding (0...2, 3...5, 6...8, and 9...11). This I would have naively expected to be called RGB888 or BGR888, since there is no "dead" unused byte as I would expect for something called e.g. RGBX8888.
However, SDL2's SDL_PIXELFORMAT_BGR888 uses 4 bytes, same as SDL_PIXELFORMAT_BGRX8888, even though the latter appears to be a longer storage format - which it isn't, internally. It's just swapped, in byte order X, B, G, R (instead of BGRX). So why isn't the macro name also swapped, as "XBGR888" instead of just "BGR888"?
I find the formats therefore named inconsistently, and unless there is a reason for this I suggest these changes:
1. deprecate SDL_PIXELFORMAT_BGR888 in favor of a new SDL_PIXELFORMAT_XBGR8888
and
2. deprecate SDL_PIXELFORMAT_RGB888 in favor of a new SDL_PIXELFORMAT_XRGB8888
2020-06-12 11:30:46 -06:00
SDL_PIXELFORMAT_RGB444 = SDL_PIXELFORMAT_XRGB4444 ,
SDL_PIXELFORMAT_XBGR4444 =
2019-11-02 16:58:52 -06:00
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_PACKED16 , SDL_PACKEDORDER_XBGR ,
SDL_PACKEDLAYOUT_4444 , 12 , 2 ) ,
Fixed bug 4938 - Suggestion: rename SDL_PIXELFORMAT_BGR888 to SDL_PIXELFORMAT_XBGR8888
Ellie
I just tripped over this: stb_image when requesting 3 channels with 8-bit actually returns them as 3 bytes per pixel with no alignment, so basically 4 pixels are 12 bytes with no padding (0...2, 3...5, 6...8, and 9...11). This I would have naively expected to be called RGB888 or BGR888, since there is no "dead" unused byte as I would expect for something called e.g. RGBX8888.
However, SDL2's SDL_PIXELFORMAT_BGR888 uses 4 bytes, same as SDL_PIXELFORMAT_BGRX8888, even though the latter appears to be a longer storage format - which it isn't, internally. It's just swapped, in byte order X, B, G, R (instead of BGRX). So why isn't the macro name also swapped, as "XBGR888" instead of just "BGR888"?
I find the formats therefore named inconsistently, and unless there is a reason for this I suggest these changes:
1. deprecate SDL_PIXELFORMAT_BGR888 in favor of a new SDL_PIXELFORMAT_XBGR8888
and
2. deprecate SDL_PIXELFORMAT_RGB888 in favor of a new SDL_PIXELFORMAT_XRGB8888
2020-06-12 11:30:46 -06:00
SDL_PIXELFORMAT_BGR444 = SDL_PIXELFORMAT_XBGR4444 ,
SDL_PIXELFORMAT_XRGB1555 =
2015-06-21 09:33:46 -06:00
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_PACKED16 , SDL_PACKEDORDER_XRGB ,
SDL_PACKEDLAYOUT_1555 , 15 , 2 ) ,
Fixed bug 4938 - Suggestion: rename SDL_PIXELFORMAT_BGR888 to SDL_PIXELFORMAT_XBGR8888
Ellie
I just tripped over this: stb_image when requesting 3 channels with 8-bit actually returns them as 3 bytes per pixel with no alignment, so basically 4 pixels are 12 bytes with no padding (0...2, 3...5, 6...8, and 9...11). This I would have naively expected to be called RGB888 or BGR888, since there is no "dead" unused byte as I would expect for something called e.g. RGBX8888.
However, SDL2's SDL_PIXELFORMAT_BGR888 uses 4 bytes, same as SDL_PIXELFORMAT_BGRX8888, even though the latter appears to be a longer storage format - which it isn't, internally. It's just swapped, in byte order X, B, G, R (instead of BGRX). So why isn't the macro name also swapped, as "XBGR888" instead of just "BGR888"?
I find the formats therefore named inconsistently, and unless there is a reason for this I suggest these changes:
1. deprecate SDL_PIXELFORMAT_BGR888 in favor of a new SDL_PIXELFORMAT_XBGR8888
and
2. deprecate SDL_PIXELFORMAT_RGB888 in favor of a new SDL_PIXELFORMAT_XRGB8888
2020-06-12 11:30:46 -06:00
SDL_PIXELFORMAT_RGB555 = SDL_PIXELFORMAT_XRGB1555 ,
SDL_PIXELFORMAT_XBGR1555 =
2015-06-21 09:33:46 -06:00
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_PACKED16 , SDL_PACKEDORDER_XBGR ,
SDL_PACKEDLAYOUT_1555 , 15 , 2 ) ,
Fixed bug 4938 - Suggestion: rename SDL_PIXELFORMAT_BGR888 to SDL_PIXELFORMAT_XBGR8888
Ellie
I just tripped over this: stb_image when requesting 3 channels with 8-bit actually returns them as 3 bytes per pixel with no alignment, so basically 4 pixels are 12 bytes with no padding (0...2, 3...5, 6...8, and 9...11). This I would have naively expected to be called RGB888 or BGR888, since there is no "dead" unused byte as I would expect for something called e.g. RGBX8888.
However, SDL2's SDL_PIXELFORMAT_BGR888 uses 4 bytes, same as SDL_PIXELFORMAT_BGRX8888, even though the latter appears to be a longer storage format - which it isn't, internally. It's just swapped, in byte order X, B, G, R (instead of BGRX). So why isn't the macro name also swapped, as "XBGR888" instead of just "BGR888"?
I find the formats therefore named inconsistently, and unless there is a reason for this I suggest these changes:
1. deprecate SDL_PIXELFORMAT_BGR888 in favor of a new SDL_PIXELFORMAT_XBGR8888
and
2. deprecate SDL_PIXELFORMAT_RGB888 in favor of a new SDL_PIXELFORMAT_XRGB8888
2020-06-12 11:30:46 -06:00
SDL_PIXELFORMAT_BGR555 = SDL_PIXELFORMAT_XBGR1555 ,
2015-06-21 09:33:46 -06:00
SDL_PIXELFORMAT_ARGB4444 =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_PACKED16 , SDL_PACKEDORDER_ARGB ,
SDL_PACKEDLAYOUT_4444 , 16 , 2 ) ,
SDL_PIXELFORMAT_RGBA4444 =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_PACKED16 , SDL_PACKEDORDER_RGBA ,
SDL_PACKEDLAYOUT_4444 , 16 , 2 ) ,
SDL_PIXELFORMAT_ABGR4444 =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_PACKED16 , SDL_PACKEDORDER_ABGR ,
SDL_PACKEDLAYOUT_4444 , 16 , 2 ) ,
SDL_PIXELFORMAT_BGRA4444 =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_PACKED16 , SDL_PACKEDORDER_BGRA ,
SDL_PACKEDLAYOUT_4444 , 16 , 2 ) ,
SDL_PIXELFORMAT_ARGB1555 =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_PACKED16 , SDL_PACKEDORDER_ARGB ,
SDL_PACKEDLAYOUT_1555 , 16 , 2 ) ,
SDL_PIXELFORMAT_RGBA5551 =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_PACKED16 , SDL_PACKEDORDER_RGBA ,
SDL_PACKEDLAYOUT_5551 , 16 , 2 ) ,
SDL_PIXELFORMAT_ABGR1555 =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_PACKED16 , SDL_PACKEDORDER_ABGR ,
SDL_PACKEDLAYOUT_1555 , 16 , 2 ) ,
SDL_PIXELFORMAT_BGRA5551 =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_PACKED16 , SDL_PACKEDORDER_BGRA ,
SDL_PACKEDLAYOUT_5551 , 16 , 2 ) ,
SDL_PIXELFORMAT_RGB565 =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_PACKED16 , SDL_PACKEDORDER_XRGB ,
SDL_PACKEDLAYOUT_565 , 16 , 2 ) ,
SDL_PIXELFORMAT_BGR565 =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_PACKED16 , SDL_PACKEDORDER_XBGR ,
SDL_PACKEDLAYOUT_565 , 16 , 2 ) ,
SDL_PIXELFORMAT_RGB24 =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_ARRAYU8 , SDL_ARRAYORDER_RGB , 0 ,
24 , 3 ) ,
SDL_PIXELFORMAT_BGR24 =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_ARRAYU8 , SDL_ARRAYORDER_BGR , 0 ,
24 , 3 ) ,
Fixed bug 4938 - Suggestion: rename SDL_PIXELFORMAT_BGR888 to SDL_PIXELFORMAT_XBGR8888
Ellie
I just tripped over this: stb_image when requesting 3 channels with 8-bit actually returns them as 3 bytes per pixel with no alignment, so basically 4 pixels are 12 bytes with no padding (0...2, 3...5, 6...8, and 9...11). This I would have naively expected to be called RGB888 or BGR888, since there is no "dead" unused byte as I would expect for something called e.g. RGBX8888.
However, SDL2's SDL_PIXELFORMAT_BGR888 uses 4 bytes, same as SDL_PIXELFORMAT_BGRX8888, even though the latter appears to be a longer storage format - which it isn't, internally. It's just swapped, in byte order X, B, G, R (instead of BGRX). So why isn't the macro name also swapped, as "XBGR888" instead of just "BGR888"?
I find the formats therefore named inconsistently, and unless there is a reason for this I suggest these changes:
1. deprecate SDL_PIXELFORMAT_BGR888 in favor of a new SDL_PIXELFORMAT_XBGR8888
and
2. deprecate SDL_PIXELFORMAT_RGB888 in favor of a new SDL_PIXELFORMAT_XRGB8888
2020-06-12 11:30:46 -06:00
SDL_PIXELFORMAT_XRGB8888 =
2015-06-21 09:33:46 -06:00
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_PACKED32 , SDL_PACKEDORDER_XRGB ,
SDL_PACKEDLAYOUT_8888 , 24 , 4 ) ,
SDL_PIXELFORMAT_RGBX8888 =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_PACKED32 , SDL_PACKEDORDER_RGBX ,
SDL_PACKEDLAYOUT_8888 , 24 , 4 ) ,
Fixed bug 4938 - Suggestion: rename SDL_PIXELFORMAT_BGR888 to SDL_PIXELFORMAT_XBGR8888
Ellie
I just tripped over this: stb_image when requesting 3 channels with 8-bit actually returns them as 3 bytes per pixel with no alignment, so basically 4 pixels are 12 bytes with no padding (0...2, 3...5, 6...8, and 9...11). This I would have naively expected to be called RGB888 or BGR888, since there is no "dead" unused byte as I would expect for something called e.g. RGBX8888.
However, SDL2's SDL_PIXELFORMAT_BGR888 uses 4 bytes, same as SDL_PIXELFORMAT_BGRX8888, even though the latter appears to be a longer storage format - which it isn't, internally. It's just swapped, in byte order X, B, G, R (instead of BGRX). So why isn't the macro name also swapped, as "XBGR888" instead of just "BGR888"?
I find the formats therefore named inconsistently, and unless there is a reason for this I suggest these changes:
1. deprecate SDL_PIXELFORMAT_BGR888 in favor of a new SDL_PIXELFORMAT_XBGR8888
and
2. deprecate SDL_PIXELFORMAT_RGB888 in favor of a new SDL_PIXELFORMAT_XRGB8888
2020-06-12 11:30:46 -06:00
SDL_PIXELFORMAT_XBGR8888 =
2015-06-21 09:33:46 -06:00
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_PACKED32 , SDL_PACKEDORDER_XBGR ,
SDL_PACKEDLAYOUT_8888 , 24 , 4 ) ,
SDL_PIXELFORMAT_BGRX8888 =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_PACKED32 , SDL_PACKEDORDER_BGRX ,
SDL_PACKEDLAYOUT_8888 , 24 , 4 ) ,
SDL_PIXELFORMAT_ARGB8888 =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_PACKED32 , SDL_PACKEDORDER_ARGB ,
SDL_PACKEDLAYOUT_8888 , 32 , 4 ) ,
SDL_PIXELFORMAT_RGBA8888 =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_PACKED32 , SDL_PACKEDORDER_RGBA ,
SDL_PACKEDLAYOUT_8888 , 32 , 4 ) ,
SDL_PIXELFORMAT_ABGR8888 =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_PACKED32 , SDL_PACKEDORDER_ABGR ,
SDL_PACKEDLAYOUT_8888 , 32 , 4 ) ,
SDL_PIXELFORMAT_BGRA8888 =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_PACKED32 , SDL_PACKEDORDER_BGRA ,
SDL_PACKEDLAYOUT_8888 , 32 , 4 ) ,
2023-11-06 01:21:26 -07:00
SDL_PIXELFORMAT_XRGB2101010 =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_PACKED32 , SDL_PACKEDORDER_XRGB ,
SDL_PACKEDLAYOUT_2101010 , 32 , 4 ) ,
SDL_PIXELFORMAT_XBGR2101010 =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_PACKED32 , SDL_PACKEDORDER_XBGR ,
SDL_PACKEDLAYOUT_2101010 , 32 , 4 ) ,
2015-06-21 09:33:46 -06:00
SDL_PIXELFORMAT_ARGB2101010 =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_PACKED32 , SDL_PACKEDORDER_ARGB ,
SDL_PACKEDLAYOUT_2101010 , 32 , 4 ) ,
2023-11-06 01:21:26 -07:00
SDL_PIXELFORMAT_ABGR2101010 =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_PACKED32 , SDL_PACKEDORDER_ABGR ,
SDL_PACKEDLAYOUT_2101010 , 32 , 4 ) ,
2024-01-25 17:51:22 -07:00
SDL_PIXELFORMAT_RGB48 =
2024-01-25 17:39:53 -07:00
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_ARRAYU16 , SDL_ARRAYORDER_RGB , 0 ,
2024-01-31 00:15:20 -07:00
48 , 6 ) ,
2024-01-25 17:51:22 -07:00
SDL_PIXELFORMAT_BGR48 =
2024-01-25 17:39:53 -07:00
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_ARRAYU16 , SDL_ARRAYORDER_BGR , 0 ,
2024-01-31 00:15:20 -07:00
48 , 6 ) ,
2024-01-25 17:51:22 -07:00
SDL_PIXELFORMAT_RGBA64 =
2024-01-25 17:39:53 -07:00
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_ARRAYU16 , SDL_ARRAYORDER_RGBA , 0 ,
2024-01-31 00:15:20 -07:00
64 , 8 ) ,
2024-01-25 17:51:22 -07:00
SDL_PIXELFORMAT_ARGB64 =
2024-01-25 17:39:53 -07:00
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_ARRAYU16 , SDL_ARRAYORDER_ARGB , 0 ,
2024-01-31 00:15:20 -07:00
64 , 8 ) ,
2024-01-25 17:51:22 -07:00
SDL_PIXELFORMAT_BGRA64 =
2024-01-25 17:39:53 -07:00
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_ARRAYU16 , SDL_ARRAYORDER_BGRA , 0 ,
2024-01-31 00:15:20 -07:00
64 , 8 ) ,
2024-01-25 17:51:22 -07:00
SDL_PIXELFORMAT_ABGR64 =
2024-01-25 17:39:53 -07:00
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_ARRAYU16 , SDL_ARRAYORDER_ABGR , 0 ,
2024-01-31 00:15:20 -07:00
64 , 8 ) ,
2024-01-25 17:53:19 -07:00
SDL_PIXELFORMAT_RGB48_FLOAT =
2024-01-25 17:39:53 -07:00
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_ARRAYF16 , SDL_ARRAYORDER_RGB , 0 ,
2024-01-31 00:15:20 -07:00
48 , 6 ) ,
2024-01-25 17:51:22 -07:00
SDL_PIXELFORMAT_BGR48_FLOAT =
2024-01-25 17:39:53 -07:00
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_ARRAYF16 , SDL_ARRAYORDER_BGR , 0 ,
2024-01-31 00:15:20 -07:00
48 , 6 ) ,
2024-01-25 17:51:22 -07:00
SDL_PIXELFORMAT_RGBA64_FLOAT =
2024-01-25 17:39:53 -07:00
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_ARRAYF16 , SDL_ARRAYORDER_RGBA , 0 ,
2024-01-31 00:15:20 -07:00
64 , 8 ) ,
2024-01-25 17:51:22 -07:00
SDL_PIXELFORMAT_ARGB64_FLOAT =
2024-01-25 17:39:53 -07:00
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_ARRAYF16 , SDL_ARRAYORDER_ARGB , 0 ,
2024-01-31 00:15:20 -07:00
64 , 8 ) ,
2024-01-25 17:51:22 -07:00
SDL_PIXELFORMAT_BGRA64_FLOAT =
2024-01-25 17:39:53 -07:00
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_ARRAYF16 , SDL_ARRAYORDER_BGRA , 0 ,
2024-01-31 00:15:20 -07:00
64 , 8 ) ,
2024-01-25 17:51:22 -07:00
SDL_PIXELFORMAT_ABGR64_FLOAT =
2024-01-25 17:39:53 -07:00
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_ARRAYF16 , SDL_ARRAYORDER_ABGR , 0 ,
2024-01-31 00:15:20 -07:00
64 , 8 ) ,
2024-01-29 14:28:33 -07:00
SDL_PIXELFORMAT_RGB96_FLOAT =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_ARRAYF32 , SDL_ARRAYORDER_RGB , 0 ,
2024-01-31 00:15:20 -07:00
96 , 12 ) ,
2024-01-29 14:28:33 -07:00
SDL_PIXELFORMAT_BGR96_FLOAT =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_ARRAYF32 , SDL_ARRAYORDER_BGR , 0 ,
2024-01-31 00:15:20 -07:00
96 , 12 ) ,
2024-01-29 14:28:33 -07:00
SDL_PIXELFORMAT_RGBA128_FLOAT =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_ARRAYF32 , SDL_ARRAYORDER_RGBA , 0 ,
2024-01-31 00:15:20 -07:00
128 , 16 ) ,
2024-01-29 14:28:33 -07:00
SDL_PIXELFORMAT_ARGB128_FLOAT =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_ARRAYF32 , SDL_ARRAYORDER_ARGB , 0 ,
2024-01-31 00:15:20 -07:00
128 , 16 ) ,
2024-01-29 14:28:33 -07:00
SDL_PIXELFORMAT_BGRA128_FLOAT =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_ARRAYF32 , SDL_ARRAYORDER_BGRA , 0 ,
2024-01-31 00:15:20 -07:00
128 , 16 ) ,
2024-01-29 14:28:33 -07:00
SDL_PIXELFORMAT_ABGR128_FLOAT =
SDL_DEFINE_PIXELFORMAT ( SDL_PIXELTYPE_ARRAYF32 , SDL_ARRAYORDER_ABGR , 0 ,
2024-01-31 00:15:20 -07:00
128 , 16 ) ,
2015-06-21 09:33:46 -06:00
2016-10-12 00:21:41 -06:00
/* Aliases for RGBA byte arrays of color data, for the current platform */
2016-10-12 00:19:05 -06:00
# if SDL_BYTEORDER == SDL_BIG_ENDIAN
2016-10-12 00:21:41 -06:00
SDL_PIXELFORMAT_RGBA32 = SDL_PIXELFORMAT_RGBA8888 ,
2016-10-12 00:19:05 -06:00
SDL_PIXELFORMAT_ARGB32 = SDL_PIXELFORMAT_ARGB8888 ,
SDL_PIXELFORMAT_BGRA32 = SDL_PIXELFORMAT_BGRA8888 ,
SDL_PIXELFORMAT_ABGR32 = SDL_PIXELFORMAT_ABGR8888 ,
2023-07-25 22:54:56 -06:00
SDL_PIXELFORMAT_RGBX32 = SDL_PIXELFORMAT_RGBX8888 ,
SDL_PIXELFORMAT_XRGB32 = SDL_PIXELFORMAT_XRGB8888 ,
SDL_PIXELFORMAT_BGRX32 = SDL_PIXELFORMAT_BGRX8888 ,
SDL_PIXELFORMAT_XBGR32 = SDL_PIXELFORMAT_XBGR8888 ,
2016-10-12 00:19:05 -06:00
# else
SDL_PIXELFORMAT_RGBA32 = SDL_PIXELFORMAT_ABGR8888 ,
SDL_PIXELFORMAT_ARGB32 = SDL_PIXELFORMAT_BGRA8888 ,
SDL_PIXELFORMAT_BGRA32 = SDL_PIXELFORMAT_ARGB8888 ,
SDL_PIXELFORMAT_ABGR32 = SDL_PIXELFORMAT_RGBA8888 ,
2023-07-25 22:54:56 -06:00
SDL_PIXELFORMAT_RGBX32 = SDL_PIXELFORMAT_XBGR8888 ,
SDL_PIXELFORMAT_XRGB32 = SDL_PIXELFORMAT_BGRX8888 ,
SDL_PIXELFORMAT_BGRX32 = SDL_PIXELFORMAT_XRGB8888 ,
SDL_PIXELFORMAT_XBGR32 = SDL_PIXELFORMAT_RGBX8888 ,
2016-10-12 00:19:05 -06:00
# endif
2015-06-21 09:33:46 -06:00
SDL_PIXELFORMAT_YV12 = /**< Planar mode: Y + V + U (3 planes) */
SDL_DEFINE_PIXELFOURCC ( ' Y ' , ' V ' , ' 1 ' , ' 2 ' ) ,
SDL_PIXELFORMAT_IYUV = /**< Planar mode: Y + U + V (3 planes) */
SDL_DEFINE_PIXELFOURCC ( ' I ' , ' Y ' , ' U ' , ' V ' ) ,
SDL_PIXELFORMAT_YUY2 = /**< Packed mode: Y0+U0+Y1+V0 (1 plane) */
SDL_DEFINE_PIXELFOURCC ( ' Y ' , ' U ' , ' Y ' , ' 2 ' ) ,
SDL_PIXELFORMAT_UYVY = /**< Packed mode: U0+Y0+V0+Y1 (1 plane) */
SDL_DEFINE_PIXELFOURCC ( ' U ' , ' Y ' , ' V ' , ' Y ' ) ,
SDL_PIXELFORMAT_YVYU = /**< Packed mode: Y0+V0+Y1+U0 (1 plane) */
SDL_DEFINE_PIXELFOURCC ( ' Y ' , ' V ' , ' Y ' , ' U ' ) ,
SDL_PIXELFORMAT_NV12 = /**< Planar mode: Y + U/V interleaved (2 planes) */
SDL_DEFINE_PIXELFOURCC ( ' N ' , ' V ' , ' 1 ' , ' 2 ' ) ,
SDL_PIXELFORMAT_NV21 = /**< Planar mode: Y + V/U interleaved (2 planes) */
2017-12-12 13:52:17 -07:00
SDL_DEFINE_PIXELFOURCC ( ' N ' , ' V ' , ' 2 ' , ' 1 ' ) ,
2024-02-04 23:19:28 -07:00
SDL_PIXELFORMAT_P010 = /**< Planar mode: Y + U/V interleaved (2 planes) */
SDL_DEFINE_PIXELFOURCC ( ' P ' , ' 0 ' , ' 1 ' , ' 0 ' ) ,
2017-12-12 13:52:17 -07:00
SDL_PIXELFORMAT_EXTERNAL_OES = /**< Android video texture format */
SDL_DEFINE_PIXELFOURCC ( ' O ' , ' E ' , ' S ' , ' ' )
2018-11-12 20:23:49 -07:00
} SDL_PixelFormatEnum ;
2015-06-21 09:33:46 -06:00
2024-01-28 18:17:38 -07:00
/**
* Pixels are a representation of a color in a particular color space .
*
* 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 .
*
* RGB colors consist of red , green , and blue channels of color that are added together to represent the colors we see on the screen .
* https : //en.wikipedia.org/wiki/RGB_color_model
*
* 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 .
* https : //en.wikipedia.org/wiki/YCbCr
*
* 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 .
*
* 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 .
*
* The color primaries and white point are a definition of the colors in the color space relative to the standard XYZ color space .
* https : //en.wikipedia.org/wiki/CIE_1931_color_space
*
* 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 .
* https : //en.wikipedia.org/wiki/Rec._709#Transfer_characteristics
*
* The matrix coefficients are used to convert between YCbCr and RGB colors .
*/
/**
* The color type
*/
2024-04-08 20:36:57 -06:00
typedef enum SDL_ColorType
2024-01-28 18:17:38 -07:00
{
SDL_COLOR_TYPE_UNKNOWN = 0 ,
SDL_COLOR_TYPE_RGB = 1 ,
SDL_COLOR_TYPE_YCBCR = 2
} SDL_ColorType ;
/**
2024-04-08 22:49:23 -06:00
* The color range , as described by
* https : //www.itu.int/rec/R-REC-BT.2100-2-201807-I/en
2024-01-28 18:17:38 -07:00
*/
2024-04-08 20:36:57 -06:00
typedef enum SDL_ColorRange
2024-01-28 18:17:38 -07:00
{
SDL_COLOR_RANGE_UNKNOWN = 0 ,
SDL_COLOR_RANGE_LIMITED = 1 , /**< Narrow range, e.g. 16-235 for 8-bit RGB and luma, and 16-240 for 8-bit chroma */
SDL_COLOR_RANGE_FULL = 2 /**< Full range, e.g. 0-255 for 8-bit RGB and luma, and 1-255 for 8-bit chroma */
} SDL_ColorRange ;
/**
2024-04-08 22:49:23 -06:00
* The color primaries , as described by
* https : //www.itu.int/rec/T-REC-H.273-201612-S/en
2024-01-28 18:17:38 -07:00
*/
2024-04-08 20:36:57 -06:00
typedef enum SDL_ColorPrimaries
2024-01-28 18:17:38 -07:00
{
SDL_COLOR_PRIMARIES_UNKNOWN = 0 ,
2024-03-05 17:47:36 -07:00
SDL_COLOR_PRIMARIES_BT709 = 1 , /**< ITU-R BT.709-6 */
2024-01-28 18:17:38 -07:00
SDL_COLOR_PRIMARIES_UNSPECIFIED = 2 ,
2024-03-05 17:47:36 -07:00
SDL_COLOR_PRIMARIES_BT470M = 4 , /**< ITU-R BT.470-6 System M */
SDL_COLOR_PRIMARIES_BT470BG = 5 , /**< ITU-R BT.470-6 System B, G / ITU-R BT.601-7 625 */
SDL_COLOR_PRIMARIES_BT601 = 6 , /**< ITU-R BT.601-7 525 */
SDL_COLOR_PRIMARIES_SMPTE240 = 7 , /**< SMPTE 240M, functionally the same as SDL_COLOR_PRIMARIES_BT601 */
SDL_COLOR_PRIMARIES_GENERIC_FILM = 8 , /**< Generic film (color filters using Illuminant C) */
SDL_COLOR_PRIMARIES_BT2020 = 9 , /**< ITU-R BT.2020-2 / ITU-R BT.2100-0 */
SDL_COLOR_PRIMARIES_XYZ = 10 , /**< SMPTE ST 428-1 */
SDL_COLOR_PRIMARIES_SMPTE431 = 11 , /**< SMPTE RP 431-2 */
SDL_COLOR_PRIMARIES_SMPTE432 = 12 , /**< SMPTE EG 432-1 / DCI P3 */
SDL_COLOR_PRIMARIES_EBU3213 = 22 , /**< EBU Tech. 3213-E */
2024-01-28 18:17:38 -07:00
SDL_COLOR_PRIMARIES_CUSTOM = 31
} SDL_ColorPrimaries ;
/**
2024-04-08 22:49:23 -06:00
* The transfer characteristics , as described by
* https : //www.itu.int/rec/T-REC-H.273-201612-S/en
2024-01-28 18:17:38 -07:00
*/
2024-04-08 20:36:57 -06:00
typedef enum SDL_TransferCharacteristics
2024-01-28 18:17:38 -07:00
{
SDL_TRANSFER_CHARACTERISTICS_UNKNOWN = 0 ,
2024-03-05 17:47:36 -07:00
SDL_TRANSFER_CHARACTERISTICS_BT709 = 1 , /**< Rec. ITU-R BT.709-6 / ITU-R BT1361 */
2024-01-28 18:17:38 -07:00
SDL_TRANSFER_CHARACTERISTICS_UNSPECIFIED = 2 ,
2024-03-05 17:47:36 -07:00
SDL_TRANSFER_CHARACTERISTICS_GAMMA22 = 4 , /**< ITU-R BT.470-6 System M / ITU-R BT1700 625 PAL & SECAM */
SDL_TRANSFER_CHARACTERISTICS_GAMMA28 = 5 , /**< ITU-R BT.470-6 System B, G */
SDL_TRANSFER_CHARACTERISTICS_BT601 = 6 , /**< SMPTE ST 170M / ITU-R BT.601-7 525 or 625 */
2024-01-28 18:17:38 -07:00
SDL_TRANSFER_CHARACTERISTICS_SMPTE240 = 7 , /**< SMPTE ST 240M */
SDL_TRANSFER_CHARACTERISTICS_LINEAR = 8 ,
SDL_TRANSFER_CHARACTERISTICS_LOG100 = 9 ,
SDL_TRANSFER_CHARACTERISTICS_LOG100_SQRT10 = 10 ,
SDL_TRANSFER_CHARACTERISTICS_IEC61966 = 11 , /**< IEC 61966-2-4 */
SDL_TRANSFER_CHARACTERISTICS_BT1361 = 12 , /**< ITU-R BT1361 Extended Colour Gamut */
SDL_TRANSFER_CHARACTERISTICS_SRGB = 13 , /**< IEC 61966-2-1 (sRGB or sYCC) */
SDL_TRANSFER_CHARACTERISTICS_BT2020_10BIT = 14 , /**< ITU-R BT2020 for 10-bit system */
SDL_TRANSFER_CHARACTERISTICS_BT2020_12BIT = 15 , /**< ITU-R BT2020 for 12-bit system */
SDL_TRANSFER_CHARACTERISTICS_PQ = 16 , /**< SMPTE ST 2084 for 10-, 12-, 14- and 16-bit systems */
SDL_TRANSFER_CHARACTERISTICS_SMPTE428 = 17 , /**< SMPTE ST 428-1 */
2024-03-05 17:47:36 -07:00
SDL_TRANSFER_CHARACTERISTICS_HLG = 18 , /**< ARIB STD-B67, known as "hybrid log-gamma" (HLG) */
2024-01-29 19:48:41 -07:00
SDL_TRANSFER_CHARACTERISTICS_CUSTOM = 31
2024-01-28 18:17:38 -07:00
} SDL_TransferCharacteristics ;
/**
2024-04-08 22:49:23 -06:00
* The matrix coefficients , as described by
* https : //www.itu.int/rec/T-REC-H.273-201612-S/en
2024-01-28 18:17:38 -07:00
*/
2024-04-08 20:36:57 -06:00
typedef enum SDL_MatrixCoefficients
2024-01-28 18:17:38 -07:00
{
SDL_MATRIX_COEFFICIENTS_IDENTITY = 0 ,
2024-03-05 17:47:36 -07:00
SDL_MATRIX_COEFFICIENTS_BT709 = 1 , /**< ITU-R BT.709-6 */
2024-01-28 18:17:38 -07:00
SDL_MATRIX_COEFFICIENTS_UNSPECIFIED = 2 ,
2024-03-05 17:47:36 -07:00
SDL_MATRIX_COEFFICIENTS_FCC = 4 , /**< US FCC */
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 */
SDL_MATRIX_COEFFICIENTS_BT601 = 6 , /**< ITU-R BT.601-7 525 */
SDL_MATRIX_COEFFICIENTS_SMPTE240 = 7 , /**< SMPTE 240M */
2024-01-28 18:17:38 -07:00
SDL_MATRIX_COEFFICIENTS_YCGCO = 8 ,
2024-03-05 17:47:36 -07:00
SDL_MATRIX_COEFFICIENTS_BT2020_NCL = 9 , /**< ITU-R BT.2020-2 non-constant luminance */
SDL_MATRIX_COEFFICIENTS_BT2020_CL = 10 , /**< ITU-R BT.2020-2 constant luminance */
SDL_MATRIX_COEFFICIENTS_SMPTE2085 = 11 , /**< SMPTE ST 2085 */
2024-01-28 18:17:38 -07:00
SDL_MATRIX_COEFFICIENTS_CHROMA_DERIVED_NCL = 12 ,
SDL_MATRIX_COEFFICIENTS_CHROMA_DERIVED_CL = 13 ,
2024-03-05 17:47:36 -07:00
SDL_MATRIX_COEFFICIENTS_ICTCP = 14 , /**< ITU-R BT.2100-0 ICTCP */
2024-01-28 18:17:38 -07:00
SDL_MATRIX_COEFFICIENTS_CUSTOM = 31
} SDL_MatrixCoefficients ;
/**
* The chroma sample location
*/
2024-04-08 20:36:57 -06:00
typedef enum SDL_ChromaLocation
2024-01-28 18:17:38 -07:00
{
SDL_CHROMA_LOCATION_NONE = 0 , /**< RGB, no chroma sampling */
2024-03-22 10:04:09 -06:00
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. */
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. */
2024-01-28 18:17:38 -07:00
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"). */
} SDL_ChromaLocation ;
/* Colorspace definition */
# define SDL_DEFINE_COLORSPACE(type, range, primaries, transfer, matrix, chroma) \
( ( ( Uint32 ) ( type ) < < 28 ) | ( ( Uint32 ) ( range ) < < 24 ) | ( ( Uint32 ) ( chroma ) < < 20 ) | \
( ( Uint32 ) ( primaries ) < < 10 ) | ( ( Uint32 ) ( transfer ) < < 5 ) | ( ( Uint32 ) ( matrix ) < < 0 ) )
# define SDL_COLORSPACETYPE(X) (SDL_ColorType)(((X) >> 28) & 0x0F)
# define SDL_COLORSPACERANGE(X) (SDL_ColorRange)(((X) >> 24) & 0x0F)
# define SDL_COLORSPACECHROMA(X) (SDL_ChromaLocation)(((X) >> 20) & 0x0F)
# define SDL_COLORSPACEPRIMARIES(X) (SDL_ColorPrimaries)(((X) >> 10) & 0x1F)
# define SDL_COLORSPACETRANSFER(X) (SDL_TransferCharacteristics)(((X) >> 5) & 0x1F)
# define SDL_COLORSPACEMATRIX(X) (SDL_MatrixCoefficients)((X) & 0x1F)
2024-03-05 17:47:36 -07:00
# define SDL_ISCOLORSPACE_MATRIX_BT601(X) (SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT601 || SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT470BG)
# define SDL_ISCOLORSPACE_MATRIX_BT709(X) (SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT709)
# define SDL_ISCOLORSPACE_MATRIX_BT2020_NCL(X) (SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT2020_NCL)
# define SDL_ISCOLORSPACE_LIMITED_RANGE(X) (SDL_COLORSPACERANGE(X) != SDL_COLOR_RANGE_FULL)
# define SDL_ISCOLORSPACE_FULL_RANGE(X) (SDL_COLORSPACERANGE(X) == SDL_COLOR_RANGE_FULL)
2024-02-03 08:05:32 -07:00
2024-04-08 20:36:57 -06:00
typedef enum SDL_Colorspace
2024-01-28 18:17:38 -07:00
{
SDL_COLORSPACE_UNKNOWN ,
2024-02-02 13:09:37 -07:00
/* sRGB is a gamma corrected colorspace, and the default colorspace for SDL rendering and 8-bit RGB surfaces */
2024-01-28 18:17:38 -07:00
SDL_COLORSPACE_SRGB = /**< Equivalent to DXGI_COLOR_SPACE_RGB_FULL_G22_NONE_P709 */
SDL_DEFINE_COLORSPACE ( SDL_COLOR_TYPE_RGB ,
SDL_COLOR_RANGE_FULL ,
SDL_COLOR_PRIMARIES_BT709 ,
SDL_TRANSFER_CHARACTERISTICS_SRGB ,
2024-02-19 09:45:02 -07:00
SDL_MATRIX_COEFFICIENTS_IDENTITY ,
2024-01-28 18:17:38 -07:00
SDL_CHROMA_LOCATION_NONE ) ,
2024-02-02 13:09:37 -07:00
2024-02-19 09:45:02 -07:00
/* 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 */
SDL_COLORSPACE_SRGB_LINEAR = /**< Equivalent to DXGI_COLOR_SPACE_RGB_FULL_G10_NONE_P709 */
2024-01-28 18:17:38 -07:00
SDL_DEFINE_COLORSPACE ( SDL_COLOR_TYPE_RGB ,
SDL_COLOR_RANGE_FULL ,
SDL_COLOR_PRIMARIES_BT709 ,
SDL_TRANSFER_CHARACTERISTICS_LINEAR ,
2024-02-19 09:45:02 -07:00
SDL_MATRIX_COEFFICIENTS_IDENTITY ,
2024-01-28 18:17:38 -07:00
SDL_CHROMA_LOCATION_NONE ) ,
2024-02-02 13:09:37 -07:00
/* HDR10 is a non-linear HDR colorspace and the default colorspace for 10-bit surfaces */
2024-01-28 18:17:38 -07:00
SDL_COLORSPACE_HDR10 = /**< Equivalent to DXGI_COLOR_SPACE_RGB_FULL_G2084_NONE_P2020 */
SDL_DEFINE_COLORSPACE ( SDL_COLOR_TYPE_RGB ,
SDL_COLOR_RANGE_FULL ,
SDL_COLOR_PRIMARIES_BT2020 ,
SDL_TRANSFER_CHARACTERISTICS_PQ ,
2024-02-19 09:45:02 -07:00
SDL_MATRIX_COEFFICIENTS_IDENTITY ,
2024-01-28 18:17:38 -07:00
SDL_CHROMA_LOCATION_NONE ) ,
2024-02-02 13:09:37 -07:00
2024-02-04 01:11:46 -07:00
SDL_COLORSPACE_JPEG = /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_FULL_G22_NONE_P709_X601 */
SDL_DEFINE_COLORSPACE ( SDL_COLOR_TYPE_YCBCR ,
SDL_COLOR_RANGE_FULL ,
SDL_COLOR_PRIMARIES_BT709 ,
SDL_TRANSFER_CHARACTERISTICS_BT601 ,
SDL_MATRIX_COEFFICIENTS_BT601 ,
SDL_CHROMA_LOCATION_NONE ) ,
2024-01-28 18:17:38 -07:00
SDL_COLORSPACE_BT601_LIMITED = /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P601 */
SDL_DEFINE_COLORSPACE ( SDL_COLOR_TYPE_YCBCR ,
SDL_COLOR_RANGE_LIMITED ,
SDL_COLOR_PRIMARIES_BT601 ,
SDL_TRANSFER_CHARACTERISTICS_BT601 ,
SDL_MATRIX_COEFFICIENTS_BT601 ,
SDL_CHROMA_LOCATION_LEFT ) ,
2024-02-02 13:09:37 -07:00
2024-01-28 18:17:38 -07:00
SDL_COLORSPACE_BT601_FULL = /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P601 */
SDL_DEFINE_COLORSPACE ( SDL_COLOR_TYPE_YCBCR ,
2024-01-30 11:59:15 -07:00
SDL_COLOR_RANGE_FULL ,
2024-01-28 18:17:38 -07:00
SDL_COLOR_PRIMARIES_BT601 ,
SDL_TRANSFER_CHARACTERISTICS_BT601 ,
SDL_MATRIX_COEFFICIENTS_BT601 ,
SDL_CHROMA_LOCATION_LEFT ) ,
2024-02-02 13:09:37 -07:00
2024-01-28 18:17:38 -07:00
SDL_COLORSPACE_BT709_LIMITED = /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P709 */
SDL_DEFINE_COLORSPACE ( SDL_COLOR_TYPE_YCBCR ,
SDL_COLOR_RANGE_LIMITED ,
SDL_COLOR_PRIMARIES_BT709 ,
SDL_TRANSFER_CHARACTERISTICS_BT709 ,
SDL_MATRIX_COEFFICIENTS_BT709 ,
SDL_CHROMA_LOCATION_LEFT ) ,
2024-02-02 13:09:37 -07:00
2024-01-28 18:17:38 -07:00
SDL_COLORSPACE_BT709_FULL = /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P709 */
SDL_DEFINE_COLORSPACE ( SDL_COLOR_TYPE_YCBCR ,
2024-01-30 11:59:15 -07:00
SDL_COLOR_RANGE_FULL ,
2024-01-28 18:17:38 -07:00
SDL_COLOR_PRIMARIES_BT709 ,
SDL_TRANSFER_CHARACTERISTICS_BT709 ,
SDL_MATRIX_COEFFICIENTS_BT709 ,
SDL_CHROMA_LOCATION_LEFT ) ,
2024-02-04 23:19:28 -07:00
SDL_COLORSPACE_BT2020_LIMITED = /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P2020 */
SDL_DEFINE_COLORSPACE ( SDL_COLOR_TYPE_YCBCR ,
SDL_COLOR_RANGE_LIMITED ,
SDL_COLOR_PRIMARIES_BT2020 ,
SDL_TRANSFER_CHARACTERISTICS_PQ ,
SDL_MATRIX_COEFFICIENTS_BT2020_NCL ,
SDL_CHROMA_LOCATION_LEFT ) ,
SDL_COLORSPACE_BT2020_FULL = /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_FULL_G22_LEFT_P2020 */
SDL_DEFINE_COLORSPACE ( SDL_COLOR_TYPE_YCBCR ,
SDL_COLOR_RANGE_FULL ,
SDL_COLOR_PRIMARIES_BT2020 ,
SDL_TRANSFER_CHARACTERISTICS_PQ ,
SDL_MATRIX_COEFFICIENTS_BT2020_NCL ,
SDL_CHROMA_LOCATION_LEFT ) ,
2024-01-28 18:17:38 -07:00
/* The default colorspace for RGB surfaces if no colorspace is specified */
SDL_COLORSPACE_RGB_DEFAULT = SDL_COLORSPACE_SRGB ,
2024-02-03 08:05:32 -07:00
/* The default colorspace for YUV surfaces if no colorspace is specified */
2024-02-04 01:11:46 -07:00
SDL_COLORSPACE_YUV_DEFAULT = SDL_COLORSPACE_JPEG ,
2024-02-03 08:05:32 -07:00
2024-01-28 18:17:38 -07:00
} SDL_Colorspace ;
2021-12-14 11:24:59 -07:00
/**
2024-04-08 20:36:57 -06:00
* A structure that represents a color as RGBA components .
*
2024-04-08 22:49:23 -06:00
* The bits of this structure can be directly reinterpreted as an
* integer - packed color which uses the SDL_PIXELFORMAT_RGBA32 format
* ( SDL_PIXELFORMAT_ABGR8888 on little - endian systems and
* SDL_PIXELFORMAT_RGBA8888 on big - endian systems ) .
2024-04-08 20:36:57 -06:00
*
* \ since This struct is available since SDL 3.0 .0 .
2021-12-14 11:24:59 -07:00
*/
2015-06-21 09:33:46 -06:00
typedef struct SDL_Color
{
Uint8 r ;
Uint8 g ;
Uint8 b ;
Uint8 a ;
} SDL_Color ;
2024-01-29 14:28:33 -07:00
/**
* The bits of this structure can be directly reinterpreted as a float - packed
* color which uses the SDL_PIXELFORMAT_RGBA128_FLOAT format
2024-04-08 20:36:57 -06:00
*
* \ since This struct is available since SDL 3.0 .0 .
2024-01-29 14:28:33 -07:00
*/
typedef struct SDL_FColor
{
float r ;
float g ;
float b ;
float a ;
} SDL_FColor ;
2024-04-08 20:36:57 -06:00
/**
* A set of indexed colors representing a palette .
*
* \ since This struct is available since SDL 3.0 .0 .
*
* \ sa SDL_PixelFormat
* \ sa SDL_SetPaletteColors
*/
2015-06-21 09:33:46 -06:00
typedef struct SDL_Palette
{
2024-04-09 13:23:31 -06:00
int ncolors ; /**< number of elements in `colors`. */
SDL_Color * colors ; /**< an array of colors, `ncolors` long. */
Uint32 version ; /**< internal use only, do not touch. */
int refcount ; /**< internal use only, do not touch. */
2015-06-21 09:33:46 -06:00
} SDL_Palette ;
/**
2024-04-08 20:36:57 -06:00
* Details about the format of a pixel .
*
2024-04-08 22:49:23 -06:00
* Generally this is used with SDL_Surface , and covers many possible
* configurations , including paletted data and various bit patterns .
2024-04-08 20:36:57 -06:00
*
* \ since This struct is available since SDL 3.0 .0 .
2015-06-21 09:33:46 -06:00
*/
typedef struct SDL_PixelFormat
{
2024-03-06 11:59:05 -07:00
SDL_PixelFormatEnum format ;
2015-06-21 09:33:46 -06:00
SDL_Palette * palette ;
2024-02-11 09:03:26 -07:00
Uint8 bits_per_pixel ;
Uint8 bytes_per_pixel ;
2015-06-21 09:33:46 -06:00
Uint8 padding [ 2 ] ;
Uint32 Rmask ;
Uint32 Gmask ;
Uint32 Bmask ;
Uint32 Amask ;
Uint8 Rloss ;
Uint8 Gloss ;
Uint8 Bloss ;
Uint8 Aloss ;
Uint8 Rshift ;
Uint8 Gshift ;
Uint8 Bshift ;
Uint8 Ashift ;
int refcount ;
struct SDL_PixelFormat * next ;
} SDL_PixelFormat ;
/**
2021-03-21 12:18:39 -06:00
* Get the human readable name of a pixel format .
*
* \ param format the pixel format to query
* \ returns the human readable name of the specified pixel format or
* ` SDL_PIXELFORMAT_UNKNOWN ` if the format isn ' t recognized .
*
2022-11-22 15:40:14 -07:00
* \ since This function is available since SDL 3.0 .0 .
2015-06-21 09:33:46 -06:00
*/
2024-03-06 11:59:05 -07:00
extern DECLSPEC const char * SDLCALL SDL_GetPixelFormatName ( SDL_PixelFormatEnum format ) ;
2015-06-21 09:33:46 -06:00
/**
2021-03-21 12:18:39 -06:00
* Convert one of the enumerated pixel formats to a bpp value and RGBA masks .
2015-06-21 09:33:46 -06:00
*
2021-03-21 12:18:39 -06:00
* \ param format one of the SDL_PixelFormatEnum values
* \ param bpp a bits per pixel value ; usually 15 , 16 , or 32
* \ param Rmask a pointer filled in with the red mask for the format
* \ param Gmask a pointer filled in with the green mask for the format
* \ param Bmask a pointer filled in with the blue mask for the format
* \ param Amask a pointer filled in with the alpha mask for the format
* \ returns SDL_TRUE on success or SDL_FALSE if the conversion wasn ' t
* possible ; call SDL_GetError ( ) for more information .
2015-06-21 09:33:46 -06:00
*
2022-11-22 15:40:14 -07:00
* \ since This function is available since SDL 3.0 .0 .
2021-10-26 19:36:05 -06:00
*
2022-12-27 07:08:13 -07:00
* \ sa SDL_GetPixelFormatEnumForMasks
2015-06-21 09:33:46 -06:00
*/
2024-03-06 11:59:05 -07:00
extern DECLSPEC SDL_bool SDLCALL SDL_GetMasksForPixelFormatEnum ( SDL_PixelFormatEnum format ,
2015-06-21 09:33:46 -06:00
int * bpp ,
Uint32 * Rmask ,
Uint32 * Gmask ,
Uint32 * Bmask ,
Uint32 * Amask ) ;
/**
2021-03-21 12:18:39 -06:00
* Convert a bpp value and RGBA masks to an enumerated pixel format .
2015-06-21 09:33:46 -06:00
*
2021-03-21 12:18:39 -06:00
* This will return ` SDL_PIXELFORMAT_UNKNOWN ` if the conversion wasn ' t
* possible .
2015-06-21 09:33:46 -06:00
*
2021-03-21 12:18:39 -06:00
* \ param bpp a bits per pixel value ; usually 15 , 16 , or 32
* \ param Rmask the red mask for the format
* \ param Gmask the green mask for the format
* \ param Bmask the blue mask for the format
* \ param Amask the alpha mask for the format
2024-03-06 17:20:27 -07:00
* \ returns the SDL_PixelFormatEnum value corresponding to the format masks ,
* or SDL_PIXELFORMAT_UNKNOWN if there isn ' t a match .
2021-03-21 12:18:39 -06:00
*
2022-11-22 15:40:14 -07:00
* \ since This function is available since SDL 3.0 .0 .
2021-10-26 19:36:05 -06:00
*
2022-12-27 07:08:13 -07:00
* \ sa SDL_GetMasksForPixelFormatEnum
2015-06-21 09:33:46 -06:00
*/
2024-03-06 17:19:08 -07:00
extern DECLSPEC SDL_PixelFormatEnum SDLCALL SDL_GetPixelFormatEnumForMasks ( int bpp ,
2015-06-21 09:33:46 -06:00
Uint32 Rmask ,
Uint32 Gmask ,
Uint32 Bmask ,
Uint32 Amask ) ;
/**
2021-03-21 12:18:39 -06:00
* Create an SDL_PixelFormat structure corresponding to a pixel format .
*
* Returned structure may come from a shared global cache ( i . e . not newly
* allocated ) , and hence should not be modified , especially the palette . Weird
* errors such as ` Blit combination not supported ` may occur .
*
* \ param pixel_format one of the SDL_PixelFormatEnum values
* \ returns the new SDL_PixelFormat structure or NULL on failure ; call
* SDL_GetError ( ) for more information .
*
2022-11-22 15:40:14 -07:00
* \ since This function is available since SDL 3.0 .0 .
2021-10-26 19:36:05 -06:00
*
2022-12-27 07:08:13 -07:00
* \ sa SDL_DestroyPixelFormat
2024-03-17 12:00:15 -06:00
* \ sa SDL_SetPixelFormatPalette
2015-06-21 09:33:46 -06:00
*/
2024-03-06 11:59:05 -07:00
extern DECLSPEC SDL_PixelFormat * SDLCALL SDL_CreatePixelFormat ( SDL_PixelFormatEnum pixel_format ) ;
2015-06-21 09:33:46 -06:00
/**
2022-12-27 07:08:13 -07:00
* Free an SDL_PixelFormat structure allocated by SDL_CreatePixelFormat ( ) .
2021-03-21 12:18:39 -06:00
*
* \ param format the SDL_PixelFormat structure to free
*
2022-11-22 15:40:14 -07:00
* \ since This function is available since SDL 3.0 .0 .
2021-10-26 19:36:05 -06:00
*
2022-12-27 07:08:13 -07:00
* \ sa SDL_CreatePixelFormat
2015-06-21 09:33:46 -06:00
*/
2023-02-09 08:53:47 -07:00
extern DECLSPEC void SDLCALL SDL_DestroyPixelFormat ( SDL_PixelFormat * format ) ;
2015-06-21 09:33:46 -06:00
/**
2021-03-21 12:18:39 -06:00
* Create a palette structure with the specified number of color entries .
2015-06-21 09:33:46 -06:00
*
2021-03-21 12:18:39 -06:00
* The palette entries are initialized to white .
2015-06-21 09:33:46 -06:00
*
2021-03-21 12:18:39 -06:00
* \ param ncolors represents the number of color entries in the color palette
* \ returns a new SDL_Palette structure on success or NULL on failure ( e . g . if
* there wasn ' t enough memory ) ; call SDL_GetError ( ) for more
* information .
2015-06-21 09:33:46 -06:00
*
2022-11-22 15:40:14 -07:00
* \ since This function is available since SDL 3.0 .0 .
2021-10-26 19:36:05 -06:00
*
2022-12-27 07:08:13 -07:00
* \ sa SDL_DestroyPalette
2024-03-17 12:00:15 -06:00
* \ sa SDL_SetPaletteColors
* \ sa SDL_SetPixelFormatPalette
2015-06-21 09:33:46 -06:00
*/
2022-12-27 07:08:13 -07:00
extern DECLSPEC SDL_Palette * SDLCALL SDL_CreatePalette ( int ncolors ) ;
2015-06-21 09:33:46 -06:00
/**
2021-03-21 12:18:39 -06:00
* Set the palette for a pixel format structure .
*
* \ param format the SDL_PixelFormat structure that will use the palette
* \ param palette the SDL_Palette structure that will be used
* \ returns 0 on success or a negative error code on failure ; call
* SDL_GetError ( ) for more information .
*
2022-11-22 15:40:14 -07:00
* \ since This function is available since SDL 3.0 .0 .
2015-06-21 09:33:46 -06:00
*/
extern DECLSPEC int SDLCALL SDL_SetPixelFormatPalette ( SDL_PixelFormat * format ,
SDL_Palette * palette ) ;
/**
2021-03-21 12:18:39 -06:00
* Set a range of colors in a palette .
2015-06-21 09:33:46 -06:00
*
2021-03-21 12:18:39 -06:00
* \ param palette the SDL_Palette structure to modify
* \ param colors an array of SDL_Color structures to copy into the palette
* \ param firstcolor the index of the first palette entry to modify
* \ param ncolors the number of entries to modify
2023-02-12 02:09:42 -07:00
* \ returns 0 on success or a negative error code on failure ; call
* SDL_GetError ( ) for more information .
2015-06-21 09:33:46 -06:00
*
2022-11-22 15:40:14 -07:00
* \ since This function is available since SDL 3.0 .0 .
2015-06-21 09:33:46 -06:00
*/
extern DECLSPEC int SDLCALL SDL_SetPaletteColors ( SDL_Palette * palette ,
const SDL_Color * colors ,
int firstcolor , int ncolors ) ;
/**
2022-12-27 07:08:13 -07:00
* Free a palette created with SDL_CreatePalette ( ) .
2021-03-21 12:18:39 -06:00
*
* \ param palette the SDL_Palette structure to be freed
2015-06-21 09:33:46 -06:00
*
2022-11-22 15:40:14 -07:00
* \ since This function is available since SDL 3.0 .0 .
2021-10-26 19:36:05 -06:00
*
2022-12-27 07:08:13 -07:00
* \ sa SDL_CreatePalette
2015-06-21 09:33:46 -06:00
*/
2023-02-09 08:53:47 -07:00
extern DECLSPEC void SDLCALL SDL_DestroyPalette ( SDL_Palette * palette ) ;
2015-06-21 09:33:46 -06:00
/**
2021-03-21 12:18:39 -06:00
* Map an RGB triple to an opaque pixel value for a given pixel format .
*
* This function maps the RGB color value to the specified pixel format and
* returns the pixel value best approximating the given RGB color value for
* the given pixel format .
*
* If the format has a palette ( 8 - bit ) the index of the closest matching color
* in the palette will be returned .
*
* If the specified pixel format has an alpha component it will be returned as
* all 1 bits ( fully opaque ) .
2015-06-21 09:33:46 -06:00
*
2021-03-21 12:18:39 -06:00
* If the pixel format bpp ( color depth ) is less than 32 - bpp then the unused
* upper bits of the return value can safely be ignored ( e . g . , with a 16 - bpp
* format the return value can be assigned to a Uint16 , and similarly a Uint8
* for an 8 - bpp format ) .
*
* \ param format an SDL_PixelFormat structure describing the pixel format
* \ param r the red component of the pixel in the range 0 - 255
* \ param g the green component of the pixel in the range 0 - 255
* \ param b the blue component of the pixel in the range 0 - 255
* \ returns a pixel value
*
2022-11-22 15:40:14 -07:00
* \ since This function is available since SDL 3.0 .0 .
2021-10-26 19:36:05 -06:00
*
2021-03-21 12:18:39 -06:00
* \ sa SDL_GetRGB
* \ sa SDL_GetRGBA
* \ sa SDL_MapRGBA
2015-06-21 09:33:46 -06:00
*/
extern DECLSPEC Uint32 SDLCALL SDL_MapRGB ( const SDL_PixelFormat * format ,
Uint8 r , Uint8 g , Uint8 b ) ;
/**
2021-03-21 12:18:39 -06:00
* Map an RGBA quadruple to a pixel value for a given pixel format .
*
* This function maps the RGBA color value to the specified pixel format and
* returns the pixel value best approximating the given RGBA color value for
* the given pixel format .
*
* If the specified pixel format has no alpha component the alpha value will
* be ignored ( as it will be in formats with a palette ) .
*
* If the format has a palette ( 8 - bit ) the index of the closest matching color
* in the palette will be returned .
*
* If the pixel format bpp ( color depth ) is less than 32 - bpp then the unused
* upper bits of the return value can safely be ignored ( e . g . , with a 16 - bpp
* format the return value can be assigned to a Uint16 , and similarly a Uint8
* for an 8 - bpp format ) .
*
* \ param format an SDL_PixelFormat structure describing the format of the
* pixel
* \ param r the red component of the pixel in the range 0 - 255
* \ param g the green component of the pixel in the range 0 - 255
* \ param b the blue component of the pixel in the range 0 - 255
* \ param a the alpha component of the pixel in the range 0 - 255
* \ returns a pixel value
2015-06-21 09:33:46 -06:00
*
2022-11-22 15:40:14 -07:00
* \ since This function is available since SDL 3.0 .0 .
2021-10-26 19:36:05 -06:00
*
2021-03-21 12:18:39 -06:00
* \ sa SDL_GetRGB
* \ sa SDL_GetRGBA
* \ sa SDL_MapRGB
2015-06-21 09:33:46 -06:00
*/
extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA ( const SDL_PixelFormat * format ,
Uint8 r , Uint8 g , Uint8 b ,
Uint8 a ) ;
/**
2021-03-21 12:18:39 -06:00
* Get RGB values from a pixel in the specified format .
2015-06-21 09:33:46 -06:00
*
2021-03-21 12:18:39 -06:00
* This function uses the entire 8 - bit [ 0. .255 ] range when converting color
* components from pixel formats with less than 8 - bits per RGB component
* ( e . g . , a completely white pixel in 16 - bit RGB565 format would return [ 0xff ,
* 0xff , 0xff ] not [ 0xf8 , 0xfc , 0xf8 ] ) .
*
* \ param pixel a pixel value
* \ param format an SDL_PixelFormat structure describing the format of the
* pixel
* \ param r a pointer filled in with the red component
* \ param g a pointer filled in with the green component
* \ param b a pointer filled in with the blue component
*
2022-11-22 15:40:14 -07:00
* \ since This function is available since SDL 3.0 .0 .
2021-10-26 19:36:05 -06:00
*
2021-03-21 12:18:39 -06:00
* \ sa SDL_GetRGBA
* \ sa SDL_MapRGB
* \ sa SDL_MapRGBA
2015-06-21 09:33:46 -06:00
*/
extern DECLSPEC void SDLCALL SDL_GetRGB ( Uint32 pixel ,
const SDL_PixelFormat * format ,
Uint8 * r , Uint8 * g , Uint8 * b ) ;
/**
2021-03-21 12:18:39 -06:00
* Get RGBA values from a pixel in the specified format .
*
* This function uses the entire 8 - bit [ 0. .255 ] range when converting color
* components from pixel formats with less than 8 - bits per RGB component
* ( e . g . , a completely white pixel in 16 - bit RGB565 format would return [ 0xff ,
* 0xff , 0xff ] not [ 0xf8 , 0xfc , 0xf8 ] ) .
*
* If the surface has no alpha component , the alpha will be returned as 0xff
* ( 100 % opaque ) .
2015-06-21 09:33:46 -06:00
*
2021-03-21 12:18:39 -06:00
* \ param pixel a pixel value
* \ param format an SDL_PixelFormat structure describing the format of the
* pixel
* \ param r a pointer filled in with the red component
* \ param g a pointer filled in with the green component
* \ param b a pointer filled in with the blue component
* \ param a a pointer filled in with the alpha component
*
2022-11-22 15:40:14 -07:00
* \ since This function is available since SDL 3.0 .0 .
2021-10-26 19:36:05 -06:00
*
2021-03-21 12:18:39 -06:00
* \ sa SDL_GetRGB
* \ sa SDL_MapRGB
* \ sa SDL_MapRGBA
2015-06-21 09:33:46 -06:00
*/
extern DECLSPEC void SDLCALL SDL_GetRGBA ( Uint32 pixel ,
const SDL_PixelFormat * format ,
Uint8 * r , Uint8 * g , Uint8 * b ,
Uint8 * a ) ;
/* Ends C function definitions when using C++ */
# ifdef __cplusplus
}
# endif
2022-12-22 09:38:59 -07:00
# include <SDL3/SDL_close_code.h>
2015-06-21 09:33:46 -06:00
2016-11-20 22:34:54 -07:00
# endif /* SDL_pixels_h_ */