libcna.com/about.html at main · libcna/libcna.com · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>About CNA - C++ Reimplementation of the XNA 4.0 API</title>
  <meta name="description" content="Learn what CNA 0.1.0-alpha.1 is: a native C++23 XNA 4.0 reimplementation with independent platform, audio and graphics selection axes.">
  <meta property="og:type"        content="website">
  <meta property="og:site_name"   content="CNA">
  <meta property="og:url"         content="https://libcna.com/about.html">
  <meta property="og:title"       content="About CNA - C++ Reimplementation of the XNA 4.0 API">
  <meta property="og:description" content="Learn what CNA 0.1.0-alpha.1 is: a native C++23 XNA 4.0 reimplementation with independent platform, audio and graphics selection axes.">
  <link rel="stylesheet" href="css/style.css">
  <link rel="icon" href="favicon.svg" type="image/svg+xml">
  <link rel="canonical" href="https://libcna.com/about.html">
  <link rel="stylesheet" href="css/prism-tomorrow.min.css">
<script>(function(){try{var t=localStorage.getItem("cna-theme");if(t==="light"||t==="dark")document.documentElement.setAttribute("data-theme",t);}catch(e){}})();</script>
</head>
<body>

<a class="skip-link" href="#main-content">Skip to content</a>
<nav class="nav">
  <div class="nav-container">
    <a href="index.html" class="nav-brand">CNA</a>
    <button class="nav-toggle" aria-label="Toggle navigation" aria-expanded="false">
      <span></span><span></span><span></span>
    </button>
    <div class="nav-menu">
      <a href="index.html"         class="nav-link">Home</a>
      <a href="about.html"         class="nav-link">About</a>
      <a href="features.html"      class="nav-link">Features</a>
      <a href="architecture.html"  class="nav-link">Architecture</a>
      <a href="documentation.html" class="nav-link">Documentation</a>
      <a href="tutorials.html"     class="nav-link">Tutorials</a>
      <a href="demos.html"         class="nav-link">Demos</a>
      <a href="showcase.html"      class="nav-link">Showcase</a>
      <a href="videos.html"        class="nav-link">Videos</a>
      <a href="roadmap.html"       class="nav-link">Roadmap</a>
      <a href="contact.html"       class="nav-link">Contact</a>
      <a href="search.html" class="nav-link">Search</a>
      <a href="https://github.com/openeggbert/cna" class="nav-link nav-link--github" target="_blank" rel="noopener">GitHub</a>
      <a href="https://discord.gg/vrnc4n6DaE" class="nav-link nav-link--discord" target="_blank" rel="noopener">Discord</a>
    </div>
    <button class="theme-toggle" type="button" aria-label="Switch to light theme" title="Switch to light theme">
      <svg class="theme-icon-light" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M12 17a5 5 0 1 1 0-10 5 5 0 0 1 0 10zm0-2a3 3 0 1 0 0-6 3 3 0 0 0 0 6zM11 1h2v3h-2V1zm0 19h2v3h-2v-3zM3.5 4.9l1.4-1.4 2.1 2.1-1.4 1.4L3.5 4.9zm13.5 13.5l1.4-1.4 2.1 2.1-1.4 1.4-2.1-2.1zM19.1 3.5l1.4 1.4-2.1 2.1-1.4-1.4 2.1-2.1zM5.6 17l1.4 1.4-2.1 2.1-1.4-1.4L5.6 17zM23 11v2h-3v-2h3zM4 11v2H1v-2h3z"/></svg>
      <svg class="theme-icon-dark" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M12.3 22a10 10 0 0 1-1.6-19.9c.6-.1 1 .5.8 1a7.9 7.9 0 0 0 9.7 10.6c.5-.2 1 .3.9.8A10 10 0 0 1 12.3 22z"/></svg>
    </button>
  </div>
</nav>

