🌈Gradients

red.jackf.jackfredlib.api.colour.Gradient

Gradients are sequences of Colours from a range of 0 to 1. They can be sampled at any given point between that range (with it looping in the case of being outside that range).

Colours also implement the Gradient interface, allowing them to be substituted for any methods taking a gradient.

Blending Modes

JFL: Colour has 3 modes for interpolating between two colours in gradients:

• RGB: Regular linear interpolation for all components

• HSV_SHORT: Linear intepolation in the HSV space, taking the shortest path. This has the effect of keeping the colours bright instead of greying in the middle.

• HSV_LONG: Linear interpolation in the HSV space, taking the longest path.

Example of blending modes available for a gradient.

Overview of what each mode actually does.

Currently, alpha values are always set to maximum when used in a HSV gradient. This may change in the future.

HSV gradients are not stored as such - they're immediately compiled into an equivalent series of RGB gradients which look identical. As such, the HSV points cannot be returned back.

Creating a gradient

Using Gradient.of()

For simple gradients, using Gradient.of() is likely the easiest method. This generates a gradient with equal intervals between colours and RGB blending.

Gradient SOLAR = Gradient.of(
    Colour.fromRGB(40, 23, 0),
    Colours.YELLOW,
    Colours.ORANGE,
    Colours.WHITE
);

The gradient created above

Using Gradient.linear()

Using Gradient.linear() creates a gradient between two points, using either RGB or HSV blending modes. For examples of these, see above.

Using Gradient.builder()

For more control, you can use the given GradientBuilder class in order to create one point by point.

Gradient complex = Gradient.builder()
    // adding regular colours
    .add(0f, Colours.RED) 
    .add(0.25f, Colours.PINK)
    
    // adding adding another gradient as part of this one
    .addBlock(0.3f, 0.45f, Gradient.linear(Colours.HOT_PINK, Colours.LIME, Gradient.LinearMode.HSV_LONG))
    
    // adding a sharp cut between two colours
    .addCut(0.5f, Colours.GREEN, Colours.BLUE)
    
    // we use Math.nextDown here to get the point 'just before' the NONBINARY gradient starts. This allows us to
    // make a sharp cut manually
    .add(Math.nextDown(0.75f), Colours.AQUAMARINE)
    
    // GradientBuilder.END is the last value before 1f, where it loops. Use it to add an endpoint to your gradient.
    .addBlock(0.75f, GradientBuilder.END, Gradients.NONBINARY)
    .build()

The gradient created by the above code

Modifying a gradient

It may be useful to modify a gradient after it's been created - you can use it in GradientBuilder.addBlock, or some post-processing methods:

squish()

If your gradient has sharp edges, you can squish it in order to make transitions smoother. It does this by shrinking it slightly towards the center, then adding points at 0f and GradientBuilder.END with a lerped colour value.

Example of squishing a gradient - the bottom gradient has been squished by 0.1f

repeat()

Returns a copy of this gradient shrunken and repeated a certain number of times back to back.

reversed()

Reverses this gradient.

slice()

Returns a subsection of this gradient between the two points. These points can be backwards, and can cross the edges of the gradient boundary. Note that it will not automatically repeat the gradient but will wrap instead.

Drawing gradients

JFL: Colour contains methods to efficiently draw gradients in a GUI context, horizontally and vertically. These methods are client-only, and can be found under GradientUtils. This can draw gradients repeated or backwards depending on what you pass for gradientStart and gradientEnd.

These methods use a single quad for each RGB segment.