Split up filter documentation into basic and advanced development

BasicFilterImpl.tex

+% -*- latex -*-
+
+\chapter{Basic Filter Implementation}
+\label{chap:BasicFilterImpl}
+
+\index{filter!implementation|(}
+
+Chapter \ref{chap:SimpleWorklets} introduced the concept of a worklet and demonstrated how to create and one run to execute an algorithm on a device.
+Although worklets provide a powerful mechanism for designing heavily threaded visualization algorithms, invoking them requires quite a bit of knowledge of the workings of \VTKm.
+Instead, most users execute algorithms in \VTKm using filters.
+Thus, to expose algorithms implemented with worklets to general users, we need to implement a filter to encapsulate the worklets.
+In this chapter we will create a filter that encapsulate the worklet algorithm presented in Chapter \ref{chap:SimpleWorklets}, which converted the units of a pressure field from pounds per square inch (psi) to Newtons per square meter ($\mathrm{N}/\mathrm{m}^2$).
+
+Filters in \VTKm are implemented by deriving one of the filter base classes provided in \vtkmfilter{}.
+There are multiple base filter classes that we can choose from.
+These different classes are documented later in Chapter \ref{chap:FilterTypeReference}.
+For this example we will use the \vtkmfilter{FilterField} base class, which is used to derive one field from another field.
+
+The following example shows the declaration of our pressure unit conversion filter.
+By convention, this declaration would be placed in a header file with a \textfilename{.h} extension.
+
+\vtkmlisting[ex:SimpleField]{Header declaration for a simple filter.}{SimpleField.cxx}
+
+It should be noted that the \textidentifier{FilterField} superclass is actually a templated class that expects to be templated by the concrete subclass (in this case the \textcode{PoundsPerSquareInchToNewtonsPerSquareMeterFilter} class we are creating).
+This allows templated methods in the superclass call templated methods in the concrete subclass.
+This technique of templating a superclass based on the subclass is known as the Curiously Recurring Template Pattern (CRTP).
+
+It is typical for a filter to have a constructor to set up its initial state.
+A filter will also implement a \classmember*{FilterField}{DoExecute} method.
+Different filter types require different arguments for \classmember*{Filter}{DoExecute}, but the \textidentifier{FilterField} version has 4 arguments: the input \textidentifier{DataSet}, an \textidentifier{ArrayHandle} holding the data for the input field, metadata about the input field, and a policy used to pull other information from the input \textidentifier{DataSet}.
+(We will not need to use the policy in this example as the superclass will give us all the data we need.
+Policies are demonstrated in Chapter \ref{chap:FilterTypeReference}.)
+
+Once the filter class is declared in the \textfilename{.h} file, the implementation filter is by convention given in a separate \textfilename{.hxx} file.
+Given the definition of our filter in Example \ref{ex:SimpleField}, we will need to provide the implementation for the constructor and the \classmember*{FilterField}{DoExecute} method.
+The constructor is quite simple.
+It initializes the name of the output field name, which is managed by the superclass.
+
+\vtkmlisting[ex:SimpleFieldConstructor]{Constructor for a simple filter.}{SimpleFieldConstructor.cxx}
+
+In this case, we are setting the output field name to the empty string.
+This is not to mean that the default name of the output field should be the empty string, which is not a good idea.
+Rather, as we will see later, we will use the empty string to flag an output name that should be derived from the input name.
+
+The meat of the filter implementation is located in the \classmember*{FilterField}{DoExecute} method.
+
+\vtkmlisting[ex:SimpleFieldDoExecute]{Implementation of \textcode{DoExecute} for a simple filter.}{SimpleFieldDoExecute.cxx}
+
+The second argument to \classmember*{FilterField}{DoExecute} is a \vtkmcont{ArrayHandle} that contains the data for the input field.
+This argument is templated because, as described in Chapter \ref{chap:BasicArrayHandles}, \textidentifier{ArrayHandle}s are templated classes that can change based on the types of values and how they are stored.
+The superclass has determined what these types are and has passed a concrete version of the \textidentifier{ArrayHandle} to \classmember*{FilterField}{DoExecute}.
+It is good practice to check that the type we get is in fact an \textidentifier{ArrayHandle} using the \vtkmmacro{VTKM\_IS\_ARRAY\_HANDLE} macro (demonstrated in line \ref{ex:SimpleFieldDoExecute.cxx:CheckArray} of Example \ref{ex:SimpleFieldDoExecute}).
+
+The first operation our filter does is to create a new \textidentifier{ArrayHandle} to store the new computed field (line \ref{ex:SimpleFieldDoExecute.cxx:CreateOutputArray}).
+The type of the computed output field is typically derived from the type of the input array.
+
+Once the filter has both the input and output \textidentifier{ArrayHandle}s, it is ready to invoke the worklet to compute the output.
+For convenience, all filter superclasses provide an \classmember*{Filter}{Invoke} member that is a \vtkmcont{Invoker} class.
+Thus, worklets can be invoked within a filter by calling \textcode{this->Invoke} as if it were a method.
+This is shown starting on line \ref{ex:SimpleFieldDoExecute.cxx:Invoke}.
+Recall that the worklet created in Chapter \ref{chap:SimpleWorklets} takes two parameters: an input array and an output array, which are shown in this invocation.
+
+With the output data created, the filter has to build the output structure to return.
+All implementations of \classmember*{Filter}{DoExecute} must return a \vtkmcont{DataSet}, and for a simple field filter like this we want to return the same \textidentifier{DataSet} as the input with the output field added.
+The output field needs a name, and we get the appropriate name from the superclass (line \ref{ex:SimpleFieldDoExecute.cxx:OutputName}).
+However, we would like a special case where if the user does not specify an output field name we construct one based on the input field name.
+Recall from Example \ref{ex:SimpleFieldConstructor} that by default we set the output field name to the empty string.
+Thus, our filter checks for this empty string, and if it is encountered, it builds a field name by appending ``\_N/M\^2'' to it.
+
+Finally, our filter constructs the output \textidentifier{DataSet} using the \vtkmfilter{CreateResult} helper function.
+There are multiple versions of \textidentifier{CreateResult}, but the version we are using is adding our new array as a field as the same type as the input.
+
+This chapter has just provided a brief introduction to creating filters.
+There are several more filter superclasses to help express algorithms of different types.
+After some more worklet concepts to implement more complex algorithms are introduced in Part \ref{part:Advanced}, we will see a more complete documentation of the types of filters in Chapter \ref{chap:FilterTypeReference}.
+
+\index{filter!implementation|)}