backend

package
v0.0.10 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 19, 2024 License: BSD-3-Clause Imports: 9 Imported by: 3

Documentation

Overview

Package backend defines a common interface, providing graphics primitives.

It aims at supporting the operations defined in HTML and SVG files in an output-agnostic manner, so that various output formats may be generated (GUI canvas, raster image or PDF files for instance).

The types implementing this interface will be used to convert a document.Document to the final output, or to draw an svg.SVGImage

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Anchor 

type Anchor struct {
	Name string
	// Origin at the top-left of the page
	X, Y Fl
}

type Attachment 

type Attachment struct {
	Title, Description string
	Content            []byte
}

type BookmarkNode 

type BookmarkNode struct {
	Label     string
	Children  []BookmarkNode
	Open      bool // state of the outline item
	PageIndex int  // page index (0-based) to link to
	X, Y      Fl   // position in the page
}

BookmarkNode exposes the outline hierarchy of the document

type Canvas 

type Canvas interface {
	// Returns the current canvas rectangle
	GetBoundingBox() (left, top, right, bottom Fl)

	// Updates the current canvas rectangle
	SetBoundingBox(left, top, right, bottom Fl)

	// OnNewStack save the current graphic state,
	// execute the given closure, and restore the state.
	OnNewStack(func())

	// State returns the current graphic state.
	State() GraphicState

	// NewGroup creates a new drawing target with the given
	// bounding box. It may be filled by graphic operations
	// before being passed to the `DrawWithOpacity`, `SetColorPattern`
	// and `SetAlphaMask` methods.
	NewGroup(x, y, width, height Fl) Canvas

	// DrawWithOpacity draw the given target to the main target, applying the given opacity (in [0,1]).
	DrawWithOpacity(opacity Fl, group Canvas)

	// Paint actually shows the current path on the target,
	// either stroking, filling or doing both, according to `op`.
	// The result of the operation depends on the current fill and
	// stroke settings.
	// After this call, the current path will be cleared.
	Paint(op PaintOp)

	// Adds a rectangle of the given size to the current path,
	// at position “(x, y)“ in user-space coordinates.
	// (X,Y) coordinates are the top left corner of the rectangle.
	// Note that this method may be expressed using MoveTo and LineTo,
	// but may be implemented more efficiently.
	Rectangle(x Fl, y Fl, width Fl, height Fl)

	// Begin a new sub-path.
	// After this call the current point will be (x, y).
	MoveTo(x Fl, y Fl)

	// Adds a line to the path from the current point
	// to position (x, y) in user-space coordinates.
	// After this call the current point will be (x, y).
	// A current point must be defined before using this method.
	LineTo(x Fl, y Fl)

	// Add cubic Bézier curve to current path.
	// The curve shall extend to (x3, y3) using (x1, y1) and (x2,
	// y2) as the Bézier control points.
	CubicTo(x1, y1, x2, y2, x3, y3 Fl)

	// ClosePath add a straight line to the beginning of
	// the current sub-path (specified by MoveTo)
	// It is somewhat equivalent to adding a LineTo instruction,
	// but some backends may optimize the corner rendering, applying line join style.
	ClosePath()

	// AddFont register a new font to be used in the output and return
	// an object used to store associated metadata.
	// This method will be called several times with the same `font` argument,
	// so caching is advised.
	AddFont(font Font, content []byte) *FontChars

	// DrawText draws the given text using the current fill color.
	// The rendering may be altered by a previous `SetTextPaint` call.
	// The fonts of the runs have been registred with `AddFont`.
	DrawText(texts []TextDrawing)

	// DrawRasterImage draws the given image at the current point, with the given dimensions.
	// Typical format for image.Content are PNG, JPEG, GIF.
	DrawRasterImage(image RasterImage, width, height Fl)

	// DrawGradient draws the given gradient at the current point.
	// Solid gradient are already handled, meaning that only linear and radial
	// must be taken care of.
	DrawGradient(gradient GradientLayout, width, height Fl)
}

Canvas represents a 2D surface which is the target of graphic operations. It may be used as the final output (like a PDF page or the screen), or as intermediate container (see for instance DrawWithOpacity or SetAlphaMask)

type Document 

type Document interface {
	// AddPage creates a new page with the given dimensions and returns
	// it to be paint on.
	// The y axis grows downward, meaning bottom > top
	AddPage(left, top, right, bottom Fl) Page

	// CreateAnchors register a list of anchors per page, which are named targets of internal links.
	// `anchors` is a 0-based list, meaning anchors in page 1 are at index 0.
	// The origin of internal link has been be added by `OutputPage.AddInternalLink`.
	// `CreateAnchors` is called after all the pages have been created and processed
	CreateAnchors(anchors [][]Anchor)

	// Add global attachments to the file
	SetAttachments(as []Attachment)

	// Embed a file. Calling this method twice with the same id
	// won't embed the content twice.
	// `fileID` will be passed to `OutputPage.AddFileAnnotation`
	EmbedFile(fileID string, a Attachment)

	SetTitle(title string)
	SetDescription(description string)
	SetCreator(creator string)
	SetAuthors(authors []string)
	SetKeywords(keywords []string)
	SetProducer(producer string)
	SetDateCreation(d time.Time)
	SetDateModification(d time.Time)

	// SetBookmarks setup the document outline
	SetBookmarks(root []BookmarkNode)
}

