API Reference · Sprites, lines and points

SpriteNode

Namespace: Ava3D

public class SpriteNode : Node

A textured quad that always faces the camera, centred on the node's position.

This is what draws anything that is light rather than surface: an engine glow, a beacon, a lamp, the corona around a star. Emissive geometry cannot substitute, because emissive geometry is still geometry — it is occluded by whatever is in front of it and it shrinks to nothing at distance. A sprite with SpriteNode.DepthTest off keeps a ship visible as a point of light long after its hull is sub-pixel, which is exactly the job.

The quad's edges stay parallel to the viewport's, and only the node's translation is read — rotation and scale on a sprite node are ignored, because a quad that is always square-on to the camera has nowhere to put them.

Not sealed, so that LabelNode can be one. A camera-facing textured quad is exactly what a label in a scene is, so a label is drawn, sorted and culled as a sprite on every renderer. Deriving from it yourself is not a way to change how sprites draw: a subclass is drawn from the properties declared here and nothing else.

Properties

MemberDescription
BlendMode Blend { get; set; }

How the quad combines with the frame. BlendMode.Alpha by default.

Vector3 Color { get; set; }

Linear RGB tint, multiplied with SpriteNode.Texture.

bool DepthTest { get; set; }

Whether the quad is hidden by geometry in front of it. On by default.

bool DepthWrite { get; set; }

Whether the quad writes depth. Off by default, and it should almost always stay off: a sprite that writes depth occludes every sprite drawn after it, so two overlapping glows stop adding up and the nearer one punches a hole in the further one.

BoundingBox LocalBounds { get; }

The quad's extent, so Ava3DView.AutoFit frames a scene that contains sprites. Flat in z, because the quad has no thickness until the camera orients it.

float Opacity { get; set; }

Overall opacity, 0..1, multiplied with the texture's own alpha.

Vector2 Size { get; set; }

The quad's size in world units, so it shrinks with distance like everything else.

World units rather than pixels on purpose. A sun's corona is a fixed size in the world and should recede as you leave; a beacon meant to hold its size on screen is a division by range the caller does itself, and that is a calculation only the caller can get right. Screen-space sizing here would make the first case impossible to express.

float SoftDistance { get; set; }

How far in front of solid geometry this quad starts fading out, in world units. Zero — the default — leaves it hard-edged.

A billboard is a flat card, and where it approaches a solid the card's own edge shows. With this set the sprite reads the depth of what is already drawn and fades as it approaches it, so a glow meets a hull as smoke rather than as a decal. Set it to about the size of the sprite.

Needs a renderer that can copy its depth buffer — see RenderInfo.Features. Where it cannot, this is ignored and the edge stays hard.

Texture Texture { get; set; }

The image to draw. Null draws a plain quad of SpriteNode.Color.

Vector4 UvRect { get; set; }

Which part of SpriteNode.Texture this quad shows: xy scale, zw offset.

The whole image by default. Its reason for existing is the atlas — see SpriteNode.UseFrame — because a field of grass or a sky of cloud wants several silhouettes and uploading each as its own texture costs an upload, a cache entry and a texture bind per variety. One sheet and a rectangle per sprite costs none of those, and the binding cache then has nothing to do between them.

A Vector4 rather than the two Vector2s Material uses, on the reasoning that a sprite's is set by SpriteNode.UseFrame far more often than by hand.

Methods

MemberDescription
void UseFrame(int columns, int rows, int index)

Points SpriteNode.UvRect at one cell of a grid atlas, counting left to right then down.

columns

Cells across. At least one.

rows

Cells down. At least one.

index

Which cell, wrapped — so an animation can hand it a counter that only goes up.

See also