Background Generators

3 min read

PinePaper provides procedural background generators that create dynamic patterns and scenes.

Using Generators

Execute a Generator

await app.executeGenerator('drawSunburst', {
  colors: ['#4f46e5', '#7c3aed', '#a855f7'],
  rayCount: 16,
  bgColor: '#0f172a'
});

Available Generators

Generator Category Description
drawSunburst effects Radial rays from center
drawSunsetScene effects Animated sunset with clouds
drawGrid geometric Lines, dots, or squares grid
drawStackedCircles effects Overlapping circles with distribution
drawCircuit geometric Tech circuit board pattern
drawWaves organic Layered wave pattern
drawPattern geometric Geometric shapes in orbit
drawBokeh effects Soft blurred circles for depth-of-field
drawGradientMesh organic Multi-color gradient blobs
drawGeometricAbstract geometric Overlapping translucent shapes
drawWindField particles Animated directional wind particles
drawFluidFlow organic Smooth flowing stream patterns
drawOrganicFlow organic Aurora/silk flowing layers
drawNoiseTexture textures Perlin noise, grain, stipple textures

Get Generator List

const generators = app.getAvailableBackgroundGenerators();
generators.forEach(g => {
  console.log(g.name, g.displayName, g.description);
});

Generator Registry

The GeneratorRegistry manages all generators and supports:

  • Parameter schemas with validation
  • Live parameter updates (knobs)
  • Animation callbacks
  • Custom generator registration

Get Registry

const registry = app.generatorRegistry;

Check if Generator Exists

if (registry.has('drawSunburst')) {
  // Generator is available
}

Distribution Utilities

Built-in algorithms for natural element placement:

Poisson Disk Sampling

Evenly distributed points with minimum distance.

const points = await app.workerPool.poissonDiskSampling(800, 600, 50);
// points = [{x, y}, ...]

Golden Ratio Distribution

Spiral distribution following golden ratio.

const points = await app.workerPool.goldenRatioDistribution(100, 800, 600);

Parameters

Each generator accepts specific parameters. Use getAvailableBackgroundGenerators() to see the parameter schema for each.

Common parameters:

  • colors - Color palette array
  • bgColor - Background fill color
  • count - Number of elements
  • speed - Animation speed multiplier

Animation

Generators can include animated elements. The animation runs automatically in the view.onFrame loop.

// Generator animation updates automatically via internal update() method
// Called on every frame for generators with animations

Generator Management

setBackgroundGenerator(name, params)

Set the active background generator.

Parameters:

  • name (string): Generator name
  • params (object): Generator parameters
app.setBackgroundGenerator('drawSunburst', {
  colors: ['#4f46e5', '#7c3aed'],
  rayCount: 16
});

getGeneratedElements()

Get all elements created by the current generator.

Returns: Map - Map of generated element groups

const elements = app.getGeneratedElements();
elements.forEach((group, key) => {
  console.log(key, group.children.length);
});

updateGeneratorParam(paramName, value)

Live-update a single generator parameter without re-executing.

Parameters:

  • paramName (string): Parameter name
  • value (any): New value
// Change ray count without full re-render
app.updateGeneratorParam('rayCount', 24);

Switching Generators

To clear a generator and switch to another mode:

// Switch to generator mode (interactive selection)
app.setBackgroundMode('generator');

// Switch to drawing mode
app.setBackgroundMode('drawing');

// Execute a new generator (replaces previous)
await app.executeGenerator('drawSunburst', { colors: ['#ff0000', '#00ff00'] });