# raylib

> Draw 2D and 3D graphics and read the keyboard and mouse in a raylib window, and use its colour, geometry and image helpers without one.

This is the Markdown version of https://osl-lang.org/packages/raylib. Every page of the OSL docs has one: add .md to its path. https://osl-lang.org/llms.txt lists them all.

```osl
import "std:raylib"
```

`std:raylib` is a window you draw into, once per frame: shapes, text, textures, 2D and 3D cameras, shaders, keyboard and mouse. It suits games, simulations and anything that moves. For forms and buttons, use [ui](/packages/ui.md) and [window](/packages/window.md) instead, or [raygui](/packages/raygui.md) for controls inside a raylib window.

Windows need SDL2 installed. Many helpers (colours, shapes for hit tests, cameras, image loading) work without a window, so the first examples run right here.

## Colours

Anything that takes a colour accepts a name, `"#rrggbb"`, `"#rgb"`, `"#rrggbbaa"` or `{r, g, b, a}`. `raylib.color` shows you what it understood:

```osl
import "std:raylib"

log raylib.color("raywhite")
log raylib.color("#f80")
log raylib.color({r: 1, g: 2, b: 3, a: 4})
```

Output:

```text
{"a":255,"b":245,"g":245,"r":245}
{"a":255,"b":0,"g":136,"r":255}
{"a":4,"b":3,"g":2,"r":1}
```

Try `"purple"` or `"#00ff0080"`. An unknown name throws a `ValueError`.

## Points and hit tests

`raylib.vec(x, y)` and `raylib.vec3(x, y, z)` build points. The `isPoint...` and `is...Overlapping` helpers answer the questions every game asks, with plain `{x, y, width, height}` rectangles and `{x, y, radius}` circles:

```osl
import "std:raylib"

auto button = {x: 1, y: 1, width: 100, height: 40}
log raylib.isPointInRect(raylib.vec(50, 20), button)
log raylib.isPointInRect(raylib.vec(150, 20), button)

auto a = {x: 1, y: 1, radius: 5}
auto b = {x: 4, y: 1, radius: 5}
log raylib.isCircleOverlapping(a, b)
log raylib.isRectOverlapping(button, {x: 90, y: 30, width: 20, height: 20})
```

Output:

```text
true
false
true
true
```

Positions count from 1, like everything in OSL, so `{x: 1, y: 1}` is the top-left pixel.

**Quiz.** Which point is inside `{x: 1, y: 1, width: 10, height: 10}`?

- [ ] `{x: 0, y: 0}`
- [x] `{x: 5, y: 5}`
- [ ] `{x: 11, y: 11}`

Answer: The rectangle starts at pixel 1 and is 10 wide, so it covers 1 to 10.

## Your first window

`raylib.initWindow` opens a window, `windowShouldClose()` becomes true when the user closes it (or presses Escape), and `raylib.draw(frame)` draws one frame. Window code can't run here, so it is marked as compile-only. Copy it to your machine:

```osl
import "std:raylib"

raylib.initWindow(800, 450, "Hello", {fps: 60}).unwrap()

while !raylib.windowShouldClose() (
  raylib.draw(def() (
    raylib.clear("#181825")
    raylib.text("Hello, World!", {x: 281, y: 201}, {size: 36, color: "#89b4fa"})
  ))
)

raylib.closeWindow()
```

Change the colours and the text. Everything on screen is drawn inside `raylib.draw`.

## The shorter loop

`raylib.runWindow(frame, options)` opens the window, calls `frame(ms)` every frame with the time the last frame took, and closes the window at the end. `background` clears for you, and `frames` stops after that many frames (handy for tests):

```osl
import "std:raylib"

number x = 20

raylib.runWindow(def(ms) (
  if raylib.isKeyDown("right") ( x += 0.3 * ms )
  if raylib.isKeyDown("left") ( x -= 0.3 * ms )
  raylib.rectangle({x: x, y: 200, width: 40, height: 40}, "#89b4fa")
  raylib.text("Arrow keys move the square", {x: 20, y: 20})
), {width: 800, height: 450, title: "Move", background: "#181825"})
```

Multiplying by `ms` makes the speed the same on a slow computer and a fast one. Here the square moves 300 pixels a second.

## Shapes and text

`rectangle`, `circle`, `line`, `polygon` and `pixel` take geometry and a colour. A `lineWidth` option draws only the outline, `radius` rounds a rectangle:

```osl
import "std:raylib"

raylib.runWindow(def(ms) (
  raylib.rectangle({x: 40, y: 40, width: 200, height: 100}, "#89b4fa", {radius: 12})
  raylib.rectangle({x: 40, y: 40, width: 200, height: 100}, "white", {lineWidth: 2})
  raylib.circle({x: 400, y: 90}, 40, "#f38ba8")
  raylib.line({x: 40, y: 200}, {x: 700, y: 260}, "#a6e3a1", {thickness: 3})
  raylib.polygon([{x: 500, y: 300}, {x: 600, y: 300}, {x: 550, y: 380}], "#f9e2af")
  raylib.text("Shapes", {x: 40, y: 300}, {size: 40, color: "white"})
), {background: "#181825", frames: 600})
```

`raylib.useFont(path, baseSize)` makes text use a TTF or OTF font, and `raylib.measureText(text, size)` tells you how wide it will be, for centring.

## Keyboard and mouse

`isKeyDown` is true while a key is held, `isKeyPressed` only on the frame it went down. Keys are named (`"space"`, `"enter"`, `"left"`, `"f1"`) or a single character. The mouse has the same trio with buttons `"left"`, `"right"` and `"middle"`, plus `mousePosition()`:

```osl
import "std:raylib"

int clicks = 0
auto target = {x: 300, y: 150, width: 200, height: 100}

raylib.runWindow(def(ms) (
  auto mouse = raylib.mousePosition()
  auto over = raylib.isPointInRect(mouse, target)
  if over and raylib.isMousePressed("left") ( clicks += 1 )

  raylib.rectangle(target, if over then "#a6e3a1" else "#89b4fa")
  raylib.text("clicks: " ++ clicks, {x: 20, y: 20}, {size: 30, color: "white"})
), {background: "#181825"})
```

