Commit 1dabc5ce authored by David C. Lonie's avatar David C. Lonie

Documentation updates.

parent c9b41f8a
......@@ -620,6 +620,9 @@ struct vtkArrayDownCast_impl
// However, not all arrays support the FastDownCast mechanism. vtkArrayDownCast
// exists to select between the two; Arrays that support FastDownCast will use
// it, while others will fallback to the slower SafeDownCast.
//
// A more detailed description of this class and related tools can be found
// \ref VTK-7-1-ArrayDispatch "here".
template <typename ArrayT>
ArrayT* vtkArrayDownCast(vtkAbstractArray *array)
{
......
......@@ -12,13 +12,16 @@
PURPOSE. See the above copyright notice for more information.
=========================================================================*/
// .NAME vtkArrayDispatch - vtkDataArray code generator
// .NAME vtkArrayDispatch - vtkDataArray code generator/dispatcher.
//
// vtkArrayDispatch implements a mechanism for generating optimized code for
// multiple subclasses of vtkDataArray at once. Using a TypeList based
// approach (see vtkTypeList), a templated worker implementation is generated
// for a restricted or unrestricted set of vtkDataArray subclasses.
//
// A more detailed description of this class and related tools can be found
// \ref VTK-7-1-ArrayDispatch "here".
//
// The primary goals of this class are to simplify multi-array dispatch
// implementations, and provide tools to lower compilation time and binary
// size (i.e. avoiding 'template explosions').
......@@ -99,13 +102,17 @@
// There are three components to a dispatch: The dispatcher, the worker, and
// the array(s). They are combined like so:
//
// @code
// bool result = Dispatcher<...>::Execute(array, worker);
// @endcode
//
// The dispatcher can also be instantiated into an object, e.g.:
//
// @code
// vtkArrayDispatch::SomeDispatcher<...> myDispatcher;
// MyWorker worker;
// bool result = myDispatcher.Execute(array, worker);
// @endcode
//
// Return value:
// The Execute method of the dispatcher will return true if a code path matching
......@@ -122,6 +129,7 @@
// additional input/output data is needed.
//
// A simple worker implementation for triple dispatch:
// @code
// struct MyWorker
// {
// template <typename Array1T, typename Array2T, typename Array3T>
......@@ -130,6 +138,7 @@
// // Do work using vtkGenericDataArray API...
// }
// };
// @endcode
//
// Note that optimized implementations (e.g. for AoS arrays vs SoA arrays) can
// be supported by providing overloads of operator() that have more restrictive
......
......@@ -12,6 +12,7 @@
PURPOSE. See the above copyright notice for more information.
=========================================================================*/
// .NAME VTK_ASSUME - Provide compiler hints for non-obvious conditions.
#ifndef vtkAssume_h
#define vtkAssume_h
......@@ -31,6 +32,9 @@
// VTK_ASSUME(array->GetNumberOfComponents() == 3); allows the compiler to
// provide faster access through the GetTypedComponent method, as the fixed data
// stride in AOS arrays allows advanced optimization of the accesses.
//
// A more detailed description of this class and related tools can be found
// \ref VTK-7-1-ArrayDispatch "here".
#define VTK_ASSUME(cond) \
do { \
const bool c = cond; \
......
......@@ -19,6 +19,9 @@
// vtkDataArrayAccessor provides access to data stored in a vtkDataArray. It
// is intended to be used in conjunction with vtkArrayDispatcher.
//
// A more detailed description of this class and related tools can be found
// \ref VTK-7-1-ArrayDispatch "here".
//
// The goal of this helper template is to allow developers to write a single
// templated worker function that will generates code to use the efficient typed
// APIs provided by vtkGenericDataArray when the array type is known, but
......@@ -37,31 +40,33 @@
//
// A standard usage pattern of this class would be:
//
// // vtkArrayDispatch worker struct:
// struct Worker
// {
// // Templated worker function:
// template <typename ArrayT>
// void operator()(ArrayT *array)
// {
// // The accessor:
// vtkDataArrayAccessor<ArrayT> accessor(array);
// // The data type used by ArrayT's API, use this for
// // temporary/intermediate results:
// typedef typename vtkDataArrayAccessor<ArrayT>::APIType APIType;
// @code
// // vtkArrayDispatch worker struct:
// struct Worker
// {
// // Templated worker function:
// template <typename ArrayT>
// void operator()(ArrayT *array)
// {
// // The accessor:
// vtkDataArrayAccessor<ArrayT> accessor(array);
// // The data type used by ArrayT's API, use this for
// // temporary/intermediate results:
// typedef typename vtkDataArrayAccessor<ArrayT>::APIType APIType;
//
// // Do work using accessor to set/get values....
// }
// };
// // Do work using accessor to set/get values....
// }
// };
//
// // Usage:
// Worker worker;
// vtkDataArray *array = ...;
// if (!vtkArrayDispatch::Dispatch::Execute(array, worker))
// {
// // Dispatch failed: unknown array type. Fallback to vtkDataArray API:
// worker(array);
// }
// // Usage:
// Worker worker;
// vtkDataArray *array = ...;
// if (!vtkArrayDispatch::Dispatch::Execute(array, worker))
// {
// // Dispatch failed: unknown array type. Fallback to vtkDataArray API:
// worker(array);
// }
// @endcode
//
// We define Worker::operator() as the templated worker function, restricting
// all data accesses to go through the 'accessor' object (methods like
......
......@@ -17,6 +17,9 @@
//
// .SECTION Description
//
// A more detailed description of this class and related tools can be found
// \ref VTK-7-1-ArrayDispatch "here".
//
// The vtkGenericDataArray class provides a generic implementation of the
// vtkDataArray API. It relies on subclasses providing access to data
// via 8 "concept methods", which should be implemented as non-virtual
......
......@@ -688,6 +688,9 @@ virtual double *Get##name() \
return thisClass::New(); \
}
// NOTE: This is no longer the prefer method for dispatching an array to a
// worker template. See vtkArrayDispatch for the new approach.
//
// The vtkTemplateMacro is used to centralize the set of types
// supported by Execute methods. It also avoids duplication of long
// switch statement case lists.
......
This diff is collapsed.
......@@ -132,3 +132,27 @@ vtkSMPTools
The following back-ends have been removed:
+ Simple: This is not a production level backend and was only used for debugging purposes.
+ Kaapi: This backend is no longer maintained.
vtkDataArray Refactor, vtkArrayDispatch and Related Tools
---------------------------------------------------------
The `vtkDataArrayTemplate` template class has been replaced by
`vtkAOSDataArrayTemplate` to distinguish it from the new
`vtkSOADataArrayTemplate`. The former uses Array-Of-Structs component ordering
while the latter uses Struct-Of-Arrays component ordering. These both derive
from the new `vtkGenericDataArray` template class and are an initial
implementation of native support for alternate memory layouts in VTK.
To facilitate working with these arrays efficiently, several new tools have
been added in this release. They are detailed \ref VTK-7-1-ArrayDispatch "here".
As part of the refactoring effort, several `vtkDataArrayTemplate` methods were
deprecated and replaced with new, const-correct methods with more meaningful
names.
The old and new method names are listed below:
+ `GetTupleValue` is now `GetTypedTuple`
+ `SetTupleValue` is now `SetTypedTuple`
+ `InsertTupleValue` is now `InsertTypedTuple`
+ `InsertNextTupleValue` is now `InsertNextTypedTuple`
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment