PudimBasicsGl - Pudim Basics OpenGL

A minimal 2D graphics library for Lua using OpenGL. PudimBasicsGl focuses on the essentials: window management, 2D rendering, textures, input, audio, text, time, camera, shaders, math, file utilities, and immediate-mode UI.

Versão em Português (PT-BR)

Features

• Window: Create and manage OpenGL windows with VSync, fullscreen, and resize support
• Renderer: Draw 2D primitives (pixels, lines, rectangles, circles, triangles, gradients) with automatic batch management
• Textures: Load images (PNG, JPG, BMP, etc.) and draw them with rotation, tinting, chroma key, and sprite sheet support
• Input: Keyboard and mouse input (key state, mouse position, cursor control)
• Audio: Load and play audio files (WAV, MP3, FLAC) with volume, pitch, and looping via miniaudio
• Text: Load TrueType fonts (.ttf) and render text with customizable size, color, and measurement via stb_truetype
• Time: Delta time, FPS, and timing utilities
• Camera: 2D camera controls (position, zoom, rotation, look_at, screen/world conversion)
• Shader: Custom GLSL shaders — compile from strings or load from files, set uniforms (int, float, vec2-4, mat4)
• Math: Vector math (vec2/vec3/vec4), arithmetic, lerp, clamp, angle conversion, and constants (PI, TAU)
• Studio: File system utilities (list directory, file timestamps, file copy)
• UI: Immediate-mode GUI widgets (panels, buttons, sliders, labels) for tools and debug overlays

Building

The recommended way to install is via LuaRocks (see below). For local development:

make

This creates PudimBasicsGl.so, a Lua module that you can load with require("PudimBasicsGl").

LSP Support

Add library/ to your lua-language-server library path for full autocomplete and type checking:

// .vscode/settings.json
{
    "Lua.workspace.library": ["./library"]
}

Or copy library/PudimBasicsGl.lua to your global lua-language-server addons folder.

Editor tip: Annotate variables with the qualified types to get method suggestions for instances. For example:

---@type PudimBasicsGl
local pb = require("PudimBasicsGl")

---@type PudimBasicsGl.Window
local win = pb.window.create(800, 600, "Title")

-- Now `win:` will show methods in VSCode's completion list
win:swap_buffers()

---@type PudimBasicsGl.Texture
local tex = pb.texture.load("sprite.png")
-- `tex:` will show texture methods such as `draw`, `get_size`, etc.

---@type Sound
local snd = pb.audio.load("music.mp3")
-- `snd:` will show audio methods such as `play`, `stop`, `set_volume`, etc.

---@type Font
local font = pb.text.load("my_font.ttf", 32)
-- `font:` will show text methods such as `draw`, `measure`, `set_size`, etc.

---@type Shader
local shd = pb.shader.create(vertex_src, fragment_src)
-- `shd:` will show shader methods such as `use`, `set_float`, `set_vec3`, etc.

Installation via LuaRocks

luarocks install pudimbasicsgl

Or build from the local rockspec:

luarocks make pudimbasicsgl-1.0.0-19.rockspec

The rockspec uses the builtin build type — LuaRocks compiles all .c sources directly into .so (Linux) or .dll (Windows), no makefile needed. The make command is only required for local development.

Usage

local pb = require("PudimBasicsGl")

-- Create a window
local window = pb.window.create(800, 600, "My App")
pb.renderer.init()

-- Load a texture (optional)
local texture = pb.texture.load("sprite.png")

-- Main loop (you control it!)
while not pb.window.should_close(window) do
    pb.time.update()
    local dt = pb.time.delta()
    
    -- Your game logic here
    
    -- Get current window size (handles resize)
    local w, h = pb.window.get_size(window)
    
    -- Render
    pb.renderer.clear(0.1, 0.1, 0.15, 1.0)
    pb.renderer.begin(w, h)
    
    -- Draw primitives
    pb.renderer.rect_filled(100, 100, 50, 50, pb.renderer.colors.RED)
    pb.renderer.circle_filled(400, 300, 30, {r=0, g=1, b=0.5, a=1})
    
    -- Draw textures (auto-flushes primitives!)
    if texture then
        texture:draw(200, 200)  -- Simple draw
        texture:draw_rotated(400, 400, 64, 64, 45)  -- Rotated 45 degrees
    end
    
    pb.renderer.finish()
    
    pb.window.swap_buffers(window)
    pb.window.poll_events()
end

if texture then texture:destroy() end
pb.window.destroy(window)

Input Example

-- Keyboard
if pb.input.is_key_pressed(pb.input.KEY_W) then
    player.y = player.y - speed * dt
end
if pb.input.is_key_pressed(pb.input.KEY_ESCAPE) then
    break
end

-- Mouse
local mx, my = pb.input.get_mouse_position()
if pb.input.is_mouse_button_pressed(pb.input.MOUSE_LEFT) then
    -- handle click
end

Audio Example

local music = pb.audio.load("music.mp3")
music:set_looping(true)
music:set_volume(0.8)
music:play()

-- Later...
music:pause()
music:resume()
music:stop()
music:destroy()

pb.audio.set_master_volume(0.5)
pb.audio.shutdown()

