devela::_dep::sdl3::sys

Module pixels

Available on crate feature dep_sdl3 only.
Expand description

SDL offers facilities for pixel management.

Largely these facilities deal with pixel format: what does this set of bits represent?

If you mostly want to think of a pixel as some combination of red, green, blue, and maybe alpha intensities, this is all pretty straightforward, and in many cases, is enough information to build a perfectly fine game.

However, the actual definition of a pixel is more complex than that:

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.

Structs§

SDL_ArrayOrder
Array component order, low byte -> high byte.
SDL_BitmapOrder
Bitmap pixel order, high bit -> low bit.
SDL_ChromaLocation
Colorspace chroma sample location.
SDL_Color
A structure that represents a color as RGBA components.
SDL_ColorPrimaries
Colorspace color primaries, as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en
SDL_ColorRange
Colorspace color range, as described by https://www.itu.int/rec/R-REC-BT.2100-2-201807-I/en
SDL_ColorType
Colorspace color type.
SDL_Colorspace
Colorspace definitions.
SDL_FColor
The bits of this structure can be directly reinterpreted as a float-packed color which uses the SDL_PIXELFORMAT_RGBA128_FLOAT format
SDL_MatrixCoefficients
Colorspace matrix coefficients.
SDL_PackedLayout
Packed component layout.
SDL_PackedOrder
Packed component order, high bit -> low bit.
SDL_Palette
A set of indexed colors representing a palette.
SDL_PixelFormat
Pixel format.
SDL_PixelFormatDetails
Details about the format of a pixel.
SDL_PixelType
Pixel type.
SDL_TransferCharacteristics
Colorspace transfer characteristics.

Constants§

