Windows Notes

These are some general notes on Cinder's implementation on the Microsoft Windows platform.

Targeting

By default Cinder targets Windows 7 and later. This is dictated by the _WIN32_WINNT macro, which is typically defined in your project's Preprocessor Definitions build setting. The value 0x0601 maps to Windows 7. To target a different version of Windows, you'll need to modify this variable in both your application and Cinder itself, and rebuild Cinder.

Development Requirements

Cinder supports Visual Studio 2013 and 2015, including the free Community editions of both. As of this writing Cinder ships with only VC 2013 projects, but these can be used with 2015 without modification. Furthermore, the v140 toolset is fully supported, meaning you can optionally upgrade to the native 2015 toolset. If you do so, you'll want to make sure you've built Cinder with the same.

Visual C++ 2013 and 2015 have two toolsets (roughly, compilers) associated with them. For VC 2013 they are v120 and v120_xp. For VC 2015 they are v140 and v140_xp. The non-XP variants are able to target Windows Vista and later. In order to target Windows XP, you'll need to use one of the _xp compilers, in addition to setting _WIN32_WINNT=x0502. Please note that this path is not officially supported, and in particular Cinder's built-in audio will not function. However for advanced users this can be made to work.

ANGLE

In addition to the normal Debug and Release build configurations, Cinder also ships with Debug_ANGLE and Release_ANGLE variants. ANGLE, which stands for Almost Native Graphics Library, is an implementation of OpenGL ES in terms of DirectX. This can be useful for supporting machines where OpenGL drivers can't be guaranteed or are of poorer quality than DirectX. TinderBox can setup your project to use ANGLE.

(Advanced) Defining preprocessor flags from outside of the Cinder repo

In some instances, it can be useful to modify libcinder's preprocessor flags without requiring direct modification of its project. For example, tying your application to a specific version of Cinder via a git submodule. Some common cases include the CI_MIN_LOG_LEVEL, as described in this guide, and compile time macros that adjust the way that CI_ASSERT() works.

  • To enable this, you need to add cinder.vcxproj to your main project's solution file. This is can be a usefl thing to do in its own right when working on a large project, as it allows you direct navigation of Cinder's codebase from within your application.
  • cinder.vcxproj is configured to search for a file called CinderMswUserDefines.h, which will be added as a "Forced Include File", i.e. its contents will be prepended to every source file built in libcinder. The first place that cinder.vcxproj searches for this file is in the same directory as your project's solution (.sln) file, which lives outside of the Cinder repository. If you don't provide a CinderMswUserDefines.h file, the empty default at include\cinder\msw will be used. To override this default, create a CinderMswUserDefines.h file in the same directory as your project's .sln file, and add the preprocessor directives to that. You can also add this same setting to any vcxproj file that you want to make use of the same preprocessor adjustments. Here's a screen capture of what that looks like:
  • For this file to also be found in your projects, you should add an 'Additional Include Directories' to your project for $(SolutionDir), which looks like:
  • Lastly, you may want to make cinder.lib a dependency on your app's target, which forces it to be rebuilt whenever necessary you modify your CinderMswUserDefines.h file (or any other source in libcinder). You can do this by going to the Solution Explorer and right clicking on your solution, then going to the 'Common Properties -> Project Dependencies' page.

Now any additions to CinderMswUserDefines.h will customize the cinder.lib that your app links to accordingly.