render

This package implements a batched 2D rendering pipeline. It serves as the primary interface for drawing sprites, text and geometric primitives, automatically handling coordinate space transformations and draw call batching.

Features:

• Automated asset pipeline: Utilizes a build-time generated texture atlas and auto-generated sprite and font enums (SpriteName and FontName in bonsai:generated package) for type-safe, optimized asset access.
• Batched rendering: Automatically batches draw calls (up to MAX_QUADS) to minimize GPU overhead, with manual control via flushBatch.
• Coordinate systems: Easy switching between world space (gameplay) and screen space (UI) using helper functions: setWorldSpace and setScreenSpace.
• Text drawing: Integrated TTF font support with utilities like drawTextWithDropShadow and drawTextSimple.
• Scissoring: Built-in support for clipping regions via ScissorState.

Usage

draw :: proc() {
  render.setWorldSpace()

  // Draw game objects using auto-generated sprite enums
  render.drawSprite(.potShadow, potPosition, drawLayer = .shadow)
  render.drawSprite(.potIdle, potPosition)

  // Draw ui with auto-generated font enum
  render.setScreenSpace()
  render.drawTextSimple(fmt.tprintf("Health: %d", potHealth), textPosition, .PixelCode)
}

Notes

Currently it only supports PNG files for images and TTF files for fonts.

The CLI generates enums from images located in assets/images. For animated sprite sheets, they have to be a horizontal stripe. You can declare the amount of animation frames by naming the file fileName_{X}x1.png, where X is the amount of frames. The animation frames suffix gets removed from the enum name.

The CLI also allows for tileset loading, with each tile being a separate sprite. Simply create a tilesets directory in assets/images, and save the tileset here. Similarly to animation frame declaration, you can suffix the tileset file name like so: tilesetName_{W}x{H}.png, where W is width of one tile in pixels, and H is height of one tile in pixels. Each tile gets saved to the atlas with its edges extruded by one pixel, to ensure there’s no edge bleeding issue. When no suffix is provided, the default size for a tile in a tileset is 16x16 pixels.

The CLI also handles font scaling via filenames. Naming a font fontName_{N}.ttf (e.g., PixelCode_12.ttf) marks it as a Pixel Font with a native size of N. These are baked at integer multiples of N to preserve the pixel grid. Fonts without a suffix are treated as Vector Fonts and are baked at the requested size (with oversampling) for smooth edges.

---

ATLAS_PATH

ATLAS_PATH :: "bonsai/core/render/atlas/atlas.png"

Path relative to project root pointing to the generated sprite atlas.

Caution

This isn’t the only place where this variable exists. Editing just this variable doesnt change where the atlas is generated.

---

Atlas

Atlas :: struct  {
  view:  sokol_gfx.View,
  image: sokol_gfx.Image,
}

Represents the global sprite atlas.

---

BINARY_PATH

BINARY_PATH :: ".bonsai/cache/sprites/sprites.bin"

Path relative to project root pointing to the generated sprite UV/size data.

Caution

This isn’t the only place where this variable exists. Editing just this variable doesnt change where the sprite data is stored.

---

BINDING_GLOBAL_UNIFORMS

BINDING_GLOBAL_UNIFORMS :: 0

Constants prefixed with BINDING define the binding index used for uniform data. By default 0 is occupied by ShaderGlobals and 1 is left for custom shader uniform data.

---

BITMAP_HEIGHT

BITMAP_HEIGHT :: 1024

Height constraint for the font bitmap texture.

---

BITMAP_WIDTH

BITMAP_WIDTH :: 1024

Width constraint for the font bitmap texture.

---

BLANK_ATLAS_PATH

BLANK_ATLAS_PATH :: "bonsai/core/render/atlas/blank.png"

Path relative to project root pointing to the blank sprite atlas. Used when there’s no images in assets/images directory.

---

CLEAR_COLOR

CLEAR_COLOR :: colors.BLACK

Default clear color (background).

---

Canvas

Canvas :: struct  {
  image:       sokol_gfx.Image,
  depthImage:  sokol_gfx.Image,
  readerView:  sokol_gfx.View,
  attachments: sokol_gfx.Attachments,
  sampler:     sokol_gfx.Sampler,
  id:          CanvasId,
  size:        gmath.Vector2,
}

Wraps all data needed for each Canvas object. Each has unique CanvasId. Shouldn’t be modified directly.

---

CanvasId

CanvasId :: distinct i32

