OpenVDB 12.1.0

Loading...
Searching...
No Matches
GridHandle< BufferT > Class Template Reference

This class serves to manage a buffer containing one or more NanoVDB Grids. More...

`#include <nanovdb/GridHandle.h>`

## Public Types
using | BufferType = BufferT

## Public Member Functions
template<typename T = BufferT, typename util::enable_if< BufferTraits< T >::hasDeviceDual, int >::type = 0>
| GridHandle (T &&buffer)
| Move constructor from a dual host-device buffer.
template<typename T = BufferT, typename util::disable_if< BufferTraits< T >::hasDeviceDual, int >::type = 0>
| GridHandle (T &&buffer)
| Move constructor from a host buffer.
| GridHandle ()=default
| Constructs an empty GridHandle.
| GridHandle (const GridHandle &)=delete
| Disallow copy-construction.
| GridHandle (GridHandle &&other) noexcept
| Move copy-constructor.
void | reset ()
| clear this GridHandle to an empty handle
GridHandle & | operator= (const GridHandle &)=delete
| Disallow copy assignment operation.
GridHandle & | operator= (GridHandle &&other) noexcept
| Move copy assignment operation.
template<typename OtherBufferT = HostBuffer>
GridHandle< OtherBufferT > | copy (const OtherBufferT &buffer=OtherBufferT()) const
| Performs a deep copy of the GridHandle, possibly templated on a different buffer type.
BufferT & | buffer ()
| Return a reference to the buffer.
const BufferT & | buffer () const
| Return a const reference to the buffer.
void * | data ()
| Returns a non-const pointer to the data.
const void * | data () const
| Returns a const pointer to the data.
template<typename U = BufferT>
util::enable_if< BufferTraits< U >::hasDeviceDual, constvoid * >::type | deviceData () const
template<typename U = BufferT>
util::enable_if< BufferTraits< U >::hasDeviceDual, constvoid * >::type | deviceData (int device) const
template<typename U = BufferT>
util::enable_if< BufferTraits< U >::hasDeviceDual, void * >::type | deviceData ()
template<typename U = BufferT>
util::enable_if< BufferTraits< U >::hasDeviceDual, void * >::type | deviceData (int device)
uint64_t | size () const
| Returns the size in bytes of the raw memory buffer managed by this GridHandle.
uint64_t | bufferSize () const
bool | empty () const
| Return true if this handle is empty, i.e. has no allocated memory.
bool | isEmpty () const
| operator bool () const
| Return true if this handle is not empty, i.e. contains at least one grid.
template<typename ValueT>
const NanoGrid< ValueT > * | grid (uint32_t n=0) const
| Returns a const host pointer to the n'th NanoVDB grid encoded in this GridHandle.
template<typename ValueT>
NanoGrid< ValueT > * | grid (uint32_t n=0)
| Returns a host pointer to the n'th NanoVDB grid encoded in this GridHandle.
template<typename ValueT, typename U = BufferT>
util::enable_if< BufferTraits< U >::hasDeviceDual, constNanoGrid< ValueT > * >::type | deviceGrid (uint32_t n=0) const
| Return a const pointer to the n'th grid encoded in this GridHandle on the device, e.g. GPU.
template<typename ValueT, typename U = BufferT>
util::enable_if< BufferTraits< U >::hasDeviceDual, NanoGrid< ValueT > * >::type | deviceGrid (uint32_t n=0)
| Return a const pointer to the n'th grid encoded in this GridHandle on the device, e.g. GPU.
template<typename U = BufferT>
util::enable_if< BufferTraits< U >::hasDeviceDual, void >::type | deviceUpload (void *stream, bool sync=true)
| Upload the grid to the device, e.g. from CPU to GPU.
template<typename U = BufferT>
util::enable_if< BufferTraits< U >::hasDeviceDual, void >::type | deviceUpload (int device=0, void *stream=nullptr, bool sync=true)
| Upload the host buffer to a specific device buffer. It device buffer doesn't exist it's created first.
template<typename U = BufferT>
util::enable_if< BufferTraits< U >::hasDeviceDual, void >::type | deviceDownload (void *stream, bool sync=true)
| Download the grid to from the device, e.g. from GPU to CPU.
template<typename U = BufferT>
util::enable_if< BufferTraits< U >::hasDeviceDual, void >::type | deviceDownload (int device=0, void *stream=nullptr, bool sync=true)
bool | isPadded () const
| Check if the buffer is this handle has any padding, i.e. if the buffer is larger than the combined size of all its grids.
uint32_t | gridCount () const
| Return the total number of grids contained in this buffer.
uint64_t | gridSize (uint32_t n=0) const
| Return the grid size of the n'th grid in this GridHandle.
uint64_t | totalGridSize () const
| compute the total sum of memory footprints of all the grids in this buffer
uint64_t | freeSize () const
| compute the size of unused storage in this buffer
bool | isFull () const
| Test if this buffer has any unused storage left, i.e. memory not occupied by grids.
GridType | gridType (uint32_t n=0) const
| Return the GridType of the n'th grid in this GridHandle.
const GridData * | gridData (uint32_t n=0) const
| Access to the GridData of the n'th grid in the current handle.
const GridMetaData * | gridMetaData (uint32_t n=0) const
| Returns a const point to the n'th grid meta data.
void | write (std::ostream &os, uint32_t n) const
| Write a specific grid in this buffer to an output stream.
void | write (std::ostream &os) const
| Write the entire grid buffer to an output stream.
void | write (const std::string &fileName) const
| Write this entire grid buffer to a file.
void | write (const std::string &fileName, uint32_t n) const
| Write a specific grid to file.
void | read (std::istream &is, const BufferT &pool=BufferT())
| Read an entire raw grid buffer from an input stream.
void | read (std::istream &is, uint32_t n, const BufferT &pool=BufferT())
| Read a specific grid from an input stream containing a raw grid buffer.
void | read (std::istream &is, const std::string &gridName, const BufferT &pool=BufferT())
| Read a specific grid from an input stream containing a raw grid buffer.
void | read (const std::string &fileName, const BufferT &pool=BufferT())
| Read a raw grid buffer from a file.
void | read (const std::string &fileName, uint32_t n, const BufferT &pool=BufferT())
| Read a specific grid from a file containing a raw grid buffer.
void | read (const std::string &fileName, const std::string &gridName, const BufferT &pool=BufferT())
| Read a specific grid from a file containing a raw grid buffer.

