VTK  9.1.0
Namespaces | Classes | Typedefs | Enumerations | Functions
vtk Namespace Reference

Specialization of tuple ranges and iterators for vtkAOSDataArrayTemplate. More...

Namespaces

namespace  detail
 
namespace  hypertreegrid
 

Classes

class  CompositeDataSetNodeReference
 A reference proxy into a vtkCompositeDataSet, obtained by dereferencing an iterator from the vtk::Range(vtkCompositeDataSet*) overloads. More...
 

Typedefs

using ComponentIdType = int
 
using TupleIdType = vtkIdType
 
using ValueIdType = vtkIdType
 
template<typename ArrayType , typename = detail::EnableIfVtkDataArray<ArrayType>>
using GetAPIType = typename detail::GetAPITypeImpl< ArrayType >::APIType
 
template<typename ArrayType >
using IsAOSDataArray = std::integral_constant< bool, detail::IsAOSDataArrayImpl< ArrayType >::value >
 

Enumerations

enum class  CompositeDataSetOptions : unsigned int { None = 0 , SkipEmptyNodes = 1 << 1 }
 
enum class  DataObjectTreeOptions : unsigned int { None = 0 , SkipEmptyNodes = 1 << 1 , VisitOnlyLeaves = 1 << 2 , TraverseSubTree = 1 << 3 }
 

Functions

template<ComponentIdType TupleSize = detail::DynamicTupleSize, typename ArrayTypePtr = vtkDataArray*>
VTK_ITER_INLINE auto 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.
 
template<ComponentIdType TupleSize = detail::DynamicTupleSize, typename ArrayTypePtr = vtkDataArray*>
VTK_ITER_INLINE auto 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.
 
template<typename IterablePtr , typename... Options>
auto Range (IterablePtr iterable, Options &&... opts) -> typename detail::IterableTraits< typename detail::StripPointers< IterablePtr >::type >::RangeType
 Generate an iterable STL proxy object for a VTK container.
 
template<typename T >
vtkSmartPointer< T > MakeSmartPointer (T *obj)
 Construct a vtkSmartPointer<T> containing obj.
 
template<typename T >
vtkSmartPointer< T > TakeSmartPointer (T *obj)
 Construct a vtkSmartPointer<T> containing obj.
 
template<typename T >
vtkWeakPointer< T > TakeWeakPointer (T *obj)
 Construct a vtkWeakPointer<T> containing obj.
 

Detailed Description

Specialization of tuple ranges and iterators for vtkAOSDataArrayTemplate.

Compare smart pointer values.

Specialization of value ranges and iterators for vtkAOSDataArrayTemplate.

Generic implementation of value ranges and iterators, suitable for vtkDataArray and all subclasses.

Typedef Documentation

◆ ComponentIdType

using vtk::ComponentIdType = typedef int

Definition at line 68 of file vtkDataArrayMeta.h.

◆ TupleIdType

using vtk::TupleIdType = typedef vtkIdType

Definition at line 69 of file vtkDataArrayMeta.h.

◆ ValueIdType

using vtk::ValueIdType = typedef vtkIdType

Definition at line 70 of file vtkDataArrayMeta.h.

◆ GetAPIType

template<typename ArrayType , typename = detail::EnableIfVtkDataArray<ArrayType>>
using vtk::GetAPIType = typedef typename detail::GetAPITypeImpl<ArrayType>::APIType

Definition at line 188 of file vtkDataArrayMeta.h.

◆ IsAOSDataArray

template<typename ArrayType >
using vtk::IsAOSDataArray = typedef std::integral_constant<bool, detail::IsAOSDataArrayImpl<ArrayType>::value>

Definition at line 206 of file vtkDataArrayMeta.h.

Enumeration Type Documentation

◆ CompositeDataSetOptions

enum class vtk::CompositeDataSetOptions : unsigned int
strong
Enumerator
None 
SkipEmptyNodes 

Definition at line 34 of file vtkCompositeDataSetRange.h.

◆ DataObjectTreeOptions

enum class vtk::DataObjectTreeOptions : unsigned int
strong
Enumerator
None 
SkipEmptyNodes 
VisitOnlyLeaves 
TraverseSubTree 

Definition at line 34 of file vtkDataObjectTreeRange.h.

Function Documentation

◆ DataArrayTupleRange()

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.

This function returns a TupleRange object that is compatible with C++11 for-range syntax. As an example usage, consider a function that takes some instance of vtkDataArray (or a subclass) and prints the magnitude of each tuple:

template <typename ArrayType>
void PrintMagnitudes(ArrayType *array)
{
for (const auto tuple : vtk::DataArrayTupleRange(array))
{
double mag = 0.;
for (const T comp : tuple)
{
mag += static_cast<double>(comp) * static_cast<double>(comp);
}
mag = std::sqrt(mag);
std::cerr << mag < "\n";
}
}
VTK_ITER_INLINE auto 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.
typename detail::GetAPITypeImpl< ArrayType >::APIType GetAPIType

Note that ArrayType is generic in the above function. When vtk::DataArrayTupleRange is given a vtkDataArray pointer, the generated code produces iterators and reference proxies that rely on the vtkDataArray API. However, when a more derived ArrayType is passed in (for example, vtkFloatArray), specialized implementations are used that generate highly optimized code.

Performance can be further improved when the number of components in the array is known. By passing a compile-time-constant integer as a template parameter, e.g. vtk::DataArrayTupleRange<3>(array), specializations are enabled that allow the compiler to perform additional optimizations.

vtk::DataArrayTupleRange takes an additional two arguments that can be used to restrict the range of tuples to [start, end).

There is a compiler definition / CMake option called VTK_DEBUG_RANGE_ITERATORS that enables checks for proper usage of the range/iterator/reference classes. This slows things down significantly, but is useful for diagnosing problems.

In some situations, developers may want to build in Debug mode while still maintaining decent performance for data-heavy computations. For these usecases, an additional CMake option VTK_ALWAYS_OPTIMIZE_ARRAY_ITERATORS may be enabled to force optimization of code using these iterators. This option will force inlining and enable -O3 (or equivalent) optimization level for iterator code when compiling on platforms that support these features. This option has no effect when VTK_DEBUG_RANGE_ITERATORS is enabled.

Warning
Use caution when using auto to hold values or references obtained from iterators, as they may not behave as expected. This is a deficiency in C++ that affects all proxy iterators (such as those from vector<bool>) that use a reference object instead of an actual C++ reference type. When in doubt, use std::iterator_traits (along with decltype) or the typedefs listed below to determine the proper value/reference type to use. The examples below show how these may be used.

To mitigate this, the following types are defined on the range object:

  • Range::TupleIteratorType: Iterator that visits tuples.
  • Range::ConstTupleIteratorType: Const iterator that visits tuples.
  • Range::TupleReferenceType: Mutable tuple proxy reference.
  • Range::ConstTupleReferenceType: Const tuple proxy reference.
  • Range::ComponentIteratorType: Iterator that visits components in a tuple.
  • Range::ConstComponentIteratorType: Const iterator that visits tuple components.
  • Range::ComponentReferenceType: Reference proxy to a single tuple component.
  • Range::ConstComponentReferenceType: Const reference proxy to a single tuple component.
  • Range::ComponentType: ValueType of components.

These can be accessed via the range objects, e.g.:

auto range = vtk::DataArrayTupleRange(array);
using TupleRef = typename decltype(range)::TupleReferenceType;
using ComponentRef = typename decltype(range)::ComponentReferenceType;
for (TupleRef tuple : range)
{
for (ComponentRef comp : tuple)
{
comp = comp - 1; // Array is modified.
}
}
using ConstTupleRef = typename decltype(range)::ConstTupleReferenceType;
using ComponentType = typename decltype(range)::ComponentType;
for (ConstTupleRef tuple : range)
{
for (ComponentType comp : tuple)
{
comp = comp - 1; // Array is not modified.
}
}
@ range
Definition: vtkX3D.h:244

Definition at line 258 of file vtkDataArrayRange.h.

◆ DataArrayValueRange()

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.

This function returns a ValueRange object that is compatible with C++11 for-range syntax. The array is traversed as if calling vtkGenericDataArray::GetValue with consecutive, increasing indices. As an example usage, consider a function that takes some instance of vtkDataArray (or a subclass) and sums the values it contains:

template <typename ArrayType>
auto ComputeSum(ArrayType *array) -> vtk::GetAPIType<ArrayType>
{
T sum = 0.;
for (const T val : vtk::DataArrayValueRange(array))
{
sum += val;
}
return sum;
}
VTK_ITER_INLINE auto 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.

These ranges may also be used with STL algorithms:

template <typename ArrayType>
auto ComputeSum(ArrayType *array) -> vtk::GetAPIType<ArrayType>
{
const auto range = vtk::DataArrayValueRange(array);
return std::accumulate(range.begin(), range.end(), 0);
}

