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

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

red: f64

Value between 0.0 and 255.0

green: f64

Value between 0.0 and 255.0

blue: f64

Value between 0.0 and 255.0

alpha: f64

Value between 0.0 and 1.0

Methods

impl Color[src]

pub fn rgb(red: f64, green: f64, blue: f64) -> Self[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);

pub fn rgba(red: f64, green: f64, blue: f64, alpha: f64) -> Self[src]

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);

pub fn hsl(hue: f64, saturation: f64, lightness: f64) -> Self[src]

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);

pub fn hsla(hue: f64, saturation: f64, lightness: f64, alpha: f64) -> Self[src]

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);

pub fn is_valid(&self) -> bool[src]

Returns true if the values for each field are valid.

The documentation above lists the valid range for each field.

pub fn opaque(self) -> Color[src]

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);

pub fn transparent(self) -> Color[src]

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);

pub fn with_alpha(self, alpha: f64) -> Color[src]

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);

pub fn mix<C: Into<Color> + Copy + Debug>(self, other: C, weight: f64) -> Self[src]

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.

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

pub fn hue(self) -> f64[src]

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());

pub fn saturation(self) -> f64[src]

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());

pub fn lightness(self) -> f64[src]

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());

pub fn rotate_hue(self, hue: f64) -> Self[src]

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);

pub fn lighten(self, lighter: f64) -> Self[src]

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));

pub fn darken(self, darker: f64) -> Self[src]

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));

pub fn saturate(self, saturation: f64) -> Self[src]

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));

pub fn desaturate(self, saturation: f64) -> Self[src]

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));

pub fn grayscale(self) -> Self[src]

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));

pub fn complement(self) -> Self[src]

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));

pub fn invert(self) -> Self[src]

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 Random for Color[src]

impl<B: Into<Color>> RandomRange<B> for Color[src]

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

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

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

impl Clone for Color[src]

impl Copy for Color[src]

impl PartialEq<Color> for Color[src]

impl Debug for Color[src]

impl StructuralPartialEq for Color[src]

impl Serialize for Color[src]

impl<'de> Deserialize<'de> for Color[src]

Auto Trait Implementations

impl Send for Color

impl Sync for Color

impl Unpin for Color

impl UnwindSafe for Color

impl RefUnwindSafe for Color

Blanket Implementations

impl<T> From<T> for T[src]

impl<T, U> Into<U> for T where
    U: From<T>, 
[src]

impl<T> ToOwned for T where
    T: Clone
[src]

type Owned = T

The resulting type after obtaining ownership.

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 
[src]

type Error = !

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 
[src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.

impl<T> Borrow<T> for T where
    T: ?Sized
[src]

impl<T> BorrowMut<T> for T where
    T: ?Sized
[src]

impl<T> Any for T where
    T: 'static + ?Sized
[src]

impl<T> DeserializeOwned for T where
    T: Deserialize<'de>, 
[src]

impl<T> SetParameter for T