render

Documentation

Overview

Package render defines the device-independent graphics layer: the Device interface that the content interpreter drives, along with the geometry types (paths, matrices, paint) shared between the interpreter and concrete backends.

Keeping paint operations abstract here is the seam that lets doctaculous target multiple backends (a raster bitmap today; SVG or others later) from a single content interpreter.

Index

• Variables
• func CMYKToRGBA(c, m, y, k float64) color.RGBA
• func Clamp8(v float64) uint8
• func GrayToRGBA(g float64) color.RGBA
• func RGBToRGBA(r, g, b float64) color.RGBA
• type Device
• type FillColor
• type FillPaint
• type FillRule
• type GlyphFace
• type GlyphRef
• type LineCap
• type LineJoin
• type Matrix
  • func Scale(sx, sy float64) Matrix
  • func Translate(tx, ty float64) Matrix
  • func (m Matrix) Apply(x, y float64) (float64, float64)
  • func (m Matrix) ApplyVector(x, y float64) (float64, float64)
  • func (m Matrix) Mul(n Matrix) Matrix
  • func (m Matrix) ScaleFactor() float64
• type Path
  • func TransformPath(p *Path, m Matrix) *Path
  • func (p *Path) Clone() *Path
  • func (p *Path) Close()
  • func (p *Path) CubeTo(x0, y0, x1, y1, x2, y2 float64)
  • func (p *Path) Empty() bool
  • func (p *Path) LineTo(x, y float64)
  • func (p *Path) MoveTo(x, y float64)
  • func (p *Path) Reset()
• type Point
• type Segment
• type SegmentKind
• type Shader
• type StrokePaint

Variables

var Identity = Matrix{A: 1, B: 0, C: 0, D: 1, E: 0, F: 0}

Identity is the identity transform.

Functions

func CMYKToRGBA

func CMYKToRGBA(c, m, y, k float64) color.RGBA

CMYKToRGBA converts DeviceCMYK components to RGBA with the naive (1-c)(1-k) device conversion (no ICC).

func Clamp8

func Clamp8(v float64) uint8

Clamp8 maps a component in [0,1] to an 8-bit value, clamping out-of-range.

func GrayToRGBA

func GrayToRGBA(g float64) color.RGBA

GrayToRGBA converts a DeviceGray component to RGBA.

func RGBToRGBA

func RGBToRGBA(r, g, b float64) color.RGBA

RGBToRGBA converts DeviceRGB components to RGBA.

Types

type Device

type Device interface {
	// Size reports the device's pixel dimensions.
	Size() (w, h int)

	// Fill paints the interior of path using paint's color and fill rule,
	// intersected with the current clip.
	Fill(path *Path, paint FillPaint)

	// Stroke paints path's outline using paint, intersected with the current clip.
	Stroke(path *Path, paint StrokePaint)

	// DrawImage draws img mapped by ctm. The image's unit square [0,1]×[0,1] is
	// mapped through ctm into device space (PDF image space convention). alpha in
	// [0,1] is the constant fill opacity (ExtGState /ca); 1 is fully opaque.
	// blendMode is the /BM blend mode name ("" or "Normal" = source-over).
	DrawImage(img image.Image, ctm Matrix, alpha float64, blendMode string)

	// FillGlyph fills a single glyph outline (already in device space) with color.
	// The outline uses the nonzero winding rule. blendMode is the /BM blend mode.
	FillGlyph(outline *Path, color FillColor, blendMode string)

	// DrawGlyph paints one shaped glyph placed in device space via g.Transform (em
	// space, Y up, 1 em = 1 unit -> device space). Backends that only rasterize
	// render g.Face's outline for g.GID and may ignore g.Runes and g.Advance;
	// backends that emit text (PDF, text extraction) use g.Runes for a ToUnicode
	// mapping and g.Advance for spacing. g.Blend is the /BM blend mode ("" =
	// Normal), matching FillGlyph.
	DrawGlyph(g GlyphRef)

	// FillShading fills the active clip region by evaluating shader at each device
	// pixel, honoring the active clip and the named blend mode. The device maps each
	// pixel center from device space into shading (user) space via the inverse of
	// ctm, then calls shader.ColorAt; a pixel where ColorAt reports paint=false is
	// left untouched. With no active clip it fills the whole device (the `sh`
	// operator is normally clipped first). blendMode is the /BM blend mode name
	// ("" or "Normal" = source-over).
	FillShading(shader Shader, ctm Matrix, blendMode string)

	// PushClip intersects the current clip with path using rule.
	PushClip(path *Path, rule FillRule)

	// Save and Restore manage the clip/state stack so the interpreter's q/Q
	// operators can be mirrored by the backend where clip state lives.
	Save()
	Restore()
}

