Metafiles (RecursiveAI.OneImage.Metafile)

The package reads Windows Enhanced Metafiles (EMF) and Windows Metafiles (WMF) two ways: as an image format that is drawn at the requested size, and as a stream of device-independent drawing commands. It is clean-room: written from [MS-EMF] and [MS-WMF] only, and checked against Windows GDI output made by us. EMF+ records are not interpreted yet (see Gaps).

Two layers

// 1. Image format: Image.Load(emf) rasterizes at the final size.
var config = new ImageConfiguration().Add(MetafileFormat.Instance).Add(WmfFormat.Instance); // WMF is its own format
Image.Load("a.emf", new LoadOptions { Configuration = config }).Resize(width: 800).Save("a.png");
 
// 2. Command stream: the same interpreter, without rasterizing.
MetafileDocument doc = MetafileDocument.Load("a.emf");   // or Parse(bytes), Identify(bytes)
doc.Play(new MyVisitor());                                 // DrawingCommandVisitor, all methods optional

The raster sink is just a DrawingCommandVisitor on the drawing engine, so the command stream carries everything a renderer needs.

The command stream

Commands are records in OneImage.Metafile; each has a language-neutral Name and Describe() (a name plus string parameters) and the index of the record that produced it.

A walk is cheap: MetafileDocument.Parse interprets once; Play can be called any number of times. Geometry, pen widths and text stay in logical units under the current transform, as on a canvas, so a consumer that draws vectors (a PDF writer, say) keeps the picture resolution-independent. MetafileReadOptions.MeasureText lets the caller supply text widths for records that carry none (needed for text alignment and the update-current-position mode).

Rendering

MetafileFormat(limits, fonts, antialias, background):

• Size. The natural size is the header's reference device size of the frame, in pixels (Identify reads the header only). The decoder advertises RenderAtSize, so Resize/Thumbnail draw at the final size. Cosmetic pens stay one output pixel wide whatever the scale; geometric pens scale with the picture.
• Anti-aliasing is on by default and uses the drawing engine's exact-area coverage. antialias: false gives GDI-like hard edges, which is how the Windows comparison runs. Windows GDI itself does not anti-alias, so a default render differs from GDI along edges.
• Background is transparent unless background is given. Raster operations that read the destination (XOR, PATINVERT, SRCAND...) treat a transparent destination as white.
• Fonts come from MetafileFontOptions: your FontCollection, optionally installed system fonts, a substitution table (Substitutions), and a DefaultFamily. Common Windows faces (Arial, Segoe UI, Tahoma, Times New Roman, ...) map to similar installed families when not present. Text is drawn from outlines with the Text package; glyph positions come from the record's advances when present.
• Sampling. Bitmaps are sampled bilinearly in STRETCH_HALFTONE mode only when the stretch shrinks the bitmap (as GDI does), and nearest-neighbor otherwise.

Geometry conventions (measured from Windows output)

Where [MS-EMF] does not say how GDI behaves, the renderer follows what Windows GDI drew for the same files (see the last section).

• Shape boxes are inclusive. GDI records Rectangle(10, 10, 45, 80) as 10, 10, 44, 79 and plays the box back covering that last pixel, so rectangles, ellipses and rounded rectangles extend one device pixel past the recorded right and bottom edge. Arc bounding boxes are used as recorded.
• Strokes are placed so that a one-pixel pen on integer coordinates fills one row or column of pixels: the geometry is shifted half a reference-device pixel, and box outlines are drawn half a pixel inside the box edge. PS_INSIDEFRAME insets by half the pen width.
• Pens. A legacy pen of width 0 or 1 is cosmetic (one device pixel, ignores the transform); wider legacy pens are geometric with round caps and joins. Extended pens follow PS_COSMETIC/PS_GEOMETRIC. Cosmetic dash patterns are 18/6 (dash), 3/3 (dot), 9/6/3/6 (dash-dot) and 9/3/3/3/3/3 (dash-dot-dot) pixels. A geometric pen counts in pen widths: dash 3 on 1 off, dot 1 on 1 off, dash-dot 3 1 1 1, dash-dot-dot 3 1 1 1 1 1; with round or square caps the cap belongs to the dash, so a round-capped dot is a disc the width of the pen every two widths. User-style dash lengths are in logical units.
• Hatch brushes are 8x8 cells in output pixels (they do not scale with the picture), anchored at the brush origin, which is also not scaled: the horizontal line is on row 3 and the vertical line on column 4 of the cell, the forward diagonal is x = y and the backward diagonal x + y = 7.
• Region fills. FrameRegion paints inside the region's edge. A raster operation other than copy keeps the brush out from under the overlap of a wide pen.
• Region data (clip regions) is in logical units, per the specification.
• Gradient fills ignore the vertex alpha.
• SelectClipPath with an empty path leaves the clip unchanged (GDI fails the call; this happens for a bracket that held only text drawn with a bitmap font).