## Detailed Description

template<typename BufferT = HostBuffer>
class nanovdb::GridHandle< BufferT >

This class serves to manage a buffer containing one or more NanoVDB Grids.

Note
  It is important to note that this class does NOT depend on OpenVDB.

## Member Typedef Documentation

## ◆ BufferType

template<typename BufferT = HostBuffer>

using BufferType = BufferT

## Constructor & Destructor Documentation

## ◆ GridHandle() [1/5]

template<typename BufferT>
template<typename T, typename util::disable_if< BufferTraits< T >::hasDeviceDual, int >::type>

GridHandle | ( | T && | buffer | ) |

Move constructor from a dual host-device buffer.

Parameters

  buffer | buffer containing one or more NanoGrids that will be moved into this GridHandle

Exceptions

  Will | throw and error with the buffer does not contain a valid NanoGrid!

Note
  The implementation of this template specialization is in nanovdb/cuda/GridHandle.cuh since it requires CUDA

## ◆ GridHandle() [2/5]

template<typename BufferT = HostBuffer>
template<typename T = BufferT, typename util::disable_if< BufferTraits< T >::hasDeviceDual, int >::type = 0>

GridHandle | ( | T && | buffer | ) |

Move constructor from a host buffer.

Parameters

  buffer | buffer containing one or more NanoGrids that will be moved into this GridHandle

Exceptions

  Will | throw and error with the buffer does not contain a valid NanoGrid!

## ◆ GridHandle() [3/5]

template<typename BufferT = HostBuffer>

GridHandle | ( |  | ) |
| default

Constructs an empty GridHandle.

## ◆ GridHandle() [4/5]

template<typename BufferT = HostBuffer>

GridHandle | ( | const GridHandle< BufferT > & |  | ) |
| delete

Disallow copy-construction.

## ◆ GridHandle() [5/5]

template<typename BufferT = HostBuffer>

GridHandle | ( | GridHandle< BufferT > && | other | ) |
| inline noexcept

Move copy-constructor.

## Member Function Documentation

## ◆ buffer() [1/2]

template<typename BufferT = HostBuffer>

BufferT & buffer | ( |  | ) |
| inline

Return a reference to the buffer.

## ◆ buffer() [2/2]

template<typename BufferT = HostBuffer>

const BufferT & buffer | ( |  | ) | const
| inline

Return a const reference to the buffer.

## ◆ bufferSize()

template<typename BufferT = HostBuffer>

uint64_t bufferSize | ( |  | ) | const
| inline

## ◆ copy()

