Building osgEarth

The documentation here is focused on Windows.

Building with vcpkg

vcpkg is an extremely useful package manager. It works on Windows, Linux and MacOS but for this guide we will focus on Windows.

Step 1 - Configure vcpkg

First, download and bootstrap vcpkg following the instructions on the page.

Next install the dependencies required to build a fully functional osgEarth. This example assume s 64-bit Windows build; you can alter that to correspond to your platform/architecture of choice.

Install the required dependencies:

vcpkg install osg:x64-windows gdal:x64-windows curl:x64-windows

For full functionality, you can install optional dependences as well:

vcpkg install sqlite3:x64-windows protobuf:x64-windows geos:x64-windows blend2d:x64-windows webp:x64-windows basisu:x64-windows draco:x64-windows libzip:x64-windows

This will take awhile the first time you run it as this pulls down lots of dependencies, so go get a cup of coffee.

Once all the dependencies are built, you’ll need to actually build osgEarth.

Step 2 - Clone the repository

Pull down the source from GitHub and create a build folder for your out-of-source build. We always recommend doing an out-of-source build to avoid problems down the road!

git clone https://github.com/gwaldron/osgearth.git
mkdir build

Step 3 - Configure CMake

vcpkg provides a CMake toolchain file that helps osgEarth find all of its dependencies.

Note: You’ll need to specify a different build directory based on your build configuration (Release, RelWIthDebInfo, Debug) and specify the build type using -DCMAKE_BUILD_TYPE. This is because some dependencies of osgEarth don’t pick up both debug and release versions without specifying the build type. Hopefully this will be fixed in future CMake versions.

Most developers will use a RelWithDebInfo build, like so:

cmake -S osgearth -B build -G "Visual Studio 15 2017 Win64" -DCMAKE_BUILD_TYPE=RelWithDebInfo -DWIN32_USE_MP=ON -DCMAKE_INSTALL_PREFIX=[installroot] -DCMAKE_TOOLCHAIN_FILE=[vcpkgroot]\scripts\buildsystems\vcpkg.cmake

Step 4 - Build and install osgEarth

You can build and install osgEarth on the command line using CMake or you can open up the Visual Studio solution and build it from there.

cmake --build build --target INSTALL --config RelWithDebInfo

Step 5 - Set up your runtime environment

You’ll need to make sure that the vcpkg dependencies and osgEarth are in your path:

set PATH=%PATH%;c:\vcpkg\installed\x64-windows\bin
set PATH=%PATH%;c:\vcpkg\installed\x64-windows\tools\osg
set PATH=%PATH%;[installroot]

Building for OpenGL CORE Profile

You may wish to build osgEarth with support for the OpenGL CORE profile. In fact is a requirement for some platforms including Apple OSX and VMWare. Doing to requires that you first build OpenSceneGraph with CORE profile support. The OpenSceneGraph dependency in vcpkg does NOT have GLCORE support (at the time of this writing) so you will have to build it yourself.

Build OpenSceneGraph for GLCORE

  1. First, download the GL CORE include files from Khronos and place them somewhere on your system. We’ll call this the GLCORE folder.
  2. In CMake, set the OPENGL_PROFILE property to “GLCORE”.
  3. In CMake, set the GLCORE_GLCOREARB_HEADER property to the location of the GL folder you downloaded from Khronos. For example, if you include file is at C:\glcore\GL\glcorearb.h you should set this property to C:\glcore.
  4. In CMake, set the following properties to ON :
    • OSG_GL3_AVAILABLE
  5. In CMake, set the following properties to OFF :
    • OSG_GL1_AVAILABLE
    • OSG_GL2_AVAILABLE
    • OSG_GLES1_AVAILABLE
    • OSG_GLES2_AVAILABLE
    • OSG_GL_DISPLAYLISTS_AVAILABLE
    • OSG_GL_FIXED_FUNCTION_AVAILABLE
    • OSG_GL_MATRICES_AVAILABLE
    • OSG_GL_VERTEX_ARRAY_FUNCS_AVAILABLE
    • OSG_GL_VERTEX_FUNCS_AVAILABLE
  6. Configure and build OpenSceneGraph.

Build osgEarth for GLCORE

Now that you have OSG built with GLCORE support, time to build osgEarth.

  1. In CMake, set the OSGEARTH_GLCORE_INCLUDE_DIR property to the same folder holding the Khronos include files (the same value of the GLCORE_GLCOREARB_HEADER in your OSG build).
  2. Configure and build osgEarth.

Test you build by running this on the command line (Windows)

set OSG_GL_CONTEXT_VERSION=4.6
osgearth_version --caps

If all went well, it should report “Core Profile = yes”.

You can disable the CORE profile and select a compatibility profile by setting a profile mask like so

set OSG_GL_CONTEXT_PROFILE_MASK=1

The context version and profile mask are also settable via the osg::DisplaySettings class in the OpenSceneGraph API.

Tips for VMware Users

Running osgEarth in a virtual machine environment can be tricky since they usually don’t have direct access to the graphics hardware by default. If you are having trouble you can try these tips.

First, build OSG and osgEarth for GL CORE profile (as above).

Next, assess the situation with a capabilities check:

osgearth_version --caps

The output will look something like this:

GPU Vendor:        WMware, Inc.
GPU Renderer       Gallium 0.3 on llvmpipe
GL/Driver Version: 1.2 Mesa 11.2.0

If is reports a Mesa driver, and the version is less than 3.3, you will need to configure a couple environment variables to move forward (Windows):

set OSG_GL_CONTEXT_VERSION=3.3
set MESA_GL_VERSION_OVERRIDE=3.3
osgearth_version --caps

Good luck!