OpenVDB: openvdb::v6_0::io Namespace Reference

OpenVDB 6.0.0

Classes | Enumerations | Functions
openvdb::v6_0::io Namespace Reference

## Classes
class | Archive
| Grid serializer/unserializer. More...
class | File
| Grid archive associated with a file on disk. More...
class | GridDescriptor
struct | HalfReader
struct | HalfReader< false, T >
| Partial specialization for non-floating-point types (no half to float promotion) More...
struct | HalfReader< true, T >
| Partial specialization for floating-point types. More...
struct | HalfWriter
struct | HalfWriter< false, T >
| Partial specialization for non-floating-point types (no float to half quantization) More...
struct | HalfWriter< true, T >
| Partial specialization for floating-point types. More...
class | MappedFile
| Handle to control the lifetime of a memory-mapped .vdb file. More...
struct | MultiPass
| Leaf nodes that require multi-pass I/O must inherit from this struct. More...
class | Queue
| Queue for asynchronous output of grids to files or streams. More...
struct | RealToHalf
| RealToHalf and its specializations define a mapping from floating-point data types to analogous half float types. More...
struct | RealToHalf< double >
struct | RealToHalf< float >
struct | RealToHalf< Vec2d >
struct | RealToHalf< Vec2s >
struct | RealToHalf< Vec3d >
struct | RealToHalf< Vec3s >
class | Stream
| Grid archive associated with arbitrary input and output streams (not necessarily files) More...
class | StreamMetadata
| Container for metadata describing how to unserialize grids from and/or serialize grids to a stream (which file format, compression scheme, etc. to use) More...
class | TempFile
| Output stream to a unique temporary file. More...

## Enumerations
enum | { COMPRESS_NONE = 0, COMPRESS_ZIP = 0x1, COMPRESS_ACTIVE_MASK = 0x2, COMPRESS_BLOSC = 0x4 }
| OR-able bit flags for compression options on input and output streams. More...
enum | { NO_MASK_OR_INACTIVE_VALS, NO_MASK_AND_MINUS_BG, NO_MASK_AND_ONE_INACTIVE_VAL, MASK_AND_NO_INACTIVE_VALS, MASK_AND_ONE_INACTIVE_VAL, MASK_AND_TWO_INACTIVE_VALS, NO_MASK_AND_ALL_VALS }

