OpenVDB 11.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: 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
20class TestFile;
21
22namespace openvdb {
24namespace OPENVDB_VERSION_NAME {
25namespace io {
26
27class GridDescriptor;
28
29
30/// Grid serializer/unserializer
32{
33public:
36
37 static const uint32_t DEFAULT_COMPRESSION_FLAGS;
38
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.
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
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
#define OPENVDB_API
Definition Platform.h:274
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:32
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:86
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:104
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:37
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:54
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
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:35
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
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:68
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:82
uint32_t compression() const
Return a bit mask specifying compression options for the data stream.
Definition Archive.h:77
std::map< Name, GridBase::Ptr > NamedGridMap
Definition Archive.h:143
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:34
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:89
VersionId libraryVersion() const
Return the (major, minor) version number of the library that was used to write the input stream.
Definition Archive.h:57
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:105
Definition GridDescriptor.h:20
Axis-aligned bounding box of signed integer coordinates.
Definition Coord.h:251
std::string Name
Definition Name.h:19
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