Home

vgl (Virtual Globe Library)

vgl is a lightweight, open-source C++ library for rendering a virtual globe inside an existing application, behind a C API. It streams level-of-detail terrain and imagery on the WGS84 ellipsoid and draws it through backends for OpenGL / OpenGL ES, Direct3D 11 and Ogre, on Windows, Linux, macOS, Android, iOS and in web browsers. This wiki is the integrator's guide: how to build vgl, embed it in an application, bake data for it and serve that data.

Status: vgl 1.0 is released (release notes). The C ABI stays compatible within major version 1; the changelog lists every change.

Where to start

• New to vgl? Read Getting started, then Core concepts.
• Embedding vgl in an engine with its own renderer? Read the Render interface.
• Preparing your own terrain or imagery? Read Baker, then Hosting packs.

Contents

Getting vgl

• Getting started: from a clone to a globe on screen
• Building vgl: presets, CMake options and dependencies
• Installing vgl: vcpkg, Conan, release archives, CMake and pkg-config
• Web builds: Emscripten and WebGL 2
• Mobile platforms: Android and iOS

Using the library

• Core concepts: architecture, coordinates, depth, budgets and threading
• Context API: packs, layers, views, queries, statistics and attribution
• Host interfaces: allocators, logging, I/O and tasks
• Defaults module: thread pool, file and HTTP readers, disk cache
• C++ wrapper: the header-only C++ API
• Geodesy and tiling: coordinate conversions and the tiling scheme

Rendering

• Render interface: writing your own backend on the core
• OpenGL backend: OpenGL 3.3, OpenGL ES 3.0 and WebGL 2
• Direct3D 11 backend
• Ogre backend: Ogre 14
• Atmosphere, stars and clouds

Data

• Baker: building and running vgl-bake
• Pack format overview
• Hosting packs: local disk, object stores and public endpoints
• Reference server: the Caddy configuration

Reference

• Samples
• Troubleshooting
• Attribution and licensing

Specifications

The specifications live in the repository, next to the code they describe, and are the source of truth. The wiki summarizes them and links to them.

• Design document: requirements, architecture and decisions
• C API conventions
• Render interface
• Pack format
• Hosting packs
• Packaging: vcpkg, Conan and the release archives

Editing this wiki

The wiki is a git repository of Markdown pages, checked out in the main repository as the wiki submodule. To edit it locally:

git submodule update --init wiki
cd wiki
git switch master
# edit or add pages: Page-Name.md becomes the page "Page Name"
git commit -s -m "Describe the change"
git push

Then record the new wiki revision in the main repository with git add wiki and a commit. Pages edited on GitHub land in the same repository; git -C wiki pull brings them in.