Version: v0.0.0-...-1fae4d3 Latest Latest

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

Go to latest
Published: May 13, 2014 License: BSD-2-Clause Imports: 8 Imported by: 0


#ps GoDoc Package ps implements the PostScript backend for libcairo rendering.


go get

Automatically generated by autoreadme on 2014.05.08



Package ps implements the PostScript backend for libcairo rendering.


EPS files must contain only one page.

Note that libcairo does not include the device independent preview.

The Encapsulated PostScript Specfication† describes how to embed EPS files into PostScript files


The PostScript surface natively supports Type 1 and TrueType fonts. All other font types (including OpenType/PS) are converted to Type 1.

Fonts are always subsetted and embedded.

Fallback images

Cairo will ensure that the PostScript output looks the same as an image surface for the same set of operations. When cairo drawing operations are performed that cannot be represented natively in PostScript, the drawing is rasterized and embedded in the output.

The rasterization of unsupported operations is limited to the smallest rectangle, or set of rectangles, required to draw the unsupported operations.

Fallback images are the main cause of large file sizes and slow printing times. Fallback images have a comment containing the size and location of the fallback.

> grep 'Fallback' Fallback Image: x=100, y=100, w=299, h=50 res=300dpi size=783750 Fallback Image: x=100, y=150, w=350, h=250 res=300dpi size=4560834 Fallback Image: x=150, y=400, w=299, h=50 res=300dpi size=783750

Supported Features

The following tables lists all features natively supported by the PostScript surface.

FEATURE                          NOTES
Paint/Fill/Stroke/ShowGlyphs     depending on pattern
Fonts                            some may be converted to Type 1
Opaque colors
Linear gradients                 level 3 only
Radial gradients                 level 3 and when one circle is inside
                                 the other and extent is ExtendNone or
                                 ExtendPad only.


Libcairo must be compiled with


in addition to the requirements of cairo.

Example (Landscape)

When generating landscape PostScript output the surface should not be created with a width greater than the height. Instead create the surface with a height greater than the width and rotate the cairo drawing context. The "%PageOrientation" DSC comment is used by PostScript viewers to indicate the orientation of the page.

The steps to create a landscape page are: Set the page size to a portrait size. Rotate user space 90 degrees counterclockwise and move the origin to the correct location. Insert the "%PageOrientation: Landscape" DSC comment.

