Palette Class

KGy SOFT Drawing Libraries Help
Represents an indexed set of colors and provides efficient color lookup with caching.
See the Remarks section for details.
Inheritance Hierarchy

SystemObject
  KGySoft.Drawing.ImagingPalette

Namespace:  KGySoft.Drawing.Imaging
Assembly:  KGySoft.Drawing (in KGySoft.Drawing.dll) Version: 5.0.0
Syntax

public sealed class Palette

The Palette type exposes the following members.

Constructors

  NameDescription
Public methodPalette(Color, Color, Byte, FuncColor32, Int32)
Initializes a new instance of the Palette class.
See the Remarks section of the Palette class for details.
Public methodPalette(Color32, Color32, Byte, FuncColor32, Int32)
Initializes a new instance of the Palette class.
See the Remarks section of the Palette class for details.
Top
Properties

  NameDescription
Public propertyAlphaThreshold
If this Palette has a transparent entry, then gets a threshold value for the Color32.A field, under which lookup operations will return the first transparent color (GetNearestColor) or the index of the first transparent color (GetNearestColorIndex) in the palette.
Public propertyBackColor
Gets the background color. If a lookup operation (GetNearestColor, GetNearestColorIndex) is performed with a color whose Color32.A field is equal to or greater than AlphaThreshold, and there is no exact match among the entries of this Palette, then the color will be blended with this color before performing the lookup.
Public propertyCount
Gets the number of color entries in the current Palette.
Top
Methods

  NameDescription
Public methodGetColor
Gets the color entry of this Palette at the specified index.
Public methodGetEntries
Gets a read-only wrapper of the entries of this Palette instance.
Public methodGetNearestColor
Gets a Color32 entry of this Palette that is the nearest color to the specified Color32 instance.
See the Remarks section for details.
Public methodGetNearestColorIndex
Gets the index of a Palette entry that is the nearest color to the specified Color32 instance.
See the Remarks section for details.
Top
Remarks

The Palette class can be used to perform quick lookup operations (see GetNearestColor and GetNearestColorIndex methods) to find the closest matching palette entry to any color.

By default the lookup is performed by a slightly modified euclidean-like search but if the Palette contains grayscale entries only, then it is optimized for finding the best matching gray shade based on human perception. To override this logic a custom lookup routine can be passed to the constructors.

If the Palette instance is created without a custom lookup logic, then the search results for non-palette-entry colors are cached. The cache is optimized for parallel processing and consists of multiple levels where the results are tried to be obtained from a non-locking storage in the first place. The theoretical maximum of cache size (apart from the actual palette entries) is 2 x 218 but as soon as that limit is reached the amount of stored elements are halved so the cache is somewhat optimized to store the most recently processed colors.

In order to prevent caching you can pass a custom lookup logic to the constructors. It is expected to be fast (applying some direct mapping to a palette index, for example), or that it uses some custom caching (which should perform well also when queried concurrently).

The palette can have any number of colors but as the typical usage is quantizing colors for indexed bitmaps the typical maximum palette size is 256. Generally, the more color the palette has the slower are the lookups for non-palette colors that are not cached yet.

Thread Safety

If there is no custom lookup logic passed to the constructors, then members of this type are guaranteed to be safe for multi-threaded operations. If this type is initialized with a custom lookup logic, then thread-safety depends on the custom lookup implementation.
See Also

Reference