Graphics API — draw calls, shaders, and GPU buffers

The Graphics static class is the primary interface for issuing draw calls and managing GPU resources in s&box. It is only valid inside a rendering block (e.g. a SceneCustomObject.OnRender callback). Supporting types — RenderAttributes, RenderTarget, ComputeShader, and GpuBuffer — let you pass data to shaders, render off-screen, and run compute workloads.

Most Graphics methods throw an exception if called outside a render block. Graphics.IsActive is true when it is safe to call rendering methods. Graphics.FlushGPU() is an exception and can be called anywhere.

Graphics static class

State

Graphics.IsActive

bool

true when executing inside a render block. Use this guard before issuing draw calls from code that may run both inside and outside rendering.

Graphics.LayerType

SceneLayerType

The current render layer — opaque, transparent, shadow, or other. Use this to conditionally emit draw calls only for the appropriate pass.

Graphics.Viewport

Rect

Gets or sets the current pixel viewport rectangle. Setting this changes the scissor region for subsequent draw calls.

Graphics.Attributes

RenderAttributes

The RenderAttributes bag for the current render context. Set material parameters here before calling Draw or Blit. Cleared at the end of the render block.

Graphics.RenderTarget

RenderTarget

Gets or sets the active render target. Setting a non-null value binds that target and resizes the viewport to match. Set back to null to restore the default framebuffer.

Camera

Graphics.CameraTransform

Transform

The world-space transform of the camera for the current view.

Graphics.CameraPosition

Vector3

The world-space position of the active camera.

Graphics.CameraRotation

Rotation

The world-space rotation of the active camera.

Graphics.FieldOfView

float

The field of view of the active camera in degrees.

Graphics.Frustum

Frustum

The view frustum of the currently rendering camera. Use this for custom visibility checks.

Draw calls

Graphics.Draw(Span<Vertex> vertices, int vertCount, Material material, RenderAttributes attributes, PrimitiveType primitiveType)

void

Draws a span of Vertex values with the given material.

Show Parameters

vertices

Span<Vertex>

required

The vertex data to draw.

vertCount

int

required

Number of vertices to consume from the span.

material

Material

required

The material (shader) to use for this draw call.

attributes

RenderAttributes

Optional. Additional render attributes. Defaults to Graphics.Attributes.

primitiveType

PrimitiveType

Optional. Topology. Defaults to PrimitiveType.Triangles.

An overload also accepts a List<Vertex> instead of a Span<Vertex>. An additional overload accepts Span<ushort> indices and int indexCount for indexed drawing.

Graphics.Blit(Material material, RenderAttributes attributes)

void

Draws a full-screen quad in screen space using the provided material. Your material must use a screen-space shader or it will render at the world origin.

Show Parameters

material

Material

required

A screen-space material/shader.

attributes

RenderAttributes

Optional extra attributes to pass to the shader.

Graphics.Render(SceneObject obj, Transform? transform, Color? color, Material material)

void

Renders a SceneObject immediately into the current render context. Useful for rendering a specific object with a custom transform or material override.

Graphics.DrawQuad(Rect rect, Material material, Color color, RenderAttributes attributes)

void

Draws a 2D quad at the given screen-space rectangle.

Graphics.DrawText(Rect position, string text, Color color, string fontFamily, float fontSize, float fontWeight, TextFlag flags)

Rect

Renders text into a screen-space rectangle using Material.UI.Text. Returns the actual bounds of the rendered text.

Graphics.DrawIcon(Rect rect, string iconName, Color color, float fontSize, TextFlag alignment)

Rect

Renders a Material Icons glyph. iconName is the lowercase icon identifier from the Material Icons library.

Graphics.DrawRoundedRectangle(Rect rect, Color color, Vector4 cornerRadius, Vector4 borderWidth, Color borderColor)

void

Draws a rounded rectangle with optional border using Material.UI.Box.

Graphics.MeasureText(Rect position, string text, string fontFamily, float fontSize, float fontWeight, TextFlag flags)

Rect

