Gradient Tool

Overview

The Gradient tool creates smooth transitions between colors. It’s essential for backgrounds, lighting effects, and color blending in pixel art and digital artwork.

Keyboard Shortcut: Press Shift+G to select the Gradient tool

Basic Usage

Select the Gradient Tool

Press Shift+G or click the gradient icon in the toolbar

Choose Colors

Foreground color: Start of gradient
Background color: End of gradient

Draw Gradient

Click and drag from start point to end point

The direction and length of your drag determines the gradient direction and transition zone. Shorter drags create sharper transitions, longer drags create smoother blends.

Gradient Types

Linear
Radial
Conical

Straight line gradient

Transitions in one direction
Start and end points define gradient line
Colors perpendicular to line remain constant

Best for:

Sky backgrounds
Directional lighting
Simple color fades

Select gradient type from the context bar.

Gradient Controls

Draw Direction

How you draw affects the gradient:

Start to End

Normal drag

Start point = first color
End point = second color
Transition fills between points

From Center

Hold Alt while dragging

Center point = first color
Drags outward symmetrically
Creates centered gradients

Angle Snapping

Snap to Angles

Hold Shift while dragging to snap to angles:

0° - Horizontal (left to right)
45° - Diagonal
90° - Vertical (top to bottom)
135° - Diagonal
180° - Horizontal (right to left)

The gradient tool uses the FirstPoint intertwiner which supports angle snapping.

Dithering Options

Dithering creates the illusion of more colors through patterns:

No Dithering

Smooth gradient

Uses all available colors
Smoothest possible transition
Can show banding in limited palettes

Best for: RGB color mode, high color count

Bayer 8x8

Ordered dithering pattern

Uses 8x8 Bayer matrix
Creates regular pattern
Predictable dithering

Best for: Retro aesthetics, consistent patterns

Bayer 4x4

Smaller ordered pattern

Uses 4x4 Bayer matrix
Coarser than 8x8
More visible pattern

Best for: Very limited palettes, stronger texture

Bayer 2x2

Smallest ordered pattern

Uses 2x2 Bayer matrix
Most visible pattern
Checkered appearance

Best for: Minimal colors, strong retro effect

Error Diffusion

Floyd-Steinberg dithering

Diffuses quantization error to adjacent pixels
More organic appearance
Less regular pattern

Best for: Natural looking gradients, pixel art

Dithering is especially important when working with Indexed color mode with limited palettes. It helps create smoother-looking gradients using fewer colors.

Advanced Features

Gradient Ink

The gradient tool uses a special Gradient Ink:

// From: source/src/app/tools/inks.h:207
class GradientInk : public BaseInk {
  bool isPaint() const override { return true; }
  bool isEffect() const override { return true; }
  bool withDitheringOptions() const override { return true; }
};

Key characteristics:

Paint ink: Modifies pixels directly
Effect ink: Processes entire stroke at once
Supports dithering: Multiple dithering algorithms available

Working with Selections

Gradients respect active selections:

Create Selection

Use any selection tool to define the area

Draw Gradient

Gradient only affects pixels within selection

Boundaries Respected

Gradient is clipped to selection boundaries

Complex Gradient Shapes: Use selections to create gradients in specific shapes:

Make an elliptical selection
Apply radial gradient inside
Result: Sphere-like gradient only in ellipse

Multi-Point Gradients

Create gradients with multiple color stops:

Using Multiple Colors

While the gradient tool directly supports two colors, you can create multi-color effects:Method 1: Layer Multiple Gradients

Create first gradient (Color A → Color B)
New layer with transparency
Create second gradient (Color B → Color C)
Blend layers

Method 2: Use Gradient Editor (via scripting)

Create custom gradient through Lua scripting
Define multiple color stops
Apply to selection

Gradient Techniques

Creating Depth

Use gradients to add depth and dimension:

Base Color

Fill your shape with a base color

Overlay Gradient Layer

Create new layer, set to Overlay blend mode

Apply Gradient

Draw gradient from light to dark

Adjust Opacity

Lower layer opacity for subtle effect

Pixel Art Gradients

For pixel art with limited colors:

Manual Gradient

Create gradients by hand for pixel-perfect control:

Choose 3-5 colors from palette
Arrange in gradient order
Fill tool to place colors
Manually adjust transitions

Pros: Total control, clean pixels Cons: Time-consuming

Dithered Gradient

Use gradient tool with dithering:

Enable Bayer 8x8 or Error Diffusion
Draw gradient
Optionally clean up dithering pattern

Pros: Fast, smooth transitions Cons: May need manual touch-up

Lighting Effects

Create realistic lighting:

Identify Light Source

Determine where light is coming from

Highlight Gradient

Use radial gradient from light color to transparent

Shadow Gradient

