Provide a Data Importer

Demonstrates the implementation of functions required to provide a data importer.

Importer Entry Points

• implement VRPImport (Lua: import) to recieve the import request

• implement VRPFormats (Lua: formats) to provide a description of supported formats

• optionally implement VRPSettingsInterface (Lua: settingsInterface) to provide a description of configurable settings that affect the import behaviour

• if providing settings interface, implement VRPDefaultRecipe (Lua: recipe) to provide a default filename for the recipe file generated by the settings description

When a plugin implements these entry points, it appears in the application import menu.

Example Code

PLUGIN_ENTRY_POINT const char* VRTREE_APIENTRY VRPFormats()
{
  return "<filetypes><type ext=\"txt\" desc=\"Text File\" /></filetypes>";
}

PLUGIN_ENTRY_POINT int VRTREE_APIENTRY VRPImport(const char *file, 
                                                 HNode root, 
                                                 HNode scenes, 
                                                 HNode libs, 
                                                 uint64_t flags, 
                                                 const char *recipePath)
{
  // Create nodes and attach them to the root / scenes / libs nodes as appropriate.

  // Return 0 on successful import.
  return 0;
}

-- Assuming module exports according to recommendation in "Getting Started".
local function formats()
  return "<filetypes><type ext=\"txt\" desc=\"Text File\" /></filetypes>"
end

local function import(file, root, scenes, libs, flags, recipePath)
  -- Create nodes and attach them to the root / scenes / libs nodes as appropriate.

  -- Return 0 on successful import.
  return 0
end

return {
  -- Alongside existing exports.
  formats = formats,
  import = import
}

Settings Interface

If you choose to implement the VRPSettingsInterface function to return valid XML (see the schema and example on the function docs), Visionary Render will automatically parse this to generate both a recipe file and the user interface to control the settings.

Recipe File

The XML is parsed before import, and if not already present on disk, the settings are written to a recipe file in <documents>/VisionaryRender <version>/recipe. The path to this file is then passed to the recipePath parameter of the VRPImport function. The importer implementation should parse this file (it is a simple key=value text file with one setting per line) and use the values accordingly.

User Interface

The XML is also used to generate the user interface when accessing the importer settings. The XML schema defines the types of controls available.

Given the example XML returned by VRPSettingsInterface:

<recipe>
  <Page name="Basic">
    <IntBox label="Log Level" name="loglevel" value="0" min="0" max="4" desc="Set log level"/> 
    <Selection label="Unit" name="vrUnit" value="meters" options="meters,milimeters,centimeters" desc="Unit of values in the file"/> 
  </Page>
</recipe>