Documentation
¶
Overview ¶
Package scene is the display list the ui package paints a frame into and the renderers draw: rounded rectangles with borders and gradients, box shadows, glyphs from a shared atlas, images, effects and clips, in paint order. Geometry is in device pixels with the origin at the top-left corner.
Index ¶
- Constants
- func BlurWeight(i int, sigma float32) float32
- func Corners(r Rect, radii [4]float32, continuous bool) [4]float32
- func FitRadii(r Rect, radii [4]float32) [4]float32
- func GammaRatios(gamma float32) [4]float32
- func HasBorder(w [4]float32) bool
- func ImageArea(src Rect, w, h int) image.Rectangle
- func Oklab(c Color) [3]float32
- func SDRoundRect(r Rect, radii [4]float32, px, py float32) float32
- func SubpixelCoverage(a, c [3]float32, contrast, boost float32, g [4]float32) [3]float32
- func TextCoverage(a float32, c [3]float32, contrast, boost float32, g [4]float32) float32
- func Uniform(w float32) [4]float32
- type Affine
- func (m Affine) Bounds(r Rect) Rect
- func (m Affine) Inverse() (Affine, bool)
- func (m Affine) Mul(n Affine) Affine
- func (m Affine) Perspective() bool
- func (m Affine) Pixels(scale float32) Affine
- func (m Affine) Point(x, y float32) (float32, float32)
- func (m Affine) VectorAt(x, y, dx, dy float32) (float32, float32)
- func (m Affine) W(x, y float32) float32
- type Atlas
- func (a *Atlas) Alloc(w, h int) (x, y int, ok bool)
- func (a *Atlas) AllocTransient(w, h int) (x, y int, ok bool)
- func (a *Atlas) Changes(gen, version uint64) (rects []image.Rectangle, full bool)
- func (a *Atlas) Generation() uint64
- func (a *Atlas) Grow() bool
- func (a *Atlas) Put(x, y, w, h int, src []byte, stride int)
- func (a *Atlas) Repack(rects []image.Rectangle) ([]image.Point, bool)
- func (a *Atlas) Reset()
- func (a *Atlas) ResetTransient()
- func (a *Atlas) Version() uint64
- type Backdrop
- type BackdropImage
- type ClipShape
- type Color
- type Effect
- type EffectCode
- type EffectOp
- type EffectPixels
- type Glyph
- type Image
- type Kind
- type Op
- type Paint
- type Rect
- type Scene
- type ShaderLayout
- type Stop
- type TextParams
- type WideColors
- type WideSet
Constants ¶
const MaxAtlasSize = 4096
MaxAtlasSize is the largest width and height an Atlas grows to.
const MaxStops = 32
MaxStops is how many stops a gradient has at most, which the shaders loop through.
const ThinBoost = 0.5
ThinBoost is the contrast Direct2D adds for thin glyphs.
Variables ¶
This section is empty.
Functions ¶
func BlurWeight ¶ added in v0.2.10
BlurWeight returns the weight of the texel i texels away in a blur of standard deviation sigma, before the weights are divided by their sum.
func Corners ¶ added in v0.2.10
Corners returns radii as renderers take them: fitted to r (FitRadii), and negative for continuous corners.
func FitRadii ¶
FitRadii scales corner radii down so that adjacent ones fit along each side of r, as CSS does; renderers apply it before drawing.
func GammaRatios ¶ added in v0.2.4
GammaRatios returns Direct2D's alpha correction ratios for text blended at a gamma between 1 and 2.2, as Windows Terminal computes them.
func ImageArea ¶ added in v0.5.5
ImageArea returns the pixels of an image of w×h that src, a rectangle of them, touches, which a blur of it reads.
func Oklab ¶ added in v0.5.5
Oklab returns c, in sRGB, in the Oklab color space, as the renderers mix gradients in it: the CPU's from this, the GPU's from the stops' values it gives them, or from the same math in their shaders.
func SDRoundRect ¶ added in v0.2.10
SDRoundRect returns the signed distance from (px, py) to the edge of the rounded rectangle r with radii (fitted), negative inside, as the shaders' sdRoundRect.
func SubpixelCoverage ¶ added in v0.2.4
SubpixelCoverage corrects the coverage of each subpixel of a subpixel glyph of straight color c, as Direct2D blends ClearType text.
func TextCoverage ¶ added in v0.2.4
TextCoverage corrects the coverage a of a glyph of straight color c, as Direct2D blends text: it enhances the contrast by contrast, the more the darker c is, plus boost, and corrects for the gamma of the ratios g.
Types ¶
type Affine ¶ added in v0.4.3
Affine maps drawing coordinates to frame coordinates: an affine map, or, when G or H is set, a projective one, which shows a plane turned in 3D in perspective, x and y going to
((A*x + C*y + X) / w, (B*x + D*y + Y) / w), with w = G*x + H*y + 1.
The zero value is identity; Set distinguishes a singular matrix (including scale zero).
func Projective ¶ added in v0.4.3
Projective returns the projective map of the matrix
| a c x | | b d y | | g h 1 |
func Translation ¶ added in v0.4.3
func (Affine) Perspective ¶ added in v0.4.3
Perspective reports whether m is projective, not affine.
func (Affine) Point ¶ added in v0.4.3
Point returns where m maps (x, y). A point behind the viewer of a projective map (W not positive) goes far away.
type Atlas ¶
type Atlas struct {
// BPP is the number of bytes per pixel: 1 for coverage masks, 4 for
// premultiplied RGBA.
BPP int
// W and H are the size in pixels; Pix holds rows of W*BPP bytes.
W, H int
Pix []byte
// contains filtered or unexported fields
}
Atlas packs small bitmaps, such as rasterized glyphs, into one larger bitmap that renderers keep as a texture. It records which rectangles changed so that renderers upload only those. Main thread only.
Lasting bitmaps fill shelves down from the top. Bitmaps a single frame draws, such as the masks of animated shapes, fill shelves up from the bottom, and ResetTransient frees them all at once, so that they never crowd out the lasting ones.
func (*Atlas) Alloc ¶
Alloc reserves a lasting w×h rectangle, keeping a pixel of padding to its right and below it so that filtering never reads a neighbor. It reports false when the atlas is full; the caller then repacks, grows or resets it.
func (*Atlas) AllocTransient ¶
AllocTransient is Alloc for a rectangle needed until ResetTransient.
func (*Atlas) Changes ¶
Changes returns the rectangles changed since version, or full when the renderer, which last uploaded version of generation gen, must upload everything.
func (*Atlas) Generation ¶
Generation changes when the atlas is resized, reset or repacked, which makes renderers create a new texture and upload all of it.
func (*Atlas) Grow ¶
Grow doubles the atlas up to MaxAtlasSize, keeping its lasting bitmaps where they are; it frees the transient ones. It reports false when the atlas is already at its largest.
func (*Atlas) Put ¶
Put copies a w×h bitmap with rows of stride bytes to (x, y), and clears the padding after it, which may hold an earlier bitmap's pixels.
func (*Atlas) Repack ¶
Repack frees the atlas and allocates rects, lasting rectangles of it, again, tallest first, moving their pixels along. It returns where each went, or false, changing nothing, when they do not fit.
func (*Atlas) Reset ¶
func (a *Atlas) Reset()
Reset empties the atlas: every allocation becomes invalid.
func (*Atlas) ResetTransient ¶
func (a *Atlas) ResetTransient()
ResetTransient frees the rectangles AllocTransient reserved.
type Backdrop ¶ added in v0.2.10
Backdrop is what an effect reads of what is behind it: the pixels of Area, averaged over squares of Down pixels a side into a smaller image (Size), which a Gaussian of standard deviation Sigma (BlurWeight) blurs, out to Radius texels each way, first along rows, then along columns. Renderers keep each step in 8 bits a channel, rounded to the nearest, as textures hold them.
func BackdropOf ¶ added in v0.2.10
BackdropOf returns the backdrop of a shape r blurred by blur, in a frame of w×h pixels: what the blur reaches around it.
Large blurs are computed at a fraction of the size, as browsers do, a power of two up to 8 that leaves the blur at least 2 texels: the average of each square adds a variance of Down²/12 pixels², which the blur leaves out.
func ImageBlur ¶ added in v0.5.5
ImageBlur returns how an image's area is blurred by blur, the standard deviation in its pixels (Op.Blur): averaged over squares of Down pixels a side and blurred as a backdrop is (BackdropOf), within the area, which it reads as transparent beyond.
type BackdropImage ¶ added in v0.2.10
type BackdropImage struct {
Backdrop
// Transform maps local sampling coordinates to the frame.
Transform Affine
W, H int
Pix []float32
}
BackdropImage is a backdrop as the CPU renderer computes it: W×H texels of premultiplied RGBA, each channel a byte over 255, as a texture reads.
func (*BackdropImage) Sample ¶ added in v0.2.10
func (b *BackdropImage) Sample(x, y float32) [3]float32
Sample returns the backdrop at (x, y), in the frame's pixels, premultiplied RGB, filtered bilinearly from its texels and clamped to its edges, as the shaders' sampleBackdrop.
type ClipShape ¶ added in v0.4.3
ClipShape is a clip in the coordinate system in which it was pushed.
type Color ¶
type Color struct{ R, G, B, A uint8 }
Color is a straight (not premultiplied) sRGB color.
type Effect ¶ added in v0.2.10
type Effect struct {
// Name names the effect in errors.
Name string
// Backdrop tells that the effect reads its backdrop.
Backdrop bool
// Metal and HLSL are the effect's shader in Metal Shading Language
// and HLSL, with the code compiled ahead of time from it; GLSL is its
// shader in GLSL 3.30 and GLSL ES 3.00, which drivers compile.
Metal, HLSL EffectCode
GLSL string
// Pixels makes what draws the effect on the CPU, one for each
// renderer.
Pixels func() EffectPixels
// Shader is set for an effect that a shader of package ui/shader
// draws: its code is the shader's (the Fragment of package shaderir's
// backends, and a function calling it), which reads the words of
// EffectOp.Uniforms in a buffer laid out as Shader says, and the images
// of EffectOp.Images. Metal's is a whole library, with a tail of its
// own (ShaderSource in package metal); the others' go between the
// effects' head and tail.
Shader *ShaderLayout
}
Effect is a kind of drawing that a package outside the renderers defines, as the official plugins do (plugins/glass): a fragment shader for each GPU renderer, drawn with a pipeline of its own, and its twin for the CPU renderer, which must compute the same colors. An effect paints the shape of its OpEffect (Rect rounded by Radii) from its parameters, and from its backdrop when it reads one: what the operations before it painted around it, blurred (see Backdrop).
Each shader is the source of a function that the renderer puts between a head and a tail of its own, which declare what it reads and call it (EffectSource in packages metal, d3d11 and gl):
Metal: float4 effect(float2 p, Effect e, texture2d<float> backdrop) HLSL: float4 effect(float2 p, Effect e) GLSL: vec4 effect(vec2 p, Effect e)
It returns the premultiplied color at the pixel center p, in device pixels, of the shape e.rect rounded by e.radii, from the parameters e.p0 to e.p4 (EffectOp.Params); the renderer multiplies it by how much of the pixel the shape and the clip cover, and by the opacity. The shape's corners may be continuous (Op.Continuous), which the renderer covers as such, while e.radii, positive, has the effect take them as circular. In Metal, e.wide tells that the target keeps colors outside the sRGB gamut, in extended sRGB (Scene.Wide), which the effect may then take from a parameter holding such a color (ui.Painter.EffectColor). sampleBackdrop(e, q) (with the backdrop texture first in Metal) returns the backdrop at q, premultiplied, as BackdropImage.Sample does.
type EffectCode ¶ added in v0.2.10
EffectCode is an effect's shader in a language: its source, and the code compiled ahead of time from what the renderer makes of it (EffectSource), with the SHA-256 of that (gpu.SourceSum). Renderers compile the source when the sum no longer matches, as when the renderer's head or tail changed since.
type EffectOp ¶ added in v0.2.10
type EffectOp struct {
Effect *Effect
// Blur is the standard deviation of the blur of the backdrop, in
// pixels, for an effect that reads its backdrop.
Blur float32
// Params are the effect's own, which its shaders read as e.p0 to e.p4.
Params [5][4]float32
// Uniforms and Images are what a shader's effect reads
// (Effect.Shader): the words of its uniforms' lanes, and up to four
// images, bitmaps or canvases, nil for none.
Uniforms []uint32
Images [4]*Image
// WideUniforms, unless nil, are the words of Uniforms that renderers
// drawing a wide gamut (Scene.Wide) read in its place: colors outside
// the sRGB gamut in extended sRGB, where Uniforms holds the nearest
// sRGB ones.
WideUniforms []uint32
// Glyphs, unless empty, are the mask glyphs Scene.Glyphs[Glyphs[0]:
// Glyphs[1]] that a shader's effect paints instead of the rounded
// rectangle: the shapes of text, paths and icons, which it fills, each
// pixel's color times the glyph's coverage, corrected as text's is
// (TextCoverage) for the color the shader returns. Rect then holds
// them, and Origin is the point its shader's positions start from, the
// top left corner of the box it fills.
Glyphs [2]int32
Origin [2]float32
}
EffectOp is the effect of an OpEffect, with its parameters.
type EffectPixels ¶ added in v0.2.10
type EffectPixels interface {
// Begin readies drawing op, the shape rect rounded by radii (fitted),
// before its pixels, which several cores may then ask for at once.
Begin(op *EffectOp, rect Rect, radii [4]float32)
// Color returns the premultiplied color of the effect at the pixel
// center (x, y), as its shaders' effect does, over the backdrop b (nil
// for an effect reading none).
Color(x, y float32, b *BackdropImage) [4]float32
}
EffectPixels draws an effect on the CPU, for one renderer.
type Glyph ¶
type Glyph struct {
// Transform is applied before its Op's transform, for inline text.
Transform Affine
// X, Y, W and H place the glyph's bitmap, in device pixels.
X, Y, W, H float32
// U, V, UW and VH are the bitmap's rectangle in its atlas.
U, V, UW, VH uint16
// Color tints mask glyphs; color glyphs take its alpha only.
Color Color
// Wide, unless 0, is 1 + the index in Scene.Wide of the glyph's
// color outside the sRGB gamut, as Op.Wide.
Wide uint16
// Colored glyphs come from Scene.ColorAtlas, the others from
// Scene.MaskAtlas.
Colored bool
// Subpixel glyphs come from Scene.ColorAtlas too, but hold the
// coverage of the red, green and blue subpixels of each pixel
// (ClearType), each blending its channel of Color.
Subpixel bool
// Thin glyphs, of fonts too thin for antialiasing such as Courier New,
// take half more contrast whatever their color (see TextCoverage), as
// Direct2D gives them.
Thin bool
}
Glyph is a glyph mask or color glyph copied from an atlas into a frame.
type Image ¶
type Image struct {
// W and H are the size in pixels; Pix holds premultiplied RGBA rows of
// 4*W bytes.
W, H int
Pix []byte
// Scene, in a canvas (NewCanvas), is what the image shows: renderers
// draw it into the image's texture whenever the version changes,
// rather than upload Pix, which the CPU renderer draws it into, and
// PixVersion is the version Pix holds.
Scene *Scene
PixVersion uint64
// contains filtered or unexported fields
}
Image is a bitmap a scene draws. Renderers keep a texture per image and upload it again when its version changes.
func NewCanvas ¶ added in v0.4.7
NewCanvas returns a w×h image that renderers draw from a scene of its own, cleared to transparent: render to texture.
func NewImageRGBA ¶
NewImageRGBA wraps premultiplied RGBA pixels of a w×h bitmap.
type Kind ¶
type Kind uint8
Kind is the kind of an Op.
const ( // OpFill paints a rounded rectangle with Color, or the Paint of Color // and Color2, and, where Border is positive, a border of BorderColor // inside its edges, dashed or not. OpFill Kind = iota // OpShadow paints the blurred shadow of a rounded rectangle: Rect and // Radii are the shadow's box, already offset and spread, Blur its blur // radius and Color its color. Unless Cast is empty, the shadow shows // only outside it, the box casting the shadow, as CSS's box-shadow // does. An Inset shadow shows only inside Cast instead, where Rect, // the hole it leaves, blurred, does not cover it, as CSS's box-shadow: // inset does; Rect may then be empty, which leaves no hole. OpShadow // OpGlyphs paints Scene.Glyphs[Start:End]. With a gradient Paint, its // mask glyphs take the gradient from Color to Color2, times Opacity, // instead of their own colors. OpGlyphs // OpImage paints Src of Image into Rect, clipped to Radii, with // Opacity, in shades of gray if Grayscale, tinted by Color unless it // is zero (its pixels times its straight color and alpha). A negative // Src.W or Src.H flips the image along that axis, Src.X or Src.Y then // being its right or bottom edge; nothing outside Src shows. OpImage // OpPushClip clips the following ops to Rect with Radii, intersected // with the clip in effect, until the matching OpPopClip. OpPushClip // OpPopClip restores the clip in effect before the matching OpPushClip. OpPopClip // OpEffect paints the rounded rectangle Rect with Radii with an effect, // Scene.Effects[Start]: shaders of a package outside the renderers (see // Effect), with Opacity; or, for a shader's effect, mask glyphs, which // Rect then holds (EffectOp.Glyphs). OpEffect // OpHole makes the rounded rectangle Rect with Radii transparent, // within the clip: what the ops before it painted there is gone, and // what the window shows under the frame, as a web view, shows through. // The ops after it paint over it as over any transparent pixels. Below // full Opacity, what the ops before it painted fades by Opacity // instead, so what shows through blends over it. OpHole )
type Op ¶
type Op struct {
Kind Kind
Rect Rect
// Transform maps this operation's geometry to frame pixels. Clips
// retain the transform with which they were pushed.
Transform Affine
// Radii are the corner radii: top-left, top-right, bottom-right and
// bottom-left.
Radii [4]float32
// Continuous curves the rounded corners of Rect, and of Cast, the way
// Apple draws them (Core Animation's continuous corner curve, SwiftUI's
// rounded rectangles): the curve starts further from the corner and
// bends gradually, instead of as a quarter circle. Corners that are
// round in both directions, as a circle's, stay circular. Only the
// renderers of macOS draw them, the CPU's and Metal's.
Continuous bool
Color Color
// Paint, unless PaintSolid, fills with Color and Color2 as Gradient
// says.
Paint Paint
Color2 Color
// Wide, unless 0, is 1 + the index in Scene.Wide of the op's colors
// outside the sRGB gamut, which the renderers drawing a wide gamut
// draw in place of Color, Color2 and BorderColor; those hold the
// nearest sRGB colors, which every other renderer draws. It fits in
// the room the fields around it leave.
Wide uint16
Gradient [4]float32
// Border holds the widths of the border on the top, right, bottom and
// left; Dashed dashes it.
Border [4]float32
BorderColor Color
Dashed bool
// BorderPaint paints an OpFill's border with Paint, its gradient of
// stops (Paint.HasStops), times BorderColor (opaque white for the
// gradient as it is), and its inside with plain Color.
BorderPaint bool
// Inset makes an OpShadow an inner shadow.
Inset bool
// Blur is an OpShadow's blur, and an OpImage's: the standard deviation
// of a Gaussian blur of the image's Src, in its pixels, before it is
// drawn, transparent beyond Src, as CSS's filter: blur() is. Large
// blurs are computed at a fraction of the size, as backdrops' are
// (BackdropOf).
Blur float32
// Cast is the box casting an OpShadow, with CastRadii.
Cast Rect
CastRadii [4]float32
Start, End int32
// Stops are a gradient's colors with stops (PaintLinearStops and the
// others), Scene.Stops[Stops[0]:Stops[1]].
Stops [2]int32
Image *Image
Src Rect
Grayscale bool
// Pixelated samples an OpImage's nearest pixel, as pixel art draws,
// where it would interpolate between pixels.
Pixelated bool
// Opacity multiplies the op's colors; 0 means 1.
Opacity float32
}
Op is one drawing operation. Which fields matter depends on Kind.
type Paint ¶ added in v0.2.1
type Paint uint8
Paint is what fills an OpFill besides plain Color, or the masks of an OpGlyphs (gradients only).
const ( PaintSolid Paint = iota // PaintLinear is a linear gradient from Color at (Gradient[0], // Gradient[1]) to Color2 at (Gradient[2], Gradient[3]), mixed in sRGB; // PaintOklab mixes them in Oklab. Both mix premultiplied colors, as // CSS does. PaintLinear PaintOklab // PaintStripes draws stripes of Color over Color2: Gradient holds the // unit vector across the stripes, their width and their period, from // the top-left corner of Rect. PaintStripes // PaintLinearStops is a linear gradient of the op's Stops, from // (Gradient[0], Gradient[1]) at 0 to (Gradient[2], Gradient[3]) at 1, // mixed in sRGB; PaintLinearStopsOklab mixes them in Oklab. PaintLinearStops PaintLinearStopsOklab // PaintConic is a conic gradient of the op's Stops around // (Gradient[0], Gradient[1]), from 0 at the angle Gradient[2], in // radians clockwise from upwards, to 1 a turn later, mixed in sRGB, as // CSS's conic-gradient() is; PaintConicOklab mixes them in Oklab. PaintConic PaintConicOklab )
type Rect ¶
type Rect struct{ X, Y, W, H float32 }
Rect is a rectangle in device pixels.
func InnerRadii ¶ added in v0.2.1
InnerRadii returns the radii of the inner edge of a border of widths w (top, right, bottom, left) inside a rounded rectangle r with radii, which FitRadii or Corners already fitted: each corner's less the wider of its two sides, fitted to the inner rectangle, negative as radii are for continuous corners.
type Scene ¶
type Scene struct {
// Width and Height of the frame in device pixels; Scale is how many
// device pixels a DIP is (0 for 1).
Width, Height int
Scale float32
// Clear is the color the frame starts with.
Clear Color
Ops []Op
Glyphs []Glyph
// Stops holds the stops of gradients (Op.Stops).
Stops []Stop
// Effects holds the effects of OpEffect operations.
Effects []EffectOp
// Words holds the words of the effects' uniforms (EffectOp.Uniforms
// and WideUniforms), which the frame's painter allocates from
// (Painter.EffectWords), kept from frame to frame.
Words []uint32
// Wide holds the colors outside the sRGB gamut of ops and glyphs (see
// Op.Wide), and those of the parameters of effects, which no op points
// at. Without any, the scene draws the same on every renderer.
Wide []WideColors
// Text corrects the coverage of mask and subpixel glyphs.
Text TextParams
// MaskAtlas holds coverage masks (one byte per pixel), ColorAtlas
// premultiplied RGBA bitmaps such as emoji, and the coverage of
// subpixel glyphs.
MaskAtlas, ColorAtlas *Atlas
// Canvases are the canvases (NewCanvas) drawn anew for this frame,
// which renderers draw before it, whether it shows them or not, while
// the atlases their glyphs point at hold them.
Canvases []*Image
}
Scene is a frame's display list.
func (*Scene) EachCanvas ¶ added in v0.4.7
EachCanvas calls fn with the canvases the scene draws anew or shows, each once, those a canvas shows before it.
type ShaderLayout ¶ added in v0.5.2
ShaderLayout is where a shader's uniforms lie in the buffer its code reads: the offset in bytes of each word of EffectOp.Uniforms, and the buffer's size in bytes, a multiple of 16.
func (*ShaderLayout) Pack ¶ added in v0.5.2
func (l *ShaderLayout) Pack(buf []byte, words []uint32) []byte
Pack writes words into buf, grown to the layout's size, as the layout lays them out, and returns it. A lane takes 4 bytes, but for a bool of Metal, which takes 1 and may lie in the last bytes: the bytes that fit are written, little end first, and lanes in ascending order write over what the one before spilled.
type Stop ¶ added in v0.5.5
Stop is a color of a gradient with stops (Op.Stops), at a place along it from 0 to 1. A gradient shows its first color before its first stop and its last after its last, and mixes premultiplied colors between, as CSS does; stops in order, at most MaxStops of them.
type TextParams ¶ added in v0.2.4
type TextParams struct {
// GammaRatios are Direct2D's alpha correction of a gamma (see
// GammaRatios).
GammaRatios [4]float32
// Contrast enhances the contrast of mask glyphs, and SubpixelContrast
// that of subpixel glyphs, the more the darker their color: DirectWrite's
// grayscale enhanced contrast and enhanced contrast.
Contrast, SubpixelContrast float32
}
TextParams corrects the coverage of mask and subpixel glyphs for the gamma and contrast text is blended with, as Direct2D does; the zero value leaves it as it is.
type WideColors ¶ added in v0.2.15
WideColors are the colors outside the sRGB gamut of an op or a glyph (see Op.Wide): straight RGBA with sRGB-encoded components beyond 0 to 1 (extended sRGB), for those of Color, Color2 and BorderColor a Set bit names, of which a glyph has only Color, times its opacity.
Source Files