## Functions
OPENVDB_API std::string | compressionToString (uint32_t flags)
| Return a string describing the given compression flags. More...
template<typename T >
T | truncateRealToHalf (const T &val)
| Return the given value truncated to 16-bit float precision. More...
OPENVDB_API void | zipToStream (std::ostream &, const char *data, size_t numBytes)
OPENVDB_API void | unzipFromStream (std::istream &, char *data, size_t numBytes)
OPENVDB_API void | bloscToStream (std::ostream &, const char *data, size_t valSize, size_t numVals)
OPENVDB_API void | bloscFromStream (std::istream &, char *data, size_t numBytes)
template<typename T >
void | readData (std::istream &is, T *data, Index count, uint32_t compression)
| Read data from a stream. More...
template<>
void | readData< std::string > (std::istream &is, std::string *data, Index count, uint32_t)
| Specialization for std::string input. More...
template<typename T >
void | writeData (std::ostream &os, const T *data, Index count, uint32_t compression)
template<>
void | writeData< std::string > (std::ostream &os, const std::string *data, Index count, uint32_t)
| Specialization for std::string output. More...
template<typename ValueT , typename MaskT >
void | readCompressedValues (std::istream &is, ValueT *destBuf, Index destCount, const MaskT &valueMask, bool fromHalf)
template<typename ValueT , typename MaskT >
void | writeCompressedValues (std::ostream &os, ValueT *srcBuf, Index srcCount, const MaskT &valueMask, const MaskT &childMask, bool toHalf)
std::ostream & | operator<< (std::ostream &, const StreamMetadata &)
| Write a description of the given metadata to an output stream. More...
std::ostream & | operator<< (std::ostream &, const StreamMetadata::AuxDataMap &)
std::string | getErrorString (int errorNum)
| Return a string (possibly empty) describing the given system error code. More...
std::string | getErrorString ()
| Return a string (possibly empty) describing the most recent system error. More...
OPENVDB_API uint32_t | getFormatVersion (std::ios_base &)
| Return the file format version number associated with the given input stream. More...
OPENVDB_API VersionId | getLibraryVersion (std::ios_base &)
| Return the (major, minor) library version number associated with the given input stream. More...
OPENVDB_API std::string | getVersion (std::ios_base &)
| Return a string of the form "<major>.<minor>/<format>", giving the library and file format version numbers associated with the given input stream. More...
OPENVDB_API void | setCurrentVersion (std::istream &)
| Associate the current file format and library version numbers with the given input stream. More...
OPENVDB_API void | setVersion (std::ios_base &, const VersionId &libraryVersion, uint32_t fileVersion)
| Associate specific file format and library version numbers with the given stream. More...
OPENVDB_API uint32_t | getDataCompression (std::ios_base &)
| Return a bitwise OR of compression option flags (COMPRESS_ZIP, COMPRESS_ACTIVE_MASK, etc.) specifying whether and how input data is compressed or output data should be compressed. More...
OPENVDB_API void | setDataCompression (std::ios_base &, uint32_t compressionFlags)
| Associate with the given stream a bitwise OR of compression option flags (COMPRESS_ZIP, COMPRESS_ACTIVE_MASK, etc.) specifying whether and how input data is compressed or output data should be compressed. More...
OPENVDB_API uint32_t | getGridClass (std::ios_base &)
| Return the class (GRID_LEVEL_SET, GRID_UNKNOWN, etc.) of the grid currently being read from or written to the given stream. More...
OPENVDB_API void | setGridClass (std::ios_base &, uint32_t)
| Associate with the given stream the class (GRID_LEVEL_SET, GRID_UNKNOWN, etc.) of the grid currently being read or written. More...
OPENVDB_API bool | getHalfFloat (std::ios_base &)
| Return true if floating-point values should be quantized to 16 bits when writing to the given stream or promoted back from 16-bit to full precision when reading from it. More...
OPENVDB_API void | setHalfFloat (std::ios_base &, bool)
| Specify whether floating-point values should be quantized to 16 bits when writing to the given stream or promoted back from 16-bit to full precision when reading from it. More...
OPENVDB_API const void * | getGridBackgroundValuePtr (std::ios_base &)
| Return a pointer to the background value of the grid currently being read from or written to the given stream. More...
OPENVDB_API void | setGridBackgroundValuePtr (std::ios_base &, const void *background)
| Specify (a pointer to) the background value of the grid currently being read from or written to the given stream. More...
OPENVDB_API bool | getWriteGridStatsMetadata (std::ios_base &)
| Return `true` if grid statistics (active voxel count and bounding box, etc.) should be computed and stored as grid metadata when writing to the given stream. More...
OPENVDB_API void | setWriteGridStatsMetadata (std::ios_base &, bool writeGridStats)
| Specify whether to compute grid statistics (active voxel count and bounding box, etc.) and store them as grid metadata when writing to the given stream. More...
OPENVDB_API SharedPtr< MappedFile > | getMappedFilePtr (std::ios_base &)
| Return a shared pointer to the memory-mapped file with which the given stream is associated, or a null pointer if the stream is not associated with a memory-mapped file. More...
OPENVDB_API void | setMappedFilePtr (std::ios_base &, SharedPtr< MappedFile > &)
| Associate the given stream with (a shared pointer to) a memory-mapped file. More...
OPENVDB_API SharedPtr< StreamMetadata > | getStreamMetadataPtr (std::ios_base &)
| Return a shared pointer to an object that stores metadata (file format, compression scheme, etc.) for use when reading from or writing to the given stream. More...
OPENVDB_API void | setStreamMetadataPtr (std::ios_base &, SharedPtr< StreamMetadata > &, bool transfer=true)
| Associate the given stream with (a shared pointer to) an object that stores metadata (file format, compression scheme, etc.) for use when reading from or writing to the stream. More...
OPENVDB_API SharedPtr< StreamMetadata > | clearStreamMetadataPtr (std::ios_base &)
| Dissociate the given stream from its metadata object (if it has one) and return a shared pointer to the object. More...
template<>
void | readCompressedValues (std::istream &is, PointDataIndex32 *destBuf, Index destCount, const util::NodeMask< 3 > &, bool)
| openvdb::io::readCompressedValues specialized on PointDataIndex32 arrays to ignore the value mask, use a larger block size and use 16-bit size instead of 64-bit More...
template<>
void | writeCompressedValues (std::ostream &os, PointDataIndex32 *srcBuf, Index srcCount, const util::NodeMask< 3 > &, const util::NodeMask< 3 > &, bool)
| openvdb::io::writeCompressedValues specialized on PointDataIndex32 arrays to ignore the value mask, use a larger block size and use 16-bit size instead of 64-bit More...
template<typename T >
void | writeCompressedValuesSize (std::ostream &os, const T *srcBuf, Index srcCount)

