Doxxx

jdolan · jdolan · commit ffca94d4ea6c · 2026-06-30T20:14:01.000-04:00
diff --git a/Documentation/ObjectivelyMVC-Hello.gif b/Documentation/ObjectivelyMVC-Hello.gif
diff --git a/Documentation/index.md b/Documentation/index.md
@@ -6,28 +6,71 @@ Object oriented graphics framework for SDL3 and C.
 
 ## About
 
-[ObjectivelyGPU](https://github.com/jdolan/ObjectivelyGPU) is a cross-platform, object oriented graphics framework for the C programming language. Built on [Objectively](https://github.com/jdolan/Objectively) and [SDL3](https://libsdl.org)'s GPU API, it provides a clean, idiomatic C API for modern GPU programming across Metal, Vulkan, and Direct3D 12.
+[ObjectivelyGPU](https://github.com/jdolan/ObjectivelyGPU) is a cross-platform object oriented graphics framework for the C programming language. Built on [Objectively](https://github.com/jdolan/Objectively) and [SDL3_gpu](https://libsdl.org), it provides a unified API for modern GPU programming with Metal, Vulkan, and Direct3D 12.
 
 ## Features
 
-- **macOS, iOS, Windows, Linux & Android** cross-platform support via SDL3 (Metal, Direct3D 12, Vulkan)
-- **RenderDevice** owns the swapchain — drive frames with a simple `beginFrame` / `endFrame` loop
-- **Resource objects** with automatic lifecycle: Buffer, Texture, Sampler, Shader, GraphicsPipeline, ComputePipeline
-- **Typed passes**: RenderPass, ComputePass, CopyPass with command-lifecycle validation
-- **Framebuffer** with multiple render targets, depth, and MSAA with automatic resolve
-- **Shaders** in every format SDL3 supports (SPIR-V, MSL, DXIL), loaded by name with automatic per-backend selection
-- **Mathlib**: vector, matrix, and quaternion math for 3D graphics
+- **Cross-platform** support for Android, iOS, macOS, Linux and Windows
+- **RenderDevice** owns the swapchain — drive frames with a simple `beginFrame` / `endFrame` loop and an unambiguous order of operations
+- **Resource objects** with automatic lifecycle — Buffer, Texture, Sampler, Shader, GraphicsPipeline and ComputePipeline initialize and tear themselves down
+- **Typed passes**: RenderPass, ComputePass and CopyPass with command-lifecycle validation that catches mistakes upfront
+- **Framebuffer** abstracts multiple render targets, depth, and MSAA with automatic resolve — convenience without forfeiting the low-level API
+- **Shaders** in every format SDL3 supports — SPIR-V (Vulkan), MSL (Metal) and DXIL (D3D12) — loaded by name with automatic per-backend selection; author them in any language and cross-compile with [SDL_shadercross](https://github.com/libsdl-org/SDL_shadercross), or bring your own blobs
+- **Mathlib** — vector, matrix, and quaternion math for 3D graphics
+
+## tl;dr
+
+The verbose, error-prone handling of a raw GPU API collapses into reference-counted objects and a handful of intuitive methods.
+
+Uploading an image to the GPU is a single call — the staging buffer and copy pass are handled for you:
+
+```c
+SDL_Surface *surface = IMG_Load("crate.png");
+Texture *texture = $(renderDevice, createTextureFromSurface, surface, SDL_GPU_TEXTUREUSAGE_SAMPLER);
+SDL_DestroySurface(surface);
+```
+
+And a whole frame — acquire the swapchain, clear, draw a multisampled scene, resolve, and present:
+
+```c
+CommandBuffer *commands = $(renderDevice, beginFrame);
+if (commands) {
+
+  const SDL_FColor clearColor = { 0.1f, 0.1f, 0.2f, 1.f };
+  const SDL_GPUColorTargetInfo color = $(framebuffer, colorTargetInfo, 0, SDL_GPU_LOADOP_CLEAR, SDL_GPU_STOREOP_STORE, &clearColor);
+  const SDL_GPUDepthStencilTargetInfo depth = $(framebuffer, depthTargetInfo, SDL_GPU_LOADOP_CLEAR, SDL_GPU_STOREOP_DONT_CARE, 1.f);
+
+  RenderPass *pass = $(commands, beginRenderPass, &color, 1, &depth);
+  $(pass, bindPipeline, pipeline);
+  $(pass, bindVertexBuffers, 0, &(SDL_GPUBufferBinding) { .buffer = vertexBuffer->buffer }, 1);
+  $(pass, drawPrimitives, 36, 1, 0, 0);
+  pass = release(pass);
+
+  $(renderDevice, endFrame);
+}
+```
+
+The `endFrame` method resolves the multisampled `Framebuffer` and presents to the swapchain for you. No manual resolve targets, no store-op bookkeeping, no presentation plumbing.
+
+## Getting Started
+
+Consult the @subpage install for dependencies, building, and linking.
 
 ## User Guide
 
-Consult the @subpage guide [User Guide] to draw your first frame.
+Consult the @subpage guide to draw your first frame — the render device, resource objects, framebuffers and MSAA, the typed passes, and shaders.
 
 ## Class Hierarchy
 
 Browse the [Class Hierarchy](hierarchy.html) to navigate the full API.
 
-## Examples
+## Project Showcase
 
-![Hello — a spinning, multisampled 3D cube](Hello.gif)
+1. [Hello](Examples/Hello.c) renders a spinning, multisampled 3D cube.
+1. [HelloCompute](Examples/HelloCompute.c) animates particles with a compute shader and draws them as points.
+1. [ObjectivelyMVC](https://github.com/jdolan/ObjectivelyMVC) is a framework for modern game interfaces built on SDL3, Objectively and ObjectivelyGPU.
+1. [Quetoo](https://github.com/jdolan/quetoo) is a free first-person shooter that uses Objectively, ObjectivelyGPU and ObjectivelyMVC extensively.
 
+![Hello — a spinning, multisampled 3D cube](Hello.gif) 
 ![HelloCompute — particles animated by a compute shader](HelloCompute.gif)
+![HelloMVC — ObjectivelyMVC](ObjectivelyMVC-Hello.gif)
diff --git a/Documentation/install.md b/Documentation/install.md
@@ -0,0 +1,27 @@
+Installing ObjectivelyGPU {#install}
+=========================
+
+Dependencies, building, and linking against ObjectivelyGPU.
+
+[TOC]
+
+## Dependencies
+
+* [Objectively](https://github.com/jdolan/Objectively) >= 2.0.0
+* [SDL3](https://github.com/libsdl-org/SDL) >= 3.2.0
+
+## Building
+
+```sh
+autoreconf -i
+./configure
+make && sudo make install
+```
+
+## Linking
+
+Compile and link against ObjectivelyGPU with `pkg-config`:
+
+```sh
+gcc `pkg-config --cflags --libs ObjectivelyGPU` -o myprogram *.c
+```
diff --git a/Doxyfile b/Doxyfile
@@ -14,7 +14,7 @@ GENERATE_TODOLIST      = YES
 GENERATE_TESTLIST      = YES
 GENERATE_BUGLIST       = YES
 GENERATE_DEPRECATEDLIST= YES
-INPUT                  = Documentation/index.md Documentation/guide.md Sources
+INPUT                  = Documentation/index.md Documentation/guide.md Documentation/install.md Sources
 INPUT_ENCODING         = UTF-8
 IMAGE_PATH             = Documentation
 RECURSIVE              = YES
diff --git a/ObjectivelyGPU.xcodeproj/project.pbxproj b/ObjectivelyGPU.xcodeproj/project.pbxproj
@@ -161,6 +161,9 @@
 		AA000000000000000000EE01 /* SDL3.xcframework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.xcframework; name = SDL3.xcframework; path = Frameworks/SDL3.xcframework; sourceTree = "<group>"; };
 		C16D60B0E94469E649953EC5 /* ObjectivelyGPU.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = ObjectivelyGPU.h; sourceTree = "<group>"; };
 		C862954A9DD435C1FF7CD31D /* CopyPass.c */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.c; path = CopyPass.c; sourceTree = "<group>"; };
+		CE1643412FF47B7D00863996 /* guide.md */ = {isa = PBXFileReference; lastKnownFileType = net.daringfireball.markdown; path = guide.md; sourceTree = "<group>"; };
+		CE1643422FF47B7D00863996 /* Hello.gif */ = {isa = PBXFileReference; lastKnownFileType = image.gif; path = Hello.gif; sourceTree = "<group>"; };
+		CE1643432FF47B7D00863996 /* HelloCompute.gif */ = {isa = PBXFileReference; lastKnownFileType = image.gif; path = HelloCompute.gif; sourceTree = "<group>"; };
 		CEA0030000000000000000F0 /* Objectively.framework */ = {isa = PBXFileReference; explicitFileType = wrapper.framework; path = Objectively.framework; sourceTree = BUILT_PRODUCTS_DIR; };
 		CEBA3F5E2FF30F1E00758CA6 /* Texture.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = Texture.h; sourceTree = "<group>"; };
 		CEBA3F5F2FF30F1E00758CA6 /* Texture.c */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.c; path = Texture.c; sourceTree = "<group>"; };
@@ -343,6 +346,9 @@
 		DOC00030000000000000001 /* Documentation */ = {
 			isa = PBXGroup;
 			children = (
+				CE1643422FF47B7D00863996 /* Hello.gif */,
+				CE1643432FF47B7D00863996 /* HelloCompute.gif */,
+				CE1643412FF47B7D00863996 /* guide.md */,
 				DOC00010000000000000001 /* index.md */,
 			);
 			path = Documentation;
diff --git a/README.md b/README.md
@@ -8,23 +8,33 @@ Object oriented graphics framework for SDL3 and C.
 Zlib [license](./COPYING).
 
 ## About
-ObjectivelyGPU is a cross-platform, object oriented graphics framework for the C programming language.
-Built on [Objectively](https://github.com/jdolan/Objectively) and [SDL3](https://libsdl.org)'s GPU API, it
+ObjectivelyGPU is a cross-platform object oriented graphics framework for the C programming language.
+Built on [Objectively](https://github.com/jdolan/Objectively) and [SDL_gpu](https://libsdl.org)'s GPU API, it
 provides a clean, idiomatic C API for modern GPU programming — targeting Metal, Vulkan, and Direct3D 12
 through a single interface.
 
 ## Features
- * **macOS, iOS, Windows, Linux & Android** cross-platform support via SDL3 (Metal, Direct3D 12, Vulkan)
- * **RenderDevice** owns the swapchain — drive frames with a simple `beginFrame` / `endFrame` loop
- * **Resource objects** with automatic lifecycle: Buffer, Texture, Sampler, Shader, GraphicsPipeline, ComputePipeline
- * **Typed passes**: RenderPass, ComputePass, CopyPass with command-lifecycle validation
- * **Framebuffer** with multiple render targets, depth, and MSAA with automatic resolve
- * **Shaders** in every format SDL3 supports — SPIR-V (Vulkan), MSL (Metal), DXIL (D3D12) — loaded by name with automatic per-backend selection; author them in any language and cross-compile with [SDL_shadercross](https://github.com/libsdl-org/SDL_shadercross), or bring your own blobs
- * **Mathlib**: vector, matrix, and quaternion math for 3D graphics
-
-The verbose, error-prone handle juggling of a raw GPU API collapses into reference-counted objects and a
-handful of methods. A whole frame — acquire the swapchain, clear, draw a multisampled scene, resolve, and
-present — is just this:
+ * **Cross-platform** support for Android, iOS, macOS, Linux and Windows
+ * **RenderDevice** owns the swapchain — drive frames with a simple `beginFrame` / `endFrame` loop and an unambiguous order of operations
+ * **Resource objects** with automatic lifecycle — Buffer, Texture, Sampler, Shader, GraphicsPipeline and ComputePipeline initialize and tear themselves down
+ * **Typed passes**: RenderPass, ComputePass and CopyPass with command-lifecycle validation that catches mistakes upfront
+ * **Framebuffer** abstracts multiple render targets, depth, and MSAA with automatic resolve — convenience without forfeiting the low-level API
+ * **Shaders** loaded by name, with the formats supported by your platform
+ * **Mathlib** — vector, matrix, and quaternion math for 3D graphics
+
+## tl;dr
+The verbose, error-prone handling of a raw GPU API collapses into reference-counted objects and a
+handful of intuitive methods. 
+
+Uploading an image to the GPU is a single call — the staging buffer and copy pass are handled for you:
+
+```c
+SDL_Surface *surface = IMG_Load("crate.png");
+Texture *texture = $(renderDevice, createTextureFromSurface, surface, SDL_GPU_TEXTUREUSAGE_SAMPLER);
+SDL_DestroySurface(surface);
+```
+
+And a whole frame — acquire the swapchain, clear, draw a multisampled scene, resolve, and present:
 
 ```c
 CommandBuffer *commands = $(renderDevice, beginFrame);
@@ -44,34 +54,23 @@ if (commands) {
 }
 ```
 
-`endFrame` resolves the multisampled `Framebuffer` and presents to the swapchain for you — no manual
-resolve targets, store-op bookkeeping, or present plumbing.
+The `endFrame` method resolves the multisampled `Framebuffer` and presents to the swapchain for you. No manual
+resolve targets, no store-op bookkeeping, no presentation plumbing.
+
+## Getting Started
+
+Check out the **[Installation](https://jdolan.github.io/ObjectivelyGPU/install.html)** page for dependencies, building, and linking instructions.
 
 ## User Guide
 
-Consult the **[User Guide](https://jdolan.github.io/ObjectivelyGPU/guide.html)** to draw your first frame — the
+Peep the **[User Guide](https://jdolan.github.io/ObjectivelyGPU/guide.html)** to draw your first frame — the
 render device, resource objects, framebuffers and MSAA, the typed passes, and shaders.
 
 ## API Documentation
 
-Browse the [API Documentation](https://jdolan.github.io/ObjectivelyGPU/) to explore the library.
-
-## Getting Started
-
-### Dependencies
-
-* [Objectively](https://github.com/jdolan/Objectively) >= 2.0.0
-* [SDL3](https://github.com/libsdl-org/SDL) >= 3.2.0
-
-### Building
-
-```sh
-autoreconf -i
-./configure
-make && sudo make install
-```
+Browse the [API Documentation](https://jdolan.github.io/ObjectivelyGPU/) to explore the library further.
 
-## Examples & projects using ObjectivelyGPU
+## Project Showcase
 
 1. [Hello](Examples/Hello.c) renders a spinning, multisampled 3D cube.
 1. [HelloCompute](Examples/HelloCompute.c) animates particles with a compute shader and draws them as points.
@@ -81,4 +80,5 @@ make && sudo make install
 <p align="center">
   <img src="Documentation/Hello.gif" width="48%" alt="Hello — a spinning, multisampled 3D cube">
   <img src="Documentation/HelloCompute.gif" width="48%" alt="HelloCompute — particles animated by a compute shader">
+  <img src="Documentation/ObjectivelyMVC-Hello.gif" width="48%" alt="Hello ObjectivelyMVC - a simple in-game menu">
 </p>