template<typename BufferT>
template<typename OtherBufferT>

GridHandle< OtherBufferT > copy | ( | const OtherBufferT & | buffer = OtherBufferT() | ) | const
| inline

Performs a deep copy of the GridHandle, possibly templated on a different buffer type.

Template Parameters

  OtherBufferT | Buffer type of the deep copy

Parameters

  buffer | optional buffer used for allocation

Returns
  A new handle of the specified buffer type that contains a deep copy of the current handle

## ◆ data() [1/2]

template<typename BufferT = HostBuffer>

void * data | ( |  | ) |
| inline

Returns a non-const pointer to the data.

Warning
  Note that the return pointer can be NULL if the GridHandle was not initialized

## ◆ data() [2/2]

template<typename BufferT = HostBuffer>

const void * data | ( |  | ) | const
| inline

Returns a const pointer to the data.

Warning
  Note that the return pointer can be NULL if the GridHandle was not initialized

## ◆ deviceData() [1/4]

template<typename BufferT = HostBuffer>
template<typename U = BufferT>

util::enable_if< BufferTraits< U >::hasDeviceDual, void * >::type deviceData | ( |  | ) |
| inline

## ◆ deviceData() [2/4]

template<typename BufferT = HostBuffer>
template<typename U = BufferT>

util::enable_if< BufferTraits< U >::hasDeviceDual, constvoid * >::type deviceData | ( |  | ) | const
| inline

## ◆ deviceData() [3/4]

template<typename BufferT = HostBuffer>
template<typename U = BufferT>

util::enable_if< BufferTraits< U >::hasDeviceDual, void * >::type deviceData | ( | int | device | ) |
| inline

## ◆ deviceData() [4/4]

template<typename BufferT = HostBuffer>
template<typename U = BufferT>

util::enable_if< BufferTraits< U >::hasDeviceDual, constvoid * >::type deviceData | ( | int | device | ) | const
| inline

## ◆ deviceDownload() [1/2]

template<typename BufferT = HostBuffer>
template<typename U = BufferT>

util::enable_if< BufferTraits< U >::hasDeviceDual, void >::type deviceDownload | ( | int | device = 0,
|  | void * | stream = nullptr,
|  | bool | sync = true )
| inline

## ◆ deviceDownload() [2/2]

template<typename BufferT = HostBuffer>
template<typename U = BufferT>

util::enable_if< BufferTraits< U >::hasDeviceDual, void >::type deviceDownload | ( | void * | stream,
|  | bool | sync = true )
| inline

Download the grid to from the device, e.g. from GPU to CPU.

Note
  This method is only available if the buffer supports devices

## ◆ deviceGrid() [1/2]

template<typename BufferT = HostBuffer>
template<typename ValueT, typename U = BufferT>

util::enable_if< BufferTraits< U >::hasDeviceDual, NanoGrid< ValueT > * >::type deviceGrid | ( | uint32_t | n = 0 | ) |
| inline

Return a const pointer to the n'th grid encoded in this GridHandle on the device, e.g. GPU.

Template Parameters

  ValueT | Value type of the grid point to be returned

Parameters

  n | Index of the grid pointer to be returned
  verbose | if non-zero error messages will be printed in case something failed

Warning
  Note that the return pointer can be NULL if the GridHandle was not initialized, n is invalid, or if the template parameter does not match the specified grid.

## ◆ deviceGrid() [2/2]

template<typename BufferT>
template<typename ValueT, typename U>

util::enable_if< BufferTraits< U >::hasDeviceDual, constNanoGrid< ValueT > * >::type deviceGrid | ( | uint32_t | n = 0 | ) | const
| inline

Return a const pointer to the n'th grid encoded in this GridHandle on the device, e.g. GPU.

Template Parameters

  ValueT | Value type of the grid point to be returned

Parameters

  n | Index of the (device) grid pointer to be returned

Warning
  Note that the return pointer can be NULL if the GridHandle has no device grid, n is invalid, or if the template parameter does not match the specified grid.

## ◆ deviceUpload() [1/2]

template<typename BufferT = HostBuffer>
template<typename U = BufferT>

util::enable_if< BufferTraits< U >::hasDeviceDual, void >::type deviceUpload | ( | int | device = 0,
|  | void * | stream = nullptr,
|  | bool | sync = true )
| inline

Upload the host buffer to a specific device buffer. It device buffer doesn't exist it's created first.

Parameters

  device | Device to upload host data to
  stream | cuda stream
  sync | if false the memory copy is asynchronous

## ◆ deviceUpload() [2/2]

