//TexC// (//Doomsday Texture Compiler//) is a tool written by  in 2002.


====== What is TexC? ======


TexC, or the Doomsday Texture Compiler, is a program that can generate
the [[pnames]], [[texture1]] and [[texture2]] data from a texture definition
source file. Texture sources (TX files) define a number of textures in
the DOOM engine format, which means each texture is composed of one or
more patches. TexC is also capable of reading existing texture data
from a WAD file and producing a TX file out of it.

You will need TexC if you want to edit the existing textures or add
your own ones. For instance, a map author can add any number of new
textures by editing a TX source and then adding the compiled PNAMES
and TEXTURE1/2 lumps into the map's WAD.

Note that some map editors (e.g. [[dee_psea]]) have an option to edit the
texture data. When using such an editor, TexC is rendered somewhat
useless. But due to the TX source files, managing different sets of
textures is easy. Just compile the ones you need (combining different
source files is simple) and use the produced texture data in your map.


====== Textures in the Doomsday Engine ======


Each texture has a name, the length of which is at most eight
characters. The name of the texture is an identifier, used in a map
editor to assign the texture to a given sidedef. In the Doomsday
engine, no restrictions are placed on the width and height of the
textures. It is perfectly legal to define textures with, for example,
the size 320x264.

Each texture is composed of one or more patches. A patch is a picture
in the normal Doom graphics format, the same one that is used with
sprites, for instance.

It is important to note that the PNAMES and TEXTURE1/2 lumps only
contain texture definitions. The actual graphics are in separate data
lumps, the names of which are listed in PNAMES.


====== Invoking the compiler ======


Texture definition source files have the extension ".TX".

When compiling, TexC produces the files PNAMES.LMP, TEXTURE1.LMP and
TEXTURE2.LMP into the current directory.

Compiling a single source file:

<code>texc myfile.tx
</code>
Note that the .TX extension can be omitted.

Compiling multiple source files with combined output:

<code>texc myfile1 myfile2 myfile3
</code>
Any number of source files can be combined this way. If some of the
sources define textures with the same name, the latest definition will
override the earlier ones.

Extracting a TX source out of a WAD file that contains PNAMES and
TEXTURE1/2 lumps:

<code>texc -i some.wad output.tx
</code>
The given WAD file will be searched for texture data and if it is
found, a TX source with the specified name will be created. This time
you can't omit the .TX extension.

The PNAMES and TEXTURE1/2 lumps contain some obsolete information that
is currently ignored. If you want to include that when extracting
texture data from a WAD file, use the -f option. It stands for 'full
import' mode. Keywords representing the obsolete data will be added to
the output TX file.


====== Texture source syntax ======


Comments begin with a hash character (#) and continue to the end of
the line. Another way to mark comments is to begin the comment with a #> symbol and end it with a <#.

Everything in a TX file is case insensitive.

A formal description of the syntax follows (comments aren't included
since they're just skipped):
  
  Tx-Source           := Statement*
  
  Statement           := Keyword-Statement | Texture-Statement
  
  Keyword-Statement   := S* "%" S* (Syntax | Group) S 
  
  S                   := " " | "\t" | "\n"
  
  Syntax              := "syntax" S  "simple"
  
  Group               := "group" S  ("1" | "2")
  
  Texture-Statement   := S* Name Texture-Property* Patch* S* ";"
  
  Name                := ("A"..."Z" | "0"..."9" | "-" | "_"){1,8}
  
      (Most other characters are allowed as well, but only these should
      be used. You'll get a warning if you try to use textures with very
      short names.)
  
  Texture-Property    := S  (Vector | Flag | Misc)
  
      (The vector defines the size of the texture.)
  
  Vector              := Integer S* "," S* Integer
  
  Integer             := Hexadecimal-Integer | Signed-Integer
  
  Flag                := "masked" | "flags" S  Integer
  
  Misc                := "misc" S  Integer
  
  Patch               := S* "@" S* Name Patch-Property*
  
  Patch-Property      := S  (Vector | Argument1 | Argument2)
  
  Argument1           := "arg1" S  Integer
  
  Argument2           := "arg2" S  Integer


An example of this syntax:

<code>
    %Group 2

    FIREWALL 128,64         # Size of the texture.
        @ FIRE01 0,96       # Patch offset (bogus).
        @ FIRE02 0,0
    ;
</code>


====== Example: Creating a new texture ======


Let's say you are working on a Doom II map and you want to add some
textures of your own. You've drawn two patches, GRITTY1 and BLDSHOT,
and they have been added to the PWAD that contains your map. Now you
want to create a texture called MESSY_1 that is composed of the two
patches.


===== Step 1 =====

The first thing you need is the texture definitions of Doom II.
Extract them with the command:

<code>texc -i \my-doom2-dir\doom2.wad doom2.tx
</code>
Now the texture definitions of Doom II have been written into the
file doom2.tx.


===== Step 2 =====

Let's create a new TX source for the new texture. You could just
append your new definition into doom2.tx, but if you don't modify
doom2.tx you can easily use it with other projects/maps as well.

Using a text editor (e.g. Notepad) create a file called my.tx.
Below are the contents of the file:

<code>MESSY_1 64,128
    @ BLDSHOT 0,64
    @ GRITTY1;
</code>
This defines a texture called MESSY_1. The texture is 64 pixels
wide and 128 pixels tall. It is composed of two patches: BLDSHOT
has its left upper corner at (0,64) and GRITTY1 at (0,0). We
assume the patches are both 64x64 in size.


===== Step 3 =====

Now we can compile the textures back into binary data. This is
done with the command:

<code>texc doom2 my
</code>
This will compile the sources doom2.tx and my.tx and generate the
files PNAMES.LMP and TEXTURE1.LMP. The names of your patches were
inserted in PNAMES and the texture itself in TEXTURE1. Since Doom
II doesn't use a secondary texture group, TEXTURE2.LMP won't be
generated.


===== Step 4 =====

Insert the generated PNAMES.LMP and TEXTURE1.LMP into your map's
PWAD.


====== Source code ======

TexC source code is available from the deng [[git_repository]], under GPL.