Import System

UNIGINE offers a flexible and extendable Import System, enabling you to import whole scenes as well as selected scene components from any external format and use them in your projects.

Imported Scene is a set of metadata on objects to be brought to UNIGINE, which can contain the following components:

• Lights
• Cameras
• Meshes
• Mesh animations
• Textures
• Materials
• Nodes

The structure of Import System is shown below. It includes Import Manager and a dynamic set of importers and processors for various external file formats.

Import Manager is used to create and manage importers and processors, as well as to directly import files in non-native formats, if an importer for such files was previously registered.

Importer is a module used by Import System to bring the data stored in various non-native formats to UNIGINE. It generates UNIGINE objects on the basis of metadata extracted from the imported file. A single importer can be used to import multiple external file formats (extensions), but there shouldn't be two or more importers registered for a single file format.

Each importer has a set of parameters that control the whole import process (e.g., scale multiplier, use of various processors such as static mesh merger or vertex cache optimizer, etc.). It also has a set of flags that define which scene components are to be extracted and imported. So, the importer should be initialized before use.

Importers use a set of processors to perform all necessary auxiliary operations. A processor is a module that performs auxiliary operations during the import process (data preparation, file saving, file management, etc.). The list of processor types that can be used includes the following:

• Pre-processor — performs additional operations on scene metadata (ImportScene) and prepares it for the object generation stage.
• Import processor — saves UNIGINE objects generated by an importer on the basis of metadata to a file in UNIGINE's native format. You can use a set of different processors for each scene component or a single processor for all of them.
• Post-processor — performs additional operations with generated files (copying files to other folders, adding files to packages, etc.).

Importer allows you to add any number of pre- and post-processors. However, you can set only one processor for each scene component.

Import System offers you the DefaultProcessor — it is, as its name says, a default processor used to save objects that were generated by an importer to corresponding UNIGINE file formats (.mesh, .texture, .node, etc.).

If your application does not require any specific file saving operations, you can use DefaultProcessor, otherwise, you can implement your own custom processor with any additional functionality (e.g., import models directly to memory).

Information on all registered importers and processors can be obtained via the import_info console command.

In order to be used, importers and processors must be registered in the system via Import Manager. You can manage the list of available modules dynamically by adding them to or removing from the registry. When you import a file in any external format, Import System automatically tries to find and use an appropriate importer registered for the specified file extension.

The basic file import workflow is as follows:

1. Check the extension of the specified input file and find the appropriate importer among the registered ones.
2. Extract scene metadata from the input file, put the data to the corresponding import structures (ImportMesh, ImportMaterial, etc.), and build the import scene.
3. Use pre-processor(s) to prepare scene metadata when necessary (merge all static meshes into a single one, optimize vertex cache, etc.).
4. Use the appropriate importer to generate UNIGINE objects (nodes, lights, cameras, materials, etc.) on the basis of scene metadata.
5. Use the appropriate import processor to save generated objects to the corresponding files in the specified output directory.
6. Use post-processor(s) to perform necessary operations with generated files.

The Import System is utilized by both the Engine and the UnigineEditor. Out-of-the-box it currently offers:

• Importer for FBX scenes implemented as UnigineFbxImporter plugin, which in addition to .fbx format also supports .obj, .dae, and .3ds.
• Importer for CAD models implemented as UnigineCadImporter plugin, which supports .iges, .step, and .stl CAD formats.

Custom importing modules (importers and processors) for any file format containing 3D scene data are also to be implemented as plugins. So, you can consider the UnigineFbxImporter and UnigineCadImporter plugins as examples to build your own custom importing modules. You can also modify and rebuild these plugins to use your own custom importer in the Editor (add functionality to process used-defined attributes of CAD models, some additional scene processing functionality, etc.).

To use the UnigineFbxImporter plugin, just load it via the plugin_load console command or the following command line option on the application start-up:

-extern_plugin UnigineFbxImporter

In general, the workflow via the API may be represented as follows:

// create an importer for the imported file ("1.fbx" in our case)
ImporterPtr importer = Import::createImporterByFileName("../data/1.fbx");

if (importer)
{
	// set up import parameter "scale" to 0.5
	importer->setParameterFloat("scale", 0.5f);
	// add a pre-processor to merge static meshes
	importer->addPreProcessor("MergeStaticMeshes");

	// initialize importer with all available import flags
	importer->init("1.fbx", ~0);

	// import our model to the specified directory
	importer->import("../data/1/");

	// create a node reference using the .node file generated for our model
	NodeReferencePtr noderef = NodeReference::create(importer->getOutputFilepath());
}

You can also load a model with default settings simply like this:

// string to store the path to the .node file for your model
String filepath_node;

// import an fbx file to the specified location and get the path to the generated .node file
filepath_node = Import::doImport("../data/1.fbx", "../data/1/");

// create a node reference using the .node file generated
NodeReferencePtr noderef = NodeReference::create(filepath_node.get());

Built-in Import Options#

importer->setParameterString("lods_postfixes", "_lod_0,_lod_1,_lod_2");

importer->setParameterString("lods_distances", "-1e+09,3,9");

• FbxImporter plugin as an a example for your custom import plugin: source/plugins/Import/FbxImporter.
• CadImporter plugin as an a example for your custom import plugin: source/plugins/Import/CadImporter.
• Custom Import Plugin usage example to learn the basics of writing your own custom import plugin.
• Importing Models Directly to Memory usage example to learn the basics of writing your own custom import processor.

File Import System API:

• File Import Functionality classes for more details on managing the Import System, importers and processors via code (C++, UnigineScript).
  Notice

  Import System API is not available for the Community SDK edition.