SDL_ALPHA_OPAQUE
A fully opaque 8-bit alpha value.
SDL_ALPHA_OPAQUE_FLOAT
A fully opaque floating point alpha value.
SDL_ALPHA_TRANSPARENT
A fully transparent 8-bit alpha value.
SDL_ALPHA_TRANSPARENT_FLOAT
A fully transparent floating point alpha value.
SDL_ARRAYORDER_ABGR
SDL_ARRAYORDER_ARGB
SDL_ARRAYORDER_BGR
SDL_ARRAYORDER_BGRA
SDL_ARRAYORDER_NONE
SDL_ARRAYORDER_RGB
SDL_ARRAYORDER_RGBA
SDL_BITMAPORDER_1234
SDL_BITMAPORDER_4321
SDL_BITMAPORDER_NONE
SDL_CHROMA_LOCATION_CENTER
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.
SDL_CHROMA_LOCATION_LEFT
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_NONE
RGB, no chroma sampling
SDL_CHROMA_LOCATION_TOPLEFT
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_COLORSPACE_BT601_FULL
Equivalent to DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P601
SDL_COLORSPACE_BT601_LIMITED
Equivalent to DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P601
SDL_COLORSPACE_BT709_FULL
Equivalent to DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P709
SDL_COLORSPACE_BT709_LIMITED
Equivalent to DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P709
SDL_COLORSPACE_BT2020_FULL
Equivalent to DXGI_COLOR_SPACE_YCBCR_FULL_G22_LEFT_P2020
SDL_COLORSPACE_BT2020_LIMITED
Equivalent to DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P2020
SDL_COLORSPACE_HDR10
Equivalent to DXGI_COLOR_SPACE_RGB_FULL_G2084_NONE_P2020
SDL_COLORSPACE_JPEG
Equivalent to DXGI_COLOR_SPACE_YCBCR_FULL_G22_NONE_P709_X601
SDL_COLORSPACE_RGB_DEFAULT
The default colorspace for RGB surfaces if no colorspace is specified
SDL_COLORSPACE_SRGB
Equivalent to DXGI_COLOR_SPACE_RGB_FULL_G22_NONE_P709
SDL_COLORSPACE_SRGB_LINEAR
Equivalent to DXGI_COLOR_SPACE_RGB_FULL_G10_NONE_P709
SDL_COLORSPACE_UNKNOWN
SDL_COLORSPACE_YUV_DEFAULT
The default colorspace for YUV surfaces if no colorspace is specified
SDL_COLOR_PRIMARIES_BT601
ITU-R BT.601-7 525, SMPTE 170M
SDL_COLOR_PRIMARIES_BT709
ITU-R BT.709-6
SDL_COLOR_PRIMARIES_BT470BG
ITU-R BT.470-6 System B, G / ITU-R BT.601-7 625
SDL_COLOR_PRIMARIES_BT470M
ITU-R BT.470-6 System M
SDL_COLOR_PRIMARIES_BT2020
ITU-R BT.2020-2 / ITU-R BT.2100-0
SDL_COLOR_PRIMARIES_CUSTOM
SDL_COLOR_PRIMARIES_EBU3213
EBU Tech. 3213-E
SDL_COLOR_PRIMARIES_GENERIC_FILM
Generic film (color filters using Illuminant C)
SDL_COLOR_PRIMARIES_SMPTE240
SMPTE 240M, functionally the same as SDL_COLOR_PRIMARIES_BT601
SDL_COLOR_PRIMARIES_SMPTE431
SMPTE RP 431-2
SDL_COLOR_PRIMARIES_SMPTE432
SMPTE EG 432-1 / DCI P3
SDL_COLOR_PRIMARIES_UNKNOWN
SDL_COLOR_PRIMARIES_UNSPECIFIED
SDL_COLOR_PRIMARIES_XYZ
SMPTE ST 428-1
SDL_COLOR_RANGE_FULL
Full range, e.g. 0-255 for 8-bit RGB and luma, and 1-255 for 8-bit chroma
SDL_COLOR_RANGE_LIMITED
Narrow range, e.g. 16-235 for 8-bit RGB and luma, and 16-240 for 8-bit chroma
SDL_COLOR_RANGE_UNKNOWN
SDL_COLOR_TYPE_RGB
SDL_COLOR_TYPE_UNKNOWN
SDL_COLOR_TYPE_YCBCR
SDL_MATRIX_COEFFICIENTS_BT601
ITU-R BT.601-7 525
SDL_MATRIX_COEFFICIENTS_BT709
ITU-R BT.709-6
SDL_MATRIX_COEFFICIENTS_BT470BG
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_BT2020_CL
ITU-R BT.2020-2 constant luminance
SDL_MATRIX_COEFFICIENTS_BT2020_NCL
ITU-R BT.2020-2 non-constant luminance
SDL_MATRIX_COEFFICIENTS_CHROMA_DERIVED_CL
SDL_MATRIX_COEFFICIENTS_CHROMA_DERIVED_NCL
SDL_MATRIX_COEFFICIENTS_CUSTOM
SDL_MATRIX_COEFFICIENTS_FCC
US FCC Title 47
SDL_MATRIX_COEFFICIENTS_ICTCP
ITU-R BT.2100-0 ICTCP
SDL_MATRIX_COEFFICIENTS_IDENTITY
SDL_MATRIX_COEFFICIENTS_SMPTE240
SMPTE 240M
SDL_MATRIX_COEFFICIENTS_SMPTE2085
SMPTE ST 2085
SDL_MATRIX_COEFFICIENTS_UNSPECIFIED
SDL_MATRIX_COEFFICIENTS_YCGCO
SDL_PACKEDLAYOUT_332
SDL_PACKEDLAYOUT_565
SDL_PACKEDLAYOUT_1555
SDL_PACKEDLAYOUT_4444
SDL_PACKEDLAYOUT_5551
SDL_PACKEDLAYOUT_8888
SDL_PACKEDLAYOUT_1010102
SDL_PACKEDLAYOUT_2101010
SDL_PACKEDLAYOUT_NONE
SDL_PACKEDORDER_ABGR
SDL_PACKEDORDER_ARGB
SDL_PACKEDORDER_BGRA
SDL_PACKEDORDER_BGRX
SDL_PACKEDORDER_NONE
SDL_PACKEDORDER_RGBA
SDL_PACKEDORDER_RGBX
SDL_PACKEDORDER_XBGR
SDL_PACKEDORDER_XRGB
SDL_PIXELFORMAT_ABGR32
SDL_PIXELFORMAT_ABGR64
SDL_PIXELFORMAT_ABGR64_FLOAT
SDL_PIXELFORMAT_ABGR128_FLOAT
SDL_PIXELFORMAT_ABGR1555
SDL_PIXELFORMAT_ABGR4444
SDL_PIXELFORMAT_ABGR8888
SDL_PIXELFORMAT_ABGR2101010
SDL_PIXELFORMAT_ARGB32
SDL_PIXELFORMAT_ARGB64
SDL_PIXELFORMAT_ARGB64_FLOAT
SDL_PIXELFORMAT_ARGB128_FLOAT
SDL_PIXELFORMAT_ARGB1555
SDL_PIXELFORMAT_ARGB4444
SDL_PIXELFORMAT_ARGB8888
SDL_PIXELFORMAT_ARGB2101010
SDL_PIXELFORMAT_BGR24
SDL_PIXELFORMAT_BGR48
SDL_PIXELFORMAT_BGR48_FLOAT
SDL_PIXELFORMAT_BGR96_FLOAT
SDL_PIXELFORMAT_BGR565
SDL_PIXELFORMAT_BGRA32
SDL_PIXELFORMAT_BGRA64
SDL_PIXELFORMAT_BGRA64_FLOAT
SDL_PIXELFORMAT_BGRA128_FLOAT
SDL_PIXELFORMAT_BGRA4444
SDL_PIXELFORMAT_BGRA5551
SDL_PIXELFORMAT_BGRA8888
SDL_PIXELFORMAT_BGRX32
SDL_PIXELFORMAT_BGRX8888
SDL_PIXELFORMAT_EXTERNAL_OES
Android video texture format
SDL_PIXELFORMAT_INDEX8
SDL_PIXELFORMAT_INDEX1LSB
SDL_PIXELFORMAT_INDEX1MSB
SDL_PIXELFORMAT_INDEX2LSB
SDL_PIXELFORMAT_INDEX2MSB
SDL_PIXELFORMAT_INDEX4LSB
SDL_PIXELFORMAT_INDEX4MSB
SDL_PIXELFORMAT_IYUV
Planar mode: Y + U + V (3 planes)
SDL_PIXELFORMAT_NV12
Planar mode: Y + U/V interleaved (2 planes)
SDL_PIXELFORMAT_NV21
Planar mode: Y + V/U interleaved (2 planes)
SDL_PIXELFORMAT_P010
Planar mode: Y + U/V interleaved (2 planes)
SDL_PIXELFORMAT_RGB24
SDL_PIXELFORMAT_RGB48
SDL_PIXELFORMAT_RGB48_FLOAT
SDL_PIXELFORMAT_RGB96_FLOAT
SDL_PIXELFORMAT_RGB332
SDL_PIXELFORMAT_RGB565
SDL_PIXELFORMAT_RGBA32
SDL_PIXELFORMAT_RGBA64
SDL_PIXELFORMAT_RGBA64_FLOAT
SDL_PIXELFORMAT_RGBA128_FLOAT
SDL_PIXELFORMAT_RGBA4444
SDL_PIXELFORMAT_RGBA5551
SDL_PIXELFORMAT_RGBA8888
SDL_PIXELFORMAT_RGBX32
SDL_PIXELFORMAT_RGBX8888
SDL_PIXELFORMAT_UNKNOWN
SDL_PIXELFORMAT_UYVY
Packed mode: U0+Y0+V0+Y1 (1 plane)
SDL_PIXELFORMAT_XBGR32
SDL_PIXELFORMAT_XBGR1555
SDL_PIXELFORMAT_XBGR4444
SDL_PIXELFORMAT_XBGR8888
SDL_PIXELFORMAT_XBGR2101010
SDL_PIXELFORMAT_XRGB32
SDL_PIXELFORMAT_XRGB1555
SDL_PIXELFORMAT_XRGB4444
SDL_PIXELFORMAT_XRGB8888
SDL_PIXELFORMAT_XRGB2101010
SDL_PIXELFORMAT_YUY2
Packed mode: Y0+U0+Y1+V0 (1 plane)
SDL_PIXELFORMAT_YV12
Planar mode: Y + V + U (3 planes)
SDL_PIXELFORMAT_YVYU
Packed mode: Y0+V0+Y1+U0 (1 plane)
SDL_PIXELTYPE_ARRAYF16
SDL_PIXELTYPE_ARRAYF32
SDL_PIXELTYPE_ARRAYU8
SDL_PIXELTYPE_ARRAYU16
SDL_PIXELTYPE_ARRAYU32
SDL_PIXELTYPE_INDEX1
SDL_PIXELTYPE_INDEX2
SDL_PIXELTYPE_INDEX4
SDL_PIXELTYPE_INDEX8
SDL_PIXELTYPE_PACKED8
SDL_PIXELTYPE_PACKED16
SDL_PIXELTYPE_PACKED32
SDL_PIXELTYPE_UNKNOWN
SDL_TRANSFER_CHARACTERISTICS_BT601
SMPTE ST 170M / ITU-R BT.601-7 525 or 625
SDL_TRANSFER_CHARACTERISTICS_BT709
Rec. ITU-R BT.709-6 / ITU-R BT1361
SDL_TRANSFER_CHARACTERISTICS_BT1361
ITU-R BT1361 Extended Colour Gamut
SDL_TRANSFER_CHARACTERISTICS_BT2020_10BIT
ITU-R BT2020 for 10-bit system
SDL_TRANSFER_CHARACTERISTICS_BT2020_12BIT
ITU-R BT2020 for 12-bit system
SDL_TRANSFER_CHARACTERISTICS_CUSTOM
SDL_TRANSFER_CHARACTERISTICS_GAMMA22
ITU-R BT.470-6 System M / ITU-R BT1700 625 PAL & SECAM
SDL_TRANSFER_CHARACTERISTICS_GAMMA28
ITU-R BT.470-6 System B, G
SDL_TRANSFER_CHARACTERISTICS_HLG
ARIB STD-B67, known as “hybrid log-gamma” (HLG)
SDL_TRANSFER_CHARACTERISTICS_IEC61966
IEC 61966-2-4
SDL_TRANSFER_CHARACTERISTICS_LINEAR
SDL_TRANSFER_CHARACTERISTICS_LOG100
SDL_TRANSFER_CHARACTERISTICS_LOG100_SQRT10
SDL_TRANSFER_CHARACTERISTICS_PQ
SMPTE ST 2084 for 10-, 12-, 14- and 16-bit systems
SDL_TRANSFER_CHARACTERISTICS_SMPTE240
SMPTE ST 240M
SDL_TRANSFER_CHARACTERISTICS_SMPTE428
SMPTE ST 428-1
SDL_TRANSFER_CHARACTERISTICS_SRGB
IEC 61966-2-1 (sRGB or sYCC)
SDL_TRANSFER_CHARACTERISTICS_UNKNOWN
SDL_TRANSFER_CHARACTERISTICS_UNSPECIFIED

