Improve some documentation for beginners

[Ogeon]

An attempt to add some documentation that may be useful for those who are new to Palette. It can always be improved more, but this is at least something. It adds a "where do I start?" section in the crate root, explains different ways of creating RGB and RGBA values (that generally promotes Srgb and Srgba), and adds some conversion docs in convert.

[github-actions[bot]]

Benchmark for 04a5009

Click to view benchmark

| Test | Base | PR | % | |------|--------------|------------------|---| | Cie family/lab to lch | 3.3±0.00µs | 3.3±0.01µs | 0.00% | | Cie family/lab to xyz | 770.3±1.22ns | **768.0±0.86ns** | **-0.30%** | | Cie family/lch to lab | 1208.2±1.32ns | **1187.8±4.05ns** | **-1.69%** | | Cie family/linsrgb to xyz | 315.6±0.21ns | **308.3±0.16ns** | **-2.31%** | | Cie family/linsrgb to xyz - wide::f32x8 | 251.4±0.29ns | 251.4±0.51ns | 0.00% | | Cie family/xyz to lab | 8.7±0.01µs | **8.6±0.02µs** | **-1.15%** | | Cie family/xyz to yxy | **676.8±0.45ns** | 677.4±0.39ns | **+0.09%** | | Cie family/yxy to xyz | 606.2±0.25ns | **606.0±0.18ns** | **-0.03%** | | Matrix functions/matrix_inverse | **13.0±0.12ns** | 13.1±0.02ns | **+0.77%** | | Matrix functions/multiply_3x3 | **9.6±0.03ns** | 9.8±0.02ns | **+2.08%** | | Matrix functions/multiply_rgb_to_xyz | 8.4±0.01ns | 8.4±0.04ns | 0.00% | | Matrix functions/multiply_xyz | 6.0±0.04ns | 6.0±0.04ns | 0.00% | | Matrix functions/multiply_xyz_to_rgb | 6.0±0.04ns | 6.0±0.03ns | 0.00% | | Matrix functions/rgb_to_xyz_matrix | 26.0±0.01ns | 26.0±0.01ns | 0.00% | | Rgb family/hsl to hsv | 737.9±0.62ns | **736.6±0.38ns** | **-0.18%** | | Rgb family/hsl to linear hsl | **7.5±0.01µs** | 7.6±0.02µs | **+1.33%** | | Rgb family/hsl to rgb | 2.4±0.03µs | **2.3±0.00µs** | **-4.17%** | | Rgb family/hsv to hsl | 1003.8±0.77ns | **985.6±0.64ns** | **-1.81%** | | Rgb family/hsv to hwb | 231.6±2.52ns | 231.5±2.78ns | -0.04% | | Rgb family/hsv to linear hsv | 6.9±0.01µs | 6.9±0.01µs | 0.00% | | Rgb family/hsv to rgb | 2.1±0.00µs | **1998.9±51.42ns** | **-4.81%** | | Rgb family/hwb to hsv | 735.7±0.39ns | 735.5±0.31ns | -0.03% | | Rgb family/hwb to linear hwb | 8.3±0.01µs | **8.2±0.02µs** | **-1.20%** | | Rgb family/linear hsl to hsl | **7.5±0.00µs** | 7.6±0.01µs | **+1.33%** | | Rgb family/linear hsv to hsv | 7.0±0.01µs | 7.0±0.03µs | 0.00% | | Rgb family/linear hwb to hwb | 8.2±0.00µs | 8.2±0.01µs | 0.00% | | Rgb family/linsrgb to rgb | 3.7±0.00µs | 3.7±0.00µs | 0.00% | | Rgb family/linsrgb to rgb - wide::f32x8 | 5.0±0.00µs | 5.0±0.00µs | 0.00% | | Rgb family/linsrgb_f32 to rgb_u8 | 948.8±0.57ns | **946.6±0.85ns** | **-0.23%** | | Rgb family/linsrgb_f64 to rgb_u8 | 1213.9±0.67ns | 1213.9±0.48ns | 0.00% | | Rgb family/rgb to hsl | 632.9±0.39ns | **626.9±4.64ns** | **-0.95%** | | Rgb family/rgb to hsl - wide::f32x8 | 476.6±0.25ns | **456.1±0.13ns** | **-4.30%** | | Rgb family/rgb to hsv | 496.1±0.34ns | **486.4±2.88ns** | **-1.96%** | | Rgb family/rgb to hsv - wide::f32x8 | 431.9±0.24ns | **431.5±0.28ns** | **-0.09%** | | Rgb family/rgb to linsrgb | 3.8±0.00µs | 3.8±0.04µs | 0.00% | | Rgb family/rgb to linsrgb - wide::f32x8 | 3.2±0.00µs | **3.1±0.00µs** | **-3.13%** | | Rgb family/rgb_u8 to linsrgb_f32 | 293.7±0.83ns | **289.2±1.10ns** | **-1.53%** | | Rgb family/rgb_u8 to linsrgb_f64 | 298.3±1.18ns | **289.4±1.40ns** | **-2.98%** | | Rgb family/xyz to linsrgb | **352.6±0.18ns** | 358.5±0.13ns | **+1.67%** | | Rgb family/xyz to linsrgb - wide::f32x8 | 248.9±0.21ns | **248.4±0.46ns** | **-0.20%** |

