Byte Engine Docs

Rendering

Look up the objects a scene is made of, the camera, the pipeline and pass model with every pass and its settings, the visibility pipeline's limits and material contract, and the render targets a frame produces.

The renderer draws each window from a scene pipeline followed by post-scene passes. This page specifies the objects an application creates, the camera, how pipelines and passes compose, every pass the engine ships with, and the contract of the visibility pipeline. The design notes behind it are under Rendering in Contribute, and the lights are in the lighting reference.

Objects

ObjectRole
WindowA named render surface with an extent and optional decorations, with one camera attached. Each window becomes one sink, numbered in creation order.
CameraView settings created on the world with a transform, which the renderer follows.
SinkThe per-frame destination the renderer builds from a window's extent and camera: the view, the extent, the exposure scale, and the frame interval.
ViewProjection and view matrices with near, far, vertical field of view, and aspect ratio, perspective or orthographic.
Renderable meshAn entity's geometry: a baked mesh by ID, a generated mesh, a sphere, or a box. A generated mesh may name its material; otherwise it takes the pipeline's default.
EnvironmentA baked environment map, optionally scaled to deliver a given illuminance. Without one, the visibility pipeline uses an opaque black fallback.
Fog, lights, particle emittersSpecified with their own pages: Light a scene, lighting, particles. The newest fog wins.
Debug meshA retained wireframe sphere, box, capsule, segment, or circle with a color, tested against scene depth or drawn over it.

Scene color is linear HDR in the packed RGBu11u11u10 format. Tone-mapping passes write 16-bit float display color. The window's swapchain is BGRAsRGB.

Camera

FieldDefaultRule
Field of view45°Vertical, in degrees, above 0 and below 180.
Exposure0 stopsThe exposure scale is 2 to the power of the stops, within ±64.
Near and far planes0.1 and 100Fixed.
ProjectionPerspectiveSinks always use a perspective view.
Aspect ratio, aperture, focus distanceStored but not read; the aspect ratio comes from the window's extent.

The camera's position and orientation come from its transform. Up is +Y, unless the view direction is within 1 percent of vertical, when +Z is used.

Pipelines and passes

ConceptRole
Scene pipelineOwns scene state and per-sink resources and records one command per sink per frame. Several can be registered; the default setup registers the visibility pipeline and particles.
Render passSink-local post-processing that reads main and usually replaces it. Registered for every sink.
Scene backgroundA pass the scene pipeline records after opaque and before transparent surfaces, such as the sky. A later registration replaces an earlier one.
Pass stateEnabled or bypassed, shared by name across sinks, set in code or by the render.pass.<name> parameter. A bypassed pass that replaced main has main forwarded in its place.
RuleValue
RegistrationPost-scene passes and the scene background are registered before the first window.
Order per sinkEvery scene pipeline in registration order, then every post-scene pass in registration order, then a copy to the swapchain only when no post-scene pass exists.
Terminal passThe last post-scene pass must create the main render target, which is the swapchain.
TargetsA pass declares named, sink-scoped targets: full-size, scaled by a divisor, persistent, or history targets whose previous frame can be read. Reading a target that nothing creates fails at setup.
ClearsA node that records nothing has its first-use targets cleared; one that records has them discarded.
Frame-wide workDetail levels, shadow views, and exposure follow the first sink.
SwapchainFIFO presentation with 2 frames in flight.

Passes

PassNameWritesPlace it
Simple scene pipelinePipelineManagermain, depthAs the scene pipeline, for prototyping.
Visibility scene pipelineVisibilityPipelineManagermain, depth, primitive and instance IDsBefore the deferred tasks thread starts.
ParticlesParticleManagermainAfter the scene pipeline, before the deferred tasks thread starts.
Atmosphere skyatmosphere skyThe scene color where depth is 0As the scene background. Black when bypassed or without a directional light.
Height fogexponential-height-fogExponential Height FogAfter the scene and particles, before lens flare, bloom, and tone mapping.
Motion blurmotion-blurMotion BlurAfter scene light and fog, before lens flare, bloom, and tone mapping.
Lens flarelens-flareLens Flare OutputBefore bloom and tone mapping.
BloombloomBloom OutputAfter everything that writes scene light, before tone mapping.
AntialiasingsmaaSMAA Output, SMAA EdgesAfter the main to filter, before sharp overlays.
AgX, ACES, and sRGB displayagx, aces, srgb-displayTheir named outputsAs the tone mapper, before creating a window. The sRGB display pass needs float input and suits SDR scenes without a tone mapper.
Color gradinglut, aces-color-grading, dwg-color-gradingTheir named outputsAfter scene-linear effects, before tone mapping.
UIuiUIBefore the renders every sink must see are published.
Debug meshesdebug-meshesDebug MeshesAfter tone mapping and the overlays it should cover, before the first window.

