Sokol.NET

Modern, cross-platform graphics and multimedia framework for C# with .NET NativeAOT

Sokol.NET is a comprehensive C# binding and application framework built on top of the Sokol headers, providing a modern, high-performance graphics API with support for desktop, mobile, and web platforms.

⚠️ Development Status: This project is under ongoing development, primarily driven by the needs of my internal projects. Future development beyond my personal technical requirements will depend on public interest and community contributions.

🌐 Live Examples

✨ Try all 36 examples in your browser →

Experience Sokol.NET's capabilities instantly with interactive WebAssembly examples. No installation required!

🎯 Features

Cross-Platform: Deploy to Windows, macOS, Linux, Android, iOS, and WebAssembly from a single codebase
High Performance: Leverages .NET NativeAOT for near-native performance with zero overhead
Modern Graphics: Unified API supporting Direct3D 11, Metal, OpenGL, OpenGL ES, and WebGL
Rich Examples: 36 example applications demonstrating various graphics techniques and features
Production Ready: Includes ImGui, Assimp, glTF, Spine, Ozz animation, and more integrations

🚀 Supported Platforms

Platform	Runtime	Graphics API	Status
Windows	JIT/NativeAOT	Direct3D 11	✅ Full Support
macOS	JIT/NativeAOT	Metal	✅ Full Support
Linux	JIT/NativeAOT	OpenGL	✅ Full Support
Android	NativeAOT (Bionic)	OpenGL ES 3.0	✅ Full Support (APK/AAB)
iOS	NativeAOT	Metal	✅ Full Support
WebAssembly	WASM	WebGL 2.0	✅ Full Support

📦 What's Included

Core Libraries

sokol_gfx: Modern 3D graphics API abstraction
sokol_app: Unified application/window management
sokol_audio: Cross-platform audio playback
sokol_fetch: Asynchronous resource loading
sokol_time: High-precision timing
sokol_gl: OpenGL 1.x style immediate mode rendering
sokol_gp: 2D graphics painter API
sokol_debugtext: Text rendering for debugging
sokol_shape: Procedural 3D shape generation

Integrated Libraries

Dear ImGui (cimgui): Immediate mode GUI toolkit
cgltf: glTF 2.0 loader
Basis Universal: GPU texture compression
fontstash: Dynamic font rendering
stb_image: Image loading (PNG, JPG, etc.)
pl_mpeg: MPEG1 video playback

External Optional Libraries

These libraries are available as separate dynamic libraries that can be loaded when needed:

Assimp: 3D model loading (40+ formats) - Load dynamically via native library configuration
- Note: May have performance issues on low-tier Android devices. Consider using GltfViewer (SharpGLTF-based) or cgltf for better compatibility and performance.
Spine: 2D skeletal animation runtime - Load dynamically via native library configuration
Ozz-animation: 3D skeletal animation system - Load dynamically via native library configuration

See example projects (assimp_simple, spine_simple, ozz_shdfeatures) and their Directory.Build.props files for configuration details.

Recommended: For glTF 2.0 models, use the GltfViewer example - a production-ready, full-featured glTF viewer with PBR rendering, animations, and advanced material support.

🎮 Example Applications

The examples/ folder contains 36 sample applications demonstrating various features:

Graphics Fundamentals

clear - Basic window and clear color
cube - Rotating 3D cube with texture
instancing - Hardware instancing demonstration
offscreen - Render-to-texture techniques
mrt - Multiple render targets
shadows - Shadow mapping implementation

2D Graphics

sgl - 2D immediate mode rendering
sgl_lines - Line rendering techniques
shapes_transform - 2D transformations
dyntex - Dynamic texture updates

Text & Fonts

debugtext - Debug text overlay
debugtext_context - Multiple text contexts
fontstash - TrueType font rendering
fontstash_layers - Layered text effects

3D Models & Animation

assimp_simple - Basic 3D model loading
assimp_animation - Skeletal animation with Assimp
assimp_scene - Complex scene loading
cgltf - glTF 2.0 model loading
GltfViewer - Full-featured glTF viewer
ozz_shdfeatures - Ozz animation system with shader features

2D Animation

spine_simple - Basic Spine animation
spine_skinsets - Spine skin swapping
spine_inspector - Spine animation debugger

Textures & Materials

loadpng - PNG texture loading
basisu - Basis Universal GPU textures
cubemap_jpeg - Cubemap textures
cubemaprt - Render-to-cubemap
miprender - Mipmap generation
vertextexture - Vertex texture fetch
texview - Texture viewer utility
sdf - Signed distance field rendering

UI & Integration

cimgui - Dear ImGui integration
imgui_usercallback - Custom ImGui rendering

Advanced

drawcallperf - Draw call performance testing
plmpeg - MPEG1 video playback

📜 Spine License Notice

Some examples in this repository (spine_simple, spine_skinsets, spine_inspector) use the Spine runtime library.

Important for Users: While you are free to evaluate and build these examples, if you wish to use Spine in your own projects, you will need to purchase a Spine license. The Spine Runtimes are covered by the Spine Runtimes License Agreement.

This repository's maintainer has a valid Spine license for development and distribution of these examples.

🛠️ Prerequisites

.NET 10.0 SDK or later
CMake 3.29.0 or later (required for building native libraries)
Visual Studio Code (primary development IDE)
- Required for Android and iOS development (build/install/debug)
- Supports all platforms: Desktop, Web, Android, and iOS
- Alternative IDEs (Visual Studio, Rider) support Desktop and Web only
wasm-tools-net8 workload (for WebAssembly development): dotnet workload install wasm-tools-net8
Platform-specific toolchains:
- Windows: Visual Studio 2022 Build Tools
- macOS: Xcode Command Line Tools
- Linux: GCC/Clang
- Android: Android SDK & NDK 25+
- iOS: Xcode 14+

