Custom effects

An effect is anything with an Apply method:

type Effect interface {
	Apply(s *canvas.Surface, t float64)
}

s is the area of cells to change: a node's own cells for a transition, or the frame beneath a layer for a backdrop. t is the progress, from 0 to 1. For a transition, an effect at 1 should leave the cells as they are, so the node ends up looking like itself.

Write an effectCopy Anchor Link

This effect flashes a node in a color and fades it back to its own colors, such as to draw attention to a value that just changed:

import (
	"image/color"

	"github.com/lrstanley/bloom/canvas"
)

// Flash shows a node in Color at first, and fades it back to its own colors as t
// reaches 1.
type Flash struct {
	Color color.Color
}

// Apply implements fx.Effect.
func (e Flash) Apply(s *canvas.Surface, t float64) {
	for y := range s.Height() {
		for x := range s.Width() {
			c := s.Cell(x, y)
			if c == nil {
				continue
			}
			c.Style.Fg = s.Mix(e.Color, s.Fg(c), t)
		}
	}
}

Use it like any other effect:

bloom.Transition(m.flash.Float(), value, Flash{Color: lipgloss.Color("#f6c177")})

Keep effects comparableCopy Anchor Link

bloom skips drawing a frame that's identical to the previous one, and compares effects with == to find out. A struct of plain fields, like Flash, compares by value, so a node that isn't animating costs nothing to keep on screen.

fx.Func turns a function into an effect, which is handy for a quick experiment:

var revealDown = fx.Func(func(s *canvas.Surface, t float64) {
	for y := int(t * float64(s.Height())); y < s.Height(); y++ {
		for x := range s.Width() {
			s.Hide(x, y)
		}
	}
})

But Go can't compare functions, so bloom assumes a function effect changes every frame and redraws whenever it's on screen. Effects behind pointers are treated the same way, since they can change in place. Prefer a struct for effects you keep.

What a surface offersCopy Anchor Link

canvas.Surface is the grid of cells an effect changes. Coordinates are relative to its top-left cell.

Cells are Ultraviolet cells: c.Content is the glyph, c.Width its width in columns, and c.Style its colors and attributes.

Draw directly with DrawableCopy Anchor Link

An effect transforms cells that something else drew. To paint cells yourself, such as a chart, a meter, or a game board, implement Ultraviolet's Drawable interface and place it with bloom.Drawable:

import (
	"image/color"

	uv "github.com/charmbracelet/ultraviolet"
)

// meter fills a fraction of its area, from the left.
type meter struct {
	value float64 // from 0 to 1
	color color.Color
}

func (m meter) Draw(scr uv.Screen, area uv.Rectangle) {
	filled := area.Min.X + int(m.value*float64(area.Dx()))
	for y := area.Min.Y; y < area.Max.Y; y++ {
		for x := area.Min.X; x < area.Max.X; x++ {
			glyph := "░"
			if x < filled {
				glyph = "█"
			}
			scr.SetCell(x, y, &uv.Cell{Content: glyph, Width: 1, Style: uv.Style{Fg: m.color}})
		}
	}
}

bloom.Row(
	bloom.Text("cpu "),
	bloom.Fill(bloom.Drawable(meter{value: m.cpu, color: lipgloss.Color("#eb6f92")})),
)

cpu ████████░░░░░░░░░░░░

The drawable is clipped to the area it's given. Its natural size is zero unless it also implements bloom.Measurer, so give it a sized slot such as Fill or Fixed.

RelatedCopy Anchor Link

• fx package source, for how the built-in effects are written
• The effects example, with two custom effects and a Drawable