Container Bindings

Binding allows Intel(R) Array Building Blocks (Intel(R) ArBB) containers to use existing C++ data directly.

You can bind dense containers (see Dense Containers) to C++ data using the arbb::bind() family of functions. When a container is bound, reading from that container provides the bound values, and assigning to that container updates the bound values.

For bindings to have effect, you must use the Container Data Access functions. Once a container is bound, any changes in the data it is bound to must be preceded by a call to arbb::dense::read_write_range() or arbb::dense::write_only_range(). Otherwise, reading from the bound data will yield unspecified results. The validity of these range calls extends up to the next ArBB operation involving the bound container. See Container Data Access for details.

Note:

You can improve the performance of bound containers by aligning the allocated data using the Alignment macros and functions.

The following code example shows how you can use bindings:

 // Allocate 1024 floating point elements on the stack.
 ARBB_CPP_ALIGN(float data[1024]);

 // Fill the data with some values.
 std::fill(data, data + 1024, 1.0f);

 // Construct a dense container and bind it to the data.
 arbb::dense<arbb::f32> container;
 arbb::bind(container, data, 1024);

 // At this point, attempting to read or write to the user data
 // results have undefined behavior.

 // The following operation affects the bound data.
 container = container + 1.0f;

 // You must call a read range function before reading the values.
 container.read_only_range(); // ...or read_write_range()

 // Read some data and print it to standard output.
 std::cout << data[0] << std::endl;

 // At this point, you must call a write range function before
 // you modify the data.
 container.write_only_range(); // ...or read_write_range()

 // Write to the user data.
 data[0] = 1.0f;

 // Perform another Intel(R) ArBB operation on the container.
 container = container * 2.0f;

 // Now you must call a range function again before you read or
 // write the data, because the previous operation invalidated
 // the above ranges.

Ranges obtained from bound containers can also be used directly, rather than accessing the bound data. When such a range is accessed, it reads from or writes to the user data directly.

You must always provide the size of the data to be bound. Additionally, pitches (in bytes) along each dimension can be passed to the binding, specifying the increment in bytes necessary to move from an entry to the next entry along the given dimension. By default, data is assumed to be stored contiguously. For 2D containers, row-major storage is assumed. For 3D containers, page-major row-major storage is assumed.

Containers with user-defined element types (see User-defined Types) can also be bound. In this case, a binding must be provided for every member in the element type. Since each member may have its own pitches, both structure-of-array and array-of-structure data formats can be used.

See Also

Dense Containers
Container Data Access
Alignment
User-defined Types

Functions

template<typename T , std::size_t D>
detail::enable_if
< detail::is_scalar< T >
::value >::type 
arbb::bind (dense< T, D > &container, typename uncaptured< T >::type *data, const array< std::size_t, D > &size)
 Binds a dense container of scalars to user data.
template<typename T , std::size_t D>
detail::enable_if
< detail::is_scalar< T >
::value >::type 
arbb::bind (dense< T, D > &container, typename uncaptured< T >::type *data, const array< std::size_t, D > &size, const array< std::size_t, D > &pitch)
 Binds a dense container of scalars to strided user data.
template<typename T >
detail::enable_if
< detail::is_scalar< T >
::value >::type 
arbb::bind (dense< T > &container, typename uncaptured< T >::type *data, std::size_t size)
 Binds a 1D dense container to user data.
template<typename T >
detail::enable_if
< detail::is_scalar< T >
::value >::type 
arbb::bind (dense< T, 2 > &container, typename uncaptured< T >::type *data, std::size_t width, std::size_t height)
 Binds a 2D dense container of scalars to user data.
template<typename T >
detail::enable_if
< detail::is_scalar< T >
::value >::type 
arbb::bind (dense< T, 3 > &container, typename uncaptured< T >::type *data, std::size_t width, std::size_t height, std::size_t depth)
 Binds a 3D dense container of scalars to user data.
template<typename T >
detail::enable_if
< detail::is_scalar< T >
::value >::type 
arbb::bind (dense< T > &container, typename uncaptured< T >::type *data, std::size_t size, std::size_t pitch)
 Binds a 1D dense container of scalars to strided user data.
