TDM Material Batch Conversion

OBSOLETE INFO AS OF TDM 2.0 ENHANCED AMBIENT STAGES ARE NO LONGER NEEDED IN MATERIALS

Introduction

Some of the ambient rendering methods available in TDM require ambient stages in all the material definitions (see Virtual Ambient Light Textures). Since TDM 1.03, there are console commands that automatically converts materials to be compatible with all the ambient methods. tdm_batchConvertMaterials is used to convert batches of material files. tdm_convertMaterialsFromFile converts all materials in one .mtr file. tdm_convertMaterial converts one material within a file.

Converting a single material

To convert a single material use the command:

tdm_convertMaterial

Syntax: tdm_convertMaterial <mtr-name> [forceUpdate]

Usage: Converts specified material to support new ambient lighting. Supports auto-complete for material name. forceUpdate is an optional parameter, if provided, material with valid ambient blocks is forcefully updated again.

Converting a single file

To convert a single file use the command:

tdm_convertMaterialsFromFile

Syntax: tdm_convertMaterialsFromFile <mtr-filename> [forceUpdateAll]

Usage: Converts all materials from a specified file to support new ambient lighting. Supports auto-complete for filename. forceUpdateAll is an optional parameter, if provided, materials with valid ambient blocks are forcefully updated again.

Converting multiple files

The command tdm_batchConvertMaterials analyses a defined number of materials and alters them according to the requirements imposed by TDM 1.03. Its console explanation reads:

Usage: tdm_batchConvertMaterials <StartIndex> <nMaterials> [forceUpdateAll]

StartIndex is a number that defines at what material the command is supposed to start processing and nMaterials defines how many successive materials should be processed. TDM currently consists of about 9000+ materials, so one would probably go ahead and just run the command with the parameters: tdm_batchConvertMaterials 0 10000. The problem is that all materials are parsed into RAM which will eventually lead to malloc errors, when the RAM is full.

If forceUpdateAll is also set, the command will update all materials, independent of the results of the analysis.

The results of the command are stored in the folder of the currently installed FM, e.g. .../Doom3/thiefs_den/materials, or in .../Doom3/darkmod/materials if no FM is installed. And in case you wonder, the materials don't need to be extracted from the pk4 archives prior to processing.

Proper usage of the command

In order to run the command without running into malloc errors, one has to successively execute it on different partitions of the materials. If you choose nMaterials=1000 (which appears to be a good value), you'll have to start the command multiple times while increasing the StartIndex and restarting TDM after each execution (in order to free the memory again). Here is an example:

tdm_batchConvertMaterials 0 1000
*Wait for finish and restart TDM*
tdm_batchConvertMaterials 1000 1000
*Wait for finish and restart TDM*
tdm_batchConvertMaterials 2000 1000
...

Eventually the console will say "0 Materials processed and changed in total.", which means you're done.

I followed the above instructions but still ran into malloc errors

It may occur that you run into malloc errors, although the first executions of the command were successful. This is due to the fact that some materials are more complex than others and require more RAM for that reason. Remember the last StartIndex and re-execute the command with that index, but a decreased nMaterials. Say for example, you received a malloc error after executing "tdm_batchConvertMaterials 4000 1000". You would now go ahead and do the following:

tdm_batchConvertMaterials 4000 500
*Wait for finish and restart TDM*
tdm_batchConvertMaterials 4500 500
...

After those two executions, you can actually try to raise nMaterials again to a higher value, in order to reduce the required user-input.

Known issues

• tdm_batchConvertMaterials can result in malloc errors. See section Proper Usage of the command.
• The conversion can produce undesired results on vertex blended materials, e.g. one of the old ambient stages is not removed. Please double check respective materials.