A pass's scene.<name> or pass.<name> metric and its render.pass.<name> parameter use the name in this table. The default setup installs the visibility pipeline, particles, and a 1920 by 1080 window, and no post-scene pass, so the scene reaches the swapchain through the copy.

Pass settings

PassSettings and defaults
BloomThreshold 1, soft knee 0.5, intensity 0.08, maximum brightness 64, radius 1, 5 levels of 1 to 6.
Motion blurShutter 8,333 µs, maximum blur radius 32 pixels, 8 taps of 1 to 32. It blurs camera turns and zooms only, by the shutter's share of the frame interval.
Lens flareThreshold 1, soft knee 0.5, maximum brightness 64, intensity 0.05, 4 ghosts of 1 to 8, ghost spacing 0.35, halo width 0.45, halo intensity 0.5, chromatic distortion 0.004, a blue tint, squeeze 1.
Height fogA layer's height falloff 0.2 and base height 0; a fog's albedo white, maximum opacity 1, anisotropy 0.7 within 0 to 1, ambient illuminance 0 lux.
Atmosphere skyEarth's radii and scale heights, Mie anisotropy 0.76, ozone strength 1, ground albedo 0.3, the sun disk capped at 32,768 per channel; not settable through the setup function.
Antialiasing, tone mapping, UI, debug meshesNo settings.

Rendering on demand, set by the render-on-demand parameter, renders a frame only when a window, camera, or pass state changed, a pass asked for one, or a screenshot is pending. Scene changes don't count, so an application that moves cameras or objects requests a redraw itself.

The visibility pipeline

LimitValue
Geometry capacitySet by the render.geometry.* parameters; a mesh that doesn't fit is rejected at upload.
Meshlet64 vertices and 126 triangles
Meshlets per primitive instance4,096
Instances drawn per frame1,024
Materials, bindless textures1,024 each
Texture slots per material16
Lights1,024; the rest are left out with one warning
Shadowed lights4 directional with 4 cascades each, 16 cone, 16 point
Light clusters16 by 8 by 24

A renderable is drawn only once its mesh, every material, and every texture are resident.

A skinned primitive instance that receives a pose takes its own vertices out of the geometry vertex capacity, as many as its primitive has, for as long as it keeps receiving poses. It gives them back when it's removed. When the capacity can't hold them, the instance draws in its bind pose and the pipeline logs one error for it.

Detail level ruleValue
Allowed errorOne pixel times render.lod.bias, converted to world units from the first sink's projection.
Instance errorThe level's error per distance times the straight-line distance from the camera to the nearest point of the bounding sphere, plus its constant error, divided by the largest model axis. Turning the camera never switches levels.
ChoiceThe coarsest level whose error is within the allowed error; the finest otherwise. An instance around the camera, with zero scale, or without a finite error draws full detail.
ShadowsDraw the same level as the camera.
Directional shadow ruleValue
CascadesFour, splitting the range from the camera to render.directional-shadows.distance by the split blend between logarithmic and even.
FittingWith receivers fitting, each cascade shrinks to the surfaces the camera sees, after two small depth passes. With frustum fitting, it covers the whole slice without them.
StabilityEach cascade is the smallest light-space square around its slice, padded by 17 texels, rounded in 8 steps per doubling, and snapped to a world-fixed texel grid. Casters start 100 m toward the light.
Beyond the last cascadeNo sun shadow.

Shadow maps

Every shadow-casting light draws from one memory budget, render.shadow-maps.budget-mb, 128 MiB by default:

LightShadow mapCost
The first directional lightFour cascades of 2,048 texels per side by default, 16-bit depth32 MiB at the default resolution
A cone lightOne map of its size class, 16-bit depth32 KiB to 8 MiB
A point lightA cube map of six faces of its size class, 16-bit depth192 KiB to 48 MiB

A cone map or point cube face takes one of five sizes, its size class:

Size classTexels per sideCone mapPoint cube map
012832 KiB192 KiB
1256128 KiB768 KiB
2512512 KiB3 MiB
31,0242 MiB12 MiB
42,0488 MiB48 MiB

A light's span is its shadow range's projected diameter, in pixels, in the sink where it looks largest. A light whose range contains a sink's camera spans that sink's larger side. A cone light needs the span in texels per side, and a point light half the span. The light takes the smallest class with at least that many texels, up to class 4. A light moves to a larger class as soon as it needs one, and to a smaller class only once it needs fewer than three quarters of that class's texels.