template<typename T >
detail::enable_if
< detail::is_scalar< T >
::value >::type 
arbb::bind (dense< T, 2 > &container, typename uncaptured< T >::type *data, std::size_t width, std::size_t height, std::size_t col_pitch, std::size_t row_pitch)
 Binds a 2D dense container of scalars to strided user data.
template<typename T >
detail::enable_if
< detail::is_scalar< T >
::value >::type 
arbb::bind (dense< T, 3 > &container, typename uncaptured< T >::type *data, std::size_t width, std::size_t height, std::size_t depth, std::size_t col_pitch, std::size_t row_pitch, std::size_t page_pitch)
 Binds a 3D dense container of scalars to strided user data.
template<typename T , std::size_t D>
detail::disable_if
< detail::is_scalar< T >
::value >::type 
arbb::bind (dense< T, D > &container, const array< std::size_t, D > &size, void *member1_data,...)
 Binds a dense container of user-defined type to user data.
template<typename T >
detail::disable_if
< detail::is_scalar< T >
::value >::type 
arbb::bind (dense< T, 1 > &container, const array< std::size_t, 1 > &size, void *member1_data, array< std::size_t, 1 > pitch1,...)
 Binds a dense container of user-defined type to strided user data.
template<typename T >
detail::disable_if
< detail::is_scalar< T >
::value >::type 
arbb::bind (dense< T, 2 > &container, const array< std::size_t, 2 > &size, void *member1_data, array< std::size_t, 2 > pitch1,...)
 Binds a dense container of user-defined type to strided user data.
template<typename T >
detail::disable_if
< detail::is_scalar< T >
::value >::type 
arbb::bind (dense< T, 3 > &container, const array< std::size_t, 3 > &size, void *member1_data, array< std::size_t, 3 > pitch1,...)
 Binds a dense container of user-defined type to strided user data.
template<typename T >
detail::disable_if
< detail::is_scalar< T >
::value >::type 
arbb::bind (dense< T > &container, std::size_t size, void *member1_data,...)
 Binds a 1D dense container of user-defined type to user data.
template<typename T >
detail::disable_if
< detail::is_scalar< T >
::value >::type 
arbb::bind (dense< T, 2 > &container, std::size_t width, std::size_t height, void *member1_data,...)
 Binds a 2D dense container of user-defined type to user data.
template<typename T >
detail::disable_if
< detail::is_scalar< T >
::value >::type 
arbb::bind (dense< T, 3 > &container, std::size_t width, std::size_t height, std::size_t depth, void *member1_data,...)
 Binds a 3D dense container of user-defined type to user data.
template<typename T >
detail::disable_if
< detail::is_scalar< T >
::value >::type 
arbb::bind (dense< T > &container, std::size_t size, void *member1_data, std::size_t pitch1,...)
 Binds a 1D dense container of user-defined type to strided user data.
template<typename T >
detail::disable_if
< detail::is_scalar< T >
::value >::type 
arbb::bind (dense< T, 2 > &container, std::size_t width, std::size_t height, void *member1_data, std::size_t col_pitch1, std::size_t row_pitch1,...)
 Binds a 2D dense container of user-defined type to strided user data.
template<typename T >
detail::disable_if
< detail::is_scalar< T >
::value >::type 
arbb::bind (dense< T, 3 > &container, std::size_t width, std::size_t height, std::size_t depth, void *member1_data, std::size_t col_pitch1, std::size_t row_pitch1, std::size_t page_pitch1,...)
 Binds a 3D dense container of user-defined type to strided user data.
template<typename T , std::size_t D, std::size_t N>
detail::enable_if
< detail::is_scalar< T >
::value >::type 
arbb::bind (dense< array< T, N >, D > &container, typename uncaptured< T >::type *data, const array< std::size_t, D > &size)
 Binds a dense container of array-of-scalar type to user data.
template<typename T , std::size_t D, std::size_t N>
detail::enable_if
< detail::is_scalar< T >
::value >::type 
arbb::bind (dense< array< T, N >, D > &container, typename uncaptured< T >::type *data, const array< std::size_t, D > &size, const array< std::size_t, D > &record_pitch, std::size_t element_pitch)
 Binds a dense container of array-of-scalar type to strided user data.
