Working with Gradients

Gradients add depth and visual interest to your FxCanvas drawings by smoothly transitioning between colors. They're perfect for backgrounds, highlights, shadows, and creating realistic materials. FxCanvas supports both linear and radial gradients that can be applied to fills and strokes.

Understanding Gradients

A gradient is a smooth color transition between two or more colors. Instead of solid colors, gradients create natural-looking effects like sunsets, metallic surfaces, or glowing elements. FxCanvas gradients work by defining a color at specific points along a line (linear) or within a circle (radial), then interpolating between them.

Gradients build on basic colors; explore color options in Working with Colors.

Linear Gradients

Linear gradients create color transitions along a straight line. This is ideal for backgrounds, button highlights, or directional lighting effects.

To create a linear gradient, use the LinearGradient class:

import { CanvasEncoder, LinearGradient, Color } from 'fxcanvas';

const canvas = new CanvasEncoder(400, 200);

// Create a horizontal gradient from left to right
const gradient = new LinearGradient(0, 0, 200, 0);

// Add color stops
gradient.addColorStop(0, new Color(255, 0, 0));    // Start with red
gradient.addColorStop(1, new Color(0, 0, 255));     // End with blue

The gradient line defines the direction of the color transition. Colors flow perpendicular to this line.

Radial Gradients

Radial gradients create circular color transitions, emanating from a center point. They're great for creating spherical objects, light sources, or circular highlights.

Use the RadialGradient class:

import { RadialGradient } from 'fxcanvas';

// Create a radial gradient from center outward
const gradient = new RadialGradient(100, 100, 0, 100, 100, 100);

// Add color stops
gradient.addColorStop(0, new Color(255, 255, 0));  // Center color - yellow
gradient.addColorStop(1, new Color(255, 165, 0));   // Outer color - orange

This creates a circular gradient centered at (100, 100), starting from yellow in the center and transitioning to orange at the edge.

Transforming Radial Gradients on Ellipses

To create elliptical gradients (as found in design tools), transform a circular radial gradient using canvas transformations. This technique scales down one axis to compress the gradient into an elliptical shape, useful for organic lighting effects or shaped highlights.

Create the radial gradient at (0,0) with the outer radius matching the ellipse's major axis, then use save/translate/scale/setFillStyle/fillEllipse/restore to apply the transformation.

// Create radial gradient for elliptical effect
const gradient = new RadialGradient(0, 0, 1, 0, 0, 120);
gradient.addColorStop(0, new Color(0, 0, 0, 1));     // Pure black center
gradient.addColorStop(1, new Color(0, 0, 0, 0));     // Transparent black edge

// Basic elliptical compression
canvas.save();
canvas.translate(128, 128);  // Center on 256x256 canvas
canvas.scale(1.0, 0.5);      // Scale down vertically for elliptical effect
canvas.setFillStyle(gradient);
canvas.fillEllipse(0, 0, 120, 120);
canvas.restore();

For rotated elliptical gradients, apply rotation after translation but before scaling:

// With rotation
canvas.save();
canvas.translate(128, 128);
canvas.rotate(Math.PI / 6);   // 30° rotation
canvas.scale(1.0, 0.5);
canvas.setFillStyle(gradient);
canvas.fillEllipse(0, 0, 120, 120);
canvas.restore();

The order of transformations is important: translate positions the gradient, rotate orients it, and scale compresses it elliptically. For more on transformations, see Transformations. For state management with save/restore, see Managing Canvas State.

Images can also incorporate gradients; see Working with Images for details.

Adding Color Stops

Both gradient types use color stops to define the color transitions. Each stop has a position (0 to 1) and a Color object.

const gradient = new LinearGradient(0, 0, 200, 0);

// Multiple color stops for complex gradients
gradient.addColorStop(0, new Color(255, 0, 0));     // red
gradient.addColorStop(0.5, new Color(255, 255, 0));  // yellow
gradient.addColorStop(1, new Color(0, 128, 0));      // green

Positions range from 0 (start) to 1 (end). You can add as many stops as needed for smooth or abrupt transitions.

Using Gradients in Fills

Gradients can be assigned as fill styles, filling the interior of shapes with smooth color transitions. This is perfect for backgrounds, buttons, and organic shapes.

// Create a linear gradient
const gradient = new LinearGradient(0, 0, 200, 0);
gradient.addColorStop(0, new Color(255, 0, 0)); // red
gradient.addColorStop(1, new Color(0, 0, 255));  // blue

// Set the gradient as the fill style
canvas.setFillStyle(gradient);

// Draw shapes filled with the gradient
canvas.fillRect(50, 50, 200, 100);

The gradient fills the shape based on its definition. For linear gradients, the direction and position affect how colors appear within the shape.

Using Gradients in Strokes

Gradients can also be applied to stroke styles, creating outlines with color transitions along their paths. This adds visual interest to borders and paths.

// Use the same gradient for strokes
canvas.setStrokeStyle(gradient);
canvas.setLineWidth(5);

// Draw stroked shapes
canvas.strokeRect(50, 50, 200, 100);

// Or custom paths
canvas.beginPath();
canvas.moveTo(100, 100);
canvas.lineTo(200, 150);
canvas.stroke();

The gradient follows the stroke path, with colors distributed along the outline. Thicker lines show more of the gradient transition.

For more on stroke properties like line width and joins, see Working with Strokes.

Advanced Gradient Techniques

Diagonal and Angled Gradients

// Diagonal gradient for depth effects
const diagonal = new LinearGradient(0, 0, 200, 200);
diagonal.addColorStop(0, new Color(255, 255, 255)); // white
diagonal.addColorStop(1, new Color(0, 0, 0));        // black

canvas.setFillStyle(diagonal);
canvas.fillRect(50, 50, 200, 200);

Concentric Radial Effects

// Layered radial gradients for glows or spheres
const glow = new RadialGradient(100, 100, 20, 100, 100, 80);
glow.addColorStop(0, new Color(255, 255, 0, 0.8));    // yellow with alpha
glow.addColorStop(0.7, new Color(255, 165, 0, 0.4));  // orange with alpha
glow.addColorStop(1, new Color(0, 0, 0, 0));          // transparent

canvas.setFillStyle(glow);
canvas.fillRect(20, 20, 160, 160);

Combining Fill and Stroke Gradients

const fillGradient = new LinearGradient(0, 0, 0, 100);
fillGradient.addColorStop(0, new Color(173, 216, 230)); // lightblue
fillGradient.addColorStop(1, new Color(0, 0, 139));     // darkblue

const strokeGradient = new LinearGradient(0, 0, 100, 0);
strokeGradient.addColorStop(0, new Color(255, 215, 0)); // gold
strokeGradient.addColorStop(1, new Color(255, 165, 0));  // orange

canvas.setFillStyle(fillGradient);
canvas.setStrokeStyle(strokeGradient);
canvas.setLineWidth(4);
canvas.fillRect(50, 50, 100, 100);
canvas.strokeRect(50, 50, 100, 100);

Repeating Patterns

While FxCanvas doesn't have built-in repeating gradients, you can simulate them by using multiple stops or creating tileable effects.

Gradients can also be used as patterns for more complex effects; learn more in Working with Patterns.

By mastering gradient usage, you can create visually stunning effects that enhance the realism and appeal of your FxCanvas applications.