Measures the bounds of text without rendering it. Use this to compute layouts before drawing.

Texture utilities

Graphics.GrabFrameTexture(string targetName, RenderAttributes renderAttributes, DownsampleMethod downsampleMethod, int maxMips)

RenderTarget

Copies the current color framebuffer into a temporary RenderTarget and registers it on renderAttributes under targetName. The texture is automatically returned to the pool at the end of the render block.

Show Parameters

targetName

string

The attribute name to bind the grabbed texture to. Defaults to "FrameTexture".

renderAttributes

RenderAttributes

The attribute bag to write to. Defaults to Graphics.Attributes.

downsampleMethod

DownsampleMethod

Generates a mip chain using the specified method if set to anything other than DownsampleMethod.None.

maxMips

int

Maximum number of mip levels to generate. 0 means generate all levels.

Graphics.GrabDepthTexture(string targetName, RenderAttributes renderAttributes)

RenderTarget

Copies the current depth buffer into a temporary RenderTarget and registers it on renderAttributes under targetName.

Graphics.CopyTexture(Texture srcTexture, Texture dstTexture)

void

Copies pixel data between two GPU textures. Format and size must match exactly.

Graphics.CopyTexture(Texture srcTexture, Texture dstTexture, int srcMipSlice, int srcArraySlice, int dstMipSlice, int dstArraySlice)

void

Copies a specific mip level and array slice between textures.

Graphics.SetupLighting(SceneObject obj, RenderAttributes targetAttributes)

void

Populates targetAttributes with per-object lighting data for the given SceneObject. Call this before drawing an object that needs dynamic lighting.

Graphics.Clear(Color color, bool clearColor, bool clearDepth, bool clearStencil)

void

Clears the active render target. All parameters default to clearing everything to the given color.

Graphics.FlushGPU()

void

Forces the GPU to complete all pending commands synchronously. Can be called outside a render block. Use sparingly as it stalls the CPU.

Primitive types

Graphics.PrimitiveType controls the interpretation of vertex data:

Value	Description
`Points`	Each vertex is an independent point.
`Lines`	Every two vertices form a line segment.
`LineStrip`	Vertices form a connected line strip.
`Triangles`	Every three vertices form a triangle.
`TriangleStrip`	Vertices form a strip of connected triangles.
`*WithAdjacency`	Variants include adjacency data for geometry shaders.

RenderAttributes

RenderAttributes is a key/value bag that passes typed data to materials and shaders. The shader side accesses attributes with the Attribute( "Name" ) annotation.

// In your shader
float4 BorderRadius < Attribute( "BorderRadius" ); >;
Texture2D g_tColor < Attribute( "Texture" ); SrgbRead( false ); >;

Setting values

RenderAttributes has Set overloads for every supported type:

C# type	Method
`int`	`Set( StringToken k, int value )`
`float` / `double`	`Set( StringToken k, float value )`
`bool`	`Set( StringToken k, bool value )`
`string`	`Set( StringToken k, string value )`
`Vector2`	`Set( StringToken k, Vector2 value )`
`Vector3`	`Set( StringToken k, Vector3 value )`
`Vector4`	`Set( StringToken k, Vector4 value )`
`Angles`	`Set( StringToken k, Angles value )`
`Matrix`	`Set( StringToken k, Matrix value )`
`Texture`	`Set( StringToken k, Texture value, int mip )`
`SamplerState`	`Set( StringToken k, SamplerState value )`
`GpuBuffer`	`Set( StringToken k, GpuBuffer value )`

SetData<T>( StringToken k, Span<T> value ) uploads raw struct data into a constant buffer. T must be a POD (blittable) struct. SetCombo( StringToken k, int value ) sets a shader static combo by name.

Getting values

Matching Get* methods retrieve values back from the bag: GetBool, GetFloat, GetInt, GetVector, GetVector4, GetAngles, GetMatrix, GetTexture.

Lifecycle

Graphics.Attributes is the per-render-context bag — it is cleared automatically at the end of each render block. To pass attributes that live longer, create your own RenderAttributes instance:

