OpenVDB  6.1.0
io.h
Go to the documentation of this file.
1 //
3 // Copyright (c) 2012-2018 DreamWorks Animation LLC
4 //
5 // All rights reserved. This software is distributed under the
6 // Mozilla Public License 2.0 ( http://www.mozilla.org/MPL/2.0/ )
7 //
8 // Redistributions of source code must retain the above copyright
9 // and license notice and the following restrictions and disclaimer.
10 //
11 // * Neither the name of DreamWorks Animation nor the names of
12 // its contributors may be used to endorse or promote products derived
13 // from this software without specific prior written permission.
14 //
15 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
16 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
17 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
18 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
19 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY INDIRECT, INCIDENTAL,
20 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
21 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
22 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
23 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
25 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26 // IN NO EVENT SHALL THE COPYRIGHT HOLDERS' AND CONTRIBUTORS' AGGREGATE
27 // LIABILITY FOR ALL CLAIMS REGARDLESS OF THEIR BASIS EXCEED US$250.00.
28 //
30 
31 #ifndef OPENVDB_IO_IO_HAS_BEEN_INCLUDED
32 #define OPENVDB_IO_IO_HAS_BEEN_INCLUDED
33 
34 #include <openvdb/Platform.h>
35 #include <openvdb/Types.h> // for SharedPtr
36 #include <openvdb/version.h>
37 #include <boost/any.hpp>
38 #include <functional>
39 #include <iosfwd> // for std::ios_base
40 #include <map>
41 #include <memory>
42 #include <string>
43 
44 class TestMappedFile;
45 
46 namespace openvdb {
48 namespace OPENVDB_VERSION_NAME {
49 
50 class MetaMap;
51 
52 namespace io {
53 
58 {
59 public:
62 
65  explicit StreamMetadata(std::ios_base&);
66  ~StreamMetadata();
67 
68  StreamMetadata& operator=(const StreamMetadata&);
69 
72  void transferTo(std::ios_base&) const;
73 
74  uint32_t fileVersion() const;
75  void setFileVersion(uint32_t);
76 
77  VersionId libraryVersion() const;
78  void setLibraryVersion(VersionId);
79 
80  uint32_t compression() const;
81  void setCompression(uint32_t);
82 
83  uint32_t gridClass() const;
84  void setGridClass(uint32_t);
85 
86  const void* backgroundPtr() const;
87  void setBackgroundPtr(const void*);
88 
89  bool halfFloat() const;
90  void setHalfFloat(bool);
91 
92  bool writeGridStats() const;
93  void setWriteGridStats(bool);
94 
95  bool seekable() const;
96  void setSeekable(bool);
97 
98  bool countingPasses() const;
99  void setCountingPasses(bool);
100 
101  uint32_t pass() const;
102  void setPass(uint32_t);
103 
105  MetaMap& gridMetadata();
111  const MetaMap& gridMetadata() const;
113 
114  using AuxDataMap = std::map<std::string, boost::any>;
116  AuxDataMap& auxData();
118  const AuxDataMap& auxData() const;
120 
122  std::string str() const;
123 
124 private:
125  struct Impl;
126  std::unique_ptr<Impl> mImpl;
127 }; // class StreamMetadata
128 
129 
131 std::ostream& operator<<(std::ostream&, const StreamMetadata&);
132 
133 std::ostream& operator<<(std::ostream&, const StreamMetadata::AuxDataMap&);
134 
135 
137 
138 
141 struct MultiPass {};
142 
143 
145 
146 
147 class File;
148 
151 {
152 public:
154 
155  ~MappedFile();
156  MappedFile(const MappedFile&) = delete; // not copyable
157  MappedFile& operator=(const MappedFile&) = delete;
158 
160  std::string filename() const;
161 
171  SharedPtr<std::streambuf> createBuffer() const;
172 
173  using Notifier = std::function<void(std::string /*filename*/)>;
176  void setNotifier(const Notifier&);
178  void clearNotifier();
179 
180 private:
181  friend class File;
182  friend class ::TestMappedFile;
183 
184  explicit MappedFile(const std::string& filename, bool autoDelete = false);
185 
186  class Impl;
187  std::unique_ptr<Impl> mImpl;
188 }; // class MappedFile
189 
190 
192 
193 
195 std::string getErrorString(int errorNum);
196 
197 
199 std::string getErrorString();
200 
201 
203 
204 
207 OPENVDB_API uint32_t getFormatVersion(std::ios_base&);
208 
211 OPENVDB_API VersionId getLibraryVersion(std::ios_base&);
212 
215 OPENVDB_API std::string getVersion(std::ios_base&);
216 
218 OPENVDB_API void setCurrentVersion(std::istream&);
219 
223 OPENVDB_API void setVersion(std::ios_base&, const VersionId& libraryVersion, uint32_t fileVersion);
224 
228 OPENVDB_API uint32_t getDataCompression(std::ios_base&);
232 OPENVDB_API void setDataCompression(std::ios_base&, uint32_t compressionFlags);
233 
236 OPENVDB_API uint32_t getGridClass(std::ios_base&);
239 OPENVDB_API void setGridClass(std::ios_base&, uint32_t);
240 
243 OPENVDB_API bool getHalfFloat(std::ios_base&);
246 OPENVDB_API void setHalfFloat(std::ios_base&, bool);
247 
250 OPENVDB_API const void* getGridBackgroundValuePtr(std::ios_base&);
254 OPENVDB_API void setGridBackgroundValuePtr(std::ios_base&, const void* background);
255 
258 OPENVDB_API bool getWriteGridStatsMetadata(std::ios_base&);
261 OPENVDB_API void setWriteGridStatsMetadata(std::ios_base&, bool writeGridStats);
262 
269 OPENVDB_API void setMappedFilePtr(std::ios_base&, SharedPtr<MappedFile>&);
270 
281 OPENVDB_API void setStreamMetadataPtr(std::ios_base&,
282  SharedPtr<StreamMetadata>&, bool transfer = true);
286 
287 } // namespace io
288 } // namespace OPENVDB_VERSION_NAME
289 } // namespace openvdb
290 
291 #endif // OPENVDB_IO_IO_HAS_BEEN_INCLUDED
292 
293 // Copyright (c) 2012-2018 DreamWorks Animation LLC
294 // All rights reserved. This software is distributed under the
295 // Mozilla Public License 2.0 ( http://www.mozilla.org/MPL/2.0/ )
Container for metadata describing how to unserialize grids from and/or serialize grids to a stream (w...
Definition: io.h:57
#define OPENVDB_API
Helper macros for defining library symbol visibility.
Definition: Platform.h:288
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...
std::string getErrorString()
Return a string (possibly empty) describing the most recent system error.
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...
SharedPtr< MappedFile > Ptr
Definition: io.h:153
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.
Definition: version.h:233
OPENVDB_API void setMappedFilePtr(std::ios_base &, SharedPtr< MappedFile > &)
Associate the given stream with (a shared pointer to) a memory-mapped file.
OPENVDB_API VersionId getLibraryVersion(std::ios_base &)
Return the (major, minor) library version number associated with the given input stream.
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_API uint32_t getFormatVersion(std::ios_base &)
Return the file format version number associated with the given input stream.
Grid archive associated with a file on disk.
Definition: File.h:57
OPENVDB_API bool getWriteGridStatsMetadata(std::ios_base &)
Return true if grid statistics (active voxel count and bounding box, etc.) should be computed and sto...
std::shared_ptr< T > SharedPtr
Definition: Types.h:139
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.
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_VERSION_NAME
The version namespace name for this library version.
Definition: version.h:125
std::ostream & operator<<(std::ostream &, const StreamMetadata::AuxDataMap &)
std::map< std::string, boost::any > AuxDataMap
Definition: io.h:114
Definition: Exceptions.h:40
OPENVDB_API void setCurrentVersion(std::istream &)
Associate the current file format and library version numbers with the given input stream...
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::function< void(std::string)> Notifier
Definition: io.h:173
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...
Library and file format version numbers.
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...
SharedPtr< StreamMetadata > Ptr
Definition: io.h:60
OPENVDB_API SharedPtr< StreamMetadata > getStreamMetadataPtr(std::ios_base &)
Return a shared pointer to an object that stores metadata (file format, compression scheme...
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_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 ...
SharedPtr< const StreamMetadata > ConstPtr
Definition: io.h:61
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...
Handle to control the lifetime of a memory-mapped .vdb file.
Definition: io.h:150
#define OPENVDB_USE_VERSION_NAMESPACE
Definition: version.h:177
Container that maps names (strings) to values of arbitrary types.
Definition: MetaMap.h:46
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.
Leaf nodes that require multi-pass I/O must inherit from this struct.
Definition: io.h:141
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...