template<typename T , std::size_t N>
detail::enable_if
< detail::is_scalar< T >
::value >::type 
arbb::bind (dense< array< T, N >, 1 > &container, typename uncaptured< T >::type *data, std::size_t size)
 Binds a 1D dense container of array-of-scalar type to user data.
template<typename T , std::size_t N>
detail::enable_if
< detail::is_scalar< T >
::value >::type 
arbb::bind (dense< array< T, N >, 2 > &container, typename uncaptured< T >::type *data, std::size_t width, std::size_t height)
 Binds a 2D dense container of array-of-scalar type to user data.
template<typename T , std::size_t N>
detail::enable_if
< detail::is_scalar< T >
::value >::type 
arbb::bind (dense< array< T, N >, 3 > &container, typename uncaptured< T >::type *data, std::size_t width, std::size_t height, std::size_t depth)
 Binds a 3D dense container of array-of-scalar type to user data.
template<typename T , std::size_t N>
detail::enable_if
< detail::is_scalar< T >
::value >::type 
arbb::bind (dense< array< T, N >, 1 > &container, typename uncaptured< T >::type *data, std::size_t size, std::size_t record_pitch, std::size_t element_pitch)
 Binds a 1D dense container of array-of-scalar type to strided user data.
template<typename T , std::size_t N>
detail::enable_if
< detail::is_scalar< T >
::value >::type 
arbb::bind (dense< array< T, N >, 2 > &container, typename uncaptured< T >::type *data, std::size_t width, std::size_t height, std::size_t col_pitch, std::size_t row_pitch, std::size_t element_pitch)
 Binds a 2D dense container of array-of-scalar type to strided user data.
template<typename T , std::size_t N>
detail::enable_if
< detail::is_scalar< T >
::value >::type 
arbb::bind (dense< array< T, N >, 3 > &container, typename uncaptured< T >::type *data, std::size_t width, std::size_t height, std::size_t depth, std::size_t col_pitch, std::size_t row_pitch, std::size_t page_pitch, std::size_t element_pitch)
 Binds a 3D dense container of array-of-scalar type to strided user data.

Function Documentation

template<typename T , std::size_t D>
detail::enable_if<detail::is_scalar<T>::value>::type arbb::bind ( dense< T, D > &  container,
typename uncaptured< T >::type *  data,
const array< std::size_t, D > &  size 
) [inline]

Binds a dense container of scalars to user data.

Example:

 bind(c, user_data, {cols, rows}) -> c(row, col) = user_data + col + row * cols
   for 0 <= col < size[0],
       0 <= row < size[1]

Parameters:

container Container to bind.
data Pointer to user data.
size Array of container dimensions in elements.
template<typename T , std::size_t D>
detail::enable_if<detail::is_scalar<T>::value>::type arbb::bind ( dense< T, D > &  container,
typename uncaptured< T >::type *  data,
const array< std::size_t, D > &  size,
const array< std::size_t, D > &  pitch 
) [inline]

Binds a dense container of scalars to strided user data.

Example:

 bind(c, user_data, {cols, rows, pages}, {col_pitch, row_pitch, page_pitch}) -> c(row, col, page) = (char*)user_data + col * col_pitch + row * row_pitch + page * page_pitch
   for 0 <= col < size[0],
       0 <= row < size[1],
       0 <= page < size[2]

Parameters:

container Container to bind.
data Pointer to user data.
size Array of container dimensions in elements.
pitch Array of container pitches in bytes.
template<typename T >
detail::enable_if<detail::is_scalar<T>::value>::type arbb::bind ( dense< T > &  container,
typename uncaptured< T >::type *  data,
std::size_t  size 
) [inline]

Binds a 1D dense container to user data.

Equivalent to bind(container, data, {size})

template<typename T >
detail::enable_if<detail::is_scalar<T>::value>::type arbb::bind ( dense< T, 2 > &  container,
typename uncaptured< T >::type *  data,
std::size_t  width,
std::size_t  height 
) [inline]

Binds a 2D dense container of scalars to user data.

Equivalent to bind(container, data, {width, height})

template<typename T >
detail::enable_if<detail::is_scalar<T>::value>::type arbb::bind ( dense< T, 3 > &  container,
typename uncaptured< T >::type *  data,
std::size_t  width,
std::size_t  height,
std::size_t  depth 
) [inline]

Binds a 3D dense container of scalars to user data.

Equivalent to bind(container, data, {width, height, depth})

template<typename T >
detail::enable_if<detail::is_scalar<T>::value>::type arbb::bind ( dense< T > &  container,
typename uncaptured< T >::type *  data,
std::size_t  size,
std::size_t  pitch 
) [inline]

Binds a 1D dense container of scalars to strided user data.

Equivalent to bind(container, data, {size}, {pitch})

template<typename T >
detail::enable_if<detail::is_scalar<T>::value>::type arbb::bind ( dense< T, 2 > &  container,
typename uncaptured< T >::type *  data,
std::size_t  width,
std::size_t  height,
std::size_t  col_pitch,
std::size_t  row_pitch 
) [inline]

Binds a 2D dense container of scalars to strided user data.

Equivalent to bind(container, data, {width, height}, {col_pitch, row_pitch})

template<typename T >
detail::enable_if<detail::is_scalar<T>::value>::type arbb::bind ( dense< T, 3 > &  container,
typename uncaptured< T >::type *  data,
std::size_t  width,
std::size_t  height,
std::size_t  depth,
std::size_t  col_pitch,
std::size_t  row_pitch,
std::size_t  page_pitch 
) [inline]

Binds a 3D dense container of scalars to strided user data.

Equivalent to bind(container, data, {width, height, depth}, {col_pitch, row_pitch, page_pitch})

template<typename T , std::size_t D>
detail::disable_if<detail::is_scalar<T>::value>::type arbb::bind ( dense< T, D > &  container,
const array< std::size_t, D > &  size,
void *  member1_data,
  ... 
) [inline]

Binds a dense container of user-defined type to user data.

The size parameter is followed by a variable argument list of data pointers, with one pointer for each data member in the user-defined type.

Example:

 bind(c, {cols, rows}, member1_data, member2_data)
 -> c(row, col).member1 = member1_data + col + row * cols
 -> c(row, col).member2 = member2_data + col + row * cols
   for 0 <= col < size[0],
       0 <= row < size[1]

Parameters:

container Container to bind.
size Array of container dimensions in elements.
member1_data Pointer to data for first class/struct member variable.
... Further pointers to user data for the remaining members in the element type. Values should have the same type as the member1_data parameter.
template<typename T >
detail::disable_if<detail::is_scalar<T>::value>::type arbb::bind ( dense< T, 1 > &  container,
const array< std::size_t, 1 > &  size,
void *  member1_data,
array< std::size_t, 1 >  pitch1,
  ... 
) [inline]

Binds a dense container of user-defined type to strided user data.

After the size parameter is a variable argument list of data pointers, with one pointer for each data member in the user-defined type.

Example:

 bind(c, {cols, rows}, member1_data, pitch1, member2_data, pitch2)
 -> c(row, col).member1 = member1_data + col * pitch1[0] + row * pitch1[1]
 -> c(row, col).member2 = member2_data + col * pitch2[0] + row * pitch2[1]
   for 0 <= col < size[0],
       0 <= row < size[1]

Parameters:

container Container to bind.
size Array of container dimensions in elements.
member1_data Pointer to data for first class/struct member variable.
pitch1 Array of pitches for binding member1_data pointer.
... Further pairs of pointers to user data and pitches for the remaining members in the element type. Values should have the same types as the member1_data and pitch1 parameters.
template<typename T >
detail::disable_if<detail::is_scalar<T>::value>::type arbb::bind ( dense< T, 2 > &  container,
const array< std::size_t, 2 > &  size,
void *  member1_data,
array< std::size_t, 2 >  pitch1,
  ... 
) [inline]

Binds a dense container of user-defined type to strided user data.

After the size parameter is a variable argument list of data pointers, with one pointer for each data member in the user-defined type.

Example:

 bind(c, {cols, rows}, member1_data, pitch1, member2_data, pitch2)
 -> c(row, col).member1 = member1_data + col * pitch1[0] + row * pitch1[1]
 -> c(row, col).member2 = member2_data + col * pitch2[0] + row * pitch2[1]
   for 0 <= col < size[0],
       0 <= row < size[1]

