Struct turtle::color::Color[−][src]

pub struct Color {
    pub red: f64,
    pub green: f64,
    pub blue: f64,
    pub alpha: f64,
}

Type for representing a color.

See the module level documentation for more.

Fields

Value between 0.0 and 255.0

Value between 0.0 and 255.0

Value between 0.0 and 255.0

Value between 0.0 and 1.0

Methods

impl Color
[src]

Create a new Color from the given RGB values and alpha set to 1.0. This provides a more concise way to create Color values, instead of using the manual Color {...} style.

The given values must adhere to those laid out in the documentation for Color. Thus:

  • 0.0 ≤ red ≤ 255.0
  • 0.0 ≤ green ≤ 255.0
  • 0.0 ≤ blue ≤ 255.0
use turtle::Color;
let expected = Color { red: 35.0, green: 200.0, blue: 180.0, alpha: 1.0 };
let actual = Color::rgb(35.0, 200.0, 180.0);
assert_eq!(expected, actual);

Values that are outside the accepted RGB range will result in a panic

use turtle::Color;
// This will not work as 256.0 is greater than the maximum allowed value for blue
let color = Color::rgb(255.0, 255.0, 256.0);

Create a new Color from the given RGB values and the provided alpha setting. This provides a more concise way to create Color values instead of using the manual Color {...} style. The given values must adhere to those laid out in the documentation for Color. Thus:

  • 0.0 ≤ red ≤ 255.0
  • 0.0 ≤ green ≤ 255.0
  • 0.0 ≤ blue ≤ 255.0
  • 0.0 ≤ alpha ≤ 1.0
use turtle::Color;
let expected = Color { red: 35.0, green: 200.0, blue: 180.0, alpha: 0.5 };
let actual = Color::rgba(35.0, 200.0, 180.0, 0.5);
assert_eq!(expected, actual);

Values that are outside the accepted RGB or alpha range will result in a panic

use turtle::Color;
// This will not work as 1.1 is greater than the maximum allowed value for alpha
let color = Color::rgba(255.0, 255.0, 255.0, 1.1);

Create a new Color from the given HSL values with alpha set to 1.0.

The expected value ranges are:

  • 0.0 ≤ hue ≤ 360.0
  • 0.0 ≤ saturation ≤ 1.0
  • 0.0 ≤ lightness ≤ 1.0
use turtle::Color;
let black: Color = "black".into();
let black_hsl = Color::hsl(0.0, 0.0, 0.0);
assert_eq!(black, black_hsl);

let white: Color = "white".into();
let white_hsl = Color::hsl(0.0, 1.0, 1.0);
assert_eq!(white, white_hsl);

let blue: Color = "blue".into();
let blue_hsl = Color::hsl(201.0, 1.0, 0.392);
assert_eq!(blue, blue_hsl);

Create a new Color from the given HSL values and the given alpha value.

The expected value ranges are:

  • 0.0 ≤ hue ≤ 360.0
  • 0.0 ≤ saturation ≤ 1.0
  • 0.0 ≤ lightness ≤ 1.0
  • 0.0 ≤ alpha ≤ 1.0
use turtle::{Color, color};

// You can chain using Color::from()
let black = Color::from("black").with_alpha(0.5);
let black_hsla = Color::hsla(0.0, 0.0, 0.0, 0.5);
assert_eq!(black, black_hsla);

// But even better, you can use the color enum value and chain the
// calls.
let white = color::WHITE.with_alpha(0.75);
let white_hsla = Color::hsla(0.0, 1.0, 1.0, 0.75);
assert_eq!(white, white_hsla);

let blue: Color = color::BLUE.with_alpha(0.8);
let blue_hsla = Color::hsla(201.0, 1.0, 0.392, 0.8);
assert_eq!(blue, blue_hsla);

Returns true if the values for each field are valid.

The documentation above lists the valid range for each field.

Return a new color with all of the same values except with opacity (alpha) set to 1.0

use turtle::Color;
let color = Color {red: 43.0, green: 79.0, blue: 23.0, alpha: 0.5};
assert_eq!(color.alpha, 0.5);
let color2 = color.opaque();
assert_eq!(color.alpha, 0.5);
assert_eq!(color2.alpha, 1.0);

Return a new color with all of the same values except with opacity (alpha) set to 0.0

use turtle::Color;
let color = Color {red: 43.0, green: 79.0, blue: 23.0, alpha: 0.5};
assert_eq!(color.alpha, 0.5);
let color2 = color.transparent();
assert_eq!(color.alpha, 0.5);
assert_eq!(color2.alpha, 0.0);

Return a new color with alpha set to the given value