[Ogeon]

Thanks for looking through it @okaneco! :pray:

[github-actions[bot]]

Benchmark for a2602a3

Click to view benchmark

| Test | Base | PR | % | |------|--------------|------------------|---| | Cie family/lab to lch | 3.8±0.14µs | 3.8±0.15µs | 0.00% | | Cie family/lab to xyz | 899.2±19.44ns | 899.3±18.20ns | +0.01% | | Cie family/lch to lab | 1396.7±43.20ns | 1404.5±40.73ns | +0.56% | | Cie family/linsrgb to xyz | 372.8±6.93ns | 370.3±7.62ns | -0.67% | | Cie family/linsrgb to xyz - wide::f32x8 | 296.9±4.19ns | 297.3±3.82ns | +0.13% | | Cie family/xyz to lab | 10.4±0.43µs | 10.2±0.22µs | -1.92% | | Cie family/xyz to yxy | **751.4±36.15ns** | 790.1±16.30ns | **+5.15%** | | Cie family/yxy to xyz | **664.4±26.48ns** | 707.1±10.58ns | **+6.43%** | | Matrix functions/matrix_inverse | 15.4±0.28ns | **14.9±0.32ns** | **-3.25%** | | Matrix functions/multiply_3x3 | 11.5±0.20ns | **11.3±0.18ns** | **-1.74%** | | Matrix functions/multiply_rgb_to_xyz | 9.6±0.33ns | 9.7±0.23ns | +1.04% | | Matrix functions/multiply_xyz | **6.8±0.22ns** | 7.0±0.12ns | **+2.94%** | | Matrix functions/multiply_xyz_to_rgb | **6.6±0.28ns** | 7.1±0.11ns | **+7.58%** | | Matrix functions/rgb_to_xyz_matrix | 30.6±0.43ns | 30.2±0.53ns | -1.31% | | Rgb family/hsl to hsv | 852.5±33.18ns | 852.4±16.96ns | -0.01% | | Rgb family/hsl to linear hsl | 8.2±0.28µs | 8.3±0.30µs | +1.22% | | Rgb family/hsl to rgb | 2.8±0.04µs | **2.7±0.07µs** | **-3.57%** | | Rgb family/hsv to hsl | **1115.9±44.26ns** | 1144.2±22.26ns | **+2.54%** | | Rgb family/hsv to hwb | **256.5±9.97ns** | 270.8±8.10ns | **+5.58%** | | Rgb family/hsv to linear hsv | **7.9±0.32µs** | 8.2±0.17µs | **+3.80%** | | Rgb family/hsv to rgb | 2.4±0.09µs | 2.4±0.03µs | 0.00% | | Rgb family/hwb to hsv | **809.3±32.43ns** | 861.8±17.01ns | **+6.49%** | | Rgb family/hwb to linear hwb | 9.2±0.37µs | 9.5±0.30µs | +3.26% | | Rgb family/linear hsl to hsl | 8.2±0.28µs | 8.3±0.29µs | +1.22% | | Rgb family/linear hsv to hsv | **7.7±0.26µs** | 8.1±0.25µs | **+5.19%** | | Rgb family/linear hwb to hwb | 9.6±0.23µs | **9.3±0.37µs** | **-3.12%** | | Rgb family/linsrgb to rgb | **4.4±0.06µs** | 4.6±0.09µs | **+4.55%** | | Rgb family/linsrgb to rgb - wide::f32x8 | **5.9±0.10µs** | 6.0±0.09µs | **+1.69%** | | Rgb family/linsrgb_f32 to rgb_u8 | 1061.6±36.33ns | 1073.6±38.58ns | +1.13% | | Rgb family/linsrgb_f64 to rgb_u8 | 1439.7±15.12ns | **1385.7±54.64ns** | **-3.75%** | | Rgb family/rgb to hsl | 732.2±14.81ns | 729.2±13.53ns | -0.41% | | Rgb family/rgb to hsl - wide::f32x8 | 545.9±18.69ns | **533.4±9.03ns** | **-2.29%** | | Rgb family/rgb to hsv | **530.7±19.31ns** | 561.6±13.31ns | **+5.82%** | | Rgb family/rgb to hsv - wide::f32x8 | 474.5±20.66ns | 475.9±10.86ns | +0.30% | | Rgb family/rgb to linsrgb | **4.4±0.14µs** | 4.6±0.09µs | **+4.55%** | | Rgb family/rgb to linsrgb - wide::f32x8 | 3.6±0.12µs | 3.6±0.08µs | 0.00% | | Rgb family/rgb_u8 to linsrgb_f32 | **331.1±10.96ns** | 339.9±6.08ns | **+2.66%** | | Rgb family/rgb_u8 to linsrgb_f64 | 341.6±7.76ns | **330.0±12.92ns** | **-3.40%** | | Rgb family/xyz to linsrgb | 416.5±8.70ns | 413.8±8.96ns | -0.65% | | Rgb family/xyz to linsrgb - wide::f32x8 | 287.8±10.59ns | 291.8±5.37ns | +1.39% |

