Documentation
¶
Overview ¶
Package imagebdf draws BDF documents into images without a browser: the pages of fixed and flow views, stretches of scroll views and regions of sheets, for thumbnails and other server-side previews, and objects that are in no document (Object).
It runs the same instructions as the viewer's Canvas 2D renderer (docs/spec.md §7) with a software rasterizer: anti-aliased paths with nonzero and even-odd fills, strokes with joins, caps and dashes, clips, gradients and patterns, images (PNG, JPEG, GIF, BMP, WebP), text in the embedded fonts (WOFF2, TrueType, OpenType) and in the fonts of the system for fonts referred to by name, groups with their alpha and blend mode, soft masks and shadows. The result is close to what a browser draws but not identical: text is not hinted, shaped (no kerning, ligatures or Arabic joining) or laid out by a full bidirectional algorithm; SVG and AVIF images and FILTER are not drawn. Warnings list what was left out.
A document decides what it asks of a renderer, so the drawing has limits: of the objects drawn again (maxReusedInstructions), of the groups, soft masks, states and clips that are open at a time (maxLayers, maxStates, maxLive), of the outline of a stroke (strokePoints, strokeDashes), of the blur of a shadow (maxShadowBlur), of the pictures kept decoded (maxPicturePixels), of SVG images (svgDepth, svgNodes, svgBudget, svgLayers and the constants beside them) and of the gridlines of a sheet (maxGridLines). What passes a limit is left out with a warning, and the rest is drawn. A panic of a drawing is the error of Page, Region and Object.
Index ¶
- Constants
- Variables
- func Object(o *bdf.Object, scale float64, opts *Options) (img *image.RGBA, err error)
- func SheetSize(v *bdf.View) (w, h float64)
- type Options
- type Renderer
- func (r *Renderer) Page(v *bdf.View, page int, scale float64) (img *image.RGBA, err error)
- func (r *Renderer) PageDPI(v *bdf.View, page int, dpi float64) (*image.RGBA, error)
- func (r *Renderer) PageSize(v *bdf.View, page, w, h int) (img *image.RGBA, err error)
- func (r *Renderer) Region(v *bdf.View, page int, region bdf.Rect, w, h int) (img *image.RGBA, err error)
- func (r *Renderer) Warnings() []string
Constants ¶
const MaxPixels = 64 << 20
MaxPixels is the largest image Page and Region draw (a canvas takes 16 bytes a pixel while it is drawn).
Variables ¶
var ErrNeedsDocument = errors.New("imagebdf: the object refers to other parts of a document")
ErrNeedsDocument is returned by Object for an object that refers to other parts (an embedded font, an image, a path collection or another object): add it to a document with them and draw a page.
var ErrNoPage = errors.New("imagebdf: no such page")
ErrNoPage is returned for a page a view does not have.
var ErrTooLarge = errors.New("imagebdf: the image would be too large")
ErrTooLarge is returned for an image of more than MaxPixels pixels.
Functions ¶
func Object ¶
Object draws an object that needs no other part, such as a formula laid out as paths, at scale device pixels per unit. The image holds the bounding box of the object grown to whole pixels, and its bounds are in device pixels from the origin of the object: the pixel at (0, 0) is where the origin is drawn, wherever the bounding box lies around it. The background is opts.Background, and transparent without one.
Types ¶
type Options ¶
type Options struct {
// FontFS holds fonts searched before FontDirs, for the text of fonts
// referred to by name (HTML, Markdown and EPUB documents, and others
// converted with system fonts) and for characters an embedded font
// lacks.
FontFS fs.FS
// FontDirs are searched for fonts before the system font directories.
FontDirs []string
// NoSystemFonts restricts font lookup to FontFS and FontDirs.
NoSystemFonts bool
// Background fills the page behind its content (default white). Use
// color.Transparent for a transparent page.
Background color.Color
}
Options configures a Renderer.
type Renderer ¶
type Renderer struct {
// contains filtered or unexported fields
}
Renderer draws the views of a document. It keeps what it decodes (objects, paths, images, fonts) for the next drawing, the images up to maxPicturePixels, past which those of the drawings before make room; it is not safe for concurrent use.
func (*Renderer) Page ¶
Page draws a whole page of a fixed or flow view (or a strip of a scroll view) at scale device pixels per unit.
func (*Renderer) PageDPI ¶
PageDPI draws a whole page at dpi pixels per inch. BDF page units are points (1/72 inch), so 72 dpi draws one pixel per page unit.
func (*Renderer) PageSize ¶
PageSize draws a whole page into exactly w × h pixels. The page is stretched if the requested size has a different aspect ratio.
func (*Renderer) Region ¶
func (r *Renderer) Region(v *bdf.View, page int, region bdf.Rect, w, h int) (img *image.RGBA, err error)
Region draws a rectangle of a view into a w × h image: of the page with index page in a fixed or flow view (in page units), of the continuous layout of a scroll view (its strips stacked, in units from the top), or of a sheet (page is ignored in the last two).