Preface
CNA is a C++23 reimplementation of the Microsoft XNA 4.0 programming model. This is the 0.1.0-alpha.1 edition, pinned to the immutable v0.1.0-alpha.1 tag at 1bb2145d99ed572dd4eb15009c34e2e5f410fcf0. The tag is CNA’s first Semantic Versioning release and remains explicitly pre-1.0: the project may change public interfaces between prereleases. It does not turn every source-visible route into a stable or runtime-proven contract.
The release separates platform integration, graphics, and audio into independent build axes. SDL3 remains the default platform and audio implementation, but SDL2, headless and terminal platform routes and a null-audio route are represented separately. A build may contain one or several renderer families; 50 public renderer identities map to 46 implementation families, and a multi-renderer build chooses one at runtime before its first graphics device is created. CNA is neither a game nor an editor-centered engine. It is a compatibility framework for native C++ programs written in the shape of Microsoft::Xna::Framework.
The surrounding repositories provide capabilities CNA should not duplicate. sharp-runtime supplies selected .NET-shaped types; easy-gl and meta-gl provide the OpenGL/OpenGL ES layer used by five public identities; free-direct and free-api implement a narrow legacy compatibility route; xna4-spec makes the XNA API surface searchable; and the sample and example repositories exercise the framework from a user’s perspective. Chapter 2 maps those relationships without treating every adjacent repository as part of CNA itself.
This book serves two roles. It is a technical monograph about CNA’s architecture and engineering trade-offs, and a reference for people building, porting, testing, or extending CNA programs. It follows public API contracts into their pinned implementations, then separates what source inspection establishes from what a build, execution, renderer trace, independent oracle, or pixel comparison establishes. Bugs, partial routes, stale project documents, and unsupported configurations remain visible because they affect engineering decisions.
The book is not the project’s live API documentation. Software changes faster than an edition can. Treat the text as a revision-bounded map: use it to locate the relevant subsystem and its constraints, then check the current repository before relying on a detail in new code. The full pin set and observed checkout state appear in Appendix D.
The release also introduces an experimental native C API. Appendix I documents its handle, result, version and coverage boundaries, including the exact-tag renderer identity mismatch that blocks the final library build. Its C ABI version is independent of the CNA product version; neither number is a substitute for the other.
The organization follows the path of a call through the system. Parts I and II introduce the ecosystem, build, framework lifecycle, math conventions, and module boundaries. Parts III and IV trace the public graphics API into renderer implementations and native APIs. Parts V and VI cover asset resolution, XNB, CNJ, glTF, models, animation, and conformance evidence. Part VII covers input, audio, media, devices, storage, networking, and related XNA services. The remaining parts cover foundation libraries, platforms, verification, and porting practice.
Appendix G is the authoritative evidence key. In short, API presence, successful compilation, execution, renderer engagement, behavioral comparison, and pixel comparison are different observations. A green result is reported at the narrowest level the retained evidence supports. This convention lets a reader distinguish a working portable path from a source-visible implementation, a historical run, or a test that skipped before reaching its intended boundary.
The production process, including its use of AI-agent assistance, is described in the front matter that follows. The authority for technical claims remains the identified source and evidence, not the tool that drafted a sentence.