More format
authorecalot <ecalot>
Fri, 11 Jan 2008 19:45:20 +0000 (19:45 +0000)
committerecalot <ecalot>
Fri, 11 Jan 2008 19:45:20 +0000 (19:45 +0000)
FP/doc/FormatSpecifications.tex

index 1fea337192e5bea4c588e338815db765755e6068..a38a3d998fd274f4c7bc0614a5e17141527fc856 100644 (file)
 \tableline{\gamma+6}{2}{US}{Size(i)\footnotemark[3]  }{Size of the item not including the checksum byte}
 }{DAT file blocks}{file blocks}
 
-%todo cross reference in table
-
 % The \index{DAT} DAT header: Size = 6 bytes
 %  - Offset 0, size 4, type UL: IndexOffset
 %           (the location where the index begins)
 
  ImageMask is a set of bits where:
 \begin{itemize}
-\item  the first 8 are zeros
-\item  the next 4 are the resolution\\
+\item[$\diamond$] the first 8 are zeros
+\item[$\diamond$] the next 4 are the resolution\\
    so if it is 1011 (B in hex) then the image has 16 colours;
    and if it is 0000 (0 in hex) then the image has 2 colours.
    To calculate the bits per pixel there are in the image, just take the
    last 2 bits and add 1. e. g. 11 is 4 ($2^4=16$ colours) and 00 is 1 ($2^1=2$ colours).
-\item  the last 4 bits are the 5 compression types (from 0 to 4) as specified in Table~\ref{algorithm codes}.
+\item[$\diamond$] the last 4 bits are the 5 compression types (from 0 to 4) as specified in Table~\ref{algorithm codes}.
 \end{itemize}
 
 \renewcommand{\tabcolsep}{1em}
  Definition: ``print'' means to commit a byte into the current location
              of the output stream.\\
 
