# Creating a Datasmith File                                                      {#exporting}

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.

1.  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"

2.  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.

3.  Create a Datasmith Scene Exporter. This object manages the process of converting your scene data into files on disk.

        FDatasmithSceneExporter MyExporter;

4.  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"));

5.  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.

6.  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);

7.  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);

7.  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;

8.  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);

9.  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.