SilverLining
Class Overview

SDK Contents

The SilverLining SDK includes the following subdirectories:

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 2010, 2012, 2013, and 2015 in the lib/vc10, lib/vc11, lib/vc12, and lib/vc14 directories, respectively. Within the vc10, 11, 12 and 14 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."

Windows Build Settings

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().

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 2010 (VC10), Visual Studio 2012 (VC11), Visual Studio 2013 (VC12), and Visual Studio 2015/2017 (VC14). Our Visual Studio 2010 libraries are linked against version 7 of the Microsoft SDK; Visual Studio 2012 is linked against version 8; at present, we only support desktop applications under Windows 8 and not Metro apps. 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.

Remember - Visual Studio version numbers and the years don't necessarily match up! For example, Visual Studio 2012 is VC11, not VC12. And both Visual Studio 2015 and 2017 are VC14! Make sure you are linking against the correct libraries for the compiler you are using.

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

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, 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 installed on your system. Make sure you have the latest drivers for your graphics card installed.

After building the SDK using "make", SilverLining's libraries will be in the lib/linux subdirectory. The OpenGL sample code provided includes a makefile that illustrates how to link in SilverLining. You'll find three libraries here:

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.

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.

If you are developing with Visual Studio 2012 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 is installed on the target systems, 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 OpenGL, OpenGL 3.2 Core, DirectX 9, DirectX 10, 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.