Games exporting

Once a model is loaded using StpLoadSpeedTreeFile(), it can be exported to any mesh format supported by the SpeedTree Modeler with a single function call. The supported games formats are:

• SpeedTree Runtime SDK format (.stsdk)
• SpeedTree 8 format (.st)
• SpeedTree 9 format (.st9)
• Crytek geometry format (.cgf)
• FBX/Filmbox (.fbx)
• Wavefront (.obj)
• All-data XML (.xml)
• Universal Scene Description (.usd)

The structure StpGamesExportOptions encapsulates all available export options and is closely related to the .ini export files supported by the Modeler CLI (command-line interface) export system.

Because the SpeedTree Pipeline SDK API is in C instead of C++, developers should call StpInitGamesExportOptions() to initialize their StpGamesExportOptions objects. The default values it sets are documented here.

The following example shows how to load an .spm file and export it as a .usd file.

C++ example

///////////////////////////////////////////////////////////////////////
//  SpeedTree Pipeline SDK error callback

static void MyErrorCallback(const char* error)
{
    fprintf(stderr, "    **[Error Report from SpeedTree Pipeline SDK]**: %s\n", error);
}


///////////////////////////////////////////////////////////////////////
//  SpeedTree Pipeline SDK message callback

static void MyMessageCallback(const char* message)
{
    fprintf(stderr, "    [Message from SpeedTree Pipeline SDK]: %s\n", message);
}

///////////////////////////////////////////////////////////////////////
//  Example_GamesExport
//
//    Parameters:
//
//      - modelFilename: should be an SpeedTree .spm file.
//
//        - exportFilename: the extension will dictate which format will be
//          exported (e.g. .usd for USD files, .obj for Wavefront OBJ). The
//        exporter will not create any new folders in the output path, so
//          please make sure the path already exists prior to calling.

bool Example_GamesExport(const char* modelFilename, const char* exportFilename)
{
    bool success = false;

    // register callback message functions; when api calls fail, messages will be
    // sent here
    StpSetErrorFunction(MyErrorCallback);
    StpSetMessageFunction(MyMessageCallback);

    // the exporting process can be lengthy, taking a minute or more, so the
    // progress callback system will help keep the caller updated
    StpSetProgressFunction(MyProgressCallback);

    // create a speedtree engine context
    StpContext* context = StpNew( );
    if (context)
    {
        // load the compact speedtree procedural file from disk
        if (StpLoadSpeedTreeFile(context, modelFilename, NULL))
        {
            // the vfx export system has specific options
            StpGamesExportOptions exportOptions;

            // let the export system set defaults for lengthy options list
            StpInitGamesExportOptions(&exportOptions);

            // express specific, non-default output preferences
            exportOptions.textureBillboardResolution = 2048; // good-sized billboard
            exportOptions.textureMaxResolution = 1024; // cap texture size

            // if exporting a .stsdk file, we need to set the packers; note
            // that packer names do not have paths or extensions here
            strcpy(exportOptions.sdkVertexPacking, "Standard");
            strcpy(exportOptions.sdkBillboardVertexPacking, "Standard_Billboard");
            strcpy(exportOptions.texturePacking, "_Standard");

            // make sure the export folder exists
            SpeedTree::CreateFolder(SpeedTree::FilenamePathOnly(exportFilename).c_str( ));

            // this is the call that causes the system to execute and it can be
            // lengthy; it's the equivalent of pressing "Export" on the Modeler's
            // export dialog.
            //
            // note that this system will not create output paths in pOutputFilename,
            // so be sure those paths already exist
            success = StpExportForGames(context, exportFilename, &exportOptions);
        }

        // operation complete, clean up
        StpDelete(context);
    }

    return success;
}