use turtle::Color;
let color = Color {red: 43.0, green: 79.0, blue: 23.0, alpha: 0.5};
assert_eq!(color.alpha, 0.5);
let color2 = color.with_alpha(0.2);
assert_eq!(color.alpha, 0.5);
assert_eq!(color2.alpha, 0.2);

Mix this color with the other given color, with the given weighting.

use turtle::Color;

// Start with red
let red: Color = "red".into();

// Create a mix that is 60% blue and 40% red
let mixed = red.mix("blue", 0.40);
let expected: Color = [92.0, 88.0, 150.0, 1.0].into();

assert_eq!(mixed, expected);

The weight parameter is a value between 0.0 and 1.0. It determines the percentage to mix self with other. So let's say that in the example above, we had used red.mix("blue", 0.5). 0.5 means 50%, so we would mix 50% red and 50% blue. The colors would be mixed evenly. If we had instead done red.mix("blue", 0.25), the weight would be 0.25 which is 25%. That means that we would get a mix of 25% red and 75% blue.

The alpha channel of both colors are also combined in the same way.

Panics

Passing a value for weight that is not between 0.0 and 1.0 will result in a panic

use turtle::{Color, color};

let orange: Color = "orange".into();

// This will panic as 1.01 is not a valid value for weight, which must be between 0.0 and 1.0.
let mixed = orange.mix(color::BROWN.with_alpha(0.8), 1.01);

Example

Let's look at a more complete example to really show what happens when we're mixing colors together.

extern crate turtle;

use turtle::{Color, Turtle};

fn main() {
    let mut turtle = Turtle::new();
    turtle.drawing_mut().set_title("Mixing colors!");
    turtle.set_pen_size(5.0);

    let red: Color = "red".into();

    // This will draw a red line
    turtle.set_pen_color(red);
    turtle.forward(100.0);
    turtle.right(90.0);

    // This will draw a purple line because we have equally mixed red with blue
    turtle.set_pen_color(red.mix("blue", 0.5));
    turtle.forward(100.0);
    turtle.right(90.0);

    // This will draw a line that is 25% red and 75% blue (a red-ish dark blue color)
    turtle.set_pen_color(red.mix("blue", 0.25));
    turtle.forward(100.0);
    turtle.right(90.0);

    // This will draw a line that is 75% red and 25% blue (medium red violet)
    turtle.set_pen_color(red.mix("blue", 0.75));
    turtle.forward(100.0);
    turtle.right(90.0);
}

Running the above program will result in the following image: turtle color mixing

Retrieve the hue for this Color. The returned value is in degrees between 0° and 360° that represents its position on the color wheel.

use turtle::Color;

let c: Color = "blue".into();
assert_eq!(201.0, c.hue());

Retrieve the saturation value for this Color. The returned value is between 0.0 and 1.0 (inclusive) that indicates the saturation percentage.

use turtle::Color;

let c: Color = "blue".into();
assert_eq!(1.0, c.saturation());

Retrieve the lightness value for this Color. The returned value is between 0.0 and 1.0 (inclusive) that indicates the lightness percentage.

use turtle::Color;

let c: Color = "blue".into();
assert_eq!(0.39215686274509803, c.lightness());

Changes the hue of a color. Takes a color and a number of degrees (usually between -360° and 360°), and returns a color with the hue rotated along the color wheel by that amount.

use turtle::Color;

// Positive values
let c = Color::hsl(120., 0.3, 0.9);
assert_eq!(c.rotate_hue(60.), Color::hsl(180.0, 0.3, 0.9));

// Negative values
assert_eq!(c.rotate_hue(-60.), Color::hsl(60.0, 0.3, 0.9));

Passing hue values outside the range of -360 and 360 will result in a panic.

So, passing a value that is too small:

use turtle::Color;

let red: Color = "red".into();

// This will panic, as -361 is outside the allowed range
let improper = red.rotate_hue(-361.0);

Or one that is too large:

use turtle::Color;

let blue: Color = "blue".into();

// This will panic as 361 is outside the allowed range
let improper = blue.rotate_hue(361.0);

Create a new Color by increasing the lightness of this Color by the given percentage. The value is a float between 0.0 and 1.0 indicating the percentage to increase the lightness. So, if you wish to make a Color 10% lighter, you would specify 0.1.

use turtle::Color;

let original = Color::hsl(158.0, 0.8, 0.3);

// Now, let's increase the lightness of original by 50%
let lighter = original.lighten(0.5);
assert_eq!(lighter, Color::hsl(158.0, 0.8, 0.8));

Now, as the maximum lightness a Color can have is 100%, trying to increase it beyond that point will result in a Color with a lightness value of 1.0

use turtle::Color;

let original = Color::hsl(200.0, 0.7, 0.8);