A handle used to identify a loaded Canvas

---

CoordSpace

CoordSpace :: struct  {
  projectionMatrix:     gmath.Matrix4,
  cameraMatrix:         gmath.Matrix4, // Model matrix of the camera
  viewProjectionMatrix: gmath.Matrix4, // Projection * Inverse(Camera) (view matrix)
}

Defines the matrices used for coordinate transformation in a render pass.

---

DEFAULT_UV

DEFAULT_UV :: gmath.Vector4 {
0, 0, 1, 1
}

Default UV coordinates covering the full texture (0,0 to 1,1).

---

DrawFrame

DrawFrame :: struct  {
  reset: struct {
    // Dynamic arrays of quads bucketed by DrawLayer
    quads:           [DrawLayer][dynamic]Quad,

    // The active coordinate space (camera, projection)
    coordSpace:      CoordSpace,

    // Current layer being drawn to
    activeDrawLayer: DrawLayer,

    // Current scissor/clipping rectangle
    activeScissor:   gmath.Rectangle,

    // Global flags applied to all subsequent quads in the batch
    activeFlags:     QuadFlags,

    // Shader uniform data
    shaderData:      ShaderGlobals,

    // Tracks which layers need Y-sorting
    sortedLayers:    bit_set[DrawLayer],
  },
}

A container for all data required to render a single frame.

---

DrawLayer

DrawLayer :: enum u8 {
  nil,
  background,
  shadow,
  playspace,
  vfx,
  ui,
  tooltip,
  pauseMenu,
  top,
}

Defines the rendering order (Z-sorting).

Note

Layers are drawn from top to bottom (nil first, top last).

---

Font

Font :: struct  {
  texture:       sokol_gfx.Image,
  view:          sokol_gfx.View,
  characterData: [96]stb_truetype.bakedchar,
  name:          string,
  pixelSize:     uint,
}

Represents a loaded and baked font ready for rendering.

---

LOCATION_POSITION

LOCATION_POSITION :: 0

Constants prefixed with LOCATION define the memory layout relation between the CPU Vertex struct and the GPU shader attributes (layout(location = X)).

Caution

Do not change these unless you update shader_vs_core.glsl to match.

---

MAX_QUADS

MAX_QUADS :: 8192

Maximum number of quads per batch flush.

Tip

Increase if you see “Quad buffer full” warnings, decrease to save memory.

---

Quad

Quad :: [4]Vertex

A visual quad composed of 4 vertices.

---

QuadFlags

QuadFlags :: enum u8 {
  flag1 = (1 << 0),
  flag2 = (1 << 1),
}

Bit flags for special rendering behaviors in the shader.

Note

Currently unused by the core.

---

RawSpriteData

RawSpriteData :: struct #packed {
  u0:     f32,
  v0:     f32,
  u1:     f32,
  v1:     f32,
  sizeX:  f32,
  sizeY:  f32,
  frames: f32,
}

Struct used to read and convert binary data to data stored in spriteData as SpriteData

---

RenderContext

RenderContext :: struct  {
  atlas:                Atlas,
  passAction:           sokol_gfx.Pass_Action,
  inPass:               bool,
  bindings:             sokol_gfx.Bindings,
  shaders:              [dynamic]Shader,
  defaultShaderId:      ShaderId,
  activeShaderId:       ShaderId,
  customUniformsData:   [1024]byte,
  customUniformsSize:   uint,
  canvases:             [dynamic]Canvas,
  defaultCanvasId:      CanvasId,
  activeCanvasId:       CanvasId,
  defaultCanvasSampler: sokol_gfx.Sampler,
}

Internal context holding the global Sokol GFX state. Manages active bindings (atlas/font) and stores the list of loaded Shaders

---

ScissorState

ScissorState :: struct  {
  enabled:     bool,
  coordinates: gmath.Vector4,
}

Tracks the state of the scissor test (clipping).

---

Shader

Shader :: struct  {
  pipeline: sokol_gfx.Pipeline,
  id:       ShaderId,
}

Wraps a compiled Sokol pipeline and its ID.

---

ShaderDescriptionFunction

ShaderDescriptionFunction :: proc (backend: sokol_gfx.Backend) -> sokol_gfx.Shader_Desc //

Function signature for the auto-generated shader descriptors created by sokol-shdc.

---

ShaderGlobals

ShaderGlobals :: struct #align (16) {
  uViewProjectionMatrix: gmath.Matrix4,
}

