DrawingImmediate

Per-frame drawing with paint signals, shaders, particles and render targets.

20 functionssUNC 100%Lynx 0.0.0

DrawingImmediate records transient draw commands for a z-index through the module's custom Signal paint callbacks. It shares resources created with Drawing.new; there is no separate resource constructor or RenderGraph object.

Paint lifecycle

DrawingImmediate.GetPaint

DrawingImmediate.GetPaint(zIndex: number): Signal

Returns the same native-owned custom Signal for this integer z-index in the primary drawing VM. Each frame fires layers in ascending z-index order. Connect callbacks receive no arguments and execute synchronously in the recording thread; call DrawingImmediate operations directly there. Callback errors are logged. This signal is not a Roblox RBXScriptSignal or SynSignal.

Returns

Signal

The result described above.

Paint signal memberBehavior
:Connect(callback: () -> ())Returns SignalConnection. Record commands directly in this callback; do not yield or dispatch recording work into another thread.
:Once(callback: () -> ())Returns SignalConnection and disconnects before its first callback. Useful for a one-frame draw, not a persistent retained shape.
:Wait()Waits for the next paint outside a paint callback; resumed waiters are not the recording thread and cannot draw through DrawingImmediate.
:Fire(...)Rejected for native paint signals. The module owns their firing.
connection:Disconnect()Stops future recording by this connection; call during cleanup. No Connected field is exposed by this custom connection class.

Primitive commands describe the current frame only. They are rebuilt and replayed from an immutable frame snapshot; keep sending a primitive in a connected callback to keep it visible. Fonts is exported as DrawingImmediate.Fonts, matching Drawing.Fonts (UI=0, System=1, Plex=2, Monospace=3, Montserrat=4).

Primitive functions

DrawingImmediate.Line

DrawingImmediate.Line(p1: Vector2, p2: Vector2, color: Color3, opacity: number, thickness: number): ()

Records a stroked line.

DrawingImmediate.Circle

DrawingImmediate.Circle(center: Vector2, radius: number, color: Color3, opacity: number, numSides: number, thickness: number): ()

Records an unfilled circle. Note opacity precedes numSides.

DrawingImmediate.FilledCircle

DrawingImmediate.FilledCircle(center: Vector2, radius: number, color: Color3, numSides: number, opacity: number): ()

Records a filled circle. Note numSides precedes opacity, unlike Circle.

DrawingImmediate.Triangle

DrawingImmediate.Triangle(p1: Vector2, p2: Vector2, p3: Vector2 | Vector3, color: Color3, opacity: number, thickness: number): ()

Records a triangle outline. Only the third point additionally accepts Vector3; its Z component is ignored.

DrawingImmediate.FilledTriangle

DrawingImmediate.FilledTriangle(p1: Vector2, p2: Vector2, p3: Vector2 | Vector3, color: Color3, opacity: number): ()

Records a filled triangle. Only the third point additionally accepts Vector3; Z is ignored.

DrawingImmediate.Rectangle

DrawingImmediate.Rectangle(topLeft: Vector2, size: Vector2, color: Color3, opacity: number, rounding: number, thickness: number): ()

Records a rounded rectangle outline; second argument is dimensions, not bottom-right coordinates.

DrawingImmediate.FilledRectangle

DrawingImmediate.FilledRectangle(topLeft: Vector2, size: Vector2, color: Color3, opacity: number, rounding: number): ()

Records a filled rounded rectangle; second argument is dimensions.

DrawingImmediate.Quad

DrawingImmediate.Quad(p1: Vector2, p2: Vector2, p3: Vector2, p4: Vector2, color: Color3, opacity: number, thickness: number): ()

Records a four-point outline.

DrawingImmediate.FilledQuad

DrawingImmediate.FilledQuad(p1: Vector2, p2: Vector2, p3: Vector2, p4: Vector2, color: Color3, opacity: number): ()

Records a filled four-point polygon.

DrawingImmediate.Text

DrawingImmediate.Text(position: Vector2, font: number, fontSize: number, color: Color3, opacity: number, text: string, center: boolean): ()

Records literal text. Font is a Drawing.Fonts integer 0..4; fontSize must be >0. center is a required boolean.

DrawingImmediate.OutlinedText

DrawingImmediate.OutlinedText(position: Vector2, font: number, fontSize: number, color: Color3, opacity: number, outlineColor: Color3, outlineOpacity: number, text: string, center: boolean): ()

Records outlined text with separate fill/outline opacity. Font is a Drawing.Fonts integer 0..4; fontSize >0 and center is required.

Shader and resource commands

DrawingImmediate.Shader

DrawingImmediate.Shader(position: Vector2, size: Vector2, shader: Shader, uniforms: UniformMap?, opacity: number?, options: DrawOptions?): ()

Records a Canvas Shader draw. Uniform overrides default to {}; opacity defaults to 1. Program default Uniforms and Bindings are merged with overrides.

DrawingImmediate.Texture

DrawingImmediate.Texture(position: Vector2, size: Vector2, texture: Texture | RenderTarget, opacity: number?, options: DrawOptions?): ()

