OpenVDB 13.2.0
Loading...
Searching...
No Matches
openvdb::v13_2::io Namespace Reference

Classes

class  Archive
 Grid serializer/unserializer. More...
struct  Codec
 Abstract base class for grid I/O codecs. More...
struct  CodecData
 Mutable per-operation state created by Codec::createData() and passed into every read and write call on a given codec. More...
struct  CodecRegistry
 A thread-safe, process-global registry that maps codec names to Codec instances. 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
struct  MaskCompress
struct  PointDataGridMultiPass
 Tag for multi-pass I/O. Only points::PointDataLeafNode may inherit from this. More...
class  Queue
 Queue for asynchronous output of grids to files or streams. More...
struct  ReadDiagnostic
 A single read diagnostic message. More...
struct  ReadDiagnostics
 Thread-safe collection of read diagnostics accumulated during a codec read. More...
struct  ReadOptions
 Global read configuration passed to every codec during deserialization. More...
struct  ReadTypedOptions
 Base class for per-grid-type, codec-specific read options. 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...
 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  StreamMetadataScope
 Replaces any StreamMetadata shared pointer associated with the stream with the given one for the lifetime of this object. When the destructor of this object is called, the StreamMetadata shared pointer is replaced with the prior one again. More...
struct  WriteOptions
 Global write configuration passed to every codec during serialization. More...

Enumerations

enum class  CodecMode { ReadWrite , ReadOnly }
 Controls which operations a codec exposes. More...
enum class  ReadMode {
  Original , Half , Bool , Mask ,
  TopologyOnly , MetadataOnly
}
 Controls how grid data is read. More...
enum class  DiagnosticSeverity { Warning }
 Severity level for a read diagnostic. More...
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

std::string compressionToString (uint32_t flags)
 Return a string describing the given compression flags.
template<typename T>
T truncateRealToHalf (const T &val)
 Return the given value truncated to 16-bit float precision.
size_t zipToStreamSize (const char *data, size_t numBytes)
void zipToStream (std::ostream &, const char *data, size_t numBytes)
void unzipFromStream (std::istream &, char *data, size_t numBytes)
size_t bloscToStreamSize (const char *data, size_t valSize, size_t numVals)
void bloscToStream (std::ostream &, const char *data, size_t valSize, size_t numVals)
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.
template<>
void readData< std::string > (std::istream &is, std::string *data, Index count, uint32_t)
 Specialization for std::string input.
template<typename T>
size_t writeDataSize (const T *data, Index count, uint32_t compression)
template<>
size_t writeDataSize< std::string > (const std::string *data, Index count, uint32_t)
 Specialization for std::string output.
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.
template<typename ValueT, typename MaskT>
void readCompressedValues (std::istream &is, ValueT *destBuf, Index destCount, const MaskT &valueMask, bool fromHalf, const ValueT *background=nullptr)
template<typename ValueT, typename MaskT>
size_t writeCompressedValuesSize (ValueT *srcBuf, Index srcCount, const MaskT &valueMask, uint8_t maskMetadata, bool toHalf, uint32_t compress)
template<typename ValueT, typename MaskT>
void writeCompressedValues (std::ostream &os, const ValueT *srcBuf, Index srcCount, const MaskT &valueMask, const MaskT &childMask, bool toHalf, const ValueT *background=nullptr)
std::ostream & operator<< (std::ostream &, const StreamMetadata &)
 Write a description of the given metadata to an output stream.
std::ostream & operator<< (std::ostream &, const StreamMetadata::AuxDataMap &)
std::string getErrorString (int errorNum)
 Return a string (possibly empty) describing the given system error code.
std::string getErrorString ()
 Return a string (possibly empty) describing the most recent system error.
uint32_t getFormatVersion (std::ios_base &)
 Return the file format version number associated with the given input stream.
void checkFormatVersion (std::ios_base &)
 Throws an IoError if the file format version number is not supported.
VersionId getLibraryVersion (std::ios_base &)
 Return the (major, minor) library version number associated with the given input stream.
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.
void setCurrentVersion (std::istream &)
 Associate the current file format and library version numbers with the given input stream.
void setVersion (std::ios_base &, const VersionId &libraryVersion, uint32_t fileVersion)
 Associate specific file format and library version numbers with the given stream.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
SharedPtr< MappedFile > getMappedFilePtr (std::ios_base &)
void setMappedFilePtr (std::ios_base &, SharedPtr< MappedFile > &)
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.
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.
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.
template<>
void readCompressedValues (std::istream &is, PointDataIndex32 *destBuf, Index destCount, const util::NodeMask< 3 > &, bool, const PointDataIndex32 *)
 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
