HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
File.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 /// @file File.h
32 
33 #ifndef OPENVDB_IO_FILE_HAS_BEEN_INCLUDED
34 #define OPENVDB_IO_FILE_HAS_BEEN_INCLUDED
35 
36 #include "io.h" // for MappedFile::Notifier
37 #include "Archive.h"
38 #include "GridDescriptor.h"
39 #include <iosfwd>
40 #include <map>
41 #include <memory>
42 #include <string>
43 
44 
45 class TestFile;
46 class TestStream;
47 
48 namespace openvdb {
50 namespace OPENVDB_VERSION_NAME {
51 namespace io {
52 
53 /// Grid archive associated with a file on disk
54 class OPENVDB_API File: public Archive
55 {
56 public:
57  using NameMap = std::multimap<Name, GridDescriptor>;
58  using NameMapCIter = NameMap::const_iterator;
59 
60  explicit File(const std::string& filename);
61  ~File() override;
62 
63  /// @brief Copy constructor
64  /// @details The copy will be closed and will not reference the same
65  /// file descriptor as the original.
66  File(const File& other);
67  /// @brief Assignment
68  /// @details After assignment, this File will be closed and will not
69  /// reference the same file descriptor as the source File.
70  File& operator=(const File& other);
71 
72  /// @brief Return a copy of this archive.
73  /// @details The copy will be closed and will not reference the same
74  /// file descriptor as the original.
75  SharedPtr<Archive> copy() const override;
76 
77  /// @brief Return the name of the file with which this archive is associated.
78  /// @details The file does not necessarily exist on disk yet.
79  const std::string& filename() const;
80 
81  /// @brief Open the file, read the file header and the file-level metadata,
82  /// and populate the grid descriptors, but do not load any grids into memory.
83  /// @details If @a delayLoad is true, map the file into memory and enable delayed loading
84  /// of grids, and if a notifier is provided, call it when the file gets unmapped.
85  /// @note Define the environment variable @c OPENVDB_DISABLE_DELAYED_LOAD to disable
86  /// delayed loading unconditionally.
87  /// @throw IoError if the file is not a valid VDB file.
88  /// @return @c true if the file's UUID has changed since it was last read.
89  /// @see setCopyMaxBytes
90  bool open(bool delayLoad = true, const MappedFile::Notifier& = MappedFile::Notifier());
91 
92  /// Return @c true if the file has been opened for reading.
93  bool isOpen() const;
94 
95  /// Close the file once we are done reading from it.
96  void close();
97 
98  /// @brief Return this file's current size on disk in bytes.
99  /// @throw IoError if the file size cannot be determined.
100  Index64 getSize() const;
101 
102  /// @brief Return the size in bytes above which this file will not be
103  /// automatically copied during delayed loading.
104  Index64 copyMaxBytes() const;
105  /// @brief If this file is opened with delayed loading enabled, make a private copy
106  /// of the file if its size in bytes is less than the specified value.
107  /// @details Making a private copy ensures that the file can't change on disk
108  /// before it has been fully read.
109  /// @warning If the file is larger than this size, it is the user's responsibility
110  /// to ensure that it does not change on disk before it has been fully read.
111  /// Undefined behavior and/or a crash might result otherwise.
112  /// @note Copying is enabled by default, but it can be disabled for individual files
113  /// by setting the maximum size to zero bytes. A default size limit can be specified
114  /// by setting the environment variable @c OPENVDB_DELAYED_LOAD_COPY_MAX_BYTES
115  /// to the desired number of bytes.
116  void setCopyMaxBytes(Index64 bytes);
117 
118  /// Return @c true if a grid of the given name exists in this file.
119  bool hasGrid(const Name&) const;
120 
121  /// Return (in a newly created MetaMap) the file-level metadata.
122  MetaMap::Ptr getMetadata() const;
123 
124  /// Read the entire contents of the file and return a list of grid pointers.
125  GridPtrVecPtr getGrids() const;
126 
127  /// @brief Read just the grid metadata and transforms from the file and return a list
128  /// of pointers to grids that are empty except for their metadata and transforms.
129  /// @throw IoError if this file is not open for reading.
130  GridPtrVecPtr readAllGridMetadata();
131 
132  /// @brief Read a grid's metadata and transform only.
133  /// @return A pointer to a grid that is empty except for its metadata and transform.
134  /// @throw IoError if this file is not open for reading.
135  /// @throw KeyError if no grid with the given name exists in this file.
136  GridBase::Ptr readGridMetadata(const Name&);
137 
138  /// @brief Read a grid's metadata, topology, transform, etc., but not
139  /// any of its leaf node data blocks.
140  /// @return the grid pointer to the partially loaded grid.
141  /// @deprecated Partially-loaded grids might not be compatible with all tools.
142  /// Use them with caution, and preferably use delayed loading instead.
143  OPENVDB_DEPRECATED GridBase::ConstPtr readGridPartial(const Name&);
144 
145  /// Read an entire grid, including all of its data blocks.
146  GridBase::Ptr readGrid(const Name&);
147 #ifndef OPENVDB_2_ABI_COMPATIBLE
148  /// @brief Read a grid, including its data blocks, but only where it
149  /// intersects the given world-space bounding box.
150  GridBase::Ptr readGrid(const Name&, const BBoxd&);
151 #endif
152 
153  /// @todo GridPtrVec readAllGridsPartial(const Name&)
154  /// @todo GridPtrVec readAllGrids(const Name&)
155 
156  /// @brief Write the grids in the given container to the file whose name
157  /// was given in the constructor.
158  void write(const GridCPtrVec&, const MetaMap& = MetaMap()) const override;
159 
160  /// @brief Write the grids in the given container to the file whose name
161  /// was given in the constructor.
162  template<typename GridPtrContainerT>
163  void write(const GridPtrContainerT&, const MetaMap& = MetaMap()) const;
164 
165  /// A const iterator that iterates over all names in the file. This is only
166  /// valid once the file has been opened.
168  {
169  public:
170  NameIterator(const NameMapCIter& iter): mIter(iter) {}
171  NameIterator(const NameIterator&) = default;
173 
174  NameIterator& operator++() { mIter++; return *this; }
175 
176  bool operator==(const NameIterator& iter) const { return mIter == iter.mIter; }
177  bool operator!=(const NameIterator& iter) const { return mIter != iter.mIter; }
178 
179  Name operator*() const { return this->gridName(); }
180 
181  Name gridName() const { return GridDescriptor::nameAsString(mIter->second.uniqueName()); }
182 
183  private:
184  NameMapCIter mIter;
185  };
186 
187  /// @return a NameIterator to iterate over all grid names in the file.
188  NameIterator beginName() const;
189 
190  /// @return the ending iterator for all grid names in the file.
191  NameIterator endName() const;
192 
193 private:
194  /// Read in all grid descriptors that are stored in the given stream.
195  void readGridDescriptors(std::istream&);
196 
197  /// @brief Return an iterator to the descriptor for the grid with the given name.
198  /// If the name is non-unique, return an iterator to the first matching descriptor.
199  NameMapCIter findDescriptor(const Name&) const;
200 
201  /// Return a newly created, empty grid of the type specified by the given grid descriptor.
203 
204  /// @brief Read a grid, including its data blocks, but only where it
205  /// intersects the given world-space bounding box.
206  GridBase::Ptr readGridByName(const Name&, const BBoxd&);
207 
208  /// Read in and return the partially-populated grid specified by the given grid descriptor.
209  GridBase::ConstPtr readGridPartial(const GridDescriptor&, bool readTopology) const;
210 
211  /// Read in and return the grid specified by the given grid descriptor.
212  GridBase::Ptr readGrid(const GridDescriptor&) const;
213 #ifndef OPENVDB_2_ABI_COMPATIBLE
214  /// Read in and return the region of the grid specified by the given grid descriptor
215  /// that intersects the given world-space bounding box.
216  GridBase::Ptr readGrid(const GridDescriptor&, const BBoxd&) const;
217  /// Read in and return the region of the grid specified by the given grid descriptor
218  /// that intersects the given index-space bounding box.
219  GridBase::Ptr readGrid(const GridDescriptor&, const CoordBBox&) const;
220 #endif
221 
222  /// @brief Partially populate the given grid by reading its metadata and transform and,
223  /// if the grid is not an instance, its tree structure, but not the tree's leaf nodes.
224  void readGridPartial(GridBase::Ptr, std::istream&, bool isInstance, bool readTopology) const;
225 
226  /// @brief Retrieve a grid from @c mNamedGrids. Return a null pointer
227  /// if @c mNamedGrids was not populated (because this file is random-access).
228  /// @throw KeyError if no grid with the given name exists in this file.
229  GridBase::Ptr retrieveCachedGrid(const Name&) const;
230 
231  void writeGrids(const GridCPtrVec&, const MetaMap&) const;
232 
233  MetaMap::Ptr fileMetadata();
234  MetaMap::ConstPtr fileMetadata() const;
235 
236  const NameMap& gridDescriptors() const;
237  NameMap& gridDescriptors();
238 
239  std::istream& inputStream() const;
240 
241  friend class ::TestFile;
242  friend class ::TestStream;
243 
244  struct Impl;
245  std::unique_ptr<Impl> mImpl;
246 };
247 
248 
249 ////////////////////////////////////////
250 
251 
252 inline void
253 File::write(const GridCPtrVec& grids, const MetaMap& meta) const
254 {
255  this->writeGrids(grids, meta);
256 }
257 
258 
259 template<typename GridPtrContainerT>
260 inline void
261 File::write(const GridPtrContainerT& container, const MetaMap& meta) const
262 {
263  GridCPtrVec grids;
264  std::copy(container.begin(), container.end(), std::back_inserter(grids));
265  this->writeGrids(grids, meta);
266 }
267 
268 } // namespace io
269 } // namespace OPENVDB_VERSION_NAME
270 } // namespace openvdb
271 
272 #endif // OPENVDB_IO_FILE_HAS_BEEN_INCLUDED
273 
274 // Copyright (c) 2012-2017 DreamWorks Animation LLC
275 // All rights reserved. This software is distributed under the
276 // Mozilla Public License 2.0 ( http://www.mozilla.org/MPL/2.0/ )
Grid serializer/unserializer.
Definition: Archive.h:58
Definition: ImfName.h:53
void write(const GridCPtrVec &, const MetaMap &=MetaMap()) const override
Write the grids in the given container to the file whose name was given in the constructor.
Definition: File.h:253
GridType::Ptr createGrid(const typename GridType::ValueType &background)
Create a new grid of type GridType with a given background value.
Definition: Grid.h:1572
SharedPtr< GridBase > Ptr
Definition: Grid.h:106
bool operator!=(const NameIterator &iter) const
Definition: File.h:177
GLsizei const GLchar *const * string
Definition: glcorearb.h:813
Grid archive associated with a file on disk.
Definition: File.h:54
NameMap::const_iterator NameMapCIter
Definition: File.h:58
bool operator==(const NameIterator &iter) const
Definition: File.h:176
Container that maps names (strings) to values of arbitrary types.
Definition: MetaMap.h:46
std::function< void(std::string)> Notifier
Definition: io.h:172
std::shared_ptr< T > SharedPtr
Definition: Types.h:130
#define OPENVDB_API
Helper macros for defining library symbol visibility.
Definition: Platform.h:194
#define OPENVDB_DEPRECATED
Definition: Platform.h:49
#define OPENVDB_VERSION_NAME
Definition: version.h:43
std::multimap< Name, GridDescriptor > NameMap
Definition: File.h:57
virtual int open(float queuesize)
SharedPtr< const MetaMap > ConstPtr
Definition: MetaMap.h:50
SharedPtr< GridPtrVec > GridPtrVecPtr
Definition: Grid.h:439
virtual void close()
SharedPtr< const GridBase > ConstPtr
Definition: Grid.h:107
#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
static std::string nameAsString(const Name &)
Given a name with suffix N, return "name[N]", otherwise just return "name". Use this to produce a...