Documentation · 3D Guide
Glossary
Every term the rest of the documentation uses, in plain words. The reference links here: a word you have not met in a type's description is a link, and it lands on the entry for it. Each entry says what the thing is, what it is called in this API, and which chapter teaches it properly.
Geometry
Vertex
A corner of a triangle. It always has a position, and it usually carries more: a normal saying which way the surface faces there, UVs saying where in a texture it sits, sometimes a tangent. Everything a shader knows about the middle of a triangle is these values, blended between its three corners.
In Ava3D: Mesh.Positions, Mesh.Normals, Mesh.TexCoords · chapter 1
Triangle
The only shape a graphics card draws. Three points, always flat and always convex, which is what makes them cheap to fill in and easy to do a million of at once. Every curved surface you see is an approximation made of them.
In Ava3D: Mesh.TriangleCount · chapter 1
Mesh
A shape: a list of vertices and a list of indices saying which of them form each triangle. A mesh has no position — it sits around the origin and can be drawn in fifty places at once, which is why placing it is a node's job.
In Ava3D: Mesh, Primitives · chapter 1
Indices, index buffer
Whole numbers that point into the vertex list, three per triangle. They exist because corners are shared: a cube has eight of them but thirty-six corner slots, so the positions are stored once and named many times.
In Ava3D: Mesh.Indices · chapter 1
Winding order
Which way round a triangle's three indices are listed, and therefore which of its two sides is the front. The convention here — and in glTF, and in OpenGL — is counter-clockwise seen from outside. It is invisible until culling is on, and then a mesh wound the other way renders inside out.
In Ava3D: every shape in Primitives · chapter 1
Normal
A unit direction saying which way a surface faces at a point. Lighting is almost entirely a comparison between the normal, the direction to the light and the direction to the eye. Stored per vertex and blended across the triangle, which is what lets flat pieces shade like a curve.
In Ava3D: Mesh.Normals, Mesh.WithGeneratedNormals() · chapter 5
Tangent
A second direction per vertex, lying along the surface, that says which way is "right" across it. A normal map stores its directions relative to the surface, so without a tangent there is no way to know how to orient them. Most exporters omit tangents, so they are usually derived from the UVs.
In Ava3D: Mesh.Tangents, Mesh.WithGeneratedTangents() · chapter 5
UV coordinates
Two numbers per vertex saying where in a texture image that corner sits — u across, v down, both usually 0 to 1. They are how a flat picture is wrapped onto a three-dimensional shape, and they are decided by whoever made the model.
In Ava3D: Mesh.TexCoords, TextureWrap · chapter 5
Bounding box
The smallest axis-aligned box containing something. Testing against a box is far cheaper than testing against the geometry inside it, so it is the first question asked when framing a scene or working out what the pointer is over.
In Ava3D: BoundingBox, Node.Bounds, Node.WorldBounds · chapter 2
Space and movement
Matrix
A 4×4 grid of numbers holding a move, a turn and a scale all at once, so that applying all three to a point is one operation. Multiplying two matrices gives the matrix that does both — which is how a hierarchy of transforms collapses into one number per vertex per frame.
In Ava3D: Node.LocalTransform, Node.WorldTransform · chapter 2
Transform
Where something is, which way it is turned, and how big it is. Applied in that order — scale, then rotate, then translate — because doing it the other way swings an object around the origin instead of turning it where it stands.
In Ava3D: Node.Position, Node.Rotation, Node.Scale · chapter 2
Scene graph
A tree of nodes where each child's transform is relative to its parent, so moving the parent moves everything under it. It is what makes a wheel stay on a car without the wheel knowing where the car is.
Local space, world space
A node's own position is measured relative to its parent — local space. World space is what everything is finally measured in, once every parent's transform has been applied. Two nodes at the same local position under different parents are nowhere near each other.
In Ava3D: Node.Position versus Node.WorldPosition · chapter 2
Quaternion
Four numbers that hold a rotation. Any orientation, however you arrived at it, is the same as one turn about one axis; a quaternion is that axis and that angle, encoded so that combining two is a single multiply and blending between two is a smooth arc. You build them from axes and directions and never read the components.
Euler angles
A rotation described as three separate turns — pitch, yaw and roll. Easy to picture, and three problems in a trench coat: the order changes the answer, two axes can collide (gimbal lock), and halfway between two sets of angles is rarely halfway between the two orientations.
In Ava3D: Node.RotationDegrees · chapter 4
Gimbal lock
What happens when two of the three Euler axes line up — pitch straight up, and yaw and roll become the same turn. A whole degree of freedom disappears and no combination of the three gets it back. It is why this camera's pitch is clamped to ±89° rather than ±90°.
The camera
View matrix
The transform that rearranges the whole world so the camera sits at the origin looking down −Z. There is no camera object inside a graphics card; moving the camera and moving the world are the same arithmetic.
In Ava3D: Camera.View · chapter 3
Projection
The step that flattens three dimensions into the rectangle on your screen, making distant things smaller. Perspective projection is the one that looks like a photograph; the alternative, orthographic, keeps parallel lines parallel and is what CAD drawings use.
In Ava3D: Camera.GetProjection(aspect) · chapter 3
Frustum
The wedge of space a camera can actually see: bounded by the edges of the screen, and cut off at both ends by the near and far planes. Anything outside it is clipped away before it costs anything.
In Ava3D: implied by FieldOfView, NearPlane, FarPlane · chapter 3
Field of view
How wide an angle the camera takes in, vertically, in degrees. The same choice as a photographer's lens: a small angle flattens depth and observes; a large one exaggerates it and makes the viewer feel present.
In Ava3D: Camera.FieldOfView, 45 by default · chapter 3
Near plane, far plane
How close and how distant something can be before it is clipped away. Their ratio is what matters: the depth buffer's precision is spent almost entirely near the near plane, so a near plane set far closer than the scene needs is the usual cause of z-fighting.
In Ava3D: Camera.NearPlane, Camera.FarPlane, derived when null · chapter 3
Orbit camera
A camera described by what it is looking at and where it sits relative to that — a target, a distance, and two angles — rather than by a position and a rotation. It is the right model for inspecting an object, which is what a viewport usually does, and it has no roll of its own: up is world up.
Surfaces and light
Shader
A small program the graphics card runs in parallel — once per vertex to work out where a corner lands, once per covered pixel to work out what colour it is. This library ships one pair, written for OpenGL, Metal and the CPU, and exposes their parameters as a Material rather than letting you supply your own.
In Ava3D: not in the public API, by design · chapter 5
PBR, metallic-roughness
Physically based rendering: shading built on how light actually behaves, so a material tuned once looks right under any lighting. The metallic-roughness flavour — the one glTF uses — describes a surface with two main numbers instead of a pile of ad-hoc ones.
Base colour, albedo
The colour a surface is. For a non-metal it is the diffuse colour and reflections stay white; for a metal there is no diffuse term at all and this becomes the tint of the reflection. Which is why the same property makes red plastic and makes gold.
In Ava3D: Material.BaseColor, Material.BaseColorTexture · chapter 5
Metallic
Not a shininess slider: a switch between two physical behaviours. At 0 the surface has a diffuse colour and white highlights; at 1 it has no diffuse term and every bit of its colour comes from what it reflects. Values in between are only meaningful where one becomes the other, like paint flaking off metal.
In Ava3D: Material.Metallic · chapter 5
Roughness
How scattered a surface's reflections are: 0 is a mirror, 1 is chalk. Microscopic texture, modelled statistically rather than drawn — which is why a rough metal blurs the horizon it reflects instead of showing it sharply.
In Ava3D: Material.Roughness · chapter 5
Texture, texel
An image sampled across a surface to vary something — colour, roughness, how much light it gives off. A texel is one pixel of it. Sampling happens at UV coordinates, and what happens outside 0-to-1 is the wrap mode.
Projected coordinates, triplanar
Taking UV coordinates from a projection through space rather than from the mesh, which removes every complaint about an unwrap at once — no seam, no pole, no stretch, and nothing to unwrap. A planar projection is one sample down one axis; triplanar projects down all three and blends by the surface normal, at three samples a map. Under a projection, density becomes repeats per metre, which is the same number on a bolt as on a bulkhead.
In Ava3D: UvSource, Material.UvDensity, UvSharpness · chapter 5
Detail layer
One high-frequency field of noise, shared by the whole scene, perturbing normal and roughness underneath whatever the base maps say. It carries the end of the range a tiling map cannot afford — the grain of the metal, below what any base map resolves and above what a repeat can be seen at — for one texture rather than one per material. It fades with distance, because a feature smaller than a pixel is noise.
In Ava3D: Scene.Detail, Material.DetailNormal, DetailFade · chapter 5
Block compression
Storing a texture in fixed-size blocks the card decompresses as it samples, so the image stays compressed all the way into the GPU and stays compressed in it — a quarter to an eighth of the memory of RGBA8, for the whole life of the texture rather than just the download. BC1 to BC7 on desktop, ETC2 on GL ES and WebGL 2, ASTC on mobile.
In Ava3D: TextureFormat, Ktx2Loader · chapter 8
Filtering
What a sampler does when a texel does not line up with a pixel, which is almost always. Linear blends the four nearest texels and suits any image that is a continuous thing stored as a grid — a photograph, a normal map, a gradient. Nearest takes the one texel the coordinate lands in, so magnifying it leaves hard squares, which is what you want when the grid is the content rather than the storage: pixel art, a palette strip, an atlas of glyphs.
In Ava3D: TextureFilter, Texture.Filter · chapter 5
Normal map
A texture whose pixels are directions rather than colours, used in place of the interpolated normal. It gives a flat surface rivets, seams and weave that catch the light with no extra triangles — and no effect on the silhouette, which is how you can always tell.
In Ava3D: Material.NormalTexture, needs tangents · chapter 5
Bump map
A height field — one channel, high and low — turned into a perturbed normal from its gradient. Cruder than a normal map and needs no tangents, which makes it the better choice on a sphere, where UV tangents degenerate at the poles.
In Ava3D: Material.BumpTexture, Material.BumpScale · chapter 5
Emissive
Light a surface appears to give off itself: a screen, a lamp housing, a city at night. It is not a light source — it illuminates nothing else — it simply stays bright when everything around it goes dark.
In Ava3D: Material.EmissiveColor, Material.EmissiveTexture, Material.EmissiveNightSide · chapter 5
Ambient occlusion
Where ambient light cannot reach — inside a crevice, under a bolt head, in the corner of a room. Baked into a texture in advance, because working it out live is what an offline renderer does.
In Ava3D: Material.OcclusionTexture, Material.OcclusionStrength · chapter 5
Environment light
The light that comes from everywhere rather than from one direction — the sky, the ground, the room. A metal with nothing to reflect renders black, correctly and uselessly, so a renderer needs some model of the surroundings. Ava3D offers two: an analytic two-colour hemisphere, which costs nothing and needs no image, and an equirectangular picture, prefiltered into eight bands of increasing roughness so that a polished surface reflects it sharply and a rough one reflects a wide average of it. The second is image-based lighting; it is stacked bands of one 2D texture rather than a cubemap, which is what lets the same arithmetic run on every backend.
In Ava3D: EnvironmentLight, Scene.Environment · chapter 5
Directional light, point light
A directional light has a direction and no position: it is the sun, infinitely far away, striking
everything at the same angle. A point light has a position and fades with distance — its
Range is where it dies entirely and its Decay is how quickly, with 2 being the
inverse-square falloff of the real world.
In Ava3D: DirectionalLight, PointLight, as many as a scene wants · chapter 5
Shadow map
A picture of the scene taken from the light, recording only how far away the nearest surface is in each direction. When a pixel is shaded, its own distance from the light is compared with what the map recorded for it; if something was nearer, the pixel is in shadow and that light is taken away. One map serves one light, so a scene picks the light worth it.
Its shape follows the light. A directional light gets a box, because its rays are parallel; a spot light gets its own cone; and a point light — which has no direction — gets six square faces looking along the axes, sampled by direction rather than by a coordinate. That last one is a cube map, and it is what lets a bulb shadow in every direction rather than in whichever one somebody guessed.
In Ava3D: Light.CastsShadows, Scene.ShadowMapSize, MeshNode.CastsShadow · chapter 5
Spot light
A light with a position, a direction and a cone: full brightness inside an inner angle, nothing outside an outer one, and a smooth falloff between them. Both angles are measured from the axis, so a twenty-five degree cone is a fifty degree beam. It is the light to reach for whenever something is carried or aimed, because a cone is also exactly the shape a shadow map wants — so a spot's shadow needs no guesswork about where to point.
In Ava3D: SpotLight · chapter 5
Tone mapping
Lighting arithmetic produces values well beyond 1.0; a screen cannot. Tone mapping is the squeeze from one range into the other, and it is why a very bright surface goes creamy rather than clipping to a flat white slab.
In Ava3D: automatic, and skipped entirely when Material.Unlit is set · chapter 5
Drawing
Draw call
One instruction from the CPU to the GPU: draw this geometry, with this state. It is the unit that
actually costs — a hundred and twenty-eight thousand triangles in 126 draw calls is comfortable, while
twelve thousand draw calls of ten triangles each is not. One MeshNode is one draw call.
In Ava3D: RenderInfo.DrawCalls · chapter 8
Depth buffer, z-buffer
A distance stored per pixel, so that a surface being drawn can be compared with whatever is already there and skipped if it is behind. It is what lets geometry be drawn in any order and still look right — and its precision is not spread evenly, which is what makes the near plane matter.
In Ava3D: Material.DepthTest, Material.DepthWrite · chapter 6
Z-fighting
Two surfaces at almost the same distance flickering between each other as the camera moves, because the depth buffer cannot tell them apart. Usually a near plane set far too close, occasionally two coplanar surfaces that should have been one.
In Ava3D: avoid by setting Camera.NearPlane honestly, or by
depth bias where the surfaces are meant to be coplanar ·
chapter 3
Depth bias
A nudge added to a surface's depth as it is rasterised, so geometry deliberately drawn on top of other geometry — a decal on a wall, panel lines on a hull, a grid on a floor — wins the depth test cleanly instead of z-fighting with what it sits on. Two numbers: a constant, and one scaled by how steeply the surface runs away from the camera, which is what covers a floor seen at a grazing angle.
In Ava3D: Material.DepthBias and DepthBiasSlope, filled
triangles only · chapter 6
Blending
How a pixel being drawn combines with the one already there. Opaque replaces it; alpha mixes the two by a weight, which is glass and smoke; additive adds, so it can only brighten, which is fire and tracers and glows. Blended things almost always want their depth write off, or they punch invisible holes in each other.
Render order
The manual override on what is drawn when. The automatic rule is render order first, then opaque before blended, then back to front by node origin — per object, not per triangle, which is why two transparent surfaces that interpenetrate cannot both be right.
In Ava3D: Node.RenderOrder · chapter 6
Billboard, sprite
A flat image that turns to face the camera every frame, so it never shows an edge. Glows, flares, smoke, distant markers. Sized in world units here, so it recedes like anything else — and it can be told to ignore depth, which is how a ship stays visible after its hull is sub-pixel.
In Ava3D: SpriteNode · chapter 6
Backface culling
Skipping triangles that face away from the camera, which for a closed solid is half of them and free to discard. Which way a triangle faces comes from its winding order. Culling the front faces instead is what a sky sphere seen from inside needs.
Instancing
Drawing the same geometry many times in one draw call. The per-copy values — a transform and a tint — go to the card as a second vertex buffer that advances once per copy rather than once per vertex. Four hundred crates become one draw. What you give up is that a copy is not a node: it has no name, no children, no visibility of its own, and nothing can pick it.
In Ava3D: MeshNode.Instances, MeshInstance · chapter 8
Batching, folding
Merging many static objects that share a material into one mesh, so they cost one draw call instead of one each. The trade is that the merged thing can no longer be moved in pieces, which is why folding leaves alone anything named, hidden, pinned or holding children — a named node is something somebody refers to.
In Ava3D: Batching.Fold, Mesh.Merge · chapter 8
Frustum culling
Not submitting what the camera cannot see: anything whose bounding box lies entirely outside the frustum is dropped before the renderer is asked to draw it. Distinct from backface culling, which is about which side of a triangle is drawn. It saves submission rather than fill, so it shows up in the draw count first and in the frame time only when submission was the limit.
In Ava3D: Scene.FrustumCulling (on by default), Scene.CullingMargin · chapter 8
Level of detail
A lighter version of a mesh, drawn in its place once it is far enough away that nobody can tell. A fern at two metres needs its three thousand triangles; the same fern at forty metres is a few pixels and needs two hundred. A draw distance is the last step: past it, nothing is drawn at all.
In Ava3D: MeshNode.LevelsOfDetail, MeshNode.MaxDrawDistance · chapter 8
Snapshot
The flat, immutable draw list this control builds from your scene once a frame and hands to the render thread. It is why you can mutate the graph from anywhere with no lock and never see half a frame, and why the renderer never holds a reference to anything you can still change. Its draw-item array comes from a small pool and is returned when the renderer has finished with it, so a scene whose shape is steady allocates almost nothing per frame.
In Ava3D: RenderInfo.SceneRebuildsPerSecond, SceneRebuildBytes · How a frame happens
Picking
Working out what is under the pointer. Done here against geometry rather than pixels: a ray is cast from the camera through the pointer, rejected quickly by each node's bounding box, then tested triangle by triangle. That behaves identically on the GPU, on the CPU, and in a browser where reading a pixel back means a round trip.
In Ava3D: PickResult, Ava3DView.IsPickingEnabled
Files and platforms
glTF, .glb
The standard interchange format for 3D scenes — geometry, materials, textures and a node hierarchy in one
file. .gltf is the JSON form with its data alongside; .glb is the same thing
packed into one binary file, which is the form to use anywhere a second file would need fetching.
In Ava3D: GltfLoader, binary only · From a .glb file to these types
Aliasing
What happens when a picture is sampled less finely than the thing it is a picture of. Each pixel takes one sample, so a triangle's edge is either in or out with no half — a diagonal comes out as a staircase. Standing still that reads as sharpness; moving, each step jumps to the next pixel at its own moment and the edge crawls. The same fault inside a surface is a tiled pattern breaking up in the distance, or a highlight sparkling on fine relief.
In Ava3D: Ava3DView.SampleCount, Ava3DView.RenderScale · chapter 8
Multisampling
Testing several points inside each pixel to see how much of it a triangle covers, while still working out the colour only once. It fixes edges cheaply, because most pixels are wholly inside or wholly outside and only the few on a silhouette cost anything extra. It does nothing for a surface that shimmers, because that is a shading problem and the shading still happens once.
In Ava3D: Ava3DView.SampleCount · chapter 8
Supersampling
Rendering the whole frame larger than it will be shown and averaging it down. The blunt instrument, and the one that works everywhere and on everything — edges and surfaces alike — because every pixel really is shaded more than once. It costs the square of the factor in fill.
In Ava3D: Ava3DView.RenderScale · chapter 8
Backend, renderer
The thing that turns a snapshot into pixels through a particular graphics API: Metal on Apple platforms, OpenGL or WebGL 2 elsewhere, and Skia on the CPU where a host offers no GPU context at all. Which one you get is decided at runtime, from what the host actually provides.
In Ava3D: RenderInfo, RenderBackendKind · How the renderer is chosen