Document is the main target to whole the laid out document, consisting in pages, metadata and embedded files.

type Fl 

type Fl = utils.Fl

type Font 

type Font interface {
	Origin() text.FontOrigin
	Description() FontDescription
}

Font are implemented by valid map keys

type FontChars added in v0.0.7 

type FontChars struct {
	Cmap    map[GID][]rune
	Extents map[GID]GlyphExtents
	Bbox    [4]int
}

FontChars stores some metadata that may be required in the output document.

func (*FontChars) IsFixedPitch added in v0.0.7 

func (f *FontChars) IsFixedPitch() bool

IsFixedPitch returns true if only one width is used, that is if the font is monospaced.

type FontDescription added in v0.0.7 

type FontDescription struct {
	Family string
	Style  text.FontStyle
	Weight int

	Ascent  Fl
	Descent Fl

	Size int // the font size used with this font

	IsOpentype bool
	// IsOpentype is true for an OpenType file containing a PostScript Type 2 font
	IsOpentypeOpentype bool
}

type GID added in v0.0.6 

type GID = uint32

type GlyphExtents 

type GlyphExtents struct {
	Width  int
	Y      int
	Height int
}

GlyphExtents exposes glyph metrics, normalized by the font size.

type GradientKind 

type GradientKind struct {
	// Kind is either:
	// 	"solid": Colors is then a one element array and Positions and Coords are empty.
	// 	"linear": Coords is (x0, y0, x1, y1)
	// 			  coordinates of the starting and ending points.
	// 	"radial": Coords is (cx0, cy0, radius0, cx1, cy1, radius1)
	// 			  coordinates of the starting end ending circles
	Kind   string
	Coords [6]Fl
}

type GradientLayout 

type GradientLayout struct {
	// Positions is a list of floats in [0..1].
	// 0 at the starting point, 1 at the ending point.
	Positions []Fl
	Colors    []parser.RGBA

	GradientKind

	// used for ellipses radial gradients. 1 otherwise.
	ScaleY     utils.Fl
	Reapeating bool
}

type GraphicState added in v0.0.3 

type GraphicState interface {
	// SetAlphaMask inteprets `mask` as an alpha mask which should be applied
	// to the painting done in the current graphic stack.
	SetAlphaMask(mask Canvas)

	// Establishes a new clip region
	// by intersecting the current clip region
	// with the current path as it would be filled by `Fill`
	// and according to the fill rule given in `evenOdd`.
	//
	// After `Clip`, the current path will be cleared (or closed).
	//
	// The current clip region affects all drawing operations
	// by effectively masking out any changes to the surface
	// that are outside the current clip region.
	//
	// Calling `Clip` can only make the clip region smaller,
	// never larger, but you can call it in the `OnNewStack` closure argument,
	// so that the original clip region is restored afterwards.
	Clip(evenOdd bool)

	// SetAlpha is the same as SetColorRgba, but only updates the alpha value.
	SetAlpha(alpha Fl, stroke bool)

	// Sets the color which will be used for any subsequent drawing operation.
	//
	// The color and alpha components are
	// floating point numbers in the range 0 to 1.
	// If the values passed in are outside that range, they will be clamped.
	// `stroke` controls whether stroking or filling operations are concerned.
	SetColorRgba(color parser.RGBA, stroke bool)

	// SetColorPattern set the current paint color to the given pattern.
	// A pattern acts as a fill or stroke color, but permits complex textures.
	// It consists of a rectangle, fill with arbitrary content, which will be replicated
	// at fixed horizontal and vertical intervals to fill an area.
	// (contentWidth, contentHeight) define the size of the pattern content.
	// `mat` maps the pattern’s internal coordinate system to the one
	// in which it will painted.
	// `stroke` controls whether stroking or filling operations are concerned.
	SetColorPattern(pattern Canvas, contentWidth, contentHeight Fl, mat matrix.Transform, stroke bool)

	// SetBlendingMode sets the blending mode, which is a CSS blend mode keyword.
	SetBlendingMode(mode string)

	// Sets the current line width to be used by `Stroke`.
	// The line width value specifies the diameter of a pen
	// that is circular in user space,
	// (though device-space pen may be an ellipse in general
	// due to scaling / shear / rotation of the CTM).
	SetLineWidth(width Fl)

	// Sets the dash pattern to be used by `Stroke`.
	// A dash pattern is specified by dashes, a list of positive values.
	// Each value provides the length of alternate "on" and "off"
	// portions of the stroke.
	// `offset` specifies a non negative offset into the pattern
	// at which the stroke begins.
	//
	// Each "on" segment will have caps applied
	// as if the segment were a separate sub-path.
	// In particular, it is valid to use an "on" length of 0
	// with `RoundCap` or `SquareCap`
	// in order to distribute dots or squares along a path.
	//
	// If `dashes` is empty dashing is disabled.
	// If it is of length 1 a symmetric pattern is assumed
	// with alternating on and off portions of the size specified
	// by the single value.
	SetDash(dashes []Fl, offset Fl)

	// SetStrokeOptions sets additionnal options to be used when stroking
	// (in addition to SetLineWidth and SetDash)
	SetStrokeOptions(StrokeOptions)

	// GetTransform returns the current transformation matrix (CTM).
	GetTransform() matrix.Transform

	// Modifies the current transformation matrix (CTM)
	// by applying `mt` as an additional transformation.
	// The new transformation of user space takes place
	// after any existing transformation.
	Transform(mt matrix.Transform)

	// SetTextPaint adjusts how text shapes are rendered.
	SetTextPaint(op PaintOp)
}

