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 toDeviceAdapterTagAny
, 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.
-
DeviceAdapterId Device = DeviceAdapterTagUndefined{}
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 fromvtkm::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
, andAddHelp
.
-
enumerator None
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}