Appendix E CNAEXT: Marker and Engine-Layer Catalog
“CNA extension” names three related but non-equivalent mechanisms in the pinned tree. Keeping them separate prevents both API overclaim and build confusion.
| Name | Meaning |
|---|---|
| CNAEXT | Empty marker placed on a declaration inside an XNA-shaped namespace when that declaration is not part of real XNA 4.0. Strict harnesses redefine it as a deprecation attribute and turn use into an error. |
| CNA::* | Project-owned namespaces for helpers, renderer contracts, input/device services, diagnostics and engine-layer types that do not pretend to be Microsoft XNA declarations. |
| CNA_CNAEXT / CNA::CnaExt | A CMake option enabling selected extension products, and an interface target composing graphics-ext with devices-ext. Neither is the declaration marker or a promise that every marked method disappears when the option is off. |
The retired pre-migration target/library spelling survives only through compatibility wiring; the compatibility label above preserves old book links, but the live manuscript and current target vocabulary use CNAEXT. The authoritative marker inventory is the source plus strict positive/negative compile harnesses, not a hand-copied book list: a whole-token scan at the pin finds 1,876 occurrences across 302 headers, and that count will change as API classification changes.
E.1 Framework and math bridges
| Surface | Extension role | Narrative home |
|---|---|---|
| GameWindow *EXT members | Raw SDL window access, borderless state and minimize/restore operations absent from the console-era XNA window contract. | Chapter 6 |
|
GraphicsDeviceManager
presentation modes |
Letterbox, overscan, stretch, native-backbuffer and fixed-height/dynamic-width policies layered around XNA’s manager. | Chapters 6 and 12 |
|
Matrix::
ToColumnMajor |
Explicit bridge from CNA/XNA row-vector storage to APIs that want column-major uniform bytes. | Chapter 7 |
| Color conveniences | Byte-component construction and convenience operators not present in the reference surface. | Chapter 7 |
| GetTypeName implementations | Project-wide runtime type-name bridge supplied by sharp-runtime conventions, not an XNA member family. | Chapters 3 and 55 |
E.2 Graphics and content extensions
| Surface | Extension role | Boundary |
|---|---|---|
|
CNA::Graphics::
AsciiPostProcessEffect |
Reusable quantization/glyph-atlas effect recovered from the removed ASCII renderer identity. | Renderer-neutral extension in graphics-ext; not a 47th renderer. |
| PbrEffect, SkinnedPbrEffect | Metallic-roughness material and its skinned sibling for glTF-era content. | Renderer coverage differs; WebGPU lacks the skinned route. |
| AnimationPlayer, SkinningData | Runtime skeletal system derived from the historical XNA skinned-model sample rather than the framework assembly. | Separate from the Avatar SkinnedModelEXT system. |
| Morph-target *EXT surface | CPU delta blending, weights and animation attached through model tags. | POSITION/NORMAL only; tangent deltas are out of scope. |
| ShaderEffect | Renderer-specific source/program custom-shader route. | Does not make a renderer support the separate compiled Effect Framework route; capability and factory must still agree. |
| Texture/format helpers | Raw pixel/data helpers, DDS cube loading, format-size queries and additional surface-format values. | Presence does not equal support on every renderer. |
| Graphics diagnostics/recovery | String markers, context-loss simulation/recovery controls, screenshot/readback and headless-related hooks. | Hook presence, renderer override and retained host evidence are separate. |
| CNJ system | JSON envelope, typed loaders and offline model sidecars. | Project-owned format; reader-specific payloads, not a universal schema. |
| Content manifests and XNB usage summaries | Enumerate discovered assets and reader-name use for audit/tooling. | Introspection does not itself resolve or validate every asset. |
E.3 Input, audio, media, and host services
| Area | Representative extension surface | Why it is separate |
|---|---|---|
| Input | Clipboard, joystick, power, haptics and raw device helpers; scancode/key-name queries; mouse capture/global position; modern gamepad identity, lights, trigger vibration and sensors. | SDL3/modern-controller capabilities exceed XNA’s Xbox 360 model. |
| Audio | Float-buffer submission on DynamicSoundEffectInstance. | Real XNA’s streaming surface accepts 16-bit PCM bytes, not this float path. |
| Media | Video URI and audio/video track selection *EXT methods. | Some originate in FNA extensions, but they remain outside original XNA. |
| Devices | CNA::Devices camera, dialogs, locale, URL, system/clipboard and power services. | Project namespace and devices-ext module keep them distinct from Microsoft::Devices::Sensors. |
| Sensors | Synthetic injection, state-symmetry and richer vibration/support helpers marked inside Microsoft-shaped classes. | Useful testing/platform bridges without reclassifying them as XNA. |
| Storage | Application-name and storage-root helpers. | CNA needs a deterministic local root where XNA selected a storage device through platform UI. |
| GamerServices | Local overlay rendering/simulation, ranking/re-pagination and persistence hooks. | They make local behavior testable without claiming Xbox LIVE services. |
| Networking | Public/internal setters and host-delivery controls needed by the ENet-backed implementation. | Restore real session behavior where the reference implementation retains inert or inaccessible state. |
Appendix F maps the surrounding faithful APIs. Extension surface still needs the same ownership, failure, hostile-input and host-evidence analysis as an XNA-shaped member; the marker says only “not original XNA”.
E.4 How the strict check proves itself
In normal compilation CNAEXT expands to nothing. Two standalone harness directions give it force:
-
1.
a positive target defines CNA_STRICT_XNA_API, enables warnings-as-errors for deprecated declarations, and compiles code restricted to the intended XNA surface;
-
2.
an excluded negative target deliberately calls a marked sensor injection method and is required to fail compilation. Its CTest uses inverted success so a broken guard that lets the leak compile turns the test red.
This pair proves both acceptance and sensitivity for the exercised slice. It does not prove that every project addition has been marked correctly; that still requires comparison with the reference surface and review of the namespace/classification boundary. Appendix G places this negative compile oracle among the other evidence forms.