Participating media and atmosphere¶
A VolumeSystem medium describes homogeneous optical properties. An instance places that medium in a scene with bounds and mobility. Distances are metres, and the coefficients of absorption and scattering are inverse metres. Emission is a source per metre. Phase anisotropy is the mean scattering cosine.
Place and retire a fog volume¶
This excerpt creates a reusable medium and a sphere placement. It includes cleanup for a failed placement and shows the resource order for removal.
#include <Renderer/Runtime/RendererRuntime.h>
namespace SnAPI::Renderer::Docs
{
struct FogPlacement
{
VolumeMediumHandle Medium;
VolumeInstanceHandle Instance;
};
TResult<FogPlacement> PlaceFog(RendererRuntime& runtime, RenderScene& scene)
{
auto medium = runtime.Volumes().CreateMedium({
.AbsorptionPerMetre = {0.002f, 0.002f, 0.002f},
.ScatteringPerMetre = {0.018f, 0.018f, 0.018f},
.PhaseAnisotropy = 0.3f,
});
if (medium.Failed())
{
return medium.Error();
}
auto placed = scene.CreateVolume({
.Medium = medium.Value(),
.Bounds = {.Shape = VolumeBounds::EShape::Sphere, .OuterRadiusMetres = 3.0},
});
if (placed.Failed())
{
auto destroyed = runtime.Volumes().DestroyMedium(medium.Value());
if (destroyed.Failed())
{
return destroyed.Error();
}
return placed.Error();
}
return FogPlacement{medium.Value(), placed.Value()};
}
TResult<void> RemoveFog(RendererRuntime& runtime, RenderScene& scene, FogPlacement fog)
{
// An instance references its medium. Retire the placement first.
if (auto removed = scene.DestroyVolume(fog.Instance); removed.Failed())
{
return removed.Error();
}
return runtime.Volumes().DestroyMedium(fog.Medium);
}
}
The active graph must contain a volume integration pass. The stock OpenPBR raster composition has an optional homogeneous transport branch with an explicit metric trace distance. A scene volume alone does not enable that branch. Volume lighting and scene shadow visibility depend on the actual supplied inputs and pass variant.
Design scope¶
World atmosphere/aerial perspective and bounded participating media can both contribute along a view ray. Atmosphere uses its own LUT-backed composition. The volume design calls for arbitrary-density media, volumetric lighting across eligible lights, volume self-shadowing and shadow casting, and planetary cloud shells with a continuous ground-to-space transition. The homogeneous public API and supplied raster integration do not provide all of those capabilities. Keep custom density and cloud experiments behind their own pass contracts until their integration is available.