sokol-samples

Sample code for https://github.com/floooh/sokol

WASM live demos:

• for WebGL2: https://floooh.github.io/sokol-html5/index.html
• for WebGPU: https://floooh.github.io/sokol-webgpu/index.html

Prerequisites

Make sure the following tools are installed:

• deno (https://docs.deno.com/runtime/getting_started/installation/)
• cmake
• your system's default C/C++ toolchain (MSVC, GCC or Clang)
• optional but recommended: ninja

[!NOTE] On Linux you'll also need to install packages for OpenGL, X11, ALSA and Vulkan development, e.g. libgl1-mesa-dev, libegl1-mesa-dev, mesa-common-dev, xorg-dev, libasound-dev, libvulkan-dev, vulkan-validationlayers, vulkan-tools

[!NOTE] On Windows with Vulkan development you need to install the Vulkan SDK and before building, make sure that the environement variable VULKAN_SDK is valid

[!NOTE] On Windows run the build in a 'Visual Studio Command Prompt' terminal window.

Build and running samples

To build the samples in the host platform's default release-mode configuration:

git clone https://github.com/floooh/sokol-samples
cd sokol-samples
./fibs build

...then list all executable samples:

./fibs list targets --exe

...and run any of the samples, e.g.:

./fibs run triangle-sapp-ui

Alternatively configure for a specific build configuration:

./fibs config [build-config-name]

To see a list of all build configs:

./fibs list configs

To search for specific build configs, use grep or rg (ripgrep):

./fibs list configs | grep d3d11
./fibs list configs | rg macos

To open a project in an IDE, first configure with a build config which has -vstudio-, -vscode- or -xcode- in the name, and then run ./fibs open, e.g.:

./fibs config sapp-metal-macos-vscode-debug
./fibs open

...for additional documentation on the fibs meta-build-system see:

• https://github.com/floooh/fibs

Cross-compile to Emscripten, iOS or Android

Emscripten

First install the Emscripten SDK (this will take a while):

./fibs emsdk install

Then pick one of the build configs with -emsc- in the name, build and run:

./fibs config sapp-gles-emsc-ninja-debug
./fibs build
./fibs run triangle-sapp

...this should open the system default web browser, running the selected sample.

iOS

Pick an iOS build config and open in Xcode:

./fibs config sapp-metal-ios-xcode-debug
./fibs open

...then build and run in the iOS simulator or iOS device.

To build and run on a real device you may need to provide an iOS Team Id, do this via:

./fibs set iosteamid [your-team-id]
./fibs config sapp-metal-ios-xcode-debug

Android

Install a JDK version 17, and check via ./fibs diag tools whether fibs can find java, javac and unzip:

./fibs diag tools
...
java:   found
unzip:  found
cwebp:  found

...next install the Android SDK/NDK via:

./fibs android install

...then pick one of the Android build configs and build:

./fibs config sapp-gles-android-ninja-debug
./fibs build

...finally run any of the samples on an attached Android device:

./fibs run triangle-sapp

Configuring for local sokol development

Clone sokol into a 'sister directory' of sokol-samples, e.g. from within the sokol-samples directory:

git clone https://github.com/floooh/sokol ../sokol

...next 'link' the cloned directory to the sokol import:

./fibs link sokol ../sokol
 linked import 'sokol' to '/Users/floh/projects/sokol'

...verify via ./fibs list imports:

./fibs list imports
...
sokol: link => /Users/floh/projects/sokol
...

The sokol-samples project will now use the linked sokol repository instead of the local imported version in the .fibs/imports subdirectory.

How to build without a build system

Many samples are simple enough to be built directly on the command line without a build system, and the following examples of that might be helpful for integrating the sokol headers and/or the sokol sample code into your own project with the build system of your choice.

The expected directory structure for building the sokol-samples manually is as follows (e.g. those directories must be cloned side-by-side):

sokol-samples
sokol
sokol-tools-bin

For instance:

> mkdir scratch
> cd scratch
> git clone https://github.com/floooh/sokol-samples
> git clone https://github.com/floooh/sokol
> git clone https://github.com/floooh/sokol-tools-bin

Of course, in your own project you can put the sokol headers wherever you want (I recommend copying them somewhere into your source directory), and you don't have to use the prebuilt sokol-shdc shader compiler either.

[!NOTE] For Release builds, you might want to add the compiler's respective optimization flags, and provide an NDEBUG define so that assert() checks and the sokol-gfx validation layer are removed (BUT please don't do this for the Debug/Dev builds because asserts() and the validation layer give important feedback if something goes wrong).

Building manually on macOS with clang

To build one of the Metal samples:

> cd sokol-samples/metal
> cc cube-metal.c osxentry.m sokol_gfx.m -o cube-metal -fobjc-arc -I../../sokol -framework Metal -framework AppKit -framework QuartzCore

To build one of the GLFW samples (requires a system-wide glfw install, e.g. brew install glfw):

> cd sokol-samples/glfw
> cc cube-glfw.c flextgl/flextGL.c -o cube-glfw -I../../sokol -lglfw -framework OpenGL -framework AppKit

To build one of the sokol-app samples for Metal:

> cd sokol-samples/sapp
> ../../sokol-tools-bin/bin/osx/sokol-shdc -i cube-sapp.glsl -o cube-sapp.glsl.h -l metal_macos
> cc cube-sapp.c ../libs/sokol/sokol.m -o cube-sapp -DSOKOL_METAL -fobjc-arc -I../../sokol -I ../libs -framework Metal -framework AppKit -framework QuartzCore -framework AudioToolbox

To build one of the sokol-app samples for GL on macOS:

> cd sokol-samples/sapp
> ../../sokol-tools-bin/bin/osx/sokol-shdc -i cube-sapp.glsl -o cube-sapp.glsl.h -l glsl430
> cc cube-sapp.c ../libs/sokol/sokol.m -o cube-sapp -fobjc-arc -DSOKOL_GLCORE -I../../sokol -I../libs -framework OpenGL -framework AppKit -framework AudioToolbox

Building manually on Windows with MSVC

From the VSxxxx x64 Native Tools Command Prompt (for 64-bit builds) or Developer Command Prompt for VSxxxx (for 32-bit builds):

To build one of the D3D11 samples:

> cd sokol-samples\d3d11
> cl cube-d3d11.c d3d11entry.c /I..\..\sokol

To build one of the sokol-app samples for D3D11:

> cd sokol-samples\sapp
> ..\..\sokol-tools-bin\bin\win32\sokol-shdc -i cube-sapp.glsl -o cube-sapp.glsl.h -l hlsl5
> cl cube-sapp.c ..\libs\sokol\sokol.c /DSOKOL_D3D11 /I..\..\sokol /I..\libs

To build one of the sokol-app samples for GL on Windows:

> cd sokol-samples\sapp
> ..\..\sokol-tools-bin\bin\win32\sokol-shdc -i cube-sapp.glsl -o cube-sapp.glsl.h -l glsl430
> cl cube-sapp.c ..\libs\sokol\sokol.c /DSOKOL_GLCORE /I..\..\sokol /I..\libs kernel32.lib user32.lib gdi32.lib

Building manually on Windows with MSYS2/mingw gcc:

[!NOTE] Compile with '-mwin32' (this defines _WIN32 for proper platform detection)

From the MSYS2 shell:

> cd sokol-samples/sapp
# compile shaders for HLSL and GLSL:
> ../../sokol-tools-bin/bin/win32/sokol-shdc -i cube-sapp.glsl -o cube-sapp.glsl.h -l hlsl5:glsl430
# build and run with D3D11 backend:
> gcc cube-sapp.c ../libs/sokol/sokol.c -o cube-sapp-d3d11 -mwin32 -O2 -DSOKOL_D3D11 -I../../sokol -I ../libs -lkernel32 -luser32 -lshell32 -ldxgi -ld3d11 -lole32 -lgdi32
> ./cube-sapp-d3d11
# build and run with GL backend:
> gcc cube-sapp.c ../libs/sokol/sokol.c -o cube-sapp-gl -mwin32 -O2 -DSOKOL_GLCORE -I../../sokol -I ../libs -lkernel32 -luser32 -lshell32 -lgdi32 -lole32
> ./cube-sapp-gl

Building manually on Windows with Clang:

[!NOTE] AFAIK Clang for Windows needs a working MSVC toolchain and Windows SDK installed, I haven't tested without.

Clang recognizes the #pragma comment(lib,...) statements in the Sokol headers, so you don't need to specify the link libraries manually.

> cd sokol-samples/sapp
# compile shaders for HLSL and GLSL:
> ..\..\sokol-tools-bin\bin\win32\sokol-shdc -i cube-sapp.glsl -o cube-sapp.glsl.h -l hlsl5:glsl430
# build and run with D3D11 backend:
> clang cube-sapp.c ../libs/sokol/sokol.c -o cube-sapp-d3d11.exe -O2 -DSOKOL_D3D11 -I ../../sokol -I ../libs
> cube-sapp-d3d11
# build and run with GL backend:
> clang cube-sapp.c ../libs/sokol/sokol.c -o cube-sapp-gl.exe -O2 -DSOKOL_GLCORE -I ../../sokol -I ../libs
> cube-sapp-gl

Building manually on Linux with gcc

On Linux you need the "usual" development-packages for OpenGL development, and for the GLFW samples, also the GLFW development package (on Ubuntu it's called libglfw3-dev).

To build one of the GLFW samples on Linux:

> cd sokol-samples/glfw
> cc cube-glfw.c glfw_glue.c flextgl/flextGL.c -o cube-glfw -I../../sokol -lGL -ldl -lm -lglfw3

To build one of the sokol-app samples on Linux:

> cd sokol-samples/sapp
> ../../sokol-tools-bin/bin/linux/sokol-shdc -i cube-sapp.glsl -o cube-sapp.glsl.h -l glsl430
> cc cube-sapp.c ../libs/sokol/sokol.c -o cube-sapp -DSOKOL_GLCORE -pthread -I../../sokol -I../libs -lGL -ldl -lm -lX11 -lasound -lXi -lXcursor

Building for WASM / WebGL2

Make sure emcc and emrun from the Emscripten SDK are in the path.

> cd sokol-samples/html5
> emcc cube-emsc.c -o cube-emsc.html -I../../sokol -sUSE_WEBGL2 --shell-file=../webpage/shell.html
> emrun cube-emsc.html

...and for the sokol-app samples:

> sokol-samples/sapp
> ../../sokol-tools-bin/bin/[platform]/sokol-shdc -i cube-sapp.glsl -o cube-sapp.glsl.h -l glsl300es
> emcc cube-sapp.c ../libs/sokol/sokol.c -o cube-sapp.html -DSOKOL_GLES3 -I../../sokol -I../libs -sUSE_WEBGL2 --shell-file=../webpage/shell.html
> emrun cube-sapp.html

Many Thanks to:

• GLFW: https://github.com/glfw/glfw
• flextGL: https://github.com/ginkgo/flextGL
• vecmath: https://github.com/mattiasgustavsson/libs/blob/main/docs/vecmath.md
• Dear Imgui: https://github.com/ocornut/imgui
• cimgui: https://github.com/cimgui/cimgui
• utest.h: https://github.com/sheredom/utest.h
• Ozz Animation: https://github.com/guillaumeblanc/ozz-animation

Enjoy!