overview(3)

NAME
overview - .TH "overview" 3 "Sat Mar 24 2012" "Version 2.36" "SilverLining"

NAME
overview - .SH "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 OpenGL and Direct3D applications that use SilverLining. You'll also find a modified 'osgviewer' application that integrates SilverLining under OpenSceneGraph 2.4, and a modified Ogre3D demo application.
•   resources: Graphics, shaders, and other resources needed by SilverLining, including the DLL's specific to OpenGL, OpenGL 3.2 core, and DirectX9, 10 or 11 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 C++ 6, 7, 8, 9 and 10 in the lib/vc6, lib/vc7, lib/vc8, lib/vc9, and lib/vc10 directories, respectively. Within the vc8, 9, and 10 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, built for 32-bit. If you purchase a license, you'll have the full source to recompile your own library for 64 bit if need be.

  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 2005, 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/vc8/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.
DirectX users in general should be building with the June 2010 version of the DirectX SDK or newer.
Project files and libraries are included for Visual Studio 6 (VC6), Visual Studio .NET 2003 (VC7), Visual Studio 2005 (VC8), Visual Studio 2008 (VC9), and Visual Studio 2010 (VC10). Our Visual Studio 2008 and 2010 libraries are linked against version 7 of the Microsoft SDK; Visual Studio 2005 is linked against version 6.0a. 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.
Support for VC6 and VC7 is limited. Library builds are not provided for linking against custom renderers with the VC6 and VC7 libraries, and only the OpenGL and DirectX9 renderers will work with them.
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 support@sundog-soft.com for any specialized builds you may require.
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. You'll also find 'norenderer' versions of each SilverLining library - these libraries do not include any rendering code, and allow you to link in your own hooks to your own rendering engine. See Direct Integration With Custom Renderers for more information.

  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.
We provide pre-built static libraries for gcc in our Linux SDK, 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:
•   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.
•   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. See Direct Integration With Custom Renderers for more information.
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 will also find a makefile for rebuilding the SilverLining library itself. To rebuild the library, you'll also need to define the LINUX preprocessor definition, as well as SILVERLINING_STATIC_RENDERER_OPENGL to statically link in the code in the SilverLiningOpenGL subdirectory.

  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 2010 Professional. If you need pre-compiled binaries, contact support@sundog-soft.com.
•   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 (available at www.opentk.com) to build this sample.
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 (February 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.
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.

Overview of SilverLining
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, 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, and CloudLayers can also provide shadow maps for use in casting shadows in your scenes from the clouds. Details on that may be found in Using SilverLining.