Core framework and graphics API map
Evidence basis: source-verified at the pinned commit. Claims on this page were checked by reading the CNA source at commit 009d40f5; unless a sentence says otherwise, nothing here was built or executed. Records API presence and one qualification per row, checked against the pinned headers; behaviour and tests are on the linked pages.
An orientation map of CNA's core framework and graphics API at this snapshot: for each group of XNA types, the header that owns it, the shape of its public surface, the boundary that most often trips a port, and the page that explains the behaviour. It groups overload families instead of reproducing declarations — the headers remain the signature authority — and it answers "where is the surface and what does it not promise?", not "what does this revision do on renderer X?". A listed member proves that the API exists; it does not prove that each of the 21 renderer families gives it the same semantics.
Reading this map safely
Public XNA-shaped declarations live under modules/<owner>/include/Microsoft/Xna/Framework/; CNA extensions without an XNA counterpart live under modules/<owner>/include/CNA/ and XNA-namespace members that CNA added are marked CNAEXT. The owners used below are math, runtime, content and graphics (graphics headers). For any row, pair the header with its implementation, the renderer route that executes it, its tests and the host that ran them; the representation census (331 of 331 public types, 3,627 of 3,627 documented members) measures presence, not behaviour — see XNA compatibility and Compatibility levels and the evidence vector. C++ spelling rules (properties as getXProperty()/setXProperty(), events, out parameters) are on From C# to C++.
Math and geometry types (math module)
| Type group | Public shape | Boundary to remember |
|---|---|---|
Vector2, Vector3, Vector4 | public components, constants, arithmetic, distance and dot, interpolation, normalisation, reflection, matrix and quaternion transforms; Vector3 adds the cross product | value-returning and output-reference overloads are separate API rows and need separate tests |
Matrix | sixteen public elements, direction and translation properties, decomposition, arithmetic, inversion and transposition, the XNA Create* families | row-vector convention as in XNA; the CNAEXT ToColumnMajor(float[16]) is a bridge for shader upload, not a change of convention |
Quaternion | construction from axis/angle, matrix and yaw-pitch-roll; arithmetic, concatenate, conjugate, inverse, lerp and slerp | multiplication order and normalisation are behavioural contracts, not naming details |
Point, Rectangle | integer screen-space coordinates, containment, intersection and union, offset and inflation | edges and empty/intersection cases follow XNA/FNA's exact boundary rules |
Color | packed RGBA value, named colours, vector, float and integer constructors, interpolation and premultiplication helpers | packed as AABBGGRR; Color derives from the polymorphic IPackedVector interface, so its C++ object is not its four-byte stream form (see vertex layouts); constructor argument types change overload choice and clamping |
Plane, Ray, BoundingBox, BoundingSphere, BoundingFrustum | construction, containment, intersection, corners and transforms | C# nullable returns become std::optional (for example Ray::Intersects returns std::optional<float>) and out parameters become output references; compare semantics, not signature strings |
Value semantics and memory layout: Math types, Math value types in C++ and math module internals. Coordinate, matrix, viewport and vertex-layout conventions: Coordinate and composition conventions. The generated xna4-spec XML is useful inventory for a table like this one, but it needs language normalisation and a behavioural oracle before a comparison means anything (xna4-spec hygiene).
Game framework and content (runtime, content)
| Type | Primary surface | Current qualification |
|---|---|---|
Game | lifecycle events; components, content, services, window and device; fixed and variable timing; Run, Tick, Exit and the initialize/load/update/draw hooks | host ownership differs on native, browser and mobile paths; the call order is the contract, not the presence of virtual methods (Game class and run modes) |
GameTime | total and elapsed time plus the slow-frame flag | written only by Game; user code consumes the snapshot (GameTime and timestep) |
GameWindow | bounds, title, resize, orientation and display events, the screen-device-change protocol, marked native-window conveniences | one concrete facade that delegates to the selected platform's IPlatformWindow (SDL3, SDL2, X11, Wayland, Win32, Headless or Terminal) where FNA has per-platform subclasses; behaviour remains host-specific |
GraphicsDeviceManager | preferred back-buffer, depth, profile and full-screen settings, ApplyChanges, device creation and preparation events, presentation extensions | stored values are requested state, not proof that the driver or window accepted them; the default profile is Reach (window and device manager) |
ContentManager | root directory, service provider, Load<T> (by value, e.g. getContentProperty().Load<Texture2D>("name")), Unload, reader and CNJ registration, manifest and reader-usage extensions | resolution tries .xnb first, then CNA's own compiled .cnb, then the loose readers registered for the type (.cnj documents and native formats); success on one route is not evidence for another, and caching and ownership vary by asset type (ContentManager) |
Graphics core: resources and batching (graphics)
| Type group | Public shape | Evidence boundary |
|---|---|---|
Texture2D | dimensions and bounds, whole and rectangular SetData/GetData, FromStream, SaveAsPng/SaveAsJpeg (plus CNAEXT file-name overloads and DDSFromStreamEXT) | a round trip can observe CNA's CPU shadow rather than sampled GPU memory; mip and sub-rectangle behaviour and accepted formats are renderer-specific (texture data transfer, surface formats) |
Texture3D, TextureCube | volume or face dimensions and level/sub-region upload and readback families | construction, format, mip, upload and readback are separate capabilities; volumes are refused under Reach |
RenderTarget2D, RenderTargetCube | texture surface plus depth/stencil, multisample and usage metadata; cubes add face selection | binding, preserve/discard, multiple targets, cube unbind and readback are independent renderer paths (render target semantics) |
VertexBuffer, IndexBuffer, dynamic variants | counts, usage and declaration; typed and sliced upload and readback; dynamic subclasses add SetDataOptions | the constructor's dynamic intent, the upload hint, the CPU shadow and the renderer buffer are four distinct layers (vertex and index buffers, declarations and streams) |
SpriteBatch | Begin/End, texture Draw overloads, DrawString for strings and StringBuilder | sort mode, state objects, custom effect, transform and clipping must each reach the selected renderer; a visible sprite does not prove every argument (SpriteBatch semantics) |
SpriteFont | atlas, glyph, cropping, character and kerning arrays, spacing, default character, measurement | XNB, CNJ and hand-built fonts enter through different reader and ownership routes (SpriteFont text layout) |
Detailed texture, render-target and SpriteBatch behaviour lives on the linked pages. The per-identity answers are in the renderer capability matrix and the evidence each family has is in what each kind of renderer can prove; do not infer a cross-renderer guarantee from the common C++ type alone.
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 and declarations, effects, Draw | several loading routes with different provenance; Model::Draw requires every part effect to implement IEffectMatrices (otherwise InvalidOperationException) and uses a per-thread shared scratch array for absolute bone transforms, so calls on one thread are serial (Model loading) |
BasicEffect | matrices, texture and vertex colour, material colours, fog, three directional lights | each renderer's own shader mapping decides which fields are consumed (BasicEffect semantics) |
AlphaTestEffect | texture, vertex colour, fog, alpha comparison and reference value | a renderer without a discard path must refuse rather than draw the surface opaque (PORTABLEGL refuses a non-default alpha test by name); a successful draw proves the test only with a fixture whose kept and discarded pixels differ |
DualTextureEffect | two texture layers, matrices, vertex colour, fog | the second layer needs a second UV set in the vertex layout and a renderer route |
EnvironmentMapEffect | diffuse texture, cube environment map, amount, specular, Fresnel, matrices, fog, lights | cube construction/sampling and effect dispatch are separate gates; lighting cannot be turned off |
SkinnedEffect | matrices, material, texture, fog, lights, a 72-bone palette and 1/2/4 weights per vertex | palette size and layout are run-time contracts; CNA's vertex-colour addition is CNAEXT |
Runtime ownership and the draw contract: Model, ModelMesh and ModelMeshPart. glTF and CNJ import: the glTF import core and glTF conformance; the glTF feature matrix keeps importer, runtime and test evidence separate.
GraphicsDevice and state objects
GraphicsDevice is the renderer-independent dispatch facade. Its public groups: adapter, display, profile, status, presentation and disposal state; texture, sampler, vertex-buffer, index-buffer and render-target binding; blend, depth/stencil, rasterizer, viewport, scissor and blend-factor state; clear, present, back-buffer readback and screenshot helpers; bound-buffer, user-array, indexed, instanced and (CNAEXT) indirect draw families; capability queries, the unsupported-3D policy and marked diagnostic and recovery helpers. The facade stores and returns state even where a renderer family does not consume it, so read back values are requested state; operation-level behaviour is on GraphicsDevice contract, and SupportsCapability(...) == true is a preflight hint, not an execution result (capability answers and evidence).
| State object | State represented |
|---|---|
BlendState | colour and alpha factors and functions, four write masks, blend factor, multisample mask, presets |
DepthStencilState | depth enable, write and comparison; front and back stencil operations |
RasterizerState | cull and fill mode, depth bias, multisampling and scissor-enable intent |
SamplerState | addressing, filtering, anisotropy, mip limit and level-of-detail bias |
State objects are not copied by value in the C# sense: C++ copies of one state object share a single payload, as references to one object do in XNA, and binding it to a device marks that payload bound. From then on every setter on any copy throws InvalidOperationException ("Cannot modify a BlendState after it has been bound to a GraphicsDevice"), and assigning the object that is already active on that device again is a no-op (unless the standalone BlendFactor, MultiSampleMask or ReferenceStencil properties have marked it dirty; see GraphicsDevice contract). Whether each field then reaches native state still depends on the renderer family (state objects).
Effect base, parameters and queries
| Type | Public shape | Boundary |
|---|---|---|
Effect | parameter and technique collections, current technique, Clone, the CNAEXT Apply() convenience; a byte constructor for XNA/FNA Direct3D 9 Effect Framework binaries | the byte constructor works where CompiledEffects is true: FNA3D always, nine families behind default-OFF options; it is not a source compiler and refuses .fx/HLSL, DXBC and MGFX (compiled XNA effects, effect object model) |
EffectParameter | typed scalar, vector, matrix, quaternion, string and texture setters and getters, class/type/dimension metadata, elements, members, annotations | on a stock effect the records are CNA-built and mostly derived; only compiled parameters are reflected storage with XNA's type checks |
ShaderEffect (CNAEXT) | a renderer-specific source or bytecode pair with SetUniformXxx/SetTexture | a separate route with its own capability; the existence of a stock effect or parameter setter never proves compiled-effect execution (four shader routes) |
OcclusionQuery | Begin, End, IsComplete, PixelCount and the CNAEXT isPixelCountPreciseEXT() | construction throws NotSupportedException under Reach, when the capability is false, or when the renderer creates no query; some renderers report a 0/1 flag rather than a sample count, so a true capability and a non-null object still need a discriminating sample-count test (which identities report the capability: column Oq of the capability matrix) |
Evidence and limits
Checked by reading the named headers and, where a boundary is stated, the implementation at snapshot 009d40f5; nothing was built or executed. The map records API presence and the most important qualification per row; behaviour, renderer matrices and test evidence live on the linked pages.
Related pages
The same subject is explained at several altitudes. These are the neighbouring pages at each one.
- User guide
- XNA compatibility · Graphics state · Math types
- Architecture
- Graphics architecture · Runtime architecture
- Internals
- GraphicsDevice internals
- Reference
- Public headers
- Deep dives
- From C# to C++: translation conventions