troubleshoot(3)

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

NAME
troubleshoot - .SH "'The application has failed to start because the application's configuration is incorrect.'"

If you receive this message when you run your application that links in SilverLining, it's due to a mismatch between the dynamic runtime libraries we linked SilverLining against, and the dynamic runtime libraries installed on your system. This is most commonly an issue under Visual Studio 2005, as a service update in July 2009 updated all of the runtime dependencies to a new version (see http://support.microsoft.com/kb/973544 .) This means that even if you have service pack 1 installed for Visual Studio 2005, you don't necessarily have the latest runtimes.

One solution is to ensure you have the most recent service packs installed for Visual Studio, and run Windows Update to apply any security patches that have been released since then. SilverLining is always linked against the latest updates from Microsoft. Be sure to install the latest redistributable dependencies from Microsoft with your application, to prevent this same issue on your user's systems.

An even better solution is to avoid the dynamic dependencies on the Visual Studio runtimes altogether. If you can, set your project settings to use the non-DLL versions of the runtimes. You can change this under the 'runtime library' property under the C++ / Language Settings property page. You may then link in the non-DLL versions of the SilverLining libraries as well, and avoid what's commonly known as 'DLL hell' by statically linking the correct runtime directly into your application.

Another solution, if you have a full-source license for SilverLining, is to recompile the SilverLining libraries from source. That will cause them to link against whatever runtime libraries are installed on your system, which should also solve this issue. Again, if you're using the DLL runtimes, it's critical that you redistribute the same runtimes with your application.

SilverLining crashes at startup

If you're using the evaluation version of the Windows SDK, SilverLining will display a dialog box when the Atmosphere constructor is invoked, warning you about the time restriction on the SDK. If you instantiate your Atmosphere object after your application is in full-screen mode, some applications will not be able to handle a dialog box being displayed while full-screen mode is active. To work around this, instantiate your Atmosphere object before entering full-screen mode.

Another situation may be OpenSceneGraph applications running with multiple monitors. The OSG sample code we provide does not handle the case of multiple contexts. Run in single-monitor mode to get started.

Atmosphere::Initialize() returns an error code

There are several cases that might cause the initialization of SilverLining to fail; here are the error codes returned from Atmosphere::Initialize for each:

E_RESOURCES_PATH_INVALID: This error will occur if the file SilverLining.config could not be opened within the resources path you specified in your call to Atmosphere::Initialize(). Usually, this means that your resource path is incorrect. Make sure the backslashes in your path are escaped, and that your path includes a trailing backslash, and double-check that the path you specified exists. The SilverLining SDK will be installed to different paths depending on whether you're on a 32-bit or 64-bit OS, for example.

E_CONFIGURATION_FILE_NOT_FOUND: If the file SilverLining.config within your resources directory could not be parsed for any reason, this error will be returned. Generally, this means the config file has been modified incorrectly or is otherwise corrupt.

E_CANT_LOAD_RENDERER_DLL: SilverLining will construct a path to the appropriate renderer DLL based on whether you're using DirectX or OpenGL, VC8 or VC9, and 32 or 64 bit builds. These DLL's are stored within your resources directory; an example path might end up being resources/vc8/win32/SilverLiningOpenGL-MT.dll for instance. If the renderer was unable to load this DLL at runtime, then this error will be returned. If you haven't moved these DLL's out of this location and you are specifying a valid value for the renderer parameter of Atmosphere::Initialize, please contact support@sundog-soft.com and indicate what renderer you're using, what version of Visual Studio, and whether you're using 32 or 64 bit versions of our libraries. Also send us a copy of your call to Atmosphere::Initialize().

E_CANT_INITIALIZE_RENDERER_SUBSYSTEM: This means SilverLining was unable to get some basic information from OpenGL or DirectX and was unable to set up its buffers for rendering to textures. Usually, this means you called Atmosphere::Initialize() before your rendering context was set up, or from outside of your rendering thread altogether. Be sure you're within the context you intend to use for rendering when calling Initialize(). SilverLining also requires a lockable backbuffer, if you're using an engine that does not provide this (such as Ogre3D,) set the render-offscreen setting in resources/Silverlining.config to 'yes' to disable direct use of the backbuffer.

E_CANT_LOAD_METABALL_TEXTURE: This error will return if the file wispy-metaball.tga could not be loaded from within your specified resources directory path. Contact support@sundog-soft.com if you haven't moved or modified this file.

My sky is sideways / upside down / otherwise misoriented

