# CategoryPixels

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.

<!-- END CATEGORY DOCUMENTATION -->

## Functions

<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
<!-- BEGIN CATEGORY LIST: CategoryPixels, CategoryAPIFunction -->
- [SDL_CreatePalette](SDL_CreatePalette)
- [SDL_DestroyPalette](SDL_DestroyPalette)
- [SDL_GetMasksForPixelFormat](SDL_GetMasksForPixelFormat)
- [SDL_GetPixelFormatDetails](SDL_GetPixelFormatDetails)
- [SDL_GetPixelFormatForMasks](SDL_GetPixelFormatForMasks)
- [SDL_GetPixelFormatName](SDL_GetPixelFormatName)
- [SDL_GetRGB](SDL_GetRGB)
- [SDL_GetRGBA](SDL_GetRGBA)
- [SDL_MapRGB](SDL_MapRGB)
- [SDL_MapRGBA](SDL_MapRGBA)
- [SDL_MapSurfaceRGB](SDL_MapSurfaceRGB)
- [SDL_MapSurfaceRGBA](SDL_MapSurfaceRGBA)
- [SDL_SetPaletteColors](SDL_SetPaletteColors)
<!-- END CATEGORY LIST -->

## Datatypes

<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
<!-- BEGIN CATEGORY LIST: CategoryPixels, CategoryAPIDatatype -->
- (none.)
<!-- END CATEGORY LIST -->

## Structs

<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
<!-- BEGIN CATEGORY LIST: CategoryPixels, CategoryAPIStruct -->
- [SDL_Color](SDL_Color)
- [SDL_FColor](SDL_FColor)
- [SDL_Palette](SDL_Palette)
- [SDL_PixelFormatDetails](SDL_PixelFormatDetails)
<!-- END CATEGORY LIST -->

## Enums

<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
<!-- BEGIN CATEGORY LIST: CategoryPixels, CategoryAPIEnum -->
- [SDL_ArrayOrder](SDL_ArrayOrder)
- [SDL_BitmapOrder](SDL_BitmapOrder)
- [SDL_ChromaLocation](SDL_ChromaLocation)
- [SDL_ColorPrimaries](SDL_ColorPrimaries)
- [SDL_ColorRange](SDL_ColorRange)
- [SDL_Colorspace](SDL_Colorspace)
- [SDL_ColorType](SDL_ColorType)
- [SDL_MatrixCoefficients](SDL_MatrixCoefficients)
- [SDL_PackedLayout](SDL_PackedLayout)
- [SDL_PackedOrder](SDL_PackedOrder)
- [SDL_PixelFormat](SDL_PixelFormat)
- [SDL_PixelType](SDL_PixelType)
- [SDL_TransferCharacteristics](SDL_TransferCharacteristics)
<!-- END CATEGORY LIST -->

## Macros

<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
<!-- BEGIN CATEGORY LIST: CategoryPixels, CategoryAPIMacro -->
- [SDL_ALPHA_OPAQUE](SDL_ALPHA_OPAQUE)
- [SDL_ALPHA_OPAQUE_FLOAT](SDL_ALPHA_OPAQUE_FLOAT)
- [SDL_ALPHA_TRANSPARENT](SDL_ALPHA_TRANSPARENT)
- [SDL_ALPHA_TRANSPARENT_FLOAT](SDL_ALPHA_TRANSPARENT_FLOAT)
- [SDL_BITSPERPIXEL](SDL_BITSPERPIXEL)
- [SDL_BYTESPERPIXEL](SDL_BYTESPERPIXEL)
- [SDL_COLORSPACECHROMA](SDL_COLORSPACECHROMA)
- [SDL_COLORSPACEMATRIX](SDL_COLORSPACEMATRIX)
- [SDL_COLORSPACEPRIMARIES](SDL_COLORSPACEPRIMARIES)
- [SDL_COLORSPACERANGE](SDL_COLORSPACERANGE)
- [SDL_COLORSPACETRANSFER](SDL_COLORSPACETRANSFER)
- [SDL_COLORSPACETYPE](SDL_COLORSPACETYPE)
- [SDL_DEFINE_COLORSPACE](SDL_DEFINE_COLORSPACE)
- [SDL_DEFINE_PIXELFORMAT](SDL_DEFINE_PIXELFORMAT)
- [SDL_DEFINE_PIXELFOURCC](SDL_DEFINE_PIXELFOURCC)
- [SDL_ISCOLORSPACE_FULL_RANGE](SDL_ISCOLORSPACE_FULL_RANGE)
- [SDL_ISCOLORSPACE_LIMITED_RANGE](SDL_ISCOLORSPACE_LIMITED_RANGE)
- [SDL_ISCOLORSPACE_MATRIX_BT2020_NCL](SDL_ISCOLORSPACE_MATRIX_BT2020_NCL)
- [SDL_ISCOLORSPACE_MATRIX_BT601](SDL_ISCOLORSPACE_MATRIX_BT601)
- [SDL_ISCOLORSPACE_MATRIX_BT709](SDL_ISCOLORSPACE_MATRIX_BT709)
- [SDL_ISPIXELFORMAT_10BIT](SDL_ISPIXELFORMAT_10BIT)
- [SDL_ISPIXELFORMAT_ALPHA](SDL_ISPIXELFORMAT_ALPHA)
- [SDL_ISPIXELFORMAT_ARRAY](SDL_ISPIXELFORMAT_ARRAY)
- [SDL_ISPIXELFORMAT_FLOAT](SDL_ISPIXELFORMAT_FLOAT)
- [SDL_ISPIXELFORMAT_FOURCC](SDL_ISPIXELFORMAT_FOURCC)
- [SDL_ISPIXELFORMAT_INDEXED](SDL_ISPIXELFORMAT_INDEXED)
- [SDL_ISPIXELFORMAT_PACKED](SDL_ISPIXELFORMAT_PACKED)
- [SDL_PIXELFLAG](SDL_PIXELFLAG)
- [SDL_PIXELLAYOUT](SDL_PIXELLAYOUT)
- [SDL_PIXELORDER](SDL_PIXELORDER)
- [SDL_PIXELTYPE](SDL_PIXELTYPE)
<!-- END CATEGORY LIST -->


----
[CategoryAPICategory](CategoryAPICategory)