// Now, we'll increase the lightness by 50%, which would go beyond 100%
let lighter = original.lighten(0.5);

// But, the lightness of the color will still max out at 1.0
assert_eq!(lighter, Color::hsl(200.0, 0.7, 1.0));

Providing values greater than 1.0 will result in a panic

use turtle::Color;

let original = Color::hsl(150.0, 0.5, 0.3);

// This will panic as a value of 1.1 is greater than the acceptable
// maximum of 1.0
let incorrect = original.lighten(1.1);

Negative values will also result in a panic

use turtle::Color;

let original = Color::hsl(150.0, 0.5, 0.8);

// This will panic, as a negative value is less than the acceptable
// minimum of 0.0
let incorrect = original.lighten(-0.3);

If you want to lighten by a negative amount, please see darken.

use turtle::Color;

let original = Color::hsl(25.0, 1.0, 0.8);

// Instead of -0.3 (-30%) as in the previous example, we will just darken by 30%
let darker = original.darken(0.3);
assert_eq!(darker, Color::hsl(25.0, 1.0, 0.5));

Create a new Color by decreasing the lightness of this Color by the given percentage. The value is a float between 0.0 and 1.0 indicating the percentage to decrease the lightness. So, if you wish to make a Color 10% darker, you would specify 0.1.

use turtle::Color;

let original = Color::hsl(25.0, 1.0, 0.8);

// Let's make the color 30% darker.
let darker = original.darken(0.3);
assert_eq!(darker, Color::hsl(25.0, 1.0, 0.5));

As the minimum lightness a Color can have is 0%, attempting to decrease beyond that will result in a Color with a lightness of 0.

use turtle::Color;

let original = Color::hsl(100.0, 1.0, 0.3);

// Let's try to decrease by 40%, which would result in a negative lightness
let darker = original.darken(0.4);

// Since we can't go below 0%, the lightness of the resulting `Color` will be 0
assert_eq!(darker, Color::hsl(100.0, 1.0, 0.0));

Providing values greater than 1.0 will result in a panic

use turtle::Color;

let original = Color::hsl(150.0, 0.3, 0.5);

// This will panic as 1.1 is greater than the acceptable maximum of 1.0
let incorrect = original.darken(1.1);

Negative values will also result in a panic

use turtle::Color;

let original = Color::hsl(150.0, 0.3, 0.5);

// This will panic as a negative value is less than the acceptable
// minimum of 0.0
let incorrect = original.darken(-0.1);

If you want to darken by a negative value please see lighten.

use turtle::Color;

let original = Color::hsl(158.0, 0.8, 0.3);

// Now, we'll increase the lightness by 10%, instead of trying to darken by
// a negative amount
let lighter = original.lighten(0.1);
assert_eq!(lighter, Color::hsl(158.0, 0.8, 0.4));

Create a new Color by increasing the saturation level of this Color by the given percentage. The value is a float between 0.0 and 1.0 indicating the percentage to increase the saturation. So, if you wish to create a Color that is 30% more saturated than this one, you would specify 0.3.

For more information on what saturation is in relation to HSL colors, please see this Wikipedia Article.

use turtle::Color;

let original = Color::hsl(120.0, 0.3, 0.9);

// Now, let's increase the saturation by 20%
let saturated = original.saturate(0.2);
assert_eq!(saturated, Color::hsl(120.0, 0.5, 0.9));

The maximum saturation level a Color can have is 100%. If you try to increase beyond that level using this method, it will result in a Color with a saturation value of 1.0.

use turtle::Color;

let original = Color::hsl(120.0, 0.8, 0.9);

// We try to increase the saturation by 50%, which would equal 130%
let saturated = original.saturate(0.5);

// But the resulting color only has a saturation value of 1.0
assert_eq!(saturated, Color::hsl(120.0, 1.0, 0.9));

Passing values that are greater than 1.0 will result in a panic

use turtle::Color;

let original = Color::hsl(120.0, 0.5, 0.9);

// This will panic, as 1.1 is greater than the maximum accepted value of 1.0
let incorrect = original.saturate(1.1);

Negative values will also result in a panic

use turtle::Color;

let original = Color::hsl(120.0, 0.5, 0.9);

// This will panic, as a negative value is less than the minimum acceptable
// value of 0.0
let incorrect = original.saturate(-0.2);

If you wish to desaturate a Color please see desaturate.

use turtle::Color;

let original = Color::hsl(120.0, 0.3, 0.9);

// Instead of trying to saturate with a negative value as in the
// previous example, we simply desaturate by the same positive amount
let desaturated = original.desaturate(0.2);
assert_eq!(desaturated, Color::hsl(120.0, 0.1, 0.9));

