2.3. Initialization

When it comes to running VTK‑m code, there are a few ways in which various facilities, such as logging device connections, and device configuration parameters, can be initialized. The preferred method of initializing these features is to run the vtkm::cont::Initialize() function. Although it is not strictly necessary to call vtkm::cont::Initialize(), it is recommended to set up state and check for available devices.

InitializeResult vtkm::cont::Initialize(int &argc, char *argv[], InitializeOptions opts = InitializeOptions::None)

Initialize the VTKm library, parsing arguments when provided:

  • Sets log level names when logging is configured.

  • Sets the calling thread as the main thread for logging purposes.

  • Sets the default log level to the argument provided to --vtkm-log-level.

  • Forces usage of the device name passed to --vtkm-device.

  • Prints usage when -h or --vtkm-help is passed.

The parameterless version only sets up log level names.

Additional options may be supplied via the opts argument, such as requiring the --vtkm-device option.

Results are available in the returned InitializeResult.

Note

This method may call exit() on parse error.

vtkm::cont::Initialize() can be called without any arguments, in which case VTK‑m will be initialized with defaults. But it can also optionally take the argc and argv arguments to the main function to parse some options that control the state of VTK‑m. VTK‑m accepts arguments that, for example, configure the compute device to use or establish logging levels. Any arguments that are handled by VTK‑m are removed from the argc/argv list so that your program can then respond to the remaining arguments.

vtkm::cont::Initialize() returns a vtkm::cont::InitializeResult structure. This structure contains information about the supported arguments and options selected during initialization.

struct InitializeResult

Public Members

DeviceAdapterId Device = DeviceAdapterTagUndefined{}

The device passed into --vtkm-device argument.

If no device was specified, then this value is set to DeviceAdapterTagUndefined. Note that if the user specifies “any” device, then this value can be set to DeviceAdapterTagAny, which is a pseudo-tag that allows any supported device.

std::string Usage

A usage statement for arguments parsed by VTK-m.

If the calling code wants to print a usage statement documenting the options that can be provided on the command line, then this string can be added to document the options supported by VTK-m.

vtkm::cont::Initialize() takes an optional third argument that specifies some options on the behavior of the argument parsing. The options are specified as a bit-wise “or” of fields specified in the vtkm::cont::InitializeOptions enum.

enum class vtkm::cont::InitializeOptions

Values:

enumerator None

Placeholder used when no options are enabled.

This is the value used when the third argument to vtkm::cont::Initialize is not provided.

enumerator RequireDevice

Issue an error if the device argument is not specified.

enumerator DefaultAnyDevice

If no device is specified, treat it as if the user gave --vtkm-device=Any.

This means that DeviceAdapterTagUndefined will never be returned in the result.

enumerator AddHelp

Add a help argument.

If -h or --vtkm-help is provided, prints a usage statement. Of course, the usage statement will only print out arguments processed by VTK-m, which is why help is not given by default. Alternatively, a string with usage help is returned from vtkm::cont::Initialize so that the calling program can provide VTK-m’s help in its own usage statement.

enumerator ErrorOnBadOption

If an unknown option is encountered, the program terminates with an error and a usage statement is printed.

If this option is not provided, any unknown options are returned in argv. If this option is used, it is a good idea to use AddHelp as well.

enumerator ErrorOnBadArgument

If an extra argument is encountered, the program terminates with an error and a usage statement is printed.

If this option is not provided, any unknown arguments are returned in argv.

enumerator Strict

If supplied, Initialize treats its own arguments as the only ones supported by the application and provides an error if not followed exactly.

This is a convenience option that is a combination of ErrorOnBadOption, ErrorOnBadArgument, and AddHelp.

Example 2.2 Calling vtkm::cont::Initialize().
 1#include <vtkm/cont/Initialize.h>
 2
 3int main(int argc, char** argv)
 4{
 5  vtkm::cont::InitializeOptions options =
 6    vtkm::cont::InitializeOptions::ErrorOnBadOption |
 7    vtkm::cont::InitializeOptions::DefaultAnyDevice;
 8  vtkm::cont::InitializeResult config = vtkm::cont::Initialize(argc, argv, options);
 9
10  if (argc != 2)
11  {
12    std::cerr << "USAGE: " << argv[0] << " [options] filename" << std::endl;
13    std::cerr << "Available options are:" << std::endl;
14    std::cerr << config.Usage << std::endl;
15    return 1;
16  }
17  std::string filename = argv[1];
18
19  // Do something cool with VTK-m
20  // ...
21
22  return 0;
23}