FxCleaner conditioner

From COLLADA Public Wiki
Jump to: navigation, search
Conditioner information
  • Name: FxCleaner
  • Purpose: Optimizes COLLADAFX data
  • Last updated: 3.12.2007
  • Current version: 1.0
  • Status: released
  • Created by: Heinrich Fink
  • Contact for technical issues: heinrich.fink@chello.at

Download

This article is part of the COLLADA conditioners directory
Adding to the conditioners directory

Description

The FxCleaner optimizes COLLADA effects by checking for various redundant definitions. The original motivation for this conditioner was to compensate COLLADAMAYA's lack of having multiple <material>-elements instancing one effect. In the next chapter you will find a description of the available algorithms.

Features

Parameter Balancing

This algorithm checks all <material>-elements for <setparam>-values that are already in the default-state of its instanced effect.

In the following example the <setparam ref="Lamp0Color"> would be deleted because its value (1 1 1) is the same as the default state value of the referenced <newparam sid="Lamp0Color"> in <effect id="Effect1">.

Fxcl pBalancing snippet1.pngFxcl pBalancing snippet2.png

The implementation of this algorithm also takes care of multiple profile-definitions per effect. So a <setparam> in <material> gets only deleted, if its value is the same as the default value of its <newparam> across all present profiles.

Reducing Effect Redundancies

This feature is the most powerful one of the FxCleaner conditioner. As already mentioned in the introduction, the current implementation of the COLLADAMAYA FX exporter is not able to use the feature of COLLADAFX having multiple materials instancing one effect.

Take the following example:

Our goal is to create two materials with the same shading-effect (simple phong) but using different textures for the surface color, like on the following screenshot.

Same shading-effect, different textures

Now, in COLLADAMAYA we would have to create two COLLADAFX materials which unfortunately creates two <effect>s. In our example case the only difference between those two effect are distinct surfaces linked to the Color-Sampler:

Fxcl redundant effect1.pngFxcl redundant effect2.png

The two actual <material>s simply instance each of the two effects:

Fxcl redundant materials.png

This is obviously a very redundant way to define our wanted materials. We would rather expect having two <material>s instancing the same effect and only overriding the ColorTexture-parameter by a <setparam>. FxCleaner is able to automatically detect two redundant <effect>s like in the above example. Those two <effect>s will be merged and their instancing <material>s will be changed accordingly.

In our example, <effect id="Effect2" name="Plastic_Two"> will be deleted, and the new <material>s will look like this:

Fxcl reduceEffect materialResult.png

The above example illustrates a very simple case. But the conditioner is also able to merge two <effect>s that might have different values in their <newparam>-defitions. After merging, the difference of the <newparam>-values between two <effect>s, is expressed by stepping through all <material>s that instanced those two <effect>s and creating <setparam>s with the correct values.

It is also possible to merge <effect>s with multiple profiles. For example you might run the CgToGLSL conditioner prior to the FxCleaner and achieve the same result, but with multiple profiles (GLSL and Cg).

You can download the above example case from here (FxCleaner_example.zip).

Removal of unreferenced <effect>s

If an <effect> is not instanced by any <material> in the current COLLADA document it will be removed.

Availability

The FxCleaner conditioner is available for Windows and Mac OS X as a Refinery plugin and a standalone CLI tool. Please read install_notes.txt in the binary packages (available here) for further installation instructions. See BUILD.txt for build instruction on both platforms of the source-package.

Usage

Conditioner options

You can set the following options of the conditioner either via the Refinery GUI, or as a commandline option.

Type

./FxCleaner --help

for command line parameters.

Perform Parameter Balancing

If enabled, FxCleaner compares <setparam> arrays of <material>-elements with default values of its effect, and deletes unnecessary <setparam>-elements (also see here)

Reduce Effect Redundancies

Enable to let the conditioner perform this algorithm.

Delete Material Extras

Enable to delete <extra>-elements in <material>s that referenced a merged effect.

Delete Unreferenced Effects

Enable to remove any <effect>s that are not instanced by any <material>.

Write Logfile

Enable to write a detailed logfile of the optimization process. By default the logfile is placed in the current working directory for the CLI-version, the Refinery-plugin places its logfiles into the directory of the INPUT Collada file.

Revision History

Ver. 1.0 released 2007-12-03

initial release

Special notes and limitations

  • This conditioner depends on the SVN version of the COLLADA DOM as it uses methods of daeElement which are not available in the current official release for comparing COLLADA elements.