Crate colstodian

An opinionated color management library built on top of kolor.

Introduction

This library seeks to be a practical color management library for games and graphics. It does so by encoding various information about a color either statically in the Rust type system (as with the strongly-typed Color), or data contained in the type (as with the dynamically-typed DynamicColor).

Although it is designed to prevent footguns wherever possible, in order to make use of this library, you should have a well-working understanding of basic color science and encoding principles. As such, I highly recommend you give sections 2.0 and 2.1 of this document a read, as it is one of the main inspirations for how this library is structured:

Required Reading

• http://github.com/jeremyselan/cinematiccolor/raw/master/ves/Cinematic_Color_VES.pdf

Overview

colstodian is broken up into two ‘halves’, a statically-typed half which is meant to be used as much as possible to help you prevent errors at compile time through leveraging the Rust type system, and a dynamically-typed half which is meant to be used when serializing and deserializing colors and otherwise interacting with colors from dynamic sources not known at compile time.

The core of the statically-typed half is the Color type, which encodes two important pieces of metadata about the color in its type signature (Color<Space, State>): the color’s color space and state. If you read the required reading (you did, didn’t you? ;)) then you should have a decent idea of what both of these things mean. To be clear, the color space encodes the primaries, white point, and transfer functions upon which the color values are based. The state encodes in which “direction” we relate the color values to real-world quantities: either scene-referred or display-referred. Types which implement the ColorSpace and State traits encode this information statically. Color spaces can be found in the spaces module and states can be found in the states module.

The core of the dynamically-typed half is the DynamicColor type, which encodes the color space and state as data stored in the type at runtime. It stores these as DynamicColorSpaces and DynamicStates.

Example

let original_color = Color::<EncodedSrgb, Display>::new(0.5, 0.5, 0.5);
let col: Color<LinearSrgb, Display> = orig.convert();
let col: Color<AcesCg, Display> = col.convert_linear();
let col: Color<AcesCg, Scene> = col.convert_state(|c| c * 5.0);

let col: Color<AcesCg, Display> = col.convert_state(|c| c / 5.0);
let col: Color<LinearSrgb, Display> = col.convert();
let final_color: Color<EncodedSrgb, Display> = col.convert();

assert_eq!(orignal_color, final_color);

Re-exports

pub use kolor;
pub use spaces::*;
pub use states::*;
pub use tonemapper::*;

Modules

spaces
states
tonemapper

Structs

Color	A strongly typed color, parameterized by a color space and state. See ColorSpace and State for more.
DynamicColor	A dynamic color, with its Space and State defined as data. This is mostly useful for (de)serialization. See ColorSpace and State for more.
DynamicColorSpace	See spaces for defined color spaces.
Mat3	A 3x3 column major matrix.
Vec3	A 3-dimensional vector without SIMD support.

Enums

DowncastError	An error when downcasting from a DynamicColor to a typed Color.
DynamicConversionError	An error that occurred when performing a conversion on a DynamicColor
DynamicState	A dynamic version of a color’s state. See docs for State
Error	Any error which can occur within the library.

Traits

ColorSpace	A type that implements ColorSpace represents a specific color space. See the documentation of DynamicColorSpace for more information about what a color space is.
LinearColorSpace	Marks a type as representing a linear color space.
LinearConvertFrom	A type that implements this trait is a color space for which a linear conversion from SrcSpace to Self exists.
State	A type that implements this trait represents a color’s State.

Type Definitions

Result