Uniform block data uploaded to the GPU for the global shader state.

Note

Must align to 16 bytes (via std140 Layout Rules).

---

ShaderId

ShaderId :: distinct i32

A handle used to identify a loaded Shader

---

Vertex

Vertex :: struct #packed {
  position:      gmath.Vector3,
  color:         gmath.Vector4,
  uv:            gmath.Vector2,
  localUv:       gmath.Vector2,
  size:          gmath.Vector2,
  textureIndex:  u8,
  drawLayer:     u8,
  quadFlags:     QuadFlags, // u8
  _:             [1]u8, // Padding to align next Vector4 to 4 byte boundary
  colorOverride: gmath.Vector4,
  parameters:    gmath.Vector4,
}

Represents a single vertex in the sprite batcher.

---

clearScissor

clearScissor :: proc ()

Disables the scissor test.

---

destroyCanvas

destroyCanvas :: proc (id: CanvasId)

Destroys the GPU resources associated with the Canvas.

Caution

Calling this invalidates the CanvasId.

---

drawArc

drawArc :: proc (
  center: gmath.Vector2,
  radius: f32,
  startAngle: f32, // in radians
  endAngle: f32, // in radians
  color: gmath.Color,
  segments: uint = 32,
  drawLayer := DrawLayer.nil,
  sortKey: f32 = 0.0,
)

Draws a filled arc defined by startAngle and endAngle. Angles are in radians.

---

drawArrow

drawArrow :: proc (
  start, end: gmath.Vector2,
  color: gmath.Color,
  thickness: f32 = 1.0,
  headSize: f32 = 10.0,
  drawLayer := DrawLayer.nil,
  sortKey: f32 = 0.0,
)

Draws an arrow pointing from start to end. headSize determines the length of the arrow tip lines.

---

drawBezierQuad

drawBezierQuad :: proc (
  start, control, end: gmath.Vector2,
  color: gmath.Color,
  thickness: f32 = 1.0,
  segments: uint = 32,
  drawLayer := DrawLayer.nil,
  sortKey: f32 = 0.0,
)

Draws a quadratic bezier curve (start -> control -> end).

---

drawCanvas

drawCanvas :: proc (
  id: CanvasId,
  position: gmath.Vector2 = {0, 0},
  rotation: f32 = 0.0,
  pivot: gmath.Pivot = .bottomLeft,
  scale: gmath.Vector2 = {1, 1},
  size: Maybe(gmath.Vector2) = nil,
  transform := gmath.Matrix4(1),
  color := colors.WHITE,
  drawLayer := DrawLayer.nil,
  sortKey: f32 = 0.0,
)

Draws the contents of a Canvas onto the screen (or current target) at the given position. This triggers an immediate batch flush because it requires switching textures.

---

drawCircle

drawCircle :: proc (
  center: gmath.Vector2,
  radius: f32,
  color: gmath.Color,
  segments: uint = 32,
  drawLayer := DrawLayer.nil,
  sortKey: f32 = 0.0,
)

Draws a filled circle.

Note

Internally it’s just a wrapper around drawRegularPolygon with high segment count.

---

drawCircleGradient

drawCircleGradient :: proc (
  center: gmath.Vector2,
  radius: f32,
  colorInner: gmath.Color,
  colorOuter: gmath.Color,
  segments: uint = 32,
  drawLayer := DrawLayer.nil,
  sortKey: f32 = 0.0,
)

Draws a filled circle with a gradient from the center to the edge.

---

drawCircleLines

drawCircleLines :: proc (
  center: gmath.Vector2,
  radius: f32,
  color: gmath.Color,
  segments: uint = 32,
  thickness: f32 = 1.0,
  drawLayer := DrawLayer.nil,
  sortKey: f32 = 0.0,
)

Draws the outline of a circle using line segments. Internally it just calls the drawRegularPolygonLines function with a high default count of segments.

---

drawDashedLine

drawDashedLine :: proc (
  start, end: gmath.Vector2,
  color: gmath.Color,
  thickness: f32 = 1.0,
  dashLength: f32 = 10.0,
  gapLength: f32 = 5.0,
  drawLayer := DrawLayer.nil,
  sortKey: f32 = 0.0,
)

Draws a dashed line between start and end. dashLength is the length of the solid part, gapLength is the empty space.

---

drawEllipse