GraphicState exposes the settings for a group of graphic operations.

type Image 

type Image interface {
	GetIntrinsicSize(imageResolution, fontSize properties.Float) (width, height, ratio properties.MaybeFloat)

	// Draw shall write the image on the given `canvas`
	Draw(canvas Canvas, textContext text.TextLayoutContext, concreteWidth, concreteHeight Fl, imageRendering string)
}

Image groups all possible image format, like raster image, svg, or gradients.

type Page 

type Page interface {
	// AddInternalLink shows a link on the page, pointing to the
	// named anchor, which will be registered with `Output.CreateAnchors`
	AddInternalLink(xMin, yMin, xMax, yMax Fl, anchorName string)

	// AddExternalLink shows a link on the page, pointing to
	// the given url
	AddExternalLink(xMin, yMin, xMax, yMax Fl, url string)

	// AddFileAnnotation adds a file annotation on the current page.
	// The file content has been added with `Output.EmbedFile`.
	AddFileAnnotation(xMin, yMin, xMax, yMax Fl, fileID string)

	SetMediaBox(left, top, right, bottom Fl)
	SetTrimBox(left, top, right, bottom Fl)
	SetBleedBox(left, top, right, bottom Fl)

	Canvas
}

Page is the target of one laid out page, composed of a Canvas and link supports.

type PaintOp added in v0.0.2 

type PaintOp uint8

PaintOp specifies the graphic operation applied to the current path 

const (
	// Clear does not show anything on the output, but reset the current path
	Stroke PaintOp = 1 << iota
	FillEvenOdd
	FillNonZero // mutually exclusive with FillEvenOdd
)

func (PaintOp) String added in v0.0.3 

func (op PaintOp) String() string

type RasterImage 

type RasterImage struct {
	Content  io.Reader
	MimeType string

	// Rendering is the CSS property for this image.
	Rendering string

	// ID is a unique identifier which permits caching
	// image content when possible.
	ID int
}

RasterImage is an image to be included in the ouput.

type StrokeCapMode 

type StrokeCapMode uint8

StrokeCapMode defines how to draw caps on the ends of lines when stroking. 

const (
	ButtCap StrokeCapMode = iota // default value
	RoundCap
	SquareCap
)

func (StrokeCapMode) String 

func (c StrokeCapMode) String() string

type StrokeJoinMode 

type StrokeJoinMode uint8

StrokeJoinMode type to specify how segments join when stroking. 

const (
	Miter StrokeJoinMode = iota
	Round
	Bevel
)

StrokeJoinMode constants determine how stroke segments bridge the gap at a join

func (StrokeJoinMode) String 

func (s StrokeJoinMode) String() string

type StrokeOptions 

type StrokeOptions struct {
	LineCap  StrokeCapMode
	LineJoin StrokeJoinMode

	// MiterLimit is the miter cutoff value for `Miter`, `Arc`, `Miterclip` and `ArcClip` join modes
	MiterLimit Fl
}

StrokeOptions specifies advanced stroking options.

type TextDrawing 

type TextDrawing struct {
	Runs []TextRun

	FontSize, ScaleX Fl
	X, Y             Fl // origin
	Angle            Fl // (optional) rotation
}

TextDrawing exposes the positionned text glyphs to draw and the associated font, in a backend independent manner

func (TextDrawing) Matrix added in v0.0.10 

func (td TextDrawing) Matrix() matrix.Transform

Matrix return the transformation scaling the text by [FontSize], translating if to (X, Y) and applying the [Angle] rotation

type TextGlyph 

type TextGlyph struct {
	Kerning  int // normalized by FontSize
	Glyph    GID
	Offset   Fl // normalized by FontSize
	Rise     Fl
	XAdvance Fl // how much to move before drawing, used for emojis
}

TextGlyph stores a glyph and it's position

type TextRun 

type TextRun struct {
	Font   Font
	Glyphs []TextGlyph
}

TextRun is a serie of glyphs with constant font.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.