`nextChar()` returns characters as they are typed, with the keyboard layout applied, which is what a text box wants.

## Images and textures

An image lives in memory, and a texture lives on the graphics card and is what you draw. `raylib.loadTexture(path)` loads a file as a texture, and `tex.drawAt(position, options)` draws it, with `scale`, `rotation`, `tint` and `source` (a part of the texture, for sprite sheets):

```osl
import "std:raylib"

raylib.initWindow(640, 360, "Sprite").unwrap()
auto sprite = raylib.loadTexture("player.png").unwrap()
sprite.setFilter("bilinear").unwrap()

while !raylib.windowShouldClose() (
  raylib.draw(def() (
    raylib.clear("#181825")
    sprite.drawAt({x: 100, y: 100}, {scale: 2, tint: "white"})
  ))
)
raylib.closeWindow()
```

Images from [img](/packages/img.md) work too: `raylib.textureFromImage(pic)` uploads one, so anything you drew with img can be shown, and `raylib.screenshot()` returns the window's contents as an `*img.Image`.

## Loading an image without a window

`raylib.loadImage(path)` needs no window. It returns a `raylib.Image`, and `toImage()` hands you a normal `*img.Image`:

```osl
import "std:raylib"
import "std:img"
import "std:fs"

raylib.setLogLevel("none")
fs.remove("blue.png", {force: true}).unwrap()
img.new(4, 3, {fill: "#336699"}).save("blue.png").unwrap()

auto loaded = raylib.loadImage("blue.png").unwrap()
log loaded.width() loaded.height()

*img.Image pic = loaded.toImage()
log pic.pixel(1, 1)
fs.remove("blue.png").unwrap()
```

Output:

```text
4 3
#336699
```

> **Note**
>
> Prefer `img.decodeFile` for images you don't draw with raylib. It reads more formats, returns an `*img.Image` at once and needs no conversion.

## A 2D camera

`raylib.camera2D({target, offset, zoom, rotation})` pans, zooms and rotates everything drawn inside `cam.use(...)`. The target is the world point shown at the offset on screen. It also converts between the two, so a click can find the world point under it:

```osl
import "std:raylib"

auto cam = raylib.camera2D({target: {x: 100, y: 100}, offset: {x: 50, y: 50}, zoom: 2})
log cam.toScreen({x: 100, y: 100})
log cam.toScreen({x: 110, y: 100})
log cam.toWorld({x: 50, y: 50})
```

Output:

```text
{"x":50,"y":50}
{"x":70,"y":50}
{"x":100,"y":100}
```

The world point 100, 100 appears at the screen's 50, 50, and 10 units to its right is 20 pixels away because of the zoom. Change `zoom` to 1 and run again. Inside a window:

```osl
import "std:raylib"

auto cam = raylib.camera2D({offset: {x: 400, y: 225}, zoom: 1})

raylib.runWindow(def(ms) (
  if raylib.isKeyDown("a") ( cam.setZoom(cam.zoom() * 1.01) )
  if raylib.isKeyDown("z") ( cam.setZoom(cam.zoom() / 1.01) )
  cam.use(def() (
    raylib.circle({x: 0, y: 0}, 50, "#f38ba8")
    raylib.rectangle({x: 100, y: -20, width: 80, height: 40}, "#89b4fa")
  ))
), {background: "#181825"})
```

## 3D

`raylib.camera({position, target, fovy})` is a 3D camera. Inside `cam.use`, `cube`, `sphere`, `cylinder`, `plane`, `grid` and `line3D` draw in world space. `cam.control("orbital")` moves the camera from the keyboard and mouse:

```osl
import "std:raylib"

auto cam = raylib.camera({position: raylib.vec3(6, 5, 6), target: raylib.vec3(0, 1, 0), fovy: 60})

raylib.runWindow(def(ms) (
  cam.control("orbital")
  cam.use(def() (
    raylib.grid(10, 1)
    raylib.cube(raylib.vec3(0, 1, 0), raylib.vec3(2, 2, 2), "#89b4fa")
    raylib.cube(raylib.vec3(0, 1, 0), raylib.vec3(2, 2, 2), "white", {wireframe: true})
    raylib.sphere(raylib.vec3(3, 0.5, 0), 0.5, "#f38ba8")
  ))
), {background: "#181825"})
```

Picking works with rays. `raylib.ray(origin, direction).box(center, size)` says whether it hits a box, and where:

```osl
import "std:raylib"

auto ray = raylib.ray(raylib.vec3(0, 0, -10), raylib.vec3(0, 0, 1))
auto hit = ray.box(raylib.vec3(0, 0, 0), raylib.vec3(2, 2, 2))
log hit.hit hit.distance
log ray.box(raylib.vec3(5, 5, 5), raylib.vec3(1, 1, 1)).hit
```

Output:

```text
true 9
false
```

## Render textures, blending and shaders

`raylib.renderTexture(w, h)` is an off-screen surface. Draw into it with `tex.use(...)`, then draw it on screen with `tex.drawAt` or save it with `tex.toImage()`. `raylib.blend("additive", draw)` changes how overlapping colours mix. `raylib.compileShader(code)` compiles a GPU [shader](/packages/shader.md), and `shader.use(draw)` draws through it. `raylib.smoothLines(draw)` draws anti-aliased lines in one batch.

### Exercise: Hit test

A button is at `{x: 10, y: 10, width: 100, height: 30}`. Use `raylib.isPointInRect` to print, for each click point in the list, whether it hit the button.

Starting code:

```osl
import "std:raylib"

auto button = {x: 10, y: 10, width: 100, height: 30}
auto clicks = [{x: 20, y: 20}, {x: 200, y: 20}, {x: 109, y: 39}]

log button.width clicks.len
```

It should print:

```text
true
false
true
```

Hint 1: Loop over `clicks` and log `raylib.isPointInRect(click, button)`.

Hint 2: The rectangle covers x from 10 to 109 and y from 10 to 39.

A solution:

```osl
import "std:raylib"

auto button = {x: 10, y: 10, width: 100, height: 30}
auto clicks = [{x: 20, y: 20}, {x: 200, y: 20}, {x: 109, y: 39}]

for click in clicks (
  log raylib.isPointInRect(click, button)
)
```

