developer.nvidia.com
Powered ByGoogle
 
WWWdeveloper.nvidia.com
Registered Developers
Join
Home
News
Documentation
Tools
Partners
Newsletter
Events Calendar
Drivers
Contact
TWIMTBP
Legal Info

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.