drawEllipse :: proc (
  center: gmath.Vector2,
  radiusX: f32,
  radiusY: f32,
  color: gmath.Color,
  rotation: f32 = 0.0,
  segments: uint = 32,
  drawLayer := DrawLayer.nil,
  sortKey: f32 = 0.0,
)

Draws a filled ellipse. The shape is created by stretching a circle, so segments determines the vertex count.

---

drawEllipseLines

drawEllipseLines :: proc (
  center: gmath.Vector2,
  radiusX: f32,
  radiusY: f32,
  color: gmath.Color,
  rotation: f32 = 0.0,
  segments: uint = 32,
  thickness: f32 = 1.0,
  drawLayer := DrawLayer.nil,
  sortKey: f32 = 0.0,
)

Draws the outline of an ellipse. The shape is created by stretching a circle, so segments determines the vertex count.

---

drawLine

drawLine :: proc (
  start: gmath.Vector2,
  end: gmath.Vector2,
  color: gmath.Color,
  thickness: f32 = 1.0,
  drawLayer := DrawLayer.nil,
  sortKey: f32 = 0.0,
)

Draws a line between start and end with a specified thickness.

Note

Uses drawRectangleTransform internally to stretch a white pixel.

---

drawNineSlice

drawNineSlice :: proc (
  sprite: generated.SpriteName,
  rectangle: gmath.Rectangle,
  sliceBorder: f32, // in pixels
  color := colors.WHITE,
  tiled := false,
  drawLayer := DrawLayer.nil,
  sortKey: f32 = 0.0,
)

Draws a 9-slice sprite.

• If tiled is false (default): The edges and center are stretched. (Fast, 9 quads).
• If tiled is true: The edges and center are repeated. (Slower, good for pixel art textures).

---

drawPolygon

drawPolygon :: proc (
  points: []gmath.Vector2,
  color: gmath.Color,
  drawLayer := DrawLayer.nil,
  sortKey: f32 = 0.0,
)

Draws a filled generic polygon. Expects points to be listed in a counter-clockwise order.

Note

The polygon must be convex.

---

drawPolygonLines

drawPolygonLines :: proc (
  points: []gmath.Vector2,
  color: gmath.Color,
  thickness: f32 = 1.0,
  drawLayer := DrawLayer.nil,
  sortKey: f32 = 0.0,
)

Draws the outline of a polygon. Expects points to be listed in a counter-clockwise order.

---

drawQuad

drawQuad :: proc (
  point1, point2, point3, point4: gmath.Vector2,
  color: gmath.Color = colors.WHITE,
  sprite := generated.SpriteName.nil,
  uvs: Maybe([4]gmath.Vector2) = nil,
  drawLayer := DrawLayer.nil,
  sortKey: f32 = 0.0,
)

Draws a quad defined by 4 arbitrary points. Useful for skewing, soft-body physics, or perspective distortion. Points should be defined in counter-clockwise order: BL, TL, TR, BR.

---

drawQuadProjected

drawQuadProjected :: proc (
  positions: [4]gmath.Vector2,
  colors: [4]gmath.Color,
  uvs: [4]gmath.Vector2,
  textureIndex: u8,
  quadSize: gmath.Vector2,
  colorOverride: gmath.Color,
  drawLayer: DrawLayer = DrawLayer.nil,
  flags: QuadFlags,
  parameters := gmath.Vector4{},
  sortKey: f32 = 0.0,
)

Core function for pushing a quad into the draw list.

This is a low-level rendering function used by higher-level drawing utilities. It directly submits a quad (4 vertices) with full control over positions, UVs, colors, and rendering parameters.

Arguments:

• positions: World-space positions of the quad’s 4 corners (bottom-left, top-left, top-right, bottom-right).
• colors: Vertex colors (RGBA) for each corner.
• uvs: Texture coordinates for each corner (x,y = bottom-left, x,w = top-left, z,w = top-right, z,y = bottom-right).
• textureIndex: Texture slot (0 = atlas, 1 = font, 255 = white pixel).
• quadSize: Original size of the quad (before transforms).
• colorOverride: Optional tint color (multiplied with vertex colors).
• drawLayer: Target draw layer (defaults to current active layer).
• flags: Special shader flags (e.g., effects).
• parameters: Custom shader parameters (vec4).
• sortKey: Z-order key (higher values draw on top).

Performance

Prefer higher-level helpers like drawSprite or drawRectangle unless you need per-vertex control.

Example

