pySpan.h File Reference

Python argument conversion for TfSpan<T>. More...

Include dependency graph for pySpan.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
template<class Source , class T >
void	TfPyRegisterSpanSource ()
	Register the wrapped C++ type Source as a span source for TfSpan<T>.
template<class T >
void	TfPyRegisterSpanBufferLayout (char scalarFormat, std::initializer_list< Py_ssize_t > elemShape={})
	Register the buffer layout of T: a C-contiguous array of elemShape-shaped blocks of scalars described by the struct-module format character scalarFormat.

Detailed Description

Python argument conversion for TfSpan<T>.

TfSpan is a view type: it does not own its elements. Boost.python's registry-based rvalue conversions construct their result in storage that is destroyed before the wrapped function is called if that result depends on a temporary, so TfSpan opts out of them (see pxr_boost_python_view_type in tf/span.h) and instead provides arg_rvalue_from_python specializations here. Any translation unit that wraps a function taking a TfSpan must include this header.

A Python argument is converted to TfSpan<T> by trying, in order:

1. Registered span sources for T (see TfPyRegisterSpanSource()). These produce a view of an existing wrapped C++ container with no copy.
2. The buffer protocol, if a buffer layout is registered for T (see TfPyRegisterSpanBufferLayout()) and the object exports a C-contiguous buffer with matching element format and shape. No copy. Layouts for bool and the builtin integer and floating-point types are registered by Tf; libraries register layouts for their own types.
3. For const T only, a Python sequence whose items each convert to T. The items are copied into storage owned by the converter for the duration of the call.

Mutable spans are never satisfied by copying, since writes through the span would be silently discarded. Use them for data that must be edited in place, such as images or mesh points. To accept arbitrary sequences, wrap a function that returns a new array instead.

Definition in file pySpan.h.

Function Documentation

TfPyRegisterSpanBufferLayout()

template<class T >

void TfPyRegisterSpanBufferLayout	(	char	scalarFormat,
		std::initializer_list< Py_ssize_t >	elemShape = {} )

Register the buffer layout of T: a C-contiguous array of elemShape-shaped blocks of scalars described by the struct-module format character scalarFormat.

Buffers with one leading dimension followed by elemShape, and a scalar format of matching kind and size, will convert to TfSpan<T> with no copy. For example, GfVec3f is registered with format 'f' and shape {3}, and accepts buffers of shape (N, 3). This function acquires the GIL, so once Python is initialized it may be called from any thread.

Definition at line 142 of file pySpan.h.

TfPyRegisterSpanSource()

template<class Source , class T >

void TfPyRegisterSpanSource

(

)

Register the wrapped C++ type Source as a span source for TfSpan<T>.

Python objects that hold a Source will convert to TfSpan<const T> as a view of the held elements, by converting a const Source to TfSpan<const T>. If T is not const, they will also convert to TfSpan<T>, by converting a non-const Source to TfSpan<T>. This function acquires the GIL, so once Python is initialized it may be called from any thread.

Definition at line 120 of file pySpan.h.