vtk Namespace Reference

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

Namespaces
	detail
	hypertreegrid
	literals

Classes
class	HasSuperclass
	Determine whether the provided class (VTKObjectType ) has a parent class. More...
struct	ParentClasses
	Invoke a functor on the named type and each of its parent types. More...
struct	ParentClasses< VTKObjectType, false >
struct	ParentClasses< VTKObjectType, true >
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 ObjectType >
std::string	TypeName ()
	Return the demangled type-name of the provided ObjectType. More...
template<typename ObjectType >
vtkStringToken	TypeToken ()
	Return a string token holding a hash of the demangled type-name of the provided ObjectType. More...
template<typename T >
vtkWeakPointer< T >	TakeWeakPointer (T *obj)
	Construct a vtkWeakPointer<T> containing obj. More...
vtkSmartPointer< vtkCompositeArray< T > >	ConcatenateDataArrays (const std::vector< vtkDataArray * > &arrays)
template<typename VTKObjectType , typename Container >
void	Inherits (Container &container)
	Populate the container with the name of this class and its ancestors. More...
template<typename VTKObjectType , typename StopAtType , typename Container >
void	Inherits (Container &container)
	Populate the container with the name of this class and its ancestors. More...

Detailed Description

Specialization of tuple ranges and iterators for vtkAOSDataArrayTemplate.

This file contains the traits for the implicit array mechanism in VTK.

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.

These traits are very much an internal to vtkImplicitArrays and normal developers looking to develop a new vtkImplicitArray should (ideally) not have to open this file.

In order to ensure that template parameters passed to the vtkImplicitArray share a common interface without having to subclass all of them from the same abstract class, we have decided to use a trait mechanism to statically dispatch the functionalities of types passed as template parameters to the array.

There is 1 mandatory traits that a template type to vtkImplicitArray must implement:

• has_map_trait || is_closure_trait: ensures an implementation of int -> value

Potential improvements to implicit arrays which would allow for write access would include the following 2 optional traits:

• has_insert_trait || is_reference_closure_trait: provides an implementation to update the internals of the template type to add or set new values to the array
• has_remove_trait: provides an implementation to update the internals of the template to remove values from the array

All the traits defining the behavior of the implicit "function" or "backend" to the vtkImplicitArray should be composited into the implicit_array_traits

Typedef Documentation

ComponentIdType

using vtk::ComponentIdType = typedef int

Definition at line 71 of file vtkDataArrayMeta.h.

TupleIdType

using vtk::TupleIdType = typedef vtkIdType

Definition at line 72 of file vtkDataArrayMeta.h.

ValueIdType

using vtk::ValueIdType = typedef vtkIdType

Definition at line 73 of file vtkDataArrayMeta.h.

GetAPIType

template<typename ArrayType , typename = detail::EnableIfVtkDataArray<ArrayType>>

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

Definition at line 196 of file vtkDataArrayMeta.h.

IsAOSDataArray

template<typename ArrayType >

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

Definition at line 219 of file vtkDataArrayMeta.h.

Enumeration Type Documentation

CompositeDataSetOptions

enum vtk::CompositeDataSetOptions : unsigned int

strong

Enumerator
None
SkipEmptyNodes

Definition at line 33 of file vtkCompositeDataSetRange.h.

DataObjectTreeOptions

enum vtk::DataObjectTreeOptions : unsigned int

strong

Enumerator
None
SkipEmptyNodes
VisitOnlyLeaves
TraverseSubTree

Definition at line 33 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 260 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 370 of file vtkDataArrayRange.h.

Inherits() [1/2]

template<typename VTKObjectType , typename Container >

void vtk::Inherits

(

Container &

container

)

Populate the container with the name of this class and its ancestors.

The VTKObjectType template-parameter should be a subclass of vtkObjectBase that uses the vtkTypeMacro() to define a Superclass type-alias, as this is how the inheritance hierarchy is traversed.

The version of this function that accepts 2 template parameters uses the second parameter to iterate over a partial hierarchy truncated at (not including) the StopAtType.

Definition at line 161 of file vtkInherits.h.

Inherits() [2/2]

template<typename VTKObjectType , typename StopAtType , typename Container >

void vtk::Inherits

(

Container &

container

)

Populate the container with the name of this class and its ancestors.

The VTKObjectType template-parameter should be a subclass of vtkObjectBase that uses the vtkTypeMacro() to define a Superclass type-alias, as this is how the inheritance hierarchy is traversed.

The version of this function that accepts 2 template parameters uses the second parameter to iterate over a partial hierarchy truncated at (not including) the StopAtType.

Definition at line 168 of file vtkInherits.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 86 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 480 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 488 of file vtkSmartPointer.h.

TypeName()

template<typename ObjectType >

std::string vtk::TypeName ( )

inline

Return the demangled type-name of the provided ObjectType.

Note that if the <cxxabi.h> header is not present or does not provide abi::__cxa_demangle(), a mangled name will be returned.

Definition at line 110 of file vtkTypeName.h.

TypeToken()

template<typename ObjectType >

vtkStringToken vtk::TypeToken ( )

inline

Return a string token holding a hash of the demangled type-name of the provided ObjectType.

Note that this function should become constexpr, so the hash will be computed at compile time (once VTK allows c++14 extensions). Because of this, the string for the hash cannot be added to the vtkStringManager and thus may cause exceptions later.

Definition at line 126 of file vtkTypeName.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 307 of file vtkWeakPointer.h.

ConcatenateDataArrays()

vtkSmartPointer<vtkCompositeArray<T> > vtk::ConcatenateDataArrays

(

const std::vector< vtkDataArray * > &

arrays

)