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 2015 and Visual Studio 2017, including the free Community editions of both. As of this writing Cinder ships with only VC 2015 projects, but these can be used with 2017 without modification. Furthermore, the v141 toolset is fully supported, meaning you can optionally upgrade to the native 2017 toolset. If you do so, you'll want to make sure you've built Cinder with the same.

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.

External Preprocessor Definitions (Advanced)

In some instances, it can be useful to modify libcinder's preprocessor flags without requiring direct modification of its project. This is particularly useful when using Cinder in a project 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 use this technique you need to add cinder.vcxproj to your main project's solution file. This can be convenient in its own right when working on a large project, as it allows 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.