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

% \documentclass[ngerman,12pt,a4paper]{scrartcl}
% \usepackage{ngerman}
\documentclass[12pt,a4paper,titlepage]{article}
\usepackage{lscape}
\usepackage{ifpdf}
\usepackage[latin1]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{textcomp}
% \usepackage{newcent}
\usepackage{mathptmx}
\usepackage[scaled=.92]{helvet}
% \usepackage{avant}
\usepackage{courier}
\usepackage{array}
\usepackage{enumerate}
\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={The bmeps program and library},
  pdfsubject={Using the bmeps program and library},
  pdfauthor={Dipl.-Ing. D. Krause},
  colorlinks=true,
  linkcolor=linkgreen,
  pdfpagemode=None,
  pdfstartview=FitH
]{hyperref}
\definecolor{linkgreen}{rgb}{0,0.5,0}
\else
\usepackage[dvips]{graphicx}
\DeclareGraphicsRule{.png}{eps}{.bb}{`bmeps #1}
\usepackage[
  dvips,
  colorlinks=true,
  linkcolor=linkgreen
]{hyperref}
\definecolor{linkgreen}{rgb}{0,0.5,0}
\fi
% \renewcommand*{\sectfont}{\bfseries}
% \parindent0cm
\setlength{\parindent}{0cm}
\author{Dipl.-Ing.~D.~Krause}
\title{The bmeps program and library, version 1.0.7}

% \include{../../Cover/cover}
\begin{document}
\begin{sloppy}
\maketitle
\tableofcontents
\clearpage
\section{Overview}
The \texttt{bmeps} package contains a library and a command line tool
to convert PNG and other images to EPS.\\*
It is intended to be used together with \LaTeX{} and \texttt{dvips}.
Using the \texttt{bmeps} package \texttt{dvips} can convert images to EPS
"on the fly",
it is not longer necessary to convert the files explicitly.\\*
Different EPS features can be used depending on the selected PS level.
PS level 2 enables color output and ASCII85 output encoding instead
of ASCII-Hex-encoding. PS level 3 enables flate compression.\\*
PS level and EPS features can be specified when \texttt{dvips} or
\texttt{bmeps} is run.
\clearpage
\section{Installation}
\subsection{Prerequisitions}
The following software packages should be installed before
you start to install \texttt{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 PNG
images\footnote{\url{http://www.libpng.org/pub/png/libpng.html}}.
\item	\textbf{jpeglib} (optional)\\*
The Independent JPEG Group's Free Software to handle JPEG
files\footnote{\url{ftp://ftp.uu.net/graphics/jpeg/}}.
After \texttt{make install} copy all \texttt{*.h}-files to
\texttt{/.../include} and the \texttt{*.a}-files to \texttt{/.../lib}.
\item	\textbf{NetPBM 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
\texttt{CFLAGS} and \texttt{LDFLAGS}.

\subsection{Installation procedure}
Unpack the distribution and change into the \texttt{bmeps} directory.
Run\\*
\begin{verbatim}
        ./configure
        make
        make install
\end{verbatim}
to build and install the software.
\clearpage

\subsection{Dvips modification}
\subsubsection{Overview}
There are two ways to convert PNG and JPEG images to EPS when \texttt{dvips}
is running:
\begin{itemize}
\item	Run the \texttt{bmeps} program. This option is available immediately
after the \texttt{bmeps} package is installed and requires no further work.
\item	Invoke conversion routines directly within \texttt{dvips}. This
requires to build a modified \texttt{dvips}. The steps to do so are
shown below.
\end{itemize}
\subsubsection{Getting the sources}
To build \texttt{dvips} you need the sources for two further
packages:
\begin{itemize}
\item	The \texttt{kpathsea} library. This library is used by \texttt{dvips}
to search for files.
\item	The \texttt{dvips} program itself.
\end{itemize}
These package are available at CTAN. The easiest way to get them is to
download \texttt{teTeX-src-*.tar.gz} (use the latest version) from\\*
\texttt{ftp://ftp.dante.de} in\\*
\texttt{tex-archive/systems/unix/teTeX/current/distrib/sources}
This archive contains the sources for the entire \texttt{teTeX} distribution,
we need to deal only with \texttt{kpathsea} and \texttt{dvipsk} in
\texttt{tetex/texk}.

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

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

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

\subsubsection{Build the modified dvips}
Change into the \texttt{dvipsk} directory.\\*
Copy the files from \texttt{.../bmeps/dvips-mods} into the \texttt{dvipsk}
directory.\\*
Run
\begin{verbatim}
        ./configure
        make
        cp dvips `which dvips`
\end{verbatim}
to build and install the modified \texttt{dvips}.
If you specified options for \texttt{./configure} when building
\texttt{kpathsea} you should specify the same options to \texttt{./configure}
here.\\*
Type
\begin{verbatim}
	dvips --version
\end{verbatim}
to verify proper installation. The output should contain a line
like
\begin{verbatim}
	dvips(k) 5.86 modified for bitmap graphics support
\end{verbatim}
showing that a modified \texttt{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 PNGs in a directory:
\begin{verbatim}
    #! /bin/csh
    foreach i (*.png)
     set j = $i:r
     set j = "${j}.bb"
     bmeps -b $i $j
    end
\end{verbatim}
To create bounding box information for a single PNG file use
\texttt{bmeps} as follows:
\begin{verbatim}
    bmeps -b x.png x.bb
\end{verbatim}

\subsection{Register file type}
In your \LaTeX{} document's preamble write
\begin{verbatim}
    \DeclareGraphicsRule{.png}{eps}{.bb}{`bmeps #1}
\end{verbatim}
This tells \LaTeX{} that files having suffix \texttt{.png}
can be converted into EPS file format. Bounding box information
is expected in a file having the same filename but the suffix
\texttt{.bb}. When the \texttt{.dvi} file is processed by
\texttt{dvips} the program \texttt{bmeps} is invoked to convert the
file to EPS.\\*
If you have build a modified \texttt{dvips} you should specify
\begin{verbatim}
    \DeclareGraphicsRule{.png}{eps}{.bb}{}
\end{verbatim}
instead. No external program is necessary to handle \texttt{.png} images.

If you want to use your \LaTeX{} source with both \LaTeX{}/\texttt{dvips}
and \texttt{pdflatex} write
\begin{verbatim}
    \usepackage{ifpdf}
    \ifpdf
    \DeclareGraphicsRule{.png}{eps}{.bb}{`bmeps #1}
    \fi
\end{verbatim}
respectively
\begin{verbatim}
    \usepackage{ifpdf}
    \ifpdf \DeclareGraphicsRule{.png}{eps}{.bb}{} \fi
\end{verbatim}
instead.

\subsection{Setting up PS output}
PS level and PS features can be configured via the
\texttt{EPSOUTPUT} environment variable.
The following settings can be made here:
\begin{itemize}
\item	\textbf{PS level}\\*
Use \texttt{1}, \texttt{2} or \texttt{3} to specify the PS level.
\item	\textbf{Colored/grayscaled output}\\*
Use \texttt{c} to obtain colored output, \texttt{g} for grayscaled
output.
\item	\textbf{DSC comments}\\*
By default \texttt{bmeps} does not issue DSC comments
(except \texttt{\%!PS-Adobe...}).\\*
Earlier versions (before 1.0.2) of bmeps had a bug,
DSC comments were not written in correct order. Recent versions
of \texttt{GhostScript/GhostView} complained about this.
Comment order is corrected now, additionally DSC comment output
is disabled now by default.
Use \texttt{x} to enable DSC comments.
\item	\textbf{Encoding and compression}\\*
If you have selected at least PS level 2 you can specify
\texttt{8} to use ASCII85-encoding instead of ASCII-Hex-encoding.
Furthermore you can specify \texttt{r} for run-length-compression.
If PS level 3 is used you can specify \texttt{f} to use flate
compression. Multiple encoding algorithms can be combined.
\item	\textbf{Draft mode}\\*
If you specify \texttt{d} for draft mode only placeholders
are printed instead of converted pictures.
\item	\textbf{Alpha channel usage}\\*
When PS level 3 is in use you can convert an alpha channel
into a clipping mask. To do so specify \texttt{a}. If the alpha
channel expresses opacity (default) specify \texttt{o}, if it
expresses transparency specify \texttt{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 \texttt{l}.\\*
If you want to mix foreground and background color depending on
the alpha channel value specify \texttt{m}.\\*
You can specify a default background color as triplet of numbers
like \texttt{128,255,128} for light green. The background color
specification must appear after the \texttt{a} for alpha channel
settings. If you want your background color specification to
superseed the background chunk contained in the file, specify
\texttt{s}.
\end{itemize}
Examples:
\begin{itemize}
\item	In a C-Shell (or a derivate) use
\begin{verbatim}
    setenv EPSOUTPUT 2gr8
\end{verbatim}
to set up EPS export for PS level 2, grayscaled output, run-length-compression
and ASCII-85-encoding. Most PS level 2 printers should be able to print this.
\item	In a Bourne-Shell (or a derivate) use
\begin{verbatim}
    EPSOUTPUT=3crf8
    export EPSOUTPUT
\end{verbatim}
to get PS level 3, colored output, run-length and flate compression
and ASCII-85-encoding. This will produce output suitable as input for
\texttt{ps2pdf}.
\item	On an DOS-prompt on Windows type
\begin{verbatim}
    set EPSOUTPUT=3crf8ams128,255,128
\end{verbatim}
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{verbatim}
    setenv EPSOUTPUT d
\end{verbatim}
to produce drafts only.
\end{itemize}

\subsection{Specifying dvips command line options}
If you have build a modified \texttt{dvips} you can overwrite
the information from \texttt{EPSOUTPUT} by command line options.\\*
Use \texttt{-I <option>} like
\begin{verbatim}
   dvips -I 2gr8 ...
\end{verbatim}
to specifiy EPS output options.
\clearpage
\subsection{Examples}
The \texttt{\textsc{Examples}} subdirectory contains some
PS files derived from the same \texttt{example.tex} file using
different \texttt{dvips} options.\\*
The picture \texttt{stefan\_255\_rgba.png} was obtained from
the\\*
\textsc{Miscellaneous~Transparent~PNGs~Using~Image~Tags} page
on the \texttt{libpng} homepage at\\*
\texttt{ftp://ftp.freesoftware.com/pub/png/index.html}. It was
provided courtesy of Stefan Schneider.

Some files (names start with \texttt{bg....}) have a page
background color.\\*
I recommend to use \texttt{gv} on \textsc{Unix} rather than \texttt{ghostview}
to view the examples. This package is available at\\*
\texttt{http://wwwthep.physik.uni-mainz.de/{\~{}}plass/gv/}.
It needs the \texttt{Xaw3d} library available at\\*
\texttt{ftp://ftp.x.org/contrib/widgets/Xaw3d/}.\\*
\begin{itemize}
\item	The file \texttt{1g.ps} was produced by:\\*
\begin{verbatim}
    latex example
    dvips -I 1g example
    mv example.ps 1g.ps
\end{verbatim}
It is a PS level 1 file containing a grayscaled picture.
\item	File \texttt{2g8r.ps} was produced using options \texttt{2g8r}
and contains the same grayscaled picture run-length-compressed
and ASCII-85-encoded.
\item	File \texttt{2c8r.ps} was produced using options \texttt{2c8r}
and contains a colored version of the picture, run-length-compressed
and ASCII-85-encoded.
\item	File \texttt{3c8rf.ps} was produced using options \texttt{3c8rf}.
Flate compressions was used additionaly.
\item	File \texttt{bg3c8rf.ps} was produced using options \texttt{3c8rf}.
It has a cyan page background.
\item	File \texttt{bg3c8rfa.ps} was produced using options \texttt{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 \texttt{0} opacity are skipped.
\item	File \texttt{bg3c8rfam.ps} was produced using options \texttt{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 PNG file \texttt{white}
background would be used.
\item	File \texttt{bg3c8rfams0\_255\_255.ps} was produced using
options \texttt{3c8rfams0,255,255}.
The pixel colors are calculated from the foreground color specified
in the file and the background color \texttt{cyan} (specified as
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 \texttt{libbmeps}' output:
\begin{itemize}
\item	Provide a configuration string using\\*
\begin{verbatim}
    void bmeps_cfg(char *cs);
\end{verbatim}
The configuration string \texttt{cs} corresponds to the
\texttt{EPSOUTPUT} environment variable.
\item	Manual configuration.\\*
To do so we need some variables:
\begin{verbatim}
  int pslevel, colored, enc_a85, enc_rl, enc_fl,
  is_draft, alpha, trans, altrig, mix, spec,
  bg_red, bg_green, bg_blue;
\end{verbatim}
We retrieve the current settings:
\begin{verbatim}
  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();
\end{verbatim}
\item	After processing configuration files and command line
arguments we need to write the changed variables back into \texttt{libbmeps}:
\begin{verbatim}
  bmeps_setup(
    pslevel, colored, enc_a85, enc_rl, enc_fl,
    is_draft, alpha, trans, altrig, mix, spec,
    bg_red, bg_green, bg_blue
  );
\end{verbatim}
\end{itemize}

\subsubsection{Checking support for a given filename}
The function
\begin{verbatim}
  int bmeps_can_handle(char *name);
\end{verbatim}
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 \texttt{0} if the file
can be converted, \texttt{0} if not.
\clearpage
\subsubsection{Writing an image}
Here is a simple example how to write an image.\\*
For a detailed example covering transparency... look into \texttt{pngeps.ctr}.
\begin{verbatim}
  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{verbatim}

\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}

