Choosing a backend¶

This page lists the render contexts, says when each is the better choice, and shows how to choose one for a project, have a fallback at run time, or use another one for a single pass.

The render contexts¶

Render context	Switch	Platforms	Renders to	Use it for
Direct2D, Direct3D 11	`SVGDirect2d3D11`	Windows (VCL, FPC)	Bitmap, window, command list, printer	The default. GPU filters, smooth animation in `TSVG2WinControl`, printing with selectable text. One rendering thread at a time.
Direct2D, WIC	`SVGDirect2dDWIC`	Windows (VCL, FMX, FPC)	Bitmap	Services and batch jobs that render in parallel: CPU only, nothing shared between threads, output identical between runs.
GDI+	`SVGGDIP`	Windows (VCL, FMX)	Bitmap, device context, metafile, printer	EMF export (used for one pass automatically, see below), and as a fallback where Direct2D cannot start.
Quartz	`SVGQuartz`	macOS, iOS (FMX, FPC)	Bitmap	The default on Apple platforms.
FMX canvas	`SVGFMXCanvas`	Every FMX platform	Bitmap, canvas, printer	The FMX default. Quality and precision depend on the platform; on Windows, Direct2D WIC is available for FMX as well.
Graphics32	`SVGGraphics32`	Windows (VCL), FPC	Bitmap, device context	Applications already built on Graphics32. Needs the Graphics32 library.
AggPas	`SVGAGGRenderer`	Windows, macOS, Linux	Bitmap	A CPU renderer that is the same on every platform. Needs the AggPasMod library.
BGRABitmap	`SVGBGRABitmap`	FPC on Windows, macOS, Linux	Bitmap	The Linux default. Not tested with the current version. Needs the BGRABitmap library. Gradient spread methods and dash offsets are not supported.
Skia	`SVGSkia`	Windows (VCL, FMX), macOS (FMX)	Bitmap, PDF file	The closest to a browser's rendering in our tests, and PDF files without a printer driver, with selectable text (see PDF). Needs the Skia4Delphi that comes with Delphi 12 and later, and on Windows `sk4d.dll` next to the application; on macOS Skia is linked into the executable.

The font systems are chosen the same way:

Font system	Switch	Platforms	Notes
DirectWrite	`SVGFontDirectWrite`	Windows	The default. Complex scripts, custom fonts, selectable text in PDF.
GDI and Uniscribe	`SVGFontGDI`	Windows	Needed for text in EMF export; used for that pass automatically.
CoreText	`SVGFontCoreText`	macOS, iOS	The Apple default. No custom fonts.
FreeType	`SVGFreetype`	Every platform	Needs the FreeType library (`freetype.dll` or `libfreetype-6.dll` on Windows). No custom fonts, no Arabic shaping.
Skia	`SVGFontSkia`	Windows, macOS	Goes with the Skia render context. Custom fonts, selectable text in PDF.

Per project¶

The switches live in the library, in Common\Vcl\ContextSettingsVCL.inc (and the FMX and FPC equivalents), so by default every project built from the same library folder gets the same backend. To choose for one project, leave that file alone and add SVGCustomContextSettings to the project's conditional defines, together with the switches you want:

Project > Options > Building > Delphi Compiler > Conditional defines
  SVGCustomContextSettings;SVGDirect2dDWIC;SVGFontDirectWrite

or on the command line:

dcc32 -DSVGCustomContextSettings;SVGDirect2dDWIC;SVGFontDirectWrite ...

With SVGCustomContextSettings defined, the include file sets nothing and the project decides. A project that selects no render context or no font system does not compile, and the error names the switches to choose from.

Build the project completely (Project → Build, or dcc32 -B) after changing these defines, so every library unit is compiled with them.

A fallback at run time¶

On VCL, Direct3D 11, WIC and GDI+ can be compiled in together. The library then uses the first one the computer supports, in that order:

SVGCustomContextSettings;SVGDirect2d3D11;SVGDirect2dDWIC;SVGGDIP;SVGFontDirectWrite;SVGFontGDI

When no graphics adapter can be used, as on some servers and virtual machines, the Direct3D 11 backend already falls back to WARP, the software rasteriser that is part of Windows. A fallback list is for environments where even that fails.

TSVGRenderContextManager.RenderContextType and RenderContextFactoryClass report which one was chosen, for a log or an About box.

One pass on another backend¶

A document can be rendered once on another backend that is compiled in, without changing the application. EMF export is the main use: BVE.SVG2ExportEMF.VCL renders the document on GDI+ with GDI fonts for that one pass, because an EMF file can only hold what GDI+ draws. See EMF for Office and report tools.

To do the same yourself, give the document a resource factory for the other pair before rendering:

Root.ResourceFactory :=
  TSVGRenderContextManager.CreateResourceFactory(rcGDIPlus, fsGDI);

The render context you then render into must be of the same kind. Set ResourceFactory back to nil to return to the default. Direct3D 11 and WIC are both rcDirect2D, so this cannot choose between the two; that choice is made at compile time.