clutter/clutter-version.h

   1 /*
   2  * Clutter.
   3  *
   4  * An OpenGL based 'interactive canvas' library.
   5  *
   6  * Authored By Matthew Allum  <mallum@openedhand.com>
   7  *
   8  * Copyright (C) 2006 OpenedHand
   9  *
  10  * This library is free software; you can redistribute it and/or
  11  * modify it under the terms of the GNU Lesser General Public
  12  * License as published by the Free Software Foundation; either
  13  * version 2 of the License, or (at your option) any later version.
  14  *
  15  * This library is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18  * Lesser General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU Lesser General Public
  21  * License along with this library. If not, see <http://www.gnu.org/licenses/>.
  22  *
  23  *
  24  */
  25
  26 #if !defined(__CLUTTER_H_INSIDE__) && !defined(CLUTTER_COMPILATION)
  27 #error "Only <clutter/clutter.h> can be included directly."
  28 #endif
  29
  30 #ifndef __CLUTTER_VERSION_H__
  31 #define __CLUTTER_VERSION_H__
  32
  33 /**
  34  * SECTION:clutter-version
  35  * @short_description: Versioning utility macros
  36  *
  37  * Clutter offers a set of macros for checking the version of the library
  38  * at compile time; it also provides a function to perform the same check
  39  * at run time.
  40  *
  41  * Clutter adds version information to both API deprecations and additions;
  42  * by definining the macros %CLUTTER_VERSION_MIN_REQUIRED and
  43  * %CLUTTER_VERSION_MAX_ALLOWED, you can specify the range of Clutter versions
  44  * whose API you want to use. Functions that were deprecated before, or
  45  * introduced after, this range will trigger compiler warnings. For instance,
  46  * if we define the following symbols:
  47  *
  48  * |[
  49  *   CLUTTER_VERSION_MIN_REQUIRED = CLUTTER_VERSION_1_6
  50  *   CLUTTER_VERSION_MAX_ALLOWED  = CLUTTER_VERSION_1_8
  51  * ]|
  52  *
  53  * and we have the following functions annotated in the Clutter headers:
  54  *
  55  * |[
  56  *   void clutter_function_A (void) CLUTTER_DEPRECATED_IN_1_4;
  57  *   void clutter_function_B (void) CLUTTER_DEPRECATED_IN_1_6;
  58  *   void clutter_function_C (void) CLUTTER_AVAILABLE_IN_1_8;
  59  *   void clutter_function_D (void) CLUTTER_AVAILABLE_IN_1_10;
  60  * ]|
  61  *
  62  * then any application code using the functions above will get the output:
  63  *
  64  * |[
  65  *   clutter_function_A: deprecation warning
  66  *   clutter_function_B: no warning
  67  *   clutter_function_C: no warning
  68  *   clutter_function_D: symbol not available warning
  69  * ]|
  70  *
  71  * It is possible to disable the compiler warnings by defining the macro
  72  * %CLUTTER_DISABLE_DEPRECATION_WARNINGS before including the clutter.h
  73  * header.
  74  */
  75
  76 #include <glib.h>
  77
  78 G_BEGIN_DECLS
  79
  80 /**
  81  * CLUTTER_MAJOR_VERSION:
  82  *
  83  * The major version of the Clutter library (1, if %CLUTTER_VERSION is 1.2.3)
  84  */
  85 #define CLUTTER_MAJOR_VERSION   (1)
  86
  87 /**
  88  * CLUTTER_MINOR_VERSION:
  89  *
  90  * The minor version of the Clutter library (2, if %CLUTTER_VERSION is 1.2.3)
  91  */
  92 #define CLUTTER_MINOR_VERSION   (10)
  93
  94 /**
  95  * CLUTTER_MICRO_VERSION:
  96  *
  97  * The micro version of the Clutter library (3, if %CLUTTER_VERSION is 1.2.3)
  98  */
  99 #define CLUTTER_MICRO_VERSION   (4)
 100
 101 /**
 102  * CLUTTER_VERSION:
 103  *
 104  * The full version of the Clutter library, like 1.2.3
 105  */
 106 #define CLUTTER_VERSION         1.10.4
 107
 108 /**
 109  * CLUTTER_VERSION_S:
 110  *
 111  * The full version of the Clutter library, in string form (suited for
 112  * string concatenation)
 113  */
 114 #define CLUTTER_VERSION_S       "1.10.4"
 115
 116 /**
 117  * CLUTTER_VERSION_HEX:
 118  *
 119  * Numerically encoded version of the Clutter library, like 0x010203
 120  */
 121 #define CLUTTER_VERSION_HEX     ((CLUTTER_MAJOR_VERSION << 24) | \
 122                                  (CLUTTER_MINOR_VERSION << 16) | \
 123                                  (CLUTTER_MICRO_VERSION << 8))
 124
 125 /* XXX - Every new stable minor release bump should add a macro here */
 126
 127 /**
 128  * CLUTTER_VERSION_1_0:
 129  *
 130  * A macro that evaluates to the 1.0 version of Clutter, in a format
 131  * that can be used by the C pre-processor.
 132  *
 133  * Since: 1.10
 134  */
 135 #define CLUTTER_VERSION_1_0     (G_ENCODE_VERSION (1, 0))
 136
 137 /**
 138  * CLUTTER_VERSION_1_2:
 139  *
 140  * A macro that evaluates to the 1.2 version of Clutter, in a format
 141  * that can be used by the C pre-processor.
 142  *
 143  * Since: 1.10
 144  */
 145 #define CLUTTER_VERSION_1_2     (G_ENCODE_VERSION (1, 2))
 146
 147 /**
 148  * CLUTTER_VERSION_1_4:
 149  *
 150  * A macro that evaluates to the 1.4 version of Clutter, in a format
 151  * that can be used by the C pre-processor.
 152  *
 153  * Since: 1.10
 154  */
 155 #define CLUTTER_VERSION_1_4     (G_ENCODE_VERSION (1, 4))
 156
 157 /**
 158  * CLUTTER_VERSION_1_6:
 159  *
 160  * A macro that evaluates to the 1.6 version of Clutter, in a format
 161  * that can be used by the C pre-processor.
 162  *
 163  * Since: 1.10
 164  */
 165 #define CLUTTER_VERSION_1_6     (G_ENCODE_VERSION (1, 6))
 166
 167 /**
 168  * CLUTTER_VERSION_1_8:
 169  *
 170  * A macro that evaluates to the 1.8 version of Clutter, in a format
 171  * that can be used by the C pre-processor.
 172  *
 173  * Since: 1.10
 174  */
 175 #define CLUTTER_VERSION_1_8     (G_ENCODE_VERSION (1, 8))
 176
 177 /**
 178  * CLUTTER_VERSION_1_10:
 179  *
 180  * A macro that evaluates to the 1.10 version of Clutter, in a format
 181  * that can be used by the C pre-processor.
 182  *
 183  * Since: 1.10
 184  */
 185 #define CLUTTER_VERSION_1_10    (G_ENCODE_VERSION (1, 10))
 186
 187 /* evaluates to the current stable version; for development cycles,
 188  * this means the next stable target
 189  */
 190 #if (CLUTTER_MINOR_VERSION % 2)
 191 # define CLUTTER_VERSION_CUR_STABLE      (G_ENCODE_VERSION (CLUTTER_MAJOR_VERSION, CLUTTER_MINOR_VERSION + 1))
 192 #else
 193 # define CLUTTER_VERSION_CUR_STABLE      (G_ENCODE_VERSION (CLUTTER_MAJOR_VERSION, CLUTTER_MINOR_VERSION))
 194 #endif
 195
 196 /* evaluates to the previous stable version */
 197 #if (CLUTTER_MINOR_VERSION % 2)
 198 # define CLUTTER_VERSION_PREV_STABLE     (G_ENCODE_VERSION (CLUTTER_MAJOR_VERSION, CLUTTER_MINOR_VERSION - 1))
 199 #else
 200 # define CLUTTER_VERSION_PREV_STABLE     (G_ENCODE_VERSION (CLUTTER_MAJOR_VERSION, CLUTTER_MINOR_VERSION - 2))
 201 #endif
 202
 203 /**
 204  * CLUTTER_CHECK_VERSION:
 205  * @major: major version, like 1 in 1.2.3
 206  * @minor: minor version, like 2 in 1.2.3
 207  * @micro: micro version, like 3 in 1.2.3
 208  *
 209  * Evaluates to %TRUE if the version of the Clutter library is greater
 210  * than @major, @minor and @micro
 211  */
 212 #define CLUTTER_CHECK_VERSION(major,minor,micro) \
 213         (CLUTTER_MAJOR_VERSION > (major) || \
 214          (CLUTTER_MAJOR_VERSION == (major) && CLUTTER_MINOR_VERSION > (minor)) || \
 215          (CLUTTER_MAJOR_VERSION == (major) && CLUTTER_MINOR_VERSION == (minor) && CLUTTER_MICRO_VERSION >= (micro)))
 216
 217 /* annotation for exported variables
 218  *
 219  * XXX: this has to be defined here because clutter-macro.h imports this
 220  * header file.
 221  */
 222 #ifdef _MSC_VER
 223 # ifdef CLUTTER_COMPILATION
 224 #  define CLUTTER_VAR __declspec(dllexport)
 225 # else
 226 #  define CLUTTER_VAR extern __declspec(dllimport)
 227 # endif
 228 #else
 229 # define CLUTTER_VAR extern
 230 #endif
 231
 232 /**
 233  * clutter_major_version:
 234  *
 235  * The major component of the Clutter library version, e.g. 1 if the version
 236  * is 1.2.3
 237  *
 238  * This value can be used for run-time version checks
 239  *
 240  * For a compile-time check, use %CLUTTER_MAJOR_VERSION
 241  *
 242  * Since: 1.2
 243  */
 244 CLUTTER_VAR const guint clutter_major_version;
 245
 246 /**
 247  * clutter_minor_version:
 248  *
 249  * The minor component of the Clutter library version, e.g. 2 if the version
 250  * is 1.2.3
 251  *
 252  * This value can be used for run-time version checks
 253  *
 254  * For a compile-time check, use %CLUTTER_MINOR_VERSION
 255  *
 256  * Since: 1.2
 257  */
 258 CLUTTER_VAR const guint clutter_minor_version;
 259
 260 /**
 261  * clutter_micro_version:
 262  *
 263  * The micro component of the Clutter library version, e.g. 3 if the version
 264  * is 1.2.3
 265  *
 266  * This value can be used for run-time version checks
 267  *
 268  * For a compile-time check, use %CLUTTER_MICRO_VERSION
 269  *
 270  * Since: 1.2
 271  */
 272 CLUTTER_VAR const guint clutter_micro_version;
 273
 274 gboolean clutter_check_version (guint major,
 275                                 guint minor,
 276                                 guint micro);
 277
 278 gboolean clutter_check_windowing_backend (const char *backend_type);
 279
 280 G_END_DECLS
 281
 282 #endif /* __CLUTTER_VERSION_H__ */