Appendix A Core Framework and Graphics API Reference
This appendix is an orientation map to the public core and graphics surface at the pinned CNA revision. It intentionally groups overload families instead of reproducing declarations: the module-owned headers remain the signature authority, while the cited chapters own behavioral and renderer-specific qualifications. A listed method proves API presence only; it does not imply that every one of the 46 implementation families renders it with the same semantics.
A.1 Math and Geometry Types
| Type group | Public shape | Boundary to remember |
|---|---|---|
| Vector2, Vector3, Vector4 | Public components, constants, arithmetic, distance/dot, interpolation, normalization, reflection, and matrix/quaternion transforms; Vector3 adds cross product. | Value-returning and output-reference overloads are independent API rows and need independent tests. |
| Matrix | Sixteen public elements, direction/translation properties, decomposition, arithmetic, inversion/transposition, and the XNA creation families. | CNA uses row-vector conventions; ToColumnMajor is a marked bridge for shader upload, not a change of the public convention. |
| Quaternion | Construction from axis/matrix/yaw-pitch-roll, arithmetic, concatenate, conjugate, inverse, lerp and slerp. | Quaternion multiplication order and normalization are behavioral contracts, not naming details. |
| Point, Rectangle | Integer screen-space coordinates, containment, intersection/union, offset and inflation. | Rectangle edges and empty/intersection cases use exact XNA/FNA boundary rules. |
| Color | Packed RGBA value, named colours, vector/float/integer constructors, interpolation and premultiplication helpers. | Packed storage is AABBGGRR; constructor type changes can alter overload and clamping behavior. |
| Plane, Ray, BoundingBox, BoundingSphere, BoundingFrustum | Shape construction, containment, intersection, corners and transform-related queries. | C++ optionals/output references translate nullable and out forms; compare semantics, not signature strings alone. |
A.2 Game Framework and Content
| Type | Primary surface | Current qualification |
|---|---|---|
| Game | Lifecycle events; components, content, services, window and device; fixed/variable timing; Run, Tick, Exit, and the initialize/load/update/draw hooks. | Host ownership differs on native, Emscripten and mobile paths; the call order is the contract, not merely the presence of virtual methods. |
| GameTime | Total and elapsed time plus the slow-frame flag. | Mutable by the framework; user code consumes the snapshot. |
| GameWindow | Bounds, title, resize/orientation/display events and screen-device-change protocol, plus marked SDL/native-window conveniences. | CNA uses one SDL3-backed concrete class; lifecycle/platform behavior remains host-specific. |
| GraphicsDeviceManager | Preferred backbuffer/depth/profile/fullscreen settings, ApplyChanges, device creation/preparation events, and presentation-mode extensions. | Stored presentation values are requested state, not proof the driver/window accepted them. |
| ContentManager | Root directory, service provider, generic Load<T>, Unload, reader/CNJ registration, manifest and reader-usage extensions. | Resolution is XNB first, then a registered loose reader that may select CNJ or a native format; cache and ownership vary by asset type. |
A.3 Graphics Core: Resources and Batching
| Type group | Public shape | Evidence boundary |
|---|---|---|
| Texture2D | Dimensions/bounds, whole and rectangular SetData/GetData, stream decode, PNG/JPEG save, and marked pixel helpers. | A round trip can observe CNA’s CPU shadow rather than sampled GPU memory; mip/subregion behavior is renderer-specific. |
| Texture3D, TextureCube | Volume or face dimensions and level/subregion upload/readback families. | Construction, format, mip, upload and readback support are separate capabilities; no CPU shadow provides a universal fallback. |
| RenderTarget2D, RenderTargetCube | Texture surface plus depth/stencil, multisample and usage metadata; cube adds face selection. | Bind, preserve/discard, plural targets, cube unbind and readback have independent renderer paths. |
| VertexBuffer, IndexBuffer | Counts/usage/declaration plus typed and sliced upload/readback; dynamic subclasses add SetDataOptions. | The constructor’s dynamic intent, upload hint, CPU shadow and renderer buffer are four distinct layers. |
| SpriteBatch | Begin/End, texture Draw overloads and DrawString for strings/StringBuilder. | Sort mode, state objects, custom effect, transform and clipping must reach the selected renderer; a visible sprite alone does not prove every argument. |
| SpriteFont | Atlas, glyph/cropping/character/kerning arrays, spacing/default character, and measurement. | XNB, CNJ and hand-built fonts enter through different reader/ownership routes. |
A.4 Model and Stock Effects
| Type group | Public shape | Boundary |
|---|---|---|
| Model, ModelBone, ModelMesh, ModelMeshPart | Bone and mesh collections, root/parent hierarchy, transform-copy helpers, part buffers/declaration, effects and draw. | Four loading routes have different provenance; Model::Draw requires matrix-capable effects and uses serial shared scratch state. |
| BasicEffect | Matrices, texture/vertex colour, material colours, fog and three directional lights. | Renderer-owned shader/fixed-function mapping decides which fields are consumed. |
| AlphaTestEffect | Texture, vertex colour, fog, alpha comparison and reference value. | A draw can succeed while a fallback loses alpha-test semantics. |
| DualTextureEffect | Two texture layers, matrices, vertex colour and fog. | The second layer needs a renderer route and compatible packed layout. |
| EnvironmentMapEffect | Diffuse texture, cube environment map, amount/specular/fresnel, matrices, fog and lights. | Cube construction/sampling and effect dispatch are separate gates. |
| SkinnedEffect | Matrices/material/texture/fog/lights plus bone palette and 1/2/4 weights per vertex. | Maximum palette/layout and animation binding are runtime contracts; CNA’s vertex-colour addition is marked CNAEXT. |
A.5 GraphicsDevice and State Objects
GraphicsDevice is the renderer-independent dispatch facade. Its public groups are:
-
•
adapter/display/profile/status/presentation identity and disposal state;
-
•
texture, sampler, vertex-buffer, index-buffer and render-target binding;
-
•
blend, depth/stencil, rasterizer, viewport, scissor and related scalar state;
-
•
clear, present, backbuffer readback and screenshot helpers;
-
•
bound-buffer, user-array, indexed and instanced draw families;
-
•
capability queries, unsupported-3D policy, and marked diagnostic/recovery helpers.
The facade stores and returns state even where an implementation family does not consume it. The pin also contains concrete asymmetries in singular/plural bindings, offsets/frequencies, readback source, clear masks, presentation interval/format and capability truth. Therefore use the operation-level matrices in Chapters 12 and 19; SupportsCapability(true) is a preflight hint, not an execution artifact.
The four state objects remain distinct:
| Type | State represented |
|---|---|
| BlendState | colour/alpha factors and equations, write masks, blend factor and presets |
| DepthStencilState | depth enable/write/compare and front/back stencil operations |
| RasterizerState | cull/fill, bias, multisampling and scissor-enable intent |
| SamplerState | addressing, filtering, anisotropy, mip limit and LOD bias |
CNA copies assigned state objects by value. Later mutation of the original object does not retroactively modify the device copy. Whether each copied field reaches native state still depends on the renderer family.
A.6 Effect Base, Parameters, and Queries
Effect owns parameter and technique collections, a current technique, cloning, and the CNA-added convenience that applies the current pass. Its bytecode constructor accepts the XNA/FNA D3D9 Effect Framework payload supported by the selected renderer; FNA3D is the normal alpha.1 route, while SDL_GPU, EasyGL and Vulkan require their explicit experimental effect options. EffectParameter exposes typed scalar/vector/matrix/string/texture setters and getters plus class/type/dimension metadata and nested collections. This is not a source compiler and does not accept .fx/HLSL, DXBC or MGFX. ShaderEffect is a distinct renderer-specific source/program route. The existence of a stock effect or parameter setter therefore does not prove compiled-effect execution for a renderer absent the matching capability and factory.
OcclusionQuery exposes Begin, End, completion, and pixel count. Appendix B identifies families with real, conditional, trace-only, null, or misreported query paths. A non-null public wrapper and a true capability bit are insufficient without a usable renderer object and a discriminating sample-count test.
A.7 Reading this appendix safely
For exact declarations, search the selected type under modules/<owner>/include/Microsoft/Xna/Framework/ at CNA v0.1.0-alpha.1 @ 1bb2145d99ed572dd4eb15009c34e2e5f410fcf0. Then pair the header with its implementation, renderer route, tests and host evidence. This appendix answers “where is the surface?”; the book’s chapters and retained audit reports answer “what does this revision actually do?”