Use linear gradient from dark to transparent

Layer Blending

Use Overlay or Soft Light blend modes

Indexed Color Mode

Gradients work differently in indexed color mode:

Limited Palette GradientsIn indexed mode:

Only uses colors from active palette
Dithering becomes essential
Cannot create colors outside palette
Color count affects smoothness

Tip: Design your palette with gradient colors in mind. Include transition colors for smoother gradients.

Palette Optimization

Create better gradients in indexed mode:

Analyze Gradient Needs

Identify how many gradient steps you need

Add Transition Colors

Add intermediate colors to palette

Sort Palette

Arrange colors in gradient order

Apply Gradient

Use gradient tool with dithering

Technical Details

Stroke Processing

The gradient tool processes the entire stroke at once:

// From: source/src/app/tools/inks.h:217
void prepareForStrokes(ToolLoop* loop, Strokes& strokes) override {
  proc()->prepareForStrokes(loop, strokes);
}

Why this matters:

Gradient calculated from full stroke
All pixels computed before rendering
Ensures smooth, consistent gradient
Different from incremental tools (pencil, brush)

Intertwiner: FirstPoint

Gradient uses the FirstPoint intertwiner:

// From: source/src/app/tools/intertwiners.h:54
class IntertwineFirstPoint : public Intertwine {
  bool snapByAngle() override { return true; }
  // Applies effect to center or first point
};

This means:

The gradient effect is applied as a whole
Supports angle snapping (Shift key)
Calculates from stroke endpoints

Common Workflows

Sky Background

New Layer

Create background layer for sky

Choose Colors

Foreground: Light sky color (top)
Background: Darker horizon color (bottom)

Draw Gradient

Drag from top to bottom with Linear gradient

Optional Dithering

Enable subtle dithering if banding occurs

Radial Highlight

Select Area

Create circular selection where highlight should appear

Set Colors

Foreground: Bright highlight color
Background: Base surface color

Apply Radial Gradient

Switch to Radial mode, drag from center outward

Blend

Set layer to Screen or Add blend mode

Performance Considerations

Large Gradient Performance

Factors affecting speed:

Canvas size: Larger = slower
Dithering: Error diffusion is slower than Bayer
Color mode: Indexed is faster than RGB
Selection complexity: Complex shapes take longer

For very large canvases, expect a brief delay while the gradient calculates. This is normal for effect-based inks.

Keyboard Shortcuts

Quick Reference

Shift+G         - Select Gradient tool
G               - Switch to Fill tool
Shift (hold)    - Snap to angle increments
Alt (hold)      - Draw from center
Ctrl+Z          - Undo gradient

Get Started

Core Concepts

Drawing Tools

Advanced Features

Workspace

Import & Export

Overview

Basic Usage

Gradient Types

Gradient Controls

Draw Direction

Start to End

From Center

Angle Snapping

Dithering Options

Advanced Features

Gradient Ink

Working with Selections

Multi-Point Gradients

Gradient Techniques

Creating Depth

Pixel Art Gradients

Lighting Effects

Indexed Color Mode

Palette Optimization

Technical Details

Stroke Processing

Intertwiner: FirstPoint

Common Workflows

Sky Background

Radial Highlight

Performance Considerations

Keyboard Shortcuts

Tool Overview

Fill Tool

Color Modes

Palettes

Layers & Blending

Build docs developers (and LLMs) love

Get Started

Core Concepts

Drawing Tools

Advanced Features

Workspace

Import & Export

Documentation Index

​Overview

​Basic Usage

​Gradient Types

​Gradient Controls

​Draw Direction

Start to End

From Center

​Angle Snapping

​Dithering Options

​Advanced Features

​Gradient Ink

​Working with Selections

​Multi-Point Gradients

​Gradient Techniques

​Creating Depth

​Pixel Art Gradients

​Lighting Effects

​Indexed Color Mode

​Palette Optimization

​Technical Details

​Stroke Processing

​Intertwiner: FirstPoint

​Common Workflows

​Sky Background

​Radial Highlight

​Performance Considerations

​Keyboard Shortcuts

​Related Topics

Tool Overview

Fill Tool

Color Modes

Palettes

Layers & Blending

Build docs developers (and LLMs) love

Overview

Basic Usage

Gradient Types

Gradient Controls

Draw Direction

Angle Snapping

Dithering Options

Advanced Features

Gradient Ink

Working with Selections

Multi-Point Gradients

Gradient Techniques

Creating Depth

Pixel Art Gradients

Lighting Effects

Indexed Color Mode

Palette Optimization

Technical Details

Stroke Processing

Intertwiner: FirstPoint

Common Workflows

Sky Background

Radial Highlight

Performance Considerations

Keyboard Shortcuts

Related Topics