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