template<typename BufferT = HostBuffer>
template<typename U = BufferT>

util::enable_if< BufferTraits< U >::hasDeviceDual, void >::type deviceUpload | ( | void * | stream,
|  | bool | sync = true )
| inline

Upload the grid to the device, e.g. from CPU to GPU.

Note
  This method is only available if the buffer supports devices

## ◆ empty()

template<typename BufferT = HostBuffer>

bool empty | ( |  | ) | const
| inline

Return true if this handle is empty, i.e. has no allocated memory.

## ◆ freeSize()

template<typename BufferT = HostBuffer>

uint64_t freeSize | ( |  | ) | const
| inline

compute the size of unused storage in this buffer

Returns
  the number of unused bytes in this buffer.

## ◆ grid() [1/2]

template<typename BufferT = HostBuffer>
template<typename ValueT>

NanoGrid< ValueT > * grid | ( | uint32_t | n = 0 | ) |
| inline

Returns a host pointer to the n'th NanoVDB grid encoded in this GridHandle.

Template Parameters

  ValueT | Value type of the grid point to be returned

Parameters

  n | Index of the (host) grid pointer to be returned

Warning
  Note that the return pointer can be NULL if the GridHandle no host grid, n is invalid or if the template parameter does not match the specified grid!

## ◆ grid() [2/2]

template<typename BufferT>
template<typename ValueT>

const NanoGrid< ValueT > * grid | ( | uint32_t | n = 0 | ) | const
| inline

Returns a const host pointer to the n'th NanoVDB grid encoded in this GridHandle.

Template Parameters

  ValueT | Value type of the grid point to be returned

Parameters

  n | Index of the (host) grid pointer to be returned

Warning
  Note that the return pointer can be NULL if the GridHandle no host grid, n is invalid or if the template parameter does not match the specified grid!

## ◆ gridCount()

template<typename BufferT = HostBuffer>

uint32_t gridCount | ( |  | ) | const
| inline

Return the total number of grids contained in this buffer.

## ◆ gridData()

template<typename BufferT>

const GridData * gridData | ( | uint32_t | n = 0 | ) | const
| inline

Access to the GridData of the n'th grid in the current handle.

Parameters

  n | zero-based ID of the grid

Returns
  Const pointer to the n'th GridData in the current handle

## ◆ gridMetaData()

template<typename BufferT>

const GridMetaData * gridMetaData | ( | uint32_t | n = 0 | ) | const
| inline

Returns a const point to the n'th grid meta data.

Parameters

  n | zero-based ID of the grid

Warning
  Note that the return pointer can be NULL if the GridHandle was not initialized

## ◆ gridSize()

template<typename BufferT = HostBuffer>

uint64_t gridSize | ( | uint32_t | n = 0 | ) | const
| inline

Return the grid size of the n'th grid in this GridHandle.

Parameters

  n | index of the grid (assumed to be less than gridCount())

Returns
  Return the byte size of the specified grid

## ◆ gridType()

template<typename BufferT = HostBuffer>

GridType gridType | ( | uint32_t | n = 0 | ) | const
| inline

Return the GridType of the n'th grid in this GridHandle.

Parameters

  n | index of the grid (assumed to be less than gridCount())

Returns
  Return the GridType of the specified grid

## ◆ isEmpty()

template<typename BufferT = HostBuffer>

bool isEmpty | ( |  | ) | const
| inline

## ◆ isFull()

template<typename BufferT = HostBuffer>

bool isFull | ( |  | ) | const
| inline

Test if this buffer has any unused storage left, i.e. memory not occupied by grids.

Returns
  true if there is no extra storage left in this buffer, i.e. empty or fully occupied with grids

## ◆ isPadded()

template<typename BufferT = HostBuffer>

bool isPadded | ( |  | ) | const
| inline

Check if the buffer is this handle has any padding, i.e. if the buffer is larger than the combined size of all its grids.

Returns
  true is the combined size of all grid is smaller than the buffer size

## ◆ operator bool()

template<typename BufferT = HostBuffer>

operator bool | ( |  | ) | const
| inline

Return true if this handle is not empty, i.e. contains at least one grid.

## ◆ operator=() [1/2]

template<typename BufferT = HostBuffer>

GridHandle & operator= | ( | const GridHandle< BufferT > & |  | ) |
| delete

Disallow copy assignment operation.

## ◆ operator=() [2/2]

template<typename BufferT = HostBuffer>

GridHandle & operator= | ( | GridHandle< BufferT > && | other | ) |
| inline noexcept

