vgl (Virtual Globe Library)
vgl is a lightweight, open-source C++ library for rendering a virtual globe inside an existing
application. 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
and iOS, and in web browsers on WebGL 2. The public interface is a C API, so the library embeds as
easily in a C code base as in a C++ one.
Status: version 1.0. The C ABI stays compatible within major version 1
(C API conventions, section 14). The Ogre backend covers OpenGL 3+ and
Direct3D 11 on Windows and Linux; Ogre on Vulkan, macOS and mobile follows
(changelog, Known limitations).
Goals
- Render a globe inside your application. The host owns the window, main loop, camera and
render target. vgl draws into the host's current render pass and never presents, swaps buffers
or clears the render target.
- C first. The stable ABI is a C API of opaque handles and result codes. A header-only C++
wrapper adds RAII, spans and enum classes on top of it, without a second ABI.
- Small and predictable. Minimal runtime dependencies (stb_image, Zstandard), no global
state, no threads or network connections created by the library, all allocations routable
through host allocator callbacks, and CPU and GPU memory bounded by budgets you set.
- Several renderers, one core. A renderer-independent core feeds backends for OpenGL 3.3 /
OpenGL ES 3.0, Direct3D 11 and classic Ogre (1.x). A host with its own renderer can use the core alone.
- Portable. The runtime uses only the C and C++ standard libraries, with files, threads and
network left to the host, so it runs the same on desktop and mobile. The baker runs on Windows
and Linux.
- Precise from orbit to the ground. Double-precision CPU geometry, tile-relative vertices and
reversed-Z (or logarithmic) depth, so there is no jitter or z-fighting at any distance.
- Offline data pipeline. A bundled baking tool turns free global datasets (Copernicus DEM,
GEBCO) and your own imagery into sharded, range-readable tile packs. The runtime reads them
from local disk or from any web server that supports HTTP range requests, such as an object
store or the reference server configuration for Caddy (hosting guide). A
disk cache keeps what was read, so that areas seen once load again offline.
- In the browser too. An Emscripten build runs the OpenGL sample on WebGL 2, with threads,
streaming packs from any server that allows it (web sample).
- Easy to extend. Backends, data providers, decoders, task scheduling, I/O, allocators and
logging are all public interfaces. The built-in implementations use the same interfaces.
Non-goals
These are out of scope for the first releases, and the architecture is not shaped around them:
- 3D Tiles and glTF streaming
- Text and label rendering
- Vector tile styling
- Time-dynamic data
- Clients for online services (Cesium ion, Google, Bing)
- General map reprojection at runtime
- An HTTP stack in the core (the host supplies I/O through a callback; the optional defaults
module has an HTTP reader on libcurl)
- Direct3D 12, and OpenGL ES 2.0
Quickstart
Try the live demo in a browser first, or browse the
project site and its API reference.
The integrator's guide covers each step in detail, starting
with Getting started.
1. Get vgl. Download a release archive from
GitHub releases and point CMAKE_PREFIX_PATH at it,
use the vcpkg port or the Conan recipe (packaging), or build from source
(below).
2. See it run. Build with a workflow preset and start the OpenGL sample on the sample data:
cmake --workflow --preset linux-gcc-static-release # or windows-msvc-static-release, macos-clang-static-release
build/linux-gcc-static/bin/Release/vgl-gl
3. Link it.
find_package(vgl 1 REQUIRED)
target_link_libraries(my_app PRIVATE vgl::vgl vgl::defaults vgl::gl)
4. Draw a globe. Your application keeps its window, loop and camera:
- Create a thread pool and a file reader (
vgl_thread_pool_create, vgl_file_reader_create)
and pass their task and I/O interfaces to vgl_context_create.
- Add packs with
vgl_pack_create: elevation, the geoid and imagery, such as those in
samples/data/packs. Bake your own with vgl-bake (baker) and
serve them from disk or any web server (hosting).
- Create a backend on your device, for example
vgl_gl_backend_create with your OpenGL
function loader.
- Every frame:
vgl_context_view_set with your camera, vgl_context_update, then the
backend's draw (vgl_gl_backend_draw) inside your render pass. Show the lines of
vgl_context_attribution_get while their data is in view.
- Destroy the backend, packs and context, then the reader and the pool.
Building
vgl uses CMake 3.24 or later and a C++20 compiler.
cmake -S . -B build
cmake --build build
ctest --test-dir build
以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗
