OpenVDB 13.0.0

Loading...
Searching...
No Matches
io.h
Go to the documentation of this file.
1// Copyright Contributors to the OpenVDB Project
2// SPDX-License-Identifier: Apache-2.0
3
4#ifndef OPENVDB_IO_IO_HAS_BEEN_INCLUDED
5#define OPENVDB_IO_IO_HAS_BEEN_INCLUDED
6
7#include <openvdb/Platform.h>
8#include <openvdb/Types.h> // for SharedPtr
9#include <openvdb/version.h>
10#include <any>
11#include <functional>
12#include <iosfwd> // for std::ios_base
13#include <map>
14#include <memory>
15#include <string>
16
17 class TestMappedFile;
18
19 namespace openvdb {
20 OPENVDB_USE_VERSION_NAMESPACE
21 namespace OPENVDB_VERSION_NAME {
22
23 class MetaMap;
24
25 namespace io {
26
27/// @brief Container for metadata describing how to unserialize grids from and/or
28/// serialize grids to a stream (which file format, compression scheme, etc. to use)
29/// @details This class is mainly for internal use.
30 class OPENVDB_API StreamMetadata
31{
32 public:
33 using Ptr = SharedPtr<StreamMetadata>;
34 using ConstPtr = SharedPtr<const StreamMetadata>;
35
36 StreamMetadata();
37 StreamMetadata(const StreamMetadata&);
38 explicit StreamMetadata(std::ios_base&);
39 ~StreamMetadata();
40
41 StreamMetadata& operator=(const StreamMetadata&);
42
43 /// @brief Transfer metadata items directly to the given stream.
44 /// @todo Deprecate direct transfer; use StreamMetadata structs everywhere.
45 void transferTo(std::ios_base&) const;
46
47 uint32_t fileVersion() const;
48 void setFileVersion(uint32_t);
49
50 VersionId libraryVersion() const;
51 void setLibraryVersion(VersionId);
52
53 uint32_t compression() const;
54 void setCompression(uint32_t);
55
56 uint32_t gridClass() const;
57 void setGridClass(uint32_t);
58
59 const void* backgroundPtr() const;
60 void setBackgroundPtr(const void*);
61
62 bool halfFloat() const;
63 void setHalfFloat(bool);
64
65 bool writeGridStats() const;
66 void setWriteGridStats(bool);
67
68 bool seekable() const;
69 void setSeekable(bool);
70
71 bool delayedLoadMeta() const;
72
73 bool countingPasses() const;
74 void setCountingPasses(bool);
75
76 uint32_t pass() const;
77 void setPass(uint32_t);
78
79 uint64_t leaf() const;
80 void setLeaf(uint64_t);
81
82 //@{
83 /// @brief Return a (reference to a) copy of the metadata of the grid
84 /// currently being read or written.
85 /// @details Some grid metadata might duplicate information returned by
86 /// gridClass(), backgroundPtr() and other accessors, but those values
87 /// are not guaranteed to be kept in sync.
88 MetaMap& gridMetadata();
89 const MetaMap& gridMetadata() const;
90 //@}
91
92 using AuxDataMap = std::map<std::string, std::any>;
93 //@{
94 /// @brief Return a map that can be populated with arbitrary user data.
95 AuxDataMap& auxData();
96 const AuxDataMap& auxData() const;
97 //@}
98
99 /// @private
100 uint32_t __test() const;
101 /// @private
102 void __setTest(uint32_t);
103
104 /// Return a string describing this stream metadata.
105 std::string str() const;
106
107 private:
108 struct Impl;
109 std::unique_ptr<Impl> mImpl;
110}; // class StreamMetadata
111
112
113/// Write a description of the given metadata to an output stream.
114std::ostream& operator<<(std::ostream&, const StreamMetadata&);
115
116std::ostream& operator<<(std::ostream&, const StreamMetadata::AuxDataMap&);
117
118
119////////////////////////////////////////
120
121
122/// @brief Leaf nodes that require multi-pass I/O must inherit from this struct.
123/// @sa Grid::hasMultiPassIO()
124 struct MultiPass {};
125
126
127////////////////////////////////////////
128
129
130 class File;
131
132#ifdef OPENVDB_USE_DELAYED_LOADING
133
134/// @brief Handle to control the lifetime of a memory-mapped .vdb file
135 class OPENVDB_API MappedFile
136{
137 public:
138 using Ptr = SharedPtr<MappedFile>;
139
140 ~MappedFile();
141 MappedFile(const MappedFile&) = delete; // not copyable
142 MappedFile& operator=(const MappedFile&) = delete;
143
144 /// Return the filename of the mapped file.
145 std::string filename() const;
146
147 /// @brief Return a new stream buffer for the mapped file.
148 /// @details Typical usage is
149 /// @code
150 /// openvdb::io::MappedFile::Ptr mappedFile = ...;
151 /// auto buf = mappedFile->createBuffer();
152 /// std::istream istrm{buf.get()};
153 /// // Read from istrm...
154 /// @endcode
155 /// The buffer must persist as long as the stream is open.
156 SharedPtr<std::streambuf> createBuffer() const;
157
158 using Notifier = std::function<void(std::string /*filename*/)>;
159 /// @brief Register a function that will be called with this file's name
160 /// when the file is unmapped.
161 void setNotifier(const Notifier&);
162 /// Deregister the notifier.
163 void clearNotifier();
164
165 private:
166 friend class File;
167 friend class ::TestMappedFile;
168
169 explicit MappedFile(const std::string& filename, bool autoDelete = false);
170
171 class Impl;
172 std::unique_ptr<Impl> mImpl;
173}; // class MappedFile
174
175#endif // OPENVDB_USE_DELAYED_LOADING
176
177////////////////////////////////////////
178
179
180/// Return a string (possibly empty) describing the given system error code.
181std::string getErrorString(int errorNum);
182
183
184/// Return a string (possibly empty) describing the most recent system error.
185std::string getErrorString();
186
187
188////////////////////////////////////////
189
190
191/// @brief Return the file format version number associated with the given input stream.
192/// @sa File::setFormatVersion()
193 OPENVDB_API uint32_t getFormatVersion(std::ios_base&);
194
195/// @brief Throws an IoError if the file format version number is not supported.
196 OPENVDB_API void checkFormatVersion(std::ios_base&);
197
198/// @brief Return the (major, minor) library version number associated with the given input stream.
199/// @sa File::setLibraryVersion()
200 OPENVDB_API VersionId getLibraryVersion(std::ios_base&);
201
202/// @brief Return a string of the form "<major>.<minor>/<format>", giving the library
203/// and file format version numbers associated with the given input stream.
204 OPENVDB_API std::string getVersion(std::ios_base&);
205
206/// Associate the current file format and library version numbers with the given input stream.
207 OPENVDB_API void setCurrentVersion(std::istream&);
208
209/// @brief Associate specific file format and library version numbers with the given stream.
210/// @details This is typically called immediately after reading a header that contains
211/// the version numbers. Data read subsequently can then be interpreted appropriately.
212 OPENVDB_API void setVersion(std::ios_base&, const VersionId& libraryVersion, uint32_t fileVersion);
213
214/// @brief Return a bitwise OR of compression option flags (COMPRESS_ZIP,
215/// COMPRESS_ACTIVE_MASK, etc.) specifying whether and how input data is compressed
216/// or output data should be compressed.
217 OPENVDB_API uint32_t getDataCompression(std::ios_base&);
218/// @brief Associate with the given stream a bitwise OR of compression option flags
219/// (COMPRESS_ZIP, COMPRESS_ACTIVE_MASK, etc.) specifying whether and how input data
220/// is compressed or output data should be compressed.
221 OPENVDB_API void setDataCompression(std::ios_base&, uint32_t compressionFlags);
222
223/// @brief Return the class (GRID_LEVEL_SET, GRID_UNKNOWN, etc.) of the grid
224/// currently being read from or written to the given stream.
225 OPENVDB_API uint32_t getGridClass(std::ios_base&);
226/// @brief Associate with the given stream the class (GRID_LEVEL_SET, GRID_UNKNOWN, etc.)
227/// of the grid currently being read or written.
228 OPENVDB_API void setGridClass(std::ios_base&, uint32_t);
229
230/// @brief Return true if floating-point values should be quantized to 16 bits when writing
231/// to the given stream or promoted back from 16-bit to full precision when reading from it.
232 OPENVDB_API bool getHalfFloat(std::ios_base&);
233/// @brief Specify whether floating-point values should be quantized to 16 bits when writing
234/// to the given stream or promoted back from 16-bit to full precision when reading from it.
235 OPENVDB_API void setHalfFloat(std::ios_base&, bool);
236
237/// @brief Return a pointer to the background value of the grid
238/// currently being read from or written to the given stream.
239 OPENVDB_API const void* getGridBackgroundValuePtr(std::ios_base&);
240/// @brief Specify (a pointer to) the background value of the grid
241/// currently being read from or written to the given stream.
242/// @note The pointer must remain valid until the entire grid has been read or written.
243 OPENVDB_API void setGridBackgroundValuePtr(std::ios_base&, const void* background);
244
245/// @brief Return @c true if grid statistics (active voxel count and bounding box, etc.)
246/// should be computed and stored as grid metadata when writing to the given stream.
247 OPENVDB_API bool getWriteGridStatsMetadata(std::ios_base&);
248/// @brief Specify whether to compute grid statistics (active voxel count and bounding box, etc.)
249/// and store them as grid metadata when writing to the given stream.
250 OPENVDB_API void setWriteGridStatsMetadata(std::ios_base&, bool writeGridStats);
251
252#ifdef OPENVDB_USE_DELAYED_LOADING
253/// @brief Return a shared pointer to the memory-mapped file with which the given stream
254/// is associated, or a null pointer if the stream is not associated with a memory-mapped file.
255 OPENVDB_API SharedPtr<MappedFile> getMappedFilePtr(std::ios_base&);
256/// @brief Associate the given stream with (a shared pointer to) a memory-mapped file.
257/// @note The shared pointer object (not just the io::MappedFile object to which it points)
258/// must remain valid until the file is closed.
259 OPENVDB_API void setMappedFilePtr(std::ios_base&, SharedPtr<MappedFile>&);
260#endif // OPENVDB_USE_DELAYED_LOADING
261
262/// @brief Return a shared pointer to an object that stores metadata (file format,
263/// compression scheme, etc.) for use when reading from or writing to the given stream.
264 OPENVDB_API SharedPtr<StreamMetadata> getStreamMetadataPtr(std::ios_base&);
265/// @brief Associate the given stream with (a shared pointer to) an object that stores
266/// metadata (file format, compression scheme, etc.) for use when reading from
267/// or writing to the stream.
268/// @details If @a transfer is true, copy metadata from the object directly to the stream
269/// (for backward compatibility with older versions of the library).
270/// @note The shared pointer object (not just the io::StreamMetadata object to which it points)
271/// must remain valid until the file is closed.
272 OPENVDB_API void setStreamMetadataPtr(std::ios_base&,
273 SharedPtr<StreamMetadata>&, bool transfer = true);
274/// @brief Dissociate the given stream from its metadata object (if it has one)
275/// and return a shared pointer to the object.
276 OPENVDB_API SharedPtr<StreamMetadata> clearStreamMetadataPtr(std::ios_base&);
277
278} // namespace io
279} // namespace OPENVDB_VERSION_NAME
280} // namespace openvdb
281
282#endif // OPENVDB_IO_IO_HAS_BEEN_INCLUDED
Platform.h
OPENVDB_API
#define OPENVDB_API
Definition Platform.h:291
openvdb::v13_0::MetaMap
Container that maps names (strings) to values of arbitrary types.
Definition MetaMap.h:20
openvdb::v13_0::io::File
Grid archive associated with a file on disk.
Definition File.h:31
openvdb::v13_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::v13_0::io::StreamMetadata::delayedLoadMeta
bool delayedLoadMeta() const
openvdb::v13_0::io::StreamMetadata::setGridClass
void setGridClass(uint32_t)
openvdb::v13_0::io::StreamMetadata::AuxDataMap
std::map< std::string, std::any > AuxDataMap
Definition io.h:92
openvdb::v13_0::io::StreamMetadata::setCompression
void setCompression(uint32_t)
openvdb::v13_0::io::StreamMetadata::operator=
StreamMetadata & operator=(const StreamMetadata &)
openvdb::v13_0::io::StreamMetadata::gridClass
uint32_t gridClass() const
openvdb::v13_0::io::StreamMetadata::~StreamMetadata
~StreamMetadata()
openvdb::v13_0::io::StreamMetadata::fileVersion
uint32_t fileVersion() const
openvdb::v13_0::io::StreamMetadata::ConstPtr
SharedPtr< const StreamMetadata > ConstPtr
Definition io.h:34
openvdb::v13_0::io::StreamMetadata::setHalfFloat
void setHalfFloat(bool)
openvdb::v13_0::io::StreamMetadata::Ptr
SharedPtr< StreamMetadata > Ptr
Definition io.h:33
openvdb::v13_0::io::StreamMetadata::gridMetadata
MetaMap & gridMetadata()
Return a (reference to a) copy of the metadata of the grid currently being read or written.
openvdb::v13_0::io::StreamMetadata::leaf
uint64_t leaf() const
openvdb::v13_0::io::StreamMetadata::StreamMetadata
StreamMetadata()
openvdb::v13_0::io::StreamMetadata::backgroundPtr
const void * backgroundPtr() const
openvdb::v13_0::io::StreamMetadata::StreamMetadata
StreamMetadata(std::ios_base &)
openvdb::v13_0::io::StreamMetadata::countingPasses
bool countingPasses() const
openvdb::v13_0::io::StreamMetadata::auxData
const AuxDataMap & auxData() const
openvdb::v13_0::io::StreamMetadata::setLeaf
void setLeaf(uint64_t)
openvdb::v13_0::io::StreamMetadata::auxData
AuxDataMap & auxData()
Return a map that can be populated with arbitrary user data.
openvdb::v13_0::io::StreamMetadata::pass
uint32_t pass() const
openvdb::v13_0::io::StreamMetadata::setSeekable
void setSeekable(bool)
openvdb::v13_0::io::StreamMetadata::compression
uint32_t compression() const
openvdb::v13_0::io::StreamMetadata::setBackgroundPtr
void setBackgroundPtr(const void *)
openvdb::v13_0::io::StreamMetadata::seekable
bool seekable() const
openvdb::v13_0::io::StreamMetadata::setFileVersion
void setFileVersion(uint32_t)
openvdb::v13_0::io::StreamMetadata::writeGridStats
bool writeGridStats() const
openvdb::v13_0::io::StreamMetadata::transferTo
void transferTo(std::ios_base &) const
Transfer metadata items directly to the given stream.
openvdb::v13_0::io::StreamMetadata::setLibraryVersion
void setLibraryVersion(VersionId)
openvdb::v13_0::io::StreamMetadata::StreamMetadata
StreamMetadata(const StreamMetadata &)
openvdb::v13_0::io::StreamMetadata::halfFloat
bool halfFloat() const
openvdb::v13_0::io::StreamMetadata::gridMetadata
const MetaMap & gridMetadata() const
openvdb::v13_0::io::StreamMetadata::str
std::string str() const
Return a string describing this stream metadata.
openvdb::v13_0::io::StreamMetadata::libraryVersion
VersionId libraryVersion() const
openvdb::v13_0::io::StreamMetadata::setCountingPasses
void setCountingPasses(bool)
openvdb::v13_0::io::StreamMetadata::setWriteGridStats
void setWriteGridStats(bool)
openvdb::v13_0::io::StreamMetadata::setPass
void setPass(uint32_t)
openvdb::v13_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::v13_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::v13_0::io::setCurrentVersion
OPENVDB_API void setCurrentVersion(std::istream &)
Associate the current file format and library version numbers with the given input stream.
openvdb::v13_0::io::getFormatVersion
OPENVDB_API uint32_t getFormatVersion(std::ios_base &)
Return the file format version number associated with the given input stream.
openvdb::v13_0::io::getLibraryVersion
OPENVDB_API VersionId getLibraryVersion(std::ios_base &)
Return the (major, minor) library version number associated with the given input stream.
openvdb::v13_0::io::getErrorString
std::string getErrorString(int errorNum)
Return a string (possibly empty) describing the given system error code.
openvdb::v13_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::v13_0::io::operator<<
std::ostream & operator<<(std::ostream &, const StreamMetadata &)
Write a description of the given metadata to an output stream.
openvdb::v13_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::v13_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::v13_0::io::checkFormatVersion
OPENVDB_API void checkFormatVersion(std::ios_base &)
Throws an IoError if the file format version number is not supported.
openvdb::v13_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::v13_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::v13_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::v13_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::v13_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::v13_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::v13_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::v13_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::v13_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::v13_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::v13_0::SharedPtr
std::shared_ptr< T > SharedPtr
Definition Types.h:95
openvdb
Definition Exceptions.h:13
Types.h
openvdb::v13_0::VersionId
Definition version.h.in:280
openvdb::v13_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:218