[Ogeon]

I wasn't entirely happy with the exceptions/restrictions list, so I rewrote it a bit. Also fixed a couple of other mistakes around it.

[github-actions[bot]]

Benchmark for 125bf34

Click to view benchmark

| Test | Base | PR | % | |------|--------------|------------------|---| | Cie family/lab to lch | 3.3±0.00µs | 3.3±0.01µs | 0.00% | | Cie family/lab to xyz | 775.4±1.29ns | **771.0±0.53ns** | **-0.57%** | | Cie family/lch to lab | **1215.3±1.88ns** | 1227.4±0.75ns | **+1.00%** | | Cie family/linsrgb to xyz | 306.4±0.17ns | **304.8±0.17ns** | **-0.52%** | | Cie family/linsrgb to xyz - wide::f32x8 | 251.6±0.23ns | 251.6±0.47ns | 0.00% | | Cie family/xyz to lab | **8.6±0.01µs** | 8.9±0.10µs | **+3.49%** | | Cie family/xyz to yxy | 690.1±2.22ns | 688.8±1.34ns | -0.19% | | Cie family/yxy to xyz | 602.4±11.93ns | **599.3±0.32ns** | **-0.51%** | | Matrix functions/matrix_inverse | **13.1±0.01ns** | 13.2±0.03ns | **+0.76%** | | Matrix functions/multiply_3x3 | 9.8±0.02ns | 9.8±0.09ns | 0.00% | | Matrix functions/multiply_rgb_to_xyz | 8.4±0.01ns | 8.4±0.02ns | 0.00% | | Matrix functions/multiply_xyz | 6.0±0.07ns | 6.0±0.06ns | 0.00% | | Matrix functions/multiply_xyz_to_rgb | 6.0±0.03ns | 6.0±0.04ns | 0.00% | | Matrix functions/rgb_to_xyz_matrix | 26.3±0.01ns | **26.0±0.02ns** | **-1.14%** | | Rgb family/hsl to hsv | 750.1±0.39ns | **737.3±0.31ns** | **-1.71%** | | Rgb family/hsl to linear hsl | 7.8±0.01µs | **7.5±0.01µs** | **-3.85%** | | Rgb family/hsl to rgb | **2.3±0.00µs** | 2.4±0.00µs | **+4.35%** | | Rgb family/hsv to hsl | **986.1±0.87ns** | 987.7±0.55ns | **+0.16%** | | Rgb family/hsv to hwb | 232.8±5.26ns | 234.9±2.10ns | +0.90% | | Rgb family/hsv to linear hsv | 7.3±0.01µs | **6.9±0.01µs** | **-5.48%** | | Rgb family/hsv to rgb | 2.1±0.00µs | 2.1±0.00µs | 0.00% | | Rgb family/hwb to hsv | **735.8±0.31ns** | 736.4±0.44ns | **+0.08%** | | Rgb family/hwb to linear hwb | 8.4±0.02µs | **8.3±0.08µs** | **-1.19%** | | Rgb family/linear hsl to hsl | 7.6±0.01µs | **7.5±0.00µs** | **-1.32%** | | Rgb family/linear hsv to hsv | 7.1±0.01µs | **7.0±0.00µs** | **-1.41%** | | Rgb family/linear hwb to hwb | 8.3±0.00µs | **8.2±0.01µs** | **-1.20%** | | Rgb family/linsrgb to rgb | 3.8±0.00µs | **3.7±0.00µs** | **-2.63%** | | Rgb family/linsrgb to rgb - wide::f32x8 | 5.0±0.01µs | 5.0±0.00µs | 0.00% | | Rgb family/linsrgb_f32 to rgb_u8 | 951.5±0.45ns | **946.2±1.14ns** | **-0.56%** | | Rgb family/linsrgb_f64 to rgb_u8 | 1215.1±0.66ns | **1214.0±0.89ns** | **-0.09%** | | Rgb family/rgb to hsl | 624.9±0.30ns | 625.0±0.43ns | +0.02% | | Rgb family/rgb to hsl - wide::f32x8 | **476.1±0.25ns** | 476.5±0.34ns | **+0.08%** | | Rgb family/rgb to hsv | 486.1±0.30ns | **476.0±0.31ns** | **-2.08%** | | Rgb family/rgb to hsv - wide::f32x8 | 431.2±0.24ns | 431.4±0.25ns | +0.05% | | Rgb family/rgb to linsrgb | 3.8±0.00µs | 3.8±0.00µs | 0.00% | | Rgb family/rgb to linsrgb - wide::f32x8 | 3.2±0.00µs | 3.2±0.00µs | 0.00% | | Rgb family/rgb_u8 to linsrgb_f32 | **289.4±0.75ns** | 290.5±4.80ns | **+0.38%** | | Rgb family/rgb_u8 to linsrgb_f64 | 290.2±1.06ns | 289.5±1.38ns | -0.24% | | Rgb family/xyz to linsrgb | 362.0±0.16ns | **352.3±0.34ns** | **-2.68%** | | Rgb family/xyz to linsrgb - wide::f32x8 | 248.8±0.22ns | 248.8±0.28ns | 0.00% |

[Ogeon]

bors r+

[bors[bot]]

Build succeeded!

The publicly hosted instance of bors-ng is deprecated and will go away soon.

If you want to self-host your own instance, instructions are here. For more help, visit the forum.

If you want to switch to GitHub's built-in merge queue, visit their help page.

• ci