render.drawQuadProjected(
    positions = { ... },
    colors    = { colors.WHITE, ... },
    uvs       = { uv.xy, uv.xw, uv.zw, uv.zy },
    textureIndex = 0,
    quadSize = {64, 64},
    drawLayer = .background,
)

---

drawRectangle

drawRectangle :: proc (
  rectangle: gmath.Rectangle,
  rotation: f32 = 0.0, // in radians
  sprite := generated.SpriteName.nil,
  uv := DEFAULT_UV,
  color := colors.WHITE,
  colorOverride := gmath.Color{},
  drawLayer := DrawLayer.nil,
  flags := QuadFlags{},
  parameters := gmath.Vector4{},
  cropTop: f32 = 0.0,
  cropLeft: f32 = 0.0,
  cropBottom: f32 = 0.0,
  cropRight: f32 = 0.0,
  sortKey: f32 = 0.0,
  isCullingEnabled := false,
)

Draws a simple Rectangle.

Tip

Useful for UI, debug shapes or non-sprite elements.

---

drawRectangleGradient

drawRectangleGradient :: proc (
  rectangle: gmath.Rectangle,
  colorBottomLeft: gmath.Color,
  colorTopLeft: gmath.Color,
  colorTopRight: gmath.Color,
  colorBottomRight: gmath.Color,
  rotation: f32 = 0.0,
  pivot := gmath.Pivot.bottomLeft,
  drawLayer := DrawLayer.nil,
  sortKey: f32 = 0.0,
)

Draws a rectangle with a specific color for each corner.

---

drawRectangleGradientHorizontal

drawRectangleGradientHorizontal :: proc (
  rectangle: gmath.Rectangle,
  colorLeft: gmath.Color,
  colorRight: gmath.Color,
  rotation: f32 = 0.0,
  pivot := gmath.Pivot.bottomLeft,
  drawLayer := DrawLayer.nil,
  sortKey: f32 = 0.0,
)

Draws a rectangle with a horizontal gradient.

---

drawRectangleGradientRadial

drawRectangleGradientRadial :: proc (
  rectangle: gmath.Rectangle,
  colorInner: gmath.Color,
  colorOuter: gmath.Color,
  rotation: f32 = 0.0,
  pivot := gmath.Pivot.bottomLeft,
  drawLayer := DrawLayer.nil,
  sortKey: f32 = 0.0,
)

Draws a rectangle with a gradient from the center outwards. Useful for vignettes or button highlights.

---

drawRectangleGradientVertical

drawRectangleGradientVertical :: proc (
  rectangle: gmath.Rectangle,
  colorBottom: gmath.Color,
  colorTop: gmath.Color,
  rotation: f32 = 0.0,
  pivot := gmath.Pivot.bottomLeft,
  drawLayer := DrawLayer.nil,
  sortKey: f32 = 0.0,
)

Draws a rectangle with a vertical gradient.

---

drawRectangleLines

drawRectangleLines :: proc (
  rectangle: gmath.Rectangle,
  color: gmath.Color,
  thickness: f32 = 1.0,
  rotation: f32 = 0.0, // in radians
  pivot := gmath.Pivot.bottomLeft,
  drawLayer := DrawLayer.nil,
  sortKey: f32 = 0.0,
)

Draws the outline of a Rectangle. The border grows outwards from the rectangle edges.

---

drawRectangleTransform

drawRectangleTransform :: proc (
  transform: gmath.Matrix4,
  size: gmath.Vector2,
  sprite := generated.SpriteName.nil,
  uv := DEFAULT_UV,
  textureIndex: u8 = 0,
  animationIndex := 0,
  color := colors.WHITE,
  colorOverride := gmath.Color{},
  drawLayer := DrawLayer.nil,
  flags := QuadFlags{},
  parameters := gmath.Vector4{},
  cropTop: f32 = 0.0,
  cropLeft: f32 = 0.0,
  cropBottom: f32 = 0.0,
  cropRight: f32 = 0.0,
  sortKey: f32 = 0.0,
)

Low-level function that pushes the final quad vertex data to the batcher.

---

drawRegularPolygon

drawRegularPolygon :: proc (
  center: gmath.Vector2,
  radius: f32,
  sides: uint,
  color: gmath.Color,
  rotation: f32 = 0.0,
  drawLayer := DrawLayer.nil,
  sortKey: f32 = 0.0,
)

Draws a filled regular N-gon.

Note