template<>
void writeCompressedValues (std::ostream &os, const PointDataIndex32 *srcBuf, Index srcCount, const util::NodeMask< 3 > &, const util::NodeMask< 3 > &, bool, const PointDataIndex32 *)
 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
template<typename T>
void writeCompressedValuesSize (std::ostream &os, const T *srcBuf, Index srcCount)

Enumeration Type Documentation

◆ 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 

◆ 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 

◆ CodecMode

enum class CodecMode
strong

Controls which operations a codec exposes.

Passed to codec registration to restrict how the codec may be used at runtime. A ReadOnly codec can still be used to read existing files but will not be selected as the write codec for new grids.

Enumerator
ReadWrite 

Both readTopology()/readBuffers() and writeTopology()/writeBuffers() are enabled. This is the default.

ReadOnly 

Only readTopology() and readBuffers() are enabled; the codec will not be offered as a write target.

◆ DiagnosticSeverity

enum class DiagnosticSeverity
strong

Severity level for a read diagnostic.

Note
Currently only Warning is defined.
Enumerator
Warning 

◆ ReadMode

enum class ReadMode
strong

Controls how grid data is read.

Passed via ReadOptions::readMode to influence which portions of a grid are deserialized and whether any on-the-fly conversion is performed during read. Codecs are expected to honour this setting in their readTopology() and readBuffers() implementations.

Enumerator
Original 

Deserialize both topology and all value buffers. This is the default behaviour and produces a fully populated grid identical to the one that was written.

Half 

Deserialize topology and value buffers, converting each voxel value to half-precision floating point on the fly. Codecs that do not support native half conversion should fall back to Original and record a ReadDiagnostic warning.

Bool 

Deserialize topology and value buffers, converting each voxel value to bool (non-zero to true, zero to false). Produces a BoolGrid whose active set matches the source grid's active set.

Mask 

Deserialize topology only and promote the result to a mask grid, discarding all value data. Equivalent to reading TopologyOnly and then constructing a MaskGrid from the active-voxel set, but may be performed more efficiently inside the codec.

TopologyOnly 

Deserialize topology only; reading of value buffers may be skipped. Useful when only the active-voxel mask is needed and avoiding the cost of reading large value buffers is desirable.

Warning
Only the topology is guaranteed. The resulting grid has a valid tree structure (node hierarchy, tiles and active/inactive state), but the voxel and tile values are unspecified. They are typically the grid's background value, however a grid read from a file without grid offsets is fully cached up-front, so the returned grid keeps the values that were read. Deep-copying such a grid to reset its values would cost more than the read this mode is meant to avoid. Callers must not rely on the values being the background value.
MetadataOnly 

Deserialize grid metadata and transform only; no topology, no value buffers. The codec is still used to construct the correct grid type, but its readTopology()/readBuffers() are not called.

Function Documentation

◆ bloscFromStream()

void bloscFromStream ( std::istream & ,
char * data,
size_t numBytes )

◆ bloscToStream()

void bloscToStream ( std::ostream & ,
const char * data,
size_t valSize,
size_t numVals )

◆ bloscToStreamSize()

size_t bloscToStreamSize ( const char * data,
size_t valSize,
size_t numVals )

◆ checkFormatVersion()

void checkFormatVersion ( std::ios_base & )

Throws an IoError if the file format version number is not supported.

◆ clearStreamMetadataPtr()

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.

◆ compressionToString()

std::string compressionToString ( uint32_t flags)

Return a string describing the given compression flags.

◆ getDataCompression()

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.

◆ getErrorString() [1/2]

std::string getErrorString ( )

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

◆ getErrorString() [2/2]

std::string getErrorString ( int errorNum)

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

◆ getFormatVersion()

uint32_t getFormatVersion ( std::ios_base & )

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

See also
File::setFormatVersion()

◆ getGridBackgroundValuePtr()

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.

◆ getGridClass()

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.

◆ getHalfFloat()

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.

◆ getLibraryVersion()

VersionId getLibraryVersion ( std::ios_base & )

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

See also
File::setLibraryVersion()

◆ getMappedFilePtr()

SharedPtr< MappedFile > getMappedFilePtr ( std::ios_base & )
inline
Deprecated
"Always returns a null pointer. This function is deprecated and will be removed. Delayed loading is no longer supported."

◆ getStreamMetadataPtr()

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.

◆ getVersion()

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.

◆ getWriteGridStatsMetadata()

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.

◆ operator<<() [1/2]

std::ostream & operator<< ( std::ostream & ,
const StreamMetadata &  )

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

◆ operator<<() [2/2]

std::ostream & operator<< ( std::ostream & ,
const StreamMetadata::AuxDataMap &  )

◆ readCompressedValues() [1/2]

