GL2PS: an OpenGL to PostScript printing
library
Christophe Geuzaine
October 17, 2015
Contents
1 Introduction 1
2 Usage 2
2.1 gl2psBeginPage and gl2psEndPage . . . . . . . . . . . . . . . . 2
2.2 gl2psText and gl2psTextOpt . . . . . . . . . . . . . . . . . . . . 6
2.3 gl2psDrawPixels . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.4 gl2psSpecial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.5 gl2psEnable and gl2psDisable . . . . . . . . . . . . . . . . . . 8
2.6 gl2psPointSize and gl2psLineWidth . . . . . . . . . . . . . . . 9
2.7 gl2psBlendFunc . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.8 gl2psBeginViewport and gl2psEndViewport . . . . . . . . . . . 10
2.9 gl2psSetOptions and gl2psGetOptions . . . . . . . . . . . . . 11
3 Example 11
4 Tips and tricks 12
5 Limitations 13
6 Contributors 13
7 Links 14
8 Versions 14
1 Introduction
GL2PS is a C library providing high quality vector output for any OpenGL
application. The main difference between GL2PS and other similar libraries
(see section 7) is the use of sorting algorithms capable of handling intersecting
1
2 USAGE 2
and stretched polygons, as well as non manifold objects. GL2PS provides ad-
vanced smooth shading and text rendering, culling of invisible primitives, mixed
vector/bitmap output, and much more...
GL2PS can currently create PostScript (PS), Encapsulated PostScript
(EPS), Portable Document Format (PDF) and Scalable Vector Graphics (SVG)
files, as well as L
A
T
E
X files for the text fragments. GL2PS also provides limited,
experimental support for Portable LaTeX Graphics (PGF). Adding new vector
output formats should be relatively easy; you can also use the excellent pstoedit
program to transform the PostScript files generated by GL2PS into many other
vector formats such as xfig, cgm, wmf, etc.
GL2PS is available at http://www.geuz.org/gl2ps/ and is released under
the GNU Library General Public License (see COPYING.LGPL). GL2PS can
also be used under an alternative license that allows (amongst other things,
and under certain conditions) for static linking with closed-source software
(see COPYING.GL2PS). Any corrections, questions or suggestions should be
e-mailed to the GL2PS mailing list gl2ps@geuz.org.
The interface consists of fifteen functions, all beginning with the prefix
gl2ps. All the data structures and the symbolic constants peculiar to GL2PS
begin with GL2PS.
2 Usage
2.1 gl2psBeginPage and gl2psEndPage
2.1.1 Specification
GLint gl2psBeginPage( const char *title, const char *producer,
GLint viewport[4],
GLint format, GLint sort, GLint options,
GLint colormode, GLint colorsize,
GL2PSrgba *colortable,
GLint nr, GLint ng, GLint nb,
GLint buffersize, FILE *stream,
const char *filename )
GLint gl2psEndPage( void )
2.1.2 Description and arguments
gl2psBeginPage and gl2psEndPage delimit the OpenGL commands that will
be caught in the feedback buffer (see section 5) and output to stream. The
arguments given to gl2psBeginPage determine the way primitives are handled:
title Specifies the plot title. For PostScript output, this string is placed in
the %%Title field.
2 USAGE 3
producer Specifies the plot producer. For PostScript output, this string is
placed in the %%For field.
viewport Specifies the plot viewport. The viewport can for example be ob-
tained with a call to glGetIntegerv(GL_VIEWPORT,viewport). This ar-
gument is ignored if the GL2PS_USE_CURRENT_VIEWPORT option is set.
format Specifies the output format, chosen among:
GL2PS_PS The output stream will be in PostScript format.
GL2PS_EPS The output stream will be in Encapsulated PostScript format.
GL2PS_PDF The output stream will be in Portable Document Format.
GL2PS_TEX The output will be a L
A
T
E
X file containing only the text
strings of the plot (cf. section 2.2), as well as an \includegraphics
command including a graphic file having the same basename as
filename.
1
GL2PS_SVG The output stream will be in Scalable Vector Graphics format.
GL2PS_PGF (Experimental) The output stream will be in Portable LaTeX
Graphics format.
sort Specifies the sorting algorithm, chosen among:
GL2PS_NO_SORT The primitives are not sorted, and are output in stream
in the order they appear in the feedback buffer. This is sufficient for
two-dimensional scenes.
GL2PS_SIMPLE_SORT The primitives are sorted according to their barycen-
ter. This can be sufficient for simple three-dimensional scenes and/or
when correctness is not crucial.
GL2PS_BSP_SORT The primitives are inserted in a Binary Space Partition
(BSP) tree. The tree is then traversed back to front in a painter-like
algorithm. This should be used whenever an accurate rendering of
a three-dimensional scene is sought. Beware that this algorithm re-
quires a lot more computational time (and memory) than the simple
barycentric sort.
options Sets global plot options, chosen among (multiple options can be com-
bined with the bitwise inclusive OR symbol |):
1
The two steps to generate a L
A
T
E
X plot with GL2PS are thus:
1. generate the PostScript or PDF file (e.g. file.ps or file.pdf) with no text strings, using
the GL2PS_PS, GL2PS_EPS or GL2PS_PDF format combined with the GL2PS_NO_TEXT option;
2. generate the L
A
T
E
X file file.tex, using the GL2PS_TEX format and specifying file.tex
as the filename argument to gl2psBeginPage.
You can of course combine the L
A
T
E
X output with other graphic formats than PostScript or
PDF. For example, you could export an image in JPEG or PNG format and use pdfL
A
T
E
X
with the same file.tex.
2 USAGE 4
GL2PS_NONE No option.
GL2PS_DRAW_BACKGROUND The background frame is drawn in the plot.
GL2PS_SIMPLE_LINE_OFFSET A small offset is added in the z-buffer to
all the lines in the plot. This is a simplified version of the GL2PS_
POLYGON_OFFSET_FILL functionality (cf. section 2.5), putting all the
lines of the rendered image slightly in front of their actual position.
This thus performs a simple anti-aliasing solution, e.g. for finite-
element-like meshes.
GL2PS_SILENT All the messages written by GL2PS on the error stream
are suppressed.
GL2PS_BEST_ROOT The construction of the BSP tree is optimized by
choosing the root primitives leading to the minimum number of splits.
GL2PS_NO_TEXT All the text strings are suppressed from the output
stream. This is useful to produce the image part of a L
A
T
E
X plot.
GL2PS_NO_PIXMAP All the pixmaps are suppressed from the output
stream.
GL2PS_LANDSCAPE The plot is output in landscape orientation instead of
portrait.
GL2PS_NO_PS3_SHADING (for PostScript output only) No use is made of
the shfill PostScript level 3 operator. Using shfill enhances the
plotting of smooth shaded primitives but can lead to problems when
converting PostScript files into PDF files. See also options nr, ng, nb
below.
GL2PS_NO_BLENDING Blending (transparency) is disabled alltogether (re-
gardless of the current GL_BLEND or GL2PS_BLEND status).
GL2PS_OCCLUSION_CULL All the hidden polygons are removed from the
output, thus substantially reducing the size of the output file.
GL2PS_USE_CURRENT_VIEWPORT The current OpenGL viewport is used in-
stead of viewport.
GL2PS_TIGHT_BOUNDING_BOX The viewport is ignored and the the plot is
generated with a tight bounding box, i.e., a bounding box enclosing
as tightly as possible all the OpenGL entities in the scene.
GL2PS_COMPRESS The output stream is compressed. For this option to
take effect you need to compile GL2PS with HAVE_ZLIB, HAVE_LIBZ
or GL2PS_HAVE_ZLIB defined, and link the executable with the zlib
library (http://www.gzip.org/zlib/).
PostScript or SVG files generated with this option turned on are
simply compressed “as a whole”, i.e., they are identical to regular
PostScript or SVG files compressed with the gzip program. For PDF
files the compression is done “locally” for each group of primitives,
in accordance with the official PDF specification.
2 USAGE 5
colormode Specifies the color mode: GL_RGBA or GL_COLOR_INDEX.
colorsize Specifies the size of the colormap if colormode is GL_COLOR_INDEX.
colortable Contains the colormap if colormode is GL_COLOR_INDEX. This
colormap must contain colorsize elements of type GL2PSrgba.
nr, ng, nb (for PostScript and SVG output only) Controls the number of flat-
shaded (sub-)triangles used to approximate a smooth-shaded triangle.
(For PostScript output, this is only used when the shfill operator is
not supported by the system or when the GL2PS_NO_PS3_SHADING option
is set.) The arguments nr, ng and nb specify the number of values used for
interpolating the full range of red, green and blue color components; that
is, a triangle is recursively subdivided until the color difference between
two of its vertices is smaller that 1/nr for the red component, 1/ng for
the green component and 1/nb for the blue component. If the arguments
are set to zero, default values are used.
buffersize Specifies the size of the feedback buffer.
stream Specifies the stream to which data is printed.
filename (for L
A
T
E
X output only) Specifies a name for the stream to which
data is printed.
2.1.3 Return value
gl2psBeginPage returns:
GL2PS_ERROR if an error occurred;
GL2PS_SUCCESS otherwise.
gl2psEndPage returns:
GL2PS_NO_FEEDBACK if the feedback buffer is empty;
GL2PS_OVERFLOW if the size of the feedback buffer given to gl2psBeginPage is
not large enough;
GL2PS_UNINITIALIZED if gl2psEndPage is called when the library is not ini-
tialized (e.g. if gl2psEndPage is called before gl2psBeginPage);
GL2PS_ERROR if an error occurred;
GL2PS_SUCCESS otherwise.
评论1