-%{\tt
- The output stream is a slide window initialised with zeros.
- The first byte of the input stream is a maskbyte.
- For each of the 8 bits in the maskbyte the next actions must be performed:
-  If the bit is 1 print the next unread byte to the slide window
+{\tt
+ The output stream is a slide window initialised with zeros.\\
+ The first byte of the input stream is a maskbyte.\\
+ For each of the 8 bits in the maskbyte the next actions must be performed:\\
+  If the bit is 1 print the next unread byte to the slide window\\
   If the bit is a zero read the next two bytes as control bytes with the
-  following format (RRRRRRSS SSSSSSSS):
+  following format (RRRRRRSS SSSSSSSS):\\
 \begin{itemize}
-\item 6  bits for the copy size number ($R$). Add 3 to this number.\\
+\item[$\cdot$] 6  bits for the copy size number ($R$). Add 3 to this number.\\
         Range: $2$ to $2^6+2=66$
-\item 10 bits for the slide position ($S$). Add 66 to this number.\\
+\item[$\cdot$] 10 bits for the slide position ($S$). Add 66 to this number.\\
         Range: $2^6+2=66$ to $2^6+2+2^{10}=1090$
 \end{itemize}
    Then print in the slide window the next $R$ bytes that are the same slide
-   window starting with the $S^{th}$ byte.
-
+   window starting with the $S^{th}$ byte.\\
+}
  After all the maskbyte is read and processed, the following input byte is
  another maskbyte. Use the same procedure to finish decompressing the file.
  Remaining unused maskbits should be zeros to validate the file.
 
 \pagebreak[2]
  The cga\_patterns block stores 16 records of one byte each, separated in
- four parts, so the format is aabbccdd where aa is a two bit colour in one
+ four parts, so the format is $a_0 a_1 b_0 b_1 c_0 c_1 d_0 d_1$ where aa is a two bit colour in one
  of the two CGA palettes (palette 1 is normally used in the \index{dungeon!environment} dungeon
  environment and 2 in the palace environment).
  
  The pattern is arranged in a 2x2 box and each pixel is denoted:
-  aa bb
-  cc dd
+\begin{center}
+\begin{tabular}{c|c}
+  $a_0 a_1$ & $b_0 b_1$\\
+  \hline
+  $c_0 c_1$ & $d_0 d_1$\\
+\end{tabular}
+\end{center}
  
  So for example if the entry 1 is 00101000 (0x28) in mode CGA2, the pattern
  will be a checkerboard of black and green like the following:
 \begin{tabular}{cc|cc|cc}
   \multicolumn{2}{c}{Bin} & \multicolumn{2}{c}{Dec} & \multicolumn{2}{c}{Colour} \\
  \hline
-  00& 01&    0& 1&    black&  green \\
-  01& 00&    1& 0&    green&  black \\
+  00 & 01  &    0 & 1 &    black &  green \\
+  01 & 00  &    1 & 0 &    green &  black \\
 \end{tabular}
 \end{center}
 
 \begin{tabular}{cc|cc|cc|cc}
   \multicolumn{2}{c}{Bin} & \multicolumn{2}{c}{Dec} & \multicolumn{2}{c}{Hex} & \multicolumn{2}{c}{Colour} \\
  \hline
-  0010& 1111  &  2 & 15  &2&f&  brown&  white\\
-  1111& 0010  &  15& 2   &f&2&  white&  brown\\
+  0010 & 1111  &  2  & 15  & 2 & f &  brown &  white\\
+  1111 & 0010  &  15 & 2   & f & 2 &  white &  brown\\
 \end{tabular}
 \end{center}
 
@@ -684,8 +687,8 @@ Hex-editing the uncompressed version. To do that, read the Hex editing documenta
  chomp & 0x03 & Partially Open \\
  chomp & 0x04 & Extra Open \\
  chomp & 0x05 & Stuck Open \\
-% wall  & 0x00 & Normal\footnotemark[1], Blue line\footnotemark[2] \\
-% wall  & 0x01 & Normal\footnotemark[1], No Blue line\footnotemark[2] \\
+ wall  & 0x00 & Normal\footnotemark[1], Blue line\footnotemark[2] \\
+ wall  & 0x01 & Normal\footnotemark[1], No Blue line\footnotemark[2] \\
 \hline
 
 \caption{Background modifiers by group}
@@ -776,8 +779,8 @@ Hex-editing the uncompressed version. To do that, read the Hex editing documenta
  Field      & \multicolumn{20}{c}{Values} \\
   \hline
  \endfirsthead
- position&        1&2&3&4&5&6&7&8&9&10&11&12&13&14&15&16&17&18&19&20 \\
- offsets&        5&4&3&3&1&5&4&2&1& 1& 5& 3& 2& 1& 5& 4& 3& 2& 5& 4 \\
+ position  &     1&2&3&4&5&6&7&8&9&10&11&12&13&14&15&16&17&18&19&20 \\
+ offsets   &     5&4&3&3&1&5&4&2&1& 1& 5& 3& 2& 1& 5& 4& 3& 2& 5& 4 \\
  separator size& 0&1&1&0&0&0&1&1&0& 0& 1& 1& 1& 0& 0& 1& 1& 1& 0& 0 \\
 \hline
 \caption{First 20 seed values of the second row separator}
@@ -943,7 +946,7 @@ Code & Pants    & Cape \\
 \subsection{Internal PC Speaker}
 
 \offsettable{}{
-0 & 3 & $\downarrow$ & $Header: /home/rodrigo/src/repo-FP/cvsroot/freeprince/FP/doc/FormatSpecifications.tex,v 1.83 2008-01-05 00:26:45 ecalot Exp $ & The file header \\
+0 & 3 & $\downarrow$ & $ Header $ & The file header \\
 \hline
 0 & 2 & UC & $Junk$ & 0x00 (or 0x80 sometimes) \\
 2 & 1 & US & $bps$ & Beats per two seconds \\
@@ -1022,14 +1025,19 @@ $3i+2$ & 1 & US & $length$ & length in beats \\
  We will use the same conventions than in the prior chapter.
  The checksum validations are still the same.
 
- High data structures:
+\offsettable{}{
+0 & 6 & $\downarrow$ & $ Header $ & The file header \\
+\hline
+0 & 4 & UL & $HighDataOffset$ & The location where the highData begins \\
+4 & 2 & US & $HighDataSize$ & the number of bytes the highData has \\
+}{High data structures}{hds}
 
- The DAT header: Size = 6 bytes
-  - Offset 0, size 4, type UL: HighDataOffset
-           (the location where the highData begins)
-  - Offset 4, size 2, type US: HighDataSize
-           (the number of bytes the highData has)
-           Note that $HighDataOffset+HighDataSize=file size$
+% The DAT header: Size = 6 bytes
+%  - Offset 0, size 4, type UL: HighDataOffset
+%           (the location where the highData begins)
+%  - Offset 4, size 2, type US: HighDataSize
+%           (the number of bytes the highData has)
+%           Note that $HighDataOffset+HighDataSize=file size$
 
  This is similar to DAT v1.0 format, except that the index area is now
  called high data.
@@ -1040,18 +1048,38 @@ $3i+2$ & 1 & US & $length$ & length in beats \\
  Slave indexes are the real file contents index.
 
 \subsubsection{The master index} %4.1.1
- The master index is made with:
-  - Offset $HighDataOffset$,   size 2, type US: NumberOfSlaveIndexes
-           (the number of the high data sections)
-  - Offset $HighDataOffset+2$, size $NumberOfSlaveIndexes*6$: The master index
+
+\offsettable{}{
+\tableline{HighDataOffset}{HighDataSize}{$\downarrow$}{Footer}{The DAT index}
+\hline
+\tableline{0}{2}{US}{NumberOfSlaveIndexes}{the number of the high data sections}
+\tableline{2}{$NumberOfSlaveIndexes*6$}{$\downarrow$}{MIRecords}{The master index
            record (a list of NumberOfSlaveIndexes blocks of 6-bytes-length
-           index record each corresponding to one slave index)
+           index record each corresponding to one slave index}
+\hline
+\hline
+\tableline{0}{6}{$\downarrow$}{MIRecord}{The DAT index}
+\hline
+\tableline{0}{4}{text}{SID}{4 ASCII bytes string denoting
+           the Slave Index ID. The character order is inverted.}
+\tableline{4}{2}{US}{SlaveIndexOffset}{slave index offset relative to $HighDataOffset$}
+\hline
+\hline
+}{DAT 2.0 Master index}{mi}
 
- The 6-bytes-length index record (one per item): Size = 6 bytes
-  - Relative offset 0, size 4, type sting: 4 ASCII bytes string denoting
-           the Slave Index ID. The character order is inverted.
-  - Relative offset 4, size 2, type US: $SlaveIndexOffset$
-           (slave index offset relative to HighDataOffset)
+%  - Offset $HighDataOffset$,   size 2, type US: NumberOfSlaveIndexes
+%           (the number of the high data sections)
+%  - Offset $HighDataOffset+2$, size $NumberOfSlaveIndexes*6$: The master index
+%           record (a list of NumberOfSlaveIndexes blocks of 6-bytes-length
+%           index record each corresponding to one slave index)
+
+% The 6-bytes-length index record (one per item): Size = 6 bytes
+%  - Relative offset 0, size 4, type sting: 4 ASCII bytes string denoting
+%           the Slave Index ID. The character order is inverted.
+%  - Relative offset 4, size 2, type US: $SlaveIndexOffset$
+%           (slave index offset relative to HighDataOffset)
+
+}{DAT 2.0 Master index}{mi blocks}
 
  From the end of the \index{Index!Master} DAT High Data Master Index to the end of the file
  we will find the High Data section contents (where the HighDataOffset
@@ -1116,9 +1144,13 @@ $3i+2$ & 1 & US & $length$ & length in beats \\
            (in ``shap'' indexes it is always 0x40 0x00 0x00;
            in others 0x00 0x00 0x00)
 
+%todo
+
  Finally, we can locate whatever item we want if we have the
-  - Slave Index ID
-  - Item ID
+ \begin{itemize}
+ \item[--] Slave Index ID
+ \item[--] Item ID
+ \end{itemize}
  this is not a unique key, unfortunately we have found repeated pairs of
  IDs for different items, so we have to use the ``order'' as a third key.
 
@@ -1135,7 +1167,6 @@ $3i+2$ & 1 & US & $length$ & length in beats \\
 
  This table has a summary of the blocks to be used in this section.
 
-
 \offsettablee{}{
  960   & 0      & pop2\_foretable \\
  3840  & 960    & pop2\_backtable \\
@@ -1250,7 +1281,7 @@ $3i+2$ & 1 & US & $length$ & length in beats \\
  The second byte in a background mask is the attribute byte. For example
  0x18 modifies the tile 0x01 and adds two small stalactites.
  
- We believe the special images uses the 3rd or 4th byte.
+ We believe the special images uses the $3^{rd}$ or $4^{th}$ byte.
 
 \subsubsection{Door events \label{door events}} %4.2.2
  This section explains how doors are handled and specifies the block
@@ -1298,10 +1329,33 @@ $3i+2$ & 1 & US & $length$ & length in beats \\
  the room with this number, we will call them ``room guard blocks''.
  
  A room guard block has a size of 116 divided this way:
+
+\offsettable{}{
+0 & 116 & $\downarrow$ & $ Header $ & The file header \\
+\hline
+0 & 1 & UC & $HighDataOffset$ & number of guards present in this room.
+   This byte may take values from 0 to 5. \\
+$1+23i$ & 23 & $\downarrow$ & $SGBlock$ & 5 block divisions of 23 bytes for each guard.
+   The first divisions have the guard information, if the number is less
+   than 5, then the latest divisions corresponding to the missing guards
+   will be filled with zeros or garbage. \\
+\hline
+0 & 1 & UC & $a$ & the location in this room (same as explained in \ref{guard handling}) of the current guard. \\
+1 & 3 & SS & $a$ & offset in pixels to reallocate the guard in the floor. \\
+3 & 1 & UC & $a$ & the facing direction as specified in \ref{guard handling}. \\
+4 & 1 & UC & $a$ & the skill. \\
+5 & 1 & - & $a$ & unknown \\
+
+
+}{High data structures}{sg}
+
+
+%todo
+
 \begin{itemize}
-\item 1 byte for the number of guards present in this room.
+\item[$\diamond$] 1 byte for the number of guards present in this room.
    This byte may take values from 0 to 5.
-\item 5 block divisions of 23 bytes for each guard.
+\item[$\diamond$] 5 block divisions of 23 bytes for each guard.
    The first divisions have the guard information, if the number is less
    than 5, then the latest divisions corresponding to the missing guards
    will be filled with zeros or garbage.
@@ -1344,6 +1398,15 @@ $3i+2$ & 1 & US & $length$ & length in beats \\
  There is only one different type of dynamic guard per room, but it is
  possible to set the number of guards that will appear running.
  
+\offsettable{}{
+0 & 6 & $\downarrow$ & $ Header $ & The file header \\
+\hline
+0 & 4 & UL & $HighDataOffset$ & The location where the highData begins \\
+4 & 2 & US & $HighDataSize$ & the number of bytes the highData has \\
+}{High data structures}{hds}
+ A room guard block has a size of 116 divided this way:
+
+%todo
  The bytes are from 0 to 33:
  Bytes from 8 to 17 may take the value 0x5a and 0. Bytes 8,9,10,15,16 are
   always 0.
@@ -1453,7 +1516,7 @@ $3i+2$ & 1 & US & $length$ & length in beats \\
  military time: HH is a number from 00 to 23.
 
  If the month, day, hour or second have only one digit, the other digit
- must be completed with 0.
+ must be completed with 0.\\
  i.e. 2002-11-26 22:16:39
 
 \pagebreak[3]
@@ -1471,33 +1534,42 @@ $3i+2$ & 1 & US & $length$ & length in beats \\
  6&      2     & US  &iv& Current hit points           \\
 }{SAV blocks}{palettes table}
 
- Remaining minutes (i)
+\begin{description}
+\item[(i)] Remaining minutes\\
   Range values:
-   0     to 32766 for minutes
-   32767 to 65534 for NO TIME (but the time is stored)
-   65535 for game over
+  \begin{itemize}
+   \item 0     to 32766 for minutes
+   \item 32767 to 65534 for NO TIME (but the time is stored)
+   \item 65535 for game over
+  \end{itemize}
 
- Remaining ticks (ii)
+\item[(ii)] Remaining ticks \\
   Seconds are stored in ticks, a tick is $\frac{1}{12} seconds$. To get the time in
-  seconds you have to divide the integer ``Remaining ticks'' by 12.
+  seconds you have to divide the integer ``Remaining ticks'' by 12.\\
 
   Range values:
-   0.000 to 59.916 seconds
+  \begin{itemize}
+   \item 0.000 to 59.916 seconds \\
                    (rounded by units of $\approx 83 ms$ or $\frac{1}{12} seconds$)
-   0     to 719    ticks
+   \item 0     to 719    ticks
+  \end{itemize}
 
- Level (iii)
+\item[(iii)] Level \\
   Range values:
-   1  to 12 for normal levels
-   13 for 12bis
-   14 for princess level
-   15 for potion level
-
- Hit points (iv)
+  \begin{itemize}
+   \item 1  to 12 for normal levels
+   \item 13 for 12bis
+   \item 14 for princess level
+   \item 15 for potion level
+  \end{itemize}
+
+\item[(iv)] Hit points \\
   Range values:
-   0 for an immediate death
-   1 to 65535 hit points
-
+  \begin{itemize}
+   \item 0 for an immediate death
+   \item 1 to 65535 hit points
+  \end{itemize}
+\end{description}
 
 \section{HOF v1.0 Format Specifications}
 
@@ -1510,7 +1582,12 @@ $3i+2$ & 1 & US & $length$ & length in beats \\
  size of 29 bytes distributed according to the following table.
 
 \offsettable{}{
- 0 &     25     & text & & Player name                  \\
+ 0 & 2 & US & $ Records $ & Number of records \\
+\hline
+\hline
+ $2+29i$ & 29 & $\downarrow$ & $ Record $ & One score record \\
+\hline
+ 0  &     25    & text & & Player name                  \\
  25 &      2    & US \footnote[1]{similar to SAV format} & & Remaining minutes            \\
  27 &      2    & US \footnotemark[1] & & Remaining ticks              \\
 }{HOF blocks}{palettes table}
@@ -1556,8 +1633,7 @@ $3i+2$ & 1 & US & $length$ & length in beats \\
       under the terms of the GNU Free Documentation License, Version 1.2
       or any later version published by the Free Software Foundation;
       with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
-      Texts.  A copy of the license is included in the section entitled
-      "GNU Free Documentation License".
+      Texts.
 
 \section*{Indexes}
 \listoftables