Be sure to call Atmosphere::SetUpVector() and Atmosphere::SetRightVector() prior to calling Atmosphere::Initialize() so we know which way is up. Also, take care in setting the handedness parameter of Atmosphere::Initialize.

My sky doesn't appear or doesn't move with the camera

SilverLining assumes that the current modelview and projection matrices represent your camera's view when Atmosphere::DrawSky() is called. Some engines will reset their modelview and projection matrices outside of their own internal rendering code. When this happens, your sky will appear static or won't be in the right place at all. You may need to explicitly obtain your modelview and projection matrices, and set them directly via OpenGL or DirectX prior to calling Atmosphere::DrawSky().

SilverLining slows down my framerate too much

Having too many cumulus congestus clouds in a scene tends to be the main performance hog; the first thing you should do is ensure your cumulus congestus cloud layers aren't bigger than they need to be. The number of clouds we need to render increases with the square of the size of these layers. Reducing the density of these cloud layers will also help.

Beyond that, there are several settings in the file resources/SilverLining.config that you can adjust, in order to make your own trade-offs between performance and visual quality.

Start with the setting cumulus-congestus-voxel-dimension. The bigger you make this, the fewer voxels will be required to render each cumulus congestus cloud. Increasing this will help quite a bit, but the clouds will look a little less complex as a result.

If you are using stratocumulus clouds, their bottleneck is fragment processing - the resolution of the display will affect performance more than anything. You can tweak performance by adjusting the preprocessor definitions in the stratocumulus shaders themselves - open them up from the resources/shaders file for the renderer you are using, and you'll see ways of adjusting the sampling rates at the top of the shader.

If your viewpoint changes slowly, configuring SilverLining to use impostors more aggressively may help quite a bit. By default, the setting of cloud-backdrop-distance is set to a distance of 50km. Bringing this in closer to the camera will cause more cumulus clouds to be rendered to a ring of impostors surrounding the camera, which can yield big framerate improvements.

cull-interior-voxels will prevent SilverLining from rendering voxels that are unlikely to be visible, and helps a little bit as well.

My framerate gets slower over time when I'm using SilverLining, for no apparent reason

This seems to be an issue specific to older NVidia drivers, related to our use of vertex buffer objects. To work around this, either update your drivers, or set the environment variable SILVERLINING_NO_VBO to 1 on your system (and restart your development environment to pick it up.)

My sky or clouds are rendering funny

Try opening up the file resources/SilverLining.config in a text editor, and set 'disable-shaders' to 'yes'. Although we test SilverLining on a wide variety of systems, our shaders will sometimes compile in unexpected ways on new hardware we haven't encountered yet. Disabling shaders will cause SilverLining to fall back to more compatible methods of transforming its vertices, at a slight performance cost. If you run into this situation, please contact support@sundog-soft.com with your system information (especially what graphics card you're using) so we can support shaders on your system going forward.

I use an unusual coordinate system, and the clouds aren't showing up where I expect them

If you're using a geocentric coordiante system ('Earth Centered Earth Fixed'), be sure to read the section Using SilverLining in Geocentric or ECEF (Earth Centered Earth Fixed) Coordinates for important information on how to position cloud layers in these systems.

Some users render everything relative to the eyepoint. This causes problems, since SilverLining assumes that the modelview matrix you pass in represents the camera location and rotation, and that this matrix is consistent with the matrix OpenGL or DirectX is using for drawing. The best way around issues like this is to push your own special modelview matrix onto the stack using glPushMatrix prior to calling Atmosphere::DrawSky or Atmosphere::DrawObjects, then construct an equivalent modelview matrix that assumes the origin is at (0,0,0) instead of the eyepoint. Such a matrix will include the camera rotation and translation. Make this new matrix your modelview matrix, and pass it into Atmosphere::SetCameraMatrix - then call Atmosphere::DrawSky or Atmosphere::DrawObjects, and then restore your original modelview matrix prior to doing your own drawing.

I can't link against your Linux libraries

Our prebuilt libraries for gcc are built against the latest STL and GL libraries at the time of the release. If your linux distribution is not up to date, you may encounter link errors against STL containers. If updating your distribution is not an option or doesn't help, contact support@sundog-soft.com using your work email account - we may be able to give you what you need to build SilverLining from source against your own environment during your evaluation. 64-bit systems may be supported in the same way.

My problem isn't listed here!

Send us a note at support@sundog-soft.com. Even if you haven't purchased a license yet, we'll do what we can to help get you up and running.