Note that ArrayType is generic in the above function. When vtk::DataArrayValueRange is given a vtkDataArray pointer, the generated code produces iterators and reference proxies that rely on the vtkDataArray API. However, when a more derived ArrayType is passed in (for example, vtkFloatArray), specialized implementations are used that generate highly optimized code.

Performance can be further improved when the number of components in the array is known. By passing a compile-time-constant integer as a template parameter, e.g. vtk::DataArrayValueRange<3>(array), specializations are enabled that allow the compiler to perform additional optimizations.

vtk::DataArrayValueRange takes an additional two arguments that can be used to restrict the range of values to [start, end).

There is a compiler definition / CMake option called VTK_DEBUG_RANGE_ITERATORS that enables checks for proper usage of the range/iterator/reference classes. This slows things down significantly, but is useful for diagnosing problems.

In some situations, developers may want to build in Debug mode while still maintaining decent performance for data-heavy computations. For these usecases, an additional CMake option VTK_ALWAYS_OPTIMIZE_ARRAY_ITERATORS may be enabled to force optimization of code using these iterators. This option will force inlining and enable -O3 (or equivalent) optimization level for iterator code when compiling on platforms that support these features. This option has no effect when VTK_DEBUG_RANGE_ITERATORS is enabled.

Warning
Use caution when using auto to hold values or references obtained from iterators, as they may not behave as expected. This is a deficiency in C++ that affects all proxy iterators (such as those from vector<bool>) that use a reference object instead of an actual C++ reference type. When in doubt, use std::iterator_traits (along with decltype) or the typedefs listed below to determine the proper value/reference type to use. The examples below show how these may be used.

To mitigate this, the following types are defined on the range object:

  • Range::IteratorType: Iterator that visits values in AOS order.
  • Range::ConstIteratorType: Const iterator that visits values in AOS order.
  • Range::ReferenceType: Mutable value proxy reference.
  • Range::ConstReferenceType: Const value proxy reference.
  • Range::ValueType: ValueType of array's API.

These can be accessed via the range objects, e.g.:

auto range = vtk::DataArrayValueRange(array);
using RefType = typename decltype(range)::ReferenceType;
for (RefType ref : range)
{ // `ref` is a reference (or reference proxy) to the data held by the array.
ref -= 1; // Array is modified.
}
using ValueType = typename decltype(range)::ValueType;
for (ValueType value : range)
{ // implicitly converts from a reference (or proxy) to a local lvalue `value`
value -= 1; // Array is not modified.
}

Definition at line 368 of file vtkDataArrayRange.h.

◆ Range()

template<typename IterablePtr , typename... Options>
auto vtk::Range ( IterablePtr  iterable,
Options &&...  opts 
) -> typename detail::IterableTraits<typename detail::StripPointers<IterablePtr>::type>::RangeType

Generate an iterable STL proxy object for a VTK container.

Currently supports:

Usage:

for (auto item : vtk::Range(myCollection))
{
// Use item.
}
// or:
using Opts = vtk::vtkDataObjectTreeOptions;
auto range = vtk::Range(dataObjTree,
Opts::TraverseSubTree | Opts::VisitOnlyLeaves);
some_algo(range.begin(), range.end());
auto Range(IterablePtr iterable, Options &&... opts) -> typename detail::IterableTraits< typename detail::StripPointers< IterablePtr >::type >::RangeType
Generate an iterable STL proxy object for a VTK container.
Definition: vtkRange.h:85

Definition at line 85 of file vtkRange.h.

◆ MakeSmartPointer()

template<typename T >
vtkSmartPointer< T > vtk::MakeSmartPointer ( T *  obj)

Construct a vtkSmartPointer<T> containing obj.

A new reference is added to obj.

Definition at line 449 of file vtkSmartPointer.h.

◆ TakeSmartPointer()

template<typename T >
vtkSmartPointer< T > vtk::TakeSmartPointer ( T *  obj)

Construct a vtkSmartPointer<T> containing obj.

obj's reference count is not changed.

Definition at line 457 of file vtkSmartPointer.h.

◆ TakeWeakPointer()

template<typename T >
vtkWeakPointer< T > vtk::TakeWeakPointer ( T *  obj)

Construct a vtkWeakPointer<T> containing obj.

obj's reference count is not changed.

Definition at line 300 of file vtkWeakPointer.h.