The shape starts rotated at 90 degrees to point up. A rotation of 0.0 results in the first vertex being at 12 o’clock.

---

drawRegularPolygonLines

drawRegularPolygonLines :: proc (
  center: gmath.Vector2,
  radius: f32,
  sides: uint,
  color: gmath.Color,
  thickness: f32 = 1.0,
  rotation: f32 = 0.0,
  drawLayer := DrawLayer.nil,
  sortKey: f32 = 0.0,
)

Draws the outline of a regular N-gon.

Note

The shape starts rotated at 90 degrees to point up. A rotation of 0.0 results in the first vertex being at 12 o’clock.

---

drawRoundedRectangle

drawRoundedRectangle :: proc (
  rectangle: gmath.Rectangle,
  cornerRadius: f32,
  color: gmath.Color,
  rotation: f32 = 0.0, // in radians
  pivot := gmath.Pivot.bottomLeft,
  drawLayer := DrawLayer.nil,
  sortKey: f32 = 0.0,
)

Draws a filled rounded rectangle. The corners are generated as arcs with the specified cornerRadius. If cornerRadius is 0, it falls back to a standard rectangle.

---

drawRoundedRectangleLines

drawRoundedRectangleLines :: proc (
  rectangle: gmath.Rectangle,
  cornerRadius: f32,
  color: gmath.Color,
  thickness: f32 = 1.0,
  rotation: f32 = 0.0, // in radians
  pivot := gmath.Pivot.bottomLeft,
  segments: uint = 10, // segments per corner
  drawLayer := DrawLayer.nil,
  sortKey: f32 = 0.0,
)

Draws the outline of a rounded rectangle. Connects the corners with straight lines and uses segments for the corner arcs.

---

drawSprite

drawSprite :: proc {
  _drawSpriteVector3Rotation,
  _drawSpriteF32Rotation,
}

Main function for drawing game entities. Supports rotation, animations, pivoting and camera culling. Accepts either a f32 or a Vector3 as the rotation. If a f32 is provided, the sprite is rotated on the Z axis.

Note

The rotation angle should be provided in radians.

---

drawSpriteInRectangle

drawSpriteInRectangle :: proc (
  sprite: generated.SpriteName,
  position: gmath.Vector2,
  size: gmath.Vector2,
  transform := gmath.Matrix4(1),
  color := colors.WHITE,
  colorOverride := gmath.Color{},
  drawLayer := DrawLayer.nil,
  flags := QuadFlags(0),
  paddingPercent: f32 = 0.1,
)

Helper to draw a sprite scaled to fit inside a target rectangle. Maintains aspect ratio (letterboxing).

---

drawText

drawText :: drawTextWithDropShadow

Default text drawing alias (includes drop shadow).

---

drawTextSimple

drawTextSimple :: proc {
  _drawTextSimpleVector3Angle,
  _drawTextSimpleF32Angle,
}

Draws text without a drop shadow. Retrieves the font using the automatically generated FontName enum. Accepts either a f32 or a Vector3 as the rotation. If a f32 is provided, the text is rotated on the Z axis.

Caution

Fonts are currently rendered as bitmaps. For the sharpest results, you may want to find a native font size (e.g. 12 for PixelCode) and use the scale argument to control the size of the text. When fonts will be rendered via SDF, this issue will be fixed.

---

drawTextSimpleFont

drawTextSimpleFont :: proc {
  _drawTextSimpleFontVector3Angle,
  _drawTextSimpleFontF32Angle,
}

Internal primitive for drawing a single line of text. Calculates layout, pivots, and batches the quads. Accepts either a f32 or a Vector3 as the rotation. If a f32 is provided, the text is rotated on the Z axis.

---

drawTextWithDropShadow

drawTextWithDropShadow :: proc {
  _drawTextWithDropShadowVector3Angle,
  _drawTextWithDropShadowF32Angle,
}

Draws text with a hard-coded drop shadow for contrast**. Retrieves the font using the automatically generated FontName enum. Accepts either a f32 or a Vector3 as the rotation. If a f32 is provided, the text is rotated on the Z axis.

Caution

Fonts are currently rendered as bitmaps. For the sharpest results, you may want to find a native font size (e.g. 12 for PixelCode) and use the scale argument to control the size of the text. When fonts will be rendered via SDF, this issue will be fixed.

---

drawTriangle

drawTriangle :: proc (
  point1, point2, point3: gmath.Vector2,
  color: gmath.Color,
  drawLayer := DrawLayer.nil,
  sortKey: f32 = 0.0,
)

