VdfInputValuesPointer< T > Class Template Reference

VdfInputValuesPointer is a smart pointer object that guarantees contiguous memory access to the requested input values, regardless of the actual memory layout in the output buffers. More...

#include <inputValuesPointer.h>

Inheritance diagram for VdfInputValuesPointer< T >:

Public Member Functions
	VdfInputValuesPointer (const VdfContext &context, const TfToken &inputName)
	Construct a new instance of this class with access to the input values provided by the input named inputName.
	~VdfInputValuesPointer ()
	Destructor.
const T *	GetData () const
	Returns an immutable raw pointer to the data.
size_t	GetSize () const
	Returns the size of the data in number of elements stored.
	operator TfSpan< const T > () const
	Construct a read-only TfSpan viewing this object's data.

Additional Inherited Members
Protected Member Functions inherited from VdfIterator
	~VdfIterator ()=default
	Disallow destruction via base class pointers.
const VdfNode &	_GetNode (const VdfContext &context) const
	Returns the current node being run.
const VdfExecutorInterface &	_GetExecutor (const VdfContext &context) const
	Returns the executor for the given context.
VDF_API const VdfVector *	_GetInputValue (const VdfContext &context, const VdfConnection &connection, const VdfMask &mask) const
	Returns a vector for reading an input value.
VDF_API const VdfVector &	_GetRequiredInputValue (const VdfContext &context, const VdfConnection &connection, const VdfMask &mask) const
	Returns the cached output value for a given output, or issues an error message if a cache value is not available.
VDF_API const VdfOutput *	_GetRequiredOutputForWriting (const VdfContext &context, const TfToken &name) const
	Returns the output for writing based on the name provided.
VDF_API VdfVector *	_GetOutputValueForWriting (const VdfContext &context, const VdfOutput &output) const
	Returns a vector for writing an output value into.
VDF_API bool	_GetOutputMasks (const VdfContext &context, const VdfOutput &output, const VdfMask **requestMask, const VdfMask **affectsMask) const
	Retrieves the request and affects masks of the given output.
VDF_API bool	_IsRequiredInput (const VdfContext &context, const VdfConnection &connection) const
	Returns true when the connection is scheduled and required, and false otherwise.
VDF_API const VdfMask *	_GetRequestMask (const VdfContext &context, const VdfOutput &output) const
	Returns the request mask of output, if the output has been scheduled and NULL otherwise.
VDF_API void	_ForEachScheduledOutput (const VdfContext &context, const VdfNode &node, const VdfScheduledOutputCallback &callback) const
	Loops over each scheduled output of node and calls callback with the output and request mask in an efficient manner.

Detailed Description

template<typename T>
class VdfInputValuesPointer< T >

VdfInputValuesPointer is a smart pointer object that guarantees contiguous memory access to the requested input values, regardless of the actual memory layout in the output buffers.

Warning

Due to performance caveats described below, accessing values through an iterator (e.g. VdfReadIterator) or the VdfContext is generally a better choice.

If the memory layout of input values is not contiguous in the output buffers, this class will make a copy of the input values in order to satisfy the contiguous access guarantees. Note that it can be expensive to make this copy. If necessary, the copy will be produced at time of construction.

If the memory layout of input values is already contiguous in the output buffers, this class will provide contiguous access into those buffers without making any copies.

Note that the memory layout of output buffers is an implementation detail of the system influenced by many factors. Subsequently, no assumptions can be made about whether copies will be made or not.

The only way to guarantee that no copies will be made is by accessing data through iterators (e.g. VdfReadIterator) or the VdfContext (e.g. VdfContext::GetInputValue). The use of iterators or the VdfContext instead of using VdfInputValuesPointer is strongly encouraged. When calling into functions, a good pattern is to parameterize said functions with iterator ranges, rather than raw pointers or specific container types.

template < Iterator >
MyFunction(Iterator begin, Iterator end)
{
    for (Iterator it = begin; it != end; ++it) {
        ...
    }
}

When using iterator ranges is not possible, for example when calling into functions from a third party library, VdfInputValuesPointer may be used to satisfy the required contiguous memory access guarantees.

VdfInputValuesPointer<GfVec3d> points(context, _tokens->points);
ThirdPartyFunction(points.GetData(), points.GetSize(), ...);

Definition at line 76 of file inputValuesPointer.h.

Constructor & Destructor Documentation

VdfInputValuesPointer()

VdfInputValuesPointer	(	const VdfContext &	context,
		const TfToken &	inputName
	)

Construct a new instance of this class with access to the input values provided by the input named inputName.

If the data provided by inputName is not contiguous in memory, the constructor will make a copy of the input values.

Definition at line 138 of file inputValuesPointer.h.

~VdfInputValuesPointer()

~VdfInputValuesPointer

Destructor.

Definition at line 217 of file inputValuesPointer.h.

Member Function Documentation

GetData()

const T * GetData ( ) const

inline

Returns an immutable raw pointer to the data.

Accessing data outside the bounds established by GetSize() is invalid and will lead to undefined behavior.

Definition at line 95 of file inputValuesPointer.h.

GetSize()

size_t GetSize ( ) const

inline

Returns the size of the data in number of elements stored.

Definition at line 101 of file inputValuesPointer.h.

operator TfSpan< const T >()

operator TfSpan< const T > ( ) const

inline

Construct a read-only TfSpan viewing this object's data.

This enables the use of VdfInputValuesPointer with template methods that require STL container API. This user-defined conversion is necessary because the API on this class is incompatible with the STL requirements of the implicit container-conversion constructor on TfSpan.

Definition at line 111 of file inputValuesPointer.h.

---

The documentation for this class was generated from the following file:

• pxr/exec/vdf/inputValuesPointer.h