Question

I’m trying to make a GlyphRun instance for use in a GlyphRunDrawing, but the documentation is just so bad that it’s almost comical. For example, the parameter renderingEmSize is described like this:

renderingEmSizeType: System.Double
A value of type Double.

Just… wow.

I know what an “em” is in a font (width of the em dash), but I don’t know what the grid units are. Device pixels? Device independent pixels?

Answer 1

Turns out the answer is in the source code. Thanks for MS making this available, if they are going to make eyes bleed on the docs.

Interestingly, all the information we need is contained in the xml doc comments on GlyphRun.cs. The renderingEmSize for example, is as follows:

<param name="renderingEmSize">Font rendering size in drawing surface units (96ths of an inch).</param>

The rest of the file is similarly well-commented, including this seemingly out-of-place but gripping read:

/*
The default branch prediction rules for modern processors specify that forward branches
are not to be taken. If the branch is in fact taken, all of the speculatively executed code
must be discarded, the processor pipeline flushed, and then reloaded. This results in a
processor stall of at least 42 cycles for the P4 Northwood for each mis-predicted branch. 
The deeper the processor pipeline the higher the cost, i.e. Prescott processors.
Checking for multiple incorrect parameters in a method with high call count like this one can 
easily add significant overhead for no reason. Note that the C# compiler should be able to make 
reasonable assumptions about branches that throw exceptions, but the current whidbey
implemenation is weak in this regard. Also the current IBC tools are unable to add branch 
prediction hints to improve behavior based on run time information. Also note that adding
branch prediction hints increases code size by a byte per branch and doing this in every
method that is coded without default branch prediction behavior in mind would add an
unacceptable amount of working set. 
*/

The whole file can be found here: GlyphRun.cs at webtropy