VTK  9.2.20230606
Namespaces | Classes | Typedefs | Enumerations | Functions
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:

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

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)
{
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.:

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:250

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>
{
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.:

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.
}
@ value
Definition: vtkX3D.h:232

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:

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:86

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)