OpenVDB: openvdb/io/Archive.h Source File

OpenVDB 13.0.0

Loading...
Searching...
No Matches
Archive.h
Go to the documentation of this file.
1// Copyright Contributors to the OpenVDB Project
2// SPDX-License-Identifier: Apache-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
20class TestFile;
21
22namespace openvdb {
23 OPENVDB_USE_VERSION_NAMESPACE
24namespace OPENVDB_VERSION_NAME {
25namespace io {
26
27class GridDescriptor;
28
29
30/// Grid serializer/unserializer
31 class OPENVDB_API Archive
32{
33public:
34 using Ptr = SharedPtr<Archive>;
35 using ConstPtr = SharedPtr<const Archive>;
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
101protected:
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
174private:
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
Compression.h
Grid.h
MetaMap.h
Platform.h
OPENVDB_API
#define OPENVDB_API
Definition Platform.h:291
openvdb::v13_0::GridBase
Abstract base class for typed grids.
Definition Grid.h:78
openvdb::v13_0::GridBase::ConstPtr
SharedPtr< const GridBase > ConstPtr
Definition Grid.h:81
openvdb::v13_0::GridBase::Ptr
SharedPtr< GridBase > Ptr
Definition Grid.h:80
openvdb::v13_0::MetaMap
Container that maps names (strings) to values of arbitrary types.
Definition MetaMap.h:20
openvdb::v13_0::io::Archive::connectInstance
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...
openvdb::v13_0::io::Archive::setFormatVersion
void setFormatVersion(std::istream &)
Tag the given input stream with the input file format version number.
openvdb::v13_0::io::Archive::isGridStatsMetadataEnabled
bool isGridStatsMetadataEnabled() const
Return true if grid statistics (active voxel count and bounding box, etc.) are computed and written a...
Definition Archive.h:86
openvdb::v13_0::io::Archive::setLibraryVersion
void setLibraryVersion(std::istream &)
Tag the given input stream with the version number of the library with which the input stream was cre...
openvdb::v13_0::io::Archive::operator=
Archive & operator=(const Archive &)=default
openvdb::v13_0::io::Archive::readGrid
static void readGrid(GridBase::Ptr, const GridDescriptor &, std::istream &)
Populate the given grid from the input stream.
openvdb::v13_0::io::Archive::inputHasGridOffsets
bool inputHasGridOffsets() const
Return true if the input stream contains grid offsets that allow for random access or partial reading...
Definition Archive.h:104
openvdb::v13_0::io::Archive::hasBloscCompression
static bool hasBloscCompression()
Return true if the OpenVDB library includes support for the Blosc compressor.
openvdb::v13_0::io::Archive::DEFAULT_COMPRESSION_FLAGS
static const uint32_t DEFAULT_COMPRESSION_FLAGS
Definition Archive.h:37
openvdb::v13_0::io::Archive::setDataCompression
void setDataCompression(std::istream &)
Tag the given input stream with flags indicating whether the input stream contains compressed data an...
openvdb::v13_0::io::Archive::fileVersion
uint32_t fileVersion() const
Return the file format version number of the input stream.
Definition Archive.h:54
openvdb::v13_0::io::Archive::write
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:92
openvdb::v13_0::io::Archive::readGrid
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...
openvdb::v13_0::io::Archive::getUniqueTag
std::string getUniqueTag() const
Return the UUID that was most recently written (or read, if no UUID has been written yet).
openvdb::v13_0::io::Archive::isDelayedLoadingEnabled
static bool isDelayedLoadingEnabled()
Return true if delayed loading is enabled.
openvdb::v13_0::io::Archive::setGridCompression
void setGridCompression(std::ostream &, const GridBase &) const
Tag an output stream with flags specifying only those compression options that are applicable to the ...
openvdb::v13_0::io::Archive::writeHeader
void writeHeader(std::ostream &, bool seekable) const
Write the magic number, version numbers, UUID, etc. to the given output stream.
openvdb::v13_0::io::Archive::readGridCount
static int32_t readGridCount(std::istream &)
Read in and return the number of grids on the input stream.
openvdb::v13_0::io::Archive::write
void write(std::ostream &, const GridCPtrVec &, bool seekable, const MetaMap &=MetaMap()) const
openvdb::v13_0::io::Archive::ConstPtr
SharedPtr< const Archive > ConstPtr
Definition Archive.h:35
openvdb::v13_0::io::Archive::isInstancingEnabled
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
openvdb::v13_0::io::Archive::readGrid
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...
openvdb::v13_0::io::Archive::setInstancingEnabled
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
openvdb::v13_0::io::Archive::readGridCompression
static void readGridCompression(std::istream &)
Read in the compression flags for a grid and tag the given input stream with those flags.
openvdb::v13_0::io::Archive::copy
virtual Ptr copy() const
Return a copy of this archive.
openvdb::v13_0::io::Archive::hasZLibCompression
static bool hasZLibCompression()
Return true if the OpenVDB library includes support for the ZLib compressor.
openvdb::v13_0::io::Archive::setCompression
void setCompression(uint32_t c)
Specify whether and how the data stream should be compressed.
Definition Archive.h:82
openvdb::v13_0::io::Archive::Archive
Archive()
openvdb::v13_0::io::Archive::compression
uint32_t compression() const
Return a bit mask specifying compression options for the data stream.
Definition Archive.h:77
openvdb::v13_0::io::Archive::NamedGridMap
std::map< Name, GridBase::Ptr > NamedGridMap
Definition Archive.h:143
openvdb::v13_0::io::Archive::isIdentical
bool isIdentical(const std::string &uuidStr) const
Return true if the given UUID matches this archive's UUID.
openvdb::v13_0::io::Archive::writeGridInstance
void writeGridInstance(GridDescriptor &, GridBase::ConstPtr, std::ostream &, bool seekable) const
openvdb::v13_0::io::Archive::writeGrid
void writeGrid(GridDescriptor &, GridBase::ConstPtr, std::ostream &, bool seekable) const
openvdb::v13_0::io::Archive::readHeader
bool readHeader(std::istream &)
Read the magic number, version numbers, UUID, etc. from the given input stream.
openvdb::v13_0::io::Archive::Ptr
SharedPtr< Archive > Ptr
Definition Archive.h:34
openvdb::v13_0::io::Archive::Archive
Archive(const Archive &)=default
openvdb::v13_0::io::Archive::setGridStatsMetadataEnabled
void setGridStatsMetadataEnabled(bool b)
Specify whether grid statistics (active voxel count and bounding box, etc.) should be computed and wr...
Definition Archive.h:89
openvdb::v13_0::io::Archive::libraryVersion
VersionId libraryVersion() const
Return the (major, minor) version number of the library that was used to write the input stream.
Definition Archive.h:57
openvdb::v13_0::io::Archive::write
void write(std::ostream &, const GridPtrVec &, bool seekable, const MetaMap &=MetaMap()) const
Write the given grids to an output stream.
openvdb::v13_0::io::Archive::~Archive
virtual ~Archive()
openvdb::v13_0::io::Archive::version
std::string version() const
Return a string of the form "<major>.<minor>/<format>", giving the library and file format version nu...
openvdb::v13_0::io::Archive::setInputHasGridOffsets
void setInputHasGridOffsets(bool b)
Definition Archive.h:105
openvdb::v13_0::io::GridDescriptor
Definition GridDescriptor.h:20
openvdb::v13_0::math::CoordBBox
Axis-aligned bounding box of signed integer coordinates.
Definition Coord.h:252
openvdb::v13_0::Name
std::string Name
Definition Name.h:19
openvdb::v13_0::GridPtrVec
std::vector< GridBase::Ptr > GridPtrVec
Definition Grid.h:508
openvdb::v13_0::BBoxd
math::BBox< Vec3d > BBoxd
Definition Types.h:65
openvdb::v13_0::SharedPtr
std::shared_ptr< T > SharedPtr
Definition Types.h:95
openvdb::v13_0::GridCPtrVec
std::vector< GridBase::ConstPtr > GridCPtrVec
Definition Grid.h:513
openvdb
Definition Exceptions.h:13
openvdb::v13_0::VersionId
Definition version.h.in:280
OPENVDB_VERSION_NAME
#define OPENVDB_VERSION_NAME
The version namespace name for this library version.
Definition version.h.in:121
OPENVDB_USE_VERSION_NAMESPACE
#define OPENVDB_USE_VERSION_NAMESPACE
Definition version.h.in:218