Repository navigation
Atmosphere Stars and Clouds
Every built-in backend can draw more than terrain and imagery: an atmosphere (the sky from the ground, the glow around the limb seen from space, and haze over the terrain), a star field the host supplies, a cloud shell from a coverage image the host supplies, a sea surface over the ocean floor, and contour lines. This page explains what each one does, what it needs from you (a sun direction, the Earth's rotation angle, a star catalogue, a cloud image, a geoid pack), and how to turn each on in the OpenGL, Direct3D 11 and Ogre backends. All of it belongs to the backends, not to the core: a host that draws through the render interface itself draws its own sky, and can reuse the shared shader code described at the end.
- Overview and quick reference
- Sun direction and lighting
- Atmosphere
- Stars
- Clouds
- Sea surface
- Contours and debug views
- Draw order and your own geometry
- The shared shader code
- Limits and pitfalls
Features are bits of vgl_draw_features (from vgl/render.h), set in each backend's draw settings. The data the features draw is set once on the backend.
| Feature | Bit | Needs | Set data with |
|---|---|---|---|
| Atmosphere | VGL_DRAW_FEATURE_ATMOSPHERE |
A view (the context's or the draw's); a sun direction (optional) | Nothing |
| Stars | VGL_DRAW_FEATURE_STARS |
A view, stars, the Earth rotation angle |
vgl_gl_backend_stars_set, vgl_d3d11_backend_stars_set, vgl::ogre::globe::stars_set
|
| Clouds | VGL_DRAW_FEATURE_CLOUDS |
The atmosphere bit too; a coverage image |
vgl_gl_backend_clouds_set, vgl_d3d11_backend_clouds_set, vgl::ogre::globe::clouds_set
|
| Sea surface | VGL_DRAW_FEATURE_SEA_SURFACE |
A geoid pack for mean sea level (else the ellipsoid) | A geoid pack in the context |
| Contours | VGL_DRAW_FEATURE_CONTOURS |
A geoid pack for heights above mean sea level (else above the ellipsoid) | Nothing |
Where the settings go:
| Setting | OpenGL (vgl_gl_draw_info) |
Direct3D 11 (vgl_d3d11_draw_info) |
Ogre (vgl::ogre::globe_settings) |
|---|---|---|---|
| Features | features |
features |
features |
| Sun | sun_direction |
sun_direction |
sun_direction |
| Star orientation | earth_rotation_angle |
earth_rotation_angle |
earth_rotation_angle |
| Cloud height |
cloud_height (0: 6000 m) |
cloud_height |
cloud_height |
| Contour interval |
contour_interval (0: 500 m) |
contour_interval |
contour_interval |
| Applied | Per vgl_gl_backend_draw call |
Per vgl_d3d11_backend_draw call |
From the next frame after settings_set
|
A complete setup, in C++ with the OpenGL backend (the other two take the same values):
// Once, after creating the backend:
static_cast<void>(backend->stars_set(my_stars)); // std::span<const vgl_star>
static_cast<void>(backend->clouds_set(coverage.data(), 4096, 2048)); // one byte per pixel
// Each frame:
auto draw = vgl::init<vgl_gl_draw_info>();
draw.features = VGL_DRAW_FEATURE_ATMOSPHERE | VGL_DRAW_FEATURE_STARS | VGL_DRAW_FEATURE_CLOUDS;
draw.sun_direction = sun_direction_ecef(unix_seconds);
draw.earth_rotation_angle = earth_rotation_angle(unix_seconds);
static_cast<void>(backend->draw(&draw));In C:
vgl_gl_backend_stars_set(backend, stars, star_count);
vgl_gl_backend_clouds_set(backend, coverage, 4096, 2048);
vgl_gl_draw_info draw = {0};
draw.struct_size = sizeof(draw);
draw.features = VGL_DRAW_FEATURE_ATMOSPHERE | VGL_DRAW_FEATURE_STARS | VGL_DRAW_FEATURE_CLOUDS;
draw.sun_direction = sun; /* vgl_dvec3, ECEF */
draw.earth_rotation_angle = angle; /* radians */
vgl_gl_backend_draw(backend, &draw);With Ogre:
static_cast<void>(globe->stars_set(my_stars));
static_cast<void>(globe->clouds_set(coverage.data(), 4096, 2048));
vgl::ogre::globe_settings settings;
settings.has_view_matrix = true;
settings.view_matrix = view_matrix;
settings.features = VGL_DRAW_FEATURE_ATMOSPHERE | VGL_DRAW_FEATURE_STARS | VGL_DRAW_FEATURE_CLOUDS;
settings.sun_direction = sun;
settings.earth_rotation_angle = angle;
static_cast<void>(globe->settings_set(settings));Unknown feature bits make a draw (or settings_set) fail with VGL_RESULT_INVALID_ARGUMENT, as do a non-finite earth_rotation_angle and a negative or non-finite cloud_height or contour_interval.
sun_direction is the direction towards the sun along the ECEF axes (x towards 0° latitude and longitude, y towards 90° E, z towards the north pole). It need not be normalized. The backends rotate it into camera space in double precision and light the terrain by the normal from each mesh's full-resolution samples.
sun_direction |
Without the atmosphere | With the atmosphere |
|---|---|---|
| Non-zero | Lit from the sun: 30 % ambient plus 70 % diffuse. The night side stays visible by the ambient light | Sunlight reddened and dimmed by its path through the air; ambient light fades through twilight to a little at night, so the night side goes dark; terminator and sunsets show |
| Zero | A headlight from the camera | The sun is placed straight above the camera, so the view is always in daylight |
vgl has no ephemeris. A simple approximation, good to about a degree, is what the samples use (samples/common/overlay.cpp): the declination from the day of the year, and the subsolar longitude from the time of day in UTC:
// day_of_year from 1 on 1 January; utc_hours from 0 to 24.
vgl_dvec3 sun_direction(int day_of_year, double utc_hours)
{
constexpr double pi = 3.14159265358979323846;
const double declination = -23.44 * pi / 180.0 * std::cos(2.0 * pi * (day_of_year + 10) / 365.0);
const double longitude = -15.0 * (utc_hours - 12.0) * pi / 180.0; // noon at 0° at 12:00 UTC
return {std::cos(declination) * std::cos(longitude),
std::cos(declination) * std::sin(longitude),
std::sin(declination)};
}For precise work, compute the sun's position with an astronomy library and convert it to ECEF.
VGL_DRAW_FEATURE_ATMOSPHERE draws, in one model shared by all backends:
- The sky seen from the ground: blue by day, red at sunset, dark at night, with a half-degree sun disc.
- The limb glow around the globe seen from space.
- Haze (aerial perspective) between the camera and the terrain, increasing with distance.
- Sunlight on the terrain reddened and dimmed by its path, and the night side left dark.
Model. Single scattering by air (Rayleigh) and haze (Mie) and absorption by ozone, with the Earth's coefficients and scale heights from Bruneton's and Hillaire's models, over a sphere (the ellipsoid becomes one when z is stretched by a / b, which moves heights by at most a third of a percent). The atmosphere is 100 km thick. Distances are in kilometres in a frame whose camera position is computed in double precision on the CPU (backends/common/atmosphere_view.hpp), so the shaders work with values near the camera.
Integration. Per pixel, without precomputed tables: 16 steps along a sky ray and 8 along the ray to the terrain, each with 6 steps of the sunlight's own path. It needs no textures or extra passes, and runs on WARP; its cost is in the fragment shader, so it is heavier at high resolutions and on small GPUs. Precomputed tables could replace the inner loops later if mobile devices need it.
Sky pass. After the tiles, one full-viewport triangle at the far depth with the depth test on and no depth writes, so it shows only where nothing was drawn. It blends as destination x T + L, with the transmittance T in its alpha, so what the framebuffer already holds there (the stars, or your space background) shows through where the sky is thin, as in space.
Display. Scattered light passes through an exponential curve (1 - exp(-c)) that keeps dim values and rolls bright ones off towards white; the lit terrain is left as it is, so imagery keeps its colours near the camera.
The atmosphere needs a view: the context's (vgl_context_view_set) or the draw's view_matrix. The OpenGL and Direct3D 11 sky passes also need the projection to be invertible (they invert it to find each pixel's ray).
VGL_DRAW_FEATURE_STARS draws a star field behind the sky, from stars you supply. vgl ships no star catalogue: none of the usual ones has terms an MIT library can take on with confidence (the Yale Bright Star Catalogue's are unclear, Hipparcos's are non-commercial, and those derived from them inherit both), so you choose a catalogue and its license, as you do your terrain and imagery.
typedef struct vgl_star
{
float direction[3]; /* unit vector, celestial frame of J2000: x towards the vernal
equinox, z towards the north celestial pole */
float magnitude; /* apparent visual magnitude: about -1.5 for Sirius, 6.5 the
faintest seen by eye */
float color[3]; /* linear RGB, 1 for the brightest channel */
float reserved; /* 0 */
} vgl_star;From right ascension α and declination δ (J2000): direction = (cos δ cos α, cos δ sin α, sin δ).
A set call validates every star and fails with VGL_RESULT_INVALID_ARGUMENT (logging the star's index) if a direction is not of unit length (within 1e-3), a value is not finite, a colour channel is outside [0, 1], or reserved is not 0. At most VGL_STAR_COUNT_MAX (400,000) stars are taken. The stars are copied (expanded to six vertices each on the CPU) and kept, so they survive a device reset; pass null and 0 to remove them. Set them on the render thread.
Each star is a small quad of two triangles, not a point (whose size not every API can set), placed at the star's direction and widened in pixels from the viewport's size: 1.2 to 2.6 pixels in radius with brightness, which follows the square root of the flux (10^(-0.4 m)) so that faint stars stay visible on a display. The quads draw after the tiles and before the sky, at the far depth, without depth writes, added to the framebuffer. With the atmosphere, each star fades with the sky's brightness in its direction and the sky pass dims what shows by the transmittance: stars disappear by day, come out through twilight, and shine fully from space. Without the atmosphere, they are always visible.
Stars are fixed in the celestial frame; the Earth turns under them. Pass the Earth rotation angle in radians as earth_rotation_angle, from vgl_earth_rotation_angle_get (Geodesy and Tiling), which takes a Julian date in UT1 (UTC is within a second of it) and implements the IAU 2000 definition, without precession and nutation (a fraction of a degree over decades):
#include <vgl/geodesy.h>
/* Unix time (seconds since 1970-01-01 00:00 UTC) to a Julian date, then the angle. */
double julian_date = 2440587.5 + (double)unix_seconds / 86400.0;
double angle = 0.0;
vgl_earth_rotation_angle_get(julian_date, &angle);
draw_info.earth_rotation_angle = angle;In C++: vgl::expected<double> angle = vgl::earth_rotation_angle_get(julian_date);.
The samples (samples/common/stars.cpp) offer two sources:
- Generated (the default): a deterministic random sky with about the real sky's number of stars per magnitude down to 6.5 (about 8,800), coloured from blue-white to orange, denser towards a Milky Way band, but not the real constellations. It is the same on every platform.
-
The Yale Bright Star Catalogue, 5th revised edition, with
--stars <file>: the filecatalogof CDS catalogue V/50 (https://cdsarc.cds.unistra.fr/ftp/V/50/catalog.gz, decompressed), which you download yourself; the repository does not hold it. The sample reads the J2000 positions (columns 76 to 90), the visual magnitude (103 to 107) and the B-V colour index (110 to 114), and converts B-V to a colour through the star's temperature and a blackbody's colour.
curl -O https://cdsarc.cds.unistra.fr/ftp/V/50/catalog.gz
gunzip catalog.gz
vgl-gl --stars catalogCheck the terms of any catalogue before you ship its data in your product.
VGL_DRAW_FEATURE_CLOUDS, together with VGL_DRAW_FEATURE_ATMOSPHERE, draws a thin cloud shell at cloud_height above the ellipsoid (VGL_CLOUD_HEIGHT_DEFAULT, 6000 m, when 0), from a coverage image of the whole globe.
| Property | Requirement |
|---|---|
| Pixels | One byte each, 0 clear to 255 overcast, rows tightly packed |
| Projection | Latitude and longitude (equirectangular): row 0 at 90° N, column 0 at 180° W, each pixel an equal step, as in NASA's cloud composites |
| Width |
VGL_CLOUD_IMAGE_SIZE_MIN (2) to VGL_CLOUD_IMAGE_WIDTH_MAX (16,384) |
| Height | 2 to VGL_CLOUD_IMAGE_HEIGHT_MAX (8,192) |
The image is copied, with mip levels built once on the CPU (backends/common/clouds.hpp), kept for device resets, and uploaded when first drawn. Pass null with 0 x 0 to remove it. Clouds are static: time-varying data is a non-goal of vgl.
The samples load samples/data/clouds.jpg (NASA's Blue Marble cloud composite of 2002, 4096 x 2048, grey) with stb_image, as one channel:
#include <stb_image.h>
int width = 0, height = 0, channels = 0;
stbi_uc* pixels = stbi_load("clouds.jpg", &width, &height, &channels, 1); // force 1 channel
if (pixels != nullptr)
{
static_cast<void>(backend->clouds_set(pixels, static_cast<std::uint32_t>(width),
static_cast<std::uint32_t>(height)));
stbi_image_free(pixels); // the backend keeps its own copy
}Its ice sheets over Antarctica and Greenland show as cloud. Credit: "NASA Earth Observatory, Blue Marble: Clouds (Reto Stöckli)" (Attribution and Licensing).
- No geometry. The shared shader code finds where each view ray meets a sphere at the cloud height. The terrain shader blends clouds over the terrain where the ray crosses the shell before the ground (seen from orbit or an aircraft); the sky shader draws them where the ray meets the shell from below, overhead, or along the limb from space, where they also hide the stars.
- No seam. The level of detail comes from how the shell point moves across the screen, not from the texture coordinates, which jump at 180°.
- Opacity. Coverage becomes opacity through a smooth step: clear where the image is dark, as over the sea, opaque where it is white.
- Light and shadow. Lit by the same sunlight as the terrain, reddened at sunset and dark at night, darker from below the thicker they are, hazed by the air in front, and casting shadows on the terrain where the sunlight crosses the shell.
VGL_DRAW_FEATURE_SEA_SURFACE gives a flat sea for applications that do not want the ocean floor: terrain below mean sea level is raised to it in the vertex shader and shaded as water (the imagery's ocean colour where there is imagery, a deep blue otherwise), with a glint of the sun and the atmosphere's sunlight when that is on. Mean sea level is the geoid, which reaches the backends as the geoid's height at each tile's corners (vgl_draw_item.geoid_heights), so add a geoid pack to the context (the sample set's packs/egm2008, or one you bake with the Baker). Without one, sea level is the ellipsoid, up to about 100 m off. Skirts are raised only as far as the tile's lowest point and shaded as land, so they still cover cracks. It works with or without the atmosphere.
VGL_DRAW_FEATURE_CONTOURS draws contour lines every contour_interval metres above mean sea level (500 m when 0), every fifth heavier, a pixel wide at every distance, fading where they crowd. The samples set the interval from the altitude.
The debug views (vgl_debug_view bits in debug_views: wireframe, level colours, imagery source, height colours) combine with every feature; see Render Interface. In the interactive samples: F6 height colours, F7 contours, F8 sea surface, F9 atmosphere, L sunlight or headlight; the stars and clouds start on, and their toggles and the time of day are in the panel.
The backends draw, in order: the tiles (with haze and cloud cover applied in their shader), the stars, then the sky. Stars and sky draw only where the depth buffer still holds the far depth, so:
- Draw an opaque background you want behind everything (a space skybox) before the globe, without writing depth: the stars are added to it and the sky blends over it, letting it show through in space.
- Opaque host geometry drawn with the same depth convention keeps the sky and stars out, wherever you draw it relative to the globe. It does not receive haze: the atmosphere applies only to the globe's terrain.
- Geometry that writes no depth and should appear in front of the sky (transparent effects) goes after the globe; in Ogre, in a render queue group after
RENDER_QUEUE_SKIES_LATE, where the sky is drawn (the stars are in the group before it).
All three backends share one implementation, so the sky looks the same everywhere:
| File | Contents |
|---|---|
| backends/common/atmosphere.glsl | Scattering (vgl_atmosphere), sunlight transmittance (vgl_sun_transmittance), daylight, exposure (vgl_expose), star visibility, and the clouds' ray intersection, coordinates, level of detail, opacity, light and shadow. Written in the part of GLSL that HLSL shares once vec2/vec3/vec4/mix are defined as float2/float3/float4/lerp and VGL_CONST as static const
|
| backends/common/atmosphere_view.hpp | The CPU side, in double precision: camera space to the atmosphere's frame, the camera's position and height, the sun's direction, the sun fallback above the camera |
| backends/common/stars.hpp | Star validation, the quad per star, brightness and radius from magnitude, the celestial-to-camera rotation |
| backends/common/clouds.hpp | Cloud image limits and the mip chain |
The OpenGL backend includes atmosphere.glsl as it is (CMake turns it into a C++ string at configure time), the Direct3D 11 backend #includes it in its HLSL for fxc, and the Ogre backend inserts it into its unified shaders with Ogre's definitions. A custom renderer can use the same files; they are MIT like the rest of vgl, but internal, not installed API.
- Clouds without the atmosphere draw nothing. Set both bits.
-
Stars without
earth_rotation_angleare drawn for angle 0, so the sky does not match the time. - Zero sun with the atmosphere puts the sun above the camera: always daylight. Pass a real direction for day and night.
- No view, no sky. Without a view (context or draw), the atmosphere and stars are skipped.
- One thin cloud shell. It looks flat from inside, and its detail is the image's (about 10 km per pixel for the samples' image).
- Cost. The atmosphere is computed per pixel; profile on your target hardware, especially mobile and integrated GPUs.
- Colour space. Output is display-encoded; draw into a unorm target, not one with sRGB conversion (OpenGL, Direct3D 11).
OpenGL Backend, Direct3D 11 Backend, Ogre Backend, Render Interface, Geodesy and Tiling, Samples, Attribution and Licensing, and the design document's sections on the atmosphere, clouds and stars (section 7.6).
Getting vgl
Using the library
Rendering
Data
Reference
Specifications