Move copy assignment operation.

## ◆ read() [1/6]

template<typename BufferT = HostBuffer>

void read | ( | const std::string & | fileName,
|  | const BufferT & | pool = BufferT() )
| inline

Read a raw grid buffer from a file.

Parameters

  filename | string name of the input file containing a raw grid buffer
  pool | optional pool from which to allocate the new grid buffer

## ◆ read() [2/6]

template<typename BufferT = HostBuffer>

void read | ( | const std::string & | fileName,
|  | const std::string & | gridName,
|  | const BufferT & | pool = BufferT() )
| inline

Read a specific grid from a file containing a raw grid buffer.

Parameters

  filename | string name of the input file containing a raw grid buffer
  gridName | string name of the grid to be read
  pool | optional pool from which to allocate the new grid buffer

Exceptions

  Will | throw a std::ios_base::failure if the file does not exist and a std::logic_error if the files does not contain a valid raw grid withe the specified name

## ◆ read() [3/6]

template<typename BufferT = HostBuffer>

void read | ( | const std::string & | fileName,
|  | uint32_t | n,
|  | const BufferT & | pool = BufferT() )
| inline

Read a specific grid from a file containing a raw grid buffer.

Parameters

  filename | string name of the input file containing a raw grid buffer
  n | zero-based index of the grid to be read
  pool | optional pool from which to allocate the new grid buffer

Exceptions

  Will | throw a std::ios_base::failure if the file does not exist and a std::logic_error if the files does not contain a valid raw grid

## ◆ read() [4/6]

template<typename BufferT>

void read | ( | std::istream & | is,
|  | const BufferT & | pool = BufferT() )

Read an entire raw grid buffer from an input stream.

Parameters

  is | input stream containing a raw grid buffer
  pool | optional pool from which to allocate the new grid buffer

Exceptions

  Will | throw a std::logic_error if the stream does not contain a valid raw grid

## ◆ read() [5/6]

template<typename BufferT>

void read | ( | std::istream & | is,
|  | const std::string & | gridName,
|  | const BufferT & | pool = BufferT() )

Read a specific grid from an input stream containing a raw grid buffer.

Parameters

  is | input stream containing a raw grid buffer
  gridName | string name of the grid to be read
  pool | optional pool from which to allocate the new grid buffer

Exceptions

  Will | throw a std::logic_error if the stream does not contain a valid raw grid with the specified name

## ◆ read() [6/6]

template<typename BufferT>

void read | ( | std::istream & | is,
|  | uint32_t | n,
|  | const BufferT & | pool = BufferT() )

Read a specific grid from an input stream containing a raw grid buffer.

Parameters

  is | input stream containing a raw grid buffer
  n | zero-based index of the grid to be read
  pool | optional pool from which to allocate the new grid buffer

Exceptions

  Will | throw a std::logic_error if the stream does not contain a valid raw grid

## ◆ reset()

template<typename BufferT = HostBuffer>

void reset | ( |  | ) |
| inline

clear this GridHandle to an empty handle

## ◆ size()

template<typename BufferT = HostBuffer>

uint64_t size | ( |  | ) | const
| inline

Returns the size in bytes of the raw memory buffer managed by this GridHandle.

## ◆ totalGridSize()

template<typename BufferT = HostBuffer>

uint64_t totalGridSize | ( |  | ) | const
| inline

compute the total sum of memory footprints of all the grids in this buffer

Returns
  the number of bytes occupied by all grids associated with this buffer

## ◆ write() [1/4]

template<typename BufferT = HostBuffer>

void write | ( | const std::string & | fileName | ) | const
| inline

Write this entire grid buffer to a file.

Parameters

  fileName | string name of the output file

## ◆ write() [2/4]

template<typename BufferT = HostBuffer>

void write | ( | const std::string & | fileName,
|  | uint32_t | n ) const
| inline

Write a specific grid to file.

Parameters

  fileName | string name of the output file
  n | zero-based index of the grid to be written to file

## ◆ write() [3/4]

template<typename BufferT = HostBuffer>

void write | ( | std::ostream & | os | ) | const
| inline

Write the entire grid buffer to an output stream.

Parameters

  os | output stream that the buffer will be written to

## ◆ write() [4/4]

template<typename BufferT = HostBuffer>

void write | ( | std::ostream & | os,
|  | uint32_t | n ) const
| inline

Write a specific grid in this buffer to an output stream.

Parameters

  os | output stream that the buffer will be written to
  n | zero-based index of the grid to be written to stream