Parameters:

container Container to bind.
size Array of container dimensions in elements.
member1_data Pointer to data for first class/struct member variable.
pitch1 Array of pitches for binding member1_data pointer.
... Further pairs of pointers to user data and pitches for the remaining members in the element type. Values should have the same types as the member1_data and pitch1 parameters.
template<typename T >
detail::disable_if<detail::is_scalar<T>::value>::type arbb::bind ( dense< T, 3 > &  container,
const array< std::size_t, 3 > &  size,
void *  member1_data,
array< std::size_t, 3 >  pitch1,
  ... 
) [inline]

Binds a dense container of user-defined type to strided user data.

After the size parameter is a variable argument list of data pointers, with one pointer for each data member in the user-defined type.

Example:

 bind(c, {cols, rows}, member1_data, pitch1, member2_data, pitch2)
 -> c(row, col).member1 = member1_data + col * pitch1[0] + row * pitch1[1]
 -> c(row, col).member2 = member2_data + col * pitch2[0] + row * pitch2[1]
   for 0 <= col < size[0],
       0 <= row < size[1]

Parameters:

container Container to bind.
size Array of container dimensions in elements.
member1_data Pointer to data for first class/struct member variable.
pitch1 Array of pitches for binding member1_data pointer.
... Further pairs of pointers to user data and pitches for the remaining members in the element type. Values should have the same types as the member1_data and pitch1 parameters.
template<typename T >
detail::disable_if<detail::is_scalar<T>::value>::type arbb::bind ( dense< T > &  container,
std::size_t  size,
void *  member1_data,
  ... 
) [inline]

Binds a 1D dense container of user-defined type to user data.

Equivalent to bind(container, {size}, member1_data...)

template<typename T >
detail::disable_if<detail::is_scalar<T>::value>::type arbb::bind ( dense< T, 2 > &  container,
std::size_t  width,
std::size_t  height,
void *  member1_data,
  ... 
) [inline]

Binds a 2D dense container of user-defined type to user data.

Equivalent to bind(container, {width, height}, member1_data, ...)

template<typename T >
detail::disable_if<detail::is_scalar<T>::value>::type arbb::bind ( dense< T, 3 > &  container,
std::size_t  width,
std::size_t  height,
std::size_t  depth,
void *  member1_data,
  ... 
) [inline]

Binds a 3D dense container of user-defined type to user data.

Equivalent to bind(container, {width, height, depth}, member1_data, ...)

template<typename T >
detail::disable_if<detail::is_scalar<T>::value>::type arbb::bind ( dense< T > &  container,
std::size_t  size,
void *  member1_data,
std::size_t  pitch1,
  ... 
) [inline]

Binds a 1D dense container of user-defined type to strided user data.

Equivalent to bind(container, {size}, member1_data, {pitch1}, ...)

template<typename T >
detail::disable_if<detail::is_scalar<T>::value>::type arbb::bind ( dense< T, 2 > &  container,
std::size_t  width,
std::size_t  height,
void *  member1_data,
std::size_t  col_pitch1,
std::size_t  row_pitch1,
  ... 
) [inline]

Binds a 2D dense container of user-defined type to strided user data.

Equivalent to bind(container, {width, height}, member1_data, {col_pitch1, row_pitch1}, ...)

template<typename T >
detail::disable_if<detail::is_scalar<T>::value>::type arbb::bind ( dense< T, 3 > &  container,
std::size_t  width,
std::size_t  height,
std::size_t  depth,
void *  member1_data,
std::size_t  col_pitch1,
std::size_t  row_pitch1,
std::size_t  page_pitch1,
  ... 
) [inline]

Binds a 3D dense container of user-defined type to strided user data.

Equivalent to bind(container, {width, height depth}, member1_data, {col_pitch1, row_pitch1, page_pitch1}, ...)

template<typename T , std::size_t D, std::size_t N>
detail::enable_if<detail::is_scalar<T>::value>::type arbb::bind ( dense< array< T, N >, D > &  container,
typename uncaptured< T >::type *  data,
const array< std::size_t, D > &  size 
) [inline]