## Enumeration Type Documentation

## ◆ anonymous enum

anonymous enum

OR-able bit flags for compression options on input and output streams.

`COMPRESS_NONE`

  On write, don't compress data.
  On read, the input stream contains uncompressed data.

`COMPRESS_ZIP`

  When writing grids other than level sets or fog volumes, apply ZLIB compression to internal and leaf node value buffers.
  When reading grids other than level sets or fog volumes, indicate that the value buffers of internal and leaf nodes are ZLIB-compressed.
  ZLIB compresses well but is slow.

`COMPRESS_ACTIVE_MASK`

  When writing a grid of any class, don't output a node's inactive values if it has two or fewer distinct values. Instead, output minimal information to permit the lossless reconstruction of inactive values.
  On read, nodes might have been stored without inactive values. Where necessary, reconstruct inactive values from available information.

`COMPRESS_BLOSC`
  When writing grids other than level sets or fog volumes, apply Blosc compression to internal and leaf node value buffers.
  When reading grids other than level sets or fog volumes, indicate that the value buffers of internal and leaf nodes are Blosc-compressed.
  Blosc is much faster than ZLIB and produces comparable file sizes.

Enumerator
COMPRESS_NONE |
COMPRESS_ZIP |
COMPRESS_ACTIVE_MASK |
COMPRESS_BLOSC |

## ◆ anonymous enum

anonymous enum

Enumerator
NO_MASK_OR_INACTIVE_VALS |
NO_MASK_AND_MINUS_BG |
NO_MASK_AND_ONE_INACTIVE_VAL |
MASK_AND_NO_INACTIVE_VALS |
MASK_AND_ONE_INACTIVE_VAL |
MASK_AND_TWO_INACTIVE_VALS |
NO_MASK_AND_ALL_VALS |

## Function Documentation

## ◆ bloscFromStream()

OPENVDB_API void openvdb::v6_0::io::bloscFromStream | ( | std::istream & | ,
|  | char * | data,
|  | size_t | numBytes
| ) |  |

## ◆ bloscToStream()

OPENVDB_API void openvdb::v6_0::io::bloscToStream | ( | std::ostream & | ,
|  | const char * | data,
|  | size_t | valSize,
|  | size_t | numVals
| ) |  |

## ◆ clearStreamMetadataPtr()

OPENVDB_API SharedPtr<StreamMetadata> openvdb::v6_0::io::clearStreamMetadataPtr | ( | std::ios_base & |  | ) |

Dissociate the given stream from its metadata object (if it has one) and return a shared pointer to the object.

## ◆ compressionToString()

OPENVDB_API std::string openvdb::v6_0::io::compressionToString | ( | uint32_t | flags | ) |

Return a string describing the given compression flags.

## ◆ getDataCompression()

OPENVDB_API uint32_t openvdb::v6_0::io::getDataCompression | ( | std::ios_base & |  | ) |

Return a bitwise OR of compression option flags (COMPRESS_ZIP, COMPRESS_ACTIVE_MASK, etc.) specifying whether and how input data is compressed or output data should be compressed.

