> ## Documentation Index
> Fetch the complete documentation index at: https://lua.starline.one/llms.txt
> Use this file to discover all available pages before exploring further.

# Renderer

> Draw shapes, text, textures, and world-space markers from paint callbacks.

Draw calls only work from a `paint` callback. Calling one anywhere else errors.

```lua theme={"dark"}
local font = renderer.default_font

events.On("paint", function()
    renderer.RectFilled(100, 100, 50, 50, Color(255, 0, 0))
    renderer.Text(font, "hello", 100, 160, Color(255, 255, 255), 14)
end)
```

## Draw

| Function                                                                           |
| ---------------------------------------------------------------------------------- |
| `Rect(x, y, w, h, color[, rounding[, thickness]])`                                 |
| `RectFilled(x, y, w, h, color[, rounding])`                                        |
| `Circle(x, y, radius, color[, thickness[, segments]])`                             |
| `CircleFilled(x, y, radius, color[, segments])`                                    |
| `CircleFilledGradient(x, y, radius, inner, outer[, segments])`                     |
| `Line(x1, y1, x2, y2, color[, thickness])`                                         |
| `Poly(points, color[, thickness[, closed]])`                                       |
| `PolyFilled(points, color)`                                                        |
| `Text(font, text, x, y, color, size[, centered])`                                  |
| `Image(texture, x, y, w, h[, tint[, rounding]])`                                   |
| `ShadowRect(x, y, w, h, color, thickness[, offset_x[, offset_y[, rounding]]])`     |
| `ShadowCircle(x, y, radius, color, thickness[, offset_x[, offset_y[, segments]]])` |

Bracketed trailing arguments are optional. Colors are [`Color`](/color) objects. Most `segments` arguments default to `0` (automatic); `ShadowCircle` defaults to `12`.

`points` is a flat array, at least two points:

```lua theme={"dark"}
renderer.PolyFilled({ 10,10, 60,10, 35,50 }, Color(255, 0, 0))
```

## Clipping

```lua theme={"dark"}
renderer.PushClip(x, y, w, h, intersect)
renderer.RectFilled(0, 0, 500, 500, Color(255, 0, 0))   -- only the clipped part shows
renderer.PopClip()
```

`intersect` is optional. Pass `true` to clip against the current rect instead of replacing it. Every `PushClip` needs a matching `PopClip`.

## MeasureText

```lua theme={"dark"}
local w, h = renderer.MeasureText(font, "hello", 14)
```

Returns two numbers. Callable from `paint` or at load time, nowhere else.

## WorldToScreen

```lua theme={"dark"}
local x, y = renderer.WorldToScreen(0, 0, 0)
if x then
    renderer.CircleFilled(x, y, 4, Color(255, 0, 0))
end
```

Returns two numbers, or `nil` when the position is behind the camera. Always check the first return before using it.

## Fonts

```lua theme={"dark"}
local font   = renderer.CreateFont('myfont.ttf', 14)
local tahoma = renderer.CreateFont('C:/Windows/Fonts/tahoma.ttf', 18)
```

| Name  | Type    |
| ----- | ------- |
| Path  | String  |
| Size  | Integer |
| Flags | Integer |

A bare filename resolves against `Documents\Starline\scripts`, so you can ship a `.ttf` with your script. A path containing `:` is used as-is.

`Flags` is optional and defaults to antialiased. Bits:

| Bit | Meaning        |
| --- | -------------- |
| 1   | antialias      |
| 2   | bold           |
| 4   | italic         |
| 8   | light hinting  |
| 16  | mono hinting   |
| 32  | force autohint |
| 64  | no hint        |
| 128 | bitmap         |

`renderer.default_font` is the menu font, always available.

Font and texture handles are opaque values, not numbers, and are not interchangeable. Passing a font where a texture is expected errors instead of drawing the wrong thing.

Load-time only. Fonts are cached by path, size and flags, so reloading your script reuses them.

## Textures

```lua theme={"dark"}
local logo = renderer.CreateTexture('logo.png')
local tex  = renderer.CreateTexture(data, 64, 64)
```

Two forms. Pass a path on its own to load an image file, or pass raw pixels with a size.

### From a file

| Name | Type   |
| ---- | ------ |
| Path | String |

Decodes PNG, JPG, BMP, TGA, GIF and PSD. The path works like [`CreateFont`](#fonts): a bare filename resolves against `Documents\Starline\scripts`, and a path containing `:` is used as-is.

### From raw pixels

| Name   | Type    |
| ------ | ------- |
| Data   | String  |
| Width  | Integer |
| Height | Integer |

`Data` must contain at least `Width * Height * 4` raw RGBA8 bytes. Extra bytes are ignored. Width and height must be from 1 to 4096.

Load-time only. Textures are freed when your script reloads or unloads.