Class ColorGradient

An immutable color gradient defined by two or more ColorGradientStop entries at normalized offset positions. Supports smooth interpolation and stepped (hard-transition) modes with RGB, HSV, or Oklab color space blending.

Inheritance

object

ColorGradient

Implements

IEquatable<ColorGradient>

Inherited Members

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Namespace: Scylla.Core.Util.Palette

Assembly: ScyllaCore.dll

Syntax

public sealed class ColorGradient : IEquatable<ColorGradient>

Remarks

Immutability. Once constructed, a ColorGradient cannot be modified. The constructor makes a defensive copy of the stops array and sorts them by offset. Use MutableColorGradient for runtime editing, then call Build() to produce an immutable snapshot.

Evaluation. Call Evaluate(float) with a normalized position (0-1) to get the interpolated color. Values outside [0, 1] are clamped. For Smooth, colors are interpolated in the color space specified by ColorSpace. For Stepped, the color of the lower bracketing stop is returned with no interpolation.

Performance. Stops are stored in pre-sorted parallel arrays (Colors and Offsets) for cache-friendly evaluation. Linear search is used for gradients with 8 or fewer stops; binary search for larger gradients. No heap allocations occur during Evaluate(float).

Palette integration. Use FromPalette(ColorPalette, ColorGradientMode, ColorGradientColorSpace) to create a gradient from an existing ColorPalette, or ToPalette(int) to sample a gradient into a discrete palette.

Constructors

ColorGradient(string, string, ColorGradientMode, ColorGradientColorSpace, ColorGradientStop[], ColorGradientAlphaStop[], float, float, string[])

Creates a new immutable color gradient from the specified stops.

Declaration

public ColorGradient(string name, string description, ColorGradientMode mode, ColorGradientColorSpace colorSpace, ColorGradientStop[] stops, ColorGradientAlphaStop[] alphaStops = null, float reduction = 0, float steppedReduction = 0, string[] tags = null)

Parameters

Type	Name	Description
string	name	Human-readable name. Must not be null or empty.
string	description	Short description. Null is treated as empty string.
ColorGradientMode	mode	Interpolation mode (smooth or stepped).
ColorGradientColorSpace	colorSpace	Color space for smooth interpolation.
ColorGradientStop[]	stops	Array of gradient stops. Must contain at least 2 stops with offsets in [0, 1]. A defensive copy is made and sorted by offset.
ColorGradientAlphaStop[]	alphaStops	Optional array of alpha stops for independent transparency control. Pass null to use alpha values from color stops.
float	reduction	Persisted smooth-mode "Reduction" slider value [0, 1] (editor-driven; 0 by default). Does not itself filter stops - the reducer pre-marks the IsMuted flags before the gradient is constructed; this just records the slider state.
float	steppedReduction	Persisted stepped-mode reduction value [0, 1] (editor-driven; 0 by default). Drives the band count when mode is Stepped.
string[]	tags	Optional asset-level tags (e.g. "Default", "Heat", "Sky"). A defensive copy is made; modifying the original array after construction has no effect. Null is treated as an empty tag set; null or whitespace tag entries are skipped silently.

Exceptions

Type	Condition
ArgumentException	Thrown if name is null/empty or stops has fewer than 2 elements.

Properties

AlphaStopCount

The number of alpha stops, or 0 if no independent alpha curve.

Declaration

public int AlphaStopCount { get; }

Property Value

Type	Description
int

AlphaStops

Zero-allocation span of alpha stops sorted by offset. Empty if this gradient does not have an independent alpha curve.

Declaration

public ReadOnlySpan<ColorGradientAlphaStop> AlphaStops { get; }

Property Value

Type	Description
ReadOnlySpan<ColorGradientAlphaStop>

ColorSpace

The color space used for smooth interpolation.

Declaration

public ColorGradientColorSpace ColorSpace { get; }

Property Value

Type	Description
ColorGradientColorSpace

Colors

Zero-allocation span of colors parallel to Stops.

Declaration

public ReadOnlySpan<Color> Colors { get; }

Property Value

Type	Description
ReadOnlySpan<Color>

Description

A short description of this gradient's purpose or origin.

Declaration

public string Description { get; }

Property Value

Type	Description
string

HasAlphaStops

Whether this gradient has an independent alpha stop curve. When true, the alpha channel is evaluated from AlphaStops rather than from the color stops' alpha values.

Declaration

public bool HasAlphaStops { get; }

Property Value

Type	Description
bool

Mode

The interpolation mode (smooth or stepped).

Declaration

public ColorGradientMode Mode { get; }

Property Value

Type	Description
ColorGradientMode

Name

The human-readable name of this gradient.

Declaration

public string Name { get; }

Property Value

Type	Description
string

Offsets

Zero-allocation span of offsets parallel to Stops.

Declaration

public ReadOnlySpan<float> Offsets { get; }

Property Value

Type	Description
ReadOnlySpan<float>

Reduction

Smooth-mode reduction-slider value [0, 1]. Driven by the editor's Reduction control while in Smooth; persisted on the gradient asset. The reducer translates this into per-stop IsMuted flags before this immutable instance is constructed - runtime sampling honors the resulting active-only stop set.

Declaration

public float Reduction { get; }

Property Value

Type	Description
float

SteppedReduction

Stepped-mode reduction-slider value [0, 1]. Drives the band count when sampling under Stepped: 0 yields the maximum band count (smoothest stepped look), 1 yields exactly one band per active color stop. Independent of Reduction so toggling between modes does not erase or replace the slider value stored for the inactive mode.

Declaration

public float SteppedReduction { get; }

Property Value

Type	Description
float

StopCount

The number of color stops in this gradient.

Declaration

public int StopCount { get; }

Property Value

Type	Description
int

Stops

Zero-allocation span of all stops sorted by offset.

Declaration

public ReadOnlySpan<ColorGradientStop> Stops { get; }

Property Value

Type	Description
ReadOnlySpan<ColorGradientStop>

TagCount

Gets the number of asset-level tags attached to this gradient.

Declaration

public int TagCount { get; }

Property Value

Type	Description
int

Tags

Gets a read-only span over all asset-level tag strings. Empty when no tags were supplied. Used by GetGradientsByTag(string) to group gradients by category.

Declaration

public ReadOnlySpan<string> Tags { get; }

Property Value

Type	Description
ReadOnlySpan<string>

Methods

Equals(ColorGradient)

Determines whether this gradient is equal to another. Equality is based solely on Name (case-sensitive, ordinal comparison).

Declaration

public bool Equals(ColorGradient other)

Parameters

Type	Name	Description
ColorGradient	other

Returns

Type	Description
bool

Remarks

Two gradients with the same name but different stops, modes, or color spaces are considered equal. When using ColorGradient as a key in hash-based collections (e.g., Dictionary, HashSet), be aware that a second gradient with the same name will silently replace the first.

Equals(object)

Declaration

public override bool Equals(object obj)

Parameters

Type	Name	Description
object	obj

Returns

Type	Description
bool

Overrides

object.Equals(object)

Evaluate(ReadOnlySpan<float>, Span<Color>)

Evaluates the gradient at multiple positions without heap allocation.

Declaration

public void Evaluate(ReadOnlySpan<float> positions, Span<Color> results)

Parameters

Type	Name	Description
ReadOnlySpan<float>	positions	Normalized positions to evaluate.
Span<Color>	results	Output span to receive the interpolated colors.

Exceptions

Type	Condition
ArgumentException	Thrown if results is shorter than positions.

Evaluate(float)

Evaluates the gradient at the specified normalized position, returning the interpolated color.

Declaration

public Color Evaluate(float t)

Parameters

Type	Name	Description
float	t	Position along the gradient, clamped to [0, 1].

Returns

Type	Description
Color	The interpolated UnityEngine.Color at position t.

Evaluate32(float)

Evaluates the gradient at the specified position, returning the color in byte precision.

Declaration

public Color32 Evaluate32(float t)

Parameters

Type	Name	Description
float	t	Position along the gradient, clamped to [0, 1].

Returns

Type	Description
Color32	The interpolated UnityEngine.Color32.

FromPalette(ColorPalette, ColorGradientMode, ColorGradientColorSpace)

Creates a smooth gradient from a ColorPalette's colors, evenly spaced across the [0, 1] range.

Declaration

public static ColorGradient FromPalette(ColorPalette palette, ColorGradientMode mode = ColorGradientMode.Smooth, ColorGradientColorSpace colorSpace = ColorGradientColorSpace.RGB)

Parameters

Type	Name	Description
ColorPalette	palette	Source palette. Must contain at least 2 colors.
ColorGradientMode	mode	Interpolation mode. Defaults to Smooth.
ColorGradientColorSpace	colorSpace	Color space. Defaults to RGB.

Returns

Type	Description
ColorGradient	A new gradient with one stop per palette color.

Exceptions

Type	Condition
ArgumentException	Thrown if palette has fewer than 2 colors.

FromUnityGradient(string, Gradient)

Creates a ColorGradient from Unity's built-in UnityEngine.Gradient type.

Declaration