Records an image or target blit. Opacity defaults to 1. Resources are shared with Drawing.new; this does not take encoded image bytes.

DrawingImmediate.ModelEffect

DrawingImmediate.ModelEffect(target: Instance, shader: Shader, uniforms: UniformMap?, opacity: number?, options: DrawOptions?): ()

Captures supported target geometry and records a Shader draw. Uniforms default to {}, opacity to 1. Uses the same geometry/camera support as retained ModelEffect; capture may raise a Drawing failed error.

DrawingImmediate.Mesh

DrawingImmediate.Mesh(mesh: Mesh, transform: CFrame | {number}, shader: Shader, uniforms: UniformMap?, opacity: number?, options: DrawOptions?): ()

Records mesh geometry with a required transform and Shader. Matrix form has 16 elements. Uniforms default to {}, opacity to 1; captures the camera for world geometry.

DrawingImmediate.Particles

DrawingImmediate.Particles(buffer: Buffer, shader: Shader?, uniforms: UniformMap?, opacity: number?, options: DrawOptions?): ()

Records structured-buffer particles. Shader may be nil for the built-in material. Uniforms default to {}, opacity to 1. Options select field names, count and Screen/World space.

DrawingImmediate.Dispatch

DrawingImmediate.Dispatch(compute: Compute, groupsX: number, groupsY: number, groupsZ: number, bindings: BindingMap?, uniforms: UniformMap?): ()

Records an ordered compute dispatch; each group count must be an integer 1..65535. Omitted bindings use Compute.Bindings; supplying a map replaces it for this dispatch. Uniforms override declared defaults. Do not enable AutoDispatch as well unless two dispatches are intended.

DrawingImmediate.BeginTarget

DrawingImmediate.BeginTarget(target: RenderTarget, clearColor: Color3 | Vector3 | {number}?): ()

Begins an off-screen target, clearing it to the supplied RGB/RGBA (default transparent black) and resetting depth. Use a three- or four-number color array for explicit alpha. Maximum nesting is 16; every call requires EndTarget in the same paint invocation. Only shader/resource commands are redirected; plain ImGui-backed Line/Text/etc remain overlay primitives.

DrawingImmediate.EndTarget

DrawingImmediate.EndTarget(): ()

Closes the innermost target. Calling without BeginTarget raises an error. An unmatched target at the end of a paint layer discards that layer's frame commands and logs the mismatch.

DrawOptions

Bindings
Type / defaultBindingMap = {}
Merges per-draw resource bindings over Shader.Bindings.
ResolutionScale
Type / defaultnumber = 1
>0 and <=4.
Blend
Type / default"Alpha" | "Add" | "Multiply" | "Opaque" = "Alpha"
Composition mode.
DepthTest
Type / defaultboolean = false
Requests compatible geometry-depth testing.
Bloom
Type / defaultboolean | BloomOptions = false
Threshold=1, Strength=0.7, Radius=6; options 0..256.
Space
Type / default"Screen" | "World" = "Screen"
Particle coordinate space.
Count
Type / defaultnumber = 0
Particle count 0..4194304; 0 uses the available buffer count.
Fields
Type / default{Position: string?, Size: string?, Color: string?}
Particle field-name overrides; defaults Position, Size, Color. Buffer types must be Position float2/float3, Size float2, Color float4.

Shader-backed draw sizes must be nonnegative, opacity must be 0..1, and all numeric values must be finite. Shader operations raise sanitized Drawing failed errors for invalid resources/layouts. The Shader stage signatures, uniform types, Structs, BindingTypes and resource lifecycle are documented on the Drawing page. Commands execute in recorded order: a Dispatch/Upload can feed a later Shader/Particles command or target pass in the same paint callback.

Paint and off-screen example

local shader = Drawing.new("Shader")
shader.Backend = "Auto"
shader.Source = [[
float4 effect(float2 uv) {
float wave = 0.5 + 0.5 * sin(20 * length(uv - 0.5) - Time * 3);
return float4(0.1, wave, 1, 1);
}
]]
local ok, err = shader:Compile()
assert(ok, err)
local target = Drawing.new("RenderTarget")
target.Backend, target.Size = shader.ActualBackend, Vector2.new(256,256)
ok, err = target:Compile()
assert(ok, err)
local connection = DrawingImmediate.GetPaint(10):Connect(function()
local D = DrawingImmediate
D.BeginTarget(target, {0,0,0,0})
D.Shader(Vector2.zero, Vector2.new(256,256), shader)
D.EndTarget()
D.Texture(Vector2.new(30,50), Vector2.new(256,256), target)
D.Line(Vector2.new(30,315), Vector2.new(286,315), Color3.new(1,1,1), 1, 2)
D.Text(Vector2.new(30,28), Drawing.Fonts.UI, 18, Color3.new(1,1,1), 1, "Shader", false)
end)
local function cleanup()
connection:Disconnect()
shader:Remove()
target:Remove()
end

Written for Lynx 0.0.0

Something unclear? Tell us on Discord