mirror of https://github.com/SixLabors/ImageSharp
James Jackson-South
1 year ago
27 changed files with 1363 additions and 805 deletions
@ -0,0 +1,28 @@ |
|||||
|
// Copyright (c) Six Labors.
|
||||
|
// Licensed under the Six Labors Split License.
|
||||
|
|
||||
|
namespace SixLabors.ImageSharp.Processing.Processors.Quantization; |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Defines the precision level used when matching colors during quantization.
|
||||
|
/// </summary>
|
||||
|
public enum ColorMatchingMode |
||||
|
{ |
||||
|
/// <summary>
|
||||
|
/// Uses a coarse caching strategy optimized for performance at the expense of exact matches.
|
||||
|
/// This provides the fastest matching but may yield approximate results.
|
||||
|
/// </summary>
|
||||
|
Coarse, |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Enables an exact color match cache for the first 512 unique colors encountered,
|
||||
|
/// falling back to coarse matching thereafter.
|
||||
|
/// </summary>
|
||||
|
Hybrid, |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Performs exact color matching without any caching optimizations.
|
||||
|
/// This is the slowest but most accurate matching strategy.
|
||||
|
/// </summary>
|
||||
|
Exact |
||||
|
} |
||||
@ -0,0 +1,184 @@ |
|||||
|
// Copyright (c) Six Labors.
|
||||
|
// Licensed under the Six Labors Split License.
|
||||
|
|
||||
|
using System.Runtime.CompilerServices; |
||||
|
using System.Runtime.InteropServices; |
||||
|
using SixLabors.ImageSharp.PixelFormats; |
||||
|
|
||||
|
namespace SixLabors.ImageSharp.Processing.Processors.Quantization; |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Gets the closest color to the supplied color based upon the Euclidean distance.
|
||||
|
/// </summary>
|
||||
|
/// <typeparam name="TPixel">The pixel format.</typeparam>
|
||||
|
/// <typeparam name="TCache">The cache type.</typeparam>
|
||||
|
/// <para>
|
||||
|
/// This class is not thread safe and should not be accessed in parallel.
|
||||
|
/// Doing so will result in non-idempotent results.
|
||||
|
/// </para>
|
||||
|
internal sealed class EuclideanPixelMap<TPixel, TCache> : PixelMap<TPixel> |
||||
|
where TPixel : unmanaged, IPixel<TPixel> |
||||
|
where TCache : struct, IColorIndexCache<TCache> |
||||
|
{ |
||||
|
private Rgba32[] rgbaPalette; |
||||
|
|
||||
|
// Do not make readonly. It's a mutable struct.
|
||||
|
#pragma warning disable IDE0044 // Add readonly modifier
|
||||
|
private TCache cache; |
||||
|
#pragma warning restore IDE0044 // Add readonly modifier
|
||||
|
|
||||
|
private readonly Configuration configuration; |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Initializes a new instance of the <see cref="EuclideanPixelMap{TPixel, TCache}"/> class.
|
||||
|
/// </summary>
|
||||
|
/// <param name="configuration">Specifies the settings and resources for the pixel map's operations.</param>
|
||||
|
/// <param name="palette">Defines the color palette used for pixel mapping.</param>
|
||||
|
public EuclideanPixelMap(Configuration configuration, ReadOnlyMemory<TPixel> palette) |
||||
|
{ |
||||
|
this.configuration = configuration; |
||||
|
this.Palette = palette; |
||||
|
this.rgbaPalette = new Rgba32[palette.Length]; |
||||
|
this.cache = TCache.Create(configuration.MemoryAllocator); |
||||
|
PixelOperations<TPixel>.Instance.ToRgba32(configuration, this.Palette.Span, this.rgbaPalette); |
||||
|
} |
||||
|
|
||||
|
/// <inheritdoc/>
|
||||
|
[MethodImpl(InliningOptions.ShortMethod)] |
||||
|
public override int GetClosestColor(TPixel color, out TPixel match) |
||||
|
{ |
||||
|
ref TPixel paletteRef = ref MemoryMarshal.GetReference(this.Palette.Span); |
||||
|
Rgba32 rgba = color.ToRgba32(); |
||||
|
|
||||
|
if (this.cache.TryGetValue(rgba, out short index)) |
||||
|
{ |
||||
|
match = Unsafe.Add(ref paletteRef, (ushort)index); |
||||
|
return index; |
||||
|
} |
||||
|
|
||||
|
return this.GetClosestColorSlow(rgba, ref paletteRef, out match); |
||||
|
} |
||||
|
|
||||
|
/// <inheritdoc/>
|
||||
|
public override void Clear(ReadOnlyMemory<TPixel> palette) |
||||
|
{ |
||||
|
this.Palette = palette; |
||||
|
this.rgbaPalette = new Rgba32[palette.Length]; |
||||
|
PixelOperations<TPixel>.Instance.ToRgba32(this.configuration, this.Palette.Span, this.rgbaPalette); |
||||
|
this.cache.Clear(); |
||||
|
} |
||||
|
|
||||
|
[MethodImpl(InliningOptions.ColdPath)] |
||||
|
private int GetClosestColorSlow(Rgba32 rgba, ref TPixel paletteRef, out TPixel match) |
||||
|
{ |
||||
|
// Loop through the palette and find the nearest match.
|
||||
|
int index = 0; |
||||
|
float leastDistance = float.MaxValue; |
||||
|
for (int i = 0; i < this.rgbaPalette.Length; i++) |
||||
|
{ |
||||
|
Rgba32 candidate = this.rgbaPalette[i]; |
||||
|
if (candidate.PackedValue == rgba.PackedValue) |
||||
|
{ |
||||
|
index = i; |
||||
|
break; |
||||
|
} |
||||
|
|
||||
|
float distance = DistanceSquared(rgba, candidate); |
||||
|
if (distance == 0) |
||||
|
{ |
||||
|
index = i; |
||||
|
break; |
||||
|
} |
||||
|
|
||||
|
if (distance < leastDistance) |
||||
|
{ |
||||
|
index = i; |
||||
|
leastDistance = distance; |
||||
|
} |
||||
|
} |
||||
|
|
||||
|
// Now I have the index, pop it into the cache for next time
|
||||
|
_ = this.cache.TryAdd(rgba, (short)index); |
||||
|
match = Unsafe.Add(ref paletteRef, (uint)index); |
||||
|
|
||||
|
return index; |
||||
|
} |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Returns the Euclidean distance squared between two specified points.
|
||||
|
/// </summary>
|
||||
|
/// <param name="a">The first point.</param>
|
||||
|
/// <param name="b">The second point.</param>
|
||||
|
/// <returns>The distance squared.</returns>
|
||||
|
[MethodImpl(InliningOptions.ShortMethod)] |
||||
|
private static float DistanceSquared(Rgba32 a, Rgba32 b) |
||||
|
{ |
||||
|
float deltaR = a.R - b.R; |
||||
|
float deltaG = a.G - b.G; |
||||
|
float deltaB = a.B - b.B; |
||||
|
float deltaA = a.A - b.A; |
||||
|
return (deltaR * deltaR) + (deltaG * deltaG) + (deltaB * deltaB) + (deltaA * deltaA); |
||||
|
} |
||||
|
|
||||
|
/// <inheritdoc/>
|
||||
|
public override void Dispose() => this.cache.Dispose(); |
||||
|
} |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Represents a map of colors to indices.
|
||||
|
/// </summary>
|
||||
|
/// <typeparam name="TPixel">The pixel format.</typeparam>
|
||||
|
internal abstract class PixelMap<TPixel> : IDisposable |
||||
|
where TPixel : unmanaged, IPixel<TPixel> |
||||
|
{ |
||||
|
/// <summary>
|
||||
|
/// Gets the color palette of this <see cref="PixelMap{TPixel}"/>.
|
||||
|
/// </summary>
|
||||
|
public ReadOnlyMemory<TPixel> Palette { get; private protected set; } |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Returns the closest color in the palette and the index of that pixel.
|
||||
|
/// </summary>
|
||||
|
/// <param name="color">The color to match.</param>
|
||||
|
/// <param name="match">The matched color.</param>
|
||||
|
/// <returns>
|
||||
|
/// The <see cref="int"/> index.
|
||||
|
/// </returns>
|
||||
|
public abstract int GetClosestColor(TPixel color, out TPixel match); |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Clears the map, resetting it to use the given palette.
|
||||
|
/// </summary>
|
||||
|
/// <param name="palette">The color palette to map from.</param>
|
||||
|
public abstract void Clear(ReadOnlyMemory<TPixel> palette); |
||||
|
|
||||
|
/// <inheritdoc/>
|
||||
|
public abstract void Dispose(); |
||||
|
} |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// A factory for creating <see cref="PixelMap{TPixel}"/> instances.
|
||||
|
/// </summary>
|
||||
|
internal static class PixelMapFactory |
||||
|
{ |
||||
|
/// <summary>
|
||||
|
/// Creates a new <see cref="PixelMap{TPixel}"/> instance.
|
||||
|
/// </summary>
|
||||
|
/// <typeparam name="TPixel">The pixel format.</typeparam>
|
||||
|
/// <param name="configuration">The configuration.</param>
|
||||
|
/// <param name="palette">The color palette to map from.</param>
|
||||
|
/// <param name="colorMatchingMode">The color matching mode.</param>
|
||||
|
/// <returns>
|
||||
|
/// The <see cref="PixelMap{TPixel}"/>.
|
||||
|
/// </returns>
|
||||
|
public static PixelMap<TPixel> Create<TPixel>( |
||||
|
Configuration configuration, |
||||
|
ReadOnlyMemory<TPixel> palette, |
||||
|
ColorMatchingMode colorMatchingMode) |
||||
|
where TPixel : unmanaged, IPixel<TPixel> => colorMatchingMode switch |
||||
|
{ |
||||
|
ColorMatchingMode.Hybrid => new EuclideanPixelMap<TPixel, HybridCache>(configuration, palette), |
||||
|
ColorMatchingMode.Exact => new EuclideanPixelMap<TPixel, NullCache>(configuration, palette), |
||||
|
_ => new EuclideanPixelMap<TPixel, CoarseCache>(configuration, palette), |
||||
|
}; |
||||
|
} |
||||
@ -1,545 +0,0 @@ |
|||||
// Copyright (c) Six Labors.
|
|
||||
// Licensed under the Six Labors Split License.
|
|
||||
|
|
||||
using System.Buffers; |
|
||||
using System.Numerics; |
|
||||
using System.Runtime.CompilerServices; |
|
||||
using System.Runtime.InteropServices; |
|
||||
using SixLabors.ImageSharp.Memory; |
|
||||
using SixLabors.ImageSharp.PixelFormats; |
|
||||
|
|
||||
namespace SixLabors.ImageSharp.Processing.Processors.Quantization; |
|
||||
|
|
||||
/// <summary>
|
|
||||
/// Gets the closest color to the supplied color based upon the Euclidean distance.
|
|
||||
/// </summary>
|
|
||||
/// <typeparam name="TPixel">The pixel format.</typeparam>
|
|
||||
/// <para>
|
|
||||
/// This class is not thread safe and should not be accessed in parallel.
|
|
||||
/// Doing so will result in non-idempotent results.
|
|
||||
/// </para>
|
|
||||
internal sealed class EuclideanPixelMap<TPixel> : IDisposable |
|
||||
where TPixel : unmanaged, IPixel<TPixel> |
|
||||
{ |
|
||||
private Rgba32[] rgbaPalette; |
|
||||
private readonly HybridColorDistanceCache cache; |
|
||||
private readonly Configuration configuration; |
|
||||
|
|
||||
/// <summary>
|
|
||||
/// Initializes a new instance of the <see cref="EuclideanPixelMap{TPixel}"/> class.
|
|
||||
/// </summary>
|
|
||||
/// <param name="configuration">The configuration.</param>
|
|
||||
/// <param name="palette">The color palette to map from.</param>
|
|
||||
public EuclideanPixelMap(Configuration configuration, ReadOnlyMemory<TPixel> palette) |
|
||||
{ |
|
||||
this.configuration = configuration; |
|
||||
this.Palette = palette; |
|
||||
this.rgbaPalette = new Rgba32[palette.Length]; |
|
||||
this.cache = new HybridColorDistanceCache(configuration.MemoryAllocator); |
|
||||
PixelOperations<TPixel>.Instance.ToRgba32(configuration, this.Palette.Span, this.rgbaPalette); |
|
||||
} |
|
||||
|
|
||||
/// <summary>
|
|
||||
/// Gets the color palette of this <see cref="EuclideanPixelMap{TPixel}"/>.
|
|
||||
/// The palette memory is owned by the palette source that created it.
|
|
||||
/// </summary>
|
|
||||
public ReadOnlyMemory<TPixel> Palette { get; private set; } |
|
||||
|
|
||||
/// <summary>
|
|
||||
/// Returns the closest color in the palette and the index of that pixel.
|
|
||||
/// The palette contents must match the one used in the constructor.
|
|
||||
/// </summary>
|
|
||||
/// <param name="color">The color to match.</param>
|
|
||||
/// <param name="match">The matched color.</param>
|
|
||||
/// <param name="transparencyThreshold">The transparency threshold.</param>
|
|
||||
/// <returns>The <see cref="int"/> index.</returns>
|
|
||||
[MethodImpl(MethodImplOptions.AggressiveInlining)] |
|
||||
public int GetClosestColor(TPixel color, out TPixel match, short transparencyThreshold = -1) |
|
||||
{ |
|
||||
ref TPixel paletteRef = ref MemoryMarshal.GetReference(this.Palette.Span); |
|
||||
Rgba32 rgba = color.ToRgba32(); |
|
||||
|
|
||||
if (transparencyThreshold > -1 && rgba.A < transparencyThreshold) |
|
||||
{ |
|
||||
rgba = default; |
|
||||
} |
|
||||
|
|
||||
// Check if the color is in the lookup table
|
|
||||
if (this.cache.TryGetValue(rgba, out short index)) |
|
||||
{ |
|
||||
match = Unsafe.Add(ref paletteRef, (ushort)index); |
|
||||
return index; |
|
||||
} |
|
||||
|
|
||||
return this.GetClosestColorSlow(rgba, ref paletteRef, out match); |
|
||||
} |
|
||||
|
|
||||
/// <summary>
|
|
||||
/// Clears the map, resetting it to use the given palette.
|
|
||||
/// </summary>
|
|
||||
/// <param name="palette">The color palette to map from.</param>
|
|
||||
public void Clear(ReadOnlyMemory<TPixel> palette) |
|
||||
{ |
|
||||
this.Palette = palette; |
|
||||
this.rgbaPalette = new Rgba32[palette.Length]; |
|
||||
PixelOperations<TPixel>.Instance.ToRgba32(this.configuration, this.Palette.Span, this.rgbaPalette); |
|
||||
this.cache.Clear(); |
|
||||
} |
|
||||
|
|
||||
[MethodImpl(MethodImplOptions.NoInlining)] |
|
||||
private int GetClosestColorSlow(Rgba32 rgba, ref TPixel paletteRef, out TPixel match) |
|
||||
{ |
|
||||
// Loop through the palette and find the nearest match.
|
|
||||
int index = 0; |
|
||||
float leastDistance = float.MaxValue; |
|
||||
for (int i = 0; i < this.rgbaPalette.Length; i++) |
|
||||
{ |
|
||||
Rgba32 candidate = this.rgbaPalette[i]; |
|
||||
if (candidate.PackedValue == rgba.PackedValue) |
|
||||
{ |
|
||||
index = i; |
|
||||
break; |
|
||||
} |
|
||||
|
|
||||
float distance = DistanceSquared(rgba, candidate); |
|
||||
if (distance == 0) |
|
||||
{ |
|
||||
index = i; |
|
||||
break; |
|
||||
} |
|
||||
|
|
||||
if (distance < leastDistance) |
|
||||
{ |
|
||||
index = i; |
|
||||
leastDistance = distance; |
|
||||
} |
|
||||
} |
|
||||
|
|
||||
// Now I have the index, pop it into the cache for next time
|
|
||||
this.cache.Add(rgba, (short)index); |
|
||||
match = Unsafe.Add(ref paletteRef, (uint)index); |
|
||||
|
|
||||
return index; |
|
||||
} |
|
||||
|
|
||||
/// <summary>
|
|
||||
/// Returns the Euclidean distance squared between two specified points.
|
|
||||
/// </summary>
|
|
||||
/// <param name="a">The first point.</param>
|
|
||||
/// <param name="b">The second point.</param>
|
|
||||
/// <returns>The distance squared.</returns>
|
|
||||
[MethodImpl(MethodImplOptions.AggressiveInlining)] |
|
||||
private static float DistanceSquared(Rgba32 a, Rgba32 b) |
|
||||
{ |
|
||||
float deltaR = a.R - b.R; |
|
||||
float deltaG = a.G - b.G; |
|
||||
float deltaB = a.B - b.B; |
|
||||
float deltaA = a.A - b.A; |
|
||||
return (deltaR * deltaR) + (deltaG * deltaG) + (deltaB * deltaB) + (deltaA * deltaA); |
|
||||
} |
|
||||
|
|
||||
public void Dispose() => this.cache.Dispose(); |
|
||||
|
|
||||
/// <summary>
|
|
||||
/// A hybrid color distance cache that combines a small, fixed-capacity exact-match dictionary
|
|
||||
/// (ExactCache, ~4–5 KB for up to 512 entries) with a coarse lookup table (CoarseCache) for 5,5,5,6 precision.
|
|
||||
/// </summary>
|
|
||||
/// <remarks>
|
|
||||
/// ExactCache provides O(1) lookup for common cases using a simple 256-entry hash-based dictionary, while CoarseCache
|
|
||||
/// quantizes RGB channels to 5 bits (yielding 32^3 buckets) and alpha to 6 bits, storing up to 4 alpha entries per bucket
|
|
||||
/// (a design chosen based on probability theory to capture most real-world variations) for a total memory footprint of
|
|
||||
/// roughly 576 KB. Lookups and insertions are performed in constant time, making the overall design both fast and memory-predictable.
|
|
||||
/// </remarks>
|
|
||||
#pragma warning disable CA1001 // Types that own disposable fields should be disposable
|
|
||||
// https://github.com/dotnet/roslyn-analyzers/issues/6151
|
|
||||
private readonly unsafe struct HybridColorDistanceCache : IDisposable |
|
||||
#pragma warning restore CA1001 // Types that own disposable fields should be disposable
|
|
||||
{ |
|
||||
private readonly CoarseCache coarseCache; |
|
||||
private readonly ExactCache exactCache; |
|
||||
|
|
||||
public HybridColorDistanceCache(MemoryAllocator allocator) |
|
||||
{ |
|
||||
this.exactCache = new ExactCache(allocator); |
|
||||
this.coarseCache = new CoarseCache(allocator); |
|
||||
} |
|
||||
|
|
||||
[MethodImpl(MethodImplOptions.AggressiveInlining)] |
|
||||
public readonly void Add(Rgba32 color, short index) |
|
||||
{ |
|
||||
if (this.exactCache.TryAdd(color.PackedValue, index)) |
|
||||
{ |
|
||||
return; |
|
||||
} |
|
||||
|
|
||||
this.coarseCache.Add(color, index); |
|
||||
} |
|
||||
|
|
||||
[MethodImpl(MethodImplOptions.AggressiveInlining)] |
|
||||
public readonly bool TryGetValue(Rgba32 color, out short match) |
|
||||
{ |
|
||||
if (this.exactCache.TryGetValue(color.PackedValue, out match)) |
|
||||
{ |
|
||||
return true; // Exact match found
|
|
||||
} |
|
||||
|
|
||||
if (this.coarseCache.TryGetValue(color, out match)) |
|
||||
{ |
|
||||
return true; // Coarse match found
|
|
||||
} |
|
||||
|
|
||||
match = -1; |
|
||||
return false; |
|
||||
} |
|
||||
|
|
||||
public readonly void Clear() |
|
||||
{ |
|
||||
this.exactCache.Clear(); |
|
||||
this.coarseCache.Clear(); |
|
||||
} |
|
||||
|
|
||||
public void Dispose() |
|
||||
{ |
|
||||
this.exactCache.Dispose(); |
|
||||
this.coarseCache.Dispose(); |
|
||||
} |
|
||||
} |
|
||||
|
|
||||
/// <summary>
|
|
||||
/// A fixed-capacity dictionary with exactly 512 entries mapping a <see cref="uint"/> key
|
|
||||
/// to a <see cref="short"/> value.
|
|
||||
/// </summary>
|
|
||||
/// <remarks>
|
|
||||
/// The dictionary is implemented using a fixed array of 512 buckets and an entries array
|
|
||||
/// of the same size. The bucket for a key is computed as (key & 0x1FF), and collisions are
|
|
||||
/// resolved through a linked chain stored in the <see cref="Entry.Next"/> field.
|
|
||||
/// The overall memory usage is approximately 4–5 KB. Both lookup and insertion operations are,
|
|
||||
/// on average, O(1) since the bucket is determined via a simple bitmask and collision chains are
|
|
||||
/// typically very short; in the worst-case, the number of iterations is bounded by 256.
|
|
||||
/// This guarantees highly efficient and predictable performance for small, fixed-size color palettes.
|
|
||||
/// </remarks>
|
|
||||
internal sealed unsafe class ExactCache : IDisposable |
|
||||
{ |
|
||||
// Buckets array: each bucket holds the index (0-based) into the entries array
|
|
||||
// of the first entry in the chain, or -1 if empty.
|
|
||||
private readonly IMemoryOwner<short> bucketsOwner; |
|
||||
private MemoryHandle bucketsHandle; |
|
||||
private short* buckets; |
|
||||
|
|
||||
// Entries array: stores up to 256 entries.
|
|
||||
private readonly IMemoryOwner<Entry> entriesOwner; |
|
||||
private MemoryHandle entriesHandle; |
|
||||
private Entry* entries; |
|
||||
|
|
||||
public const int Capacity = 512; |
|
||||
|
|
||||
public ExactCache(MemoryAllocator allocator) |
|
||||
{ |
|
||||
this.Count = 0; |
|
||||
|
|
||||
// Allocate exactly 512 ints for buckets.
|
|
||||
this.bucketsOwner = allocator.Allocate<short>(Capacity, AllocationOptions.Clean); |
|
||||
Span<short> bucketSpan = this.bucketsOwner.GetSpan(); |
|
||||
bucketSpan.Fill(-1); |
|
||||
this.bucketsHandle = this.bucketsOwner.Memory.Pin(); |
|
||||
this.buckets = (short*)this.bucketsHandle.Pointer; |
|
||||
|
|
||||
// Allocate exactly 512 entries.
|
|
||||
this.entriesOwner = allocator.Allocate<Entry>(Capacity, AllocationOptions.Clean); |
|
||||
this.entriesHandle = this.entriesOwner.Memory.Pin(); |
|
||||
this.entries = (Entry*)this.entriesHandle.Pointer; |
|
||||
} |
|
||||
|
|
||||
public int Count { get; private set; } |
|
||||
|
|
||||
/// <summary>
|
|
||||
/// Adds a key/value pair to the dictionary.
|
|
||||
/// If the key already exists, the dictionary is left unchanged.
|
|
||||
/// </summary>
|
|
||||
/// <param name="key">The key to add.</param>
|
|
||||
/// <param name="value">The value to add.</param>
|
|
||||
/// <returns><see langword="true"/> if the key was added; otherwise, <see langword="false"/>.</returns>
|
|
||||
[MethodImpl(MethodImplOptions.AggressiveInlining)] |
|
||||
public bool TryAdd(uint key, short value) |
|
||||
{ |
|
||||
if (this.Count == Capacity) |
|
||||
{ |
|
||||
return false; // Dictionary is full.
|
|
||||
} |
|
||||
|
|
||||
// The key is a 32-bit unsigned integer representing an RGBA color, where the bytes are laid out as R|G|B|A
|
|
||||
// (with R in the most significant byte and A in the least significant).
|
|
||||
// To compute the bucket index:
|
|
||||
// 1. (key >> 16) extracts the top 16 bits, effectively giving us the R and G channels.
|
|
||||
// 2. (key >> 8) shifts the key right by 8 bits, bringing R, G, and B into the lower 24 bits (dropping A).
|
|
||||
// 3. XORing these two values with the original key mixes bits from all four channels (R, G, B, and A),
|
|
||||
// which helps to counteract situations where one or more channels have a limited range.
|
|
||||
// 4. Finally, we apply a bitmask of 0x1FF to keep only the lowest 9 bits, ensuring the result is between 0 and 511,
|
|
||||
// which corresponds to our fixed bucket count of 512.
|
|
||||
int bucket = (int)(((key >> 16) ^ (key >> 8) ^ key) & 0x1FF); |
|
||||
int i = this.buckets[bucket]; |
|
||||
|
|
||||
// Traverse the collision chain.
|
|
||||
Entry* entries = this.entries; |
|
||||
while (i != -1) |
|
||||
{ |
|
||||
Entry e = entries[i]; |
|
||||
if (e.Key == key) |
|
||||
{ |
|
||||
// Key already exists; do not overwrite.
|
|
||||
return false; |
|
||||
} |
|
||||
|
|
||||
i = e.Next; |
|
||||
} |
|
||||
|
|
||||
short index = (short)this.Count; |
|
||||
this.Count++; |
|
||||
|
|
||||
// Insert the new entry:
|
|
||||
entries[index].Key = key; |
|
||||
entries[index].Value = value; |
|
||||
|
|
||||
// Link this new entry into the bucket chain.
|
|
||||
entries[index].Next = this.buckets[bucket]; |
|
||||
this.buckets[bucket] = index; |
|
||||
return true; |
|
||||
} |
|
||||
|
|
||||
/// <summary>
|
|
||||
/// Tries to retrieve the value associated with the specified key.
|
|
||||
/// Returns true if the key is found; otherwise, returns false.
|
|
||||
/// </summary>
|
|
||||
/// <param name="key">The key to search for.</param>
|
|
||||
/// <param name="value">The value associated with the key, if found.</param>
|
|
||||
/// <returns><see langword="true"/> if the key is found; otherwise, <see langword="false"/>.</returns>
|
|
||||
[MethodImpl(MethodImplOptions.AggressiveInlining)] |
|
||||
public bool TryGetValue(uint key, out short value) |
|
||||
{ |
|
||||
int bucket = (int)(((key >> 16) ^ (key >> 8) ^ key) & 0x1FF); |
|
||||
int i = this.buckets[bucket]; |
|
||||
|
|
||||
// If the bucket is empty, return immediately.
|
|
||||
if (i == -1) |
|
||||
{ |
|
||||
value = -1; |
|
||||
return false; |
|
||||
} |
|
||||
|
|
||||
// Traverse the chain.
|
|
||||
Entry* entries = this.entries; |
|
||||
do |
|
||||
{ |
|
||||
Entry e = entries[i]; |
|
||||
if (e.Key == key) |
|
||||
{ |
|
||||
value = e.Value; |
|
||||
return true; |
|
||||
} |
|
||||
|
|
||||
i = e.Next; |
|
||||
} |
|
||||
while (i != -1); |
|
||||
|
|
||||
value = -1; |
|
||||
return false; |
|
||||
} |
|
||||
|
|
||||
/// <summary>
|
|
||||
/// Clears the dictionary.
|
|
||||
/// </summary>
|
|
||||
public void Clear() |
|
||||
{ |
|
||||
Span<short> bucketSpan = this.bucketsOwner.GetSpan(); |
|
||||
bucketSpan.Fill(-1); |
|
||||
this.Count = 0; |
|
||||
} |
|
||||
|
|
||||
public void Dispose() |
|
||||
{ |
|
||||
this.bucketsHandle.Dispose(); |
|
||||
this.bucketsOwner.Dispose(); |
|
||||
this.entriesHandle.Dispose(); |
|
||||
this.entriesOwner.Dispose(); |
|
||||
this.buckets = null; |
|
||||
this.entries = null; |
|
||||
} |
|
||||
|
|
||||
private struct Entry |
|
||||
{ |
|
||||
public uint Key; // The key (packed RGBA)
|
|
||||
public short Value; // The value; -1 means unused.
|
|
||||
public short Next; // Index of the next entry in the chain, or -1 if none.
|
|
||||
} |
|
||||
} |
|
||||
|
|
||||
/// <summary>
|
|
||||
/// <para>
|
|
||||
/// CoarseCache is a fast, low-memory lookup structure for caching palette indices associated with RGBA values,
|
|
||||
/// using a quantized representation of 5,5,5,6 (RGB: 5 bits each, Alpha: 6 bits).
|
|
||||
/// </para>
|
|
||||
/// <para>
|
|
||||
/// The cache quantizes the RGB channels to 5 bits each, resulting in 32 levels per channel and a total of 32³ = 32,768 buckets.
|
|
||||
/// Each bucket is represented by an <see cref="AlphaBucket"/>, which holds a small, inline array of alpha entries.
|
|
||||
/// Each alpha entry stores the alpha value quantized to 6 bits (0–63) along with a palette index (a 16-bit value).
|
|
||||
/// </para>
|
|
||||
/// <para>
|
|
||||
/// Performance Characteristics:
|
|
||||
/// - Lookup: O(1) for computing the bucket index from the RGB channels, plus a small constant time (up to 4 iterations)
|
|
||||
/// to search through the alpha entries in the bucket.
|
|
||||
/// - Insertion: O(1) for bucket index computation and a quick linear search over a very small (fixed) number of entries.
|
|
||||
/// </para>
|
|
||||
/// <para>
|
|
||||
/// Memory Characteristics:
|
|
||||
/// - The cache consists of 32,768 buckets.
|
|
||||
/// - Each <see cref="AlphaBucket"/> is implemented using an inline array with a capacity of 4 entries.
|
|
||||
/// - Each bucket occupies approximately 18 bytes.
|
|
||||
/// - Overall, the buckets occupy roughly 32,768 × 18 = 589,824 bytes (576 KB).
|
|
||||
/// </para>
|
|
||||
/// <para>
|
|
||||
/// This design provides nearly constant-time lookup and insertion with minimal memory usage,
|
|
||||
/// making it ideal for applications such as color distance caching in images with a limited palette (up to 256 entries).
|
|
||||
/// </para>
|
|
||||
/// </summary>
|
|
||||
internal sealed unsafe class CoarseCache : IDisposable |
|
||||
{ |
|
||||
// Use 5 bits per channel for R, G, and B: 32 levels each.
|
|
||||
// Total buckets = 32^3 = 32768.
|
|
||||
private const int RgbBits = 5; |
|
||||
private const int BucketCount = 1 << (RgbBits * 3); // 32768
|
|
||||
private readonly IMemoryOwner<AlphaBucket> bucketsOwner; |
|
||||
private readonly AlphaBucket* buckets; |
|
||||
private MemoryHandle bucketHandle; |
|
||||
|
|
||||
public CoarseCache(MemoryAllocator allocator) |
|
||||
{ |
|
||||
this.bucketsOwner = allocator.Allocate<AlphaBucket>(BucketCount, AllocationOptions.Clean); |
|
||||
this.bucketHandle = this.bucketsOwner.Memory.Pin(); |
|
||||
this.buckets = (AlphaBucket*)this.bucketHandle.Pointer; |
|
||||
} |
|
||||
|
|
||||
[MethodImpl(MethodImplOptions.AggressiveInlining)] |
|
||||
private static int GetBucketIndex(byte r, byte g, byte b) |
|
||||
{ |
|
||||
int qr = r >> (8 - RgbBits); |
|
||||
int qg = g >> (8 - RgbBits); |
|
||||
int qb = b >> (8 - RgbBits); |
|
||||
|
|
||||
// Combine the quantized channels into a single index.
|
|
||||
return (qr << (RgbBits * 2)) | (qg << RgbBits) | qb; |
|
||||
} |
|
||||
|
|
||||
[MethodImpl(MethodImplOptions.AggressiveInlining)] |
|
||||
private static byte QuantizeAlpha(byte a) |
|
||||
|
|
||||
// Quantize to 6 bits: shift right by (8 - 6) = 2 bits.
|
|
||||
=> (byte)(a >> 2); |
|
||||
|
|
||||
public void Add(Rgba32 color, short paletteIndex) |
|
||||
{ |
|
||||
int bucketIndex = GetBucketIndex(color.R, color.G, color.B); |
|
||||
byte quantAlpha = QuantizeAlpha(color.A); |
|
||||
this.buckets[bucketIndex].Add(quantAlpha, paletteIndex); |
|
||||
} |
|
||||
|
|
||||
public void Dispose() |
|
||||
{ |
|
||||
this.bucketHandle.Dispose(); |
|
||||
this.bucketsOwner.Dispose(); |
|
||||
} |
|
||||
|
|
||||
public bool TryGetValue(Rgba32 color, out short paletteIndex) |
|
||||
{ |
|
||||
int bucketIndex = GetBucketIndex(color.R, color.G, color.B); |
|
||||
byte quantAlpha = QuantizeAlpha(color.A); |
|
||||
return this.buckets[bucketIndex].TryGetValue(quantAlpha, out paletteIndex); |
|
||||
} |
|
||||
|
|
||||
public void Clear() |
|
||||
{ |
|
||||
Span<AlphaBucket> bucketsSpan = this.bucketsOwner.GetSpan(); |
|
||||
bucketsSpan.Clear(); |
|
||||
} |
|
||||
|
|
||||
public struct AlphaEntry |
|
||||
{ |
|
||||
// Store the alpha value quantized to 6 bits (0..63)
|
|
||||
public byte QuantizedAlpha; |
|
||||
public short PaletteIndex; |
|
||||
} |
|
||||
|
|
||||
public struct AlphaBucket |
|
||||
{ |
|
||||
// Fixed capacity for alpha entries in this bucket.
|
|
||||
// We choose a capacity of 4 for several reasons:
|
|
||||
//
|
|
||||
// 1. The alpha channel is quantized to 6 bits, so there are 64 possible distinct values.
|
|
||||
// In the worst-case, a given RGB bucket might encounter up to 64 different alpha values.
|
|
||||
//
|
|
||||
// 2. However, in practice (based on probability theory and typical image data),
|
|
||||
// the number of unique alpha values that actually occur for a given quantized RGB
|
|
||||
// bucket is usually very small. If you randomly sample 4 values out of 64,
|
|
||||
// the probability that these 4 samples are all unique is high if the distribution
|
|
||||
// of alpha values is skewed or if only a few alpha values are used.
|
|
||||
//
|
|
||||
// 3. Statistically, for many real-world images, most RGB buckets will have only a couple
|
|
||||
// of unique alpha values. Allocating 4 slots per bucket provides a good trade-off:
|
|
||||
// it captures the common-case scenario while keeping overall memory usage low.
|
|
||||
//
|
|
||||
// 4. Even if more than 4 unique alpha values occur in a bucket,
|
|
||||
// our design overwrites the first entry. This behavior gives us some "wriggle room"
|
|
||||
// while preserving the most frequently encountered or most recent values.
|
|
||||
public const int Capacity = 4; |
|
||||
public byte Count; |
|
||||
private InlineArray4<AlphaEntry> entries; |
|
||||
|
|
||||
[MethodImpl(MethodImplOptions.AggressiveInlining)] |
|
||||
public bool TryGetValue(byte quantizedAlpha, out short paletteIndex) |
|
||||
{ |
|
||||
for (int i = 0; i < this.Count; i++) |
|
||||
{ |
|
||||
ref AlphaEntry entry = ref this.entries[i]; |
|
||||
if (entry.QuantizedAlpha == quantizedAlpha) |
|
||||
{ |
|
||||
paletteIndex = entry.PaletteIndex; |
|
||||
return true; |
|
||||
} |
|
||||
} |
|
||||
|
|
||||
paletteIndex = -1; |
|
||||
return false; |
|
||||
} |
|
||||
|
|
||||
[MethodImpl(MethodImplOptions.AggressiveInlining)] |
|
||||
public void Add(byte quantizedAlpha, short paletteIndex) |
|
||||
{ |
|
||||
// Check for an existing entry with the same quantized alpha.
|
|
||||
for (int i = 0; i < this.Count; i++) |
|
||||
{ |
|
||||
ref AlphaEntry entry = ref this.entries[i]; |
|
||||
if (entry.QuantizedAlpha == quantizedAlpha) |
|
||||
{ |
|
||||
// Update palette index if found.
|
|
||||
entry.PaletteIndex = paletteIndex; |
|
||||
return; |
|
||||
} |
|
||||
} |
|
||||
|
|
||||
// If there's room, add a new entry.
|
|
||||
if (this.Count < Capacity) |
|
||||
{ |
|
||||
ref AlphaEntry newEntry = ref this.entries[this.Count]; |
|
||||
newEntry.QuantizedAlpha = quantizedAlpha; |
|
||||
newEntry.PaletteIndex = paletteIndex; |
|
||||
this.Count++; |
|
||||
} |
|
||||
else |
|
||||
{ |
|
||||
// Bucket is full. Overwrite the first entry to give us some wriggle room.
|
|
||||
this.entries[0].QuantizedAlpha = quantizedAlpha; |
|
||||
this.entries[0].PaletteIndex = paletteIndex; |
|
||||
} |
|
||||
} |
|
||||
} |
|
||||
} |
|
||||
} |
|
||||
@ -0,0 +1,491 @@ |
|||||
|
// Copyright (c) Six Labors.
|
||||
|
// Licensed under the Six Labors Split License.
|
||||
|
|
||||
|
using System.Buffers; |
||||
|
using System.Runtime.CompilerServices; |
||||
|
using SixLabors.ImageSharp.Memory; |
||||
|
using SixLabors.ImageSharp.PixelFormats; |
||||
|
|
||||
|
namespace SixLabors.ImageSharp.Processing.Processors.Quantization; |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Represents a cache used for efficiently retrieving palette indices for colors.
|
||||
|
/// </summary>
|
||||
|
internal interface IColorIndexCache : IDisposable |
||||
|
{ |
||||
|
/// <summary>
|
||||
|
/// Adds a color to the cache.
|
||||
|
/// </summary>
|
||||
|
/// <param name="color">The color to add.</param>
|
||||
|
/// <param name="value">The index of the color in the palette.</param>
|
||||
|
/// <returns>
|
||||
|
/// <see langword="true"/> if the color was added; otherwise, <see langword="false"/>.
|
||||
|
/// </returns>
|
||||
|
public bool TryAdd(Rgba32 color, short value); |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Gets the index of the color in the palette.
|
||||
|
/// </summary>
|
||||
|
/// <param name="color">The color to get the index for.</param>
|
||||
|
/// <param name="value">The index of the color in the palette.</param>
|
||||
|
/// <returns>
|
||||
|
/// <see langword="true"/> if the color is in the palette; otherwise, <see langword="false"/>.
|
||||
|
/// </returns>
|
||||
|
public bool TryGetValue(Rgba32 color, out short value); |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Clears the cache.
|
||||
|
/// </summary>
|
||||
|
public void Clear(); |
||||
|
} |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Represents a cache used for efficiently retrieving palette indices for colors.
|
||||
|
/// </summary>
|
||||
|
/// <typeparam name="T">The type of the cache.</typeparam>
|
||||
|
internal interface IColorIndexCache<T> : IColorIndexCache |
||||
|
where T : struct, IColorIndexCache |
||||
|
{ |
||||
|
/// <summary>
|
||||
|
/// Creates a new instance of the cache.
|
||||
|
/// </summary>
|
||||
|
/// <param name="allocator">The memory allocator to use.</param>
|
||||
|
/// <returns>
|
||||
|
/// The new instance of the cache.
|
||||
|
/// </returns>
|
||||
|
public static abstract T Create(MemoryAllocator allocator); |
||||
|
} |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// A hybrid color distance cache that combines a small, fixed-capacity exact-match dictionary
|
||||
|
/// (ExactCache, ~4–5 KB for up to 512 entries) with a coarse lookup table (CoarseCache) for 5,5,5,6 precision.
|
||||
|
/// </summary>
|
||||
|
/// <remarks>
|
||||
|
/// ExactCache provides O(1) lookup for common cases using a simple 256-entry hash-based dictionary, while CoarseCache
|
||||
|
/// quantizes RGB channels to 5 bits (yielding 32^3 buckets) and alpha to 6 bits, storing up to 4 alpha entries per bucket
|
||||
|
/// (a design chosen based on probability theory to capture most real-world variations) for a total memory footprint of
|
||||
|
/// roughly 576 KB. Lookups and insertions are performed in constant time, making the overall design both fast and memory-predictable.
|
||||
|
/// </remarks>
|
||||
|
internal unsafe struct HybridCache : IColorIndexCache<HybridCache> |
||||
|
{ |
||||
|
private CoarseCache coarseCache; |
||||
|
private ExactCache exactCache; |
||||
|
|
||||
|
public HybridCache(MemoryAllocator allocator) |
||||
|
{ |
||||
|
this.exactCache = ExactCache.Create(allocator); |
||||
|
this.coarseCache = CoarseCache.Create(allocator); |
||||
|
} |
||||
|
|
||||
|
/// <inheritdoc/>
|
||||
|
public static HybridCache Create(MemoryAllocator allocator) => new(allocator); |
||||
|
|
||||
|
/// <inheritdoc/>
|
||||
|
[MethodImpl(InliningOptions.ShortMethod)] |
||||
|
public bool TryAdd(Rgba32 color, short index) |
||||
|
{ |
||||
|
if (this.exactCache.TryAdd(color, index)) |
||||
|
{ |
||||
|
return true; |
||||
|
} |
||||
|
|
||||
|
return this.coarseCache.TryAdd(color, index); |
||||
|
} |
||||
|
|
||||
|
/// <inheritdoc/>
|
||||
|
[MethodImpl(InliningOptions.ShortMethod)] |
||||
|
public readonly bool TryGetValue(Rgba32 color, out short value) |
||||
|
{ |
||||
|
if (this.exactCache.TryGetValue(color, out value)) |
||||
|
{ |
||||
|
return true; |
||||
|
} |
||||
|
|
||||
|
return this.coarseCache.TryGetValue(color, out value); |
||||
|
} |
||||
|
|
||||
|
/// <inheritdoc/>
|
||||
|
public readonly void Clear() |
||||
|
{ |
||||
|
this.exactCache.Clear(); |
||||
|
this.coarseCache.Clear(); |
||||
|
} |
||||
|
|
||||
|
/// <inheritdoc/>
|
||||
|
public void Dispose() |
||||
|
{ |
||||
|
this.exactCache.Dispose(); |
||||
|
this.coarseCache.Dispose(); |
||||
|
} |
||||
|
} |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// <para>
|
||||
|
/// CoarseCache is a fast, low-memory lookup structure for caching palette indices associated with RGBA values,
|
||||
|
/// using a quantized representation of 5,5,5,6 (RGB: 5 bits each, Alpha: 6 bits).
|
||||
|
/// </para>
|
||||
|
/// <para>
|
||||
|
/// The cache quantizes the RGB channels to 5 bits each, resulting in 32 levels per channel and a total of 32³ = 32,768 buckets.
|
||||
|
/// Each bucket is represented by an <see cref="AlphaBucket"/>, which holds a small, inline array of alpha entries.
|
||||
|
/// Each alpha entry stores the alpha value quantized to 6 bits (0–63) along with a palette index (a 16-bit value).
|
||||
|
/// </para>
|
||||
|
/// <para>
|
||||
|
/// Performance Characteristics:
|
||||
|
/// - Lookup: O(1) for computing the bucket index from the RGB channels, plus a small constant time (up to 4 iterations)
|
||||
|
/// to search through the alpha entries in the bucket.
|
||||
|
/// - Insertion: O(1) for bucket index computation and a quick linear search over a very small (fixed) number of entries.
|
||||
|
/// </para>
|
||||
|
/// <para>
|
||||
|
/// Memory Characteristics:
|
||||
|
/// - The cache consists of 32,768 buckets.
|
||||
|
/// - Each <see cref="AlphaBucket"/> is implemented using an inline array with a capacity of 4 entries.
|
||||
|
/// - Each bucket occupies approximately 18 bytes.
|
||||
|
/// - Overall, the buckets occupy roughly 32,768 × 18 = 589,824 bytes (576 KB).
|
||||
|
/// </para>
|
||||
|
/// <para>
|
||||
|
/// This design provides nearly constant-time lookup and insertion with minimal memory usage,
|
||||
|
/// making it ideal for applications such as color distance caching in images with a limited palette (up to 256 entries).
|
||||
|
/// </para>
|
||||
|
/// </summary>
|
||||
|
internal unsafe struct CoarseCache : IColorIndexCache<CoarseCache> |
||||
|
{ |
||||
|
// Use 5 bits per channel for R, G, and B: 32 levels each.
|
||||
|
// Total buckets = 32^3 = 32768.
|
||||
|
private const int RgbBits = 5; |
||||
|
private const int RgbShift = 8 - RgbBits; // 3
|
||||
|
private const int BucketCount = 1 << (RgbBits * 3); // 32768
|
||||
|
private readonly IMemoryOwner<AlphaBucket> bucketsOwner; |
||||
|
private readonly AlphaBucket* buckets; |
||||
|
private MemoryHandle bucketHandle; |
||||
|
|
||||
|
private CoarseCache(MemoryAllocator allocator) |
||||
|
{ |
||||
|
this.bucketsOwner = allocator.Allocate<AlphaBucket>(BucketCount, AllocationOptions.Clean); |
||||
|
this.bucketHandle = this.bucketsOwner.Memory.Pin(); |
||||
|
this.buckets = (AlphaBucket*)this.bucketHandle.Pointer; |
||||
|
} |
||||
|
|
||||
|
/// <inheritdoc/>
|
||||
|
public static CoarseCache Create(MemoryAllocator allocator) => new(allocator); |
||||
|
|
||||
|
/// <inheritdoc/>
|
||||
|
public readonly bool TryAdd(Rgba32 color, short paletteIndex) |
||||
|
{ |
||||
|
int bucketIndex = GetBucketIndex(color.R, color.G, color.B); |
||||
|
byte quantAlpha = QuantizeAlpha(color.A); |
||||
|
this.buckets[bucketIndex].Add(quantAlpha, paletteIndex); |
||||
|
return true; |
||||
|
} |
||||
|
|
||||
|
/// <inheritdoc/>
|
||||
|
public readonly bool TryGetValue(Rgba32 color, out short paletteIndex) |
||||
|
{ |
||||
|
int bucketIndex = GetBucketIndex(color.R, color.G, color.B); |
||||
|
byte quantAlpha = QuantizeAlpha(color.A); |
||||
|
return this.buckets[bucketIndex].TryGetValue(quantAlpha, out paletteIndex); |
||||
|
} |
||||
|
|
||||
|
/// <inheritdoc/>
|
||||
|
public readonly void Clear() |
||||
|
{ |
||||
|
Span<AlphaBucket> bucketsSpan = this.bucketsOwner.GetSpan(); |
||||
|
bucketsSpan.Clear(); |
||||
|
} |
||||
|
|
||||
|
/// <inheritdoc/>
|
||||
|
public void Dispose() |
||||
|
{ |
||||
|
this.bucketHandle.Dispose(); |
||||
|
this.bucketsOwner.Dispose(); |
||||
|
} |
||||
|
|
||||
|
[MethodImpl(InliningOptions.ShortMethod)] |
||||
|
private static int GetBucketIndex(byte r, byte g, byte b) |
||||
|
{ |
||||
|
int qr = r >> RgbShift; |
||||
|
int qg = g >> RgbShift; |
||||
|
int qb = b >> RgbShift; |
||||
|
|
||||
|
// Combine the quantized channels into a single index.
|
||||
|
return (qr << (RgbBits << 1)) | (qg << RgbBits) | qb; |
||||
|
} |
||||
|
|
||||
|
[MethodImpl(InliningOptions.ShortMethod)] |
||||
|
private static byte QuantizeAlpha(byte a) |
||||
|
|
||||
|
// Quantize to 6 bits: shift right by (8 - 6) = 2 bits.
|
||||
|
=> (byte)(a >> 2); |
||||
|
|
||||
|
public struct AlphaEntry |
||||
|
{ |
||||
|
// Store the alpha value quantized to 6 bits (0..63)
|
||||
|
public byte QuantizedAlpha; |
||||
|
public short PaletteIndex; |
||||
|
} |
||||
|
|
||||
|
public struct AlphaBucket |
||||
|
{ |
||||
|
// Fixed capacity for alpha entries in this bucket.
|
||||
|
// We choose a capacity of 4 for several reasons:
|
||||
|
//
|
||||
|
// 1. The alpha channel is quantized to 6 bits, so there are 64 possible distinct values.
|
||||
|
// In the worst-case, a given RGB bucket might encounter up to 64 different alpha values.
|
||||
|
//
|
||||
|
// 2. However, in practice (based on probability theory and typical image data),
|
||||
|
// the number of unique alpha values that actually occur for a given quantized RGB
|
||||
|
// bucket is usually very small. If you randomly sample 4 values out of 64,
|
||||
|
// the probability that these 4 samples are all unique is high if the distribution
|
||||
|
// of alpha values is skewed or if only a few alpha values are used.
|
||||
|
//
|
||||
|
// 3. Statistically, for many real-world images, most RGB buckets will have only a couple
|
||||
|
// of unique alpha values. Allocating 4 slots per bucket provides a good trade-off:
|
||||
|
// it captures the common-case scenario while keeping overall memory usage low.
|
||||
|
//
|
||||
|
// 4. Even if more than 4 unique alpha values occur in a bucket,
|
||||
|
// our design overwrites the first entry. This behavior gives us some "wriggle room"
|
||||
|
// while preserving the most frequently encountered or most recent values.
|
||||
|
public const int Capacity = 4; |
||||
|
public byte Count; |
||||
|
private InlineArray4<AlphaEntry> entries; |
||||
|
|
||||
|
[MethodImpl(InliningOptions.ShortMethod)] |
||||
|
public bool TryGetValue(byte quantizedAlpha, out short paletteIndex) |
||||
|
{ |
||||
|
for (int i = 0; i < this.Count; i++) |
||||
|
{ |
||||
|
ref AlphaEntry entry = ref this.entries[i]; |
||||
|
if (entry.QuantizedAlpha == quantizedAlpha) |
||||
|
{ |
||||
|
paletteIndex = entry.PaletteIndex; |
||||
|
return true; |
||||
|
} |
||||
|
} |
||||
|
|
||||
|
paletteIndex = -1; |
||||
|
return false; |
||||
|
} |
||||
|
|
||||
|
[MethodImpl(InliningOptions.ShortMethod)] |
||||
|
public void Add(byte quantizedAlpha, short paletteIndex) |
||||
|
{ |
||||
|
// Check for an existing entry with the same quantized alpha.
|
||||
|
for (int i = 0; i < this.Count; i++) |
||||
|
{ |
||||
|
ref AlphaEntry entry = ref this.entries[i]; |
||||
|
if (entry.QuantizedAlpha == quantizedAlpha) |
||||
|
{ |
||||
|
// Update palette index if found.
|
||||
|
entry.PaletteIndex = paletteIndex; |
||||
|
return; |
||||
|
} |
||||
|
} |
||||
|
|
||||
|
// If there's room, add a new entry.
|
||||
|
if (this.Count < Capacity) |
||||
|
{ |
||||
|
ref AlphaEntry newEntry = ref this.entries[this.Count]; |
||||
|
newEntry.QuantizedAlpha = quantizedAlpha; |
||||
|
newEntry.PaletteIndex = paletteIndex; |
||||
|
this.Count++; |
||||
|
} |
||||
|
else |
||||
|
{ |
||||
|
// Bucket is full. Overwrite the first entry to give us some wriggle room.
|
||||
|
this.entries[0].QuantizedAlpha = quantizedAlpha; |
||||
|
this.entries[0].PaletteIndex = paletteIndex; |
||||
|
} |
||||
|
} |
||||
|
} |
||||
|
} |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// A fixed-capacity dictionary with exactly 512 entries mapping a <see cref="uint"/> key
|
||||
|
/// to a <see cref="short"/> value.
|
||||
|
/// </summary>
|
||||
|
/// <remarks>
|
||||
|
/// The dictionary is implemented using a fixed array of 512 buckets and an entries array
|
||||
|
/// of the same size. The bucket for a key is computed as (key & 0x1FF), and collisions are
|
||||
|
/// resolved through a linked chain stored in the <see cref="Entry.Next"/> field.
|
||||
|
/// The overall memory usage is approximately 4–5 KB. Both lookup and insertion operations are,
|
||||
|
/// on average, O(1) since the bucket is determined via a simple bitmask and collision chains are
|
||||
|
/// typically very short; in the worst-case, the number of iterations is bounded by 256.
|
||||
|
/// This guarantees highly efficient and predictable performance for small, fixed-size color palettes.
|
||||
|
/// </remarks>
|
||||
|
internal unsafe struct ExactCache : IColorIndexCache<ExactCache> |
||||
|
{ |
||||
|
// Buckets array: each bucket holds the index (0-based) into the entries array
|
||||
|
// of the first entry in the chain, or -1 if empty.
|
||||
|
private readonly IMemoryOwner<short> bucketsOwner; |
||||
|
private MemoryHandle bucketsHandle; |
||||
|
private short* buckets; |
||||
|
|
||||
|
// Entries array: stores up to 256 entries.
|
||||
|
private readonly IMemoryOwner<Entry> entriesOwner; |
||||
|
private MemoryHandle entriesHandle; |
||||
|
private Entry* entries; |
||||
|
|
||||
|
public const int Capacity = 512; |
||||
|
|
||||
|
private ExactCache(MemoryAllocator allocator) |
||||
|
{ |
||||
|
this.Count = 0; |
||||
|
|
||||
|
// Allocate exactly 512 indexes for buckets.
|
||||
|
this.bucketsOwner = allocator.Allocate<short>(Capacity, AllocationOptions.Clean); |
||||
|
Span<short> bucketSpan = this.bucketsOwner.GetSpan(); |
||||
|
bucketSpan.Fill(-1); |
||||
|
this.bucketsHandle = this.bucketsOwner.Memory.Pin(); |
||||
|
this.buckets = (short*)this.bucketsHandle.Pointer; |
||||
|
|
||||
|
// Allocate exactly 512 entries.
|
||||
|
this.entriesOwner = allocator.Allocate<Entry>(Capacity, AllocationOptions.Clean); |
||||
|
this.entriesHandle = this.entriesOwner.Memory.Pin(); |
||||
|
this.entries = (Entry*)this.entriesHandle.Pointer; |
||||
|
} |
||||
|
|
||||
|
public int Count { get; private set; } |
||||
|
|
||||
|
/// <inheritdoc/>
|
||||
|
public static ExactCache Create(MemoryAllocator allocator) => new(allocator); |
||||
|
|
||||
|
/// <inheritdoc/>
|
||||
|
[MethodImpl(InliningOptions.ShortMethod)] |
||||
|
public bool TryAdd(Rgba32 color, short value) |
||||
|
{ |
||||
|
if (this.Count == Capacity) |
||||
|
{ |
||||
|
return false; // Dictionary is full.
|
||||
|
} |
||||
|
|
||||
|
uint key = color.PackedValue; |
||||
|
|
||||
|
// The key is a 32-bit unsigned integer representing an RGBA color, where the bytes are laid out as R|G|B|A
|
||||
|
// (with R in the most significant byte and A in the least significant).
|
||||
|
// To compute the bucket index:
|
||||
|
// 1. (key >> 16) extracts the top 16 bits, effectively giving us the R and G channels.
|
||||
|
// 2. (key >> 8) shifts the key right by 8 bits, bringing R, G, and B into the lower 24 bits (dropping A).
|
||||
|
// 3. XORing these two values with the original key mixes bits from all four channels (R, G, B, and A),
|
||||
|
// which helps to counteract situations where one or more channels have a limited range.
|
||||
|
// 4. Finally, we apply a bitmask of 0x1FF to keep only the lowest 9 bits, ensuring the result is between 0 and 511,
|
||||
|
// which corresponds to our fixed bucket count of 512.
|
||||
|
int bucket = (int)(((key >> 16) ^ (key >> 8) ^ key) & 0x1FF); |
||||
|
int i = this.buckets[bucket]; |
||||
|
|
||||
|
// Traverse the collision chain.
|
||||
|
Entry* entries = this.entries; |
||||
|
while (i != -1) |
||||
|
{ |
||||
|
Entry e = entries[i]; |
||||
|
if (e.Key == key) |
||||
|
{ |
||||
|
// Key already exists; do not overwrite.
|
||||
|
return false; |
||||
|
} |
||||
|
|
||||
|
i = e.Next; |
||||
|
} |
||||
|
|
||||
|
short index = (short)this.Count; |
||||
|
this.Count++; |
||||
|
|
||||
|
// Insert the new entry:
|
||||
|
entries[index].Key = key; |
||||
|
entries[index].Value = value; |
||||
|
|
||||
|
// Link this new entry into the bucket chain.
|
||||
|
entries[index].Next = this.buckets[bucket]; |
||||
|
this.buckets[bucket] = index; |
||||
|
return true; |
||||
|
} |
||||
|
|
||||
|
/// <inheritdoc/>
|
||||
|
[MethodImpl(InliningOptions.ShortMethod)] |
||||
|
public bool TryGetValue(Rgba32 color, out short value) |
||||
|
{ |
||||
|
uint key = color.PackedValue; |
||||
|
int bucket = (int)(((key >> 16) ^ (key >> 8) ^ key) & 0x1FF); |
||||
|
int i = this.buckets[bucket]; |
||||
|
|
||||
|
// If the bucket is empty, return immediately.
|
||||
|
if (i == -1) |
||||
|
{ |
||||
|
value = -1; |
||||
|
return false; |
||||
|
} |
||||
|
|
||||
|
// Traverse the chain.
|
||||
|
Entry* entries = this.entries; |
||||
|
do |
||||
|
{ |
||||
|
Entry e = entries[i]; |
||||
|
if (e.Key == key) |
||||
|
{ |
||||
|
value = e.Value; |
||||
|
return true; |
||||
|
} |
||||
|
|
||||
|
i = e.Next; |
||||
|
} |
||||
|
while (i != -1); |
||||
|
|
||||
|
value = -1; |
||||
|
return false; |
||||
|
} |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Clears the dictionary.
|
||||
|
/// </summary>
|
||||
|
public void Clear() |
||||
|
{ |
||||
|
Span<short> bucketSpan = this.bucketsOwner.GetSpan(); |
||||
|
bucketSpan.Fill(-1); |
||||
|
this.Count = 0; |
||||
|
} |
||||
|
|
||||
|
public void Dispose() |
||||
|
{ |
||||
|
this.bucketsHandle.Dispose(); |
||||
|
this.bucketsOwner.Dispose(); |
||||
|
this.entriesHandle.Dispose(); |
||||
|
this.entriesOwner.Dispose(); |
||||
|
this.buckets = null; |
||||
|
this.entries = null; |
||||
|
} |
||||
|
|
||||
|
private struct Entry |
||||
|
{ |
||||
|
public uint Key; // The key (packed RGBA)
|
||||
|
public short Value; // The value; -1 means unused.
|
||||
|
public short Next; // Index of the next entry in the chain, or -1 if none.
|
||||
|
} |
||||
|
} |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Represents a cache that does not store any values.
|
||||
|
/// It allows adding colors, but always returns false when trying to retrieve them.
|
||||
|
/// </summary>
|
||||
|
internal readonly struct NullCache : IColorIndexCache<NullCache> |
||||
|
{ |
||||
|
/// <inheritdoc/>
|
||||
|
public static NullCache Create(MemoryAllocator allocator) => default; |
||||
|
|
||||
|
/// <inheritdoc/>
|
||||
|
public bool TryAdd(Rgba32 color, short value) => true; |
||||
|
|
||||
|
/// <inheritdoc/>
|
||||
|
public bool TryGetValue(Rgba32 color, out short value) |
||||
|
{ |
||||
|
value = -1; |
||||
|
return false; |
||||
|
} |
||||
|
|
||||
|
/// <inheritdoc/>
|
||||
|
public void Clear() |
||||
|
{ |
||||
|
} |
||||
|
|
||||
|
/// <inheritdoc/>
|
||||
|
public void Dispose() |
||||
|
{ |
||||
|
} |
||||
|
} |
||||
@ -0,0 +1,27 @@ |
|||||
|
// Copyright (c) Six Labors.
|
||||
|
// Licensed under the Six Labors Split License.
|
||||
|
|
||||
|
using SixLabors.ImageSharp.Formats; |
||||
|
using SixLabors.ImageSharp.PixelFormats; |
||||
|
|
||||
|
namespace SixLabors.ImageSharp.Processing.Processors.Quantization; |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Defines a delegate for processing a row of pixels in an image for quantization.
|
||||
|
/// </summary>
|
||||
|
/// <typeparam name="TPixel">Represents a pixel type that can be processed in a quantizing operation.</typeparam>
|
||||
|
internal interface IQuantizingPixelRowDelegate<TPixel> |
||||
|
where TPixel : unmanaged, IPixel<TPixel> |
||||
|
{ |
||||
|
/// <summary>
|
||||
|
/// Gets the transparent color mode to use when adding colors to the palette.
|
||||
|
/// </summary>
|
||||
|
public TransparentColorMode TransparentColorMode { get; } |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Processes a row of pixels for quantization.
|
||||
|
/// </summary>
|
||||
|
/// <param name="row">The row of pixels to process.</param>
|
||||
|
/// <param name="rowIndex">The index of the row being processed.</param>
|
||||
|
public void Invoke(ReadOnlySpan<TPixel> row, int rowIndex); |
||||
|
} |
||||
Loading…
Reference in new issue