## ◆ getErrorString() [1/2]

std::string openvdb::v6_0::io::getErrorString | ( | int | errorNum | ) |

Return a string (possibly empty) describing the given system error code.

## ◆ getErrorString() [2/2]

std::string openvdb::v6_0::io::getErrorString | ( |  | ) |

Return a string (possibly empty) describing the most recent system error.

## ◆ getFormatVersion()

OPENVDB_API uint32_t openvdb::v6_0::io::getFormatVersion | ( | std::ios_base & |  | ) |

Return the file format version number associated with the given input stream.

See also
  File::setFormatVersion()

## ◆ getGridBackgroundValuePtr()

OPENVDB_API const void* openvdb::v6_0::io::getGridBackgroundValuePtr | ( | std::ios_base & |  | ) |

Return a pointer to the background value of the grid currently being read from or written to the given stream.

## ◆ getGridClass()

OPENVDB_API uint32_t openvdb::v6_0::io::getGridClass | ( | std::ios_base & |  | ) |

Return the class (GRID_LEVEL_SET, GRID_UNKNOWN, etc.) of the grid currently being read from or written to the given stream.

## ◆ getHalfFloat()

OPENVDB_API bool openvdb::v6_0::io::getHalfFloat | ( | std::ios_base & |  | ) |

Return true if floating-point values should be quantized to 16 bits when writing to the given stream or promoted back from 16-bit to full precision when reading from it.

## ◆ getLibraryVersion()

OPENVDB_API VersionId openvdb::v6_0::io::getLibraryVersion | ( | std::ios_base & |  | ) |

Return the (major, minor) library version number associated with the given input stream.

See also
  File::setLibraryVersion()

## ◆ getMappedFilePtr()

OPENVDB_API SharedPtr<MappedFile> openvdb::v6_0::io::getMappedFilePtr | ( | std::ios_base & |  | ) |

Return a shared pointer to the memory-mapped file with which the given stream is associated, or a null pointer if the stream is not associated with a memory-mapped file.

## ◆ getStreamMetadataPtr()

OPENVDB_API SharedPtr<StreamMetadata> openvdb::v6_0::io::getStreamMetadataPtr | ( | std::ios_base & |  | ) |

Return a shared pointer to an object that stores metadata (file format, compression scheme, etc.) for use when reading from or writing to the given stream.

## ◆ getVersion()

OPENVDB_API std::string openvdb::v6_0::io::getVersion | ( | std::ios_base & |  | ) |

Return a string of the form "<major>.<minor>/<format>", giving the library and file format version numbers associated with the given input stream.

## ◆ getWriteGridStatsMetadata()

OPENVDB_API bool openvdb::v6_0::io::getWriteGridStatsMetadata | ( | std::ios_base & |  | ) |

Return `true` if grid statistics (active voxel count and bounding box, etc.) should be computed and stored as grid metadata when writing to the given stream.

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

std::ostream& openvdb::v6_0::io::operator<< | ( | std::ostream & | ,
|  | const StreamMetadata & |
| ) |  |

Write a description of the given metadata to an output stream.

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

std::ostream& openvdb::v6_0::io::operator<< | ( | std::ostream & | ,
|  | const StreamMetadata::AuxDataMap & |
| ) |  |

## ◆ readCompressedValues() [1/2]

void openvdb::v6_0::io::readCompressedValues | ( | std::istream & | is,
|  | PointDataIndex32 * | destBuf,
|  | Index | destCount,
|  | const util::NodeMask< 3 > & | ,
|  | bool |
| ) |  |
| inline

openvdb::io::readCompressedValues specialized on PointDataIndex32 arrays to ignore the value mask, use a larger block size and use 16-bit size instead of 64-bit

## ◆ readCompressedValues() [2/2]

void openvdb::v6_0::io::readCompressedValues | ( | std::istream & | is,
|  | ValueT * | destBuf,
|  | Index | destCount,
|  | const MaskT & | valueMask,
|  | bool | fromHalf
| ) |  |
| inline