<main id="main-content">

  <div class="page-header">
    <div class="container">
      <span class="section-label">About</span>
      <h1>What is CNA?</h1>
      <p>A native C++23 framework that mirrors the XNA 4.0 programming model without a managed runtime. SDL3 is the default host and audio implementation, not an inseparable architectural requirement.</p>
    </div>
  </div>

  <section class="section">
    <div class="container" style="max-width:820px;">

      <div class="callout callout--warn">
        <span class="callout-icon">&#9888;</span>
        <p>This site documents <strong>CNA 0.1.0-alpha.1</strong>, the project's first tagged pre-release. CNA mirrors the XNA programming model in C++23 and includes real graphics, input, audio, networking, content, media and local GamerServices implementations. Alpha.1 adds an opt-in multi-renderer registry, independent platform and audio abstractions, renderer-qualified compiled Effect Framework bytecode and a generated product-version API. It also contains an experimental native C source surface, but the final C library target is compile-blocked at this tag. The C++ release is usable for evaluation and porting work, but APIs may change before 1.0.</p>
      </div>

      <div class="callout callout--note">
        <span class="callout-icon">&#128221;</span>
        <p><strong>Where the project actually stands.</strong> Alpha.1 is a large, fast-moving prerelease with 50 renderer identities of very different depth. Its 21 workflow files cover important Linux, Apple/Metal, Emscripten, platform, multi-renderer and declared C API slices, but the final C API target is compile-blocked and the matrix does not cover every identity, driver, physical device or GPU pixel/oracle path. The source has 568 C++ test files and 8,263 statically discoverable test definitions; what compiles, registers and passes is configuration-specific. Storage is now tested, but remains a thin area with one source and five definitions.</p>
      </div>

      <h2>Background - the XNA programming model</h2>
      <p>Microsoft XNA Game Studio was a managed game development framework targeting Windows, Xbox 360, and Windows Phone. Released around 2006–2013, it offered developers a clean, well-structured API for 2D and 3D game development. The framework's game loop (<code>Initialize</code>, <code>LoadContent</code>, <code>Update</code>, <code>Draw</code>), its sprite batching system, content pipeline, and the <code>Microsoft.Xna.Framework</code> namespace hierarchy were widely praised for their clarity.</p>
      <p>XNA was discontinued by Microsoft in 2014. The open-source community responded with notable projects:</p>
      <ul>
        <li><strong>FNA</strong> - a fully managed C# reimplementation that is binary-compatible with XNA 4.0, built on SDL2.</li>
        <li><strong>MonoGame</strong> - a cross-platform C# successor to XNA, used commercially to this day.</li>
      </ul>
      <p>Both FNA and MonoGame are excellent projects. However, both remain in the managed C# ecosystem. There was no mature native C++ reimplementation of the XNA 4.0 API.</p>

      <h2>Why CNA?</h2>
      <p>CNA was created to fill a specific niche: <strong>native C++ implementation of the XNA 4.0 API</strong>. The reasons this is useful:</p>
      <ul>
        <li><strong>No managed runtime:</strong> C++ avoids garbage collection pauses, managed heap overhead, and JIT warmup costs. Useful for performance-critical or embedded scenarios.</li>
        <li><strong>Toolchain flexibility:</strong> C++ integrates directly with any C or C++ codebase, LLVM toolchains, and embedded/console targets that may not support .NET.</li>
        <li><strong>API preservation:</strong> The XNA programming model is genuinely good design. Preserving it in C++ keeps the conceptual clarity that game developers appreciated while moving to a native runtime.</li>
        <li><strong>Portability:</strong> host integration, audio, graphics rendering and target OS are separate axes. Alpha.1 contains Linux, Windows, macOS, Emscripten and Android paths, plus narrow experimental iOS SDL_RENDERER final-link and simulator-smoke evidence.</li>
      </ul>

      <h2>What problem does CNA solve?</h2>
      <p>If you are building a game or engine in C++ and you want:</p>
      <ul>
        <li>A familiar, well-structured game loop modelled after XNA</li>
        <li>A <code>SpriteBatch</code> API for 2D rendering and <code>BasicEffect</code>-powered 3D rendering</li>
        <li>A <code>GraphicsDevice</code> abstraction that hides renderer details — either one of 50 identities in the default compact build, or a compatible compiled set resolved at runtime, from the OpenGL ES family through Vulkan, Direct3D 1&ndash;12, Metal, SDL_GPU, SDL_Renderer, bgfx, FNA3D and WebGPU down to the GPU-free Software, PortableGL and Headless renderers for CI</li>
        <li>Complete input handling — <code>Keyboard</code>, <code>Mouse</code>, <code>GamePad</code> (a real SDL3 bridge with rumble, trigger rumble, LED and hot-plug), and a <code>TouchPanel</code> that genuinely detects all 10 XNA gesture types</li>
        <li>Audio via <code>SoundEffect</code>, <code>SoundEffectInstance</code>, and <code>MediaPlayer</code> — plus a real XACT implementation that parses the XGS/XWB/XSB binary formats and plays them back, rather than a facade</li>
        <li>Real <code>SystemLink</code> multiplayer via <code>NetworkSession</code>, backed by genuine ENet over UDP with real LAN discovery. (<code>PlayerMatch</code> and <code>Ranked</code> correctly no-op, as they require Xbox Live.)</li>
        <li>A real <code>.xnb</code> content pipeline, with loose-file loading as a fallback</li>
        <li>The ability to swap renderers without changing game code</li>
      </ul>
      <p>…then CNA provides a substantial alpha foundation in native C++23 &mdash; with renderer-qualified effect and format behavior, platform-specific media boundaries, and pre-1.0 API stability caveats.</p>

      <h2>What CNA is not</h2>
      <ul>
        <li>CNA is <strong>not</strong> a C# framework or a .NET library.</li>
        <li>CNA is <strong>not</strong> affiliated with or endorsed by Microsoft Corporation.</li>
        <li>CNA does <strong>not</strong> use any Microsoft, Xbox, or XNA branding assets. XNA is referenced only as the compatibility target and API inspiration.</li>
        <li>CNA is <strong>not</strong> a game - it is a framework and runtime abstraction layer.</li>
        <li>CNA's platform claims are scoped: macOS/Metal has automatic CI, while iOS is experimental and limited to SDL_RENDERER final-link plus a one-frame simulator smoke path; tvOS is unsupported.</li>
        <li>CNA is <strong>not yet recommended</strong> for shipping commercial games, though it is suitable for research, demos, and open-source development.</li>
      </ul>

      <h2 id="fna">Relationship to FNA and MonoGame</h2>

      <div class="callout callout--info">
        <span class="callout-icon">&#128221;</span>
        <p><strong>Attribution - based in part on FNA (C#):</strong> CNA is partially based on the <a href="https://github.com/FNA-XNA/FNA" target="_blank" rel="noopener">FNA</a> project, a managed C# reimplementation of the XNA 4.0.4 API. Portions of CNA's design, API structure, and implementation logic are derived from or inspired by FNA's C# source code. FNA is authored by Ethan Lee and contributors, and is likewise licensed under the <strong>Microsoft Public License (Ms-PL)</strong>. CNA's use of FNA as a basis is permitted by and compliant with the Ms-PL. The release attribution is in the tag's <a href="https://github.com/openeggbert/cna/blob/v0.1.0-alpha.1/NOTICE.md" target="_blank" rel="noopener">NOTICE.md</a> and <a href="https://github.com/openeggbert/cna/blob/v0.1.0-alpha.1/THIRD_PARTY_NOTICES.md" target="_blank" rel="noopener">THIRD_PARTY_NOTICES.md</a>.</p>
      </div>

      <p>In practical terms: where FNA provides a C# class implementing a particular XNA behaviour, CNA translates that behaviour into C++23 idioms - replacing managed types with RAII, delegates with virtual methods, and properties with getter/setter methods. The game-facing API shape follows FNA's C# surface as the authoritative XNA 4.0 reference, while the internal implementation is native C++ throughout.</p>
      <p>Both <a href="https://fna-xna.github.io/docs/" target="_blank" rel="noopener">FNA</a> and <a href="https://docs.monogame.net/articles/index.html" target="_blank" rel="noopener">MonoGame</a> remain excellent choices for managed C# game development. CNA serves the C++ ecosystem specifically.</p>

      <h2>C++ API differences — the <code>CNAEXT</code> marker</h2>
      <p>Declarations marked with <code>CNAEXT</code> in CNA's source code are <strong>not</strong> part of the XNA 4.0 public API. A strict CMake mode turns use of marked declarations into diagnostics that can be promoted to errors, giving ports a mechanical XNA-purity check. When consuming CNA directly you can use these declarations freely; the marker means they have no XNA counterpart.</p>
      <p>Some of it is plain C++ glue (iterator support, RTTI helpers, RAII wrappers), but a lot of it is substantial functionality XNA never had:</p>
      <ul>
        <li><strong>Graphics:</strong> <code>ShaderEffect</code> for renderer-native custom shaders, <code>PbrEffect</code>/<code>SkinnedPbrEffect</code> for physically based rendering, <code>SkinnedModelEXT</code> with animation types, <code>MorphTargetEXT</code> blend shapes, tangent/skinned vertex types, and extended surface formats. XNA Effect Framework bytecode is a separate compatibility path on qualified renderer builds.</li>
        <li><strong>Input:</strong> around 17 <code>GamePad</code> extension methods (GUID, light bar, trigger vibration, gyro/accelerometer, power info, touchpad fingers, Steam handle), paddle and touchpad buttons, scancode-based <code>Keyboard</code> methods, <code>MouseCursor</code> and <code>TextInputEXT</code>.</li>
        <li><strong>The whole <code>CNA::</code> namespace</strong> — roughly 58 public headers that are not XNA at all: <code>Camera</code>, <code>FileDialog</code>, <code>MessageBox</code>, <code>SystemTray</code>, <code>Clipboard</code>, <code>UrlLauncher</code>, <code>Locale</code>, <code>PowerInfo</code>, <code>DisplayInfo</code>, <code>SystemInfo</code>, full <code>Joystick</code>/<code>Haptics</code> APIs, <code>Logger</code>, and render-pipeline settings including <code>PbrMaterial</code>, <code>TonemappingMode</code> and <code>ShadowQuality</code>.</li>
      </ul>
      <p>The CMake options gating the extended layers (<code>CNA_CNAEXT</code> and <code>CNA_DEVICES</code>) both default to <strong>OFF</strong>. Their compiled and registered tests therefore depend on the configured build; the tag includes focused Devices CI, while CNAEXT coverage is not universal across the workflow matrix.</p>

      <h2>Technology stack</h2>
      <ul>
        <li><strong>Language:</strong> C++23 — requires GCC 12+, Clang 15+, or MSVC 2022 v17.8+</li>
        <li><strong>Platform implementations:</strong> SDL3 by default, real SDL 2.30, Headless, or POSIX Terminal through <code>CNA_PLATFORM</code></li>
        <li><strong>Image loading:</strong> SDL3_image (vendored submodule) — PNG, JPG, BMP, and more</li>
        <li><strong>Audio-device selection:</strong> SDL3 by default, SDL2 or Null through the independent <code>CNA_AUDIO_PLATFORM</code> axis; only SDL3 enables alpha.1's high-level XNA playback/decoding engine</li>
        <li><strong>OpenGL renderer:</strong> <code>easy-gl</code> plus <code>meta-gl</code> — sibling repositories used by the five EasyGL identities: <code>OPENGLES2</code>, <code>OPENGLES3</code>, <code>OPENGL33</code>, <code>WEBGL1</code> and <code>WEBGL2</code></li>
        <li><strong>DirectDraw renderer:</strong> <code>free-direct</code> — a sibling repo reimplementing a DirectX 3 / DirectDraw 2D subset over SDL3; required only for the <code>FREEDIRECT</code> renderer</li>
        <li><strong>Runtime support:</strong> <code>sharp-runtime</code> — a required C++23 sibling implementing the practical <code>System::*</code> surface CNA uses, including primitives, collections, IO, text/JSON/regex, networking, threading, XML, globalization and numerics. This is where <code>bytecs</code>, <code>intcs</code> and <code>Single</code> come from</li>
        <li><strong>Video playback:</strong> FFmpeg — real libavcodec/libavformat decoding for <code>VideoPlayer</code>, with PTS-driven pacing. The video translation units are present for Linux and macOS and excluded on Emscripten, Android and Windows in alpha.1</li>
        <li><strong>Networking:</strong> in-tree <code>enet</code> for reliable UDP; also in-tree are <code>cgltf</code>, <code>stb</code> and a pinned <code>wgpu-native</code></li>
        <li><strong>Build system:</strong> CMake 3.20+ with a compact single-renderer default through <code>CNA_GRAPHICS_RENDERER</code>, or an opt-in compatible set through <code>CNA_GRAPHICS_RENDERERS</code> and pre-device runtime selection</li>
        <li><strong>Test source inventory:</strong> 568 C++ test files and 8,263 static GoogleTest-family definitions at the tag; the instantiated/run inventory varies by configuration</li>
        <li><strong>Model tooling:</strong> a runtime glTF 2.0 loader plus the offline <code>gltf_to_cnj</code> converter for deployment-oriented <code>.cnj</code> Model/AnimationClip assets</li>
      </ul>

      <h2>Real-world validation</h2>
      <p>Unit tests only prove that the code does what its author expected. CNA is checked against several things it does not control:</p>
      <ul>
        <li><strong>A real XNA reference renderer.</strong> The oracle corpus under <code>tools/xna-oracle/</code> holds <strong>39 scenes</strong> rendered by a genuine C#/XNA reference renderer, diffed pixel-exactly (<code>--tolerance 0</code>) against CNA's DIRECTX9 output. DIRECTX9 is the renderer that uniquely targets pixel-exact XNA 4.0 authenticity.</li>
        <li><strong>A running FNA build.</strong> A C# harness links the real FNA build, dumps reference values to JSON, and a script diffs them against CNA's own output. Ground truth comes from executing the reference implementation, not from reading its source.</li>
        <li><strong>The official XNA sample collection.</strong> <a href="https://github.com/openeggbert/cna-samples" target="_blank" rel="noopener">cna-samples</a> ports Microsoft's XNA Game Studio 4.0 samples to C++ on CNA: 86 samples, of which 63 currently build.</li>
        <li><strong>GPU and integration verification.</strong> Renderer-specific programs and CTest entries are registered for the selected build; use <code>ctest -N</code> in that build instead of quoting a tree-wide universal count.</li>
      </ul>
      <p>Beyond that, <a href="https://github.com/openeggbert/cna-craft" target="_blank" rel="noopener">CNA Craft</a> and the <a href="demos.html">browser demos</a> exercise real game-code paths. They remain independent evidence: repository CI does not continuously launch every hosted demo. Media has 29 test sources with 286 static definitions at the tag; Storage has one source with five, so the latter is still deliberately described as thin. See <a href="docs/verification.html">Verification &amp; Known Issues</a>.</p>

      <h2>Licence <span style="display:inline-block;background:#217346;color:#fff;padding:2px 8px;border-radius:3px;font-size:0.8em;font-weight:600;vertical-align:middle;">Ms-PL License</span></h2>
      <p>CNA is licensed under the <strong>Microsoft Public License (Ms-PL)</strong>. See the tag's <a href="https://github.com/openeggbert/cna/blob/v0.1.0-alpha.1/LICENSE" target="_blank" rel="noopener">LICENSE file</a> for full terms. Portions of CNA are derived from or based on FNA, which is also licensed under the Ms-PL.</p>

    </div>
  </section>

</main>

<footer>
  <div class="footer-inner">
    <div class="footer-top">
      <div class="footer-brand">
        <div class="footer-brand-name">CNA</div>
        <p>Documentation snapshot for CNA 0.1.0-alpha.1, the first tagged pre-release. CNA exposes 50 renderer identities across 46 implementation families; APIs may change before 1.0.</p>
      </div>
      <div class="footer-col">
        <h4>Project</h4>
        <ul>
          <li><a href="about.html">About</a></li>
          <li><a href="features.html">Features</a></li>
          <li><a href="architecture.html">Architecture</a></li>
          <li><a href="roadmap.html">Roadmap</a></li>
        </ul>
      </div>
      <div class="footer-col">
        <h4>Docs</h4>
        <ul>
          <li><a href="docs/getting-started.html">Getting Started</a></li>
          <li><a href="docs/building.html">Building</a></li>
          <li><a href="docs/platforms.html">Platforms</a></li>
          <li><a href="docs/rendering-backends.html">Renderers</a></li>
          <li><a href="docs/faq.html">FAQ</a></li>
        </ul>
      </div>
      <div class="footer-col">
        <h4>Community</h4>
        <ul>
          <li><a href="https://github.com/openeggbert/cna" target="_blank" rel="noopener">GitHub</a></li>
          <li><a href="https://discord.gg/vrnc4n6DaE" target="_blank" rel="noopener">Discord</a></li>
          <li><a href="demos.html">Demos</a></li>
          <li><a href="videos.html">Videos</a></li>
          <li><a href="contact.html">Contact</a></li>
        </ul>
      </div>
    </div>
    <div class="footer-bottom">
      <p>CNA is not affiliated with or endorsed by Microsoft Corporation. XNA is a trademark of Microsoft. Licensed under the Microsoft Public License (Ms-PL).</p>
      <div class="footer-links">
        <a href="https://github.com/openeggbert/cna/blob/master/LICENSE" target="_blank" rel="noopener">License</a>
        <a href="contact.html">Contact</a>
      </div>
    </div>
  </div>
</footer>

<script src="js/main.js"></script>
<script src="js/prism/prism.min.js" defer></script>
<script src="js/prism/prism-cpp.min.js" defer></script>
<script src="js/prism/prism-glsl.min.js" defer></script>
<script src="js/prism/prism-json.min.js" defer></script>
<script src="js/prism/prism-bash.min.js" defer></script>
<script src="js/prism/prism-cmake.min.js" defer></script>
</body>
</html>