### Exercise: Where does it appear?

A 2D camera looks at the world point 200, 100, shown at the screen point 400, 300, with no zoom. Print the screen position of the world point 250, 100.

Starting code:

```osl
import "std:raylib"

auto cam = raylib.camera2D({target: {x: 200, y: 100}, offset: {x: 400, y: 300}})

log cam.toScreen({x: 200, y: 100})
```

It should print:

```text
{"x":450,"y":300}
```

Hint 1: Ask the camera: `cam.toScreen({x: 250, y: 100})`.

A solution:

```osl
import "std:raylib"

auto cam = raylib.camera2D({target: {x: 200, y: 100}, offset: {x: 400, y: 300}})

log cam.toScreen({x: 250, y: 100})
```

## API reference

## API reference

Every member of `std:raylib`, generated from the source of OSL.

### Functions

#### `raylib.begin3D(*raylib.Camera camera) boolean`

**Deprecated.** Deprecated: use camera.use(draw) instead.

begin3D starts drawing through a 3D camera.

#### `raylib.beginBlend(any mode)`

**Deprecated.** Deprecated: use raylib.blend(mode, draw) instead.

beginBlend switches the blend mode; unknown modes mean "alpha".

#### `raylib.beginDrawing()`

**Deprecated.** Deprecated: use raylib.draw(frame) instead, which ends the frame even when frame throws.

beginDrawing starts a frame.

#### `raylib.beginShader(*raylib.Shader s) boolean`

**Deprecated.** Deprecated: use shader.use(draw) instead.

beginShader starts drawing through a shader and returns false for an
invalid one.

#### `raylib.blend(string mode, any draw)`

blend runs draw with a blend mode: "alpha" (normal), "additive",
"multiply", "premultiplied", or "layer" (alpha blending that keeps a
transparent render texture premultiplied, for compositing it later with
"premultiplied"). Throws ValueError for an unknown mode.

#### `raylib.camera(object? options) *raylib.Camera`

camera builds a 3D camera. Options: position and target ({x, y, z}, the
camera's place and what it looks at; default the origin), up (default
{x: 0, y: 1, z: 0}), fovy (vertical field of view in degrees, or the view
height for an orthographic camera; default 60) and projection
("perspective", the default, or "orthographic").

#### `raylib.camera2D(object? options) *raylib.Camera2D`

camera2D builds a 2D camera. Options: target (the world point {x, y} the
camera looks at; default {x: 1, y: 1}), offset (where on screen that
point appears, {x, y}; default {x: 1, y: 1}, the top-left pixel),
rotation (degrees, default 0) and zoom (default 1). World points count
from 1 like window positions, so the default camera draws everything
where it would be drawn without one.

#### `raylib.centerRay(*raylib.Camera camera) *raylib.Ray`

**Deprecated.** Deprecated: use camera.centerRay() instead.

centerRay returns the ray from a camera through the middle of the screen.

#### `raylib.circle(any center, number radius, any color, object? options)`

circle draws a circle around a center {x, y}, filled unless lineWidth is
given. Options: lineWidth (draw only the outline, this thick).

#### `raylib.circlesCollide(any first, any firstRadius, any second, any secondRadius) boolean`

**Deprecated.** Deprecated: use raylib.isCircleOverlapping({x, y, radius}, {x, y, radius}) instead.

circlesCollide reports whether two circles overlap.

#### `raylib.clear(any color)`

clear fills the whole drawing target with a color.

#### `raylib.closeWindow()`

closeWindow closes the window and its graphics context. Closing when no
window is open does nothing.

#### `raylib.color(any value) {a: int, b: int, g: int, r: int}`

color reads a color and returns it as {r, g, b, a}. It accepts "#rrggbb",
"#rrggbbaa", "#rgb", "#rgba", raylib's color names ("black", "white",
"red", "green", "blue", "yellow", "orange", "purple", "pink", "gray",
"transparent", "raywhite") and {r, g, b, a}; every raylib function that
takes a color accepts the same. Throws ValueError for anything else.

#### `raylib.compileShader(string code, object? options) result<*raylib.Shader, error>`

