8. XML Tools¶

8.1. Overview¶

VisIt developers use several xml-based code generation tools to implement VisIt’s features. The source core for these tools is kept in src/tools/dev/xml/ and src/tools/dev/xmledit/.

8.2. Types Managed by XML Tools¶

These XML tools are designed to be aware of a number of basic data types. These include…

Bool
Int
Float
Double
UChar (aka Unsigned Char)
String

In addition to these basic types as scalars, we also support Arrays of fixed length and Vectors of arbitrary length of these basic types. There is also support for a number of types that require special handling. These are…

types defined in the avtTypes.h header file

#define AVT_TYPES_H

#include <dbatts_exports.h>

#include <vector>
#include <string>

enum avtVarType
{
    AVT_MESH                     = 0,
    AVT_SCALAR_VAR,             /* 1 */
    AVT_VECTOR_VAR,             /* 2 */
    AVT_TENSOR_VAR,             /* 3 */
    AVT_SYMMETRIC_TENSOR_VAR,   /* 4 */
    AVT_ARRAY_VAR,              /* 5 */
    AVT_LABEL_VAR,              /* 6 */
    AVT_MATERIAL,               /* 7 */
    AVT_MATSPECIES,             /* 8 */
    AVT_CURVE,                  /* 9 */
    AVT_UNKNOWN_TYPE            /* 10 */
};


enum avtSubsetType
{
    AVT_DOMAIN_SUBSET      = 0,
    AVT_GROUP_SUBSET,     /* 1 */
    AVT_MATERIAL_SUBSET,  /* 2 */
    AVT_ENUMSCALAR_SUBSET,/* 3 */
    AVT_UNKNOWN_SUBSET    /* 4 */
};


enum avtCentering
{
    AVT_NODECENT         = 0,
    AVT_ZONECENT,       /* 1 */
    AVT_NO_VARIABLE,    /* 2 */
    AVT_UNKNOWN_CENT    /* 3 */
};


enum avtExtentType
{
    AVT_ORIGINAL_EXTENTS      = 0,
    AVT_ACTUAL_EXTENTS,      /* 1 */
    AVT_SPECIFIED_EXTENTS,   /* 2 */
    AVT_UNKNOWN_EXTENT_TYPE  /* 3 */
};


enum avtMeshType
{
    AVT_RECTILINEAR_MESH      = 0,
    AVT_CURVILINEAR_MESH,    /* 1 */
    AVT_UNSTRUCTURED_MESH,   /* 2 */
    AVT_POINT_MESH,          /* 3 */
    AVT_SURFACE_MESH,        /* 4 */
    AVT_CSG_MESH,            /* 5 */
    AVT_AMR_MESH,            /* 6 */
    AVT_UNKNOWN_MESH         /* 7 */
};


enum avtGhostType
{
    AVT_NO_GHOSTS        = 0,
    AVT_HAS_GHOSTS,     /* 1 */
    AVT_CREATED_GHOSTS, /* 2 */
    AVT_MAYBE_GHOSTS    /* 3 */
};

//
// Note:
// These are used in a bit mask.
// If you need to extend the available types
// make sure to shift new enum values properly.
//
enum avtGhostsZonesPresent
{
    AVT_NO_GHOST_ZONES          = 0,
    AVT_BOUNDARY_GHOST_ZONES,  /* 1 */
    AVT_NESTING_GHOST_ZONES    /* 2 */
};

enum avtMeshCoordType
{
    AVT_XY      = 0,
    AVT_RZ,    /* 1 */
    AVT_ZR     /* 2 */
};

enum avtPrecisionType
{
    AVT_PRECISION_FLOAT     = 0,
    AVT_PRECISION_NATIVE,  /* 1 */
    AVT_PRECISION_DOUBLE   /* 2 */
};

enum avtBackendType
{
    AVT_BACKEND_VTK     = 0,
    AVT_BACKEND_VTKM   /* 1 */
};

enum SetState
{
    NoneUsed            = 0,
    SomeUsed,          /* 1 */
    AllUsed,           /* 2 */
    SomeUsedOtherProc, /* 3 */
    AllUsedOtherProc   /* 4 */
};


enum LoadBalanceScheme
{
    LOAD_BALANCE_UNKNOWN                       =-1,
    LOAD_BALANCE_CONTIGUOUS_BLOCKS_TOGETHER    = 0,
    LOAD_BALANCE_STRIDE_ACROSS_BLOCKS,        /* 1 */
    LOAD_BALANCE_RANDOM_ASSIGNMENT,           /* 2 */
    LOAD_BALANCE_DBPLUGIN_DYNAMIC,            /* 3 */
    LOAD_BALANCE_RESTRICTED,                  /* 4 */
    LOAD_BALANCE_ABSOLUTE,                    /* 5 */
    LOAD_BALANCE_STREAM                       /* 6 */
};

typedef std::vector<std::string> MaterialList;

types representing some high-level knowledge such as a LineWidth, a database VariableName, an Opacity (slider) value, etc.

The implementation of these types in C++, Java, Python and Qt is handled by various of the GenerateXXX.h header files.

For more details, please see this issue.

8.3. CMake Integration¶

We rely on xml code generation to keep our State object, Attribute, and Plugin APIs up-to-date. To automate the process we provide CMake targets that call our xml code generation tools for each object or plugin registered. Individual code gen targets are all wired into top level targets that allow you to apply the code gen tools to categories of code gen tasks. These targets replace older tools such as regen-ajp and various regenerateatts.py scripts. Keep in mind however, that these targets are only created for plugins that are enabled for building. Any use of the plugin-reducing CMake vars (VISIT_BUILD_MINIMAL_PLUGINS and any of the VISIT_SELECTED_XXX_PLUGINS) will limit the created code gen targets to those plugins being built.

8.3.1. Top Level CMake Code Gen Targets¶

CMake Target	Target Action
gen_cpp_all	Run xml2atts on all identified objects
gen_python_all	Run xml2python on all identified objects
gen_java_all	Run xml2java on all identified objects
gen_info_all	Run xml2info on all plugins
gen_cmake_all	Run xml2cmake on all plugins
gen_plugin_all	Run all applicable xml tools for all plugins

8.3.2. CMake Code Gen Functions¶

These are the helper functions we use to create targets that call xml tools in our CMake build system.

XML Tools Helper functions in src/CMake/VisItMacros.cmake:

CMake Function	Target Action
ADD_CPP_GEN_TARGET	Calls xml2atts
ADD_PYTHON_GEN_TARGET	Calls xml2python
ADD_JAVA_GEN_TARGET	Calls xml2java
ADD_INFO_GEN_TARGET	Calls xml2info
ADD_CMAKE_GEN_TARGET	Calls xml2cmake

The xml2plugin and xml2avt tools are only called when you first create a new plugin or object, they are not exposed here.

Plugin Tools Helper functions in src/CMake/PluginMacros.cmake:

ADD_PLUGIN_CODE_GEN_TARGETS - wires up:

ADD_CPP_GEN_TARGET

ADD_PYTHON_GEN_TARGET

ADD_JAVA_GEN_TARGET

ADD_INFO_GEN_TARGET

ADD_CMAKE_GEN_TARGET

ADD_DATABASE_CODE_GEN_TARGETS - wires up:

ADD_INFO_GEN_TARGET

ADD_CMAKE_GEN_TARGET

ADD_OPERATOR_CODE_GEN_TARGETS - alias for ADD_PLUGIN_CODE_GEN_TARGETS
ADD_PLOT_CODE_GEN_TARGETS - alias for ADD_PLUGIN_CODE_GEN_TARGETS