vtkDataArrayRange.h File Reference

STL-compatible iterable ranges that provide access to vtkDataArray elements. More...

#include "vtkAOSDataArrayTemplate.h"
#include "vtkDataArray.h"
#include "vtkDataArrayMeta.h"
#include "vtkDataArrayTupleRange_AOS.h"
#include "vtkDataArrayTupleRange_Generic.h"
#include "vtkDataArrayValueRange_AOS.h"
#include "vtkDataArrayValueRange_Generic.h"
#include "vtkMeta.h"
#include "vtkSmartPointer.h"
#include <cassert>
#include <iterator>
#include <type_traits>

Include dependency graph for vtkDataArrayRange.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	vtk::detail::SelectTupleRange< ArrayTypePtr, TupleSize >
struct	vtk::detail::SelectValueRange< ArrayTypePtr, TupleSize >

Namespaces
namespace	vtk
	Specialization of tuple ranges and iterators for vtkAOSDataArrayTemplate.
namespace	vtk::detail

Functions
template<ComponentIdType TupleSize = detail::DynamicTupleSize, typename ArrayTypePtr = vtkDataArray*>
VTK_ITER_INLINE auto	vtk::DataArrayTupleRange (const ArrayTypePtr &array, TupleIdType start=-1, TupleIdType end=-1) -> typename detail::SelectTupleRange< ArrayTypePtr, TupleSize >::type
	Generate an stl and for-range compatible range of tuple iterators from a vtkDataArray. More...
template<ComponentIdType TupleSize = detail::DynamicTupleSize, typename ArrayTypePtr = vtkDataArray*>
VTK_ITER_INLINE auto	vtk::DataArrayValueRange (const ArrayTypePtr &array, ValueIdType start=-1, ValueIdType end=-1) -> typename detail::SelectValueRange< ArrayTypePtr, TupleSize >::type
	Generate an stl and for-range compatible range of flat AOS iterators from a vtkDataArray. More...

Detailed Description

STL-compatible iterable ranges that provide access to vtkDataArray elements.

The vtkDataArrayRange.h header provides utilities to convert vtkDataArrays into "range" objects that behave like STL ranges.

Note

Since the term 'range' is overloaded, it's worth pointing out that to determine the value-range of an array's elements (an unrelated concept to the Range objects defined here), see the vtkDataArray::GetRange and vtkGenericDataArray::GetValueRange methods.

There are two types of ranges: TupleRange and ValueRange.

See Testing/Cxx/ExampleDataArrayRangeAPI.cxx for an illustrative example of how these ranges and their associated iterators and references are used.

These ranges unify the different memory layouts supported by VTK and provide a consistent interface to processing them with high efficiency. Whether a range is constructed from a vtkDataArray, vtkFloatArray, or even vtkScaledSOADataArrayTemplate, the same range-based algorithm implementation can be used to provide the best performance possible using the input array's API.

Constructing a range using a derived subclass of vtkDataArray (such as vtkFloatArray) will always give better performance than a range constructed from a vtkDataArray pointer, since the vtkDataArray API requires virtual calls and type conversion. Using a more derived type generally allows the compiler to optimize out any function calls and emit assembly that directly operates on the array's raw memory buffer(s). See vtkArrayDispatch for utilities to convert an unknown vtkDataArray into a more derived type. Testing/Cxx/ExampleDataArrayRangeDispatch.cxx demonstrates how ranges may be used with the dispatcher system.

TupleRanges

A TupleRange traverses a vtkDataArray tuple-by-tuple, providing iterators and reference objects that refer to conceptual tuples. The tuple references themselves may be iterated upon to access individual components.

TupleRanges are created via the function vtk::DataArrayTupleRange. See that function's documentation for more information about creating TupleRanges.

ValueRanges

A ValueRange will traverse a vtkDataArray in "value index" order, e.g. as if walking a pointer into an AOS layout array:

Array:    {X, X, X}, {X, X, X}, {X, X, X}, ...
TupleIdx:  0  0  0    1  1  1    2  2  2
CompIdx:   0  1  2    0  1  2    0  1  2
ValueIdx:  0  1  2    3  4  5    6  7  8

ValueRanges are created via the function vtk::DataArrayValueRange. See that function's documentation for more information about creating ValueRanges.

Definition in file vtkDataArrayRange.h.