Struct ColorMatrix

Namespace

Egami.Operations

Assembly

Egami.dll

A 4 × 5 color matrix applied to straight (not premultiplied) RGBA scaled to 0..1: each output channel is m[row, 0] × R + m[row, 1] × G + m[row, 2] × B + m[row, 3] × A + m[row, 4], rows in R, G, B, A order, and results are clamped to 0..1. The factories follow the W3C Filter Effects definitions.

public readonly struct ColorMatrix : IEquatable<ColorMatrix>

Implements

IEquatable<ColorMatrix>

Inherited Members

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Examples

// A ColorMatrix is 4 rows of 5 values: each output channel is a weighted sum of R, G, B, A plus an offset.
// Combine the ready-made ones with Then; no clamping happens in between.
ColorMatrix warm = ColorMatrix.Saturation(1.1f).Then(new ColorMatrix(
[
    1.05f, 0, 0, 0, 0,
    0, 1, 0, 0, 0,
    0, 0, 0.92f, 0, 0,
    0, 0, 0, 1, 0,
]));
photo.Apply(ops => ops.ColorMatrix(warm), Ct);

Remarks

default(ColorMatrix) is Identity, so a matrix left unset changes nothing.

Constructors

ColorMatrix(ReadOnlySpan<float>)

Creates a matrix from 20 values, row by row.

public ColorMatrix(ReadOnlySpan<float> values)

Parameters

values ReadOnlySpan<float>

Four rows of five: the R, G, B and A weights, then the offset.

Exceptions

ArgumentException

values does not hold exactly 20 finite values.

Properties

Identity

Gets the matrix that changes nothing.

public static ColorMatrix Identity { get; }

Property Value

ColorMatrix

this[int, int]

Gets one value.

[SuppressMessage("Design", "CA1043:Use Integral Or String Argument For Indexers", Justification = "Integral.")]
public float this[int row, int column] { get; }

Parameters

row int

The output channel: 0 red, 1 green, 2 blue, 3 alpha.

column int

The input channel in the same order, or 4 for the offset.

Property Value

float

The value.

Exceptions

ArgumentOutOfRangeException

row or column is out of range.

Methods

Brightness(float)

Multiplies red, green and blue by amount. 1 changes nothing, 0 gives black.

public static ColorMatrix Brightness(float amount)

Parameters

amount float

The factor, 0 or more.

Returns

ColorMatrix

The matrix.

Exceptions

ArgumentOutOfRangeException

amount is negative or not finite.

Contrast(float)

Scales red, green and blue around 0.5 by amount. 1 changes nothing, 0 gives flat gray.

public static ColorMatrix Contrast(float amount)

Parameters

amount float

The factor, 0 or more.

Returns

ColorMatrix

The matrix.

Exceptions

ArgumentOutOfRangeException

amount is negative or not finite.

Equals(ColorMatrix)

Indicates whether the current object is equal to another object of the same type.

public bool Equals(ColorMatrix other)

Parameters

other ColorMatrix

An object to compare with this object.

Returns

bool

true if the current object is equal to the other parameter; otherwise, false.

Equals(object?)

Indicates whether this instance and a specified object are equal.

public override bool Equals(object? obj)

Parameters

obj object

The object to compare with the current instance.

Returns

bool

true if obj and this instance are the same type and represent the same value; otherwise, false.

GetHashCode()

Returns the hash code for this instance.

public override int GetHashCode()

Returns

int

A 32-bit signed integer that is the hash code for this instance.

Grayscale(LumaWeights, float)

Converts toward gray with the given luma weights, applied to the stored (gamma-encoded) values.

public static ColorMatrix Grayscale(LumaWeights mode = LumaWeights.Rec709, float amount = 1)

Parameters

mode LumaWeights

The luma weights.

amount float

0 changes nothing, 1 gives full gray.

Returns

ColorMatrix

The matrix.

Exceptions

ArgumentOutOfRangeException

mode is not defined, or amount is outside 0 to 1.

HueRotate(float)

Rotates hue around the luma axis with the W3C Filter Effects matrix.

public static ColorMatrix HueRotate(float degrees)

Parameters

degrees float

The angle; 0 and 360 change nothing.

Returns

ColorMatrix

The matrix.

Exceptions

ArgumentOutOfRangeException

degrees is not finite.

Invert(float)

Replaces red, green and blue with 1 − value, blended by amount.

public static ColorMatrix Invert(float amount = 1)

Parameters

amount float

0 changes nothing, 1 inverts fully.

Returns

ColorMatrix

The matrix.

Exceptions

ArgumentOutOfRangeException

amount is outside 0 to 1.

Opacity(float)

Multiplies alpha by amount.

public static ColorMatrix Opacity(float amount)

Parameters

amount float

0 makes the image transparent, 1 changes nothing.

Returns

ColorMatrix

The matrix.

Exceptions

ArgumentOutOfRangeException

amount is outside 0 to 1.

Saturation(float)

Mixes each color with its luma, using the W3C Filter Effects weights (0.213, 0.715, 0.072).

public static ColorMatrix Saturation(float amount)

Parameters

amount float

1 changes nothing, 0 gives gray, above 1 oversaturates.

Returns

ColorMatrix

The matrix.

Exceptions

ArgumentOutOfRangeException

amount is negative or not finite.

Sepia(float)

Tints toward sepia with the W3C Filter Effects sepia matrix.

public static ColorMatrix Sepia(float amount = 1)

Parameters

amount float

0 changes nothing, 1 gives full sepia.

Returns

ColorMatrix

The matrix.

Exceptions

ArgumentOutOfRangeException

amount is outside 0 to 1.

Then(ColorMatrix)

Returns the matrix that applies this one and then next, without clamping in between.

public ColorMatrix Then(ColorMatrix next)

Parameters

next ColorMatrix

The matrix applied second.

Returns

ColorMatrix

The combined matrix.

Exceptions

ArgumentException

The product has a value that is not finite.

ToString()

Returns the fully qualified type name of this instance.

public override string ToString()

Returns

string

The fully qualified type name.

Operators

operator ==(ColorMatrix, ColorMatrix)

Returns whether two matrices hold the same values.

public static bool operator ==(ColorMatrix left, ColorMatrix right)

Parameters

left ColorMatrix

The first matrix.

right ColorMatrix

The second matrix.

Returns

bool

true if every value is equal.

operator !=(ColorMatrix, ColorMatrix)

Returns whether two matrices differ.

public static bool operator !=(ColorMatrix left, ColorMatrix right)

Parameters

left ColorMatrix

The first matrix.

right ColorMatrix

The second matrix.

Returns

bool

true if any value differs.