Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve some documentation for beginners #351

Merged
merged 3 commits into from
Aug 30, 2023
Merged

Improve some documentation for beginners #351

merged 3 commits into from
Aug 30, 2023

Conversation

Ogeon
Copy link
Owner

@Ogeon Ogeon commented Aug 28, 2023

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
Copy link

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%

okaneco
okaneco reviewed Aug 28, 2023
View reviewed changes
palette/src/convert.rs Outdated Show resolved Hide resolved
palette/src/convert.rs Outdated Show resolved Hide resolved
palette/src/rgb.rs Outdated Show resolved Hide resolved
palette/src/alpha/alpha.rs Outdated Show resolved Hide resolved
palette/src/alpha/alpha.rs Outdated Show resolved Hide resolved
@Ogeon
Copy link
Owner Author

Ogeon commented Aug 28, 2023

Thanks for looking through it @okaneco! 🙏

@github-actions
Copy link

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
Copy link
Owner Author

Ogeon commented Aug 29, 2023

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
Copy link

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
Copy link
Owner Author

Ogeon commented Aug 30, 2023

bors r+

@bors
Copy link
Contributor

bors bot commented Aug 30, 2023

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.

@bors bors bot merged commit fc6c530 into master Aug 30, 2023
15 checks passed
@bors bors bot deleted the improve_beginner_docs branch August 30, 2023 10:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@okaneco okaneco okaneco left review comments

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@Ogeon @okaneco