Draws a filled triangle. Expects points to be listed in a counter-clockwise order.

---

drawTriangleGradient

drawTriangleGradient :: proc (
  point1: gmath.Vector2,
  point2: gmath.Vector2,
  point3: gmath.Vector2,
  color1: gmath.Color,
  color2: gmath.Color,
  color3: gmath.Color,
  drawLayer := DrawLayer.nil,
  sortKey: f32 = 0.0,
)

Draws a filled triangle with different colors at each vertex.

---

drawTriangleLines

drawTriangleLines :: proc (
  point1, point2, point3: gmath.Vector2,
  color: gmath.Color,
  thickness: f32 = 1.0,
  drawLayer := DrawLayer.nil,
  sortKey: f32 = 0.0,
)

Draws a triangle outline. Expects points to be listed in a counter-clockwise order.

---

flushBatch

flushBatch :: proc ()

Flushes all queued quads to the GPU. Sorts layers if necessary. Warns when MAX_QUADS is exceeded.

---

getAtlasUv

getAtlasUv :: proc (sprite: generated.SpriteName) -> gmath.Vector4

Helper to retrieve texture info from SpriteName.

---

getCanvasSpace

getCanvasSpace :: proc (width, height: f32) -> CoordSpace

Calculates the coordinate space for a custom Canvas. Called internally by setCanvas.

---

getDrawFrame

getDrawFrame :: proc () -> ^DrawFrame

Returns a pointer to the current frame’s draw data.

---

getFont

getFont :: proc (fontName: generated.FontName, requestedSize: uint) -> (Font, bool)

Retrieves or loads a font for a specific size. Caches the result to avoid re-baking the bitmap every frame. Automatically calculates the best texture size based on the font type:

• Pixel Fonts: Snaps to the nearest integer multiple of the native size.
• Vector Fonts: Oversamples (default: 2x) for crisp rendering at small sizes.

---

getFrameCount

getFrameCount :: proc (sprite: generated.SpriteName) -> int

Helper to retrieve frame count from SpriteName.

---

getRenderContext

getRenderContext :: proc () -> ^RenderContext

Returns a pointer to the RenderContext struct.

---

getScreenSpace

getScreenSpace :: proc () -> CoordSpace

Calculates the coordinate space for UI/Screen elements.

---

getScreenSpaceProjectionMatrix

getScreenSpaceProjectionMatrix :: proc () -> gmath.Matrix4

Generates the projection matrix for the UI. Handles aspect ratio scaling to ensure the UI fits within the design resolution (GAME_WIDTH/GAME_HEIGHT).

---

getSpriteSize

getSpriteSize :: proc (sprite: generated.SpriteName) -> gmath.Vector2

Helper to retrieve size from SpriteName.

---

getTextSize

getTextSize :: proc (fontName: generated.FontName, fontSize: uint, text: string) -> gmath.Vector2

Calculates the total dimension (width, height) of a string if it were rendered.

Tip

Useful for centering text.

---

getViewportPivot

getViewportPivot :: proc (pivot: gmath.Pivot) -> gmath.Vector2

Helper to get specific screen/viewport coordinates based on a Pivot (anchoring).

Returns a Vector2 position.

Tip

Useful for positioning UI elements relative to screen edges.

---

getViewportRectangle

getViewportRectangle :: proc () -> gmath.Rectangle

Helper that calculates and creates a Rectangle containing the current viewport in Screen Space. Uses ScaleMode internally in its calculations.

---

getWorldSpace

getWorldSpace :: proc () -> CoordSpace

Calculates the coordinate space for the main gameplay world. Creates a View-Projection matrix based on the camera’s position and zoom.

---

loadCanvas

loadCanvas :: proc (width: i32, height: i32) -> CanvasId

Creates a new Canvas with the specified dimensions and returns its CanvasId.

Arguments:

• width: Width of the Canvas in pixels.
• height: Height of the Canvas in pixels.

Returns:

• CanvasId: A unique identifier for the created Canvas.

Usage

Canvases are used as offscreen render targets. After creating a Canvas, use setCanvas to render to it and drawCanvas to display its contents on the screen.

// Create a Canvas for rendering shadows
shadowCanvas := render.loadCanvas(512, 512)

// Render to the Canvas
render.setCanvas(shadowCanvas)
render.drawSprite(.shadow, position)

