Loading...
Searching...
No Matches
io.h
Go to the documentation of this file.
// Copyright Contributors to the OpenVDB Project
// SPDX-License-Identifier: MPL-2.0
#ifndef OPENVDB_IO_IO_HAS_BEEN_INCLUDED
#define OPENVDB_IO_IO_HAS_BEEN_INCLUDED
#include <openvdb/Platform.h>
#include <openvdb/Types.h> // for SharedPtr
#include <openvdb/version.h>
#include <any>
#include <functional>
#include <iosfwd> // for std::ios_base
#include <map>
#include <memory>
#include <string>
class TestMappedFile;
namespace openvdb {
OPENVDB_USE_VERSION_NAMESPACE
namespace OPENVDB_VERSION_NAME {
class MetaMap;
namespace io {
/// @brief Container for metadata describing how to unserialize grids from and/or
/// serialize grids to a stream (which file format, compression scheme, etc. to use)
/// @details This class is mainly for internal use.
class OPENVDB_API StreamMetadata
{
public:
using Ptr = SharedPtr<StreamMetadata>;
using ConstPtr = SharedPtr<const StreamMetadata>;
StreamMetadata();
StreamMetadata(const StreamMetadata&);
explicit StreamMetadata(std::ios_base&);
~StreamMetadata();
StreamMetadata& operator=(const StreamMetadata&);
/// @brief Transfer metadata items directly to the given stream.
/// @todo Deprecate direct transfer; use StreamMetadata structs everywhere.
void transferTo(std::ios_base&) const;
uint32_t fileVersion() const;
void setFileVersion(uint32_t);
VersionId libraryVersion() const;
void setLibraryVersion(VersionId);
uint32_t compression() const;
void setCompression(uint32_t);
uint32_t gridClass() const;
void setGridClass(uint32_t);
const void* backgroundPtr() const;
void setBackgroundPtr(const void*);
bool halfFloat() const;
void setHalfFloat(bool);
bool writeGridStats() const;
void setWriteGridStats(bool);
bool seekable() const;
void setSeekable(bool);
bool delayedLoadMeta() const;
bool countingPasses() const;
void setCountingPasses(bool);
uint32_t pass() const;
void setPass(uint32_t);
uint64_t leaf() const;
void setLeaf(uint64_t);
//@{
/// @brief Return a (reference to a) copy of the metadata of the grid
/// currently being read or written.
/// @details Some grid metadata might duplicate information returned by
/// gridClass(), backgroundPtr() and other accessors, but those values
/// are not guaranteed to be kept in sync.
MetaMap& gridMetadata();
const MetaMap& gridMetadata() const;
//@}
using AuxDataMap = std::map<std::string, std::any>;
//@{
/// @brief Return a map that can be populated with arbitrary user data.
AuxDataMap& auxData();
const AuxDataMap& auxData() const;
//@}
/// @private
uint32_t __test() const;
/// @private
void __setTest(uint32_t);
/// Return a string describing this stream metadata.
std::string str() const;
private:
struct Impl;
std::unique_ptr<Impl> mImpl;
}; // class StreamMetadata
/// Write a description of the given metadata to an output stream.
std::ostream& operator<<(std::ostream&, const StreamMetadata&);
std::ostream& operator<<(std::ostream&, const StreamMetadata::AuxDataMap&);
////////////////////////////////////////
/// @brief Leaf nodes that require multi-pass I/O must inherit from this struct.
/// @sa Grid::hasMultiPassIO()
struct MultiPass {};
////////////////////////////////////////
class File;
#ifdef OPENVDB_USE_DELAYED_LOADING
/// @brief Handle to control the lifetime of a memory-mapped .vdb file
class OPENVDB_API MappedFile
{
public:
using Ptr = SharedPtr<MappedFile>;
~MappedFile();
MappedFile(const MappedFile&) = delete; // not copyable
MappedFile& operator=(const MappedFile&) = delete;
/// Return the filename of the mapped file.
std::string filename() const;
/// @brief Return a new stream buffer for the mapped file.
/// @details Typical usage is
/// @code
/// openvdb::io::MappedFile::Ptr mappedFile = ...;
/// auto buf = mappedFile->createBuffer();
/// std::istream istrm{buf.get()};
/// // Read from istrm...
/// @endcode
/// The buffer must persist as long as the stream is open.
SharedPtr<std::streambuf> createBuffer() const;
using Notifier = std::function<void(std::string /*filename*/)>;
/// @brief Register a function that will be called with this file's name
/// when the file is unmapped.
void setNotifier(const Notifier&);
/// Deregister the notifier.
void clearNotifier();
private:
friend class File;
friend class ::TestMappedFile;
explicit MappedFile(const std::string& filename, bool autoDelete = false);
class Impl;
std::unique_ptr<Impl> mImpl;
}; // class MappedFile
#endif // OPENVDB_USE_DELAYED_LOADING
////////////////////////////////////////
/// Return a string (possibly empty) describing the given system error code.
std::string getErrorString(int errorNum);
/// Return a string (possibly empty) describing the most recent system error.
std::string getErrorString();
////////////////////////////////////////
/// @brief Return the file format version number associated with the given input stream.
/// @sa File::setFormatVersion()
OPENVDB_API uint32_t getFormatVersion(std::ios_base&);
/// @brief Return the (major, minor) library version number associated with the given input stream.
/// @sa File::setLibraryVersion()
OPENVDB_API VersionId getLibraryVersion(std::ios_base&);
/// @brief Return a string of the form "<major>.<minor>/<format>", giving the library
/// and file format version numbers associated with the given input stream.
OPENVDB_API std::string getVersion(std::ios_base&);
/// Associate the current file format and library version numbers with the given input stream.
OPENVDB_API void setCurrentVersion(std::istream&);
/// @brief Associate specific file format and library version numbers with the given stream.
/// @details This is typically called immediately after reading a header that contains
/// the version numbers. Data read subsequently can then be interpreted appropriately.
OPENVDB_API void setVersion(std::ios_base&, const VersionId& libraryVersion, uint32_t fileVersion);
/// @brief 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.
OPENVDB_API uint32_t getDataCompression(std::ios_base&);
/// @brief 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.
OPENVDB_API void setDataCompression(std::ios_base&, uint32_t compressionFlags);
/// @brief Return the class (GRID_LEVEL_SET, GRID_UNKNOWN, etc.) of the grid
/// currently being read from or written to the given stream.
OPENVDB_API uint32_t getGridClass(std::ios_base&);
/// @brief Associate with the given stream the class (GRID_LEVEL_SET, GRID_UNKNOWN, etc.)
/// of the grid currently being read or written.
OPENVDB_API void setGridClass(std::ios_base&, uint32_t);
/// @brief 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.
OPENVDB_API bool getHalfFloat(std::ios_base&);
/// @brief 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.
OPENVDB_API void setHalfFloat(std::ios_base&, bool);
/// @brief Return a pointer to the background value of the grid
/// currently being read from or written to the given stream.
OPENVDB_API const void* getGridBackgroundValuePtr(std::ios_base&);
/// @brief 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.
OPENVDB_API void setGridBackgroundValuePtr(std::ios_base&, const void* background);
/// @brief Return @c 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.
OPENVDB_API bool getWriteGridStatsMetadata(std::ios_base&);
/// @brief 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.
OPENVDB_API void setWriteGridStatsMetadata(std::ios_base&, bool writeGridStats);
#ifdef OPENVDB_USE_DELAYED_LOADING
/// @brief 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.
OPENVDB_API SharedPtr<MappedFile> getMappedFilePtr(std::ios_base&);
/// @brief 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.
OPENVDB_API void setMappedFilePtr(std::ios_base&, SharedPtr<MappedFile>&);
#endif // OPENVDB_USE_DELAYED_LOADING
/// @brief 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.
OPENVDB_API SharedPtr<StreamMetadata> getStreamMetadataPtr(std::ios_base&);
/// @brief 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.
/// @details If @a 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.
OPENVDB_API void setStreamMetadataPtr(std::ios_base&,
SharedPtr<StreamMetadata>&, bool transfer = true);
/// @brief Dissociate the given stream from its metadata object (if it has one)
/// and return a shared pointer to the object.
OPENVDB_API SharedPtr<StreamMetadata> clearStreamMetadataPtr(std::ios_base&);
} // namespace io
} // namespace OPENVDB_VERSION_NAME
} // namespace openvdb
#endif // OPENVDB_IO_IO_HAS_BEEN_INCLUDED
operator<<
OPENVDB_API std::ostream & operator<<(std::ostream &os, half h)
Output h to os, formatted as a float.
Platform.h
OPENVDB_API
#define OPENVDB_API
Definition Platform.h:274
Types.h
openvdb::v11_0::MetaMap
Container that maps names (strings) to values of arbitrary types.
Definition MetaMap.h:20
openvdb::v11_0::io::File
Grid archive associated with a file on disk.
Definition File.h:31
openvdb::v11_0::io::StreamMetadata
Container for metadata describing how to unserialize grids from and/or serialize grids to a stream (w...
Definition io.h:31
openvdb::v11_0::io::StreamMetadata::delayedLoadMeta
bool delayedLoadMeta() const
openvdb::v11_0::io::StreamMetadata::setGridClass
void setGridClass(uint32_t)
openvdb::v11_0::io::StreamMetadata::AuxDataMap
std::map< std::string, std::any > AuxDataMap
Definition io.h:92
openvdb::v11_0::io::StreamMetadata::setCompression
void setCompression(uint32_t)
openvdb::v11_0::io::StreamMetadata::operator=
StreamMetadata & operator=(const StreamMetadata &)
openvdb::v11_0::io::StreamMetadata::gridClass
uint32_t gridClass() const
openvdb::v11_0::io::StreamMetadata::~StreamMetadata
~StreamMetadata()
openvdb::v11_0::io::StreamMetadata::fileVersion
uint32_t fileVersion() const
openvdb::v11_0::io::StreamMetadata::ConstPtr
SharedPtr< const StreamMetadata > ConstPtr
Definition io.h:34
openvdb::v11_0::io::StreamMetadata::setHalfFloat
void setHalfFloat(bool)
openvdb::v11_0::io::StreamMetadata::Ptr
SharedPtr< StreamMetadata > Ptr
Definition io.h:33
openvdb::v11_0::io::StreamMetadata::gridMetadata
MetaMap & gridMetadata()
Return a (reference to a) copy of the metadata of the grid currently being read or written.
openvdb::v11_0::io::StreamMetadata::leaf
uint64_t leaf() const
openvdb::v11_0::io::StreamMetadata::StreamMetadata
StreamMetadata()
openvdb::v11_0::io::StreamMetadata::backgroundPtr
const void * backgroundPtr() const
openvdb::v11_0::io::StreamMetadata::StreamMetadata
StreamMetadata(std::ios_base &)
openvdb::v11_0::io::StreamMetadata::countingPasses
bool countingPasses() const
openvdb::v11_0::io::StreamMetadata::auxData
const AuxDataMap & auxData() const
openvdb::v11_0::io::StreamMetadata::setLeaf
void setLeaf(uint64_t)
openvdb::v11_0::io::StreamMetadata::auxData
AuxDataMap & auxData()
Return a map that can be populated with arbitrary user data.
openvdb::v11_0::io::StreamMetadata::pass
uint32_t pass() const
openvdb::v11_0::io::StreamMetadata::setSeekable
void setSeekable(bool)
openvdb::v11_0::io::StreamMetadata::compression
uint32_t compression() const
openvdb::v11_0::io::StreamMetadata::setBackgroundPtr
void setBackgroundPtr(const void *)
openvdb::v11_0::io::StreamMetadata::seekable
bool seekable() const
openvdb::v11_0::io::StreamMetadata::setFileVersion
void setFileVersion(uint32_t)
openvdb::v11_0::io::StreamMetadata::writeGridStats
bool writeGridStats() const
openvdb::v11_0::io::StreamMetadata::transferTo
void transferTo(std::ios_base &) const
Transfer metadata items directly to the given stream.
openvdb::v11_0::io::StreamMetadata::setLibraryVersion
void setLibraryVersion(VersionId)
openvdb::v11_0::io::StreamMetadata::StreamMetadata
StreamMetadata(const StreamMetadata &)
openvdb::v11_0::io::StreamMetadata::halfFloat
bool halfFloat() const
openvdb::v11_0::io::StreamMetadata::gridMetadata
const MetaMap & gridMetadata() const
openvdb::v11_0::io::StreamMetadata::str
std::string str() const
Return a string describing this stream metadata.
openvdb::v11_0::io::StreamMetadata::libraryVersion
VersionId libraryVersion() const
openvdb::v11_0::io::StreamMetadata::setCountingPasses
void setCountingPasses(bool)
openvdb::v11_0::io::StreamMetadata::setWriteGridStats
void setWriteGridStats(bool)
openvdb::v11_0::io::StreamMetadata::setPass
void setPass(uint32_t)
openvdb::v11_0::io::getDataCompression
OPENVDB_API uint32_t getDataCompression(std::ios_base &)
Return a bitwise OR of compression option flags (COMPRESS_ZIP, COMPRESS_ACTIVE_MASK,...
openvdb::v11_0::io::setGridBackgroundValuePtr
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 g...
openvdb::v11_0::io::setCurrentVersion
OPENVDB_API void setCurrentVersion(std::istream &)
Associate the current file format and library version numbers with the given input stream.
openvdb::v11_0::io::getFormatVersion
OPENVDB_API uint32_t getFormatVersion(std::ios_base &)
Return the file format version number associated with the given input stream.
openvdb::v11_0::io::getLibraryVersion
OPENVDB_API VersionId getLibraryVersion(std::ios_base &)
Return the (major, minor) library version number associated with the given input stream.
openvdb::v11_0::io::getErrorString
std::string getErrorString(int errorNum)
Return a string (possibly empty) describing the given system error code.
openvdb::v11_0::io::getHalfFloat
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 ...
openvdb::v11_0::io::getWriteGridStatsMetadata
OPENVDB_API bool getWriteGridStatsMetadata(std::ios_base &)
Return true if grid statistics (active voxel count and bounding box, etc.) should be computed and sto...
openvdb::v11_0::io::setWriteGridStatsMetadata
OPENVDB_API void setWriteGridStatsMetadata(std::ios_base &, bool writeGridStats)
Specify whether to compute grid statistics (active voxel count and bounding box, etc....
openvdb::v11_0::io::setVersion
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.
openvdb::v11_0::io::getGridBackgroundValuePtr
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 give...
openvdb::v11_0::io::clearStreamMetadataPtr
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 t...
openvdb::v11_0::io::setStreamMetadataPtr
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,...
openvdb::v11_0::io::getGridClass
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 writte...
openvdb::v11_0::io::getStreamMetadataPtr
OPENVDB_API SharedPtr< StreamMetadata > getStreamMetadataPtr(std::ios_base &)
Return a shared pointer to an object that stores metadata (file format, compression scheme,...
openvdb::v11_0::io::setHalfFloat
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...
openvdb::v11_0::io::setGridClass
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 ...
openvdb::v11_0::io::getVersion
OPENVDB_API std::string getVersion(std::ios_base &)
Return a string of the form "<major>.<minor>/<format>", giving the library and file format version nu...
openvdb::v11_0::io::setDataCompression
OPENVDB_API void setDataCompression(std::ios_base &, uint32_t compressionFlags)
Associate with the given stream a bitwise OR of compression option flags (COMPRESS_ZIP,...
openvdb::v11_0::SharedPtr
std::shared_ptr< T > SharedPtr
Definition Types.h:114
openvdb
Definition Exceptions.h:13
openvdb::v11_0::VersionId
Definition version.h.in:273
openvdb::v11_0::io::MultiPass
Leaf nodes that require multi-pass I/O must inherit from this struct.
Definition io.h:124
OPENVDB_VERSION_NAME
#define OPENVDB_VERSION_NAME
The version namespace name for this library version.
Definition version.h.in:121
OPENVDB_USE_VERSION_NAMESPACE
#define OPENVDB_USE_VERSION_NAMESPACE
Definition version.h.in:212