template<>
void readCompressedValues ( std::istream & is,
PointDataIndex32 * destBuf,
Index destCount,
const util::NodeMask< 3 > & ,
bool ,
const PointDataIndex32 *  )
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]

template<typename ValueT, typename MaskT>
void readCompressedValues ( std::istream & is,
ValueT * destBuf,
Index destCount,
const MaskT & valueMask,
bool fromHalf,
const ValueT * background = nullptr )
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
isa stream from which to read data (possibly compressed, depending on the stream's compression settings)
destBufa buffer into which to read values of type ValueT
destCountthe number of values to be stored in the buffer
valueMaska bitmask (typically, a node's value mask) indicating which positions in the buffer correspond to active values
fromHalfif true, read 16-bit half floats from the input stream and convert them to full floats
backgroundoptional background value used when mask compressed

◆ readData()

template<typename T>
void readData ( std::istream & is,
T * data,
Index count,
uint32_t compression )
inline

Read data from a stream.

Parameters
isthe input stream
datathe contiguous array of data to read in
countthe number of elements to read in
compressionwhether and how the data is compressed (either COMPRESS_NONE, COMPRESS_ZIP, COMPRESS_ACTIVE_MASK or COMPRESS_BLOSC)
Exceptions
IoErrorif 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 >()

template<>
void readData< std::string > ( std::istream & is,
std::string * data,
Index count,
uint32_t  )
inline

Specialization for std::string input.

◆ setCurrentVersion()

void setCurrentVersion ( std::istream & )

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

◆ setDataCompression()

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.

◆ setGridBackgroundValuePtr()

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.

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

◆ setGridClass()

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.

◆ setHalfFloat()

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.

◆ setMappedFilePtr()

void setMappedFilePtr ( std::ios_base & ,
SharedPtr< MappedFile > &  )
inline
Deprecated
"This function is deprecated and will be removed. Delayed loading is no longer supported."

◆ setStreamMetadataPtr()

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.

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()

void 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()

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.

◆ truncateRealToHalf()

template<typename T>
T truncateRealToHalf ( const T & val)
inline

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

◆ unzipFromStream()

void unzipFromStream ( std::istream & ,
char * data,
size_t numBytes )

◆ writeCompressedValues() [1/2]

template<>
void writeCompressedValues ( std::ostream & os,
const PointDataIndex32 * srcBuf,
Index srcCount,
const util::NodeMask< 3 > & ,
const util::NodeMask< 3 > & ,
bool ,
const PointDataIndex32 *  )
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]

template<typename ValueT, typename MaskT>
void writeCompressedValues ( std::ostream & os,
const ValueT * srcBuf,
Index srcCount,
const MaskT & valueMask,
const MaskT & childMask,
bool toHalf,
const ValueT * background = nullptr )
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
osa stream to which to write data (possibly compressed, depending on the stream's compression settings)
srcBufa buffer containing values of type ValueT to be written
srcCountthe number of values stored in the buffer
valueMaska bitmask (typically, a node's value mask) indicating which positions in the buffer correspond to active values
childMaska bitmask (typically, a node's child mask) indicating which positions in the buffer correspond to child node pointers
toHalfif true, convert floating-point values to 16-bit half floats
backgroundoptional background value used when mask compressed

◆ writeCompressedValuesSize() [1/2]

template<typename T>
void writeCompressedValuesSize ( std::ostream & os,
const T * srcBuf,
Index srcCount )
inline

◆ writeCompressedValuesSize() [2/2]

template<typename ValueT, typename MaskT>
size_t writeCompressedValuesSize ( ValueT * srcBuf,
Index srcCount,
const MaskT & valueMask,
uint8_t maskMetadata,
bool toHalf,
uint32_t compress )
inline

◆ writeData()

template<typename T>
void writeData ( std::ostream & os,
const T * data,
Index count,
uint32_t compression )
inline

Write data to a stream.

Parameters
osthe output stream
datathe contiguous array of data to write
countthe number of elements to write out
compressionwhether and how to compress the data (either COMPRESS_NONE, COMPRESS_ZIP, COMPRESS_ACTIVE_MASK or COMPRESS_BLOSC)
Exceptions
IoErrorif 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 >()

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

Specialization for std::string output.

◆ writeDataSize()

template<typename T>
size_t writeDataSize ( const T * data,
Index count,
uint32_t compression )
inline

◆ writeDataSize< std::string >()

template<>
size_t writeDataSize< std::string > ( const std::string * data,
Index count,
uint32_t  )
inline

Specialization for std::string output.

◆ zipToStream()

void zipToStream ( std::ostream & ,
const char * data,
size_t numBytes )

◆ zipToStreamSize()

size_t zipToStreamSize ( const char * data,
size_t numBytes )