HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Archive.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_ARCHIVE_HAS_BEEN_INCLUDED
32 #define OPENVDB_IO_ARCHIVE_HAS_BEEN_INCLUDED
33 
34 #include "Compression.h" // for COMPRESS_ZIP, etc.
35 #include <openvdb/Grid.h>
36 #include <openvdb/MetaMap.h>
37 #include <openvdb/Platform.h>
38 #include <openvdb/version.h> // for VersionId
39 #include <hboost/uuid/uuid.hpp>
40 #include <cstdint>
41 #include <iosfwd>
42 #include <map>
43 #include <memory>
44 #include <string>
45 
46 
47 class TestFile;
48 
49 namespace openvdb {
51 namespace OPENVDB_VERSION_NAME {
52 namespace io {
53 
54 class GridDescriptor;
55 
56 
57 /// Grid serializer/unserializer
59 {
60 public:
63 
64  static const uint32_t DEFAULT_COMPRESSION_FLAGS;
65 
66  Archive();
67  Archive(const Archive&) = default;
68  Archive& operator=(const Archive&) = default;
69  virtual ~Archive();
70 
71  /// @brief Return a copy of this archive.
72  virtual Ptr copy() const;
73 
74  /// @brief Return the UUID that was most recently written (or read,
75  /// if no UUID has been written yet).
76  std::string getUniqueTag() const;
77  /// @brief Return @c true if the given UUID matches this archive's UUID.
78  bool isIdentical(const std::string& uuidStr) const;
79 
80  /// @brief Return the file format version number of the input stream.
81  uint32_t fileVersion() const { return mFileVersion; }
82  /// @brief Return the (major, minor) version number of the library that was
83  /// used to write the input stream.
84  VersionId libraryVersion() const { return mLibraryVersion; }
85  /// @brief Return a string of the form "<major>.<minor>/<format>", giving the
86  /// library and file format version numbers associated with the input stream.
87  std::string version() const;
88 
89  /// @brief Return @c true if trees shared by multiple grids are written out
90  /// only once, @c false if they are written out once per grid.
91  bool isInstancingEnabled() const { return mEnableInstancing; }
92  /// @brief Specify whether trees shared by multiple grids should be
93  /// written out only once (@c true) or once per grid (@c false).
94  /// @note Instancing is enabled by default.
95  void setInstancingEnabled(bool b) { mEnableInstancing = b; }
96 
97  /// Return @c true if the OpenVDB library includes support for the Blosc compressor.
98  static bool hasBloscCompression();
99 
100  /// Return a bit mask specifying compression options for the data stream.
101  uint32_t compression() const { return mCompression; }
102  /// @brief Specify whether and how the data stream should be compressed.
103  /// @param c bitwise OR (e.g., COMPRESS_ZIP | COMPRESS_ACTIVE_MASK) of
104  /// compression option flags (see Compression.h for the available flags)
105  /// @note Not all combinations of compression options are supported.
106  void setCompression(uint32_t c) { mCompression = c; }
107 
108  /// @brief Return @c true if grid statistics (active voxel count and
109  /// bounding box, etc.) are computed and written as grid metadata.
110  bool isGridStatsMetadataEnabled() const { return mEnableGridStats; }
111  /// @brief Specify whether grid statistics (active voxel count and
112  /// bounding box, etc.) should be computed and written as grid metadata.
113  void setGridStatsMetadataEnabled(bool b) { mEnableGridStats = b; }
114 
115  /// @brief Write the grids in the given container to this archive's output stream.
116  virtual void write(const GridCPtrVec&, const MetaMap& = MetaMap()) const {}
117 
118  /// @brief Return @c true if delayed loading is enabled.
119  /// @details If enabled, delayed loading can be disabled for individual files,
120  /// but not vice-versa.
121  /// @note Define the environment variable @c OPENVDB_DISABLE_DELAYED_LOAD
122  /// to disable delayed loading unconditionally.
123  static bool isDelayedLoadingEnabled();
124 
125 protected:
126  /// @brief Return @c true if the input stream contains grid offsets
127  /// that allow for random access or partial reading.
128  bool inputHasGridOffsets() const { return mInputHasGridOffsets; }
129  void setInputHasGridOffsets(bool b) { mInputHasGridOffsets = b; }
130 
131  /// @brief Tag the given input stream with the input file format version number.
132  ///
133  /// The tag can be retrieved with getFormatVersion().
134  /// @sa getFormatVersion()
135  void setFormatVersion(std::istream&);
136 
137  /// @brief Tag the given input stream with the version number of
138  /// the library with which the input stream was created.
139  ///
140  /// The tag can be retrieved with getLibraryVersion().
141  /// @sa getLibraryVersion()
142  void setLibraryVersion(std::istream&);
143 
144  /// @brief Tag the given input stream with flags indicating whether
145  /// the input stream contains compressed data and how it is compressed.
146  void setDataCompression(std::istream&);
147 
148  /// @brief Tag an output stream with flags specifying only those
149  /// compression options that are applicable to the given grid.
150  void setGridCompression(std::ostream&, const GridBase&) const;
151  /// @brief Read in the compression flags for a grid and
152  /// tag the given input stream with those flags.
153  static void readGridCompression(std::istream&);
154 
155  /// Read in and return the number of grids on the input stream.
156  static int32_t readGridCount(std::istream&);
157 
158  /// Populate the given grid from the input stream.
159  static void readGrid(GridBase::Ptr, const GridDescriptor&, std::istream&);
160 #ifndef OPENVDB_2_ABI_COMPATIBLE
161  /// @brief Populate the given grid from the input stream, but only where it
162  /// intersects the given world-space bounding box.
163  static void readGrid(GridBase::Ptr, const GridDescriptor&, std::istream&, const BBoxd&);
164  /// @brief Populate the given grid from the input stream, but only where it
165  /// intersects the given index-space bounding box.
166  static void readGrid(GridBase::Ptr, const GridDescriptor&, std::istream&, const CoordBBox&);
167 #endif
168 
169  typedef std::map<Name /*uniqueName*/, GridBase::Ptr> NamedGridMap;
170 
171  /// @brief If the grid represented by the given grid descriptor
172  /// is an instance, connect it with its instance parent.
173  void connectInstance(const GridDescriptor&, const NamedGridMap&) const;
174 
175  /// Write the given grid descriptor and grid to an output stream
176  /// and update the GridDescriptor offsets.
177  /// @param seekable if true, the output stream supports seek operations
178  void writeGrid(GridDescriptor&, GridBase::ConstPtr, std::ostream&, bool seekable) const;
179  /// Write the given grid descriptor and grid metadata to an output stream
180  /// and update the GridDescriptor offsets, but don't write the grid's tree,
181  /// since it is shared with another grid.
182  /// @param seekable if true, the output stream supports seek operations
183  void writeGridInstance(GridDescriptor&, GridBase::ConstPtr,
184  std::ostream&, bool seekable) const;
185 
186  /// @brief Read the magic number, version numbers, UUID, etc. from the given input stream.
187  /// @return @c true if the input UUID differs from the previously-read UUID.
188  bool readHeader(std::istream&);
189  /// @brief Write the magic number, version numbers, UUID, etc. to the given output stream.
190  /// @param seekable if true, the output stream supports seek operations
191  /// @todo This method should not be const since it actually redefines the UUID!
192  void writeHeader(std::ostream&, bool seekable) const;
193 
194  //@{
195  /// Write the given grids to an output stream.
196  void write(std::ostream&, const GridPtrVec&, bool seekable, const MetaMap& = MetaMap()) const;
197  void write(std::ostream&, const GridCPtrVec&, bool seekable, const MetaMap& = MetaMap()) const;
198  //@}
199 
200 private:
201  friend class ::TestFile;
202 
203  /// The version of the file that was read
204  uint32_t mFileVersion;
205  /// The version of the library that was used to create the file that was read
206  VersionId mLibraryVersion;
207  /// 16-byte (128-bit) UUID
208  mutable hboost::uuids::uuid mUuid;// needs to be mutable since writeHeader is const!
209  /// Flag indicating whether the input stream contains grid offsets
210  /// and therefore supports partial reading
211  bool mInputHasGridOffsets;
212  /// Flag indicating whether a tree shared by multiple grids should be
213  /// written out only once (true) or once per grid (false)
214  bool mEnableInstancing;
215  /// Flags indicating whether and how the data stream is compressed
216  uint32_t mCompression;
217  /// Flag indicating whether grid statistics metadata should be written
218  bool mEnableGridStats;
219 }; // class Archive
220 
221 } // namespace io
222 } // namespace OPENVDB_VERSION_NAME
223 } // namespace openvdb
224 
225 #endif // OPENVDB_IO_ARCHIVE_HAS_BEEN_INCLUDED
226 
227 // Copyright (c) 2012-2017 DreamWorks Animation LLC
228 // All rights reserved. This software is distributed under the
229 // Mozilla Public License 2.0 ( http://www.mozilla.org/MPL/2.0/ )
Grid serializer/unserializer.
Definition: Archive.h:58
uint32_t fileVersion() const
Return the file format version number of the input stream.
Definition: Archive.h:81
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: ImfName.h:53
SharedPtr< GridBase > Ptr
Definition: Grid.h:106
GLsizei const GLchar *const * string
Definition: glcorearb.h:813
bool inputHasGridOffsets() const
Return true if the input stream contains grid offsets that allow for random access or partial reading...
Definition: Archive.h:128
uint32_t compression() const
Return a bit mask specifying compression options for the data stream.
Definition: Archive.h:101
Container that maps names (strings) to values of arbitrary types.
Definition: MetaMap.h:46
std::vector< GridBase::Ptr > GridPtrVec
Definition: Grid.h:436
void setGridStatsMetadataEnabled(bool b)
Specify whether grid statistics (active voxel count and bounding box, etc.) should be computed and wr...
Definition: Archive.h:113
std::shared_ptr< T > SharedPtr
Definition: Types.h:130
Abstract base class for typed grids.
Definition: Grid.h:103
void setCompression(uint32_t c)
Specify whether and how the data stream should be compressed.
Definition: Archive.h:106
#define OPENVDB_API
Helper macros for defining library symbol visibility.
Definition: Platform.h:194
void setInstancingEnabled(bool b)
Specify whether trees shared by multiple grids should be written out only once (true) or once per gri...
Definition: Archive.h:95
#define OPENVDB_VERSION_NAME
Definition: version.h:43
bool isGridStatsMetadataEnabled() const
Return true if grid statistics (active voxel count and bounding box, etc.) are computed and written a...
Definition: Archive.h:110
static const uint32_t DEFAULT_COMPRESSION_FLAGS
Definition: Archive.h:64
GLboolean GLboolean GLboolean b
Definition: glcorearb.h:1221
SharedPtr< const Archive > ConstPtr
Definition: Archive.h:62
virtual void write(const GridCPtrVec &, const MetaMap &=MetaMap()) const
Write the grids in the given container to this archive's output stream.
Definition: Archive.h:116
SharedPtr< const GridBase > ConstPtr
Definition: Grid.h:107
bool isInstancingEnabled() const
Return true if trees shared by multiple grids are written out only once, false if they are written ou...
Definition: Archive.h:91
std::map< Name, GridBase::Ptr > NamedGridMap
Definition: Archive.h:169
VersionId libraryVersion() const
Return the (major, minor) version number of the library that was used to write the input stream...
Definition: Archive.h:84
#define OPENVDB_USE_VERSION_NAMESPACE
Definition: version.h:71
void write(T &out, bool v)
Definition: ImfXdr.h:332
std::vector< GridBase::ConstPtr > GridCPtrVec
Definition: Grid.h:441