var attrs = new RenderAttributes();
attrs.Set( "MyParam", 42.0f );
Graphics.Blit( myMaterial, attrs );

Manually-created RenderAttributes objects clean up their native memory asynchronously on the main thread.

RenderTarget

RenderTarget wraps a color texture and an optional depth texture for off-screen rendering.

RenderTarget.Width

int

Width of the render target in pixels.

RenderTarget.Height

int

Height of the render target in pixels.

RenderTarget.ColorTarget

Texture

The color texture attached to this render target.

RenderTarget.DepthTarget

Texture

The depth texture attached to this render target. May be null if no depth is needed.

RenderTarget.From(Texture color, Texture depth)

RenderTarget (static)

Creates a RenderTarget from existing render-target-compatible textures. Both textures must have been created with Texture.CreateRenderTarget.

RenderTarget.Dispose()

void

Returns a temporary RenderTarget to the pool. Call this when done with a target obtained from Graphics.GrabFrameTexture or Graphics.GrabDepthTexture if not relying on automatic pool return.

ComputeShader

ComputeShader runs a shader program on the GPU outside the standard rendering pipeline. Pair it with GpuBuffer to exchange data between the CPU and GPU.

ComputeShader(string path)

constructor

Loads a compute shader from the given asset path.

Show Parameters

path

string

required

Path to the compute shader asset, e.g. "shaders/my_compute.shader".

ComputeShader.Attributes

RenderAttributes

The RenderAttributes bag for this shader. Set input and output buffers here before calling Dispatch.

ComputeShader.Dispatch(int threadsX, int threadsY, int threadsZ)

void

Dispatches the compute shader. Thread counts are automatically divided by the thread group size declared in the shader.When called inside a graphics context the dispatch runs asynchronously. When called outside a graphics context it runs immediately.

Show Parameters

threadsX

int

Number of threads to dispatch in X. Defaults to 32.

threadsY

int

Number of threads to dispatch in Y. Defaults to 32.

threadsZ

int

Number of threads to dispatch in Z. Defaults to 32.

ComputeShader.DispatchWithAttributes(RenderAttributes attributes, int threadsX, int threadsY, int threadsZ)

void

Dispatches with an explicit RenderAttributes bag instead of the shader’s built-in Attributes property.

ComputeShader.DispatchIndirect(GpuBuffer indirectBuffer, uint indirectElementOffset)

void

Reads dispatch thread group counts from a GPU buffer of type GpuBuffer.UsageFlags.IndirectDrawArguments. The buffer’s element size must be 12 bytes.

Show Parameters

indirectBuffer

GpuBuffer

required

Buffer containing (x, y, z) dispatch group counts as three uint32 values.

indirectElementOffset

uint

Element index into the buffer (not a byte offset). Defaults to 0.

GpuBuffer

GpuBuffer and the generic GpuBuffer<T> wrap a GPU-side memory buffer for use with compute shaders and custom rendering. Use SetData to upload from the CPU and GetData to read back.

Construction

GpuBuffer(int elementCount, int elementSize, UsageFlags flags, string debugName)

constructor

Creates an untyped buffer.

Show Parameters

elementCount

int

required

Number of elements the buffer holds.

elementSize

int

required

Size of a single element in bytes. Must be divisible by 4 for Structured buffers, and 2 or 4 for Index buffers.

flags

UsageFlags

Buffer usage type. Defaults to UsageFlags.Structured.

debugName

string

Optional label shown in GPU profilers.

GpuBuffer<T>(int elementCount, UsageFlags flags, string debugName)

constructor

Creates a typed buffer. T must be a blittable struct. Element size is inferred from sizeof(T).

Properties

GpuBuffer.ElementCount

int

Number of elements allocated in the buffer.

GpuBuffer.ElementSize

int

Size in bytes of a single element.

GpuBuffer.Usage

UsageFlags

The usage flags the buffer was created with.

GpuBuffer.IsValid

bool

true when the native GPU handle is valid and the buffer has not been disposed.