Device is the backend-agnostic drawing target the content interpreter drives. All geometry passed to a Device is already in device space (the interpreter applies the CTM before calling). Implementations include the raster bitmap backend; future backends (e.g. SVG) implement the same interface.

Methods must tolerate degenerate input (empty paths, zero-area images) without panicking.

type FillColor

type FillColor struct {
	R, G, B, A uint8
}

FillColor is the solid color used for glyph fills (kept separate from FillPaint so glyph rendering need not carry a fill rule).

type FillPaint

type FillPaint struct {
	Color     color.RGBA
	Rule      FillRule
	BlendMode string
}

FillPaint describes how to fill a region. BlendMode is the ExtGState /BM blend mode name ("" or "Normal" = source-over).

type FillRule

type FillRule int

FillRule selects how a path's interior is determined.

const (
	// NonZero is the nonzero winding rule (PDF "f"/"F").
	NonZero FillRule = iota
	// EvenOdd is the even-odd rule (PDF "f*").
	EvenOdd
)

type GlyphFace

type GlyphFace interface {
	// Outline returns gid's outline in em units (Y up), or nil if empty/missing.
	Outline(gid uint16) *Path
}

GlyphFace is the minimal view of a font face a Device needs: outline geometry for a GID (rasterizer). The concrete type is *font.Face; this interface keeps pkg/render from importing pkg/font (which would invert the layer dependency). A PDF writer needs more than the outline (program bytes) and type-asserts the concrete *font.Face at its own boundary.

type GlyphRef

type GlyphRef struct {
	Face      GlyphFace // font identity; see GlyphFace
	GID       uint16    // glyph id within Face
	Runes     []rune    // source characters this glyph represents (the cluster)
	Transform Matrix    // em space (Y up) -> device space; position, size, skew
	Advance   float64   // horizontal advance in device units
	Color     FillColor
	Blend     string // /BM blend mode ("" = Normal)
}

GlyphRef is one shaped glyph handed to a Device, carrying enough identity for a rasterizing backend (Face+GID outline), a PDF writer (Face+GID embed/subset, Runes for ToUnicode), and a future text-extraction backend (Runes+Transform+ Advance for positioned text). It is format-neutral: both the reflow paint layer and the PDF content interpreter can populate it.

type LineCap

type LineCap int

LineCap is the shape drawn at the ends of open subpaths.

const (
	// ButtCap ends the stroke squarely at the endpoint.
	ButtCap LineCap = iota
	// RoundCap ends the stroke with a semicircle.
	RoundCap
	// SquareCap ends the stroke with a half-square extending past the endpoint.
	SquareCap
)

type LineJoin

type LineJoin int

LineJoin is the shape drawn where two stroke segments meet.

const (
	// MiterJoin extends the outer edges to a point.
	MiterJoin LineJoin = iota
	// RoundJoin rounds the corner.
	RoundJoin
	// BevelJoin cuts the corner off.
	BevelJoin
)

type Matrix

type Matrix struct {
	A, B, C, D, E, F float64
}

Matrix is a 2-D affine transform in PDF's six-element form [a b c d e f], representing:

