Pixel format. More...

Public Member Functions
constexpr	PixelFormat (SDL_PixelFormat format={})
	Wraps PixelFormat.

constexpr	PixelFormat (SDL_PixelType type, int order, SDL_PackedLayout layout, int bits, int bytes)
	Defining custom non-FourCC pixel formats.

constexpr bool	operator== (const PixelFormat &other) const =default
	Default comparison operator.

constexpr bool	operator== (SDL_PixelFormat format) const
	Compares with the underlying type.

constexpr	operator SDL_PixelFormat () const
	Unwraps to the underlying PixelFormat.

constexpr	operator bool () const
	Check if valid.

constexpr PixelType	GetType () const
	Retrieve the type.

constexpr int	GetOrder () const
	Retrieve the order.

constexpr PackedLayout	GetLayout () const
	Retrieve the layout.

constexpr int	GetBitsPerPixel () const
	Determine this's bits per pixel.

constexpr int	GetBytesPerPixel () const
	Determine this's bytes per pixel.

constexpr bool	IsIndexed () const
	Determine if this is an indexed format.

constexpr bool	IsPacked () const
	Determine if this is a packed format.

constexpr bool	IsArray () const
	Determine if this is an array format.

constexpr bool	Is10Bit () const
	Determine if this is a 10-bit format.

constexpr bool	IsFloat () const
	Determine if this is a floating point format.

constexpr bool	IsAlpha () const
	Determine if this has an alpha channel.

constexpr bool	IsFourCC () const
	Determine if this is a "FourCC" format.

const char *	GetName () const
	Get the human readable name of a pixel format.

void	GetMasks (int bpp, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 *Amask) const
	Convert one of the enumerated pixel formats to a bpp value and RGBA masks.

const PixelFormatDetails *	GetDetails () const
	Create an PixelFormatDetails structure corresponding to a pixel format.

Uint32	Map (Color color, PaletteRef palette) const
	Map an RGBA quadruple to a pixel value for a given pixel format.

Color	Get (Uint32 pixel, PaletteRef palette) const
	Get RGBA values from a pixel in the specified format.

Static Public Member Functions
static PixelFormat	ForMasks (int bpp, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask)
	Convert a bpp value and RGBA masks to an enumerated pixel format.

Detailed Description

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.

Since: This enum is available since SDL 3.2.0.

Category:: Wrap state

See also: wrap-state; PixelFormats

Constructor & Destructor Documentation

◆ PixelFormat() [1/2]

constexpr SDL::PixelFormat::PixelFormat ( SDL_PixelFormat format = {} )

inlineconstexpr

Parameters

format the value to be wrapped

◆ PixelFormat() [2/2]

constexpr SDL::PixelFormat::PixelFormat	(	SDL_PixelType	type,
		int	order,
		SDL_PackedLayout	layout,
		int	bits,
		int	bytes
	)

inlineconstexpr

For example, defining PIXELFORMAT_RGBA8888 looks like this:

PixelFormat(PIXELTYPE_PACKED32, PACKEDORDER_RGBA,

PACKEDLAYOUT_8888, 32, 4)

SDL::PixelFormat

Pixel format.

Definition SDL3pp_pixels.h:374

SDL::PIXELTYPE_PACKED32

constexpr PixelType PIXELTYPE_PACKED32

PACKED32.

Definition SDL3pp_pixels.h:149

SDL::PACKEDORDER_RGBA

constexpr PackedOrder PACKEDORDER_RGBA

RGBA.

Definition SDL3pp_pixels.h:205

SDL::PACKEDLAYOUT_8888

constexpr PackedLayout PACKEDLAYOUT_8888

8888

Definition SDL3pp_pixels.h:269

Parameters

type	the type of the new format, probably a PixelType value.
order	the order of the new format, probably a BitmapOrder, PackedOrder, or ArrayOrder value.
layout	the layout of the new format, probably an PackedLayout value or zero.
bits	the number of bits per pixel of the new format.
bytes	the number of bytes per pixel of the new format.

Postcondition: a format value in the style of PixelFormat.

Thread safety:: It is safe to call this macro from any thread.

Since: This macro is available since SDL 3.2.0.

Member Function Documentation

◆ ForMasks()

static PixelFormat SDL::PixelFormat::ForMasks	(	int	bpp,
		Uint32	Rmask,
		Uint32	Gmask,
		Uint32	Bmask,
		Uint32	Amask
	)

inlinestatic

This will return PIXELFORMAT_UNKNOWN if the conversion wasn't possible.

Parameters

bpp	a bits per pixel value; usually 15, 16, or 32.
Rmask	the red mask for the format.
Gmask	the green mask for the format.
Bmask	the blue mask for the format.
Amask	the alpha mask for the format.

Returns: the PixelFormat value corresponding to the format masks, or PIXELFORMAT_UNKNOWN if there isn't a match.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: PixelFormat.GetMasks

◆ Get()

Color SDL::PixelFormat::Get	(	Uint32	pixel,
		PaletteRef	palette = `nullptr`
	)		const

inline

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).

Parameters

pixel	a pixel value.
palette	an optional palette for indexed formats, may be NULL.

Returns: a color value.