Data transfer

GpuBuffer.SetData<T>(Span<T> data, int elementOffset)

void

Synchronously uploads data from a Span<T> to the GPU. Blocks until the upload completes.

GpuBuffer.SetData<T>(List<T> data, int elementOffset)

void

Same as the Span overload but accepts a List<T>.

GpuBuffer.GetData<T>(Span<T> data)

void

Synchronously downloads all buffer data from the GPU. Blocks the CPU until the read is complete.

GpuBuffer.GetData<T>(Span<T> data, int start, int count)

void

Downloads a range of elements from the GPU.

GpuBuffer.GetDataAsync<T>(Action<ReadOnlySpan<T>> callback)

void

Asynchronously reads the full buffer and invokes callback with the data. The ReadOnlySpan<T> is only valid inside the callback.

GpuBuffer.GetDataAsync<T>(Action<ReadOnlySpan<T>> callback, int start, int count)

void

Asynchronously reads a range of the buffer.

Utilities

GpuBuffer.Clear(uint value)

void

Fills the entire buffer with a repeated uint32 value on the GPU. Defaults to 0.

GpuBuffer.SetCounterValue(uint counterValue)

void

Sets the hidden atomic counter for Append or Counter structured buffers.

GpuBuffer.CopyStructureCount(GpuBuffer destBuffer, int destBufferOffset)

void

Copies the hidden structure count from an Append or Structured buffer into destBuffer.

GpuBuffer.Dispose()

void

Destroys the GPU buffer. Must be called on the main thread. After disposal IsValid returns false.

UsageFlags

Flag	HLSL mapping	Notes
`Structured`	`StructuredBuffer<T>` / `RWStructuredBuffer<T>`	Default. Element size must be 4-byte aligned.
`Index`	Index buffer	Element size must be 2 or 4 bytes.
`Append`	`AppendStructuredBuffer<T>`	Supports atomic append and hidden counter.
`Counter`	`RWStructuredBuffer<T>` with counter	Supports `SetCounterValue`.
`ByteAddress`	`ByteAddressBuffer`	Raw byte-addressable reads.
`IndirectDrawArguments`	Indirect dispatch/draw args	Required for `DispatchIndirect`. Element size must be 12 bytes.

Usage examples

// In SceneCustomObject.OnRender
public override void OnRender()
{
    if ( !Graphics.IsActive ) return;

    Graphics.GrabFrameTexture( "FrameTexture" );

    Graphics.Blit( myPostMaterial );
}

Rendering guide

How to write custom render passes and post-processing effects in s&box.

Shaders guide

Writing and compiling HLSL shaders with the s&box shader system.

Camera component

The CameraComponent API for setting up scene views.

Game class

Global game state and active scene access.

Scene & Objects

Built-in Components

Systems

Graphics API — draw calls, shaders, and GPU buffers

Graphics static class

State

Camera

Draw calls

Texture utilities

Primitive types

RenderAttributes

Setting values

Getting values

Lifecycle

RenderTarget

ComputeShader

GpuBuffer

Construction

Properties

Data transfer

Utilities

UsageFlags

Usage examples

Rendering guide

Shaders guide

Camera component

Game class

Build docs developers (and LLMs) love

Scene & Objects

Built-in Components

Systems

Documentation Index

​Graphics static class

​State

​Camera

​Draw calls

​Texture utilities

​Primitive types

​RenderAttributes

​Setting values

​Getting values

​Lifecycle

​RenderTarget

​ComputeShader

​GpuBuffer

​Construction

​Properties

​Data transfer

​Utilities

​UsageFlags

​Usage examples

​Related pages

Rendering guide

Shaders guide

Camera component

Game class

Build docs developers (and LLMs) love

Graphics static class

State

Camera

Draw calls

Texture utilities

Primitive types

RenderAttributes

Setting values

Getting values

Lifecycle

RenderTarget

ComputeShader

GpuBuffer

Construction

Properties

Data transfer

Utilities

UsageFlags

Usage examples

Related pages