%
%	%Z% %G% %I% %M%
%

\documentclass[ngerman,12pt,a4paper]{scrartcl}
\usepackage{ngerman}
\usepackage{lscape}
\usepackage{ifpdf}
\usepackage[latin1]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{textcomp}
\usepackage{mathptmx}
\usepackage[scaled=.92]{helvet}
\usepackage{courier}
\usepackage{amsmath}
\usepackage{array}
\usepackage{enumerate}
\usepackage{listings}
\lstset{numbers=none, basicstyle=\small}
\lstset{showstringspaces=true,showspaces=true}
\usepackage{longtable}
\usepackage{latexsym}
\usepackage{varioref}
\usepackage{color}
\ifpdf
\usepackage[activate=normal]{pdfcprot}
\usepackage[pdftex]{graphicx}
\usepackage{epstopdf}
\pdfcompresslevel=9
\usepackage[
  pdftex,
  a4paper=true,
  pdftitle={Das Handbuch für bmeps},
  pdfsubject={bmeps},
  pdfauthor={Dipl.-Ing. D. Krause},
  colorlinks=true,
  linkcolor=black,
  pdfpagemode=UseNone,
  pdfstartview={XYZ 0 835 1.25}
]{hyperref}
\else
\usepackage[dvips]{graphicx}
\DeclareGraphicsRule{.png}{eps}{.bb}{`bmeps #1}
\usepackage[
  dvips,
  colorlinks=true,
  linkcolor=black
]{hyperref}
\fi
% \renewcommand*{\sectfont}{\bfseries}
% \parindent0cm
% \setlength{\parindent}{0cm}
\author{Dipl.-Ing.~D.~Krause}
\title{Das Handbuch zu bmeps 2.0.0}

\begin{document}
% \begin{sloppy}
\maketitle
\cleardoublepage
\ifpdf\pdfbookmark[1]{\contentsname}{tocanc}\fi
\tableofcontents
\cleardoublepage
\section{Übersicht}
\subsection{Einsatzzweck}\input{b2de0101}
\subsection{Vorwort zur Version 2.0.0}\input{b2de0102}
\subsection{Lizenzbedingungen}\input{b2de0103}
\section{License}
The software in this package -- except the files and directories
mentioned in the paragraph below -- is licensed to you under a \textsc{bsd}
style license as follows:
\begin{itemize}
\item	Redistribution and use in source and binary forms,
with or without modification, are permitted provided
that the following conditions are met:
\begin{itemize}
\item	Redistributions of source code must retain the above
  copyright notice, this list of conditions and the
  following disclaimer.
\item	Redistributions in binary form must reproduce the above 
  opyright notice, this list of conditions and the following
  disclaimer in the documentation and/or other materials
  provided with the distribution.
\item	Neither the name of the Dirk Krause nor the names of
  its contributors may be used to endorse or promote
  products derived from this software without specific
  prior written permission.
\end{itemize}
\item	This software is provided by the copyright holders
	and contributors ``as~is'' and any express or implied warranties,
	including, but not limited to, the implied warranties of
	merchantability and fitness for a particular purpose
	are disclaimed.\\*
	In no event shall the copyright owner or contributors be
	liable for any direct, indirect, incidental, special,
	exemplary, or consequential damages (including, but not
	limited to, procurement of substitute goods or services;
	loss of use, data or profits; or business interruption)
	however caused and on any theory of liability, whether
	in contract, strict liability, or tort (including negligence
	or otherwise) arising in any way out of the use of this
	software, even if advised of the possibility of such damage.
\end{itemize}
\clearpage
\textbf{Exceptions}
\begin{itemize}
\item	dvips-mods subdirectory\\*
The files in the dvips-mods subdirectory are derived from the original
dvips sources and remain under the same license conditions and copyright
statements as the original sources.
The current version of dvips -- the version you should use to build a
modified dvips -- can be found in the teTeX distribution\footnote{\url{ftp://ftp.dante.de/tex-archive/systems/unix/teTeX/current/distrib}}, the file
is tetex-src.tar.gz. After unpacking the archive you will find a directory
tetex-src-2.0.2/texk/dvipsk (the version number may vary), see the sources and
documentation in this directory for copyright and license details.
\item	contrib/kant\_krishna directory and DOCU/kant\_krishna/excel\_to\_eps.txt file\\*
The file excel\_to\_eps.vb was provided by Krishna Kant. No copyright
and/or license terms were specified for this file. You should leave
the Author:...-line intact when distributing this file.
\end{itemize}
\clearpage
\section{Installation}
\subsection{Prerequisitions}
The following software packages should be installed before
you start to install bmeps:
\begin{itemize}
\item	\textbf{zlib} (required)\\*
A general purpose compression library\footnote{\url{http://www.gzip.org/zlib}}.
\item	\textbf{libpng} (required)\\*
A library for dealing with \textsc{png}
images\footnote{\url{http://www.libpng.org/pub/png/libpng.html}}.
\item	\textbf{jpeglib} (optional)\\*
The Independent \textsc{jpeg} Group's Free Software to handle \textsc{jpeg}
files\footnote{\url{ftp://ftp.uu.net/graphics/jpeg/}}.
After ``make~install'' copy all *.h-files to
/\ldots{}/include and the *.a-files to /\ldots{}/lib.
\item	\textbf{Net\textsc{pbm} Tools} (optional)\\*
Tools and libraries for converting bitmap
images\footnote{\url{ftp://ftp.metalab.unc.edu/pub/Linux/apps/graphics/convert/}}.
% NACH DEM 20.06.2003 evtl. wieder hinzufuegen.
% ---------------------------------------------
% \item	\textbf{libtiff} (optional)\\*
% Tools and libraries for dealing with TIFF
% images\footnote{\url{ftp://ftp.remotesensing.org/pub/libtiff/}}.
\end{itemize}
Install the packages in the order given here and make sure to set
\textsc{cflags} and \textsc{ldflags}.

\subsection{Installation procedure}
Unpack the distribution and change into the bmeps directory.
Run
\begin{lstlisting}
	./configure
	make
	make install
\end{lstlisting}
to build and install the software.\\*
A second makefile ``Makefile-shared-linux'' is created. This can be
used on Linux systems to build a shared library and a binary using
this shared library.
\begin{lstlisting}
	./configure
	make -f Makefile-shared-linux
	make -f Makefile-shared-linux install
\end{lstlisting}
\emph{Note:} Dealing with shared libraries is not recommended to the
wide majority of users, only experienced users, developers and people creating
binary installation packages for Linux distributions and
\LaTeX{} distributions should do this. The directory containing the libbmeps.so
library must be added to the LD\_LIBRARY\_PATH environment variable
or listed in the /etc/ld.so.conf file. For details about placing shared libraries
and configuring search paths consult you systems manuals.
\clearpage

\subsection{Dvips modification}
\subsubsection{Overview}
There are two ways to convert \textsc{png}
and \textsc{jpeg} images to \textsc{eps} when dvips
is running:
\begin{itemize}
\item	Run the bmeps program. This option is available immediately
after the bmeps package is installed and requires no further work.
\item	Invoke conversion routines directly within dvips. This
requires to build a modified dvips. The steps to do so are
shown below.
\end{itemize}
\subsubsection{Getting the sources}
To build dvips you need the sources for two further
packages:
\begin{itemize}
\item	The kpathsea library. This library is used by dvips
to search for files.
\item	The dvips program itself.
\end{itemize}
These packages are available at \textsc{ctan}\footnote{\url{ftp://ftp.dante.de/tex-archive/systems/unix/teTeX/current/distrib/}}, download
``tetex-src.tar.gz''.

This archive contains the sources for the entire teTeX distribution,
we need to deal only with kpathsea and dvipsk in
tetex/texk.

\subsubsection{Build and install kpathsea}
In the kpathsea directory type
\begin{lstlisting}
	./configure
	make
	make install
\end{lstlisting}
If you have downloaded the ``tetex-src.tar.gz'' archive, run
\begin{lstlisting}
	./configure
\end{lstlisting}
in the tetex directory and
\begin{lstlisting}
	make
	make install
\end{lstlisting}
in the tetex/texk/kpathsea directory.

\subsubsection{Build the unmodified dvips}
First we need to make sure that we are able to build an unmodified
dvips. To do so run
\begin{lstlisting}
	./configure
	make
\end{lstlisting}
in the dvipsk directory.
If you have downloaded the ``tetex-src.tar.gz'' archive it is
not necessary to run configure again, running make
in the tetex/texk/dvipsk directory is sufficient.

\subsubsection{Create a backup of dvips}
Type
\begin{lstlisting}
	which dvips
\end{lstlisting}
to see where your dvips resides. Create a backup copy of the existing
dvips and name it ``dvips.original''. The copy should get
the same permissions as the original.

\subsubsection{Build the modified dvips}
Change into the dvipsk directory.
Copy the files from \ldots{}/bmeps/dvips-mods into the dvipsk
directory.\\*
Run
\begin{lstlisting}
	./configure
	make
	cp dvips `which dvips`
\end{lstlisting}
to build and install the modified dvips.
If you specified options for ./configure when building
kpathsea you should specify the same options to ./configure
here.\\*
Type
\begin{lstlisting}
	dvips --version
\end{lstlisting}
to verify proper installation. The output should contain a line
like
\begin{lstlisting}
	dvips(k) 5.86 modified for bitmap graphics support
\end{lstlisting}
showing that a modified dvips is in use.

\clearpage
\section{Usage}

\subsection{Bounding box creation}
\LaTeX{} needs bounding box information for all graphics to include.
Run a shell script like the following to create bounding box information
files for all \textsc{png}s in a directory:
\begin{lstlisting}
    #! /bin/csh
    foreach i (*.png)
     set j = $i:r
     set j = "${j}.bb"
     bmeps -b $i $j
    end
\end{lstlisting}
To create bounding box information for a single \textsc{png} file use
bmeps as follows:
\begin{lstlisting}
    bmeps -b x.png x.bb
\end{lstlisting}
\emph{Note:\/} You should not use the ebb program in conjuction with
bmeps because the programs use different methods to calculate
the BoundingBox.
\begin{itemize}
\item	Bmeps converts 1 \textsc{png} pixel into 1 \textsc{ps} point.\\
	72 \textsc{png} pixels are used to fill one inch.
\item	Ebb expects image conversion programs to convert
	1 \textsc{png} pixel into \(\tfrac{72}{150}\)
	\textsc{ps} point.\\
	150 \textsc{png} pixels are used to fill one inch.
\end{itemize}
\clearpage
\subsection{Register file type}
In your \LaTeX{} document's preamble write
\begin{lstlisting}
    \DeclareGraphicsRule{.png}{eps}{.bb}{`bmeps #1}
\end{lstlisting}
This tells \LaTeX{} that files having suffix .png
can be converted into \textsc{eps} file format. Bounding box information
is expected in a file having the same filename but the suffix
.bb. When the .dvi file is processed by
dvips the program bmeps is invoked to convert the
file to \textsc{eps}.

If you have build a modified dvips -- I strongly recommend
to do so -- you should specify
\begin{lstlisting}
    \DeclareGraphicsRule{.png}{eps}{.bb}{}
\end{lstlisting}
instead.
The dvips program now invokes the conversion routines from the bmeps
library directly without running external programs.



If you want to use your \LaTeX{} source with both \LaTeX{}/dvips
and pdflatex write
\begin{lstlisting}
    \usepackage{ifpdf}
    \ifpdf
    ...
    \else
    ...
    \DeclareGraphicsRule{.png}{eps}{.bb}{`bmeps #1}
    \fi
\end{lstlisting}
respectively
\begin{lstlisting}
    \usepackage{ifpdf}
    \ifpdf
    ...
    \else
    ...
    \DeclareGraphicsRule{.png}{eps}{.bb}{}
    \fi
\end{lstlisting}
instead.
\clearpage
\subsection{Setting up \textsc{ps} output}
\subsubsection{The EPSOUTPUT environment variable}
\textsc{ps} level and \textsc{ps} features can be configured via the
\textsc{epsoutput} environment variable.
The following settings can be made here:
\begin{itemize}
\item	\textbf{Verbose mode}\\*
Use ``V'' to turn verbose mode on. By default it is turned off.
If bmeps encounters an error when reading input files it writes
an error message as PostScript comment to the output.\\*
In verbose mode the error message is also written to the standard
error output.
\item	\textbf{\textsc{ps} level}\\*
Use ``1'', ``2'' or ``3'' to specify the \textsc{ps} level.
\item	\textbf{Colored/grayscaled output}\\*
Use ``c'' to obtain colored output, ``g'' for grayscaled
output.
\item	\textbf{showpage operator}\\*
By default bmeps does not print a showpage operator at the end of
the output file (version 1.0.9 and above).\\*
The showpage operator can be printed using the ``h''
character.
\item	\textbf{PostScript memory managment}\\*
Bmeps can install a separated dictionary using the
``u'' character.\\*
The ``r'' character can be used to add a ``1~vmreclaim''
instruction.
\item	\textbf{\textsc{dsc} comments}\\*
By default bmeps does not issue \textsc{dsc} comments
(except ``\%!PS-Adobe\ldots{}'').\\*
Earlier versions (before 1.0.2) of bmeps had a bug,
\textsc{dsc} comments were not written in correct order. Recent versions
of GhostScript/GhostView complained about this.
Comment order is corrected now, additionally \textsc{dsc} comment output
is disabled now by default.
Use ``x'' to enable \textsc{dsc} comments.
\item	\textbf{Encoding and compression}\\*
If you have selected at least \textsc{ps} level 2 you can specify
``8'' to use \textsc{Ascii}85-encoding instead of \textsc{Ascii}-Hex-encoding.
Furthermore you can specify ``r'' for run-length-compression.
If \textsc{ps} level 3 is used you can specify ``f'' to use flate
compression. Multiple encoding algorithms can be combined.
\item	\textbf{Exact resolution}\\*
Specify ``e'' to use the resolution information found in the PNG file's
pHYs chunk. This option should not be used to produce images for inclusion
in \LaTeX{} documents or DTP applications. It is intended for creating
EPS files for standalone viewing.
\item	\textbf{Draft mode}\\*
If you specify ``d'' for draft mode only placeholders
are printed instead of converted pictures.
\item	\textbf{Alpha channel usage}\\*
When \textsc{ps} level 3 is in use you can convert an alpha channel
into a clipping mask. To do so specify ``a''. If the alpha
channel expresses opacity (default) specify ``o'', if it
expresses transparency specify ``t''.
Normally only pixels with full transparency are masked out.
To change this so that all pixels with transparency not 0 are
masked out specify ``l''.\\*
If you want to mix foreground and background color depending on
the alpha channel value specify ``m''.
A triple of numbers (i.e. ``128,255,128'' for light green) can be used
to specify a default background color.
The background color
specification must appear after the ``a'' for alpha channel
settings. If you want your background color specification to
superseed the background chunk contained in the file, specify
``s''.
\end{itemize}
Examples:
\begin{itemize}
\item	In a C-Shell (or a derivate) use
\begin{lstlisting}
    setenv EPSOUTPUT 2gr8
\end{lstlisting}
to set up \textsc{eps} export for PS level 2,
grayscaled output, run-length-compression
and \textsc{Ascii}85-encoding. Most \textsc{ps} level 2 printers
should be able to print this.
\item	In a Bourne-Shell (or a derivate) use
\begin{lstlisting}
    EPSOUTPUT=3crf8
    export EPSOUTPUT
\end{lstlisting}
to get \textsc{ps} level 3, colored output, run-length and flate compression
and \textsc{Ascii}85-encoding. This will produce output suitable as input for
ps2pdf.
\item	On an \textsc{dos}-prompt on Windows type
\begin{lstlisting}
    set EPSOUTPUT=3crf8ams128,255,128
\end{lstlisting}
to convert a transparancy alpha channel to a masking bitmap.
Depending on the alpha channels value the foreground picture of
each pixel is mixed against a lightgreen background. The specified
background color is used, a background chunk in the image file is ignored.
\item	In a C-Shell you can use
\begin{lstlisting}
    setenv EPSOUTPUT d
\end{lstlisting}
to produce drafts only.
\end{itemize}
\subsubsection{Command line options}
The \textsc{epsoutput} environment variable is a convenient way to
set up default options.\\*
These defaults can be overwritten by command line options:
\begin{itemize}
\item	-b\\*
Generate a bounding box only. No other options should be specified together
with this option.
\item	-d\\*
Draft mode, generate a symbol only. No other options should be specified
together with this option.
\item	-V\\*
Enables verbose output.
\item	-p \textit{level}\\*
Set the \textsc{ps} level, ``1'', ``2'' or ``3''.
\item	-c\\*
Colored printing, requires \textsc{ps} level 2.
\item	-g\\*
Grayscaled printing. You can specify either ``-c'' or ``-g''.
\item	-e \textit{encoding}\\*
Specify compression and encoding mechanisms, the string consists of
the following key characters:
\begin{itemize}
\item	``8''\\*
Use ASCII-85-encoding. Requires \textsc{ps} level 2.
\item	``r''\\*
Use run-length compression. Requires \textsc{ps} level 2.
\item	``f''\\*
Use flate compression. Requires \textsc{ps} level 3.
\end{itemize}
\item	-a \textit{alpha-options}\\*
Specify how to handle the alpha channel.
The string consists of the following entries:
\begin{itemize}
\item	o\\*
Treat alpha channel data as opacity (default).
\item	t\\*
Treat alpha channel data as transparency. You can use either ``o'' or ``t'',
not both.
\item	l\\*
Use alternative trigger level for image mask creation. By default
only pixels with no opacity at all are masked out. This option masks out
all pixels except those with full opacity.
\item	m\\*
Mix image against white background or a specified color (see below).
\item	\textit{rgb-triple}\\*
Specify background color as \textsc{rgb}-triple, i.e. ``128,255,128'' for
light green.
\item	s\\*
Give the user-specified background color (see entry above) a higher priority
than the color specified in the PNG file's background chunk.
\end{itemize}
\item	-t \textit{filetype}\\*
Specify the source file type if the program is running as a pipe
or unusual file names are in use. Use either ``png'', ``jpg''
or ``pnm''.
\item	-s\\*
Print \textsc{dsc} comments.
\item	-o\\*
Print a showpage operator at the end of the output.
\item	-u\\*
Undefine ``/pstr'' and ``/inputf'' to allow the garbage collection
to release the memory.
\item	-r\\*
Force garbage collection at the end of file via ``1~vmreclaim''.
\item	-q\\*
Use resolution information from the PNG file's pHYs chunk, if available.
\end{itemize}
\clearpage
\subsection{Specifying dvips command line options}
If you have build a modified dvips you can overwrite
the information from \textsc{epsoutput} by command line options.
Use ``\textbf{-I}~\textit{option}'' like
\begin{lstlisting}
   dvips -I 2gr8 ...
\end{lstlisting}
to specifiy \textsc{eps} output options.
\clearpage
\subsection[Recommended options]{Recommended options for typical usage scenarios}
\subsubsection{PS level 2 printers}
If you plan to use the EPS images in a document to be printed on a
printer capable of PS level 2 you should use the bmeps options
\begin{lstlisting}
  -p2 -g -e8r -u
  -p2 -c -e8r -u
\end{lstlisting}
for grayscaled/colored printing. For the \textsc{epsoutput} variable use:
\begin{lstlisting}
  2g8ru
  2c8ru
\end{lstlisting}
For dvips use the option:
\begin{lstlisting}
  -I 2g8ru
  -I 2c8ru
\end{lstlisting}
\subsubsection{PS level 3 for distilling}
If you plan to use the EPS images in a document to be distilled or passed
to Ghostscript to produce a PDF you should use the bmeps options
\begin{lstlisting}
  -p3 -c -e8rf -u -r
\end{lstlisting}
For the \textsc{epsoutput} variable use:
\begin{lstlisting}
  3c8rfu
\end{lstlisting}
For dvips use the option:
\begin{lstlisting}
  -I 3c8rfu
\end{lstlisting}
\clearpage
\subsection{Examples}
The \textsc{examples} subdirectory contains some
\textsc{ps} files derived from the same example.tex file using
different dvips options.
The picture ``stefan\_255\_rgba.png'' was obtained from
the\\*
\textsc{Miscellaneous~Transparent~PNGs~Using~Image~Tags} page
on the libpng homepage
\footnote{\url{ftp://ftp.freesoftware.com/pub/png/index.html}}.
It was
provided courtesy of Stefan Schneider.

Some files (names start with ``bg\ldots{}'') have a page
background color.

I recommend to use ``gv''
\footnote{\url{http://wwwthep.physik.uni-mainz.de/\textasciitilde plass/gv/}}
on \textsc{unix} rather than ``ghostview''
to view the examples.
It needs the ``Xaw3d'' library
\footnote{\url{ftp://ftp.x.org/contrib/widgets/Xaw3d/}}.
\begin{itemize}
\item	The file ``1g.ps'' was produced by:\\*
\begin{lstlisting}
    latex example
    dvips -I 1g example
    mv example.ps 1g.ps
\end{lstlisting}
It is a \textsc{ps} level 1 file containing a grayscaled picture.
\item	File ``2g8r.ps'' was produced using options ``2g8r''
and contains the same grayscaled picture run-length-compressed
and \textsc{Ascii}85-encoded.
\item	File ``2c8r.ps'' was produced using options ``2c8r''
and contains a colored version of the picture, run-length-compressed
and \textsc{Ascii}85-encoded.
\item	File ``3c8rf.ps'' was produced using options ``3c8rf''.
Flate compressions was used additionaly.
\item	File ``bg3c8rf.ps'' was produced using options ``3c8rf''.
It has a cyan page background.
\item	File ``bg3c8rfa.ps'' was produced using options ``3c8rfa''.
The alpha channel in the picture was converted into an image mask.
All pixels having at least some opacity are drawn in the color specified
by the file, pixels with 0 opacity are skipped.
\item	File ``bg3c8rfam.ps'' was produced using options ``3c8rfam''.
For each pixel the color is calculated from the foreground color
specified in the file and the background color from the background
chunk in the file depending on the alpha channel.\\*
If there was no background chunk in the \textsc{png} file white
background would be used.
\item	``bg3c8rfams0\_255\_255.ps'' was produced using
``3c8rfams0,255,255''.
The pixel colors are calculated from the foreground color specified
in the file and the background color cyan (specified as
\textsc{rgb} 0 255 255) depending on the alpha channel.\\*
You can get ``free-standing'' objects by defining the same
background color as used as page background color.
\end{itemize}
\clearpage
\section{Programmer's manual}

\subsection{How to use libbmeps in applications}

\subsubsection{Module configuration}
There are two ways to configure libbmeps' output:
\begin{itemize}
\item	Provide a configuration string using\\*
\begin{lstlisting}
    void bmeps_cfg(char *cs);
\end{lstlisting}
The configuration string \textit{cs} corresponds to the
\textsc{epsoutput} environment variable.
\item	Manual configuration.\\*
To do so we need some variables:
\begin{lstlisting}
  int pslevel, colored, enc_a85, enc_rl, enc_fl,
  is_draft, alpha, trans, altrig, mix, spec,
  bg_red, bg_green, bg_blue,
  shp, dic, vmr, usr;
\end{lstlisting}
We retrieve the current settings:
\begin{lstlisting}
  pslevel  = bmeps_get_pslevel();
  /* PS level */
  colored  = bmeps_get_colored();
  /* 1=colored, 0=grayscaled */
  enc_a85  = bmeps_get_enc_a85();
  /* 1=use ASCII85 encoding */
  enc_rl   = bmeps_get_enc_rl();
  /* 1=use run-length-encoding */
  enc_fl   = bmeps_get_enc_fl;	
  /* 1=use flate compression */
  is_draft = bmeps_get_draft();	
  /* 1=draft only */
  alpha    = bmeps_get_alpha();
  /* 1=special alpha handling wanted */
  trans    = bmeps_get_trans();	
  /* 1=alpha channel is transparency */
  altrig   = bmeps_get_altrig();
  /* 1=alternative masking trigger level*/
  mix      = bmeps_get_mix();	
  /* 1=mix background and foreground */
  spec     = bmeps_get_spec();	
  /* 1=specified background */
  /* background color */
  bg_red   = bmeps_get_bg_red();
  bg_green = bmeps_get_bg_green();
  bg_blue  = bmeps_get_bg_blue();
  shp      = bmeps_get_showpage();
  dic      = bmeps_get_dictionary();
  vmr      = bmeps_get_vmreclaim();
  /* keep resolution */
  usr      = bmeps_get_usr();
\end{lstlisting}
\item	After processing configuration files and command line
arguments we need to write the changed variables back into libbmeps:
\begin{lstlisting}
  bmeps_setup(
    pslevel, colored, enc_a85, enc_rl, enc_fl,
    is_draft, alpha, trans, altrig, mix, spec,
    bg_red, bg_green, bg_blue,
    shp, dic, vmr, usr
  );
\end{lstlisting}
\end{itemize}

\subsubsection{Checking support for a given filename}
The function
\begin{lstlisting}
  int bmeps_can_handle(char *name);
\end{lstlisting}
can be used to check, whether the file with the given name
can be converted. The check is performed based on the file name
extension, the file contentes is not inspected.
The function returns a value not 0 if the file
can be converted, 0 if not.
\clearpage
\subsection{Error messages}
To change verbose mode use
\begin{lstlisting}
  void bmeps_set_verb(int flag);
\end{lstlisting}
verbose mode is turned off if \textit{flag~=~0} and turned on
for all other values.

Use
\begin{lstlisting}
  void bmeps_set_app(int flag);
\end{lstlisting}
to indicate whether your application produces ``normal'' logging
(\textit{flag~=~0}) or ``special'' logging (like dvips, where we
should write a newline before we start the error message).

The functions
\begin{lstlisting}
  int bmeps_get_verb(void);
  int bmeps_get_app(void);
\end{lstlisting}
can be used to check these settings.
\clearpage
\subsubsection{Writing an image}
Here is a simple example how to write an image.\\*
For a detailed example covering transparency\ldots{} look into ``pngeps.ctr''.
\begin{lstlisting}
  FILE *out;
  char *name;
  unsigned long width, height;
  ...
  bmeps_header(out, name, width, height);
  if(bmeps_get_draft()) {
    bmeps_draft(out, width, height);
  } else {
    bmeps_begin_image(out, width, height);
      for(y = 0; y < height; y++) {
        for(x = 0; x < width; x++) {
          bmeps_add_rgb(r(x,y), g(x,y), b(x,y));
        }
      }
    bmeps_end_image(out);
  }
  bmeps_footer(out);
\end{lstlisting}

\subsection{MT-Level}
This library is not thread-safe. Configuration data and
other data are stored in module-wide static variables.\\*
You can convert only one image at a time in a given process.

% \end{sloppy}
\end{document}