% OpenCP Module Player
%
% Documentation LaTeX source
%
% revision history: (please note changes here)
% -tmb990413  Felix Domke
%   -initial release

\chapter{W\"urfelAnimator WAP}
\label{wap}
This chapter is written by Felix Domke, the author of WAP.

\section{What is the so called W\"urfelMode?}
In version 1.0 of the famous Cubic Player, pascal got a nice idea of playing
silly animations inside the Player.

He invented the \emph{W\"urfelMode} (\emph{W\"urfel} is the german word for
cube). The W\"urfelMode was able to play animations with a resolution of
160x100 pixels in 256 colors in a special tweaked vga-mode. The animation
format was a special one.
 
\section{How can I create such animations by myself?}

Long time, only the cubic team (or even only pascal?) itself was able to
create such animations. The reason for this was that, as said, the animations
had to be in a very special format, and the only tool that was be able to
create this format were the not-so-famous \emph{W\"urfelTools}. Included
there was a tool called \texttt{makedmp.exe}. It  took  various \texttt{.tga}
files, and made a \texttt{.dat} animation out of them. But noone checked how
this tools worked, mainly because it had no command-line-help and the sources
weren't available anymore. 
 
But times are changing. Today, you don't have to guess how to use a utility 
anymore. You just have to read the documentation (yes, even you, Realtime ;).
Today, you can even use a resolution of 320x200 (wow, THAT's highres). 
 
For people who didn't guess how pascal's tool worked, I made a new one.
This time \emph{with} source available to all interested people. This time
with \texttt{.pcx} images, not \emph{.tga} one, because \texttt{.pcx} is much
easier to read, and also more widely supported. This time even with some
palette-aligning, so you don't have to care about same palettes anymore.
 
\section{And how can I use your tool?}
First, you have to render/paint/rip a animation. It HAS to be 320x200, or,
if you want to make an old, $<$ \cp\ 2.0q, animation, 160x100.
In case you didn't notice, the \cp\ 2.0q and higher has a new W\"urfelMode,
called \emph{W\"urfelMode \texttt{][}} , with support for 320x200 pixels
images, instead of the lowres 160x100 ones.

Your  animation should be in the form of many, many \texttt{.pcx} files,
called for example \texttt{PIC000.PCX}, \texttt{PIC001.PCX},
\texttt{PIC002.PCX} and so on. They  must have only 256 colors, and they
should have all the same palette. If  they don't have the same palette, the
palette will be aligned. But my calculation of this isn't very good (but it
works :), so for BEST results you have to do this in your favourite
picture-editing-program. Next,  you have  to create  a \emph{script}. This
script contains informations about the filenames of your frames, and a some
other stuff.
 
The script has the following format: 
\begin{verbatim} 
Version 
[SFO] RLECompression 
Title 
NumFrames Delay Filename 
[NumFrames Delay Filename] 
[NumFrames Delay Filename] 
[...                     ] 
\end{verbatim} 

\begin{description}
\item[Version] is either 0 or 1, 0 for 160x100 animations, 1 for 320x200.
If you want to create a Version 0-animation, \emph{SFO} should be set to 1,
if you want to create a Version 1-animtion, \emph{SFO} has to be left out.
\footnote{If  you're interested what  this value means, well, just get the
original documentation for professionals, it's described there}
\item[RLECompression] should be set to 1, it compresses the Animation a little
bit.
\item[Title] is the title of the animation, it shouldn't be longer than 31
chars, it's displayed inside the fileselector of \cp.
\end{description}

After this \emph{header}, a random number of section follows (but at least 
ONE ;). 

Every section describes a sequence of some PCXs. In the final animation,
all sections are joint together.
\begin{description}
\item[NumFrames] is the number of frames in this sequence. For example, if
you have PCXs that are named from \texttt{PIC000.PCX} up to
\texttt{PIC199.PCX}, NumFrames should be 200. 
\item[Delay] is handled a little bit different in the two versions. If you
want to create a Version 0-animation, a \emph{Delay} of 1 means a framerate
of about 21.3 frames per second, a \emph{Delay} of 2 is about 10.65 fps (the
half), a \emph{Delay} of 3 is about 7.1 (a third) and so on.

If  you  want  to create a Version 1-animation, \emph{Delay} is 65536/desired
fps, so if you want to have 15fps, "Delay" should be 4369. This value has to
be BELOW 65536 (and above 0, of course :)
\item[Filename] is the filename of your sequence. Because most animations 
have more than 1 frame, you can use \%d (and other C-printf placeholders).
For people whose native language is not C, here some short examples: \\
\begin{tabular}{lll} 
filename      &  framenumber  &   real filename \\
pic\%d.pcx    &  0            &   pic0.pcx      \\
              &  1            &   pic1.pcx      \\
              &  2            &   pic2.pcx      \\
              &  3            &   pic3.pcx      \\
              &  9            &   pic9.pcx      \\
              &  10           &   pic10.pcx     \\
              &  11           &   pic11.pcx     \\
pic\%03d.pcx  &  0            &   pic000.pcx    \\
              &  1            &   pic001.pcx    \\
              &  2            &   pic002.pcx    \\
              &  3            &   pic003.pcx    \\
              &  9            &   pic009.pcx    \\
              &  10           &   pic010.pcx    \\
              &  11           &   pic011.pcx    \\
\end{tabular} \\
The framenumber always starts with 0, not with 1, keep this in mind! 
\end{description} 
Here is an example script: (version 0) 
\begin{verbatim} 
0 
1 1 
a basic cubic-player animation 
11 2 intro%d.pcx 
200 1 ani%03d.pcx 
\end{verbatim} 
This animation would have 211 frames (\texttt{intro0.pcx} to
\texttt{intro10.pcx}, then \texttt{ani000.pcx} to \texttt{ani199.pcx}). 
 
And here again one for version 1: 
\begin{verbatim} 
1 
1 
an enhanced OpenCP animation 
11 3072 intro%x.pcx 
200 1000 ani%03d.pcx 
\end{verbatim} 

To create the animation, just type in \\
\texttt{wap <scriptfilename.scr> <outputfilename.dat>} \\
and hit \keys{Enter}. 
 
The W\"urfelAnimator will now try to make the animation. 
To view the animation inside \cp, rename the created \texttt{.dat}-file
to \texttt{cpani001.dat} (or \texttt{cpani002.dat} and so on...) and press
\keys{w} inside the player. 
 
\section{This tool doesn't work!}
No problem,I have always an open ear for your problems. Just write your
problems to \textbf{\htmladdnormallink{tmbinc@gmx.net}{mailto:tmbinc@gmx.net}}.

Maybe you have luck and meet me on IRC, usually I am in \texttt{\#coders.ger}
and some other channels, but if you don't know those, well, maybe you're
not welcome on them ;) 
 
Anyway, maybe you have some fun with this tool.
