HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
version.h
Go to the documentation of this file.
1 // Copyright Contributors to the OpenVDB Project
2 // SPDX-License-Identifier: MPL-2.0
3 
4 /// @file openvdb/version.h
5 /// @brief Library and file format version numbers
6 ///
7 /// @details
8 /// When the library is built with the latest ABI, its namespace has the form
9 /// <B>openvdb::vX_Y</B>, where @e X and @e Y are the major and minor version numbers.
10 ///
11 /// The library can be built using an older ABI by changing the value of the
12 /// @b OPENVDB_ABI_VERSION_NUMBER macro (e.g., via <TT>-DOPENVDB_ABI_VERSION_NUMBER=<I>N</I></TT>).
13 /// In that case, the namespace has the form <B>openvdb::vX_YabiN</B>,
14 /// where N is the ABI version number.
15 /// The ABI version must be set consistently when building code that depends on OpenVDB.
16 ///
17 /// The ABI version number defaults to the library major version number,
18 /// which gets incremented whenever changes are made to the ABI of the
19 /// Grid class or related classes (Tree, Transform, Metadata, etc.).
20 /// Setting the ABI version number to an earlier library version number
21 /// disables grid ABI changes made since that library version.
22 /// The OpenVDB 1.x ABI is no longer supported, and support for other old ABIs
23 /// might also eventually be dropped.
24 ///
25 /// The library minor version number gets incremented whenever a change is made
26 /// to any aspect of the public API (not just the grid API) that necessitates
27 /// changes to client code. Changes to APIs in private or internal namespaces
28 /// do not trigger a minor version number increment; such APIs should not be used
29 /// in client code.
30 ///
31 /// A patch version number increment indicates a change&mdash;usually a new feature
32 /// or a bug fix&mdash;that does not necessitate changes to client code but rather
33 /// only recompilation of that code (because the library namespace incorporates
34 /// the version number).
35 ///
36 /// The file format version number gets incremented when it becomes possible
37 /// to write files that cannot safely be read with older versions of the library.
38 /// Not all files written in a newer format are incompatible with older libraries, however.
39 /// And in general, files containing grids of unknown type can be read safely,
40 /// although the unknown grids will not be accessible.
41 
42 #ifndef OPENVDB_VERSION_HAS_BEEN_INCLUDED
43 #define OPENVDB_VERSION_HAS_BEEN_INCLUDED
44 
45 #include "Platform.h"
46 #include <cstddef> // size_t
47 #include <cstdint> // uint32_t
48 
49 /// @name Utilities
50 /// @{
51 /// @cond OPENVDB_VERSION_INTERNAL
52 #define OPENVDB_PREPROC_STRINGIFY_(x) #x
53 /// @endcond
54 /// @brief Return @a x as a string literal. If @a x is a macro,
55 /// return its value as a string literal.
56 /// @hideinitializer
57 #define OPENVDB_PREPROC_STRINGIFY(x) OPENVDB_PREPROC_STRINGIFY_(x)
58 
59 /// @cond OPENVDB_VERSION_INTERNAL
60 #define OPENVDB_PREPROC_CONCAT_(x, y) x ## y
61 /// @endcond
62 /// @brief Form a new token by concatenating two existing tokens.
63 /// If either token is a macro, concatenate its value.
64 /// @hideinitializer
65 #define OPENVDB_PREPROC_CONCAT(x, y) OPENVDB_PREPROC_CONCAT_(x, y)
66 /// @}
67 
68 // Library major, minor and patch version numbers
69 #define OPENVDB_LIBRARY_MAJOR_VERSION_NUMBER 7
70 #define OPENVDB_LIBRARY_MINOR_VERSION_NUMBER 2
71 #define OPENVDB_LIBRARY_PATCH_VERSION_NUMBER 2
72 
73 // If OPENVDB_ABI_VERSION_NUMBER is already defined (e.g., via -DOPENVDB_ABI_VERSION_NUMBER=N)
74 // use that ABI version. Otherwise, use this library version's default ABI.
75 #ifdef OPENVDB_ABI_VERSION_NUMBER
76  #if OPENVDB_ABI_VERSION_NUMBER > OPENVDB_LIBRARY_MAJOR_VERSION_NUMBER
77  #error expected OPENVDB_ABI_VERSION_NUMBER <= OPENVDB_LIBRARY_MAJOR VERSION_NUMBER
78  #endif
79 #else
80  #define OPENVDB_ABI_VERSION_NUMBER OPENVDB_LIBRARY_MAJOR_VERSION_NUMBER
81 #endif
82 
83 // If using an OPENVDB_ABI_VERSION_NUMBER that has been deprecated, issue a message
84 // directive. Note that an error is also set in openvdb.cc which enforces stricter
85 // behavior during compilation of the library. Both can be optionally suppressed
86 // by defining OPENVDB_USE_DEPRECATED_ABI_<VERSION>.
87 #ifndef OPENVDB_USE_DEPRECATED_ABI_5
88  #if OPENVDB_ABI_VERSION_NUMBER == 5
89  PRAGMA(message("NOTE: ABI = 5 is deprecated, CMake option OPENVDB_USE_DEPRECATED_ABI_5 "
90  "suppresses this message"))
91  #endif
92 #endif
93 
94 #if OPENVDB_ABI_VERSION_NUMBER == OPENVDB_LIBRARY_MAJOR_VERSION_NUMBER
95  /// @brief The version namespace name for this library version
96  /// @hideinitializer
97  ///
98  /// When the ABI version number matches the library major version number,
99  /// symbols are named as in the following examples:
100  /// - @b openvdb::vX_Y::Vec3i
101  /// - @b openvdb::vX_Y::io::File
102  /// - @b openvdb::vX_Y::tree::Tree
103  ///
104  /// where X and Y are the major and minor version numbers.
105  ///
106  /// When the ABI version number does not match the library major version number,
107  /// symbol names include the ABI version:
108  /// - @b openvdb::vX_YabiN::Vec3i
109  /// - @b openvdb::vX_YabiN::io::File
110  /// - @b openvdb::vX_YabiN::tree::Tree
111  ///
112  /// where X, Y and N are the major, minor and ABI version numbers, respectively.
113  #define OPENVDB_VERSION_NAME \
114  OPENVDB_PREPROC_CONCAT(v, \
115  OPENVDB_PREPROC_CONCAT(OPENVDB_LIBRARY_MAJOR_VERSION_NUMBER, \
116  OPENVDB_PREPROC_CONCAT(_, \
117  OPENVDB_PREPROC_CONCAT(OPENVDB_LIBRARY_MINOR_VERSION_NUMBER, _sesi))))
118 #else
119  // This duplication of code is necessary to avoid issues with recursive macro expansion.
120  #define OPENVDB_VERSION_NAME \
121  OPENVDB_PREPROC_CONCAT(v, \
122  OPENVDB_PREPROC_CONCAT(OPENVDB_LIBRARY_MAJOR_VERSION_NUMBER, \
123  OPENVDB_PREPROC_CONCAT(_, \
124  OPENVDB_PREPROC_CONCAT(OPENVDB_LIBRARY_MINOR_VERSION_NUMBER, \
125  OPENVDB_PREPROC_CONCAT(_sesi_, \
126  OPENVDB_PREPROC_CONCAT(abi, OPENVDB_ABI_VERSION_NUMBER))))))
127 #endif
128 
129 /// @brief Library version number string of the form "<major>.<minor>.<patch>"
130 /// @details This is a macro rather than a static constant because we typically
131 /// want the compile-time version number, not the runtime version number
132 /// (although the two are usually the same).
133 /// @hideinitializer
134 #define OPENVDB_LIBRARY_VERSION_STRING \
135  OPENVDB_PREPROC_STRINGIFY(OPENVDB_LIBRARY_MAJOR_VERSION_NUMBER) "." \
136  OPENVDB_PREPROC_STRINGIFY(OPENVDB_LIBRARY_MINOR_VERSION_NUMBER) "." \
137  OPENVDB_PREPROC_STRINGIFY(OPENVDB_LIBRARY_PATCH_VERSION_NUMBER)
138 
139 /// @brief Library version number string of the form "<major>.<minor>.<patch>abi<abi>"
140 /// @details This is a macro rather than a static constant because we typically
141 /// want the compile-time version number, not the runtime version number
142 /// (although the two are usually the same).
143 /// @hideinitializer
144 #define OPENVDB_LIBRARY_ABI_VERSION_STRING \
145  OPENVDB_LIBRARY_VERSION_STRING "abi" OPENVDB_PREPROC_STRINGIFY(OPENVDB_ABI_VERSION_NUMBER)
146 
147 /// Library version number as a packed integer ("%02x%02x%04x", major, minor, patch)
148 #define OPENVDB_LIBRARY_VERSION_NUMBER \
149  ((OPENVDB_LIBRARY_MAJOR_VERSION_NUMBER << 24) | \
150  ((OPENVDB_LIBRARY_MINOR_VERSION_NUMBER & 0xFF) << 16) | \
151  (OPENVDB_LIBRARY_PATCH_VERSION_NUMBER & 0xFFFF))
152 
153 
154 /// By default, the @b OPENVDB_REQUIRE_VERSION_NAME macro is undefined, and
155 /// symbols from the version namespace are promoted to the top-level namespace
156 /// so that, for example, @b openvdb::v5_0::io::File can be referred to
157 /// simply as @b openvdb::io::File.
158 ///
159 /// When @b OPENVDB_REQUIRE_VERSION_NAME is defined, symbols must be
160 /// fully namespace-qualified.
161 /// @hideinitializer
162 #ifdef OPENVDB_REQUIRE_VERSION_NAME
163 #define OPENVDB_USE_VERSION_NAMESPACE
164 #else
165 // The empty namespace clause below ensures that OPENVDB_VERSION_NAME
166 // is recognized as a namespace name.
167 #define OPENVDB_USE_VERSION_NAMESPACE \
168  namespace OPENVDB_VERSION_NAME {} \
169  using namespace OPENVDB_VERSION_NAME;
170 #endif
171 
172 
173 namespace openvdb {
175 namespace OPENVDB_VERSION_NAME {
176 
177 /// @brief The magic number is stored in the first four bytes of every VDB file.
178 /// @details This can be used to quickly test whether we have a valid file or not.
179 const int32_t OPENVDB_MAGIC = 0x56444220;
180 
181 // Library major, minor and patch version numbers
182 const uint32_t
186 /// Library version number as a packed integer ("%02x%02x%04x", major, minor, patch)
188 // ABI version number
190 
191 /// @brief The current version number of the VDB file format
192 /// @details This can be used to enable various backwards compatibility switches
193 /// or to reject files that cannot be read.
194 const uint32_t OPENVDB_FILE_VERSION = 224;
195 
196 /// Notable file format version numbers
197 enum {
212 };
213 
214 
215 /// Return a library version number string of the form "<major>.<minor>.<patch>".
216 inline constexpr const char* getLibraryVersionString() { return OPENVDB_LIBRARY_VERSION_STRING; }
217 /// Return a library version number string of the form "<major>.<minor>.<patch>abi<abi>".
218 inline constexpr const char* getLibraryAbiVersionString() {
220 }
221 
222 
223 struct VersionId {
224  uint32_t first, second;
225  VersionId(): first(0), second(0) {}
226  VersionId(uint32_t major, uint32_t minor): first(major), second(minor) {}
227 };
228 
229 } // namespace OPENVDB_VERSION_NAME
230 } // namespace openvdb
231 
232 #endif // OPENVDB_VERSION_HAS_BEEN_INCLUDED
#define OPENVDB_LIBRARY_MINOR_VERSION_NUMBER
Definition: version.h:70
constexpr const char * getLibraryAbiVersionString()
Return a library version number string of the form "<major>.<minor>.<patch>abi<abi>".
Definition: version.h:218
const int32_t OPENVDB_MAGIC
The magic number is stored in the first four bytes of every VDB file.
Definition: version.h:179
#define PRAGMA(x)
Definition: Platform.h:11
const uint32_t OPENVDB_LIBRARY_PATCH_VERSION
Definition: version.h:185
#define OPENVDB_LIBRARY_PATCH_VERSION_NUMBER
Definition: version.h:71
#define OPENVDB_LIBRARY_VERSION_STRING
Library version number string of the form "<major>.<minor>.<patch>".
Definition: version.h:134
const GLint * first
Definition: glew.h:1528
#define OPENVDB_USE_VERSION_NAMESPACE
Definition: version.h:167
#define OPENVDB_ABI_VERSION_NUMBER
Definition: version.h:80
#define OPENVDB_LIBRARY_VERSION_NUMBER
Library version number as a packed integer ("%02x%02x%04x", major, minor, patch)
Definition: version.h:148
const uint32_t OPENVDB_LIBRARY_VERSION
Library version number as a packed integer ("%02x%02x%04x", major, minor, patch)
Definition: version.h:187
GLsizei GLenum GLuint GLuint GLsizei GLchar * message
Definition: glew.h:2581
VersionId(uint32_t major, uint32_t minor)
Definition: version.h:226
const uint32_t OPENVDB_LIBRARY_MAJOR_VERSION
Definition: version.h:183
#define OPENVDB_LIBRARY_MAJOR_VERSION_NUMBER
Definition: version.h:69
#define OPENVDB_LIBRARY_ABI_VERSION_STRING
Library version number string of the form "<major>.<minor>.<patch>abi<abi>".
Definition: version.h:144
const uint32_t OPENVDB_LIBRARY_MINOR_VERSION
Definition: version.h:184
const uint32_t OPENVDB_ABI_VERSION
Definition: version.h:189
constexpr const char * getLibraryVersionString()
Return a library version number string of the form "<major>.<minor>.<patch>".
Definition: version.h:216
#define OPENVDB_VERSION_NAME
The version namespace name for this library version.
Definition: version.h:113
const uint32_t OPENVDB_FILE_VERSION
The current version number of the VDB file format.
Definition: version.h:194