GFFX

GFFX is a portable, general-purpose graphics, geometry, and mesh toolkit for Python 3.10+, differentiable wherever differentiation exists and capable regardless of whether it does. Its design centers on stable tensor-level semantics across autodiff frameworks, a dependency-light C11 CPU core, isolated accelerator providers, compilation and export, and allocation-controlled integration into streaming and edge applications.

The project is pre-release. M1 is complete for the adopted development-readiness scope: finite generic graphics supply, recorded CPU/CUDA profiles, and the B1 public CPU fitting integration. The experimental 0.2.0a2 Windows package with an optional CUDA provider has a separately defined artifact/runtime scope; M1 does not confer universal release support. See M1 closeout and development wheels for the artifact boundaries.

The core geometry inventory below is one part of the current camera, scene, animation, shading and image supply. Experimental filtered-renderer qualification remains a separate, unqualified workstream; its reference campaign is paused.

What works today

The development checkout also includes the minimal scene API: typed objects, transform hierarchies, frame-major mesh packing, attribute/material bindings and differentiable transforms. This is an eager PyTorch composition over the existing operations, not a scene editor, file importer or new native renderer.

Thirteen native geometry operations, each with a written acceptance contract and fixtures:

Gradients for twelve of the thirteen. mesh.build_edge_topology publishes none, because every one of its outputs is integer topology and there is nothing to differentiate. Differentiability is a per-operation property rather than a condition of membership: an operation declares its gradient support by publishing a _backward entry point or by not publishing one, so the absence is visible when you bind rather than when you first ask for a gradient.

A CUDA provider covering twelve of the thirteen forwards and all twelve backwards, loaded as an isolated optional plugin. mesh.build_edge_topology has no CUDA forward.

Bitwise CPU/CUDA agreement, not merely closeness, for every operation that can promise it. The device build passes -fmad=false and each kernel mirrors the host operation for operation rather than reassociating for speed, so results are compared with memcmp rather than a tolerance. Where a gradient scatters onto shared geometry the default path reproduces the host's accumulation order exactly; a faster atomic path exists but is reached only when the caller sets GFFX_EXECUTION_ALLOW_NONDETERMINISTIC, and it makes no bit-identity claim.

A framework-neutral C11 ABI, usable without Python or any autodiff framework. The figures in this README were produced by calling it from Python with ctypes and nothing else — see docs/showcase/.

The working camera implementation is documented in Eager pinhole cameras: gffx.camera.Camera projects points, reconstructs positions from depth, and batches cameras using the existing transforms. Its optional in_front_only=True filter keeps behind-camera rejection separate from mathematical projection validity and visibility. It adds no native primitive and makes no compilation/export or real-time performance claim.

PyTorch also exposes compositional classic and principled/custom materials, tagged light integration, and explicit tensor colour sources. These are not additional native primitives. Principled shading has separately named, finite-profile float64 budget bundles for CPU and CUDA; the table is shipped package data, not a download. Input/layout, energy and gradient tests do not imply Cycles fidelity, compiled/exported shading, or real-time performance. See the shading implementation and evidence map for what is locally tested and what remains outside this slice.

What does not work yet

• The PyTorch adapter requires PyTorch 2.10 or newer. On an older PyTorch it refuses to load and the Python operation surface is inert. The C ABI remains available.
• Use an explicit alpha version. The public 0.1.x releases are the inherited prototype with unrelated APIs. The 0.2.x prereleases package the M1 development snapshot; see the exact alpha profile for what the selected artifact verifies.
• GPU evidence is local and artifact-specific. Historical laptop/RTX 5090 and PC/RTX 3080 cohorts retain separate identities. This alpha does not claim a complete GPU/driver/framework matrix or continuous hosted hardware qualification. The hardware lane retains its independent requirements.
• No JAX adapter. Compilation, export and preallocated streaming retain their own operation-specific development profiles and limits.
• No general real-time claim. KNN and closest-point queries remain brute force; the rasterizer has conservative block rejection. Exact historical timings do not establish current-artifact throughput or sustained latency.
• Shading is still a bounded development implementation. Lobes, built-in lights and classic/principled material compositions are available in the development checkout. The exact bundled principled loss table has separate CPU/CUDA float64 profiles with a 32-entry standalone query limit. Material calls separately support 1024 point/light pairs (8 forward or 4 backward points), under a 64 MiB planning ceiling. Fixed image/reference fixtures do not qualify arbitrary scenes, sustained performance or compilation/export. See material usage and limits. Tangent frames, bump mapping and colour management remain later work.
• No ray tracing or BVH traversal, remeshing, mesh booleans, volumetric rendering, non-triangle faces, or image decoding. render.texture samples a tensor the caller already holds; it opens no file.
• Support claims are per combination and measured, not inherited. See measured evidence versus support targets before depending on a platform, Python version, or accelerator.

What it looks like

The render chain stage by stage, on a procedurally generated sphere. Every pixel comes from a GFFX operation:

And the property that makes it a differentiable renderer rather than a renderer — gradient descent on vertex positions, driven entirely by the library's own backward passes, until a triangle matches its target:

More figures, with what each one demonstrates, in docs/showcase/.

Install and inspect

The 0.2.0a2 candidate is one Windows x64 CPU wheel with an optional CUDA provider and PyTorch adapter. See the installation guide and exact GPU alpha profile. PyTorch is selected separately; base use has no mandatory Python dependencies. Once the version is available on PyPI, install it explicitly:

python -m pip install --only-binary=gffx "gffx==0.2.0a2"

GPU operations additionally need an NVIDIA driver supporting the embedded PTX, a compatible NVIDIA GPU and CUDA-enabled PyTorch. A toolkit or native compiler is needed only to build from source. The published CPU-only 0.2.0a1 remains available; GPU and broader source capabilities retain their exact evidence limits.

The stable entry point is always:

import gffx

print(gffx.__version__)
print(gffx.capabilities())       # static; never probes a GPU

# Explicit diagnostic only; may load the optional provider and GPU driver.
print(gffx.cuda.capabilities())

Do not call the full CUDA capability probe from a real-time frame or audio callback.

Documentation

• Installation and optional components
• Source and native builds
• Dependency and vendoring policy
• Measured evidence versus support targets
• Isolated CUDA provider recipes
• The CUDA hardware test lane
• Capability figures and how they are generated
• Testing-dashboard learning pages and dependency-free mathematics

Source boundaries

• include/gffx/: public framework-neutral C11 ABI.
• native/core/: dependency-light runtime and the independent CPU operations.
• native/cuda/: private optional CUDA provider; no semantics belong here exclusively.
• adapters/: CPython and autodiff-framework loading/registration glue.
• src/gffx/: stable dependency-light Python namespace.
• tests/: ABI, packaging, import, framework-loading, accelerator-isolation, and operation acceptance contracts.
• docs/showcase/: the figure generators and the figures above.

The pre-foundation source remains recoverable in Git history and on codex/archive-pre-phase1-20260821. Prototype behavior is unsupported and receives no compatibility credit toward the new operation contracts.

GFFX is licensed under the MIT License. No third-party source is vendored, and every figure here is generated from GFFX's own primitives with procedurally constructed inputs, so no external asset or dataset is redistributed.