SilverLining
Class Overview

SDK Contents

The SilverLining SDK includes the following subdirectories:

  • lib: The SilverLining libraries built against various runtime libraries. You'll need to link one of these into your project, as described in the table below.
  • include: The public header files for use with the SilverLining libraries.
  • samplecode: Sample code for simple Vulkan, OpenGL and Direct3D applications that use SilverLining. You'll also find a modified "osgviewer" application that integrates SilverLining under OpenSceneGraph, as well as a VulkanSceneGraph (VSG) integration example.
  • resources: Graphics, shaders, and other resources needed by SilverLining, including the DLL's specific to Vulkan, OpenGL, OpenGL 3.2 core, and DirectX9, 10, 11, or 11.1 for Windows users. These files must be redistributed with your application.
  • docs: Documentation for SilverLining (you're reading it!)

The lib directory contains several versions of the SilverLining library for linking against projects that use different runtime libraries. Builds are available for Microsoft Visual Studio 2015-2019 and Visual Studio 2022 in the lib/vc14 and lib/vc143 directories, respectively. Within the 14 and 143 directories you'll find x64 and win32 subdirectories that contain 64-bit and 32-bit builds, respectively. Linux developers will find the static library linux/libSilverLining.a in here, after building the SDK with "make."

If you require libraries for Visual Studio 2010, 2012, or 2013, an evaluation version that supports these compilers is available at http://media.sundog-soft.com/silverlining-sdk-623.exe. If you own a license for source code, contact suppo.nosp@m.rt@s.nosp@m.undog.nosp@m.-sof.nosp@m.t.com and we can provide the source version of that release for you. A legacy release for Visual Studio 2003 and newer is also available on request, but is unsupported.

Windows Build Settings

NOTE: VULKAN SUPPORT IS ONLY AVAILABLE WITH VISUAL STUDIO 2022 (vc143) OR NEWER.

The Windows SDK installer will set up the environment variable SILVERLINING_PATH, which you can use to safely specify absolute paths to the SilverLining libraries and headers.

To check what runtime library you are using in Visual Studio, open up the project properties, and view the C/C++ "Code Generation" settings. Add the library according to the chart below, by adding it to the "Additional Dependencies" in your Linker / Input settings. Finally, be sure that your linker path is set to include the appropriate lib directory for your development environment (for example, lib/vc14/win32 - see "additional library directories" under the Linker / General tab.)

Also, you will need to link in the system library winmm.lib in order to obtain the definition of timeGetTime().

Vulkan developers will also need to link in the Vulkan SDK library (vulkan-1.lib) and include the necessary Vulkan headers from the Vulkan SDK. Be sure to install the VMA headers for the Vulkan SDK as well, if you plan on rebuilding SilverLining from source at some point. Again, you must install the SilverLining SDK with Visual Studio 2022 support for Vulkan, as our Vulkan support relies on modern features of the C++ language.

DirectX11 users need to link in the build of D3DX11Effects.lib specific to your runtime and compiler under the third-party/Effects11 directory. This is not needed when using the DirectX11.1 renderer, as our DirectX 11.1 support has no dependencies on the effects library, D3DX interfaces, or the D3Dcompiler DLL.

DirectX 9-11 users should be building with the June 2010 version of the DirectX SDK. DirectX 11.1 users may build against the DirectX support included in the Windows 8.1+ SDK.

Project files and libraries are included for Visual Studio 2015/2017/2019 (VC14) and Visual Studio 2022 (VC143). Our libraries are built with the latest service packs installed for each version of Visual Studio; you may encounter runtime linking errors if your Visual Studio is not up to date.

Make sure you are linking against the correct libraries for the compiler you are using.

Visual Studio VersionSilverLining Library Version
2015, 2017, or 2019VC14
2022VC143
Runtime LibrarySilverLining Library
Multi-threadedSilverLining-MT.lib
Multi-threaded DebugSilverLining-MTD.lib
Multi-threaded DLLSilverLining-MT-DLL.lib
Multi-threaded Debug DLLSilverLining-MTD-DLL.lib

Note that Visual Studio 2017 and 2019 are only backward-compatible with VC14.0 libraries when your application is compiled with "whole-program optimization" disabled. If you encounter linker errors with SilverLining under Visual Studio 2017 or 2019, try disabling whole-program optimization (under compiler/optimization) and set link-time code generation to "default" (under linker/optimization.) Alternately, you may rebuild SilverLining with the VC141 toolset you have installed if you have a source code license, which will allow the use of whole-program optimization.

The libraries are built with default byte alignment. If you have specific byte alignment requirements for your application, contact suppo.nosp@m.rt@s.nosp@m.undog.nosp@m.-sof.nosp@m.t.com for any specialized builds you may require.

If you encounter an exception or crash when calling a SilverLining method, odds are you are linking in a C standard runtime library that is different from the one SilverLining was bulit against. This is especially likely if you are ignoring specific runtime libraries in your linker settings, to work around other linker issues with other third party libraries. Usually this is cleared up by also ignoring the msvcrt library variant that's causing the trouble. Don't hesitate to contact suppo.nosp@m.rt@s.nosp@m.undog.nosp@m.-sof.nosp@m.t.com if you run into this sort of trouble. Crashes inside an iterator or mutex object within SilverLining are symptoms of this sort of issue.

The libraries listed above will dynamically link in a DirectX9, DirectX10, DirectX11, Vulkan, or OpenGL rendering library at runtime. Some developers prefer to avoid runtime DLL dependencies; and for customers porting SilverLining to game consoles, this may be required. Licensed users with the full source will find build configurations for the SilverLining library in its project file for statically linking in these renderers, avoiding the runtime dependency on our renderer DLL's.

Linux Build Settings and Dependencies

To successfully link against SilverLining for Linux, you must have OpenGL and/or the Vulkan SDK installed on your system. Make sure you have the latest drivers for your graphics card installed. If building for Vulkan, be sure you have opted to include the VMA headers when installing the Vulkan SDK. Your C++ compiler must support C++11 at a minimum.

After building the SDK using "make", SilverLining's libraries will be in the lib/linux subdirectory. If you require Vulkan support and have already installed the Vulkan SDK (with vma headers), you should run "make vulkan" as well.

The OpenGL and Vulkan sample code provided includes a makefile that illustrates how to link in SilverLining. You'll find four libraries here:

  • libSilverLiningVulkan.a - SilverLining for use in Vulkan applications (only if you ran "make vulkan")
  • libSilverLiningOpenGL.a - SilverLining for any OpenGL context from version 1.4 up; also compatible with 3.2 and above contexts with backward compatibility enabled.
  • libSilverLiningOpenGL32Core.a - SilverLining compatible with OpenGL 3.2 core contexts and above. This takes advantage of modern OpenGL extensions to offer better performance.
  • libSilverLining-norenderer.a - SilverLining with no rendering calls linked in at all. When using this library, you must implement your own renderer that implements the interface defined in SilverLiningDLLCommon.h.

In short, add the lib directory of the sdk to your library path (-L), add the include directory to your include path (-I), and include the libraries SilverLining, GL, and pthreads (-l).

That's all there is to it. Licensed users with full source code receive unobfuscated source code to build from.

Building with C#

You'll find an example of C# integration with SilverLining in the C# Example folder in the sample applications. It's composed of three different projects, which you can build using Visual Studio 2017 Community Edition. Pre-compiled DLL's of the C# interface are also provided for you, for 64-bit Visual Studio 2017.

  • SilverLiningInt - This is a DLL wrapper for the SilverLining native libraries, which may be used to integrate with other interpreted languages as well.
  • SilverLiningCLR - This is a C# wrapper over the native DLL, providing C# access to our unmanaged code. You'll find wrappers for the Atmosphere, CloudLayer, and AtmosphericConditions classes, enabling you to do almost everything in C# that you can do using the C++ public interface. Refer to the C++ class documentation for more details on the methods exposed.
  • OpenGLExample - This example C# application uses SilverLiningCLR to create a scene containing a dynamic skybox and cumulus clouds. You'll need to install OpenTK.GLControl (available through the NuGet Package manager, or at www.opentk.net) to build this sample.

If you're using Managed DirectX, the only trick is to pass the UnmanagedComPointer member of the Device object as the last parameter in AtmosphereCLR::Initialize().

When redistributing a C# application using SilverLining, ensure that the SilverLiningInt.dll is in the application's path, and that the correct path to the resources folder is passed into Atmosphere::Initialize().

Distributing SilverLining with Your Application

You must ship the resources subdirectory, in its entirety, with your application. You will specify where this subdirectory is installed when you call Atmosphere::Initialize().

If your project is linked against the dynamically linked runtime libraries, be sure that the required Microsoft DLL's are distributed with your application as well.

DirectX users must install the latest DirectX runtime libraries (June 2010 or newer.) DirectX11 users must furthermore install the Direct3D11 dll's on systems that do not have them using the D3D11InstallHelper or an equivalent scheme. See http://msdn.microsoft.com/en-us/library/ee416805(VS.85).aspx and http://msdn.microsoft.com/en-us/library/ee416644(VS.85).aspx for more information.

Vulkan users must ensure a recent Vulkan runtime and recent video drivers are installed on the client systems.

If you are developing with Visual Studio 2015 or newer and the Windows 8 SDK, and using DirectX, you also need to redistribute the runtime shader compilation DLL's alongside your application's executable. You'll find these inside the Windows 8 SDK under %ProgramFiles(x86)%\Windows Kits\8.0\Redist\D3D\<arch> where <arch> is x86 and x64. You must also install the runtimes for the June 2010 DirectX DLL to ensure the D3DX methods that are not included in the Windows 8 SDK are available.

Linux application developers must ensure that OpenGL or Vulkan is installed on the target systems as appropriate, as well as the latest graphics drivers for their 3D video card.

If you are distributing a commercial application with SilverLining, please remember to include the required copyright notices for SilverLining in your application. See your license agreement for more details. We'd also appreciate including our name and/or logo along with your other middleware credits.

Class Overview

Using SilverLining isn't complicated, and involves understanding only a few classes and how they interact with each other. While developing an application with SilverLining, you'll likely encounter these classes in this order:

First, you'll create an SilverLining::Atmosphere object, which is the primary interface to SilverLining for your application. After instantiating it, it needs to be initialized so that it knows if you're using Vulkan, OpenGL, OpenGL 3.2 Core, DirectX 9, or DirectX 11.

Next, you'll want to create a SilverLining::AtmosphericConditions object, in order to configure your Atmosphere to your liking.

The first things you'll want to configure in AtmosphericConditions are the time and location you wish to simulate. To do this, you'll need to instantiate and configure a LocalTime and a Location class, and pass these into SilverLining::AtmosphericConditions::SetTime() and SilverLining::AtmosphericConditions::SetLocation().

If you want to simulate wind in your scene to make your clouds move, just set up a SilverLining::WindVolume class and pass that into SilverLining::AtmosphericConditions::SetWind().

If you want to add clouds to your scene, the easiest way to get started is to use SilverLining::AtmosphericConditions::SetPresetConditions(). This will let you quickly set up fair, partly cloudy, mostly cloudy, or overcast conditions with one line of code.

For more control of the cloud conditions, you'll need to create some SilverLining::CloudLayer objects and pass them into SilverLining::AtmosphericConditions::AddCloudLayer(). CloudLayer objects are created with the SilverLining::CloudLayerFactory class, which allows you to create cumulus congestus, cumulus mediocris, cumulonimbus, stratus, nimbostratus, or cirrus cloud decks. After creating the CloudLayer you want, configure it for the desired dimensions, precipitation, and cloud coverage, call SilverLining::CloudLayer::SeedClouds() to populate the cloud layer with clouds, and then pass it into your AtmosphericConditions.

Once your AtmosphericConditions are set up to your liking, pass them into your Atmosphere using SilverLining::Atmosphere::SetConditions().

That's all the setup that's required. Now, to actually see the simulated sky and clouds in your scene, only three more things are necessary: at the beginning of each frame, pass your modelview and projection matrices into SilverLining using SilverLining::Atmosphere::SetCameraMatrix() and SilverLining::Atmosphere::SetProjectionMatrix(). Then, call SilverLining::Atmosphere::DrawSky() before rendering the objects in your scene, and call SilverLining::Atmosphere::DrawObjects() at the end of your frame.

That's really all there is to it; we've discussed every class you need to know about already. Users who want to take advantage of the lighting and fog simulation provided by SilverLining can obtain this information from the Atmosphere class. Details on that may be found in Using SilverLining.