FxCanvas Documentation

Appearance

Working with Patterns ​

Patterns allow you to fill or stroke shapes with repeating textures or images, creating rich, tiled backgrounds and effects. Unlike solid colors or gradients, patterns use image data that repeats across the filled or stroked area.

Understanding Patterns ​

Patterns are created from Image objects and can repeat in various ways. They're perfect for creating textured backgrounds, seamless tiles, or complex fill effects that go beyond simple colors.

Patterns enhance basic colors and images; see Working with Colors and Working with Images.

Creating Patterns from Images ​

The Pattern class creates a pattern from an Image source.

javascript
import { CanvasEncoder, Pattern, Image, RepetitionStyle } from 'fxcanvas';

const canvas = new CanvasEncoder(400, 200);

// Create an image
const img = new Image('texture.png');

// Create a repeating pattern
const pattern = new Pattern(img, RepetitionStyle.Repeat);

// Use as fill style
canvas.setFillStyle(pattern);
canvas.fillRect(0, 0, 200, 200);

The repetition parameter controls how the pattern repeats:

  • RepetitionStyle.Repeat - Repeats in both directions (default)
  • RepetitionStyle.RepeatX - Repeats horizontally only
  • RepetitionStyle.RepeatY - Repeats vertically only
  • RepetitionStyle.NoRepeat - No repetition, pattern appears once

Pattern Repetition Options ​

Full Repeat ​

javascript
const pattern = new Pattern(img, RepetitionStyle.Repeat);
// Fills entire area with tiled image

Horizontal Repeat Only ​

javascript
const pattern = new Pattern(img, RepetitionStyle.RepeatX);
// Repeats horizontally, single row vertically

Vertical Repeat Only ​

javascript
const pattern = new Pattern(img, RepetitionStyle.RepeatY);
// Repeats vertically, single column horizontally

No Repeat ​

javascript
const pattern = new Pattern(img, RepetitionStyle.NoRepeat);
// Pattern appears once at origin

Creating Patterns from Image Data ​

You can create patterns from Image objects with custom data, allowing for procedural or dynamic textures.

javascript
// Create an image with custom data (this would typically come from another source)
const patternImage = new Image();
patternImage.data = new Uint8Array(/* image data */);
patternImage.width = 20;
patternImage.height = 20;
patternImage.mimeType = ImageMimeType.Png;

// Create pattern from image
const pattern = new Pattern(patternImage, RepetitionStyle.Repeat);
canvas.setFillStyle(pattern);
canvas.fillRect(0, 0, 200, 200);

For procedural patterns, you can generate image data programmatically or load from external sources.

Using Patterns in Fills ​

Once created, patterns work just like colors or gradients in fill operations.

javascript
// Fill shapes with patterns
canvas.setFillStyle(pattern);
canvas.fillRect(50, 50, 150, 100);

// Fill paths
canvas.beginPath();
canvas.arc(100, 100, 50, 0, Math.PI * 2);
canvas.fill();

// Fill text
const font = new Font({ size: 48, faces: [fontFace] });
canvas.setFont(font);
canvas.fillText('Pattern Text', 50, 150);

Using Patterns in Strokes ​

Patterns can also be applied to strokes, creating textured outlines. FxCanvas supports using colors, gradients, and patterns as stroke styles.

Solid Color Strokes ​

javascript
canvas.setStrokeStyle(new Color(255, 0, 0)); // red
canvas.setLineWidth(5);
canvas.strokeRect(50, 50, 150, 100);

Linear Gradient Strokes ​

javascript
const linearStroke = new LinearGradient(0, 0, 150, 0);
linearStroke.addColorStop(0, new Color(255, 0, 0)); // red
linearStroke.addColorStop(1, new Color(0, 0, 255)); // blue
canvas.setStrokeStyle(linearStroke);
canvas.setLineWidth(5);
canvas.strokeRect(50, 50, 150, 100);

Radial Gradient Strokes ​

javascript
const radialStroke = new RadialGradient(100, 100, 10, 100, 100, 50);
radialStroke.addColorStop(0, new Color(255, 255, 0)); // yellow
radialStroke.addColorStop(1, new Color(255, 0, 0)); // red
canvas.setStrokeStyle(radialStroke);
canvas.setLineWidth(5);
canvas.strokeRect(50, 50, 150, 100);

Pattern Strokes ​

javascript
const strokePattern = new Pattern(img, RepetitionStyle.Repeat);
canvas.setStrokeStyle(strokePattern);
canvas.setLineWidth(10);
canvas.strokeRect(50, 50, 150, 100);

Patterns in strokes follow the path of the outline, creating textured borders and decorative effects.

For gradient strokes, see Working with Gradients.

For more stroke properties, see Working with Strokes.

Advanced Pattern Techniques ​

Scaled Patterns ​

javascript
// Create pattern from image
const largeImg = new Image('large-texture.jpg');

const pattern = new Pattern(largeImg, RepetitionStyle.Repeat);

// Scale the pattern by transforming the encoder
canvas.save();
canvas.scale(0.5, 0.5); // Make pattern appear larger
canvas.setFillStyle(pattern);
canvas.fillRect(0, 0, 400, 400); // Scaled coordinates
canvas.restore();

Pattern with Transparency ​

javascript
// Create pattern from image with alpha channel
const alphaImg = new Image('semi-transparent-texture.png');

const alphaPattern = new Pattern(alphaImg, RepetitionStyle.Repeat);
canvas.setFillStyle(alphaPattern);
canvas.fillRect(0, 0, 200, 200);

Combining Patterns with Other Styles ​

javascript
// Use pattern as base, add gradient overlay
const basePattern = new Pattern(img, RepetitionStyle.Repeat);
canvas.setFillStyle( basePattern;
canvas.fillRect(0, 0, 200, 200);

// Add gradient on top
const gradient = new LinearGradient(0, 0, 200, 200);
gradient.addColorStop(0, new Color(255, 255, 255, 0.5));
gradient.addColorStop(1, new Color(0, 0, 0, 0.5));

canvas.setGlobalCompositeOperation(GlobalCompositeOperation.Overlay);
canvas.setFillStyle(gradient);
canvas.fillRect(0, 0, 200, 200);
canvas.setGlobalCompositeOperation(GlobalCompositeOperation.SourceOver);

Fill patterns bring texture and visual interest to your FxCanvas drawings, enabling everything from subtle backgrounds to striking visual effects.