
DXTool 1.42

1. WHAT IS DXTOOL

DXTool is a DX:IW Ini file tweaker and resource im- and exporter. It works
for Thief 3 Deadly Shadows as well. For more information regarding Deus Ex 
or Thief 3, see www.ionstorm.com

2. WHATS NEW

The following features were added 

* Fixed: Transparency now maps correctly again to texture. Thanks to
  william for kindly providing some test cases.
* Fixed: When accessing the same resource multiple times, it is now only
  added onde to the history list.
* Fixed: Texture now loads in preview area when using the history list
  to navigate.

Since 1.41

* Fixed: Deus Ex tweaker did not initialize correctly. I had to reinstall
  Deus Ex 2 to fix it :-)

Since 1.40

* Added support for Thief 3 - Deadly Shadows. Note that DXTool is not a 
  tweaker for Thief 3 but only a texture viewer / exporter / importer.
* Added scrolling through textures with cursor keys

Since 1.35

* Fixed bug that always required _alpha image to be present
* Fixed handling of MIP maps. When you import a texture in DXTool, mip maps
  are automatically generated for your newly created textures.

Since 1.30

* Support for MIP map levels 
* History button is now properly working. It remembers the last items you
  have changed and will allow to quickly find this item in the resource list.
* Support for alpha layers. Alpha layers can be viewed separately in DXTool by
  pressing the View Alpha toggle
* DXTool remembers the last path used for im- and exporting
* Right mouse button saves resource names to the clipboard
* Support for batch importing of textures

For supporting alpha layers, I had to do a rewrite / extend most of the code.
My sincere apologies if you find a bug. Contact me to have it resolved :)
  
3. SUPPORT FOR ALPHA LAYERS

When exporting, DXTool now saves the alpha layer of textures as a separate 
bitmap. When saving dx_font2.bmp for example, a file dx_font2_alpha.bmp is saved
to the same folder

When importing dx_font2.bmp again, DXTool looks inside the same folder to see
if it can find a dx_font2_alpha.bmp and merge that image onto the texture alpha
layer.
  
4. USING THE BATCH IMPORT FEATURE

Batch import is a feature that makes it possible to import a lot of textures
at once, without having to fiddle to import every texture manually.

TIP: You can open the dximport.xml inside the "sampleimport" folder in the folder
     where you installed DXTool. The files do not change anything, they are 
     unchanged resources.

4.1 HOW DOES BATCH IMPORT WORK

In DXTool, you can see a button "Batch Import" on the resources tab. When you
click this will see DXTool asking for an import file. This file is a plain text file
that describes the textures you want imported and in which resources files you
want to import them in. These files are named dxtool.xml.

You can open a dxtool.xml file in any text editor such as Notepad or UltraEdit
or whatever tool you fancy. Just do not use a program like Microsoft Word, since
these will add graphic formatting options to the file, which is not what you want.

It is possible to modify a resource such as "dx_font" and using a dximport.xml
file to import them in all the resource files that are appropriate in one go.

4.2 WHATS THE CATCH

The only catch is that you, at this time, will have to edit your dximport.xml
file manually. There might be some form of automatic generation in a next version
of DXTool.

But do not worry, the dximport.xml fileformat is pretty elementary and there is
an example provided with the installation of DXTool.

4.3 DISTRIBUTION OF 'TEXTURE PACKS'

When you have created a masterpiece and want to distribute it for DXTool import,
read on.

Your texture pack should consist of
* Your modified textures exported from DXTool
* A dximport.xml file in

The best way to go is to create a folder, called MyTextures for example. Then
extract and edit the textures with DXTool as you please in subfolders. What I 
do myself is to create a subfolder for each resource file to keep things 
orderly.

Create a dximport.xml in the root to describe which textures are to be imported
and where they can be located -in relation to the dximport.xml file-.

Your folder structure would look something like this:

...\MyTextures\dximport.xml
...\MyTextures\Kernel_GFXALL\inv_spider_bomb.bmp
...\MyTextures\Kernel_GFXALL\inv_spider_bomb_alpha.bmp
...\MyTextures\Kernel_GFXALL\inv_ballistic_pistol.bmp
...\MyTextures\Kernel_GFXALL\inv_ballistic_pistol_alpha.bmp
...\MyTextures\m1_club\m1hub-clubvox_decalsign1.bmp
...\MyTextures\m1_club\m1hub-clubvox_decalsign1_alpha.bmp

Then when you're ready editing, grab your favorite archive program like WinZip,
RAR, TAR, ACE, or whatever and compress the MyTextures folder. Make sure you
include folder information so that when the end-user extracts it to a temporary
directory, the dximport.xml structure is still valid (ie: all files are where
they should be)

4.4 BATCH IMPORT FILE FORMAT 

The batch import files DXTool uses are called dximport.xml. Here's an example I
made earlier:

We will go through this step by step. You might notice there are several 'levels'
of information:
* Root: The description of the file and what type it is
*   The resource files that should be adjusted
*     The textures that should be imported therein

