Combobulate 0.8.2

Combobulate

A XAML controls library for UWP and WinUI 3 / Windows App SDK that renders 3D .obj files made of triangles and quads using the Windows Composition visual layer — no D3D, no SwapChainPanel, no shaders.

combobulate (humorous) — to compose (oneself); to compose, organize, design, or arrange; to reverse the effect of discombobulation. (Wiktionary)

Each face becomes a SpriteVisual placed in 3D by a perspective TransformMatrix. Quad faces use the full sprite rectangle; triangle faces add a triangular CompositionGeometricClip (one shared unit-triangle path geometry, per-face scale) plus a 3-point affine brush transform that maps brush UVs exactly. Back-face culling and a polygon sort keep the draw order right without a depth buffer, and a fully analytical baked aspect graph renderer can sustain GPU-driven animation with zero CPU work per frame.

Packages

• Combobulate — the XAML control library for UWP and WinUI 3 / Windows App SDK.
• Combobulate.SystemComp — a XAML-free flavor of the renderer bound to the system Windows.UI.Composition surface with no Windows App SDK dependency. Use it to host a live 3D model on a raw DesktopWindowTarget (e.g. a per-pixel alpha WS_EX_NOREDIRECTION_BITMAP window) from a plain .NET 5+ desktop process. It exposes the same Combobulate API under a distinct assembly name (Combobulate.SystemComp), so an app can reference it alongside the lifted WinAppSdk build. It depends on arcadiog.CompositionExpressions.SystemComp (the system-composition flavor of the expression DSL) and unlocks the BakedAspectGraph rendering mode in the XAML-free build.

Targets

• UWP — uap10.0.19041
• WinUI 3 / Windows App SDK — net10.0-windows10.0.19041.0 (lifted composition)
• System composition (Combobulate.SystemComp) — net10.0-windows10.0.19041.0 bound to the system Windows.UI.Composition, no Windows App SDK

Repo Layout

src/
  Combobulate/                 UWP class library (canonical source)
  Combobulate.WinAppSdk/       WinUI 3 head — links sources from Combobulate
  Combobulate.SystemComp/      XAML-free head (system composition, COMBOBULATE_NO_XAML)
  Combobulate.Sample.Uwp/      UWP sample app
  Combobulate.Sample.WinUI3/   WinUI 3 sample app
samples/
  book.obj                     Example quad-based model

Getting Started

1. Add the Combobulate NuGet package to your UWP or WinUI 3 app.

2. Place a Combobulate control in your XAML:

   <Page xmlns:c="using:Combobulate">
       <c:Combobulate x:Name="Viewer"
                      Source="ms-appx:///Assets/book.obj"
                      ModelScale="200"
                      RotationX="-30"
                      RotationY="40"
                      RotationZ="0" />
   </Page>
   

   Source accepts an ms-appx:/// URI, an absolute file path, or an ObjCache key — geometry, materials (via sibling mtllib), and texture surfaces are all loaded and cached process-wide.

3. Or parse an .obj yourself and assign the resulting model directly:

   using Combobulate.Parsing;
   
   var text = await FileIO.ReadTextAsync(
       await StorageFile.GetFileFromPathAsync(@"C:\path\to\book.obj"));
   var result = ObjParser.Parse(text);
   Viewer.Model = result.Model;        // partial model on parse error
   foreach (var err in result.Errors)  // optional: inspect parse diagnostics
       System.Diagnostics.Debug.WriteLine(err);
   

That's it — the control rebuilds its visual tree whenever any of its inputs change.

Highlights

• Materials. Auto-loaded from mtllib or supplied via ObjMaterialPack, with live texture updates from SoftwareBitmap or streams.
• Three sort algorithms. Bsp (default, exact, O(n)), Newell (split-on-cycle, deformable-friendly), and Topological (legacy, fast).
• Composition-driven rotation. SetExternalRotation(ExpressionAnimation) binds rotation directly to the compositor; pair with EnableAutoRefresh to keep cull and sort in lock-step with the compositor clock.
• Baked aspect graph. Pre-computes every painter-order breakpoint along an animation axis and emits one ContainerVisual per cell, each gated by an opacity expression on a live scalar. Smooth GPU spin without per-frame CPU cost. See docs/rendering-pipeline.md.

For everything beyond "drop a control, point Source at a file" see the usage guide and the rendering pipeline doc.

Supported .obj subset

• v x y z [w] — vertex positions
• vt u v [w] — texture coordinates
• vn x y z — vertex normals (parsed; not used for shading today)
• f a b c — triangle faces; a/ta/na style references accepted
• f a b c d — quad faces; a/ta/na style references accepted
• usemtl <name>, mtllib <file> — material binding and library load
• o, g, s — preserved; l, p, vp, curves/surfaces are ignored

Both triangles and quads are first-class faces. Triangles render via a SpriteVisual + shared triangle CompositionGeometricClip + exact 3-point affine brush transform; quads render directly as parallelogram sprites as before. A geometry-build preprocess fuses coplanar adjacent triangle pairs back into single quads where it is safe to do so (same material, matching UVs at the shared edge, convex result), so triangulated-quad meshes hit the 1-sprite-per-quad fast path with no overdraw.

Wind each face so that (V1 - V0) × (V_last - V0) points outward — that's the direction the renderer treats as front-facing for back-face culling (V_last is V2 for triangles, V3 for quads). Faces with fewer than 3 or more than 4 vertices are reported as parse errors and skipped.

See samples/book.obj for a worked example.

Control properties at a glance

Full descriptions and examples are in the usage guide.

Releasing

Push a tag of the form vX.Y.Z to trigger the GitHub Actions workflow that builds both targets, packs Combobulate.nuspec, publishes to NuGet.org, and creates a GitHub Release.