Creating a Datasmith File

The following procedure summarizes the overall process of using the Datasmith SDK to generate a .udatasmith file programmatically. For a working code example that illustrates these steps, see the \ref DatasmithExportBasicSample.cpp file.

Tip: You can find examples that show how to set up all of the different types of 3D content that this SDK supports in the source code for the Datasmith export plugins for 3DS Max, Revit, and Sketchup. The source code for all of these plugins is publicly available in the Unreal Engine source code distribution.

Any time you want to access the classes and symbols defined in the SDK, you'll need to include the files from the Datasmith SDK that define those classes or symbols. For example, for the purposes of the instructions below, you'll need to add the following includes at the top of your .cpp file:
```
#include "DatasmithExporterManager.h"
#include "DatasmithSceneExporter.h"
#include "DatasmithSceneFactory.h"
#include "DatasmithExportOptions.h"
#include "DatasmithMesh.h"
#include "DatasmithMeshExporter.h"
```
Initialize the Datasmith Exporter Manager. This initializes core systems of the engine that the SDK relies on.
```
FDatasmithExporterManager::Initialize();
```
Tip: You don’t see this call in the code of the \ref DatasmithExportBasicSample.cpp sample, because that sample is built as a module within the Unreal Engine solution. Therefore, the initialization of the core engine systems is already done implicitly. However, if you’re integrating the SDK into your own application, or if you need it to run as a plugin within a separate host application, you’ll need this call to initialize the core engine systems explicitly yourself.
Create a Datasmith Scene Exporter. This object manages the process of converting your scene data into files on disk.
```
FDatasmithSceneExporter MyExporter;
```
Set up the properties of the exporter. At a minimum, you’ll need to:
- Give the scene a name by calling SetName().
```
MyExporter.SetName(TEXT("MyExportedSceneName"));
```
- Set the folder on your computer where you want to save the .udatasmith file you export at the end of this process.
```
MyExporter.SetOutputPath(TEXT("D:\\BasicSample"));
```
Create a Datasmith Scene. This object is the top-level container for all the information you need to bring into the Unreal Engine.
```
TSharedRef< IDatasmithScene > DatasmithScene = FDatasmithSceneFactory::CreateScene(TEXT("BasicSample"));
```
Now that you have a Datasmith Scene set up, you'll need to feed it with all the 3D data that is used in your scene.
For most types of scene elements, you use the same general process:
1. Use one of the static functions offered by the FDatasmithSceneFactory class to create a new object of the type you need. You'll receive a pointer to the new object. For example:
```
// Create a 2D texture
TSharedRef< IDatasmithTextureElement > MyTextureObject = FDatasmithSceneFactory::CreateTexture(TEXT("My Texture Asset Name"));

// Create a material
TSharedRef< IDatasmithMaterialIDElement > MyMaterial = FDatasmithSceneFactory::CreateMaterialId(TEXT("My Material"));

// Create an empty Actor in the scene hierarchy.
TSharedRef< IDatasmithActorElement > MyActor = FDatasmithSceneFactory::CreateActor(TEXT("My Actor Name"));

// Create a point light in the scene hierarchy.
TSharedRef< IDatasmithPointLightElement > MyLight = FDatasmithSceneFactory::CreatePointLight(TEXT("My PointLight Actor Name"));
```
2. Through the returned pointer, call functions exposed by the new object to set it up with the data you need to express.
  
  For example, to control the 3D transform of an Actor, camera, or light in the scene hierarchy, you can call its IDatasmithActorElement::SetTranslation(), IDatasmithActorElement::SetRotation(), and IDatasmithActorElement::SetScale() functions. You can also call the IDatasmithActorElement::AddChild() function of any Actor to add another Actor as a child, organizing your Datasmith Scene into a hierarchy of Actors that matches the way your source scene is organized.
