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 0.2.0 release line defines a bounded Windows x64 support contract. Its stable admission covers the declared eager CPU geometry, camera, animation and image API on CPython 3.10-3.14 with separately selected Torch 2.10.0. The wheel also contains the existing optional CUDA provider under a finite experimental profile. See release scope and gates, installation and current release evidence. M1 development readiness is complete; broader platform, renderer and performance targets keep their own evidence boundaries. The reference campaign is paused indefinitely.

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.
• Select the current release deliberately. The public 0.1.x releases are the inherited prototype with unrelated APIs. The 0.2.x line packages the native implementation; the release policy and exact-artifact evidence define stable and experimental features.
• GPU evidence is local and artifact-specific. Historical laptop/RTX 5090 and PC/RTX 3080 cohorts retain separate identities. This release scope 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.0 candidate is one Windows x64 CPU wheel with an optional CUDA provider and PyTorch adapter. See the installation guide and release policy. 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.0"

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.