Thread safety:: It is safe to call this function from any thread, as long as the palette is not modified.

Since: This function is available since SDL 3.2.0.

See also: GetPixelFormatDetails(); GetRGBA(); Map()

◆ GetBitsPerPixel()

constexpr int SDL::PixelFormat::GetBitsPerPixel ( ) const

inlineconstexpr

FourCC formats will report zero here, as it rarely makes sense to measure them per-pixel.

Returns: the bits-per-pixel.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: GetBytesPerPixel

◆ GetBytesPerPixel()

constexpr int SDL::PixelFormat::GetBytesPerPixel ( ) const

inlineconstexpr

Note that this macro double-evaluates its parameter, so do not use expressions with side-effects here.

FourCC formats do their best here, but many of them don't have a meaningful measurement of bytes per pixel.

Returns: the bytes-per-pixel.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: GetBitsPerPixel

◆ GetDetails()

const PixelFormatDetails * SDL::PixelFormat::GetDetails ( ) const

inline

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.

Returns: a pointer to a PixelFormatDetails structure or nullptr on failure; call GetError() for more information.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ GetLayout()

constexpr PackedLayout SDL::PixelFormat::GetLayout ( ) const

inlineconstexpr

This is usually a value from the PackedLayout enumeration, or zero if a layout doesn't make sense for the format type.

Returns: the layout

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ GetMasks()

void SDL::PixelFormat::GetMasks	(	int *	bpp,
		Uint32 *	Rmask,
		Uint32 *	Gmask,
		Uint32 *	Bmask,
		Uint32 *	Amask
	)		const

inline

Parameters

bpp	a bits per pixel value; usually 15, 16, or 32.
Rmask	a pointer filled in with the red mask for the format.
Gmask	a pointer filled in with the green mask for the format.
Bmask	a pointer filled in with the blue mask for the format.
Amask	a pointer filled in with the alpha mask for the format.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: PixelFormat.ForMasks

◆ GetName()

const char * SDL::PixelFormat::GetName ( ) const

inline

Returns: the human readable name of the specified pixel format or "PIXELFORMAT_UNKNOWN" if the format isn't recognized.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ GetOrder()

constexpr int SDL::PixelFormat::GetOrder ( ) const

inlineconstexpr

This is usually a value from the BitmapOrder, PackedOrder, or ArrayOrder enumerations, depending on the format type.

Returns: the order.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ GetType()

constexpr PixelType SDL::PixelFormat::GetType ( ) const

inlineconstexpr

Returns: the type as PixelType.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ Is10Bit()

constexpr bool SDL::PixelFormat::Is10Bit ( ) const

inlineconstexpr

Returns: true if the format is 10-bit, false otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ IsAlpha()

constexpr bool SDL::PixelFormat::IsAlpha ( ) const

inlineconstexpr

Returns: true if the format has alpha, false otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ IsArray()

constexpr bool SDL::PixelFormat::IsArray ( ) const

inlineconstexpr

Returns: true if the format is an array, false otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ IsFloat()

constexpr bool SDL::PixelFormat::IsFloat ( ) const

inlineconstexpr

Returns: true if the format is 10-bit, false otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ IsFourCC()

constexpr bool SDL::PixelFormat::IsFourCC ( ) const

inlineconstexpr

This covers custom and other unusual formats.

Returns: true if the format has alpha, false otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ IsIndexed()

constexpr bool SDL::PixelFormat::IsIndexed ( ) const

inlineconstexpr

Returns: true if the format is indexed, false otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ IsPacked()

constexpr bool SDL::PixelFormat::IsPacked ( ) const

inlineconstexpr

Returns: true if the format is packed, false otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ Map()

Uint32 SDL::PixelFormat::Map	(	Color	color,
		PaletteRef	palette = `nullptr`
	)		const

inline

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).

Parameters

color	the color components of the pixel in the range 0-255.
palette	an optional palette for indexed formats, may be NULL.

Returns: a pixel value.

Thread safety:: It is safe to call this function from any thread, as long as the palette is not modified.

Since: This function is available since SDL 3.2.0.

See also: GetPixelFormatDetails(); Get(); MapRGBA(); Surface.MapColor()

◆ operator bool()

constexpr SDL::PixelFormat::operator bool ( ) const

inlineexplicitconstexpr

Returns: True if valid state, false otherwise.

◆ operator SDL_PixelFormat()

constexpr SDL::PixelFormat::operator SDL_PixelFormat ( ) const

inlineconstexpr

Returns: the underlying PixelFormat.

The documentation for this class was generated from the following file:

SDL3pp/SDL3pp_pixels.h

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ PixelFormat() [1/2]

◆ PixelFormat() [2/2]

Member Function Documentation

◆ ForMasks()

◆ Get()

◆ GetBitsPerPixel()

◆ GetBytesPerPixel()

◆ GetDetails()

◆ GetLayout()

◆ GetMasks()

◆ GetName()

◆ GetOrder()

◆ GetType()

◆ Is10Bit()

◆ IsAlpha()

◆ IsArray()

◆ IsFloat()

◆ IsFourCC()

◆ IsIndexed()

◆ IsPacked()

◆ Map()

◆ operator bool()

◆ operator SDL_PixelFormat()