Chapter 26 DirectX 1–3 and free-direct

DirectX 1 shipped DirectDraw but no Direct3D. CNA’s renderer is consequently a 2D implementation, not an unfinished 3D renderer. Its off-screen surfaces provide RenderTarget2D; MRT and occlusion queries do not exist at this API level.

The extended primitive methods are inherited. Their base route reaches colored rendering, and this 2D family rejects that request. This is the correct visible failure for a permanent API ceiling. Reporting successful effect-aware 3D would be more misleading than throwing.

Build and execution are Windows-shaped. The repository can cross-compile with mingw-w64 and exercise the binary under Wine’s DirectDraw implementation, but that proves a compatibility layer as well as CNA. Native historical drivers remain a different environment claim.

Direct3D 2 is often associated with execute buffers, yet CNA submits immediate DrawPrimitive calls. A spike established that Wine’s implementation accepts the route and provides the transform, lighting, texture, depth, and raster behavior needed by the bounded renderer.

Both extended draw entry points are native fixed-function adapters. CNA’s modern draw packet is reduced to texture, matrix, lighting, fog, alpha, and state concepts available in the old pipeline. Custom programmable effects are outside the API’s design. 2D targets work; multiple attachments and queries do not.

This renderer uses the DirectDraw 2 and Direct3D 2 interface generation available with the DirectX 3 SDK surface. It landed under a temporary DX30 name because the old DIRECTX3 selector was still occupied by what is now FREEDIRECT. The identity cleanup separated historical Microsoft DirectX from the portable sibling project.

The measured source delta from the DirectX 2 port was small, roughly 3.7 percent, but that number describes lineage rather than semantic equivalence. Interface acquisition, presentation, and platform behavior still belong to a separate family and build target. Its draw and target feature shape matches the preceding rung: native fixed-function draws, one 2D target, no MRT, and no occlusion queries.

The sequence isolates what the API itself added. DirectX 1 can compose surfaces but cannot express 3D. DirectX 2 introduces an immediate fixed-function route sufficient for CNA’s bounded 3D mapping. DirectX 3 changes the surrounding SDK/interface generation without turning that fixed pipeline into a programmable one. The same CNA call surface therefore reveals a historical API boundary instead of flattening every old renderer into one generic legacy label.

FREEDIRECT is CNA’s second 2D-only renderer, and its odd one out architecturally: it does not use SDL3’s 2D API at all, instead fronting IDirectDraw / IDirectDrawSurface-shaped calls against free-direct, the narrow DirectDraw reimplementation introduced in Chapter 2 and covered as its own project later in this book. This chapter covers only what is specific to CNA’s own renderer layer on top of it; this book’s free-direct chapter covers the library itself.

free-direct’s IDirectDrawSurface::Lock() never exposes a writable pointer for the primary surface—only for offscreen ones. Instead of treating the primary surface as a render target directly, this renderer owns an internal, always-lockable “shadow backbuffer”: every Clear() and every SpriteBatch draw targets that shadow surface, and Present() is a single identity Blt() copying it onto the primary surface. This design makes the renderer possible.

TextureAddressMode::Wrap and Mirror — the two features Chapter 30 named as formally BLOCKED on SDL_RENDERER — have implemented sampling paths here. This renderer’s CPU compositor already samples per-source-pixel for any non-identity draw, so wrap/mirror addressing costs nothing extra to add. FREEDIRECT also implements separate Opaque, AlphaBlend, NonPremultiplied, and Additive formulas, in contrast to the SOFTWARE renderer’s single collapsed baseline formula.

The renderer audit corrected several independent faults:

• •

  Clear() wrote alpha 255 through its color-fill route; locked-pixel writes now preserve all four requested channels.

• •

  the general CPU blend path omitted source-alpha multiplication;

• •

  CreateOcclusionQuery() threw instead of using the project’s null-safe query;

• •

  blend-preset detection compared factors but ignored BlendFunction, so a custom subtract state could be mistaken for a preset; and

• •

  display-free tests were unnecessarily registered as requiring X11.

The current regressions cover the behavior, while historical test-count bookkeeping is not used as a capability claim.