| a b 0 |
| c d 0 |
| e f 1 |

A point (x,y) maps to (a*x + c*y + e, b*x + d*y + f).

func Scale

func Scale(sx, sy float64) Matrix

Scale returns a scaling matrix.

func Translate

func Translate(tx, ty float64) Matrix

Translate returns a translation matrix.

func (Matrix) Apply

func (m Matrix) Apply(x, y float64) (float64, float64)

Apply transforms a point by the matrix.

func (Matrix) ApplyVector

func (m Matrix) ApplyVector(x, y float64) (float64, float64)

ApplyVector transforms a vector (ignoring translation), used for distances and directions such as line widths.

func (Matrix) Mul

func (m Matrix) Mul(n Matrix) Matrix

Mul returns m * n, i.e. the transform that applies m first, then n. In PDF the concatenation order for "cm" is newCTM = cm × CTM, which is Mul(cm, ctm).

func (Matrix) ScaleFactor

func (m Matrix) ScaleFactor() float64

ScaleFactor returns an approximate uniform scale factor of the transform, useful for converting a 1-D measure (e.g. line width) into device space. It uses the square root of the absolute determinant.

type Path

type Path struct {
	Segments []Segment
}

Path is a sequence of segments already transformed into device space.

func TransformPath

func TransformPath(p *Path, m Matrix) *Path

TransformPath returns a copy of p with every point mapped through m. It is used by backends that need a path in a different coordinate space (e.g. a glyph outline moved into device space). It returns nil for a nil p.

func (*Path) Clone

func (p *Path) Clone() *Path

Clone returns a deep copy of the path.

func (*Path) Close

func (p *Path) Close()

Close appends a close-subpath segment.

func (*Path) CubeTo

func (p *Path) CubeTo(x0, y0, x1, y1, x2, y2 float64)

CubeTo appends a cubic Bézier segment.

func (*Path) Empty

func (p *Path) Empty() bool

Empty reports whether the path has no segments.

func (*Path) LineTo

func (p *Path) LineTo(x, y float64)

LineTo appends a line-to segment.

func (*Path) MoveTo

func (p *Path) MoveTo(x, y float64)

MoveTo appends a move-to segment.

func (*Path) Reset

func (p *Path) Reset()

Reset clears the path for reuse, retaining capacity.

type Point

type Point struct {
	X, Y float64
}

Point is a 2-D point in device space (pixels), origin at top-left, y down.

type Segment

type Segment struct {
	Kind       SegmentKind
	P0, P1, P2 Point
}

Segment is one element of a path. Which Point fields are meaningful depends on Kind: MoveTo/LineTo use P0; CubeTo uses P0,P1,P2; Close uses none.

type SegmentKind

type SegmentKind int

SegmentKind identifies a path segment type.

const (
	// MoveTo starts a new subpath at P0.
	MoveTo SegmentKind = iota
	// LineTo draws a straight line to P0.
	LineTo
	// CubeTo draws a cubic Bézier with control points P0, P1 and endpoint P2.
	CubeTo
	// Close closes the current subpath.
	Close
)

type Shader

type Shader interface {
	ColorAt(userX, userY float64) (c color.RGBA, ok bool)
}

Shader evaluates a PDF shading: it maps a point in shading (user) space to the color painted there. ok=false means the point lies outside the shading and is not extended, so the backdrop is left untouched. The backend builds a Shader from a shading dictionary (keeping shading geometry and color math out of the content interpreter); FillShading drives it per device pixel.

type StrokePaint

type StrokePaint struct {
	Color      color.RGBA
	Width      float64
	Cap        LineCap
	Join       LineJoin
	MiterLimit float64
	DashArray  []float64
	DashPhase  float64
	BlendMode  string
}

StrokePaint describes how to stroke a path. Width and DashArray/DashPhase are already expressed in device space. BlendMode is the /BM blend mode name.