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. More...
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. More...
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. More...
template<typename T >
vtkSmartPointer< T >	MakeSmartPointer (T *obj)
	Construct a vtkSmartPointer<T> containing obj. More...
template<typename T >
vtkSmartPointer< T >	TakeSmartPointer (T *obj)
	Construct a vtkSmartPointer<T> containing obj. More...
template<typename T >
vtkWeakPointer< T >	TakeWeakPointer (T *obj)
	Construct a vtkWeakPointer<T> containing obj. More...

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)
{
  using T = vtk::GetAPIType<ArrayType>;
 
  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";
  }
}

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.
  }
}

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

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:

• vtkCollection and subclasses (#include <vtkCollectionRange.h>):
  • ItemType is the (non-pointer) result type of GetNextItem() if this method exists on the collection type, otherwise vtkObject is used.
  • Iterators fulfill the STL InputIterator concept with some exceptions:
    • Const iterators/references are mutable, since vtkObjects are generally unusable when const.
    • Value/pointer/reference types are just ItemType*, since:
      • Plain ItemType wouldn't be usable (vtkObjects cannot be copied/assigned)
      • ItemType*& references aren't generally desired.
      • ItemType& references are unconventional for vtkObjects.
      • ItemType** pointers are unruly.
• vtkCompositeDataSet (#include <vtkCompositeDataSetRange.h>)
  • vtk::CompositeDataSetOptions: None, SkipEmptyNodes.
    • Ex. vtk::Range(compDS, vtk::CompositeDataSetOptions::SkipEmptyNodes);
  • Reverse iteration is not supported. Use vtkCompositeDataIterator directly instead for this.
  • Dereferencing the iterator yields a vtk::CompositeDataSetNodeReference that provides additional API to get the node's flat index, data object, and metadata. See that class's documentation for more information.
• vtkDataObjectTree (#include <vtkDataObjectTreeRange.h>)
  • vtk::DataObjectTreeOptions: None, SkipEmptyNodes, VisitOnlyLeaves, TraverseSubTree.
    • Ex. vtk::Range(dObjTree, vtk::DataObjectTreeOptions::TraverseSubTree | vtk::DataObjectTreeOptions::SkipEmptyNodes);
  • Reverse iteration is not supported. Use vtkDataObjectTreeIterator directly instead for this.
  • Dereferencing the iterator yields a vtk::CompositeDataSetNodeReference that provides additional API to get the node's flat index, data object, and metadata. See that class's documentation for more information.

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());

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.