Documentation
¶
Overview ¶
Package pdfw writes PDF files: indirect objects, streams, the cross reference table, and the content stream operators a printout's marks need.
It is a writer and nothing else. It knows no marks, no layout and no fonts beyond embedding the bytes it is handed, so the mapping from a printout to a page is one level up, in package pdf.
Index ¶
- Constants
- func ASCIIString(text string) string
- func Date(when time.Time) string
- func Num(value float64) string
- func Ref(num int) string
- func TextString(text string) string
- type Content
- func (con *Content) BeginText()
- func (con *Content) Bytes() []byte
- func (con *Content) Clip()
- func (con *Content) CurveTo(left1, top1, left2, top2, left3, top3 float64)
- func (con *Content) Dash(pattern []float64)
- func (con *Content) EndText()
- func (con *Content) Fill()
- func (con *Content) FillColor(red, green, blue float64)
- func (con *Content) FillStroke()
- func (con *Content) Font(name string, size float64)
- func (con *Content) Len() int
- func (con *Content) LineTo(left, top float64)
- func (con *Content) LineWidth(width float64)
- func (con *Content) Matrix(scaleX, scaleY, left, top float64)
- func (con *Content) MoveTo(left, top float64)
- func (con *Content) Rect(left, top, width, height float64)
- func (con *Content) Restore()
- func (con *Content) RoundedRect(left, top, width, height, radius float64)
- func (con *Content) Save()
- func (con *Content) ShowGlyphs(glyphs []uint16)
- func (con *Content) Stroke()
- func (con *Content) StrokeColor(red, green, blue float64)
- func (con *Content) TextOffset(dx, dy float64)
- func (con *Content) TextStart(left, baseline float64)
- func (con *Content) XObject(name string)
- type Doc
- func (doc *Doc) Alloc() int
- func (doc *Doc) Finish(root, info int) []byte
- func (doc *Doc) Object(num int, body string)
- func (doc *Doc) RawStream(num int, extra string, data []byte)
- func (doc *Doc) Stream(num int, extra string, data []byte)
- func (doc *Doc) WriteFont(embedded *Embedded) (int, error)
- func (doc *Doc) WriteImage(pic *Picture) int
- type Embedded
- type Picture
Constants ¶
const Bezier = 0.5522847498
Bezier is the circle approximation constant: the control point offset, as a fraction of the radius, that makes a cubic segment match a quarter circle to within a quarter of a per mille.
const Version = "1.7"
Version is the PDF version the writer claims.
1.7 covers everything here; nothing emitted needs a later one.
Variables ¶
This section is empty.
Functions ¶
func ASCIIString ¶
ASCIIString formats a string that is not shown to a person and carries no encoding mark: a URI, a destination name.
func Num ¶
Num formats a length for a PDF file: at most three decimals, which is the printout's own precision, with no trailing zeros and no exponent.
func TextString ¶
TextString formats a string for a field a reader shows to a person -- a title, an outline entry, a link caption.
Printable ASCII goes out as a literal string; anything else as UTF-16BE with a byte order mark, which is the only encoding PDF defines for text outside PDFDocEncoding.
Types ¶
type Content ¶
type Content struct {
// Height is the page height, the axis the flip turns around.
Height float64
// contains filtered or unexported fields
}
Content builds one page's content stream.
Callers work in the printout's coordinates -- origin top left, Y down -- and Content flips Y as it writes each number. The flip is per coordinate rather than a page-level matrix because a matrix that mirrors the page mirrors the glyphs with it.
func NewContent ¶
NewContent starts a content stream for a page of a height.
func (*Content) Clip ¶
func (con *Content) Clip()
Clip intersects the clipping path with the current path and ends it.
func (*Content) FillColor ¶
FillColor sets the non-stroking colour, which paints both fills and glyphs.
func (*Content) FillStroke ¶
func (con *Content) FillStroke()
FillStroke paints both, the fill first.
func (*Content) Len ¶
Len is the number of bytes written, which tells an empty page from one that drew something.
func (*Content) LineWidth ¶
LineWidth sets the stroke width.
Zero is a hairline, which PDF defines as the thinnest line the output device can render, so it is passed through rather than turned into a width of our choosing.
func (*Content) Matrix ¶
Matrix concatenates a transformation matrix, its translation given in top-down coordinates: the matrix maps the unit square onto a box whose top-left corner is at left, top.
func (*Content) RoundedRect ¶
RoundedRect appends a rectangle with rounded corners. A radius larger than half the shorter side is clamped, so a very round small box stays a box rather than turning inside out.
func (*Content) ShowGlyphs ¶
ShowGlyphs draws a run of glyphs, given as glyph indices in the embedded subset, which Identity-H encoding writes as two bytes each.
func (*Content) StrokeColor ¶
StrokeColor sets the stroking colour from components in 0..1.
func (*Content) TextOffset ¶
TextOffset moves the line start by a displacement.
This is how the segments of a justified line are placed: each offset is exact, so a segment's position does not depend on the glyph advances before it.
type Doc ¶
type Doc struct {
// Compress applies FlateDecode to content and font streams.
// Off makes the output readable, which is what a failing test wants.
Compress bool
// contains filtered or unexported fields
}
Doc collects indirect objects and writes the file around them.
Object numbers are handed out by Alloc and written in any order, so a page can name its content stream before the stream exists. Output is a pure function of what was written: no timestamps of its own, no map iteration, so the same document twice is the same bytes twice.
func (*Doc) Finish ¶
Finish appends the cross reference table and the trailer, and returns the whole file.
func (*Doc) RawStream ¶
RawStream writes a stream whose data is already filtered, so the caller supplies the Filter entry itself. A JPEG passes through this way, keeping its own compression.
func (*Doc) Stream ¶
Stream writes a stream object.
extra holds the dictionary entries other than Length and Filter, without the enclosing angle brackets.
func (*Doc) WriteFont ¶
WriteFont writes a font's five objects and returns the number of the Type0 dictionary, which is what a page's resource dictionary names.
func (*Doc) WriteImage ¶
WriteImage writes an image XObject, and its soft mask when it has one, returning the number of the image object.
type Embedded ¶
type Embedded struct {
Program *sfnt.Font
Glyphs []uint16
// Advances are the glyphs' advance widths in font units,
// parallel to Glyphs. They are supplied rather than read
// back out of the program so that the widths a reader
// advances the pen by are the widths the engine measured.
Advances []float64
// Runes maps a subset glyph index to the characters it stands for,
// which is what makes the text selectable, searchable, and readable
// back out of the file.
Runes map[uint16][]rune
Italic bool
}
Embedded is one font as it will appear in the file: a font program, the glyphs the document actually uses, and how a reader is to read them back.
Glyphs holds original glyph indices, and a glyph's position in the slice is its index in the embedded subset, which under Identity-H encoding is also the two-byte code a content stream shows. Position 0 must be glyph 0, the empty box a font draws for a character it lacks.
type Picture ¶
type Picture struct {
Width, Height int
// ColorSpace is a PDF name without its slash: DeviceRGB or DeviceGray.
ColorSpace string
// Filter is the PDF filter the samples already carry, empty
// when they are raw and the writer is free to compress them.
Filter string
Data []byte
// Alpha holds one grey sample per pixel, absent for an opaque image.
Alpha []byte
}
Picture is an image ready to become an XObject: samples, the colour space they are in, and a soft mask when the source had transparency.
func DecodePicture ¶
DecodePicture turns an image file into samples a PDF can carry.
A JPEG whose own compression a PDF can read is passed through untouched, so a photograph does not grow twentyfold on the way into the document. Everything else is decoded and re-encoded, which is the simple road and correct for every format the format admits.
Source Files