Record coverage

All record types 1–122 of [MS-EMF] 2.1.1 are dispatched.

Binary raster operations (SETROP2, 16 modes) and ternary operations (the 256 BITBLT codes) are computed per pixel by a pass over the covered area.

WMF

WmfFormat (name wmf, .wmf, image/wmf) registers next to MetafileFormat; MetafileDocument.Parse/Load/Identify accept both and MetafileDocument.IsWmf tells them apart. Placeable (APM header) and non-placeable files are read.

Approach. Each WMF record is translated in memory to the equivalent EMF record and played by the EMF interpreter (Windows itself converts the same way), so every convention above applies and the command stream is unchanged. Diagnostics name the WMF record index and function. WMF specifics:

• Objects. Slots are allocated lowest-free as GDI does (an EMF handle is slot + 1). Palettes and regions are tracked by the converter; regions become inline region data.
• Size. A placeable file is its bounding box divided by units-per-inch, at 96 px per inch. Without a header: the first SetWindowExt in pixels, else the bounds of the drawn coordinates, else 256x256. The reference device is a synthetic 96 dpi 1024x768 display. Until the file sets them, the mapping is anisotropic with window = bounding box and viewport = the whole picture.
• Boxes are right/bottom exclusive as written; the EMF inclusive expansion is not applied.
• Embedded EMF. A file carrying META_ESCAPE / ENHANCED_METAFILE comment chunks is reassembled (at most MetafileLimits.MaxEmbeddedEmfBytes, 64 MiB, checked against the declared size before allocating) and played through the EMF interpreter instead of the WMF records, unless MetafileReadOptions.PreferEmbeddedEmf is false. A damaged embedded EMF falls back to the WMF records with a diagnostic. Identify still reports the WMF header's size.
• Pseudo-records for window/viewport offsets and text character extra are internal.

For a bottom-up DIB the source rows of StretchDIB count from the bottom (as GDI). Bitmap16 is read at 1, 16, 24 and 32 bpp; 1 bpp is black and white.

WMF checked against Windows

The same 15 drawings were recorded as WMF (placeable and non-placeable, identical results) and played by PlayMetaFile at 256x256 into a white bitmap; WmfReferenceTests uses the same pixel comparison as for EMF (per-case floor 95%, text_styled 90%).

The remaining differences are the same as for EMF; text_styled is lowest because of the font faces GDI used.

Gaps (each produces a diagnostic)

WIDENPATH, SETMETARGN, EXTFLOODFILL, text inside a path bracket, glyph-index text (treated as code points), vertical advances in ExtTextOut (PDY), the XformSrc of blits, DIB_PAL_COLORS bitmaps, JPEG or PNG compressed DIBs, right-to-left layout, and EMF+ records. Skipped records never stop the interpretation.

EMF+ (GDI+)

Files recorded by GDI+ keep their drawing in EMF+ records inside EMR_COMMENT records. The interpreter walks them with a graphics state of its own (world, page and container transforms, saved states) and produces the same command stream as for GDI records.

