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