Scripting FX Composer using C#
Taking advantage of FX Composer's scripting features to gain
greater control over the application and import or export data.
FX Composer 1.5 introduced
C# scripts. They can be loaded and compiled just like .fx files,
and executed using a new 'play' button on the main toolbar.
The C# scripts that
ship with FX Composer give an overview of what is possible. Using
the script code, it is possible to access the FX Composer scene graph,
and some additional application services designed to help with common
tasks such as taking screenshots.
A good first example to try is "export_materials.cs", found in
the MEDIA\Scripts directory. This script will export the
materials currently loaded into FX Composer, along with the
parameters in effect, as set on the properties panel. The
entry point to all FX Composer scripts is the Run method.
When play is pressed on the toolbar, this is the function that
is called. It looks like this:
- public int Run(NVSystem Sys) { }
The parameter passed to the script is the interface to the FX
Composer engine, called NVSystem. Through this interface
it's possible to access all the FX Composer engine. For
example, the following code will access the scene:
- NVScene Scene;
Sys.GetScene(out Scene);
Looking at the export_materials.cs file, it can be seen
that this simple script walks through the scene finding all
of the materials, and writes them to a simple XML style of
data file. It isn't a huge leap to change this code to
export data in any fashion so desired.
Other scripts of note are: export_materials_keys.cs -
export materials and key frame information
material_export_images.cs - given a list of .fx files, will
generate a series of screenshots of each material.
fxcomposer_export_images.cs - given a list of .fxproj
projects will load each and save a screenshot.
spiral_scene.cs - given a list of .fx files will build a
spiral shape containing a sphere for each material.
In particular, it is worth trying the material_export_images script and
choosing all the .fx files in the MEDIA\HLSL directory.
This is a quick way to preview all materials, and build a
directory full of material screenshots. Script Advantages
- They can be compiled in FX Composer, with full
compilation error reports, making them easy to build
with fast turn-around.
- Scripts don't require a compiler or a custom DLL to
function.
- Scripts can replace most plugins, as they have the
same access to the FX Composer API as plugins do.
- Using C# it is often easier to read or write data
files, such as XML.
Script Disadvantages
- Scripts cannot currently be loaded at startup or
added to menus. They must be manually started.
- Scripts cannot be debugged - using messages,
debug logs, etc. is the only way to test script
output.
- Scripts cannot run during frame ticks, in
response to animations (though they can cause a
sequence of frames to be drawn).
Script Tips
- Always wrap your script in an exception
handler, and report errors. That way it's
easy to debug them.
- To add additional .NET assemblies to FX
Composer, so that your script can call them, you
need to modify the fxcomposer.config file to
include the assembly.
- A good way to 'discover' the API methods
available is to use a tool such as .NET
Reflector to example the nv_sys.interop dll.
- The 'methods.cs' script uses reflection to
list the methods in the main system interface -
NVSystem.
- FX Composer also supports VB.NET scripts.
PluginList.vb lists all the loaded plugins using
VB.NET
- If your script has an unhandled exception,
FX Composer will display a dialog pointing to
the cause.
|