compileShader compiles a fragment shader for drawing. code is GLSL 330 or
OSL-style shader code (see shader.transpile). Options: vertex (vertex
shader code; default raylib's). Fails with StateError when no window is
open and ParseError when the GPU driver rejects the code (raylib logs the
driver's message).

#### `raylib.compileShaderFile(string path, object? options) result<*raylib.Shader, error>`

compileShaderFile compiles a fragment shader from a file, like
compileShader. Options: vertex (a vertex shader file; default raylib's).
Fails with StateError when no window is open, NotFoundError or IOError
when a file can't be read, and ParseError when the code doesn't compile.

#### `raylib.cube(any center, any size, any color, object? options)`

cube draws a box around a center {x, y, z} with a size {x, y, z}.
Options: wireframe (draw only the edges).

#### `raylib.cursorHidden() boolean`

**Deprecated.** Deprecated: use raylib.isCursorHidden() instead.

cursorHidden reports whether the mouse cursor is hidden.

#### `raylib.cylinder(any from, any to, any color, object? options)`

cylinder draws a cylinder or cone from one point {x, y, z} to another.
Options: radius (default 1), topRadius (the radius at to; default radius,
0 makes a cone), slices (default 16) and wireframe.

#### `raylib.disableCursor()`

disableCursor hides and locks the mouse cursor, for mouse-look controls.

#### `raylib.dpiScale() number`

dpiScale returns framebuffer pixels per window unit (2 on most retina
screens). It is measured rather than taken from the platform, which some
backends report incorrectly.

#### `raylib.draw(any frame)`

draw runs frame to draw one frame of the window and shows the result.
Everything drawn on screen happens inside it. Throws StateError when no
window is open.

#### `raylib.draw3D(*raylib.Camera camera, any frame) boolean`

**Deprecated.** Deprecated: use camera.use(frame) instead.

draw3D runs frame drawing through a 3D camera.

#### `raylib.drawBillboard(*raylib.Camera camera, *raylib.Texture texture, any position, any size, any tint) boolean`

**Deprecated.** Deprecated: use texture.drawBillboard(camera, position, {size, tint}) instead.

drawBillboard draws a texture facing the camera and returns false for a
missing camera or invalid texture.

#### `raylib.drawCube(any center, any size, any color)`

**Deprecated.** Deprecated: use raylib.cube(center, size, color) instead.

drawCube draws a solid box.

#### `raylib.drawCubeWires(any center, any size, any color)`

**Deprecated.** Deprecated: use raylib.cube(center, size, color, {wireframe: true}) instead.

drawCubeWires draws a box's edges.

#### `raylib.drawCylinder(any position, any radiusTop, any radiusBottom, any height, any slices, any color)`

**Deprecated.** Deprecated: use raylib.cylinder(from, to, color, {radius, topRadius, slices}) instead.

drawCylinder draws a cylinder standing on position.

#### `raylib.drawGrid(any slices, any spacing)`

**Deprecated.** Deprecated: use raylib.grid(slices, spacing) instead.

drawGrid draws a ground grid.

#### `raylib.drawLine3D(any start, any end, any color)`

**Deprecated.** Deprecated: use raylib.line3D(from, to, color) instead.

drawLine3D draws a 3D line.

#### `raylib.drawPlane(any center, any size, any color)`

**Deprecated.** Deprecated: use raylib.plane(center, {x, z}, color) instead.

drawPlane draws a ground rectangle.

#### `raylib.drawSphere(any center, any radius, any color)`

**Deprecated.** Deprecated: use raylib.sphere(center, radius, color) instead.

drawSphere draws a solid sphere.

#### `raylib.drawSphereWires(any center, any radius, any rings, any slices, any color)`

**Deprecated.** Deprecated: use raylib.sphere(center, radius, color, {wireframe: true, rings, slices}) instead.

drawSphereWires draws a sphere's wireframe.

#### `raylib.drawToTexture(*raylib.RenderTexture target, any drawFunc) boolean`

**Deprecated.** Deprecated: use renderTexture.use(draw) instead.

drawToTexture runs drawFunc drawing into a render texture and returns
false for an invalid one.

#### `raylib.elapsed() number`

elapsed returns the milliseconds since the window was opened.

#### `raylib.enableCursor()`

enableCursor shows and unlocks the mouse cursor.

#### `raylib.end3D()`

**Deprecated.** Deprecated: use camera.use(draw) instead.

end3D stops drawing through a 3D camera.

#### `raylib.endBlend()`

**Deprecated.** Deprecated: use raylib.blend(mode, draw) instead.

endBlend restores normal alpha blending.

#### `raylib.endDrawing()`

**Deprecated.** Deprecated: use raylib.draw(frame) instead.

endDrawing ends a frame and shows it.

#### `raylib.endShader()`

**Deprecated.** Deprecated: use shader.use(draw) instead.

endShader stops drawing through a shader.

#### `raylib.fps() int`

fps returns the frames drawn in the last second.

#### `raylib.frameDuration() number`

frameDuration returns how long the last frame took, in milliseconds.

#### `raylib.frameTime() number`

**Deprecated.** Deprecated: use raylib.frameDuration() instead; it returns milliseconds.

frameTime returns how long the last frame took, in seconds.

#### `raylib.gpuPreference() string`

gpuPreference returns "integrated" or "discrete".

#### `raylib.grid(int slices, number spacing)`

grid draws a ground grid of slices by slices squares, spacing apart,
centred on the origin.

#### `raylib.initWindow(int width, int height, string title, object? options) result<unit, error>`

initWindow opens the program's window, width by height window units, and
its graphics context; most other functions need it open. Options: fps
(frames per second to aim for) and the window flags highdpi, resizable,
vsync, msaa, transparent, undecorated, borderless, topmost, hidden and
alwaysRun (booleans, default false). A hidden window can show for a
moment as it opens, since SDL2 opens every window shown. Throws
ValueError for transparent, which SDL2's windows can't be. Fails with
StateError when a window is already open and RuntimeError when one can't
be opened.

#### `raylib.isCircleOverlapping(any a, any b) boolean`

isCircleOverlapping reports whether two circles {x, y, radius} overlap.

#### `raylib.isCursorHidden() boolean`

isCursorHidden reports whether the mouse cursor is hidden.

#### `raylib.isKeyDown(string key) boolean`

isKeyDown reports whether key is held down. Keys are named as for
isKeyPressed.

#### `raylib.isKeyPressed(string key) boolean`

isKeyPressed reports whether key went down this frame. Keys are names
("space", "escape", "enter", "tab", "backspace", "insert", "delete",
arrow keys "left"/"right"/"up"/"down", "pageup", "pagedown", "home",
"end", "shift", "ctrl", "alt" and their "left"/"right" forms, "f1" to
"f12") or single characters ("a", "1", "/"). Throws ValueError for an
unknown key.

#### `raylib.isKeyReleased(string key) boolean`

isKeyReleased reports whether key came up this frame. Keys are named as
for isKeyPressed.

#### `raylib.isMouseDown(string button) boolean`

isMouseDown reports whether a mouse button is held down. Buttons are
named as for isMousePressed.

#### `raylib.isMousePressed(string button) boolean`

isMousePressed reports whether a mouse button ("left", "right",
"middle", "side" or "extra") went down this frame. Throws ValueError for
an unknown button.

#### `raylib.isMouseReleased(string button) boolean`

isMouseReleased reports whether a mouse button came up this frame.
Buttons are named as for isMousePressed.

#### `raylib.isPointInCircle(any point, any circle) boolean`

isPointInCircle reports whether a point {x, y} is inside a circle
{x, y, radius}.

#### `raylib.isPointInRect(any point, any rect) boolean`

isPointInRect reports whether a point {x, y} is inside a rectangle
{x, y, width, height}.

#### `raylib.isRectOverlapping(any a, any b) boolean`

isRectOverlapping reports whether two rectangles {x, y, width, height}
overlap.

#### `raylib.isWindowReady() boolean`

isWindowReady reports whether a window is open.

#### `raylib.keyDown(any key) boolean`

**Deprecated.** Deprecated: use raylib.isKeyDown(key) instead.

keyDown reports whether a key, by name or key code, is held down.

#### `raylib.keyPressed(any key) boolean`

**Deprecated.** Deprecated: use raylib.isKeyPressed(key) instead.

keyPressed reports whether a key, by name or key code, went down this
frame.

#### `raylib.keyReleased(any key) boolean`

**Deprecated.** Deprecated: use raylib.isKeyReleased(key) instead.

keyReleased reports whether a key, by name or key code, came up this
frame.

#### `raylib.line(any from, any to, any color, object? options)`

line draws a straight line between two points {x, y}. Options: thickness
(default 1).

#### `raylib.line3D(any from, any to, any color)`

line3D draws a line between two points {x, y, z}.

#### `raylib.loadFragmentShader(any fs) *raylib.Shader`

**Deprecated.** Deprecated: use raylib.compileShader(code) or raylib.compileShaderFile(path) instead.

loadFragmentShader loads a fragment shader from a file or code; check
valid() afterwards.

#### `raylib.loadImage(string path) result<*raylib.Image, error>`

loadImage loads an image file (PNG, BMP, TGA, JPEG, GIF, QOI, HDR, PSD,
...) into memory; no window is needed. Fails with NotFoundError or IOError
when the file can't be read and ParseError when it isn't an image raylib
can decode.

#### `raylib.loadSVG(string path, number scale) result<*raylib.Image, error>`

loadSVG rasterises an SVG file at scale, rounding the size up and
stretching the drawing to fill it. Fails with NotFoundError or IOError
when the file can't be read, ParseError when it isn't an SVG with a size,
and ValueError when the image would be over 67 million pixels; throws
ValueError for a scale that isn't positive.

#### `raylib.loadSVGCanvas(string path, number scale) result<*raylib.Image, error>`

loadSVGCanvas rasterises an SVG the way a browser draws it onto a canvas
that is width * scale by height * scale (sizes truncated, as canvas
dimensions are), with the drawing at exactly that scale. Fails like
loadSVG.

#### `raylib.loadShader(any vs, any fs) *raylib.Shader`

**Deprecated.** Deprecated: use raylib.compileShader(code, {vertex}) or raylib.compileShaderFile(path, {vertex}) instead.

loadShader loads a vertex and fragment shader, each from a file when one
exists at that path and as code otherwise; check valid() afterwards.

#### `raylib.loadTexture(string path) result<*raylib.Texture, error>`

loadTexture loads an image file (PNG, BMP, TGA, JPEG, GIF, QOI, HDR, PSD,
...) onto the GPU. Fails with StateError when no window is open,
NotFoundError or IOError when the file can't be read, and ParseError when
it isn't an image raylib can decode.

#### `raylib.measureText(string text, number size) int`

measureText returns how wide text is at an em size, in window units.

#### `raylib.mouseDelta() {x: number, y: number}`

mouseDelta returns how far the mouse moved {x, y} since the last frame.

#### `raylib.mouseDown(any button) boolean`

**Deprecated.** Deprecated: use raylib.isMouseDown(button) instead.

mouseDown reports whether a mouse button is held down.

#### `raylib.mousePosition() {x: number, y: number}`

mousePosition returns the mouse position {x, y} in window units, 1, 1
over the top-left pixel, the way drawing calls take positions.

#### `raylib.mousePressed(any button) boolean`

**Deprecated.** Deprecated: use raylib.isMousePressed(button) instead.

mousePressed reports whether a mouse button, by name or number, went down
this frame; unknown names mean the left button.

#### `raylib.mouseReleased(any button) boolean`

**Deprecated.** Deprecated: use raylib.isMouseReleased(button) instead.

mouseReleased reports whether a mouse button came up this frame.

#### `raylib.mouseWheel() number`

mouseWheel returns how far the mouse wheel turned this frame; positive is
away from the user.

#### `raylib.nextChar() string?`

nextChar returns the next character typed since the last call, with
shift and the keyboard layout applied, or null when the queue is empty.

#### `raylib.nextKey() string?`

nextKey returns the next key pressed since the last call, named as
isKeyPressed names keys, or null when the queue is empty. Keys without a
name are skipped.

#### `raylib.off(string event, any handler)`

off removes a handler added with on. Removing one that isn't registered
does nothing.

#### `raylib.on(string event, any handler)`

on adds handler for an event. "resize" runs while the window is being
resized by dragging its edge: on macOS the program's loop is paused until
the drag ends, so the handler is the only chance to redraw (fit the
content, then draw a frame) during it. Throws ValueError for an unknown
event.

#### `raylib.onResize(any handler)`

**Deprecated.** Deprecated: use raylib.on("resize", handler) instead.

onResize sets the one handler run while the window is being resized,
replacing any earlier one.

#### `raylib.pixel(any point, any color)`

pixel draws one pixel at a point {x, y}; {x: 1, y: 1} is the top-left
pixel.

#### `raylib.plane(any center, any size, any color)`

plane draws a flat rectangle on the ground (the x-z plane) around a center
{x, y, z}, size {x, z} across.

#### `raylib.pointInRectangle(any point, any rectangle) boolean`

**Deprecated.** Deprecated: use raylib.isPointInRect(point, rect) instead.

pointInRectangle reports whether a point is inside a rectangle.

#### `raylib.polygon(array points, any color, object? options)`

polygon draws a convex polygon through three or more points {x, y}, in
either winding order, filled unless lineWidth is given. Options:
lineWidth (draw only the outline, this thick).

#### `raylib.pressedChar() string`

**Deprecated.** Deprecated: use raylib.nextChar() instead; it returns null when there is none.

pressedChar returns the next typed character, or "" when there is none.

#### `raylib.pressedKey() string`

**Deprecated.** Deprecated: use raylib.nextKey() instead; it returns null when there is none.

pressedKey returns the next pressed key's name, or "" when there is none.

#### `raylib.ray(any origin, any direction) *raylib.Ray`

ray builds a ray from an origin {x, y, z} in a direction {x, y, z}.

#### `raylib.rect(any x, any y, any width, any height) object`

**Deprecated.** Deprecated: write the object {x, y, width, height} instead.

rect builds a rectangle {x, y, width, height}.

#### `raylib.rectangle(any rect, any color, object? options)`

rectangle draws a rectangle {x, y, width, height}, x, y its top-left
corner, filled unless lineWidth is given. Options: lineWidth (draw only
the outline, this thick) and radius (round the corners by this many
units).

#### `raylib.rectanglesCollide(any first, any second) boolean`

**Deprecated.** Deprecated: use raylib.isRectOverlapping(a, b) instead.

rectanglesCollide reports whether two rectangles overlap.

#### `raylib.renderTexture(int width, int height) result<*raylib.RenderTexture, error>`

renderTexture makes an off-screen texture of width by height pixels to
draw into with use(), then draw on screen with drawAt() or pass to a
shader. Fails with StateError when no window is open and RuntimeError when
the GPU can't make one; throws ValueError for a size that isn't positive.

#### `raylib.run(object options, any update, any draw)`

**Deprecated.** Deprecated: use raylib.runWindow(frame, options) instead; frame gets milliseconds.

run opens a window from an options object and calls update(seconds) and
draw() once a frame until the window closes.

#### `raylib.runWindow(any frame, object? options) result<unit, error>`

runWindow opens a window, calls frame(ms) once a frame inside draw with
the previous frame's duration in milliseconds until the window is asked
to close, then closes it. Options: width (default 800), height (450),
title ("OSL raylib"), fps (60), background (a color to clear each frame
to), frames (stop after this many; 0, the default, runs until closed) and
the window flags of initWindow. When a window is already open it is used
and left open. Fails with RuntimeError when a window can't be opened.

#### `raylib.screenSize() {height: int, width: int}`

screenSize returns the window's {width, height} in window units.

#### `raylib.screenshot() result<*img.Image, error>`

screenshot returns what the window shows as a new img.Image from
std:img, at the framebuffer's full resolution on high-DPI screens and
fully opaque. Fails with StateError when no window is open.

#### `raylib.setConfigFlags(any flags)`

**Deprecated.** Deprecated: pass flags as initWindow options instead, such as {highdpi: true, resizable: true}.

setConfigFlags sets window flags for the next window from a "a|b" string,
an array of names, or a number; unknown names are ignored.

#### `raylib.setGPUPreference(string preference) string`

setGPUPreference chooses the GPU for windows opened afterwards:
"integrated" (the default, lower power) or "discrete" ("dedicated" and
"high_performance" mean the same). It returns the preference now in
effect. Throws ValueError for anything else.

#### `raylib.setLogLevel(string level)`

setLogLevel sets which of raylib's own log messages are printed: "all",
"trace", "debug", "info" (raylib's default), "warning", "error", "fatal" or
"none". Throws ValueError for anything else.

#### `raylib.setMousePosition(number x, number y)`

setMousePosition moves the mouse cursor to x, y in window units, 1, 1
being the top-left pixel as for mousePosition.

#### `raylib.setSVGFont(string family, string path) boolean`

**Deprecated.** Deprecated: use svg.addFont(family, path) instead.

setSVGFont registers the font file used for SVG text in a font family and
returns false when it can't be loaded.

#### `raylib.setTargetFPS(int fps)`

setTargetFPS caps the frame rate; 0 means no cap.

#### `raylib.setWindowSize(int width, int height)`

setWindowSize resizes the window to width by height window units. Throws
StateError when no window is open.

#### `raylib.setWindowTitle(string title)`

setWindowTitle changes the window's title. Throws StateError when no
window is open.

#### `raylib.shader(any code) *raylib.Shader`

**Deprecated.** Deprecated: use raylib.compileShader(code) instead.

shader loads a fragment shader from a file or code; check valid()
afterwards.

#### `raylib.smoothLine(any from, any to, any color, object? options)`

smoothLine draws an antialiased line with round caps between two points
{x, y}; a zero-length line draws a round dot. Options: thickness (default
1). Throws StateError outside raylib.smoothLines.

#### `raylib.smoothLines(any draw) result<unit, error>`

smoothLines runs draw, in which smoothLine draws antialiased round-capped
lines with premultiplied alpha, all sent to the GPU in one batch at the
end. Fails with StateError when no window is open and RuntimeError when
the line shader doesn't compile.

#### `raylib.sphere(any center, number radius, any color, object? options)`

sphere draws a sphere around a center {x, y, z}. Options: wireframe,
rings (default 16) and slices (default 16).

#### `raylib.svgSize(string path, number scale) int[]`

**Deprecated.** Deprecated: use raylib.loadSVG(path, scale) and the image's width() and height() instead.

svgSize returns the [width, height] loadSVG gives an SVG at scale, or
[0, 0].

#### `raylib.svgViewBox(string path) number[]`

**Deprecated.** Deprecated: use svg.infoFile(path) instead.

svgViewBox returns an SVG file's viewBox as [x, y, width, height], or
zeros.

#### `raylib.takeScreenshot(string path) result<unit, error>`

takeScreenshot saves what the window shows to an image file (PNG by
extension). Fails with StateError when no window is open and IOError when
the file can't be written.

#### `raylib.text(string text, any position, object? options)`

text draws text with its top-left corner at a point {x, y}. Options: size
(em size, default 20) and color (default "#000000").

#### `raylib.textHeight(number size) number`

textHeight returns the line height text uses for an em size: the font's
ascent plus descent, or the size itself with raylib's default font.

#### `raylib.textureFromImage(*img.Image image, object? options) result<*raylib.Texture, error>`

textureFromImage uploads an img.Image from std:img to the GPU as a
texture, so anything drawn with img can be shown in the window. Later
changes to the image don't reach the texture. Options: premultiplied, as
for Image.toTexture. Fails with StateError when no window is open; throws
StateError when the image is closed and TypeError for null.

#### `raylib.time() number`

**Deprecated.** Deprecated: use raylib.elapsed() instead; it returns milliseconds.

time returns the seconds since the window was opened.

#### `raylib.useFont(string path, int baseSize) result<unit, error>`

useFont makes text and measureText use a TTF or OTF font, rasterised at
baseSize pixels and smoothly scaled; sizes passed to them are em sizes, as
in CSS. Fails with StateError when no window is open, NotFoundError or
IOError when the file can't be read, and ParseError when it isn't a font.

#### `raylib.vec(number x, number y) {x: number, y: number}`

vec builds a 2D point {x, y}.

#### `raylib.vec3(number x, number y, number z) {x: number, y: number, z: number}`

vec3 builds a 3D point {x, y, z}.

#### `raylib.windowReady() boolean`

**Deprecated.** Deprecated: use raylib.isWindowReady() instead.

windowReady reports whether a window is open.

#### `raylib.windowShouldClose() boolean`

windowShouldClose reports whether the user asked to close the window
(its close button or Escape). Throws StateError when no window is open.

### `*raylib.Texture`

#### `texture.close()`

close frees the texture's GPU memory. A texture from a render texture's
texture() belongs to it and is freed with it; closing that one only stops
it being used. Closing twice does nothing; drawing a closed texture
throws StateError.

#### `texture.drawAt(any position, object? options)`

drawAt draws the texture with its top-left corner at a point {x, y}.
Options: scale (default 1), rotation (degrees around origin, default 0),
tint (a color multiplied in, default "#ffffff"), source (the part of the
texture to draw, {x, y, width, height} in texture pixels with x, y its
top-left pixel, 1, 1 for the texture's corner; default all of it; a
negative width or height flips it), width and height (the drawn size;
default the source size times scale) and origin (how far {x, y} from the
drawn rectangle's top-left corner the point is that position and rotation
refer to; default {x: 0, y: 0}). Throws StateError when the texture is
closed.

#### `texture.drawBillboard(*raylib.Camera camera, any position, object? options)`

drawBillboard draws the texture in 3D at a point {x, y, z}, always facing
the camera. Call it inside camera.use. Options: size (world units tall,
default 1) and tint (default "#ffffff"). Throws StateError when the
texture is closed.

#### `texture.height() int`

height returns the texture's height in pixels.

#### `texture.isClosed() boolean`

isClosed reports whether the texture has been closed, or belongs to a
render texture that has.

#### `texture.setFilter(string mode) result<unit, error>`

setFilter sets how the texture is sampled when scaled: "point" (sharp
pixels, the default), "bilinear" or "trilinear" (smooth, with mipmaps).
Fails with StateError when the texture is closed; throws ValueError for
an unknown mode.

#### `texture.setWrap(string mode) result<unit, error>`

setWrap sets how sampling beyond the texture's edges behaves: "repeat"
(the default), "clamp" (edge pixels extend outwards) or "mirror". Fails
with StateError when the texture is closed; throws ValueError for an
unknown mode.

#### `texture.unload() boolean`

**Deprecated.** Deprecated: use texture.close() instead.

unload frees the texture and returns false when it was already unloaded.

#### `texture.valid() boolean`

**Deprecated.** Deprecated: loaders now fail with a result instead of returning invalid textures; use isClosed() for closed ones.

valid reports whether the texture loaded and hasn't been unloaded.

#### `texture.width() int`

width returns the texture's width in pixels.

### `*raylib.Image`

#### `image.close()`

close frees the image's memory. Closing twice does nothing; any other use
afterwards throws StateError.

#### `image.height() int`

height returns the image's height in pixels. Throws StateError when the
image is closed.

#### `image.isClosed() boolean`

isClosed reports whether the image has been closed.

#### `image.pixels() int[]`

pixels returns every pixel row by row from the top left, each packed as
one 0xRRGGBBAA number. Throws StateError when the image is closed.

#### `image.premultipliedTexture() *raylib.Texture`

**Deprecated.** Deprecated: use image.toTexture({premultiplied: true}) instead.

premultipliedTexture uploads a premultiplied copy of the image, returning
an invalid texture when it can't.

#### `image.save(string path) result<unit, error>`

save writes the image to a file (PNG by extension), alpha included.
Fails with IOError when the file can't be written; throws StateError when
the image is closed.

#### `image.texture() *raylib.Texture`

**Deprecated.** Deprecated: use image.toTexture() instead.

texture uploads the image to the GPU, returning an invalid texture when it
can't.

#### `image.toImage() *img.Image`

toImage copies the image into a new img.Image from std:img, to draw on,
filter or encode it there; the two don't share pixels. Throws StateError
when the image is closed.

#### `image.toTexture(object? options) result<*raylib.Texture, error>`

toTexture uploads the image to the GPU as a texture. Options:
premultiplied (multiply color by alpha first, for drawing inside
raylib.blend("premultiplied", ...); linear filtering of such a texture
doesn't darken the edges of transparent areas). Fails with StateError
when no window is open; throws StateError when the image is closed.

#### `image.unload() boolean`

**Deprecated.** Deprecated: use image.close() instead.

unload frees the image and returns false when it was already unloaded.

#### `image.valid() boolean`

**Deprecated.** Deprecated: loaders now fail with a result instead of returning invalid images; use isClosed() for closed ones.

valid reports whether the image loaded and hasn't been unloaded.

#### `image.width() int`

width returns the image's width in pixels. Throws StateError when the
image is closed.

### `*raylib.Camera`

#### `camera.centerRay() *raylib.Ray`

centerRay returns the ray from the camera through the middle of the
screen.

#### `camera.control(string mode)`

control moves the camera from this frame's keyboard and mouse input the
way raylib's camera modes do: "free" (fly with WASD and the mouse),
"orbital" (circle the target), "firstPerson" or "thirdPerson". Throws
ValueError for an unknown mode.

#### `camera.position() {x: number, y: number, z: number}`

position returns where the camera is, {x, y, z}.

#### `camera.screenRay(any point) *raylib.Ray`

screenRay returns the ray from the camera through a point {x, y} on the
screen, such as the mouse position.

#### `camera.setPosition(any position) result<unit, error>`

setPosition moves the camera to a point {x, y, z}. It always succeeds.

#### `camera.setTarget(any target) result<unit, error>`

setTarget points the camera at a point {x, y, z}. It always succeeds.

#### `camera.target() {x: number, y: number, z: number}`

target returns the point {x, y, z} the camera looks at.

#### `camera.update(any ...modes) boolean`

**Deprecated.** Deprecated: use camera.control(mode) instead.

update moves the camera from input in a mode ("free" by default); unknown
modes mean "free".

#### `camera.use(any draw)`

use runs draw with 3D drawing (cube, sphere, ...) seen through this
camera. Call it inside raylib.draw.

### `*raylib.Camera2D`

#### `camera2D.offset() {x: number, y: number}`

offset returns where on screen the target appears, {x, y}.

#### `camera2D.rotation() number`

rotation returns the camera's rotation in degrees.

#### `camera2D.setOffset(any offset)`

setOffset sets where on screen the target appears, {x, y}.

#### `camera2D.setRotation(number degrees)`

setRotation sets the camera's rotation in degrees.

#### `camera2D.setTarget(any target)`

setTarget sets the world point {x, y} the camera looks at.

#### `camera2D.setZoom(number zoom)`

setZoom sets the camera's zoom. Throws ValueError unless it is more than 0.

#### `camera2D.target() {x: number, y: number}`

target returns the world point {x, y} the camera looks at.

#### `camera2D.toScreen(any point) {x: number, y: number}`

toScreen converts a world point {x, y} to where it appears on screen.

#### `camera2D.toWorld(any point) {x: number, y: number}`

toWorld converts a screen point {x, y}, such as the mouse position, to the
world point under it.

#### `camera2D.use(any draw)`

use runs draw with drawing panned, rotated and zoomed by this camera.
Call it inside raylib.draw.

#### `camera2D.zoom() number`

zoom returns the camera's zoom; 2 draws everything twice as large.

### `*raylib.Ray`

#### `ray.box(any center, any size) {distance: number?, hit: boolean, normal: {x: number, y: number, z: number}?, point: {x: number, y: number, z: number}?}`

box returns where the ray first meets a box around a center {x, y, z}
with a size {x, y, z}: {hit, distance, point, normal}, where distance,
point and normal are null when hit is false.

### `*raylib.Shader`

#### `shader.begin() boolean`

**Deprecated.** Deprecated: use shader.use(draw) instead.

begin starts drawing through the shader and returns false for an invalid
one.

#### `shader.close()`

close frees the shader. Closing twice does nothing; any other use
afterwards throws StateError.

#### `shader.drawFullscreen() result<unit, error>`

drawFullscreen fills the whole window with white drawn through this
shader. Fails with StateError when the shader is closed or no window is
open.

#### `shader.drawRect(any rect)`

drawRect fills a rectangle {x, y, width, height} with white drawn through
this shader. Throws StateError when the shader is closed.

#### `shader.end()`

**Deprecated.** Deprecated: use shader.use(draw) instead.

end stops drawing through the shader.

#### `shader.hasUniform(string name) boolean`

hasUniform reports whether the shader has a uniform with this name. GLSL
drops uniforms the code doesn't use.

#### `shader.isClosed() boolean`

isClosed reports whether the shader has been closed.

#### `shader.setUniform(string name, any value) result<unit, error>`

setUniform sets a uniform: a number (float), an array of 1 to 4 numbers
or a vector {x, y}, {x, y, z} or {x, y, z, w} (float to vec4), a color
{r, g, b, a} (vec4 of 0-255 channels), or a texture or render texture
(sampler2D). Setting a uniform the shader doesn't have does nothing,
since GLSL drops unused ones (see hasUniform). Fails with StateError when
the shader is closed; throws TypeError for any other value.

#### `shader.setValue(any name, any value) boolean`

**Deprecated.** Deprecated: use shader.setUniform(name, value) instead.

setValue sets a uniform and returns false when the shader is invalid, has
no such uniform, or the value can't be used.

#### `shader.unload() boolean`

**Deprecated.** Deprecated: use shader.close() instead.

unload frees the shader and returns false when it was invalid or already
unloaded.

#### `shader.use(any draw)`

use runs draw with everything it draws passed through this shader. Call
it inside raylib.draw. Throws StateError when the shader is closed.

#### `shader.valid() boolean`

**Deprecated.** Deprecated: raylib.compileShader fails with a result instead of returning invalid shaders; use isClosed() for closed ones.

valid reports whether the shader compiled and hasn't been unloaded.

### `*raylib.RenderTexture`

#### `renderTexture.begin() boolean`

**Deprecated.** Deprecated: use renderTexture.use(draw) instead.

begin starts drawing into the render texture and returns false for an
invalid one.

#### `renderTexture.close()`

close frees the render texture, and the textures texture() returned with
it. Closing twice does nothing; any other use afterwards throws
StateError.

#### `renderTexture.drawAt(any position, object? options)`

drawAt draws the render texture's contents the right way up with the
top-left corner at a point {x, y}. Takes the options of Texture.drawAt.
Throws StateError when the render texture is closed.

#### `renderTexture.end()`

**Deprecated.** Deprecated: use renderTexture.use(draw) instead.

end stops drawing into the render texture.

#### `renderTexture.height() int`

height returns the render texture's height in pixels.

#### `renderTexture.isClosed() boolean`

isClosed reports whether the render texture has been closed.

#### `renderTexture.save(string path) result<unit, error>`

save writes the render texture's contents to an image file (PNG by
extension), the right way up and fully opaque. Fails with IOError when
the file can't be written; throws StateError when the render texture is
closed.

#### `renderTexture.texture() *raylib.Texture`

texture returns the render texture's contents as a texture, for
setUniform or drawing with texture options. It shares the render
texture's GPU memory: it is upside down (OpenGL stores rows bottom-up),
closing it doesn't free anything, and it stops working when the render
texture is closed. Throws StateError when the render texture is closed.

#### `renderTexture.toImage() *img.Image`

toImage copies the render texture's contents into a new img.Image from
std:img, the right way up and with the alpha it was drawn with. Throws
StateError when the render texture is closed.

#### `renderTexture.unload() boolean`

**Deprecated.** Deprecated: use renderTexture.close() instead.

unload frees the render texture and returns false when it was invalid or
already unloaded.

#### `renderTexture.use(any draw)`

use runs draw with everything it draws going into this texture instead
of the screen. Throws StateError when the render texture is closed.

#### `renderTexture.valid() boolean`

**Deprecated.** Deprecated: raylib.renderTexture fails with a result instead of returning invalid render textures; use isClosed() for closed ones.

valid reports whether the render texture was made and hasn't been
unloaded.

#### `renderTexture.width() int`

width returns the render texture's width in pixels.