There are some basic considerations when writing an dximport.xml file:
* All tags like <data> should be in lowercase
* All opening tags <data> should be closed by a matching close tag like </data>
* Attribute values like name in <ibdfile name=" "> need to be enclosed in 
  double quotes (")

<?xml version="1.0"?>
<dximport version="1.3">
  
  ; This is a comment line
  ; Below is the resource file Kernel_GFXALL
  <ibdfile name="Kernel_GFXALL">
    
    <resource type="texture" name="inv_boltcaster">
      <imagename>inv_boltcaster.bmp</imagename>
      <alphaname>inv_boltcaster_alpha.bmp</alphaname>
    </resource>
    
    <resource type="texture" name="player_alexdfem02">
      <imagename>player_alexdfem02.bmp</imagename>
      <alphaname>player_alexdfem02_alpha.bmp</alphaname>
    </resource>
    
  </ibdfile>
  
  ; Comment
  <ibdfile name="m1_acorp_lab">
    
    <resource type="texture" name="fo_ficus">
      <imagename>ficus\fo_ficus.bmp</imagename>
      <alphaname>ficus\fo_ficus_alpha.bmp</alphaname>
    </resource>
        
  </ibdfile>
  
</dximport>

4.5 ADDING COMMENTS

You can place as much comments in a file as you see fit. Each comment needs 
to start with a semicolon (;). All characters after that are considered belonging to
a comment.

4.6 OPENING OF THE FILE / DESCRIPTION

The two lines are mandatory. They tell the parser that this is an XML document
and that it contains DXTool information <dximport>

<?xml version="1.0"?>
<dximport version="1.3">

Note that the file is closed on the last line with a </dximport> tag telling
the parser there are no other resources to be processed beyond that point.

4.7 IBD FILE SPECIFIER

In order to tell DXTool we want to modify a resource file, the first thing DXTool
must know is which resource file to modify. We specify this with the <ibdfile> tag.

The <ibdfile> tag has an required attribute called name. Here name specifies the
exact filename of the ibd file in the Deus Ex 2 Maps folder. 

Inside the ibd files we list resources to import, and then closing off the <ibdfile>
tag with </ibdfile> telling the parser that no further resources need to be imported
in that file.

So taking into account all that we have handled so far we would have a basic file like
this:

<?xml version="1.0"?>
<dximport version="1.3">
  
  <ibdfile name="Kernel_GFXALL">
    
  </ibdfile>

</dximport>

Only problem is that this by itself does not do much, without telling DXTool what 
textures to import in the Kernel_GFXALL ibd file.

TIP: You do not need to manually copy the name of each resourcr file when composing
an import file. You can press right mouse button on the drop down list and copy the
resource filename to the clipboard. Use CTRL-V (paste) in your editor to paste.

4.8 IMPORTING A TEXTURE TO AN IBD FILE

To import a texture, we build upon the syntax handled so far and introduce the 
<resource> tag. The <resource> tag has two attributes:
* type: can only be "texture" for now. May be extended in the future.
* name: the name of the resource we want to overwrite. This is the name as it appears
        in the resource list in DXTool under 'Resource name'.
        
TIP: You can easily get the resource name by right clicking the resource list and
     copy the name to the clipboard. Then use CTRL-V in your favorite editor.
     
The resource tag is as usual closed by </resource> but between the opening and close
tags we can specify the image information (or bitmap) to import. 

If you look at the example we can see the <imagename> and <alphaname> tags.

Between <imagename> and </imagename> we can specify the bitmap file name of the image
to import. For example mytexture.bmp. If you have put your images in subfolders 
(subdirectories) in relation to the dximport.xml file then you can specify the
relative path for the image as follows 

<imagename>myfolder\mytextures\atexture.bmp</imagename>

The tag <alphaname> works in pretty much the same way, also referring to an image
file that can be inside a subdirectory. The alpha image however, should be a greyscale
image where black indicates fully transparent and white indicates non-transparent
pixels.

NOTE: When you export a texture from DXTool 1.30, the alpha image is saved 
      as a separate image with extension _alpha. DXTool looks for this extension when
      importing images (ie. automatically searches for dx_font2_alpha.bmp when you try
      to import dx_font2.bmp)

NOTE: You cannot at this time import a texture that is larger in dimensions than
      the original resource.
      
4.9 THAT ABOUT WRAPS IT UP

This is pretty much a 101 on dximport.xml editing. You can find an example of
an import file inside the folder where you installed DXTool.

5. FAQ

5.1 Can I import larger textures than the ones saved by DXTool

 - Theoretically this is possible although you cannot do so in the current release of
   DXTool. I still need to find out for myself if this works. If it does, you might see
   it in a future version.
   
5.2 I cannot import 24 bit textures only 256 color ones

  - This will probably be to blame on your image editor. Try saving it out as BMP plain
    vanilla (no RLE compression etc.). Or see if you can save it as DIB format.
    
    Trust me that DXTool saves out 24 bit textures. If you reimport 256 color ones, DXTool
    converts it internally to 24 bit but since you have downscaled colors in your image
    editor, you are bound to lose texture quality.
    
    TIP: Personally I use Paint Shop Pro and it works flawlessly. MS Paint works as well 
         but is -somewhat- limited.
    
5.3 Why does DXTool save BMP files and not JPG

  - BMP is a lossless format. JPG loses image information in the compression cycle although
    you can minimize this and choose for maximum compression.

5.4 I cannot open the exported BMP with Photoshop
  
  - This is probably due to a photoshop BMP reader limitation. If you first open it in 
    MS Paint and then save it out again or Copy / Paste it from there it works. It is also
    proven to work directly in Paint Shop Pro.
    
6. THE AUTHOR
 
You can always mail me at invoke41@yahoo.com if you have questions. If you want to
offer me a job then im all ears *big grin* 