draw := func(c *cairo.Context, text string, width, height int) error {
	const Border = 50
	border := cairo.Pt(Border, Border)
	size := cairo.Pt(float64(width), float64(height))

		Rectangle(cairo.Rectangle{border, border.Sub(size)}).

		SelectFont("Sans", 0, 0).
		MoveTo(cairo.Pt(200, float64(height)/3)).

		MoveTo(cairo.Pt(120, float64(height)*2/3.)).
		ShowText(fmt.Sprintf("Width: %d points\t\tHeight: %d points"))

	return nil

const (
	PageWidth  = 595
	PageHeight = 842
surface, err := New(os.Stdout, PageWidth, PageHeight, false, nil, nil)
if err != nil {
defer surface.Close()

c, err := cairo.New(surface)
if err != nil {
defer c.Close()

//Print portrait page
surface.AddComment("PageOrientation", "Portrait")
err = draw(c, "Portrait", PageWidth, PageHeight)
if err != nil {

//Print landscape page
surface.AddComment("PageOrientation", "Landscape")

//Move the origin to landscape origin and rotate counterclockwise
	Translate(cairo.Pt(0, PageHeight)).
	Rotate(-math.Pi / 2)

err = draw(c, "Landscape", PageHeight, PageWidth)
if err != nil {




View Source
const (
	//Level2 is the language level 2 of the PostScript specification.
	Level2 level = C.CAIRO_PS_LEVEL_2
	//Level3 is the language level 3 of the PostScript specification.
	Level3 level = C.CAIRO_PS_LEVEL_3

The level type is used to describe the language level of the PostScript Language Reference that a generated PostScript file will conform to.

While language level 3 supports additional features, such as gradient patterns, language level 2 printers cannot print PostScript containing language level 3 features.

Note that when using Level3 the LanguageLevel DSC comment in the output may still indicate 2 if no level 3 features are used.

Originally cairo_ps_level_t.


This section is empty.


func Comment

func Comment(key, value string) comment

Comment specifies a PostScript Document Structuring Comment (DSC).

The returned comment has String and Err methods.

The returned comment's String method produces this output:

%%key: value

If value == "", String produces:


The total byte length of the result of String must not be greater than 255.

As a convenience, Comment trims trailing and leading whitespace from the key and value; however, it is an error for a key to contain any other whitespace and for value to contain any newlines after being trimmed.

It is also an error for key to contain the ":" colon character.

The following keys are used by libcairo and are forbidden:


Use of a forbidden key results in an error.

Even if a comment does not result in an error, that does not mean it produces the desires effect, only that it is not invalid.

func Commentf

func Commentf(key, value string, vars ...interface{}) comment

Commentf is a convenience function for

Comment(key, fmt.Sprintf(value, vars...))

See Comment for an explanation for how a comment is constructed and what constitutes a valid comment.

func Levels

func Levels() (levels []level)

Levels reports the supported language levels.

Originally cairo_ps_get_levels.

func RawComment

func RawComment(s string) comment

RawComment creates a comments that is exempt from formatting and error checking. Use at your own peril.


type Comments

type Comments []comment

Comments represents a sequence of PostScript Document Structuring Comments (DSC).

Please see that manual for details on the available comments and their meanings.

In particular, the %%IncludeFeature comment allows a device-independent means of controlling printer device features, so the PostScript Printer Description Files Specification will also be a useful reference.

The individual comment entries have String and Err methods.

See Comment for an explanation for how a comment is constructed and what constitutes a valid comment.

Comments can be reused and do not need to be reconstituted on each use if they do not change.

func (Comments) Err

func (c Comments) Err() error

Err calls Err on each comment in turn and returns the first error found.

type Surface

type Surface struct {
	// contains filtered or unexported fields

Surface is a PostScript surface.

Surface implements cairo.PagedVectorSurface

func New

func New(w io.Writer, width, height float64, eps bool, header, setup Comments) (S Surface, err error)

New creates a new PostScript of the specified size.

W is the Writer the PostScript is written to. Width and height are in the unit of a typographical point (1 point = 1/72 inch). Eps specifies whether this will be Encapsulated PostScript. Header is any DSC comments to apply to the header section. Setup is any DSC comment to apply to the setup section.

Originally cairo_ps_surface_create_for_stream and cairo_ps_surface_set_eps and cairo_ps_surface_dsc_comment and cairo_ps_surface_dsc_begin_setup and cairo_ps_surface_dsc_begin_page_setup.

func (Surface) AddComment

func (s Surface) AddComment(key, value string) error

AddComment is shorthand for adding a single comment.

func (Surface) AddCommentf

func (s Surface) AddCommentf(key, value string, vars ...interface{}) error

AddCommentf is shorthand for adding a single formatted comment.

func (Surface) AddComments

func (s Surface) AddComments(comments Comments) (err error)

AddComments adds comments to the PageSetup sections.

Originally cairo_ps_surface_dsc_comment.

func (Surface) EPS

func (s Surface) EPS() bool

EPS reports whether s is Encapsulated PostScript.

Originally cairo_ps_surface_get_eps.

func (Surface) RestrictTo

func (s Surface) RestrictTo(level level) error

RestrictTo restricts the generated PostScript to the specified level. The default is Level3.

This method should only be called before any drawing operations have been performed on this surface.

Originally cairo_ps_surface_restrict_to_level.

func (Surface) SetSize

func (s Surface) SetSize(width, height float64) error

SetSize changes the size of the PostScript surface for the current and subsequent pages.

This method should only be called before any drawing operations have been performed on the current page.

Originally cairo_ps_surface_set_size.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL