VTK-m
2.0
|
An ArrayHandle of an unknown value type and storage. More...
#include <UnknownArrayHandle.h>
Public Member Functions | |
VTKM_CONT | UnknownArrayHandle ()=default |
template<typename T , typename S > | |
VTKM_CONT | UnknownArrayHandle (const vtkm::cont::ArrayHandle< T, S > &array) |
VTKM_CONT bool | IsValid () const |
Returns whether an array is stored in this UnknownArrayHandle . More... | |
VTKM_CONT UnknownArrayHandle | NewInstance () const |
Create a new array of the same type as this array. More... | |
VTKM_CONT UnknownArrayHandle | NewInstanceBasic () const |
Create a new ArrayHandleBasic with the same ValueType as this array. More... | |
VTKM_CONT UnknownArrayHandle | NewInstanceFloatBasic () const |
Create a new ArrayHandleBasic with the base component of FloatDefault More... | |
VTKM_CONT std::string | GetValueTypeName () const |
Returns the name of the value type stored in the array. More... | |
VTKM_CONT std::string | GetBaseComponentTypeName () const |
Returns the name of the base component of the value type stored in the array. More... | |
VTKM_CONT std::string | GetStorageTypeName () const |
Returns the name of the storage tag for the array. More... | |
VTKM_CONT std::string | GetArrayTypeName () const |
Returns a string representation of the underlying data type. More... | |
template<typename ValueType > | |
VTKM_CONT bool | IsValueType () const |
Returns true if this array matches the ValueType template argument. More... | |
template<typename StorageType > | |
VTKM_CONT bool | IsStorageType () const |
Returns true if this array matches the StorageType template argument. More... | |
template<typename BaseComponentType > | |
VTKM_CONT bool | IsBaseComponentType () const |
Returns true if this array's ValueType has the provided base component type. More... | |
template<typename ArrayHandleType > | |
VTKM_CONT bool | IsType () const |
Returns true if this array matches the ArrayHandleType template argument. More... | |
template<typename NewValueTypeList , typename NewStorageTypeList > | |
VTKM_CONT vtkm::cont::UncertainArrayHandle< NewValueTypeList, NewStorageTypeList > | ResetTypes (NewValueTypeList=NewValueTypeList{}, NewStorageTypeList=NewStorageTypeList{}) const |
Assigns potential value and storage types. More... | |
VTKM_CONT vtkm::Id | GetNumberOfValues () const |
Returns the number of values in the array. More... | |
VTKM_CONT vtkm::IdComponent | GetNumberOfComponents () const |
Returns the number of components for each value in the array. More... | |
VTKM_CONT vtkm::IdComponent | GetNumberOfComponentsFlat () const |
Returns the total number of components for each value in the array. More... | |
template<typename ArrayHandleType > | |
VTKM_CONT bool | CanConvert () const |
Determine if the contained array can be passed to the given array type. More... | |
void | DeepCopyFrom (const vtkm::cont::UnknownArrayHandle &source) |
Deep copies data from another UnknownArrayHandle . More... | |
void | DeepCopyFrom (const vtkm::cont::UnknownArrayHandle &source) const |
Deep copies data from another UnknownArrayHandle . More... | |
void | CopyShallowIfPossible (const vtkm::cont::UnknownArrayHandle &source) |
Attempts a shallow copy of an array or a deep copy if that is not possible. More... | |
void | CopyShallowIfPossible (const vtkm::cont::UnknownArrayHandle &source) const |
Attempts a shallow copy of an array or a deep copy if that is not possible. More... | |
template<typename BaseComponentType > | |
VTKM_CONT vtkm::cont::ArrayHandleStride< BaseComponentType > | ExtractComponent (vtkm::IdComponent componentIndex, vtkm::CopyFlag allowCopy=vtkm::CopyFlag::On) const |
Extract a component of the array. More... | |
template<typename BaseComponentType > | |
VTKM_CONT vtkm::cont::ArrayHandleRecombineVec< BaseComponentType > | ExtractArrayFromComponents (vtkm::CopyFlag allowCopy=vtkm::CopyFlag::On) const |
Extract the array knowing only the component type of the array. More... | |
template<typename TypeList , typename StorageList , typename Functor , typename... Args> | |
VTKM_CONT void | CastAndCallForTypes (Functor &&functor, Args &&... args) const |
Call a functor using the underlying array type. More... | |
template<typename TypeList , typename StorageList , typename Functor , typename... Args> | |
VTKM_CONT void | CastAndCallForTypesWithFloatFallback (Functor &&functor, Args &&... args) const |
Call a functor using the underlying array type with a float cast fallback. More... | |
template<typename Functor , typename... Args> | |
VTKM_CONT void | CastAndCallWithExtractedArray (Functor &&functor, Args &&... args) const |
Call a functor on an array extracted from the components. More... | |
VTKM_CONT void | ReleaseResourcesExecution () const |
Releases any resources being used in the execution environment (that are not being shared by the control environment). More... | |
VTKM_CONT void | ReleaseResources () const |
Releases all resources in both the control and execution environments. More... | |
VTKM_CONT void | PrintSummary (std::ostream &out, bool full=false) const |
template<typename T , typename... Ss> | |
void | AsArrayHandle (vtkm::cont::ArrayHandle< T, vtkm::cont::StorageTagMultiplexer< Ss... >> &array) const |
template<typename TypeList , typename StorageTagList , typename Functor , typename... Args> | |
void | CastAndCallForTypes (Functor &&f, Args &&... args) const |
template<typename Functor , typename... Args> | |
void | CastAndCallWithExtractedArray (Functor &&functor, Args &&... args) const |
VTKM_CONT void | Allocate (vtkm::Id numValues, vtkm::CopyFlag preserve, vtkm::cont::Token &token) const |
Reallocate the data in the array. More... | |
VTKM_CONT void | Allocate (vtkm::Id numValues, vtkm::CopyFlag preserve=vtkm::CopyFlag::Off) const |
Reallocate the data in the array. More... | |
template<typename T , typename S > | |
VTKM_CONT void | AsArrayHandle (vtkm::cont::ArrayHandle< T, S > &array) const |
template<typename T , typename... Ss> | |
VTKM_CONT void | AsArrayHandle (vtkm::cont::ArrayHandle< T, vtkm::cont::StorageTagMultiplexer< Ss... >> &array) const |
template<typename TargetT , typename SourceT , typename SourceS > | |
VTKM_CONT void | AsArrayHandle (vtkm::cont::ArrayHandle< TargetT, vtkm::cont::StorageTagCast< SourceT, SourceS >> &array) const |
template<typename ArrayType > | |
VTKM_CONT ArrayType | AsArrayHandle () const |
Private Member Functions | |
VTKM_CONT bool | IsValueTypeImpl (std::type_index type) const |
VTKM_CONT bool | IsStorageTypeImpl (std::type_index type) const |
VTKM_CONT bool | IsBaseComponentTypeImpl (const detail::UnknownAHComponentInfo &type) const |
Private Attributes | |
std::shared_ptr< detail::UnknownAHContainer > | Container |
An ArrayHandle of an unknown value type and storage.
UnknownArrayHandle
holds an ArrayHandle
object using runtime polymorphism to manage different value and storage types rather than compile-time templates. This adds a programming convenience that helps avoid a proliferation of templates. It also provides the management necessary to interface VTK-m with data sources where types will not be known until runtime and is the storage mechanism for classes like DataSet
and Field
that can hold numerous types.
To interface between the runtime polymorphism and the templated algorithms in VTK-m, UnknownArrayHandle
contains a method named CastAndCallForTypes
that determines the correct type from some known list of value types and storage. This mechanism is used internally by VTK-m's worklet invocation mechanism to determine the type when running algorithms.
If the UnknownArrayHandle
is used in a context where the possible array types can be whittled down to a finite list (or you have to), you can specify lists of value types and storage using the ResetTypesAndStorage
method. This will convert this object to an UncertainArrayHandle
of the given types. In cases where a finite set of types need to specified but there is no known subset, VTKM_DEFAULT_TYPE_LIST
and VTKM_DEFAULT_STORAGE_LIST
can be used.
ArrayHandleCast
and ArrayHandleMultiplexer
are treated special. If the UnknownArrayHandle
is set to an ArrayHandle
of one of these types, it will actually store the ArrayHandle
contained. Likewise, if the ArrayHandle
is retrieved as one of these types, it will automatically convert it if possible.
|
default |
|
inline |
VTKM_CONT void vtkm::cont::UnknownArrayHandle::Allocate | ( | vtkm::Id | numValues, |
vtkm::CopyFlag | preserve, | ||
vtkm::cont::Token & | token | ||
) | const |
Reallocate the data in the array.
The allocation works the same as the Allocate
method of vtkm::cont::ArrayHandle
.
VTKM_CONT void vtkm::cont::UnknownArrayHandle::Allocate | ( | vtkm::Id | numValues, |
vtkm::CopyFlag | preserve = vtkm::CopyFlag::Off |
||
) | const |
Reallocate the data in the array.
The allocation works the same as the Allocate
method of vtkm::cont::ArrayHandle
.
|
inline |
Returns this array cast appropriately and stored in the given ArrayHandle
type. Throws an ErrorBadType
if the stored array cannot be stored in the given array type. Use the CanConvert
method to determine if the array can be returned with the given type.
|
inline |
Returns this array cast appropriately and stored in the given ArrayHandle
type. Throws an ErrorBadType
if the stored array cannot be stored in the given array type. Use the CanConvert
method to determine if the array can be returned with the given type.
VTKM_CONT void vtkm::cont::UnknownArrayHandle::AsArrayHandle | ( | vtkm::cont::ArrayHandle< T, vtkm::cont::StorageTagMultiplexer< Ss... >> & | array | ) | const |
Returns this array cast appropriately and stored in the given ArrayHandle
type. Throws an ErrorBadType
if the stored array cannot be stored in the given array type. Use the CanConvert
method to determine if the array can be returned with the given type.
void vtkm::cont::UnknownArrayHandle::AsArrayHandle | ( | vtkm::cont::ArrayHandle< T, vtkm::cont::StorageTagMultiplexer< Ss... >> & | array | ) | const |
|
inline |
Returns this array cast appropriately and stored in the given ArrayHandle
type. Throws an ErrorBadType
if the stored array cannot be stored in the given array type. Use the CanConvert
method to determine if the array can be returned with the given type.
VTKM_CONT bool vtkm::cont::UnknownArrayHandle::CanConvert |
Determine if the contained array can be passed to the given array type.
This method will return true if calling AsArrayHandle
of the given type will succeed. The result is similar to IsType
, and if IsType
returns true, then this will return true. However, this method will also return true for other types such as an ArrayHandleMultiplexer
that can contain the array.
|
inline |
VTKM_CONT void vtkm::cont::UnknownArrayHandle::CastAndCallForTypes | ( | Functor && | functor, |
Args &&... | args | ||
) | const |
Call a functor using the underlying array type.
CastAndCallForTypes
attempts to cast the held array to a specific value type, and then calls the given functor with the cast array. You must specify the TypeList
and StorageList
as template arguments.
After the functor argument you may add any number of arguments that will be passed to the functor after the converted ArrayHandle
.
VTKM_CONT void vtkm::cont::UnknownArrayHandle::CastAndCallForTypesWithFloatFallback | ( | Functor && | functor, |
Args &&... | args | ||
) | const |
Call a functor using the underlying array type with a float cast fallback.
CastAndCallForTypesWithFloatFallback
attempts to cast the held array to a specific value type, and then calls the given functor with the cast array. You must specify the TypeList
and StorageList
as template arguments.
After the functor argument you may add any number of arguments that will be passed to the functor after the converted ArrayHandle
.
If the underlying array does not match any of the requested array types, the array is copied to a new ArrayHandleBasic
with FloatDefault
components in its value and attempts to cast to those types.
VTKM_CONT void vtkm::cont::UnknownArrayHandle::CastAndCallWithExtractedArray | ( | Functor && | functor, |
Args &&... | args | ||
) | const |
Call a functor on an array extracted from the components.
CastAndCallWithExtractedArray
behaves similarly to CastAndCallForTypes
. It converts the contained data to an ArrayHandle
and calls a functor with that ArrayHandle
(and any number of optionally specified arguments).
The advantage of CastAndCallWithExtractedArray
is that you do not need to specify any TypeList
or StorageList
. Instead, it internally uses ExtractArrayFromComponents
to work with most ArrayHandle
types with only about 10 instances of the functor. In contrast, calling CastAndCallForTypes
with, for example, VTKM_DEFAULT_TYPE_LIST
and VTKM_DEFAULT_STORAGE_LIST
results in many more instances of the functor but handling many fewer types of ArrayHandle
.
There are, however, costs to using this method. Details of these costs are documented for the ExtractArrayFromComponents
method, but briefly they are that Vec
types get flattened, the resulting array has a strange Vec
-like value type that has many limitations on its use, there is an overhead for retrieving each value from the array, and there is a potential that data must be copied.
|
inline |
void vtkm::cont::UnknownArrayHandle::CopyShallowIfPossible | ( | const vtkm::cont::UnknownArrayHandle & | source | ) |
Attempts a shallow copy of an array or a deep copy if that is not possible.
This method takes an UnknownArrayHandle
and attempts to perform a shallow copy. This shallow copy occurs if this object points to an ArrayHandle
of the same type or does not point to any ArrayHandle
at all. If this is not possible, then the array is deep copied.
This method is roughly equivalent to the ArrayCopyShallowIfPossible
function (defined in vtkm/cont/ArrayCopy.h
). However, this method can be used without having to use a device compiler (whereas ArrayCopyShallowIfPossible
does require a device device compiler).
void vtkm::cont::UnknownArrayHandle::CopyShallowIfPossible | ( | const vtkm::cont::UnknownArrayHandle & | source | ) | const |
Attempts a shallow copy of an array or a deep copy if that is not possible.
This method takes an UnknownArrayHandle
and attempts to perform a shallow copy. This shallow copy occurs if this object points to an ArrayHandle
of the same type. If the types are incompatible, then the array is deep copied.
If this object does not point to an existing ArrayHandle
, this const version of CopyShallowIfPossible
throws an exception.
This method is roughly equivalent to the ArrayCopyShallowIfPossible
function (defined in vtkm/cont/ArrayCopy.h
). However, this method can be used without having to use a device compiler (whereas ArrayCopyShallowIfPossible
does require a device device compiler).
void vtkm::cont::UnknownArrayHandle::DeepCopyFrom | ( | const vtkm::cont::UnknownArrayHandle & | source | ) |
Deep copies data from another UnknownArrayHandle
.
This method takes an UnknownArrayHandle
and deep copies data from it.
If this object does not point to an existing ArrayHandle
, a new ArrayHandleBasic
with the same value type of the source
is created.
void vtkm::cont::UnknownArrayHandle::DeepCopyFrom | ( | const vtkm::cont::UnknownArrayHandle & | source | ) | const |
Deep copies data from another UnknownArrayHandle
.
This method takes an UnknownArrayHandle
and deep copies data from it.
If this object does not point to an existing ArrayHandle
, this const version of DeepCopyFrom
throws an exception.
|
inline |
Extract the array knowing only the component type of the array.
This method returns an ArrayHandle
that points to the data in the array. This method differs from AsArrayHandle
because you do not need to know the exact ValueType
and StorageTag
of the array. Instead, you only need to know the base component type.
ExtractArrayFromComponents
works by calling the ExtractComponent
method and then combining them together in a fancy ArrayHandle
. This allows you to ignore the storage type of the underlying array as well as any Vec
structure of the value type. However, it also places some limitations on how the data can be pulled from the data.
First, you have to specify the base component type. This must match the data in the underlying array (as reported by IsBaseComponentType
).
Second, the array returned will have the Vec
s flattened. For example, if the underlying array has a ValueType
of Vec<Vec<T, 3>, 3>
, then this method will tread the data as if it was Vec<T, 9>
. There is no way to get an array with Vec
of Vec
values.
Third, because the Vec
length of the values in the returned ArrayHandle
must be determined at runtime, that can break many assumptions of using Vec
objects. The type is not going to be a Vec<T,N>
type but rather an internal class that is intended to behave like that. The type should behave mostly like a Vec
, but will have some differences that can lead to unexpected behavior. For example, this Vec
-like object will not have a NUM_COMPONENTS
constant static expression because it is not known at compile time. (Use the GetNumberOfComponents
method instead.) And for the same reason you will not be able to pass these objects to classes overloaded or templated on the Vec
type. Also, these Vec
-like objects cannot be created as new instances. Thus, you will likely have to iterate over all components rather than do operations on the whole Vec
.
Fourth, because ExtractArrayFromComponents
uses ExtractComponent
to pull data from the array (which in turn uses ArrayExtractComponent
), there are some ArrayHandle
types that will require copying data to a new array. This could be problematic in cases where you want to write to the array. To prevent data from being copied, set the optional allowCopy
to vtkm::CopyFlag::Off
. This will cause an exception to be thrown if the resulting array cannot reference the memory held in this UnknownArrayHandle
.
Fifth, component arrays are extracted using ArrayHandleStride
as the representation for each component. This array adds a slight overhead for each lookup as it performs the arithmetic for finding the index of each component.
|
inline |
Extract a component of the array.
This method returns an array that holds the data for a given flat component of the data. The BaseComponentType
has to be specified and must match the contained array (i.e. the result of IsBaseComponentType
must succeed for the given type).
This method treats each value in the array as a flat Vec
even if it is a Vec
of Vec
s. For example, if the array actually holds values of type Vec<Vec<T, 3>, 2>
, it is treated as if it holds a Vec<T, 6>
. See vtkm::VecFlat
for details on how vectors are flattened.
The point of using ExtractComponent
over AsArrayHandle
is that it drastically reduces the amount of types you have to try. Most of the type the base component type is one of the basic C types (i.e. int
, long
, float
, etc.). You do not need to know what shape the containing Vec
is in, nor do you need to know the actual storage of the array.
Note that the type of the array returned is ArrayHandleStride
. Using this type of array handle has a slight overhead over basic arrays like ArrayHandleBasic
and ArrayHandleSOA
.
When extracting a component of an array, a shallow pointer to the data is returned whenever possible. However, in some circumstances it is impossible to conform the array. In these cases, the data are by default copied. If copying the data would cause problems (for example, you are writing into the array), you can select the optional allowCopy
flag to vtkm::CopyFlag::Off
. In this case, an exception will be thrown if the result cannot be represented by a shallow copy.
VTKM_CONT std::string vtkm::cont::UnknownArrayHandle::GetArrayTypeName | ( | ) | const |
Returns a string representation of the underlying data type.
The returned string will be of the form vtkm::cont::ArrayHandle<T, S>
rather than the name of an actual subclass. If no array is stored, an empty string is returned.
VTKM_CONT std::string vtkm::cont::UnknownArrayHandle::GetBaseComponentTypeName | ( | ) | const |
Returns the name of the base component of the value type stored in the array.
Returns an empty string if no array is stored.
VTKM_CONT vtkm::IdComponent vtkm::cont::UnknownArrayHandle::GetNumberOfComponents | ( | ) | const |
Returns the number of components for each value in the array.
If the array holds vtkm::Vec
objects, this will return the number of components in each value. If the array holds a basic C type (such as float
), this will return 1. If the array holds Vec
-like objects that have the number of components that can vary at runtime, this method will return 0 (because there is no consistent answer).
VTKM_CONT vtkm::IdComponent vtkm::cont::UnknownArrayHandle::GetNumberOfComponentsFlat | ( | ) | const |
Returns the total number of components for each value in the array.
If the array holds vtkm::Vec
objects, this will return the total number of components in each value assuming the object is flattened out to one level of Vec
objects. If the array holds a basic C type (such as float
), this will return 1. If the array holds a simple Vec
(such as vtkm::Vec3f
), this will return the number of components (in this case 3). If the array holds a hierarchy of Vec
s (such as vtkm::Vec<vtkm::Vec3f, 2>
), this will return the total number of vecs (in this case 6). If the array holds Vec
-like objects that have the number of components that can vary at runtime, this method will return 0 (because there is no consistent answer).
Returns the number of values in the array.
VTKM_CONT std::string vtkm::cont::UnknownArrayHandle::GetStorageTypeName | ( | ) | const |
Returns the name of the storage tag for the array.
Returns an empty string if no array is stored.
VTKM_CONT std::string vtkm::cont::UnknownArrayHandle::GetValueTypeName | ( | ) | const |
Returns the name of the value type stored in the array.
Returns an empty string if no array is stored.
|
inline |
Returns true if this array's ValueType
has the provided base component type.
The base component type is the recursive component type of any Vec
-like object. So if the array's ValueType
is vtkm::Vec<vtkm::Float32, 3>
, then the base component type will be vtkm::Float32
. Likewise, if the ValueType
is vtkm::Vec<vtkm::Vec<vtkm::Float32, 3>, 2>
, then the base component type is still vtkm::Float32
.
If the ValueType
is not Vec
-like type, then the base component type is the same. So a ValueType
of vtkm::Float32
has a base component type of vtkm::Float32
.
|
private |
|
inline |
Returns true if this array matches the StorageType template argument.
|
private |
|
inline |
Returns true if this array matches the ArrayHandleType template argument.
Note that UnknownArrayHandle
has some special handling for ArrayHandleCast
and ArrayHandleMultiplexer
. If you stored an array of one of these types into an UnknownArrayHandle
, the type of the underlying array will change and IsType
will fail. However, you can still get the array back out as that type using AsArrayHandle
.
Use the CanConvert
method instead to determine if the UnknownArrayHandle
contains an array that "matches" the array of a given type. Under most circumstances, you should prefer CanConvert
over IsType
.
VTKM_CONT bool vtkm::cont::UnknownArrayHandle::IsValid | ( | ) | const |
Returns whether an array is stored in this UnknownArrayHandle
.
If the UnknownArrayHandle
is constructed without an ArrayHandle
, it will not have an underlying type, and therefore the operations will be invalid. It is still possible to set this UnknownArrayHandle
to an ArrayHandle
.
|
inline |
Returns true if this array matches the ValueType template argument.
|
private |
VTKM_CONT UnknownArrayHandle vtkm::cont::UnknownArrayHandle::NewInstance | ( | ) | const |
Create a new array of the same type as this array.
This method creates a new array that is the same type as this one and returns a new UnknownArrayHandle
for it. This method is convenient when creating output arrays that should be the same type as some input array.
VTKM_CONT UnknownArrayHandle vtkm::cont::UnknownArrayHandle::NewInstanceBasic | ( | ) | const |
Create a new ArrayHandleBasic
with the same ValueType
as this array.
This method creates a new ArrayHandleBasic
that has the same ValueType
as the array held by this one and returns a new UnknownArrayHandle
for it. This method is convenient when creating output arrays that should have the same types of values of the input, but the input might not be a writable array.
VTKM_CONT UnknownArrayHandle vtkm::cont::UnknownArrayHandle::NewInstanceFloatBasic | ( | ) | const |
Create a new ArrayHandleBasic
with the base component of FloatDefault
This method creates a new ArrayHandleBasic
that has a ValueType
that is similar to the array held by this one except that the base component type is replaced with vtkm::FloatDefault
. For example, if the contained array has vtkm::Int32
value types, the returned array will have vtkm::FloatDefault
value types. If the contained array has vtkm::Id3
value types, the returned array will have vtkm::Vec3f
value types. If the contained array already has vtkm::FloatDefault
as the base component (e.g. vtkm::FloatDefault
, vtkm::Vec3f
, vtkm::Vec<vtkm::Vec2f, 3>
), then the value type will be preserved.
The created array is returned in a new UnknownArrayHandle
.
This method is used to convert an array of an unknown type to an array of an almost known type.
VTKM_CONT void vtkm::cont::UnknownArrayHandle::PrintSummary | ( | std::ostream & | out, |
bool | full = false |
||
) | const |
VTKM_CONT void vtkm::cont::UnknownArrayHandle::ReleaseResources | ( | ) | const |
Releases all resources in both the control and execution environments.
VTKM_CONT void vtkm::cont::UnknownArrayHandle::ReleaseResourcesExecution | ( | ) | const |
Releases any resources being used in the execution environment (that are not being shared by the control environment).
VTKM_CONT vtkm::cont::UncertainArrayHandle< NewValueTypeList, NewStorageTypeList > vtkm::cont::UnknownArrayHandle::ResetTypes | ( | NewValueTypeList | = NewValueTypeList{} , |
NewStorageTypeList | = NewStorageTypeList{} |
||
) | const |
Assigns potential value and storage types.
Calling this method will return an UncertainArrayHandle
with the provided value and storage type lists. The returned object will hold the same ArrayHandle
, but CastAndCall
s on the returned object will be constrained to the given types.
|
private |