# Gradient Tool

The Gradient tool paints a smooth transition between your current foreground and background colors on the canvas.

You can activate the Gradient tool from the canvas toolbar.

## Where Gradient Draws

Gradient only draws into the **active raster layer**:

- It does not draw into inpaint masks.
- It does not draw into other non-raster layer types.
- The result is always clipped to the current **generation bounding box**.

If a raster layer is not selected, the tool is unavailable.

## Common Behavior

- Click and drag to define the gradient.
- Release the pointer to commit the gradient.
- Press `Esc` to discard the in-progress gradient.
- Hold `Alt` to temporarily switch to the color picker.
- Hold `Space` to temporarily switch to panning.

The Gradient tool uses the current **FG/BG color pair**:

- The **active** color swatch becomes the start color.
- The **inactive** color swatch becomes the end color.

## Gradient Modes

### Linear

Click and drag to set the gradient direction. The drag defines the transition from the start color to the end color.

### Radial

Click to place the center, then drag outward to set the radius. The gradient fades from the start color at the center to the end color toward the outside.

## Transparency Lock

When **Transparency Lock** is enabled on the active raster layer, the Gradient tool respects it:

- The gradient only affects pixels that already have opacity on the layer.
- Fully transparent areas stay transparent.
- This applies to both **Linear** and **Radial** gradients.

Use this when you want to recolor or shade existing painted content without spilling into empty transparent regions of the layer.

## Clip Gradient

The toolbar includes a **Clip Gradient** toggle:

- **Enabled:** Limits the gradient to the dragged region.
- **Disabled:** Lets the gradient extend across the full current bounding box.

In practice:

- A clipped **linear** gradient is limited to the span you dragged.
- A clipped **radial** gradient is limited to the circle you dragged out.
- With clipping disabled, both modes can be used to wash the entire bbox with a full gradient transition.

## Practical Examples

- Use **Linear** for sky fades, shadow ramps, and broad directional lighting.
- Use **Radial** for vignettes, glows, spotlights, and soft falloff around a focal point.
- Enable **Transparency Lock** when you want the gradient to stay inside existing painted pixels.
- Disable **Clip Gradient** when you want a full-bbox color transition.
- Keep **Clip Gradient** enabled when you only want to affect a localized area.

## Summary

The Gradient tool is a raster-only canvas tool for painting linear and radial color transitions. Use it when you want soft blends between your FG and BG colors, use **Transparency Lock** to keep the effect inside existing opaque pixels, and use **Clip Gradient** to decide whether the effect stays local or fills the full bbox.