Create a new Color by decreasing the saturation level of this Color by the given percentage. The value is a float between 0.0 and 1.0 indicating the percentage to decrease the saturation. So, if you wish to create a Color that is 30% less saturated than this one, you would specify 0.3.

For more information on what saturation is in relation to HSL colors, please see this Wikipedia Article.

use turtle::Color;

let original = Color::hsl(120.0, 0.3, 0.9);

// Now, desaturate the original by 20%
let desaturated = original.desaturate(0.2);
assert_eq!(desaturated, Color::hsl(120.0, 0.1, 0.9));

Since the minimum saturation value a color can have is 0%, attempting to desaturate beyond that level will simply result in a Color with a saturation value of 0.

use turtle::Color;

let original = Color::hsl(120.0, 0.3, 0.9);

// Now, desaturate the color by 50%, which would equal -20%
let desaturated = original.desaturate(0.5);

// However the resulting color simply has a saturation of 0.0
assert_eq!(desaturated, Color::hsl(120.0, 0.0, 0.9));

A color with a saturation level of 0.0 is known as an 'achromatic' color. As they have no hue, they are the range of all gray colors, ranging from white to black.

Passing values that are greater than 1.0 will result in a panic

use turtle::Color;

let original = Color::hsl(120.0, 0.3, 0.9);

// This will panic, as 1.1 is greater than the acceptable maximum of 1.0
let incorrect = original.desaturate(1.1);

Passing negative values will also panic

use turtle::Color;

let original = Color::hsl(120.0, 0.3, 0.7);

// This will panic, as a negative value is less than the acceptable
// minimum value of 0.0
let incorrect = original.desaturate(-0.2);

If you wish to saturate a Color, please see saturate

use turtle::Color;

let original = Color::hsl(120.0, 0.3, 0.9);

// Now, let's increase the saturation by 20% instead of trying to
// desaturate by a negative number
let saturated = original.saturate(0.2);
assert_eq!(saturated, Color::hsl(120.0, 0.5, 0.9));

Convert this Color to grayscale, which is essentailly desaturating it by 100%. For more information on desaturation please see desaturate.

use turtle::Color;

// Let's start with a standard HSL color
let original = Color::hsl(0.0, 0.5, 0.5);

// Now, when we switch this to grayscale, we will end up with Turtle 'grey'
assert_eq!(original.grayscale(), "grey".into());

A Color that has no saturation is known as an 'achromatic' Color, which are gray colors ranging from white to black.

Since this is essentally removing all saturation you can verify that the grayscale version of any Color is the same hue and lightness values with 0 saturation.

use turtle::Color;

// An arbitrary HSL color
let original = Color::hsl(200.0, 0.9, 1.0);

// The grayscale version simply has a saturation of 0
assert_eq!(original.grayscale(), Color::hsl(200.0, 0.0, 1.0));

Create a new Color by obtaining the complement (opposite) of this Color. The complement of a color is 180 degrees around the color wheel. For more information on rotating the hue of a Color please see rotate_hue.

This Wikipedia Article contains more information about complementary colors.

use turtle::Color;

// A standard HSL color
let original = Color::hsl(100.0, 0.7, 1.0);

// The complement will be have a hue value that is 180 degrees greater
assert_eq!(original.complement(), Color::hsl(280.0, 0.7, 1.0));

Create a Color that is the inverse (negative) of this Color. The red, green, and blue values of this color are inverted but alpha is not touched.

For more information about what the inverse of a Color is, please see this StackExchange Answer.

This Color is mixed with the inverted values to produce the inverse of it. The mix is done with a weight of 1.0 for the invert values. For more information see mix.

use turtle::Color;

// We will start with blue. Turtle blue is rgb(0, 130, 200)
let blue: Color = "blue".into();

// The inverse of blue is a light orange color. Note that the
// original color had a default alpha value of 1.0, so we can
// make sure the resulting color also has the same alpha value
assert_eq!(blue.invert(), [255.0, 125.0, 55.0, 1.0].into());

Trait Implementations

impl Debug for Color
[src]

Formats the value using the given formatter. Read more

impl Clone for Color
[src]

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

impl Copy for Color
[src]

impl PartialEq for Color
[src]

This method tests for self and other values to be equal, and is used by ==. Read more

This method tests for !=.

impl Distribution<Color> for Standard
[src]

Generate a random value of T, using rng as the source of randomness.

ⓘImportant traits for DistIter<'a, D, R, T>

Create an iterator that generates random values of T, using rng as the source of randomness. Read more

impl From<[f64; 3]> for Color
[src]

Performs the conversion.

impl From<[f64; 4]> for Color
[src]

Performs the conversion.

impl<'a> From<&'a str> for Color
[src]

Performs the conversion.

Auto Trait Implementations

impl Send for Color

impl Sync for Color