// Resume rendering to screen and draw the Canvas
render.setCanvas()
render.drawCanvas(shadowCanvas, drawLayer = .shadow)

Performance

Canvases consume GPU resources. Use destroyCanvas to free them when no longer needed.

---

loadShader

loadShader :: proc (descriptionFunction: ShaderDescriptionFunction) -> ShaderId

Creates a new ShaderId from a sokol-shdc generated description function. This function enforces the framework’s standard vertex layout to ensure compatibility with batching.

Note

This doesn’t change the current shader, just loads it into memory.

Example

import "shaders"

potShader := render.loadShader(shaders.pot_shader_desc)

---

loadSpriteMetadata

loadSpriteMetadata :: proc (filepath: string = BINARY_PATH)

Loads/reloads the sprite data from a binary file with the structure matching the RawSpriteData struct.

---

popScissor

popScissor :: proc ()

Pops the current scissor, restoring the previous state. If the stack becomes empty, scissoring is disabled.

---

pushScissor

pushScissor :: proc (rectangle: gmath.Rectangle)

Pushes a new scissor rectangle onto the stack. Automatically intersects with the previous scissor to ensure nested clipping works.

---

resetDrawFrame

resetDrawFrame :: proc ()

Resets the DrawFrame (clears quads, resets camera) and sets the shader to default.

---

setCanvas

setCanvas :: proc (
  id: CanvasId = _renderContext.defaultCanvasId,
  clear: bool = true,
  clearColor: Maybe(gmath.Color) = nil,
)

Sets the current render target (Canvas). Flushes the batch and switches to the specified Canvas or falls back to the default screen buffer.

Arguments:

• id: CanvasId to render to (default = screen).
• clear: If true, clears the Canvas with clearColor (default = true).
• clearColor: Background fill color (defaults to CLEAR_COLOR).

Usage

• Use loadCanvas to create a new Canvas.
• Rendering to a Canvas requires calling drawCanvas afterward to display it.

// Render shadows to an offscreen buffer
render.setCanvas(shadowCanvas)
render.drawSprite(.shadow, position)

// Resume rendering to screen
render.setCanvas()
render.drawCanvas(shadowCanvas, drawLayer = .shadow)

Performance

Switching Canvases forces a flushBatch. Minimize calls to avoid performance overhead.

---

setClearColor

setClearColor :: proc (col: gmath.Vector4)

Sets the background clear color.

---

setCoordSpace

setCoordSpace :: proc {
  _setCoordSpaceValue,
  _setCoordSpaceDefault,
}

Sets the coordinate space (projection/camera matrices).

Arguments:

• CoordSpace struct: Sets the drawFrame.reset.coordSpace to given CoordSpace.
• nil: Sets the drawFrame.reset.coordSpace to default.

---

setCustomUniforms

setCustomUniforms :: proc (data: rawptr, size: uint)

Uploads custom uniform data to the currently active shader. This triggers a batch flush to ensure previous sprites are drawn with old uniforms.

Note

The data is bound to layout(binding=1) in GLSL.

Example

parameters := PotParameters{ time = 1.0, power = 10.0 } render.setCustomUniforms(&params, size_of(params))

---

setFontTexture

setFontTexture :: proc (view: sokol_gfx.View)

Changes the active font texture view.

---

setScissorCoordinates

setScissorCoordinates :: proc (coordinates: gmath.Vector4)

Sets the scissor (clipping) rectangle. Flushes the batch if the scissor state changes.

---

setScreenSpace

setScreenSpace :: proc ()

Flushes the current batch and switches coordinate space to screen space (UI). Sets the active draw layer to DrawLayer.ui.

---

setShader

setShader :: proc (id: ShaderId = _renderContext.defaultShaderId)

Sets the active shader pipeline for subsequent draw calls. Flushes the current batch if the shader changes.

Arguments:

• id: Expects the ShaderId returned by loadShader.

---

setTexture

setTexture :: proc (view: sokol_gfx.View)

Changes the active main texture view.

---

setWorldSpace

setWorldSpace :: proc ()

Flushes the current batch and switches coordinate space to world space (gameplay). Sets the active draw layer to DrawLayer.background.

---

shutdown

shutdown :: proc ()

Cleans up all rendering resources. Called internally by main.odin.

---

spriteData

spriteData: [generated.SpriteName]generated.SpriteData

Stores UV, size and frame info for each SpriteName enum from the sprite atlas.

---