Drawing
Persistent drawing objects, shaders, compute programs, textures, meshes and effects.
- Library functions
- Drawing.new
- Drawing.clear
- isrenderobj
- getrenderproperty
- setrenderproperty
- cleardrawcache
- Fonts
- Custom fonts
- DrawFont.Register
- DrawFont:GetTextBounds
- Common primitive properties
- Line
- Circle
- Square
- Triangle
- Quad
- Text
- Image
- Shader resource kinds
- Shared resource state and drawing state
- CPU, GPU and shader language
- Engine-provided HLSL inputs
- Uniform values
- BindingType
- Compute properties
- Buffer and texture storage
- Mesh, ModelEffect and particles
- Resource methods
- DrawingResource:Remove
- DrawingResource:Compile
- DrawingResource:Upload
- DrawingResource:Readback
- DrawingResource:Resize
- DrawingResource:SetUniform
- DrawingResource:GetUniform
- Compute:Dispatch
- Shader, compute and target example
The Drawing library adds shapes, text, images and shader effects to the screen. Create an object with Drawing.new, set its properties, then set Visible to true. Objects remain visible until you hide or remove them. Shader resources can also be used with DrawingImmediate.
Library functions
Drawing.new
Drawing.new(kind: string): DrawingObjectDrawing.new creates a drawing object or shader resource of the requested type.
Parameters
kindstring- The drawing or resource type to create. See the type lists below.
Returns
DrawingObjectThe new Drawing object or resource. Its properties depend on the requested type.
Drawing.clear
Drawing.clear(): ()Drawing.clear removes every active drawing object and shader resource created with Drawing.new.
Returns
()This function does not return a value.
isrenderobj
isrenderobj(value: unknown): booleanisrenderobj checks whether a value is a Drawing object.
Also available as is_render_obj.
Parameters
valueunknown- The value to check for Drawing-object identity.
Returns
booleanTrue if the value is a Drawing object, otherwise false. This check does not report whether it has been removed.
getrenderproperty
getrenderproperty(object: DrawingObject, property: string): unknowngetrenderproperty gets a property from a Drawing object, using its name.
Also available as get_render_property.
Parameters
objectDrawingObject- The Drawing object whose property will be accessed.
propertystring- The name of the property to read or change.
Returns
unknownThe current value of the named property, with that property's type.
setrenderproperty
setrenderproperty(object: DrawingObject, property: string, value: unknown): ()setrenderproperty changes a property on a Drawing object, using its name.
Also available as set_render_property.
Parameters
objectDrawingObject- The Drawing object whose property will be accessed.
propertystring- The name of the property to read or change.
valueunknown- The new value of the named property, using the type required by that property.
Returns
()This function does not return a value.
cleardrawcache
cleardrawcache(): ()cleardrawcache removes every active drawing object and shader resource created with Drawing.new.
Also available as clear_draw_cache, cleardrawingcache and clear_drawing_cache.
Returns
()This function does not return a value.
Fonts
Drawing.Fonts and DrawingImmediate.Fonts provide the font IDs listed above. New Text objects use Drawing.Fonts.Plex (2). The Font property and immediate text functions also accept a custom font returned by DrawFont.Register.
Custom fonts
DrawFont.Register
YieldsDrawFont.Register(data: string, options: DrawFontOptions): DrawFont?DrawFont.Register loads font bytes from memory and returns a reusable, read-only font for Drawing and DrawingImmediate text.
Parameters
datastring- Raw supported font-file bytes, such as a TrueType file read with readfile. A file path or URL is not font data.
optionsDrawFontOptions- A table with required PixelSize and optional Glyphs. See the option fields below.
Returns
DrawFont?The font after registration and atlas upload complete, or nil if the font data cannot be loaded, registration is cancelled, or the font-resource budget is exhausted.
Example
PixelSizenumber (required)Glyphs{{number}}? = nilDrawFont:GetTextBounds
DrawFont:GetTextBounds(size: number, text: string): Vector2font:GetTextBounds measures a string using a registered custom font at the requested text size.
Parameters
sizenumber- Finite text size from 1 to 4096 pixels. This can differ from the font's registered PixelSize.
textstring- The text to measure, including any line breaks.
Returns
Vector2The width and height of the text in logical screen pixels.
Example
Common primitive properties
Visibleboolean = falseZIndexnumber = 1ColorColor3 = Color3.new(0,0,0)Transparencynumber = 1__OBJECT_EXISTSboolean (read-only):Remove() / :Destroy()() -> ()Line
From, ToVector2 = (0,0)Thicknessnumber = 0Circle
PositionVector2 = (0,0)Radiusnumber = 1Thicknessnumber = 16NumSidesnumber = 100Filledboolean = falseSquare
Position, SizeVector2 = (0,0)Thicknessnumber = 16Filledboolean = falseTriangle
PointA, PointB, PointCVector2 = (0,0)Thicknessnumber = 2Filledboolean = falseQuad
PointA, PointB, PointC, PointDVector2 = (0,0)Thicknessnumber = 2Filledboolean = falseText
Textstring = ""PositionVector2 = (0,0)Centerboolean = falseOutlineboolean = falseOutlineColorColor3 = blackOutlineTransparency / OutlineOpacitynumber = 1Sizenumber = 16Fontnumber | DrawFont = Drawing.Fonts.PlexTextBoundsVector2 (read-only)Image
DatastringUristringLoadedboolean = falsePosition, SizeVector2 = (0,0)OriginalSizeVector2 (read-only)ScaleFactornumber = 1Roundingnumber = 0Shader resource kinds
ShaderComputeBufferTextureRenderTargetMeshModelEffectParticlesShared resource state and drawing state
Backend"Auto" | "GPU" | "CPU" = "Auto"ActualBackend"GPU" | "CPU" | nil (read-only)LastErrorstring? (read-only)IsRemovedboolean (read-only)Visible, ZIndex, Transparencyfalse, 1, 1ColorColor3 = whitePositionVector2 = (0,0)SizeVector2 = (1,1)ResolutionScalenumber = 1UpdateRatenumber = 0Blend"Alpha" | "Add" | "Multiply" | "Opaque" = "Alpha"DepthTestboolean = falseBloomboolean | BloomOptions = falseShaderShader?BufferBuffer?MeshMesh?TextureTexture | RenderTarget | nilRenderTargetRenderTarget?Bindings{[string]: DrawingResource} = {}UniformsUniformMap = {}CPU, GPU and shader language
Backend="GPU" runs shaders on the graphics processor. Backend="CPU" runs them on the CPU; both modes use the same HLSL source, not Luau callbacks. Auto chooses GPU when available, otherwise CPU. It does not retry invalid shader source on CPU. Use compatible backends for a program and its bound resources.
Sourcestring = ""Domain"Canvas" | "Surface" = "Canvas"Vertexstring = ""UniformTypes{[string]: NumericType} = {}Structs{[string]: {{string, NumericType}}} = {}BindingTypes{[string]: BindingType} = {}float4 effect(float2 uv)float4 effect(Surface s)Vertex vertex(Vertex v)void compute(uint3 id)Engine-provided HLSL inputs
Time, DeltaTime, StepDeltaTimefloatFrameIndexuintResolutionfloat2OpacityfloatWorld, ViewProjection, NormalMatrixrow_major float4x4CameraPositionfloat3CanvasRect, FullResolutionfloat4VertexstructSurfacestructPixelInput, _EngineTint, engine paddingUniform values
Uniform and binding identifiers use letters/digits/underscore, start with a letter or underscore and contain 1..128 characters. UniformMap contains at most 256 names. Every numeric component must be finite. Declare uniforms through initial Uniforms, optionally assisted by UniformTypes; changing values is supported, adding/removing program uniform names or changing their types after allocation is rejected.
floatintuintboolfloat2float3float4float4x4{Type = NumericType, Value = value}BindingType
Type"Buffer" | "Texture" (required)ElementstringAccess"Read" | "ReadWrite" = "Read"A read-only Texture binding also provides a sampler named bindingNameSampler. Do not declare the same resource or sampler again in your HLSL. A pass supports at most 16 read bindings and 8 writable bindings; do not read and write the same resource in one pass. Compute output resources require Access="ReadWrite".
Compute properties
ThreadGroupSize{number, number, number} = {64,1,1}Groups{number, number, number} = {1,1,1}AutoDispatchboolean = falseBuffer and texture storage
Elementstring = "float4"Countnumber = 1Access"Read" | "ReadWrite" = "Read"Format"RGBA8" | "RGBA16F" | "R32F" = "RGBA8"SizeVector2 = (1,1)Datastring | {NumericValue} | {Record}:Upload(data, firstElement?):Readback()(table?, string?) or (string?, string?)For raw buffer strings, store fields in Structs order with 32-bit numeric components. Texture tables contain a flat list of components: RGBA8 uses values from 0 to 1, RGBA16F uses half-floats, and R32F uses float32. Data and Upload accept at most 256 MiB. Readback reads current resource contents; Data reads the configured data and is not a substitute for Readback.
Mesh, ModelEffect and particles
Vertices{MeshVertex} = {}MeshVertex.PositionVector3 | {number,number,number}MeshVertex.NormalMeshVertex.UVMeshVertex.ColorIndices{number} = {}TransformCFrame | {number}; identityTargetInstance? = nilCountnumber = 0Fields{Position: string?, Size: string?, Color: string?}Space"Screen" | "World" = "Screen"ModelEffect draws a separate effect over supported geometry; it does not replace the target's material. The geometry must be available on the client. Some meshes, including ones requiring deformed or skinned vertices, may not be supported. Reuse resources and avoid large readbacks every frame. Remove each resource when finished.
Resource methods
DrawingResource:Remove
DrawingResource:Remove(): ()DrawingResource:Remove removes a drawing resource and stops its rendering or automatic compute updates.
Also available as DrawingResource:Destroy.
Returns
()This function does not return a value.
DrawingResource:Compile
DrawingResource:Compile(): (boolean, string?)DrawingResource:Compile compiles a shader program or prepares a resource for use.
Returns
(boolean, string?)True and nil on success, or false and an error string if compilation or allocation fails.
DrawingResource:Upload
DrawingResource:Upload(data: string | table, firstElement: number?): (boolean, string?)DrawingResource:Upload copies new data into an existing buffer or texture.
Parameters
datastring | table- The bytes or structured values to upload, matching the buffer element layout or texture format.
firstElementnumber?- Optional.The zero-based buffer element at which the upload begins. Texture uploads start at 0. Default
0.
Returns
(boolean, string?)True and nil on success, or false and an error string if the upload fails.
DrawingResource:Readback
DrawingResource:Readback(): (table | string | nil, string?)DrawingResource:Readback reads the current contents of a buffer, texture or render target.
Returns
(table | string | nil, string?)A table of buffer elements or a string of texture bytes, followed by nil. Returns nil and an error string on failure.
DrawingResource:Resize
DrawingResource:Resize(size: Vector2): (boolean, string?)DrawingResource:Resize changes the dimensions of a texture or render target.
Parameters
sizeVector2- The new allocation dimensions. Both components must be integers from 1 to 16384.
Returns
(boolean, string?)True and nil on success, or false and an error string if resizing fails.
DrawingResource:SetUniform
DrawingResource:SetUniform(name: string, value: NumericValue): ()DrawingResource:SetUniform sets the value of a named shader uniform.
Parameters
namestring- The name used to declare the uniform in
Uniforms. valueNumericValue- The new uniform value, matching its declared numeric type.
Returns
()This function does not return a value.
DrawingResource:GetUniform
DrawingResource:GetUniform(name: string): NumericValue?DrawingResource:GetUniform gets the stored value of a named shader uniform.
Parameters
namestring- The name used to declare the uniform in
Uniforms.
Returns
NumericValue?The stored uniform value, or nil if the uniform has no stored value.
Compute:Dispatch
Compute:Dispatch(groupsX: number, groupsY: number, groupsZ: number, bindings: BindingMap?, uniforms: UniformMap?): ()Compute:Dispatch runs a compute program with the requested number of thread groups.
Parameters
groupsXnumber- The number of compute thread groups along the X axis, from 1 to 65535.
groupsYnumber- The number of compute thread groups along the Y axis, from 1 to 65535.
groupsZnumber- The number of compute thread groups along the Z axis, from 1 to 65535.
bindingsBindingMap?- Optional.The resources assigned to the program's named bindings. If omitted, uses its
Bindingsproperty. Defaultprogram.Bindings. uniformsUniformMap?- Optional.Named values that override the shader or compute program's declared uniform defaults. Default
{}.
Returns
()This function does not return a value.
Shader, compute and target example
Written for Lynx 0.747
Something unclear? Tell us on Discord