PortableGL Shader Workshop Announcement

PortableGL: Shader Workshop Announcement and Project Overview

Shader Workshop Announcement

• PGL Shadertoy

If you’d like to support PortableGL development or are interested in shader art (or ideally both), there’s a shader workshop you can check out. The project team has chosen to go with plain preorders ahead of a public beta release, aiming for an early May public beta. The workshop blends shader artistry with PortableGL’s approachable, portable OpenGL-style rendering, inviting both artists and programmers to explore creative shader work within a lightweight software rendering framework.

A note from the founder encapsulates the project ethos: “Because of the nature of Moore’s law, anything that an extremely clever graphics programmer can do at one point can be replicated by a merely competent programmer some number of years later.” — John Carmack

In a nutshell, PortableGL is an implementation of OpenGL 3.x core (mostly; see GL Version) in clean C99 as a single header library, designed to be easy to drop into almost any codebase. It’s written in a style inspired by the stb single-header libraries, meaning you can compile cleanly as C++ and integrate it into various projects with minimal fuss. It’s intended to be compatible with anything that can input a 32- or 16-bit framebuffer/texture, in common formats. From image output to manual disk writes (via stbimagewrite or similar), PortableGL aims to support a broad range of use cases—subject to performance constraints of the platform.

The demos commonly rely on SDL2, but the repository also contains backends that demonstrate usage with other windowing backends (x11/xlib and win32). PortableGL supports arbitrary 32- and 16-bit color formats, with several common formats ready out of the box. For more detail, the project documentation is the best place to start.

The project’s priorities are clear:

• Portability
• Matching the API within reasonable bounds
• Ease of Use
• Straightforward code
• Speed

There are trade-offs, of course. One notable example is how shaders are implemented: rather than cloning GLSL parsing, a built-in compiler or interpreter isn’t included. Shaders are realized as special C/C++ functions that follow a specific prototype. Uniforms are implemented in a way that favors simplicity by passing pointers to user-defined structures, rather than trying to mirror every aspect of the OpenGL API. See the examples for how this pattern is used in practice.

Download, Get It, and How to Start

• Source: GitHub
• Homebrew: PortableGL can be installed via Homebrew

Gallery: Visual Highlights

• Gears, from the classic OpenGL demos
• Sphereworld: a demonstration of lighting, textures, and geometry
• Backpack model: a showcase of 3D model loading and rendering Backpack model example
• Craft: a PortableGL port that demonstrates a game-like scene

Directory Structure and What It Contains

• demos: Unpolished open-ended programs that demonstrate a wide variety of features
• examples: More polished demonstrations in C and C++, some graduating from demos
• original: Original custom examples; C++ programs use rsw_math rather than glm
• classic: Ports of classic OpenGL programs/demos (currently includes gears)
• webgl_lessons: Ports of lessons from learningwebgl.com based on OpenGL 3.3
• backends: “Hello triangle” using backends other than SDL2 (win32 and xlib)
• glcommon: Helper libraries used in graphics programming
• media: External resources
• models: Models in a simplified text format (created with demos/assimp_convert)
• screenshots: Screenshots of demos and external programs
• textures: Textures used in any program in the repo
• src: The actual source files of portablegl.h (amalgamated with generateglh.py)
• testing: Regression and performance test suites
• expected_output: The expected frames for regression tests
• test_output: Outputs from regression tests
• portablegl.h: Current development version of PortableGL

As with any project of this scope, bugs do slip in and occasionally there are non-breaking changes. The long-term plan includes more frequent point releases to fix issues and maintain alignment with semantic versioning.

Documentation and Learning Resources

• There is built-in documentation in the header’s top comments and in the file src/header_docs.txt, but there is no formal standalone documentation yet.
• The best way to learn is to study the examples and demos, then compare them to equivalent OpenGL 3.3+ programs.
• My LearnPortableGL project is particularly helpful: ports of learnopengl.com tutorials with comments explaining PortableGL’s differences and limitations in the early stages.
• For originalOpenGL comparisons, you can browse my opengl_reference repository.

OpenGL Versioning: What PortableGL Really Is

PortableGL positions itself as “3.x-ish” in spirit, rather than a strict 3.3 Core profile clone. Several decisions influence this stance:

• Shaders are implemented as C/C++ functions with a fixed prototype, not GLSL parsing.
• Uniform handling is designed for simplicity via user-defined structures.
• The project has grown to include 4.x diffuse-style features like Direct State Access (DSA) functions when it makes sense, especially since the rendering happens entirely in RAM in this software implementation.
• Client arrays and modern features are supported where practical; the end result is a hybrid that remains true to its 3.x foundation while embracing some helpful 4.x capabilities.
• In mid-2024, portablegl gained support for GL debug output (OpenGL 4.3). This provides a lightweight mechanism to print errors and message callbacks, though it remains tailored to PortableGL’s goals and is not a full OpenGL 4.3 implementation.

What PortableGL Is Not

PortableGL is not a drop-in replacement for libGL the way Mesa or similar software renderers are. Porting a real OpenGL program to PortableGL may require some changes:

• Windowing backend differences: Some windowing systems (like GLFW) assume an actual OpenGL context, whereas PortableGL renders directly to a pixel buffer. If you want full software rendering with windowed output, you’ll need a system that can blit raw pixels to the screen or use a minimal windowing binding that fits the PortableGL model.
• Backends exist for separate purposes (win32, xlib), but many “classic” OpenGL windowing toolkits aren’t directly compatible.

Backends, Ports, and Language Bindings

• portablegl-rs: A Rust port (with AI-assisted assistance) that demonstrates how PortableGL can be consumed from Rust code.
• pgl: A Go port using CXGO, with manual translations of demos and examples.
• The project also includes examples showing how to port to other environments and the potential for additional bindings.

Sponsors and Licensing

• PortableGL is released under the MIT License.
• The project has sponsorship channels, including GitHub Sponsors and other linked methods.
• Past sponsor Aeronix supported PortableGL in 2023.

History and Motivation

PortableGL began as a simple wireframe software renderer in the summer of 2011, inspired by a tutorial. Over the next year, incremental features were added, and in early 2013, the project pivoted to software OpenGL implementation. This decision aimed to sidestep API design obstacles by implementing a well-known API, which could be useful even as Mesa3D lagged in 3.x support. The journey featured bursts of progress and a focus on demos and examples. While an MVP could have appeared as early as 2014, the project matured into its current form around 2016 and beyond. After thousands of hours across more than a decade, PortableGL stands as a compact, portable, and educational OpenGL-like environment. The author continues to refine and polish PortableGL, acknowledging that “software is never finished,” and expressing openness to improvements and polish through ongoing development.

What PortableGL Is Useful For

• Educational purposes: PortableGL provides a compact foundation for teaching modern graphics concepts without requiring a heavyweight OpenGL environment.
• Research and experimentation: Because the codebase is relatively small and well-contained, researchers or students can modify core algorithms or data structures to explore new rendering approaches.
• Lightweight shader experimentation: Shaders in PortableGL are embedded C/C++ functions, enabling shader-style experimentation without a full GLSL compiler.

What PortableGL Is Not For

• It is not intended as a universal replacement for hardware-backed OpenGL environments in production-grade games or high-performance applications that demand raw-GPU-accelerated rendering.

References and Reading

• Fundamentals of Computer Graphics (3rd, 4th, and forthcoming 5th Editions) for math foundations and the transformation pipeline.
• OpenGL Superbible (5th edition) for historical OpenGL guidance and examples.
• OpenGL 4.x references for deeper API detail, and Khronos resources for core API references and tutorials.

Related Projects and Comparisons

• TinyGL and TinyGL Updated: Lightweight software renderers for OpenGL-style rendering in C; useful for historical comparison and educational insight.
• pixomatic and pixman: Historical software rasterization approaches and composition tools that can be complementary to PortableGL in various workflows.
• Softer open-source renderers and shader environments (SoftGLRender, EmberGL) that illustrate the spectrum of approaches to software rendering with shaders.

TODO and Future Ideas

• Render to texture support: Investigate FBOs/Renderbuffers/PixelBuffers and related render-to-texture workflows.
• Render-to-texture example programs to exercise off-screen rendering pipelines.
• Porting and documentation improvements: Move toward more complete LearnOpenGL-style tutorials, integrated documentation, and clearer setup instructions.
• Premake5 updates: Update build tooling to support multiple platforms as new toolchains emerge.
• Regression and performance testing: Ongoing WIP efforts for robust validation and benchmarking.

Notes on Learning and Using PortableGL

• If you’re seeking a lightweight way to explore OpenGL-like rendering concepts without a heavy GPU-backed environment, PortableGL offers a compact, readable codebase that can be extended by students and hobbyists.
• The single-header approach (portablegl.h) is designed to make integration simple and portable to a range of platforms with C99/C++ compilers.
• The project’s approach to shaders—treating them as special C/C++ functions—offers a pragmatic way to experiment with shading concepts while preserving the familiar OpenGL-like pipeline in a software renderer.

Images and Visuals

• The Shader Workshop banner image introduces the piece and sets the tone for shader-focused exploration.
• The gears, sphereworld, backpack, and craft visuals illustrate the variety of demos that PortableGL can power, from classic shader experiments to modern-style scene renderings.

Conclusion

PortableGL occupies a unique niche in the open-source graphics ecosystem: a portable, educational OpenGL-like library implemented as a clean C99 single-header solution. It emphasizes portability and ease of integration while offering a practical pathway to experiment with shaders and modern rendering concepts within a software-rendered context. The project’s history reflects a deliberate, iterative approach to evolving OpenGL-like capabilities in a way that remains approachable for students, educators, and hobbyists. The ongoing work—refinements to the GL versioning story, expanded tests, and richer documentation—promises to make PortableGL an even more valuable learning and experimentation platform in the years ahead. If you’re curious about shader art, learning modern OpenGL concepts without the complexity of a GPU driver stack, or contributing to a focused, small-footprint project, PortableGL presents a compelling path forward.