Merge pull request #1495 from floooh/sokol-framebuffer

implement sokol_framebuffer.h

Author: floooh

CHANGELOG.md

@@ -1,5 +1,23 @@
 ## Updates
 
+### 11-May-2026
+
+- A new header `sokol_framebuffer.h` has been added which provides a 'CPU framebuffer'
+  in 32-bits-per-pixel direct-color mode or 8-bits-per-pixel color-palette mode
+  (Mode13H-style).
+
+  Implementation PR: https://github.com/floooh/sokol/pull/1495
+
+  New samples:
+    - [framebuffer-sapp.c](https://floooh.github.io/sokol-html5/framebuffer-sapp.html): a 'simplest possible' example
+    - [ilbm-sapp.c](https://floooh.github.io/sokol-html5/ilbm-sapp.html): load and display Amiga IFF ILBM images
+
+  The following side-projects have also been moved to sokol_framebuffer.h (see the
+  sokol_framebuffer.h implementation PR for links to the side-project PRs):
+    - [Doom on Sokol](https://floooh.github.io/doom-sokol/)
+    - [Tiny Emulators](https://floooh.github.io/tiny8bit/)
+    - [Pacman.c](https://floooh.github.io/pacman.c/pacman.html)
+
 ### 04-May-2026
 
 - sokol_app.h android: The sokol-app Android backend now uses the Choreographer

README.md

@@ -6,7 +6,7 @@
 
 # Sokol
 
-[**See what's new**](https://github.com/floooh/sokol/blob/master/CHANGELOG.md) (**21-Apr-2026**: new header: sokol_letterbox.h)
+[**See what's new**](https://github.com/floooh/sokol/blob/master/CHANGELOG.md) (**11-May-2026**: new header: sokol_framebuffer.h)
 
 [![Build](/../../actions/workflows/main.yml/badge.svg)](/../../actions/workflows/main.yml) [![Bindings](/../../actions/workflows/gen_bindings.yml/badge.svg)](/../../actions/workflows/gen_bindings.yml) [![build](https://github.com/floooh/sokol-zig/actions/workflows/main.yml/badge.svg)](https://github.com/floooh/sokol-zig/actions/workflows/main.yml) [![build](https://github.com/floooh/sokol-nim/actions/workflows/main.yml/badge.svg)](https://github.com/floooh/sokol-nim/actions/workflows/main.yml) [![Odin](https://github.com/floooh/sokol-odin/actions/workflows/main.yml/badge.svg)](https://github.com/floooh/sokol-odin/actions/workflows/main.yml)[![Rust](https://github.com/floooh/sokol-rust/actions/workflows/main.yml/badge.svg)](https://github.com/floooh/sokol-rust/actions/workflows/main.yml)[![Dlang](https://github.com/floooh/sokol-d/actions/workflows/build.yml/badge.svg)](https://github.com/floooh/sokol-d/actions/workflows/build.yml)[![C3](https://github.com/floooh/sokol-c3/actions/workflows/build.yml/badge.svg)](https://github.com/floooh/sokol-c3/actions/workflows/build.yml)
 
@@ -85,6 +85,7 @@ useful details for integrating the Sokol headers into your own project with your
 - [**sokol\_color.h**](https://github.com/floooh/sokol/blob/master/util/sokol_color.h): X11 style color constants and functions for creating sg_color objects
 - [**sokol\_spine.h**](https://github.com/floooh/sokol/blob/master/util/sokol_spine.h): a sokol-style wrapper around the Spine C runtime (http://en.esotericsoftware.com/spine-in-depth)
 - [**sokol\_letterbox.h**](https://github.com/floooh/sokol/blob/master/util/sokol_letterbox.h): compute viewport params for rendering fixed-aspect-ratio content in a variable-aspect-ratio canvas
+- [**sokol\_framebuffer.h**](https://github.com/floooh/sokol/blob/master/util/sokol_framebuffer.h): provides CPU-framebuffers rendered via sokol_gfx.h
 
 ## 'Official' Language Bindings
 

shdgen/shdgen.ts

@@ -1,51 +1,34 @@
 import { parseArgs } from 'jsr:@std/cli@^1/parse-args';
 
-type Shader = { filename: string, prefix: string, prog: string };
-type Header = { path: string, shaders: Shader[] };
-
-const headers: Header[] = [
-    // sokol_gl.h
-    {
-        path: '../util/sokol_gl.h',
-        shaders: [ { filename: 'sokol_gl.glsl', prefix: '_sgl', prog: 'shd' } ],
-    },
-    // sokol_debugtext.h
-    {
-        path: '../util/sokol_debugtext.h',
-        shaders: [ { filename: 'sokol_debugtext.glsl', prefix: '_sdtx', prog: 'shd' } ],
-    },
-    // sokol_fontstash.h
-    {
-        path: '../util/sokol_fontstash.h',
-        shaders: [ { filename: 'sokol_fontstash.glsl', prefix: '_sfons', prog: 'shd' } ],
-    },
-    // sokol_imgui.h
-    {
-        path: '../util/sokol_imgui.h',
-        shaders: [ { filename: 'sokol_imgui.glsl', prefix: '_simgui', prog: 'shd' } ],
-    },
-    // sokol_nuklear.h
-    {
-        path: '../util/sokol_nuklear.h',
-        shaders: [ { filename: 'sokol_nuklear.glsl', prefix: '_snk', prog: 'shd' } ],
-    },
-    // sokol_spine.h
-    {
-        path: '../util/sokol_spine.h',
-        shaders: [ { filename: 'sokol_spine.glsl', prefix: '_sspine', prog: 'shd' } ],
-    },
-];
-
 const denoArgs = parseArgs(Deno.args, {
-    boolean: ['hlsl'],
-    string: ['shdcroot', 'branch'],
+    boolean: ['hlsl', 'local'],
+    string: ['shdcroot', 'branch', 'only'],
     default: {
         hlsl: false,
+        local: false,
         shdcroot: '../../sokol-tools-bin',
         branch: 'master',
+        only: null,
     },
 });
 
+type Item = { header: string, shader: string, prefix: string, progs: string[] };
+
+const items: Item[] = [
+    { header: '../util/sokol_gl.h', shader: 'sokol_gl.glsl', prefix: '_sgl', progs: ['shd'] },
+    { header: '../util/sokol_debugtext.h', shader: 'sokol_debugtext.glsl', prefix: '_sdtx', progs: ['shd'] },
+    { header: '../util/sokol_fontstash.h', shader: 'sokol_fontstash.glsl', prefix: '_sfons', progs: ['shd'] },
+    { header: '../util/sokol_imgui.h', shader: 'sokol_imgui.glsl', prefix: '_simgui', progs: ['shd'] },
+    { header: '../util/sokol_nuklear.h', shader: 'sokol_nuklear.glsl', prefix: '_snk', progs: ['shd'] },
+    { header: '../util/sokol_spine.h', shader: 'sokol_spine.glsl', prefix: '_sspine', progs: ['shd'] },
+    {
+        header: '../util/sokol_framebuffer.h',
+        shader: 'sokol_framebuffer.glsl',
+        prefix:  '_sfb',
+        progs: ['rgba8', 'palette8', 'render'],
+    }
+];
+
 function dirExists(path: string): boolean {
     try {
         return Deno.statSync(path).isDirectory;
@@ -62,34 +45,47 @@ async function main(): Promise<void> {
 
     if (denoArgs.hlsl) {
         // only compile hlsl shaders into binaries (runs on CI)
-        for (const hdr of headers) {
-            for (const shd of hdr.shaders) {
-                await compile(shd, true);
-            }
+        for (const item of items) {
+            await compile(item);
         }
     } else {
         // compile non-HLSL shader locally, and HLSL by triggering a remote Github CI run
-        await compileHlslRemote();
-        for (const hdr of headers) {
+        if (!denoArgs.local) {
+            await compileHlslRemote();
+        }
+        for (const item of items) {
+            await compile(item);
             const outp: string[] = []
-            for (const shd of hdr.shaders) {
-                await compile(shd, false);
-                outp.push(...gatherShader(shd));
+            for (const prog of item.progs) {
+                outp.push(...gatherShader(item, prog));
             }
-            inject(hdr.path, outp);
+            if (denoArgs.only && !item.header.includes(denoArgs.only)) {
+                continue;
+            }
+            inject(item.header, outp);
         }
     }
 }
 
-async function compile(shd: Shader, hlsl: boolean): Promise<void> {
-    await shdc([
-        '-i', shd.filename,
-        '-o', `out/${shd.filename}`,
+async function compile(item: Item): Promise<void> {
+    let slangs: string;
+    if (denoArgs.hlsl) {
+        slangs = 'hlsl4';
+    } else {
+        slangs = 'glsl410:glsl300es:metal_macos:metal_ios:metal_sim:wgsl:spirv_vk';
+        if (denoArgs.local) {
+            slangs += ':hlsl4';
+        }
+    }
+    const args = [
+        '-i', item.shader,
         '-t', 'out/tmpdir',
-        '-l', hlsl ? 'hlsl4' : 'glsl410:glsl300es:metal_macos:metal_ios:metal_sim:wgsl:spirv_vk',
-        '-f', 'bare_yaml',
+        '-l', slangs,
         '-b',
-    ]);
+    ];
+    // compile once as regular C header and once as bare_yaml
+    await shdc([...args, '-o', `out/${item.shader}.h`]);
+    await shdc([...args, '-o', `out/${item.shader}`, '-f', 'bare_yaml']);
 }
 
 function bytesToCArray(name: string, bytes: Uint8Array): string[] {
@@ -104,41 +100,45 @@ function bytesToCArray(name: string, bytes: Uint8Array): string[] {
     return lines;
 }
 
-function gatherSlang(shd: Shader, slang: string, ext: string, isBinary: boolean): string[] {
+function gatherSlang(item: Item, prog: string, slang: string, ext: string, isBinary: boolean): string[] {
     const res: string[] = [];
     for (const stage of ['vertex', 'fragment']) {
-        const path = `out/${shd.filename}_${shd.prog}_${slang}_${stage}${ext}`;
+        const path = `out/${item.shader}_${prog}_${slang}_${stage}${ext}`;
         let bytes: Uint8Array = Deno.readFileSync(path);
         if (!isBinary) {
             // for source code, append a terminating zero
             bytes = new Uint8Array([...bytes, 0]);
         }
-        const cArrayName = `${shd.prefix}_${shd.prog}_${stage==='vertex'?'vs':'fs'}_${isBinary?'bytecode':'source'}_${slang}`;
+        const cArrayName = `${item.prefix}_${prog}_${stage==='vertex'?'vs':'fs'}_${isBinary?'bytecode':'source'}_${slang}`;
         const cArray = bytesToCArray(cArrayName, bytes);
         res.push(...cArray);
     }
     return res;
 }
 
-function gatherShader(shd: Shader): string[] {
+function gatherShader(item: Item, prog: string): string[] {
     const res: string[] = [];
     res.push('#if defined(SOKOL_GLCORE)');
-    res.push(...gatherSlang(shd, 'glsl410', '.glsl', false));
+    res.push(...gatherSlang(item, prog, 'glsl410', '.glsl', false));
     res.push('#elif defined(SOKOL_GLES3)');
-    res.push(...gatherSlang(shd, 'glsl300es', '.glsl', false));
+    res.push(...gatherSlang(item, prog, 'glsl300es', '.glsl', false));
     res.push('#elif defined(SOKOL_METAL)');
-    res.push(...gatherSlang(shd, 'metal_macos', '.metallib', true));
-    res.push(...gatherSlang(shd, 'metal_ios', '.metallib', true));
-    res.push(...gatherSlang(shd, 'metal_sim', '.metal', false));
+    res.push(...gatherSlang(item, prog, 'metal_macos', '.metallib', true));
+    res.push(...gatherSlang(item, prog, 'metal_ios', '.metallib', true));
+    res.push(...gatherSlang(item, prog, 'metal_sim', '.metal', false));
     res.push('#elif defined(SOKOL_D3D11)');
-    res.push(...gatherSlang(shd, 'hlsl4', '.fxc', true));
+    if (denoArgs.local) {
+        res.push(...gatherSlang(item, prog, 'hlsl4', '.hlsl', false));
+    } else {
+        res.push(...gatherSlang(item, prog, 'hlsl4', '.fxc', true));
+    }
     res.push('#elif defined(SOKOL_WGPU)');
-    res.push(...gatherSlang(shd, 'wgsl', '.wgsl', false));
+    res.push(...gatherSlang(item, prog, 'wgsl', '.wgsl', false));
     res.push('#elif defined(SOKOL_VULKAN)');
-    res.push(...gatherSlang(shd, 'spirv_vk', '', true));
+    res.push(...gatherSlang(item, prog, 'spirv_vk', '', true));
     res.push('#elif defined(SOKOL_DUMMY_BACKEND)');
-    res.push(`static const char* ${shd.prefix}_vs_source_dummy = "";`);
-    res.push(`static const char* ${shd.prefix}_fs_source_dummy = "";`);
+    res.push(`static const char* ${item.prefix}_${prog}_vs_source_dummy = "";`);
+    res.push(`static const char* ${item.prefix}_${prog}_fs_source_dummy = "";`);
     res.push('#else');
     res.push('#error "Please define one of SOKOL_GLCORE, SOKOL_GLES3, SOKOL_D3D11, SOKOL_METAL, SOKOL_WGPU, SOKOL_VULKAN or SOKOL_DUMMY_BACKEND!"');
     res.push('#endif');

shdgen/sokol_framebuffer.glsl

@@ -0,0 +1,72 @@
+@vs offscreen_vs
+@glsl_options flip_vert_y
+layout(binding=0) uniform offscreen_vs_params {
+    vec2 uv_offset;
+    vec2 uv_scale;
+};
+out vec2 uv;
+
+void main() {
+    float x = (gl_VertexIndex & 1) != 0 ? 2.0 : 0.0;
+    float y = (gl_VertexIndex & 2) != 0 ? 2.0 : 0.0;
+    gl_Position = vec4(vec2(x, y) * 2.0 - 1.0, 0.5, 1.0);
+    uv = (vec2(x, 1.0 - y) * uv_scale) + uv_offset;
+}
+@end
+@fs rgba8_fs
+layout(binding=0) uniform texture2D fb_tex;
+layout(binding=0) uniform sampler smp;
+in vec2 uv;
+out vec4 frag_color;
+void main() {
+    frag_color = texture(sampler2D(fb_tex, smp), uv);
+}
+@end
+@program rgba8 offscreen_vs rgba8_fs
+
+// offscreen shader with color palette decoding
+@fs palette8_fs
+layout(binding=0) uniform texture2D fb_tex;
+layout(binding=1) uniform texture2D pal_tex;
+layout(binding=0) uniform sampler smp;
+in vec2 uv;
+out vec4 frag_color;
+void main() {
+    float pix = texture(sampler2D(fb_tex, smp), uv).x;
+    frag_color = vec4(texture(sampler2D(pal_tex, smp), vec2(pix,0)).xyz, 1.0);
+}
+@end
+@program palette8 offscreen_vs palette8_fs
+
+@vs render_vs
+layout(binding=0) uniform render_vs_params {
+    int rotate;
+};
+out vec2 uv;
+
+void main() {
+    vec2 in_pos, in_uv;
+    in_pos.x = (gl_VertexIndex & 1) != 0 ? 2.0 : 0.0;
+    in_pos.y = (gl_VertexIndex & 2) != 0 ? 2.0 : 0.0;
+    if (rotate == 0) {
+        in_uv.x = in_pos.x;
+        in_uv.y = 1.0 - in_pos.y;
+    } else {
+        in_uv.x = 1.0 - in_pos.y;
+        in_uv.y = 1.0 - in_pos.x;
+    }
+    gl_Position = vec4(in_pos*2.0-1.0, 0.5, 1.0);
+    uv = in_uv;
+}
+@end
+@fs render_fs
+layout(binding=0) uniform texture2D tex;
+layout(binding=0) uniform sampler smp;
+in vec2 uv;
+out vec4 frag_color;
+
+void main() {
+    frag_color = vec4(texture(sampler2D(tex, smp), uv).xyz, 1.0);
+}
+@end
+@program render render_vs render_fs

util/sokol_debugtext.h

@@ -3609,8 +3609,8 @@ static const uint8_t _sdtx_shd_fs_bytecode_spirv_vk[816] = {
     0x09,0x00,0x00,0x00,0x1d,0x00,0x00,0x00,0xfd,0x00,0x01,0x00,0x38,0x00,0x01,0x00,
 };
 #elif defined(SOKOL_DUMMY_BACKEND)
-static const char* _sdtx_vs_source_dummy = "";
-static const char* _sdtx_fs_source_dummy = "";
+static const char* _sdtx_shd_vs_source_dummy = "";
+static const char* _sdtx_shd_fs_source_dummy = "";
 #else
 #error "Please define one of SOKOL_GLCORE, SOKOL_GLES3, SOKOL_D3D11, SOKOL_METAL, SOKOL_WGPU, SOKOL_VULKAN or SOKOL_DUMMY_BACKEND!"
 #endif
@@ -4153,8 +4153,8 @@ static void _sdtx_setup_common(void) {
         shd_desc.fragment_func.bytecode = SG_RANGE(_sdtx_shd_fs_bytecode_spirv_vk);
         shd_desc.fragment_func.entry = "main";
     #else
-        shd_desc.vertex_func.source = _sdtx_vs_source_dummy;
-        shd_desc.fragment_func.source = _sdtx_fs_source_dummy;
+        shd_desc.vertex_func.source = _sdtx_shd_vs_source_dummy;
+        shd_desc.fragment_func.source = _sdtx_shd_fs_source_dummy;
     #endif
     _sdtx.shader = sg_make_shader(&shd_desc);
     SOKOL_ASSERT(SG_INVALID_ID != _sdtx.shader.id);

util/sokol_fontstash.h

@@ -1705,8 +1705,8 @@ static const uint8_t _sfons_shd_fs_bytecode_spirv_vk[888] = {
     0xfd,0x00,0x01,0x00,0x38,0x00,0x01,0x00,
 };
 #elif defined(SOKOL_DUMMY_BACKEND)
-static const char* _sfons_vs_source_dummy = "";
-static const char* _sfons_fs_source_dummy = "";
+static const char* _sfons_shd_vs_source_dummy = "";
+static const char* _sfons_shd_fs_source_dummy = "";
 #else
 #error "Please define one of SOKOL_GLCORE, SOKOL_GLES3, SOKOL_D3D11, SOKOL_METAL, SOKOL_WGPU, SOKOL_VULKAN or SOKOL_DUMMY_BACKEND!"
 #endif
@@ -1841,8 +1841,8 @@ static int _sfons_render_create(void* user_ptr, int width, int height) {
             shd_desc.fragment_func.bytecode = SG_RANGE(_sfons_shd_fs_bytecode_spirv_vk);
             shd_desc.fragment_func.entry = "main";
         #else
-            shd_desc.vertex_func.source = _sfons_vs_source_dummy;
-            shd_desc.fragment_func.source = _sfons_fs_source_dummy;
+            shd_desc.vertex_func.source = _sfons_shd_vs_source_dummy;
+            shd_desc.fragment_func.source = _sfons_shd_fs_source_dummy;
         #endif
         shd_desc.label = "sfons-shader";
         sfons->shd = sg_make_shader(&shd_desc);