HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
io.h
Go to the documentation of this file.
1 // Copyright Contributors to the OpenVDB Project
2 // SPDX-License-Identifier: MPL-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 <hboost/any.hpp>
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 {
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.
31 {
32 public:
35 
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, hboost::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.
114 std::ostream& operator<<(std::ostream&, const StreamMetadata&);
115 
116 std::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 /// @brief Handle to control the lifetime of a memory-mapped .vdb file
134 {
135 public:
137 
138  ~MappedFile();
139  MappedFile(const MappedFile&) = delete; // not copyable
140  MappedFile& operator=(const MappedFile&) = delete;
141 
142  /// Return the filename of the mapped file.
143  std::string filename() const;
144 
145  /// @brief Return a new stream buffer for the mapped file.
146  /// @details Typical usage is
147  /// @code
148  /// openvdb::io::MappedFile::Ptr mappedFile = ...;
149  /// auto buf = mappedFile->createBuffer();
150  /// std::istream istrm{buf.get()};
151  /// // Read from istrm...
152  /// @endcode
153  /// The buffer must persist as long as the stream is open.
154  SharedPtr<std::streambuf> createBuffer() const;
155 
156  using Notifier = std::function<void(std::string /*filename*/)>;
157  /// @brief Register a function that will be called with this file's name
158  /// when the file is unmapped.
159  void setNotifier(const Notifier&);
160  /// Deregister the notifier.
161  void clearNotifier();
162 
163 private:
164  friend class File;
165  friend class ::TestMappedFile;
166 
167  explicit MappedFile(const std::string& filename, bool autoDelete = false);
168 
169  class Impl;
170  std::unique_ptr<Impl> mImpl;
171 }; // class MappedFile
172 
173 
174 ////////////////////////////////////////
175 
176 
177 /// Return a string (possibly empty) describing the given system error code.
178 std::string getErrorString(int errorNum);
179 
180 
181 /// Return a string (possibly empty) describing the most recent system error.
183 
184 
185 ////////////////////////////////////////
186 
187 
188 /// @brief Return the file format version number associated with the given input stream.
189 /// @sa File::setFormatVersion()
190 OPENVDB_API uint32_t getFormatVersion(std::ios_base&);
191 
192 /// @brief Return the (major, minor) library version number associated with the given input stream.
193 /// @sa File::setLibraryVersion()
194 OPENVDB_API VersionId getLibraryVersion(std::ios_base&);
195 
196 /// @brief Return a string of the form "<major>.<minor>/<format>", giving the library
197 /// and file format version numbers associated with the given input stream.
198 OPENVDB_API std::string getVersion(std::ios_base&);
199 
200 /// Associate the current file format and library version numbers with the given input stream.
201 OPENVDB_API void setCurrentVersion(std::istream&);
202 
203 /// @brief Associate specific file format and library version numbers with the given stream.
204 /// @details This is typically called immediately after reading a header that contains
205 /// the version numbers. Data read subsequently can then be interpreted appropriately.
206 OPENVDB_API void setVersion(std::ios_base&, const VersionId& libraryVersion, uint32_t fileVersion);
207 
208 /// @brief Return a bitwise OR of compression option flags (COMPRESS_ZIP,
209 /// COMPRESS_ACTIVE_MASK, etc.) specifying whether and how input data is compressed
210 /// or output data should be compressed.
211 OPENVDB_API uint32_t getDataCompression(std::ios_base&);
212 /// @brief Associate with the given stream a bitwise OR of compression option flags
213 /// (COMPRESS_ZIP, COMPRESS_ACTIVE_MASK, etc.) specifying whether and how input data
214 /// is compressed or output data should be compressed.
215 OPENVDB_API void setDataCompression(std::ios_base&, uint32_t compressionFlags);
216 
217 /// @brief Return the class (GRID_LEVEL_SET, GRID_UNKNOWN, etc.) of the grid
218 /// currently being read from or written to the given stream.
219 OPENVDB_API uint32_t getGridClass(std::ios_base&);
220 /// @brief Associate with the given stream the class (GRID_LEVEL_SET, GRID_UNKNOWN, etc.)
221 /// of the grid currently being read or written.
222 OPENVDB_API void setGridClass(std::ios_base&, uint32_t);
223 
224 /// @brief Return true if floating-point values should be quantized to 16 bits when writing
225 /// to the given stream or promoted back from 16-bit to full precision when reading from it.
226 OPENVDB_API bool getHalfFloat(std::ios_base&);
227 /// @brief Specify whether floating-point values should be quantized to 16 bits when writing
228 /// to the given stream or promoted back from 16-bit to full precision when reading from it.
229 OPENVDB_API void setHalfFloat(std::ios_base&, bool);
230 
231 /// @brief Return a pointer to the background value of the grid
232 /// currently being read from or written to the given stream.
233 OPENVDB_API const void* getGridBackgroundValuePtr(std::ios_base&);
234 /// @brief Specify (a pointer to) the background value of the grid
235 /// currently being read from or written to the given stream.
236 /// @note The pointer must remain valid until the entire grid has been read or written.
237 OPENVDB_API void setGridBackgroundValuePtr(std::ios_base&, const void* background);
238 
239 /// @brief Return @c true if grid statistics (active voxel count and bounding box, etc.)
240 /// should be computed and stored as grid metadata when writing to the given stream.
241 OPENVDB_API bool getWriteGridStatsMetadata(std::ios_base&);
242 /// @brief Specify whether to compute grid statistics (active voxel count and bounding box, etc.)
243 /// and store them as grid metadata when writing to the given stream.
244 OPENVDB_API void setWriteGridStatsMetadata(std::ios_base&, bool writeGridStats);
245 
246 /// @brief Return a shared pointer to the memory-mapped file with which the given stream
247 /// is associated, or a null pointer if the stream is not associated with a memory-mapped file.
249 /// @brief Associate the given stream with (a shared pointer to) a memory-mapped file.
250 /// @note The shared pointer object (not just the io::MappedFile object to which it points)
251 /// must remain valid until the file is closed.
252 OPENVDB_API void setMappedFilePtr(std::ios_base&, SharedPtr<MappedFile>&);
253 
254 /// @brief Return a shared pointer to an object that stores metadata (file format,
255 /// compression scheme, etc.) for use when reading from or writing to the given stream.
257 /// @brief Associate the given stream with (a shared pointer to) an object that stores
258 /// metadata (file format, compression scheme, etc.) for use when reading from
259 /// or writing to the stream.
260 /// @details If @a transfer is true, copy metadata from the object directly to the stream
261 /// (for backward compatibility with older versions of the library).
262 /// @note The shared pointer object (not just the io::StreamMetadata object to which it points)
263 /// must remain valid until the file is closed.
264 OPENVDB_API void setStreamMetadataPtr(std::ios_base&,
265  SharedPtr<StreamMetadata>&, bool transfer = true);
266 /// @brief Dissociate the given stream from its metadata object (if it has one)
267 /// and return a shared pointer to the object.
269 
270 } // namespace io
271 } // namespace OPENVDB_VERSION_NAME
272 } // namespace openvdb
273 
274 #endif // OPENVDB_IO_IO_HAS_BEEN_INCLUDED
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.
std::ostream & operator<<(std::ostream &, const StreamMetadata &)
Write a description of the given metadata to an output stream.
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.
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 ...
GT_API const UT_StringHolder filename
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_API void setHalfFloat(std::ios_base &, bool)
Specify whether floating-point values should be quantized to 16 bits when writing to the given stream...
std::string getErrorString(int errorNum)
Return a string (possibly empty) describing the given system error code.
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...
SharedPtr< StreamMetadata > Ptr
Definition: io.h:33
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.
Leaf nodes that require multi-pass I/O must inherit from this struct.
Definition: io.h:124
Grid archive associated with a file on disk.
Definition: File.h:30
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 ...
#define OPENVDB_USE_VERSION_NAMESPACE
Definition: version.h:166
SharedPtr< MappedFile > Ptr
Definition: io.h:136
OPENVDB_API VersionId getLibraryVersion(std::ios_base &)
Return the (major, minor) library version number associated with the given input stream.
Container that maps names (strings) to values of arbitrary types.
Definition: MetaMap.h:19
std::function< void(std::string)> Notifier
Definition: io.h:156
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...
std::shared_ptr< T > SharedPtr
Definition: Types.h:91
OPENVDB_API void setMappedFilePtr(std::ios_base &, SharedPtr< MappedFile > &)
Associate the given stream with (a shared pointer to) a memory-mapped file.
#define OPENVDB_API
Helper macros for defining library symbol visibility.
Definition: Platform.h:230
Handle to control the lifetime of a memory-mapped .vdb file.
Definition: io.h:133
void
Definition: png.h:1083
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. ...
SharedPtr< const StreamMetadata > ConstPtr
Definition: io.h:34
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_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...
GLsizei const GLchar *const * string
Definition: glew.h:1844
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_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...
std::map< std::string, hboost::any > AuxDataMap
Definition: io.h:92
OPENVDB_API SharedPtr< StreamMetadata > getStreamMetadataPtr(std::ios_base &)
Return a shared pointer to an object that stores metadata (file format, compression scheme...
Container for metadata describing how to unserialize grids from and/or serialize grids to a stream (w...
Definition: io.h:30
#define OPENVDB_VERSION_NAME
The version namespace name for this library version.
Definition: version.h:112
OPENVDB_API uint32_t getFormatVersion(std::ios_base &)
Return the file format version number associated with the given input stream.
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.
OPENVDB_API void setCurrentVersion(std::istream &)
Associate the current file format and library version numbers with the given input stream...