3. When you're happy with your new object, add it to your Datasmith Scene by calling one of the Add...() functions offered by the IDatasmithScene. For example:
```
// Add the texture element
MyDatasmithScene->AddTexture(MyTextureObject);

// Add the material
MyDatasmithScene->AddMaterial(MyMaterial);

// Add the Actors, making the light a child of the empty Actor.
MyActor->AddChild(MyLight);
MyDatasmithScene->AddActor(MyActor);
```
For geometric objects, the process is slightly different.
1. Create an FDatasmithMesh object.
2. Call its FDatasmithMesh::Set..Count() functions, like FDatasmithMesh::SetVerticesCount(), to set up the size of the buffers it uses for 3D vertices, faces, and UV coordinates.
3. Call its other FDatasmithMesh::Set..() functions, like FDatasmithMesh::SetVertex(), repeatedly to set up the vertices in the geometry, to make faces out of those vertices, and to set the UV coordinates for the face vertices. You can also set up each face with the numeric ID of the Material you want to assign it.
  
  Tip: For examples that show how to set up mesh geometry for simple primitives, see the \ref DatasmithExportHelper.cpp file.
4. When you have the geometry set up the way you want it, you'll need to export it to a file. (Geometric data isn't kept in the *.udatasmith file itself, it's kept in binary *.udsmesh files in an _Assets subfolder next to the *.udatasmith file.)
  
  To do this, create an FDatasmithMeshExporter and call its FDatasmithMeshExporter::ExportToUObject() function. For example:
```
FDatasmithMeshExporter MeshExporter;
TSharedPtr< IDatasmithMeshElement > MyMeshElement = MeshExporter.ExportToUObject( DatasmithSceneExporter.GetAssetsOutputPath(), TEXT("MySimpleMesh"), MyMesh, nullptr, EDSExportLightmapUV::Always );
```
  Use the DatasmithSceneExporter.GetAssetsOutputPath() function to set the export path, to be certain that your mesh data will be stored in the location the the Datasmith importer will expect to find it.
5. In the last step, you acquired a pointer to an IDatasmithMeshElement. Add this to the Datasmith Scene:
```
MyDatasmithScene->AddMesh(MyMeshElement);
```
6. Now you can make Actors in the Datasmith Scene that instantiate this mesh geometry:
```
TSharedPtr< IDatasmithMeshActorElement > MyMeshActor = FDatasmithSceneFactory::CreateMeshActor( TEXT("My Simple Mesh Actor") );
MyMeshActor->SetStaticMeshPathName( TEXT("MySimpleMesh") );
MyDatasmithScene->AddActor(MyMeshActor);
```
Use the static functions offered by the FDatasmithExportOptions class to set any export options that you want to override. For example, you can specify maximum texture sizes and how to handle lightmap UVs.
```
FDatasmithExportOptions::LightmapUV = EDSExportLightmapUV::IfNotPresent;
```
When your scene is set up exactly the way you want it, call the Export() method of your Datasmith Scene Exporter to begin the process of serializing the data in your Datasmith Scene to a .udatasmith file on disk.
```
MyExporter.Export(DatasmithScene);
```
When the export is done, and you no longer need any of the objects you set up above, shut down the Datasmith Exporter Manager to close down all the core engine systems and release the resources they allocated.
```
FDatasmithExporterManager::Shutdown();
```

When you compile and run your application, and navigate to the folder that you set as the output path for the Datasmith Scene Exporter, you should see a .udatasmith file with the name you set for the Datasmith Scene Exporter. There should also be a folder with the same name, plus the _Assets suffix. This folder should contain a .udsmesh file for each mesh that you created, and an image file for each texture you added to the Datasmith Scene.

You can now open the Unreal Editor and use the Datasmith importer in the Toolbar to import your .udatasmith file.

Note: For best results, use the same version of the Unreal Editor that you used to build your export application. Full compatibility is not guaranteed for .udatasmith files that were generated by a different version of the Datasmith SDK than the version of the Datasmith importer that you use to import the file.

8.6 KiB Raw Blame History Unescape Escape

Creating a Datasmith File

8.6 KiB

Raw Blame History