Functions§

SDL_BITSPERPIXEL
A macro to determine an SDL_PixelFormat’s bits per pixel.
SDL_BYTESPERPIXEL
A macro to determine an SDL_PixelFormat’s bytes per pixel.
SDL_COLORSPACECHROMA
A macro to retrieve the chroma sample location of an SDL_Colorspace.
SDL_COLORSPACEMATRIX
A macro to retrieve the matrix coefficients of an SDL_Colorspace.
SDL_COLORSPACEPRIMARIES
A macro to retrieve the primaries of an SDL_Colorspace.
SDL_COLORSPACERANGE
A macro to retrieve the range of an SDL_Colorspace.
SDL_COLORSPACETRANSFER
A macro to retrieve the transfer characteristics of an SDL_Colorspace.
SDL_COLORSPACETYPE
A macro to retrieve the type of an SDL_Colorspace.
SDL_CreatePalette⚠
Create a palette structure with the specified number of color entries.
SDL_DEFINE_COLORSPACE
A macro for defining custom SDL_Colorspace formats.
SDL_DEFINE_PIXELFORMAT
A macro for defining custom non-FourCC pixel formats.
SDL_DEFINE_PIXELFOURCC
A macro for defining custom FourCC pixel formats.
SDL_DestroyPalette⚠
Free a palette created with SDL_CreatePalette().
SDL_GetMasksForPixelFormat⚠
Convert one of the enumerated pixel formats to a bpp value and RGBA masks.
SDL_GetPixelFormatDetails⚠
Create an SDL_PixelFormatDetails structure corresponding to a pixel format.
SDL_GetPixelFormatForMasks⚠
Convert a bpp value and RGBA masks to an enumerated pixel format.
SDL_GetPixelFormatName⚠
Get the human readable name of a pixel format.
SDL_GetRGB⚠
Get RGB values from a pixel in the specified format.
SDL_GetRGBA⚠
Get RGBA values from a pixel in the specified format.
SDL_ISCOLORSPACE_FULL_RANGE
A macro to determine if an SDL_Colorspace has a full range.
SDL_ISCOLORSPACE_LIMITED_RANGE
A macro to determine if an SDL_Colorspace has a limited range.
SDL_ISCOLORSPACE_MATRIX_BT601
A macro to determine if an SDL_Colorspace uses BT601 (or BT470BG) matrix coefficients.
SDL_ISCOLORSPACE_MATRIX_BT709
A macro to determine if an SDL_Colorspace uses BT709 matrix coefficients.
SDL_ISCOLORSPACE_MATRIX_BT2020_NCL
A macro to determine if an SDL_Colorspace uses BT2020_NCL matrix coefficients.
SDL_ISPIXELFORMAT_10BIT
A macro to determine if an SDL_PixelFormat is a 10-bit format.
SDL_ISPIXELFORMAT_ALPHA
A macro to determine if an SDL_PixelFormat has an alpha channel.
SDL_ISPIXELFORMAT_ARRAY
A macro to determine if an SDL_PixelFormat is an array format.
SDL_ISPIXELFORMAT_FLOAT
A macro to determine if an SDL_PixelFormat is a floating point format.
SDL_ISPIXELFORMAT_FOURCC
A macro to determine if an SDL_PixelFormat is a “FourCC” format.
SDL_ISPIXELFORMAT_INDEXED
A macro to determine if an SDL_PixelFormat is an indexed format.
SDL_ISPIXELFORMAT_PACKED
A macro to determine if an SDL_PixelFormat is a packed format.
SDL_MapRGB⚠
Map an RGB triple to an opaque pixel value for a given pixel format.
SDL_MapRGBA⚠
Map an RGBA quadruple to a pixel value for a given pixel format.
SDL_PIXELFLAG
A macro to retrieve the flags of an SDL_PixelFormat.
SDL_PIXELLAYOUT
A macro to retrieve the layout of an SDL_PixelFormat.
SDL_PIXELORDER
A macro to retrieve the order of an SDL_PixelFormat.
SDL_PIXELTYPE
A macro to retrieve the type of an SDL_PixelFormat.
SDL_SetPaletteColors⚠
Set a range of colors in a palette.