The first directional light is placed first, then cone and point lights in order of the screen area they cover, each at the cost of its size class, then any other directional lights. A light that doesn't fit stays lit without shadows, with one warning in the log. At most 4 directional, 16 cone, and 16 point lights hold shadow maps at once.

Shadow map updates

A shadow map isn't drawn again every frame. Each frame draws a set of updates chosen within an update budget, render.shadow-maps.update-texels, 16,777,216 texels by default. One update draws one of these:

UpdateTexels
One cascade of a directional lightThe cascade resolution squared, 4,194,304 at 2,048 texels per side
One cone mapIts size class's texels per side squared
One face of a point light's cube mapIts size class's texels per side squared

Every frame draws cascades 0 and 1 of every shadowed directional light. Their texels count against the budget first, even when they exceed it. Every other update is a candidate: cascades 2 and 3, cone maps, and point cube faces.

Candidates are ordered in three tiers:

  1. Maps that haven't been drawn yet.
  2. Maps whose view changed since they were drawn: the light moved, turned, or changed its shadow range, or, for a cascade, the camera or the sun moved it.
  3. Every other map.

Within a tier, candidates are ordered by age times importance, highest first. Age is the number of frames since the map was drawn. Importance is the largest number of sink pixels the light's shadow range covers in any sink, and for a cascade, the pixel count of the largest sink. Candidates draw in that order while their texels fit in what's left of the budget. A candidate that doesn't fit is skipped, and later candidates can still draw. When no candidate fits, the first one draws anyway.

Until a map has been drawn, its light is lit without that shadow. A map that isn't drawn this frame keeps the view it was drawn with, and receivers sample it with that view. A receiver outside a cascade's drawn square uses the next coarser cascade that covers it, and gets no shadow from that light when none does. A new map, a map in a new size class, and every map of an image that changed size count as not yet drawn.

A light keeps its map, at the same place in its class's image, for as long as it stays selected in the same size class. A light that changes class gets a new map. The image of each class grows when the class needs more maps than it holds, and shrinks only when the budget needs its memory. An image that changes size loses every map it holds.

Materials

The pipeline accepts a material whose render model is Visibility with the MaterialEvaluation pass, which is what every .bema file and imported model bakes to, and whose first shader is its evaluation shader. The evaluation shader is generated from the material's BEMX graph.

RuleValue
Alpha modeOpaque, masked with a cutoff, or blended. Blended materials draw in the transparent phase.
Double-sidedDraws without back-face culling.
VariablesPrograms that differ only in textures or dynamic values share one pipeline and one dispatch; each distinct set of static scalar and vector values takes its own. Texture variables take slots in declaration order, up to 16. Dynamic values number at most 16384 in all, counting every loaded material's and every entity's own.
Layout layersEvery material builds on the scene records, scene, visibility buffer, and material evaluation layers.

The evaluation shader writes the graph's surface into these properties. A surface input the graph leaves out takes its BEMX default, and a graph without a normal keeps the geometric one:

PropertyTypeDefault
albedoFour half floats: the base colour, then the opacity, which is alpha in the transparent phase0.8, 0.8, 0.8, 1
normalThree half floats in tangent space0, 0, 1, meaning no normal map
metalnessHalf float0
roughnessHalf float0.5
occlusionHalf float, multiplying indirect diffuse light1
emissionThree half floats, added to the diffuse light0, 0, 0

The surface's world-space normal is converted to the tangent frame. A BEMX image node samples its texture at the vertex UV with the derivatives the pipeline computed. Writing a normal or reading the tangent or bitangent makes the pipeline build the tangent frame for that material, and sampling a texture or reading texture coordinates makes it reconstruct the UV.

Stages and targets

Each sink records these stages in order, and each reports a stage.<name> metric when it runs: skinning, shadow-maps, shadow-depth-pyramid, light-clusters, visibility-early, occlusion-pyramid, visibility-late, material-prepasses, depth-pyramid, cascade-fit, screen-space, material-evaluation, background, and transparent.

TargetContent
Lit, aliased mainScene color, full size.
Depth, aliased depthReversed depth, full size.
primitive index, instance_id32-bit IDs per pixel.
Sun Visibility, Contact Shadow TraceSun visibility per shadow slot, full size, and its half-size contact trace.
SSGI Raw, SSGI Normals, SSGI History, Diffuse Radiance HistoryHalf-size indirect lighting and its history.
Radiance HistoryThe previous frame's radiance, for reflections.

These names, with a pass's outputs, select a screenshot through the inspector; history targets can also be read from the previous frame.

Rust API

On this page