RenderTarget2D reuses the shadow-backbuffer design once per target. The private render-target renderer owns an always-lockable offscreen surface, defined (like FreeDirectTextureRenderer) entirely inside FreeDirectRenderer.cpp so <ddraw.h> never leaks into a header. Binding one is a pure redirect: Clear() and ReadBackbuffer() both route through an internal Impl::ActiveSurface() indirection that resolves to whichever surface is currently bound, while Present() always targets the shadow backbuffer from §26.6 regardless of what is bound at the time — an intentional asymmetry, since only the shadow backbuffer is the only surface copied to the primary.

freedirect_texture_rendertarget_test.cpp verifies this bind-redirect concretely rather than by code inspection alone, using two distinct, deliberately different clear colors so a readback that returned either the wrong surface’s color or a stale value would fail visibly:

Two further checks round out the same test. RenderTargetUsage::DiscardContents auto-clearing to black on rebind needed zero FREEDIRECT-specific code at all — it falls straight out of shared GraphicsDevice.cpp logic once bind/Clear/read were wired correctly, the same "comes for free" shape Chapter 14 documents for other renderers. This is also a CNA/FNA identity difference: CNA repeats that clear on an identical currently-bound target, while FNA treats the redundant call as a no-op. The persistent DirectDraw surface makes Preserve and Platform retain color in source, but the test proves only the Discard-to-black case; presentation usage is ignored. SetRenderTargets() with two or more bindings throws, honestly: IDirectDrawSurface has exactly one active surface at a time, the identical single-active-surface conclusion Chapter 30 reached for SDL_RENDERER for an unrelated reason (that renderer’s SDL2 render target API, not DirectDraw’s own surface model) — two structurally different renderers landing on the same MRT answer for two different underlying reasons.

The same test confirms the size boundary: a $5000\times 5000$ Texture2D construction throws. free-direct::CreateSurface enforces a fixed $4096\times 4096$ cap, and the renderer propagates that exception.

The ordinary colour hook locks and fills the complete active surface with all four requested channels, and target-redirection tests prove that “active” changes between the shadow backbuffer and a RenderTarget2D. Depth and stencil follow two different layers. GraphicsDevice sees SupportsDepthStencil()==false, strips both flags, and returns silently when no target bit remains — the same depthless-target rule current FNA uses. freedirect_no3d_test.cpp separately invokes all six renderer combination hooks and proves their ThrowNo3D errors precisely because those hooks are unreachable through the public mask. Treating either result as evidence for the other would conflate shared and renderer contracts; §19.4.2 keeps them separate.

No 3D pipeline exists, matching free-direct’s own explicit “Direct3D not implemented” stance; 8-bit palette surfaces and GetDC / SetPalette-style GDI-adjacent calls are unsupported, since XNA itself has no palette-texture concept to begin with; mip levels above zero throw, since IDirectDrawSurface has no native mip chain; and SetPresentationMode() is honestly downgraded from an earlier full-pass mark to a documented partial: it stores the requested presentation mode but never changes the actual physical output scale and always presents in letterbox. Closing this limitation requires a change in free-direct, not only CNA.

The same stored-versus-applied distinction affects two ordinary XNA properties: Dx3GraphicsRenderer overrides neither SetViewport() nor SetScissorRect(), and it has no rasterizer-state hook. Both values therefore round-trip through GraphicsDevice without changing the 2D DirectDraw/SDL output. The SDL renderer that free-direct owns privately does not rescue this path: CNA never routes these graphics-state setters into it (unlike the separate public input-discovery route below). There is no dedicated negative pixel test, so this is a source-proven permanent 2D boundary rather than an executed claim.

There is a related resize defect that is easier to miss because the new logical surfaces are created correctly. Once the first Present() has configured free-direct’s internal renderer, a later SetVirtualResolution() replaces CNA’s primary and shadow surfaces but cannot reset the library’s private logicalPresentationSet_ flag. The next frame therefore uploads the new-sized primary texture into the old logical-presentation rectangle. CNA’s input-transform methods do recompute their scale from the new logical dimensions, but the public input path does not call them: it discovers free-direct’s associated SDL renderer first, as the section below explains. That renderer retains the same old logical-presentation rectangle as physical output, so public input and presentation remain tied to the old coordinate canvas while the game’s newly allocated surfaces use the new size. Closing that three-way mismatch needs free-direct to reapply logical presentation when the primary changes, not an unilateral CNA-side approximation.

DirectSound / DirectPlay networking are explicitly out of scope for this renderer by the project owner’s own instruction — CNA’s own audio and networking go through the ordinary renderer-agnostic paths from Chapter 45 and Chapter 51 of this book, not through free-direct at all.

The renderer implements both TransformWindowToLogical() and its inverse from the physical SDL_Window size. For a logical size $(L_w,L_h)$ and physical window size $(P_w,P_h)$, they recompute the same centered-letterbox transform that free-direct uses:

A logical point maps to $(xs+o_x,ys+o_y)$; a mouse/window point maps back through $((x-o_x)/s,(y-o_y)/s)$. Thus the black bars introduced by the otherwise unavoidable letterbox mode are accounted for explicitly, rather than being accidentally treated as game pixels. The calculation intentionally queries the live physical window every time it is used: the primary/shadow surfaces retain the requested logical resolution, while window managers may choose a quite different actual window size.

Those two correct methods are nevertheless shadowed during normal public input. Both public callers first ask SDL_GetRenderer(window) for an associated renderer and use SDL’s own logical-coordinate conversion when one exists. Only a renderer-less window proceeds to the renderer registry. free-direct creates an SDL renderer on this same window during SetCooperativeLevel(), so SDL’s first tier wins even though Dx3GraphicsRenderer::GetRendererInternal() returns nullptr. CNA can still reach the renderer through the registry; this accessor does not return it.

This route has two time-dependent consequences. Before the first Present(), free-direct has created the renderer but has not yet called SDL_SetRenderLogicalPresentation; public input therefore passes through at window scale. The first presentation installs the hardcoded letterbox mapping, after which SDL’s own conversion correctly follows the displayed output. A later logical resize hits the stale logicalPresentationSet_ problem above: both output and public input retain the old SDL mapping, while the new game surfaces no longer share that coordinate size.

The dedicated Dx3_LogicalTransform test avoids a fragile fixed-size expectation for that reason. It asks the running window for its physical dimensions, requests a $64\times 64$ logical canvas, then verifies four properties: logical-to-window-to-logical round trips preserve five points (corners and centre); logical $(32,32)$ becomes the physical geometric centre; equal horizontal and vertical logical steps have equal physical length; and that measured length is exactly $\min (P_w/64,P_h/64)$. These checks prove both the centering and the absence of silent anisotropic stretch on the active display, including the environment where an attempted SDL_SetWindowSize() was not honoured by the window manager. They do not prove the public route above: the test obtains FreeDirectRenderer& and invokes both methods directly, bypassing Mouse::SetPosition(), SdlInputBridge, and the SDL-renderer-first branch. Chapter 19, §19.2.1, places that proof boundary in the full renderer matrix.

FreeDirectRenderer.cpp creates the primary, shadow backbuffer, render targets, and Texture2D surfaces at 32 bits per pixel. It has no palette/8-bit route. This makes two limitations in free-direct’s docs/directdraw-limitations.md unreachable from CNA:

The discarded bit-depth parameter.

IDirectDraw::SetDisplayMode’s dwBPP parameter is silently discarded — free-direct’s own CreateSurface always allocates a 32bpp primary regardless of the requested depth. CNA’s CreateSurfaces() always requests 32, so its request and the library result agree.

The mixed-depth blit silent-no-op.

DirectDrawSurfaceImpl’s BlitFrom method implements same-depth 8-on-8 and 32-on-32 copies; a mixed pair copies nothing. CNA creates only 32bpp surfaces, so every renderer-issued blit follows the 32-on-32 path.

XNA’s SurfaceFormat has no 8-bit indexed-color member, so this fixed direct-color choice fits CNA’s public texture model. Direct users of free-direct that request 8-bit surfaces or mixed-depth blits remain exposed to the underlying limitations.