Populate the given buffer with destCount values of type `ValueT` read from the given stream, taking into account that the stream might have been compressed via one of several supported schemes. [Mainly for internal use]

Parameters

  is | a stream from which to read data (possibly compressed, depending on the stream's compression settings)
  destBuf | a buffer into which to read values of type `ValueT`
  destCount | the number of values to be stored in the buffer
  valueMask | a bitmask (typically, a node's value mask) indicating which positions in the buffer correspond to active values
  fromHalf | if true, read 16-bit half floats from the input stream and convert them to full floats

## ◆ readData()

void openvdb::v6_0::io::readData | ( | std::istream & | is,
|  | T * | data,
|  | Index | count,
|  | uint32_t | compression
| ) |  |
| inline

Read data from a stream.

Parameters

  is | the input stream
  data | the contiguous array of data to read in
  count | the number of elements to read in
  compression | whether and how the data is compressed (either COMPRESS_NONE, COMPRESS_ZIP, COMPRESS_ACTIVE_MASK or COMPRESS_BLOSC)

Exceptions

  IoError | if compression is COMPRESS_BLOSC but OpenVDB was compiled without Blosc support.

This default implementation is instantiated only for types whose size can be determined by the sizeof() operator.

## ◆ readData< std::string >()

void openvdb::v6_0::io::readData< std::string > | ( | std::istream & | is,
|  | std::string * | data,
|  | Index | count,
|  | uint32_t |
| ) |  |
| inline

Specialization for std::string input.

## ◆ setCurrentVersion()

OPENVDB_API void openvdb::v6_0::io::setCurrentVersion | ( | std::istream & |  | ) |

Associate the current file format and library version numbers with the given input stream.

## ◆ setDataCompression()

OPENVDB_API void openvdb::v6_0::io::setDataCompression | ( | std::ios_base & | ,
|  | uint32_t | compressionFlags
| ) |  |

Associate with the given stream a bitwise OR of compression option flags (COMPRESS_ZIP, COMPRESS_ACTIVE_MASK, etc.) specifying whether and how input data is compressed or output data should be compressed.

## ◆ setGridBackgroundValuePtr()

OPENVDB_API void openvdb::v6_0::io::setGridBackgroundValuePtr | ( | std::ios_base & | ,
|  | const void * | background
| ) |  |

Specify (a pointer to) the background value of the grid currently being read from or written to the given stream.

Note
  The pointer must remain valid until the entire grid has been read or written.

## ◆ setGridClass()

OPENVDB_API void openvdb::v6_0::io::setGridClass | ( | std::ios_base & | ,
|  | uint32_t |
| ) |  |

Associate with the given stream the class (GRID_LEVEL_SET, GRID_UNKNOWN, etc.) of the grid currently being read or written.

## ◆ setHalfFloat()

OPENVDB_API void openvdb::v6_0::io::setHalfFloat | ( | std::ios_base & | ,
|  | bool |
| ) |  |

Specify whether floating-point values should be quantized to 16 bits when writing to the given stream or promoted back from 16-bit to full precision when reading from it.

## ◆ setMappedFilePtr()

OPENVDB_API void openvdb::v6_0::io::setMappedFilePtr | ( | std::ios_base & | ,
|  | SharedPtr< MappedFile > & |
| ) |  |

Associate the given stream with (a shared pointer to) a memory-mapped file.

Note
  The shared pointer object (not just the io::MappedFile object to which it points) must remain valid until the file is closed.

## ◆ setStreamMetadataPtr()

OPENVDB_API void openvdb::v6_0::io::setStreamMetadataPtr | ( | std::ios_base & | ,
|  | SharedPtr< StreamMetadata > & | ,
|  | bool | transfer = `true`
| ) |  |

Associate the given stream with (a shared pointer to) an object that stores metadata (file format, compression scheme, etc.) for use when reading from or writing to the stream.

If transfer is true, copy metadata from the object directly to the stream (for backward compatibility with older versions of the library).

Note
  The shared pointer object (not just the io::StreamMetadata object to which it points) must remain valid until the file is closed.

## ◆ setVersion()

OPENVDB_API void openvdb::v6_0::io::setVersion | ( | std::ios_base & | ,
|  | const VersionId & | libraryVersion,
|  | uint32_t | fileVersion
| ) |  |

Associate specific file format and library version numbers with the given stream.

This is typically called immediately after reading a header that contains the version numbers. Data read subsequently can then be interpreted appropriately.

## ◆ setWriteGridStatsMetadata()

OPENVDB_API void openvdb::v6_0::io::setWriteGridStatsMetadata | ( | std::ios_base & | ,
|  | bool | writeGridStats
| ) |  |

Specify whether to compute grid statistics (active voxel count and bounding box, etc.) and store them as grid metadata when writing to the given stream.

## ◆ truncateRealToHalf()

T openvdb::v6_0::io::truncateRealToHalf | ( | const T & | val | ) |
| inline

Return the given value truncated to 16-bit float precision.

## ◆ unzipFromStream()

OPENVDB_API void openvdb::v6_0::io::unzipFromStream | ( | std::istream & | ,
|  | char * | data,
|  | size_t | numBytes
| ) |  |

## ◆ writeCompressedValues() [1/2]

void openvdb::v6_0::io::writeCompressedValues | ( | std::ostream & | os,
|  | PointDataIndex32 * | srcBuf,
|  | Index | srcCount,
|  | const util::NodeMask< 3 > & | ,
|  | const util::NodeMask< 3 > & | ,
|  | bool |
| ) |  |
| inline

openvdb::io::writeCompressedValues specialized on PointDataIndex32 arrays to ignore the value mask, use a larger block size and use 16-bit size instead of 64-bit

## ◆ writeCompressedValues() [2/2]

void openvdb::v6_0::io::writeCompressedValues | ( | std::ostream & | os,
|  | ValueT * | srcBuf,
|  | Index | srcCount,
|  | const MaskT & | valueMask,
|  | const MaskT & | childMask,
|  | bool | toHalf
| ) |  |
| inline

Write srcCount values of type `ValueT` to the given stream, optionally after compressing the values via one of several supported schemes. [Mainly for internal use]

Parameters

  os | a stream to which to write data (possibly compressed, depending on the stream's compression settings)
  srcBuf | a buffer containing values of type `ValueT` to be written
  srcCount | the number of values stored in the buffer
  valueMask | a bitmask (typically, a node's value mask) indicating which positions in the buffer correspond to active values
  childMask | a bitmask (typically, a node's child mask) indicating which positions in the buffer correspond to child node pointers
  toHalf | if true, convert floating-point values to 16-bit half floats

## ◆ writeCompressedValuesSize()

void openvdb::v6_0::io::writeCompressedValuesSize | ( | std::ostream & | os,
|  | const T * | srcBuf,
|  | Index | srcCount
| ) |  |
| inline

## ◆ writeData()

void openvdb::v6_0::io::writeData | ( | std::ostream & | os,
|  | const T * | data,
|  | Index | count,
|  | uint32_t | compression
| ) |  |
| inline

Write data to a stream.

Parameters

  os | the output stream
  data | the contiguous array of data to write
  count | the number of elements to write out
  compression | whether and how to compress the data (either COMPRESS_NONE, COMPRESS_ZIP, COMPRESS_ACTIVE_MASK or COMPRESS_BLOSC)

Exceptions

  IoError | if compression is COMPRESS_BLOSC but OpenVDB was compiled without Blosc support.

This default implementation is instantiated only for types whose size can be determined by the sizeof() operator.

## ◆ writeData< std::string >()

void openvdb::v6_0::io::writeData< std::string > | ( | std::ostream & | os,
|  | const std::string * | data,
|  | Index | count,
|  | uint32_t |
| ) |  |
| inline

Specialization for std::string output.

## ◆ zipToStream()

OPENVDB_API void openvdb::v6_0::io::zipToStream | ( | std::ostream & | ,
|  | const char * | data,
|  | size_t | numBytes
| ) |  |