Text Example

-- Load a TrueType font at 32px
local font = pb.text.load("my_font.ttf", 32)

-- Draw text (auto-flushing handles switching from primitives)
font:draw("Hello, World!", 100, 100, 1, 1, 1) -- white text
font:draw("Colored!", 100, 150, {r=1, g=0.5, b=0, a=1}) -- orange text

-- Measure text dimensions
local w, h = font:measure("Hello, World!")

-- Change font size dynamically
font:set_size(48)

-- Cleanup
font:destroy()

API Reference

pb.window

pb.renderer

pb.texture

Texture Methods

pb.input

Key Constants

KEY_A to KEY_Z, KEY_0 to KEY_9, KEY_SPACE, KEY_ESCAPE, KEY_ENTER, KEY_TAB, KEY_BACKSPACE, KEY_UP, KEY_DOWN, KEY_LEFT, KEY_RIGHT, KEY_F1 to KEY_F3, KEY_F11, KEY_F12, KEY_LEFT_SHIFT, KEY_RIGHT_SHIFT, KEY_LEFT_CTRL, KEY_RIGHT_CTRL, KEY_LEFT_ALT, KEY_RIGHT_ALT

Mouse Constants

MOUSE_LEFT, MOUSE_RIGHT, MOUSE_MIDDLE

pb.audio

Sound Methods

pb.text

Font Methods

pb.math

Constants: pb.math.PI, pb.math.TAU, pb.math.HALF_PI

pb.studio

pb.ui

Immediate-mode GUI widgets. First call set_font before the first frame.

pb.shader

Shader Methods

pb.time

pb.camera

Color Format

Colors can be passed as:

• Table: {r=1.0, g=0.5, b=0.0, a=1.0}
• Individual values: r, g, b, a (alpha optional, defaults to 1.0)

Shader Example

-- Create a custom fragment shader
local vs = [[
#version 330 core
layout(location = 0) in vec2 aPos;
void main() { gl_Position = vec4(aPos, 0.0, 1.0); }
]]
local fs = [[
#version 330 core
out vec4 FragColor;
uniform float uTime;
void main() {
    FragColor = vec4(sin(uTime)*0.5+0.5, 0.3, 0.8, 1.0);
}
]]

local shader = pb.shader.create(vs, fs)
shader:use()
shader:set_float("uTime", pb.time.get())
-- draw geometry ...
shader:unuse()
shader:destroy()

Examples

We provide several example scripts in the examples/ directory. A new OOP-style demo demonstrates the object-style API (method calls via :) — it shows window:should_close(), texture:draw(), pb.time:update() and a simple render loop.

Run the demo after building/installing the module locally:

# Build/install locally (optional)
luarocks make --local

# Run example (ensures local .so is in package.cpath)
lua -e "package.cpath='./?.so;'..package.cpath" examples/oop_demo.lua

You can also inspect scripts/test_oop.lua for a minimal non-visual smoke test of the object-style API.

Dependencies

• GLFW3
• OpenGL 3.3+
• Lua 5.4 or 5.5

Building

Linux

make

The makefile auto-detects your Lua version. To build for a specific version:

make LUA_VERSION=5.4   # Force Lua 5.4
make LUA_VERSION=5.5   # Force Lua 5.5

Windows (MSYS2/MinGW)

1. Install MSYS2 and open the MinGW64 terminal
2. Install dependencies:

pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-glfw mingw-w64-x86_64-lua

3. Build:

make

This creates PudimBasicsGl.dll. Use with:

-- Windows
package.cpath = ".\\?.dll;" .. package.cpath
local pb = require("PudimBasicsGl")

Example Scripts

• examples/main.lua - Basic rendering demo
• examples/minimal.lua - Minimal example
• examples/texture_demo.lua - Texture loading and drawing
• examples/window_demo.lua - VSync and window features
• examples/input_demo.lua - Keyboard and mouse input demo
• examples/audio_demo.lua - Audio loading and playback demo
• examples/oop_demo.lua - Object-oriented style API demo
• examples/text_demo.lua - Text rendering and font loading demo
• examples/camera_demo.lua - 2D camera pan, zoom, rotation and coordinate conversion demo
• examples/shader_demo.lua - Custom GLSL shader with animated color wave effect
• examples/api_reference.lua - Complete API reference example

Command-line tool (pbgl)

A small CLI named pbgl is installed with the rock. It provides two commands:

• pbgl show-examples — Copy bundled example scripts to ./demos/ in the current directory
• pbgl help — Show usage information

After running pbgl show-examples you'll have a ./demos/ folder; run an example with:

lua demos/main.lua

Make sure ~/.luarocks/bin is in your PATH so you can call pbgl directly:

export PATH="$HOME/.luarocks/bin:$PATH"

Credits

• Sample audio file (examples/example.mp3) from file-examples.com — used for testing/demo purposes only.
• miniaudio — single-header audio library by David Reid (public domain / MIT-0).
• stb_image — single-header image loader by Sean Barrett (public domain / MIT).
• stb_truetype — single-header TrueType font rasterizer by Sean Barrett (public domain / MIT).
• GLAD — OpenGL loader generator.

License

MIT