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¶
- First, download the GL CORE include files from Khronos and place them somewhere on your system. We’ll call this the GLCORE folder.
- In CMake, set the
OPENGL_PROFILE
property to “GLCORE”. - 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 atC:\glcore\GL\glcorearb.h
you should set this property toC:\glcore
. - In CMake, set the following properties to
ON
:OSG_GL3_AVAILABLE
- 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
- Configure and build OpenSceneGraph.
Build osgEarth for GLCORE¶
Now that you have OSG built with GLCORE support, time to build osgEarth.
- In CMake, set the
OSGEARTH_GLCORE_INCLUDE_DIR
property to the same folder holding the Khronos include files (the same value of theGLCORE_GLCOREARB_HEADER
in your OSG build). - 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!