🏁 Quick Start

1. Clone and Register

git clone --recursive https://github.com/elix22/Sokol.NET.git
cd Sokol.NET

# Register the repository (creates ~/.sokolnet_config)
./register.sh  # macOS/Linux
# or
register.bat   # Windows

2. Run Examples

📘 Complete VS Code Run Guide with Screenshots - Get started instantly with step-by-step instructions for running applications on all platforms.

Using Visual Studio Code (Recommended)

VS Code is the primary development environment with full support for all platforms.

Desktop & Web: Press F5 and select your platform and example.

Android & iOS: Use Command Palette (Cmd+Shift+P / Ctrl+Shift+P) → Tasks: Run Task:

Android Tasks:

Android: List Devices - List all connected Android devices
Android: Build APK - Build release/debug APK
Android: Build AAB - Build release/debug Android App Bundle
Android: Install APK - Build and install APK to selected device
Android: Install AAB - Build and install AAB to selected device

iOS Tasks:

iOS: List Devices - List all connected iOS devices
iOS: Build - Build release/debug iOS app
iOS: Install - Build and install to selected iOS device

Using Command Line or Other IDEs

Desktop (works with Visual Studio, Rider, or command line):

cd examples/cube
dotnet build cube.csproj -t:CompileShaders
dotnet build cube.csproj
dotnet run -p cube.csproj

Note: Visual Studio and Rider support Desktop and Web development only. For Android and iOS, use Visual Studio Code.

3. Build for Other Platforms

Android APK/AAB

dotnet run --project tools/SokolApplicationBuilder -- \
  --task build --architecture android --type release \
  --path examples/cube --install --interactive

iOS

dotnet run --project tools/SokolApplicationBuilder -- \
  --task build --architecture ios --type release \
  --path examples/cube --install --interactive

WebAssembly

dotnet run --project tools/SokolApplicationBuilder -- \
  --task build --architecture web \
  --path examples/cube

See docs/web-server-setup.md for running WebAssembly apps locally.

📚 Documentation

Comprehensive documentation is available in the docs/ folder:

Getting Started

Visual Studio Code Run Guide ⭐ - Step-by-step guide with screenshots for running apps on all platforms
Shader Programming Guide 🎨 - Complete guide to writing cross-platform shaders with sokol-shdc
Creating New Examples 🆕 - How to create new example projects from template

Platform-Specific Guides

Android
iOS
- iOS Device Selection & Installation
- iOS Properties Configuration
WebAssembly

Build System & Deployment

Build System Documentation - Complete build system reference
Quick Build Reference - Common build commands
Sokol Application Builder - Build tool documentation
Multi-Device Install - Installing to multiple devices

Configuration & Customization

Advanced Topics

📖 Full Documentation Index

🏗️ Project Structure

Sokol.NET/
├── examples/          # 36 example applications
├── src/              # C# bindings and core libraries
├── ext/              # Native C/C++ dependencies
│   ├── sokol/       # Sokol headers
│   ├── cimgui/      # ImGui C bindings
│   ├── assimp/      # 3D model loader
│   ├── cgltf/       # glTF loader
│   ├── spine-c/     # Spine runtime
│   └── ozz-animation/ # Animation system
├── libs/             # Prebuilt native libraries
│   ├── windows/
│   ├── macos/
│   ├── linux/
│   ├── android/
│   ├── ios/
│   └── emscripten/
├── tools/            # Build tools and utilities
│   └── SokolApplicationBuilder/
├── bindgen/          # C# binding generator
├── docs/             # Documentation
└── templates/        # Project templates

🔧 Building Native Libraries

Native Sokol libraries are pre-built and included in the libs/ folder. To rebuild:

Windows

.\scripts\build-vs2022-windows.ps1

macOS

./scripts/build-xcode-macos.sh

Linux

./scripts/build-linux-library.sh

Android

./scripts/build-android-sokol-libraries.sh

iOS

./scripts/build-ios-sokol-library.sh

See docs/BUILD_SYSTEM.md for detailed build instructions.

🤝 Contributing

Contributions are welcome! Please ensure:

Code follows existing style and conventions
All platforms continue to build successfully
Examples run without errors
Documentation is updated for new features

📄 License

This project is licensed under the MIT License. See individual library folders for their respective licenses:

Sokol: zlib/libpng license
ImGui: MIT License
Assimp: BSD 3-Clause License
Spine: Spine Runtime License

🙏 Credits

Built on top of these excellent libraries:

Sokol by Andre Weissflog
Dear ImGui by Omar Cornut
Assimp - Open Asset Import Library
cgltf by Johannes Kuhlmann
Spine Runtimes by Esoteric Software
Ozz-animation by Guillaume Blanc

📞 Support & Community

Issues: GitHub Issues
Author: Eli Aloni (elix22)

Get started now: Clone the repository, run ./register.sh, and explore the examples!

Name		Name	Last commit message	Last commit date
Latest commit History 15 Commits
.github/workflows		.github/workflows
.vscode		.vscode
bindgen		bindgen
docs		docs
examples		examples
ext		ext
libs		libs
screenshots		screenshots
scripts		scripts
src		src
templates		templates
tools		tools
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitmodules		.gitmodules
Android.Build.targets		Android.Build.targets
BionicNativeAot.targets		BionicNativeAot.targets
Directory.Build.props		Directory.Build.props
LICENSE		LICENSE
README.md		README.md
Sokol.NET.sln		Sokol.NET.sln
iOS.Build.targets		iOS.Build.targets
register.bat		register.bat
register.sh		register.sh
sokol_net_root		sokol_net_root

License

DavidAlphaFox/Sokol.NET

Folders and files

Latest commit

History

Repository files navigation