-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathcontribute.html
More file actions
337 lines (299 loc) · 22.6 KB
/
Copy pathcontribute.html
File metadata and controls
337 lines (299 loc) · 22.6 KB
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
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Contribute to CNA - C++ Reimplementation of XNA 4.0</title>
<meta name="description" content="How to contribute to CNA - build instructions, repository structure, code style, CNAEXT marker, and open contribution opportunities.">
<meta property="og:type" content="website">
<meta property="og:site_name" content="CNA">
<meta property="og:url" content="https://libcna.com/contribute.html">
<meta property="og:title" content="Contribute to CNA - C++ Reimplementation of XNA 4.0">
<meta property="og:description" content="How to contribute to CNA - build instructions, repository structure, code style, CNAEXT marker, and open contribution opportunities.">
<link rel="stylesheet" href="css/style.css">
<link rel="icon" href="favicon.svg" type="image/svg+xml">
<link rel="canonical" href="https://libcna.com/contribute.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">Contributing</span>
<h1>Contribute to CNA</h1>
<p>CNA is an open-source C++23 reimplementation of the XNA 4.0 API built on SDL3. Contributions of any kind are welcome — new implementations, tests, platform fixes, and documentation improvements all help.</p>
</div>
</div>
<section class="section">
<div class="container" style="max-width:820px;">
<!-- ====================================================
Section 1 — Getting started
==================================================== -->
<h2>Getting started</h2>
<h3>Step 1 — Clone CNA and initialise submodules</h3>
<pre><code>git clone https://github.com/openeggbert/cna.git
cd cna
git submodule update --init --recursive</code></pre>
<p>This populates <code>third_party/SDL</code>, <code>third_party/SDL_image</code>, and <code>third_party/SDL_mixer</code>. SDL3 is built from source by CMake — no system SDL packages are required.</p>
<h3>Step 2 — Clone sibling repositories</h3>
<p>CNA always requires <code>sharp-runtime</code> as a sibling directory next to <code>cna/</code>. Two more siblings are needed only by specific renderers: <code>easy-gl</code> for EasyGL and <code>free-direct</code> for FreeDirect.</p>
<pre><code>parent/
├── cna/
├── sharp-runtime/ # always required
├── easy-gl/ # required by the OPENGLES3 renderer
└── free-direct/ # required by the FREEDIRECT renderer</code></pre>
<p>Clone them at the same level:</p>
<pre><code>git clone https://github.com/openeggbert/sharp-runtime.git
git clone https://github.com/openeggbert/easy-gl.git
git clone https://github.com/openeggbert/free-direct.git</code></pre>
<h3>Step 3 — Build with EasyGL</h3>
<pre><code>cmake -S . -B build -DCNA_GRAPHICS_RENDERER=OPENGLES3
cmake --build build --target CnaTests</code></pre>
<p><code>CNA</code> is an interface umbrella, not a standalone build target; build <code>CnaTests</code>, an example, or your consumer target. CNA accepts 50 renderer identities. A normal configure selects one through <code>CNA_GRAPHICS_RENDERER</code>; an opt-in <code>CNA_GRAPHICS_RENDERERS</code> list can link several compatible families for pre-device runtime selection. See the <a href="docs/building.html">Building documentation</a> for the full inventory and platform gates.</p>
<h3>Step 4 — Run the tests</h3>
<pre><code>ctest --test-dir build --output-on-failure</code></pre>
<p>The alpha.1 source tree has 568 C++ test files and 8,263 statically discoverable GoogleTest-family definitions. What reaches <code>CnaTests</code> and CTest depends on renderer set, platform, audio implementation, host and options. Run the configuration you changed and include its configure command, <code>ctest -N</code> inventory and failing output in a report.</p>
<div class="callout callout--note">
<span class="callout-icon">ⓘ</span>
<p>Single-renderer build directories remain the easiest way to isolate a matrix. Multi-renderer builds are valuable for registry, selection and fallback work, but they do not remove renderer-specific dependencies or platform gates. Alpha.1 has 21 workflow files; local coverage of the exact family and driver you changed remains valuable.</p>
</div>
<!-- ====================================================
Section 2 — Repository structure
==================================================== -->
<h2>Repository structure</h2>
<div class="table-wrap">
<table>
<thead>
<tr><th>Path</th><th>Contents</th></tr>
</thead>
<tbody>
<tr>
<td><code>modules/*/include/</code></td>
<td>Module-owned public C++ headers, including the XNA 4.0-shaped API and CNA namespaces. Non-XNA declarations in the XNA surface require <code>CNAEXT</code>.</td>
</tr>
<tr>
<td><code>modules/*/src/</code></td>
<td>Module-owned implementations; renderer families live under <code>modules/renderers/</code>.</td>
</tr>
<tr>
<td><code>modules/*/tests/</code></td>
<td>Module-owned GoogleTest sources. Alpha.1 has 568 C++ test files and 8,263 statically discoverable definitions; a build compiles only its applicable subset.</td>
</tr>
<tr>
<td><code>third_party/</code></td>
<td>Vendored submodules: SDL3, SDL3_image, SDL3_mixer. Do not modify these directly.</td>
</tr>
<tr>
<td><code>docs/</code></td>
<td>CNA-internal documentation: <code>xna-4-api-coverage.md</code>, <code>coverage.md</code>, and related notes on implementation status.</td>
</tr>
<tr>
<td><code>CHECKLIST.md</code></td>
<td>Per-file porting checklist tracking which XNA types have been ported. Also explains the <code>CNAEXT</code> marker convention.</td>
</tr>
<tr>
<td><code>GRAPHICS_TASKS.md</code></td>
<td>Graphics-specific implementation task plan listing remaining work per renderer.</td>
</tr>
</tbody>
</table>
</div>
<!-- ====================================================
Section 3 — CNAEXT marker
==================================================== -->
<h2>The CNAEXT marker</h2>
<div class="callout callout--info">
<span class="callout-icon">📝</span>
<p><strong>Rule:</strong> When porting XNA APIs, stay faithful to the public XNA 4.0 surface. Use the <code>CNAEXT</code> marker <em>only</em> for C++ glue code that has no counterpart in the managed XNA/FNA API.</p>
</div>
<p>Methods and types annotated with a <code>// CNAEXT</code> comment in the source are <strong>not</strong> part of the XNA 4.0 public API. They exist purely to support C++ idioms and integration patterns. Examples:</p>
<ul>
<li>Iterator support — <code>begin()</code> / <code>end()</code> on collections to enable range-for loops</li>
<li><code>GetTypeName()</code> — runtime type name helper for debugging</li>
<li>RAII helpers and move constructors that have no equivalent in managed C#</li>
</ul>
<p>The authoritative reference for the XNA 4.0 public API surface is <a href="https://github.com/FNA-XNA/FNA" target="_blank" rel="noopener">FNA (C#)</a>. When in doubt whether a method belongs to the XNA API, check the corresponding FNA class. If it is present there without modification, it belongs in CNA without the <code>CNAEXT</code> marker. If it is a C++-only addition, mark it <code>CNAEXT</code>.</p>
<!-- ====================================================
Section 4 — What needs work
==================================================== -->
<h2>What needs work</h2>
<p>Below are the most impactful contribution opportunities, grouped by area. Any of these would be a meaningful addition to the project.</p>
<div class="cards cards--2" style="margin-top:1.5rem;">
<div class="card">
<span class="status-badge status-wip" style="margin-bottom:0.75rem;">Open</span>
<h3>Broaden compiled-effect portability</h3>
<p>Alpha.1 implements XNA/FNA D3D9 Effect Framework bytecode on FNA3D and opted-in EasyGL, SDL_GPU and Vulkan builds. The open work is to extend that qualified path, add real sample runtime evidence, or build an explicit conversion strategy for different inputs such as HLSL <code>.fx</code> source, DXBC and MGFX. Do not treat those formats as interchangeable.</p>
</div>
<div class="card">
<span class="status-badge status-wip" style="margin-bottom:0.75rem;">Open</span>
<h3>bgfx 32-bit index buffers</h3>
<p>A confirmed correctness bug. The bgfx renderer never overrides <code>CreateIndexBuffer32</code>, so 32-bit indices are uploaded into a 16-bit buffer and <code>DrawUserIndexedPrimitives</code> corrupts geometry. Every other 3D renderer implements this. Well-scoped and clearly diagnosed — a good first substantial contribution.</p>
</div>
<div class="card">
<span class="status-badge status-wip" style="margin-bottom:0.75rem;">Open</span>
<h3>bgfx D3D and Metal shader variants</h3>
<p>bgfx ships 108 shader blobs, but only for GL, GLES, Vulkan and WebGPU — there are no D3D or Metal variants. The practical consequence is that <strong>3D silently draws nothing on bgfx's default Windows and macOS renderers</strong>. Building out the missing shader variants through bgfx's shader toolchain would make the renderer genuinely cross-platform.</p>
</div>
<div class="card">
<span class="status-badge status-wip" style="margin-bottom:0.75rem;">Open</span>
<h3>Truthful <code>SupportsCapability()</code></h3>
<p>The base explicitly returns false for multi-stream input and compiled effects and delegates stencil, but returns <code>true</code> for the remaining capabilities. <code>DIRECTX9</code>, <code>DIRECTX11</code>, <code>DIRECTX12</code> and <code>SDL_GPU</code> never override it at all. Because most entries <em>fail open</em>, several renderers advertise features whose implementation throws or silently does nothing. Renderers that report honestly — deterministically refusing what they cannot do — are the model to follow.</p>
</div>
<div class="card">
<span class="status-badge status-wip" style="margin-bottom:0.75rem;">Open</span>
<h3>DIRECTX12 scissor, viewport, stencil and blend factor</h3>
<p>DIRECTX12 has a strong core (PSO and root-signature caches, a barrier tracker) but four unimplemented pieces of fixed-function state, and its MRT path clears attachments but never draws to them. Windows-only work with a clear specification and existing sibling implementations in DIRECTX9 and DIRECTX11 to follow.</p>
</div>
<div class="card">
<span class="status-badge status-wip" style="margin-bottom:0.75rem;">Open</span>
<h3>Draw-offset handling</h3>
<p><code>startIndex</code> and <code>baseVertex</code> are ignored on DIRECTX11, and on bgfx outside the wireframe path. Any code that draws a sub-range of a shared buffer therefore renders the wrong geometry on those renderers. Small, well-defined, and pixel-testable.</p>
</div>
<div class="card">
<span class="status-badge status-planned" style="margin-bottom:0.75rem;">Needs CI</span>
<h3>Broader CI coverage</h3>
<p>Alpha.1 has 21 workflow files covering Linux, Apple, Emscripten, platform abstraction, runtime multi-renderer selection and five declared C API gates, while Windows D3D/GDI lanes remain manual. The C API's final target is nevertheless compile-blocked by its incomplete renderer map, and the wider matrix is not exhaustive across 50 identities, drivers and target platforms. Fixing or extending a reproducible gap is useful work.</p>
</div>
<div class="card">
<span class="status-badge status-planned" style="margin-bottom:0.75rem;">Needs a Windows toolchain fix</span>
<h3><code>CnaTests</code> on Windows</h3>
<p>Windows-native lanes exist but the D3D/GDI workflows are manual. A useful contribution is to make a specific renderer lane automatic and reproducible, with its exact MSVC configuration and scoped test inventory documented.</p>
</div>
<div class="card">
<span class="status-badge status-planned" style="margin-bottom:0.75rem;">Unofficial</span>
<h3>macOS support</h3>
<p>CNA has automatic macOS/Metal coverage and experimental iOS final-link plus simulator-smoke coverage. Useful contributions include testing other valid macOS renderer configurations and carefully expanding iOS evidence beyond its alpha.1 SDL_RENDERER boundary.</p>
</div>
<div class="card">
<span class="status-badge status-wip" style="margin-bottom:0.75rem;">Open</span>
<h3>XNB reader gaps</h3>
<p>The read-side XNB loader has 50 built-in readers with FFmpeg and 49 without it. <code>VideoReader</code>, typed external references and a real compiled-effect <code>EffectReader</code> are present. Reflection-based discovery is not; custom readers and closed generic types need explicit registration through the available creator/reader APIs. See <a href="docs/content-pipeline-xnb.html">XNB Content Pipeline</a>.</p>
</div>
<div class="card">
<span class="status-badge status-wip" style="margin-bottom:0.75rem;">Open</span>
<h3>ContentManager lifecycle</h3>
<p><code>ContentManager::Unload()</code> clears its maps without disposing the assets they held, and <code>ResourceContentManager</code> is the repository's only pure stub. Both are small, self-contained fixes with obvious correctness criteria.</p>
</div>
<div class="card">
<span class="status-badge status-planned" style="margin-bottom:0.75rem;">Always welcome</span>
<h3>Test coverage</h3>
<p>Coverage remains uneven even with 8,263 statically discoverable definitions. Storage has only five GoogleTest-family definitions, while Media has 286 and the Canvas renderer has 17; none of those source counts proves runtime success on a target. New focused tests and configuration-specific execution evidence are welcome.</p>
</div>
</div>
<!-- ====================================================
Section 5 — Code style
==================================================== -->
<h2>Code style</h2>
<ul>
<li><strong>C++23 throughout.</strong> CNA requires GCC 12+, Clang 15+, or MSVC 2022 v17.8+. Use modern C++ features freely — structured bindings, ranges, concepts — but keep readability first.</li>
<li><strong>API shape is fixed.</strong> The <code>Microsoft::Xna::Framework</code> public API mirrors XNA 4.0 exactly. Do not rename, remove, or add overloads to public methods without a compelling reason backed by FNA precedent.</li>
<li><strong>Properties become getter/setter methods.</strong> C# <code>public int Width { get; set; }</code> becomes <code>intcs getWidthProperty() const</code> and <code>void setWidthProperty(intcs value)</code> in C++.</li>
<li><strong>Use <code>sharp-runtime</code> types.</strong> Use <code>intcs</code>, <code>bytecs</code>, <code>Single</code>, <code>String</code>, events, and interfaces from <code>sharp-runtime</code> to match C# semantics. Avoid raw <code>int</code> or <code>float</code> at the public API boundary.</li>
<li><strong>No extra runtime dependencies.</strong> CNA's dependency set is deliberately small and mostly vendored or submoduled — SDL3 (plus SDL_image and SDL_mixer), <code>sharp-runtime</code>, and the per-renderer siblings <code>easy-gl</code> and <code>free-direct</code>, alongside in-tree <code>enet</code>, <code>cgltf</code>, <code>stb</code> and <code>wgpu-native</code>. Do not introduce new third-party libraries without prior discussion.</li>
<li><strong>Mark non-XNA additions as <code>CNAEXT</code>.</strong> Any method or type added purely for C++ convenience must carry a <code>// CNAEXT</code> comment so that API coverage tooling stays accurate.</li>
</ul>
<!-- ====================================================
Section 6 — License
==================================================== -->
<h2>License and attribution</h2>
<p>CNA is licensed under the <strong>Microsoft Public License (Ms-PL)</strong>. All contributions must be compatible with the Ms-PL. By submitting a pull request you agree that your contribution will be distributed under the same license.</p>
<div class="callout callout--note">
<span class="callout-icon">📜</span>
<p><strong>Deriving from FNA (C#):</strong> FNA is the authoritative XNA 4.0 reference and is also licensed under the Ms-PL. If you port logic from FNA's C# source into CNA, you must preserve the Ms-PL attribution. See <a href="https://github.com/openeggbert/cna/blob/master/NOTICE.md" target="_blank" rel="noopener">NOTICE.md</a> and <a href="https://github.com/openeggbert/cna/blob/master/THIRD_PARTY_NOTICES.md" target="_blank" rel="noopener">THIRD_PARTY_NOTICES.md</a> for the existing attribution text and the pattern to follow.</p>
</div>
<!-- ====================================================
GitHub CTA
==================================================== -->
<div style="margin-top:3rem; text-align:center;">
<a href="https://github.com/openeggbert/cna" class="btn btn-primary" target="_blank" rel="noopener">
View CNA on GitHub
</a>
</div>
</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>