public static ColorGradient FromUnityGradient(string name, Gradient gradient)

Parameters

Type	Name	Description
string	name	Name for the resulting gradient.
Gradient	gradient	The Unity gradient to convert.

Returns

Type	Description
ColorGradient	A new gradient matching the Unity gradient's appearance.

Remarks

Unity's UnityEngine.Gradient separates color and alpha keys. This method samples the gradient at all unique key positions to produce unified stops with the evaluated RGBA color at each position.

GetHashCode()

Declaration

public override int GetHashCode()

Returns

Type	Description
int

Overrides

object.GetHashCode()

GetStop(int)

Gets the stop at the specified index.

Declaration

public ColorGradientStop GetStop(int index)

Parameters

Type	Name	Description
int	index	Zero-based index into the sorted stops array.

Returns

Type	Description
ColorGradientStop	The ColorGradientStop at the given index.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown if index is outside the valid range.

GetTag(int)

Gets the asset-level tag at the specified index.

Declaration

public string GetTag(int index)

Parameters

Type	Name	Description
int	index	Zero-based tag index, must be in [0, TagCount).

Returns

Type	Description
string	The tag string at the specified index.

Exceptions

Type	Condition
IndexOutOfRangeException	If index is out of range.

HasTag(string)

Tests whether this gradient carries the given tag (case-insensitive).

Declaration

public bool HasTag(string tag)

Parameters

Type	Name	Description
string	tag	The tag to look up. Null returns false.

Returns

Type	Description
bool	true if any tag matches, otherwise false.

Reversed()

Creates a new gradient with the stops reversed (mirrored around 0.5).

Declaration

public ColorGradient Reversed()

Returns

Type	Description
ColorGradient	A new ColorGradient with inverted stop offsets.

Sample(int)

Samples the gradient at count evenly-spaced positions.

Declaration

public Color[] Sample(int count)

Parameters

Type	Name	Description
int	count	Number of samples. Must be at least 2.

Returns

Type	Description
Color[]	An array of count colors.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown if count is less than 2.

SteppedFromPalette(ColorPalette, ColorGradientColorSpace)

Creates a stepped gradient from a ColorPalette's colors, where each color occupies an equal band across the [0, 1] range.

Declaration

public static ColorGradient SteppedFromPalette(ColorPalette palette, ColorGradientColorSpace colorSpace = ColorGradientColorSpace.RGB)

Parameters

Type	Name	Description
ColorPalette	palette	Source palette. Must contain at least 2 colors.
ColorGradientColorSpace	colorSpace	Color space (used if mode is later changed to smooth).

Returns

Type	Description
ColorGradient	A new stepped gradient with one stop per palette color.

Exceptions

Type	Condition
ArgumentException	Thrown if palette has fewer than 2 colors.

ToPalette(int)

Samples this gradient into a discrete ColorPalette.

Declaration

public ColorPalette ToPalette(int sampleCount)

Parameters

Type	Name	Description
int	sampleCount	Number of evenly-spaced samples. Must be at least 2.

Returns

Type	Description
ColorPalette	A new ColorPalette with sampleCount entries named "Color_0", "Color_1", etc.

ToString()

Returns a human-readable representation in the format "Name (N stops, Smooth, RGB)".

Declaration

public override string ToString()

Returns

Type	Description
string

Overrides

object.ToString()

TwoColor(string, Color, Color, ColorGradientMode, ColorGradientColorSpace)

Creates a simple two-stop gradient between two colors.

Declaration

public static ColorGradient TwoColor(string name, Color start, Color end, ColorGradientMode mode = ColorGradientMode.Smooth, ColorGradientColorSpace colorSpace = ColorGradientColorSpace.RGB)

Parameters

Type	Name	Description
string	name	Gradient name.
Color	start	Color at offset 0.
Color	end	Color at offset 1.
ColorGradientMode	mode	Interpolation mode. Defaults to Smooth.
ColorGradientColorSpace	colorSpace	Color space. Defaults to RGB.

Returns

Type	Description
ColorGradient	A new ColorGradient with exactly 2 stops.

Implements

IEquatable<T>

Extension Methods

FileExtensions.SaveSecureToFileAsync<T>(T, string, string, CancellationToken)

FileExtensions.SaveSecureToFile<T>(T, string, string)

FileExtensions.SaveToFileAsync<T>(T, string, CancellationToken)

FileExtensions.SaveToFile<T>(T, string)

FileExtensions.SaveToFile<T>(T, string, SerializationSettings)

See Also

ColorGradientStop

ColorGradientMode

ColorGradientColorSpace

MutableColorGradient

ColorPalette