Binds a dense container of array-of-scalar type to user data.

Example:

 bind(c, user_data, {cols, rows}) -> c(row, col)[n] = user_data + n + col + row * cols
   for 0 <= col < size[0],
       0 <= row < size[1],
       0 <= n < N

Parameters:

container Container to bind.
data Pointer to user data.
size Array of container dimensions in elements.
template<typename T , std::size_t D, std::size_t N>
detail::enable_if<detail::is_scalar<T>::value>::type arbb::bind ( dense< array< T, N >, D > &  container,
typename uncaptured< T >::type *  data,
const array< std::size_t, D > &  size,
const array< std::size_t, D > &  record_pitch,
std::size_t  element_pitch 
) [inline]

Binds a dense container of array-of-scalar type to strided user data.

Example:

 bind(c, user_data, {cols, rows, pages}, {col_pitch, row_pitch, page_pitch}, element_pitch)
   -> c(row, col, page)[n] = (char*)user_data + n * element_pitch + col * col_pitch + row * row_pitch + page * page_pitch
   for 0 <= col < size[0],
       0 <= row < size[1],
       0 <= page < size[2],
       0 <= n < N

Parameters:

container Container to bind.
data Pointer to user data.
size Array of container dimensions in elements.
record_pitch Array of pitches between successive arrays in bytes.
element_pitch Pitch between array elements in bytes.
template<typename T , std::size_t N>
detail::enable_if<detail::is_scalar<T>::value>::type arbb::bind ( dense< array< T, N >, 1 > &  container,
typename uncaptured< T >::type *  data,
std::size_t  size 
) [inline]

Binds a 1D dense container of array-of-scalar type to user data.

Equivalent to bind(container, data, {size})

template<typename T , std::size_t N>
detail::enable_if<detail::is_scalar<T>::value>::type arbb::bind ( dense< array< T, N >, 2 > &  container,
typename uncaptured< T >::type *  data,
std::size_t  width,
std::size_t  height 
) [inline]

Binds a 2D dense container of array-of-scalar type to user data.

Equivalent to bind(container, data, {width, height})

template<typename T , std::size_t N>
detail::enable_if<detail::is_scalar<T>::value>::type arbb::bind ( dense< array< T, N >, 3 > &  container,
typename uncaptured< T >::type *  data,
std::size_t  width,
std::size_t  height,
std::size_t  depth 
) [inline]

Binds a 3D dense container of array-of-scalar type to user data.

Equivalent to bind(container, data, {width, height, depth})

template<typename T , std::size_t N>
detail::enable_if<detail::is_scalar<T>::value>::type arbb::bind ( dense< array< T, N >, 1 > &  container,
typename uncaptured< T >::type *  data,
std::size_t  size,
std::size_t  record_pitch,
std::size_t  element_pitch 
) [inline]

Binds a 1D dense container of array-of-scalar type to strided user data.

Equivalent to bind(container, data, {size}, {record_pitch}, element_pitch)

template<typename T , std::size_t N>
detail::enable_if<detail::is_scalar<T>::value>::type arbb::bind ( dense< array< T, N >, 2 > &  container,
typename uncaptured< T >::type *  data,
std::size_t  width,
std::size_t  height,
std::size_t  col_pitch,
std::size_t  row_pitch,
std::size_t  element_pitch 
) [inline]

Binds a 2D dense container of array-of-scalar type to strided user data.

Equivalent to bind(container, data, {width, height}, {col_pitch, row_pitch}, element_pitch)

template<typename T , std::size_t N>
detail::enable_if<detail::is_scalar<T>::value>::type arbb::bind ( dense< array< T, N >, 3 > &  container,
typename uncaptured< T >::type *  data,
std::size_t  width,
std::size_t  height,
std::size_t  depth,
std::size_t  col_pitch,
std::size_t  row_pitch,
std::size_t  page_pitch,
std::size_t  element_pitch 
) [inline]

Binds a 3D dense container of array-of-scalar type to strided user data.

Equivalent to bind(container, data, {width, height, depth}, {col_pitch, row_pitch, page_pitch}, element_pitch)

Submit feedback on this help topic

Copyright © 2010, Intel Corporation. All rights reserved.