Search code examples
ioscore-text

What does CGContextSetTextMatrix do?

I am not sure what this function does or is supposed to do.

void CGContextSetTextMatrix (
   CGContextRef c,
   CGAffineTransform t
);

The reference isn't all that helpful. :(

Sets the current text matrix.

The text matrix specifies the transform from text space to user space. To produce the final text rendering matrix that is used to actually draw the text on the page, Quartz concatenates the text matrix with the current transformation matrix and other parameters from the graphics state.

Note that the text matrix is not a part of the graphics state—saving or restoring the graphics state has no effect on the text matrix. The text matrix is an attribute of the graphics context, not of the current font."

Can you explain it to me?

Solution

  • The text matrix is a special transform that's applied to text. You can use it to change the orientation of text drawn with Core Text (or Core Graphics before CGContextShowText was deprecated). On iOS, Core Text and Core Graphics have different coordinate systems. Typically you solve this by flipping the Core Graphics coordinate system, but it is possible to flip the text matrix instead, though I don't recommend it except for very simple text (it messes up text layout).

    (Why?!?!? he asks, would they have different coordinate systems? Well, because when iPhoneOS came along, Apple decided that iPhone devs would like the origin to be in the upper left like on Windows, rather than the lower left where mathematicians and Mac developers are used to it being. So they flipped the coordinate system, but when they ported over Core Text from Mac they kept its coordinate system, which was very good for all of us who have complicated text layout code that we could port over easily, and I'm sure it dramatically simplified porting, and... well... reasons. Not that this has anything to do with the text matrix; that's existed since 10.0, and exists so you can rotate text.)

    Since the text matrix is not initialized for you, it is best practice to always initialize it before drawing text with low-level frameworks. You initialize it like so:

    CGContextSetTextMatrix(context, CGAffineTransformIdentity);

    This of course is not necessary if you're drawing text with UIKit. UIKit will handle all of this for you.