OpenVDB  11.0.0
Archive.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_ARCHIVE_HAS_BEEN_INCLUDED
5 #define OPENVDB_IO_ARCHIVE_HAS_BEEN_INCLUDED
6 
7 #include <openvdb/version.h>
8 #include "Compression.h" // for COMPRESS_ZIP, etc.
9 #include <openvdb/Grid.h>
10 #include <openvdb/MetaMap.h>
11 #include <openvdb/Platform.h>
12 #include <openvdb/version.h> // for VersionId
13 #include <cstdint>
14 #include <iosfwd>
15 #include <map>
16 #include <memory>
17 #include <string>
18 
19 
20 class TestFile;
21 
22 namespace openvdb {
24 namespace OPENVDB_VERSION_NAME {
25 namespace io {
26 
27 class GridDescriptor;
28 
29 
30 /// Grid serializer/unserializer
32 {
33 public:
36 
37  static const uint32_t DEFAULT_COMPRESSION_FLAGS;
38 
39  Archive();
40  Archive(const Archive&) = default;
41  Archive& operator=(const Archive&) = default;
42  virtual ~Archive();
43 
44  /// @brief Return a copy of this archive.
45  virtual Ptr copy() const;
46 
47  /// @brief Return the UUID that was most recently written (or read,
48  /// if no UUID has been written yet).
49  std::string getUniqueTag() const;
50  /// @brief Return @c true if the given UUID matches this archive's UUID.
51  bool isIdentical(const std::string& uuidStr) const;
52 
53  /// @brief Return the file format version number of the input stream.
54  uint32_t fileVersion() const { return mFileVersion; }
55  /// @brief Return the (major, minor) version number of the library that was
56  /// used to write the input stream.
57  VersionId libraryVersion() const { return mLibraryVersion; }
58  /// @brief Return a string of the form "<major>.<minor>/<format>", giving the
59  /// library and file format version numbers associated with the input stream.
60  std::string version() const;
61 
62  /// @brief Return @c true if trees shared by multiple grids are written out
63  /// only once, @c false if they are written out once per grid.
64  bool isInstancingEnabled() const { return mEnableInstancing; }
65  /// @brief Specify whether trees shared by multiple grids should be
66  /// written out only once (@c true) or once per grid (@c false).
67  /// @note Instancing is enabled by default.
68  void setInstancingEnabled(bool b) { mEnableInstancing = b; }
69 
70  /// Return @c true if the OpenVDB library includes support for the Blosc compressor.
71  static bool hasBloscCompression();
72 
73  /// Return @c true if the OpenVDB library includes support for the ZLib compressor.
74  static bool hasZLibCompression();
75 
76  /// Return a bit mask specifying compression options for the data stream.
77  uint32_t compression() const { return mCompression; }
78  /// @brief Specify whether and how the data stream should be compressed.
79  /// @param c bitwise OR (e.g., COMPRESS_ZIP | COMPRESS_ACTIVE_MASK) of
80  /// compression option flags (see Compression.h for the available flags)
81  /// @note Not all combinations of compression options are supported.
82  void setCompression(uint32_t c) { mCompression = c; }
83 
84  /// @brief Return @c true if grid statistics (active voxel count and
85  /// bounding box, etc.) are computed and written as grid metadata.
86  bool isGridStatsMetadataEnabled() const { return mEnableGridStats; }
87  /// @brief Specify whether grid statistics (active voxel count and
88  /// bounding box, etc.) should be computed and written as grid metadata.
89  void setGridStatsMetadataEnabled(bool b) { mEnableGridStats = b; }
90 
91  /// @brief Write the grids in the given container to this archive's output stream.
92  virtual void write(const GridCPtrVec&, const MetaMap& = MetaMap()) const {}
93 
94  /// @brief Return @c true if delayed loading is enabled.
95  /// @details If enabled, delayed loading can be disabled for individual files,
96  /// but not vice-versa.
97  /// @note Define the environment variable @c OPENVDB_DISABLE_DELAYED_LOAD
98  /// to disable delayed loading unconditionally.
99  static bool isDelayedLoadingEnabled();
100 
101 protected:
102  /// @brief Return @c true if the input stream contains grid offsets
103  /// that allow for random access or partial reading.
104  bool inputHasGridOffsets() const { return mInputHasGridOffsets; }
105  void setInputHasGridOffsets(bool b) { mInputHasGridOffsets = b; }
106 
107  /// @brief Tag the given input stream with the input file format version number.
108  ///
109  /// The tag can be retrieved with getFormatVersion().
110  /// @sa getFormatVersion()
111  void setFormatVersion(std::istream&);
112 
113  /// @brief Tag the given input stream with the version number of
114  /// the library with which the input stream was created.
115  ///
116  /// The tag can be retrieved with getLibraryVersion().
117  /// @sa getLibraryVersion()
118  void setLibraryVersion(std::istream&);
119 
120  /// @brief Tag the given input stream with flags indicating whether
121  /// the input stream contains compressed data and how it is compressed.
122  void setDataCompression(std::istream&);
123 
124  /// @brief Tag an output stream with flags specifying only those
125  /// compression options that are applicable to the given grid.
126  void setGridCompression(std::ostream&, const GridBase&) const;
127  /// @brief Read in the compression flags for a grid and
128  /// tag the given input stream with those flags.
129  static void readGridCompression(std::istream&);
130 
131  /// Read in and return the number of grids on the input stream.
132  static int32_t readGridCount(std::istream&);
133 
134  /// Populate the given grid from the input stream.
135  static void readGrid(GridBase::Ptr, const GridDescriptor&, std::istream&);
136  /// @brief Populate the given grid from the input stream, but only where it
137  /// intersects the given world-space bounding box.
138  static void readGrid(GridBase::Ptr, const GridDescriptor&, std::istream&, const BBoxd&);
139  /// @brief Populate the given grid from the input stream, but only where it
140  /// intersects the given index-space bounding box.
141  static void readGrid(GridBase::Ptr, const GridDescriptor&, std::istream&, const CoordBBox&);
142 
143  using NamedGridMap = std::map<Name /*uniqueName*/, GridBase::Ptr>;
144 
145  /// @brief If the grid represented by the given grid descriptor
146  /// is an instance, connect it with its instance parent.
147  void connectInstance(const GridDescriptor&, const NamedGridMap&) const;
148 
149  /// Write the given grid descriptor and grid to an output stream
150  /// and update the GridDescriptor offsets.
151  /// @param seekable if true, the output stream supports seek operations
152  void writeGrid(GridDescriptor&, GridBase::ConstPtr, std::ostream&, bool seekable) const;
153  /// Write the given grid descriptor and grid metadata to an output stream
154  /// and update the GridDescriptor offsets, but don't write the grid's tree,
155  /// since it is shared with another grid.
156  /// @param seekable if true, the output stream supports seek operations
157  void writeGridInstance(GridDescriptor&, GridBase::ConstPtr,
158  std::ostream&, bool seekable) const;
159 
160  /// @brief Read the magic number, version numbers, UUID, etc. from the given input stream.
161  /// @return @c true if the input UUID differs from the previously-read UUID.
162  bool readHeader(std::istream&);
163  /// @brief Write the magic number, version numbers, UUID, etc. to the given output stream.
164  /// @param seekable if true, the output stream supports seek operations
165  /// @todo This method should not be const since it actually redefines the UUID!
166  void writeHeader(std::ostream&, bool seekable) const;
167 
168  //@{
169  /// Write the given grids to an output stream.
170  void write(std::ostream&, const GridPtrVec&, bool seekable, const MetaMap& = MetaMap()) const;
171  void write(std::ostream&, const GridCPtrVec&, bool seekable, const MetaMap& = MetaMap()) const;
172  //@}
173 
174 private:
175  friend class ::TestFile;
176 
177  /// The version of the file that was read
178  uint32_t mFileVersion;
179  /// The version of the library that was used to create the file that was read
180  VersionId mLibraryVersion;
181  /// Unique tag, a random 16-byte (128-bit) value, stored as a string format.
182  mutable std::string mUuid;// needs to be mutable since writeHeader is const!
183  /// Flag indicating whether the input stream contains grid offsets
184  /// and therefore supports partial reading
185  bool mInputHasGridOffsets;
186  /// Flag indicating whether a tree shared by multiple grids should be
187  /// written out only once (true) or once per grid (false)
188  bool mEnableInstancing;
189  /// Flags indicating whether and how the data stream is compressed
190  uint32_t mCompression;
191  /// Flag indicating whether grid statistics metadata should be written
192  bool mEnableGridStats;
193 }; // class Archive
194 
195 } // namespace io
196 } // namespace OPENVDB_VERSION_NAME
197 } // namespace openvdb
198 
199 #endif // OPENVDB_IO_ARCHIVE_HAS_BEEN_INCLUDED
void setGridStatsMetadataEnabled(bool b)
Specify whether grid statistics (active voxel count and bounding box, etc.) should be computed and wr...
Definition: Archive.h:89
void writeGrid(const std::string &fileName, const GridHandle< BufferT > &handle, io::Codec codec=io::Codec::NONE, int verbose=0)
Write a single grid to file (over-writing existing content of the file)
Definition: IO.h:487
virtual void write(const GridCPtrVec &, const MetaMap &=MetaMap()) const
Write the grids in the given container to this archive&#39;s output stream.
Definition: Archive.h:92
#define OPENVDB_API
Definition: Platform.h:274
SharedPtr< const GridBase > ConstPtr
Definition: Grid.h:81
bool inputHasGridOffsets() const
Return true if the input stream contains grid offsets that allow for random access or partial reading...
Definition: Archive.h:104
static fileSize_t write(std::ostream &os, const GridHandle< BufferT > &handle, Codec codec, uint32_t n)
std::shared_ptr< T > SharedPtr
Definition: Types.h:114
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:64
std::vector< GridBase::ConstPtr > GridCPtrVec
Definition: Grid.h:513
BBox< Coord > CoordBBox
Definition: NanoVDB.h:2535
Grid serializer/unserializer.
Definition: Archive.h:31
Container that maps names (strings) to values of arbitrary types.
Definition: MetaMap.h:19
SharedPtr< Archive > Ptr
Definition: Archive.h:34
Definition: Exceptions.h:13
uint32_t compression() const
Return a bit mask specifying compression options for the data stream.
Definition: Archive.h:77
std::string Name
Definition: Name.h:19
std::map< Name, GridBase::Ptr > NamedGridMap
Definition: Archive.h:143
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:68
void setCompression(uint32_t c)
Specify whether and how the data stream should be compressed.
Definition: Archive.h:82
GridHandle< BufferT > readGrid(const std::string &fileName, int n=0, int verbose=0, const BufferT &buffer=BufferT())
Read and return one or all grids from a file into a single GridHandle.
Definition: IO.h:580
std::vector< GridBase::Ptr > GridPtrVec
Definition: Grid.h:508
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.
void setInputHasGridOffsets(bool b)
Definition: Archive.h:105
VersionId libraryVersion() const
Return the (major, minor) version number of the library that was used to write the input stream...
Definition: Archive.h:57
static const uint32_t DEFAULT_COMPRESSION_FLAGS
Definition: Archive.h:37
SharedPtr< GridBase > Ptr
Definition: Grid.h:80
Definition: version.h.in:273
SharedPtr< const Archive > ConstPtr
Definition: Archive.h:35
Definition: GridDescriptor.h:19
bool isGridStatsMetadataEnabled() const
Return true if grid statistics (active voxel count and bounding box, etc.) are computed and written a...
Definition: Archive.h:86
#define OPENVDB_VERSION_NAME
The version namespace name for this library version.
Definition: version.h.in:121
uint32_t fileVersion() const
Return the file format version number of the input stream.
Definition: Archive.h:54
Abstract base class for typed grids.
Definition: Grid.h:77
#define OPENVDB_USE_VERSION_NAMESPACE
Definition: version.h.in:212