• Dual and EMF+-only files. Once the EMF+ header is seen the GDI records are skipped, as GDI+ itself does, so a dual file is drawn once: the EMF+ drawing wins. Records between an EmfPlusGetDC record and the next EMF+ record are GDI records and are played, in the EMF+ world transform that was in force. (Windows renders both kinds of file the same, and so does the test below.)
• Units. EMF+ coordinates are in reference-device pixels: the world transform, then the page transform (SetPageTransform; inches, points, millimeters, documents and display units use the header's dpi), then the container base. They are folded into one set-transform. The pixel grid needs no half-pixel shift (shapes at integer coordinates cover the same pixels as in GDI+).
• Containers. BeginContainer maps its source rectangle onto its destination rectangle in the parent's coordinates and starts a fresh world transform; its page unit is taken as pixels. Save/Restore/EndContainer share one stack and map to save/restore.
• Objects. Brushes (solid, hatch, texture, linear and path gradient), pens (dash styles and custom dashes, dash offset and cap, joins, inset alignment on rectangles and ellipses), paths, regions (a tree of rectangles and paths, combined with the exact path booleans), images (bitmaps in all pixel formats, compressed images through the core decoders, embedded EMF files played as commands inside their destination), fonts, string formats and image attributes, including objects that are split across records. Limits: MaxPlusObjectBytes for an object (and the sum of its parts), MaxNestedMetafileDepth for metafiles inside images; points, regions, bitmaps, saves and text use the existing limits.
• Drawing. Clear, fill and draw of rectangles, polygons, ellipses, pies, arcs, lines, Beziers, cardinal splines (open, closed, with offset and segment count), paths and regions; images (DrawImage, DrawImagePoints), strings and driver strings; clip records with all combine modes (Complement is replaced by Replace, with a warning), reset and offset.
• Hints. Smoothing (anti-aliasing), source-copy compositing and the interpolation mode change the raster output; the others are carried in rendering-hints.
• Fidelity choices measured against GDI+. Arc and pie angles are ray angles from the ellipse center, converted to the ellipse's parametric angle. A path's winding fill mode is bit 0x2000 of its flags (the table in [MS-EMFPLUS] does not list it). Strings without a string format have a margin of 1/6 em on both sides, as GDI+ draws them; the first baseline is the ascent below the top of the layout rectangle.
• Gaps (each reports a diagnostic). Triangle, anchor and custom pen line caps (drawn flat), compound pens (drawn solid), image effects and color matrices, path gradient blend ramps, EmfPlusStrokeFillPath (no defined layout), multi-format records, glyph-index driver strings (taken as characters), and the 54 hatch styles that are dithers or weaves are approximations of the GDI+ patterns.

Limits and safety

MetafileLimits bounds the file size, record and command counts, object table, path points, bitmap pixels (per bitmap and in total), save depth, region rectangles, text length, dash entries, and a total work budget; every size read from a record is checked against the record's own length and these limits before an allocation, and a bad record is skipped with a diagnostic rather than failing the file. A file that breaks a limit throws ImageLimitException; a file with a bad header throws ImageFormatException. Interpretation is iterative (no recursion on input) and checks for cancellation.

Checked against Windows

tests/testdata/metafile/oracle holds 25 EMF files recorded with real GDI calls (rectangles, pens, arcs, polygons, Beziers, paths, clips, hatch and DIB brushes, bitmaps, ROPs, text, world transforms, mapping modes, gradients, alpha blending, regions, DC save/restore, stock objects) together with what PlayEnhMetaFile drew for each into a white 32-bit bitmap of 256x256 and 512x512 (a 150% display, ClearType on; the header's reference device is 2496x1664 px, 317x211 mm). Both the files and the images are generated by us; the notice beside them says so. WindowsReferenceTests renders each file without anti-aliasing over white, stretched to the same size, and counts pixels whose channels differ by more than 48; EveryCaseAgreesWithWindowsOnMostPixels keeps each case above 95%.

The pictures are 384 px wide at their natural size, so both comparison sizes are fractional scales, and GDI rounds shape corners to its own grid: most of the remaining differences are one-pixel edge placement. The rest: text in fonts other than Arial (the system raster fonts and Arial itself are not available to the renderer), the smoothing GDI applies to stretched bitmaps, WidenPath and text in paths (not interpreted).

tests/testdata/metafile/oracle-gdiplus holds 12 drawings recorded by GDI+ as EMF+ only and as EMF+ dual, with what GDI+ rendered for each (WindowsGdiPlusReferenceTests; the page-unit case could not be recorded by GDI+). Agreement on pixels (tolerance 48 per channel, anti-aliased, test fonts instead of Arial) for both variants, which render identically:

The brushes case loses most on the hatch patterns that are approximations and on texture phase at a scale of two thirds; the text case on the fonts (the machine had Arial, the tests use Noto Sans); the pens case on triangle caps and compound lines.

The pictures are 384 px wide at their natural size, so both comparison sizes are fractional scales, and GDI rounds shape corners to its own grid: most of the remaining differences are one-pixel edge placement. The rest: text in fonts other than Arial (the system raster fonts and Arial itself are not available to the renderer), the smoothing GDI applies to stretched bitmaps, WidenPath and text in paths (not interpreted), and ROP2 modes other than copy where GDI does not apply a fill under a wide pen's overlap twice (rop2).