Direct2D Text

May 25 2017

Direct2D and DWrite provide a lot of control over how the text is rendered, but there is a steep learning curve.

Simple Text

The simplest way to render text is using ID2D1RenderTarget::DrawTextW(), which has 5 prerequisites:

1. ID2D1Factory *pD2DFactory: This is the top-level interface used to create Direct2D objects. Only one instance should be created.

   D2D1Factory1 *pD2DFactory; int D2DGetFactory(void) { int Err= ERR_OK; HRESULT WinErr; D2D1_FACTORY_TYPE type= D2D1_FACTORY_TYPE_MULTI_THREADED; REFIID guid= __uuidof(ID2D1Factory1); D2D1_FACTORY_OPTIONS options; options.debugLevel= D2D1_DEBUG_LEVEL_INFORMATION; if(!SUCCEEDED(WinErr= D2D1CreateFactory(Type,guid,&options,(void**)&pD2DFactory))) { Err= Error(ERR_DIRECTX,"D2DGetFactory: Unable to create Direct2D factory. [%X]",WinErr); } return(Err); }

2. IDWriteFactory *pDWriteFactory: The top level interface to create DirectWrite objects. Only one instance should be created.

   IDWriteFactory *pDWriteFactory; int D2DCreateWriteFactory(void) { int Err= ERR_OK; HRESULT WinErr; DWRITE_FACTORY_TYPE Type= DWRITE_FACTORY_TYPE_SHARED; REFIID guid= __uuidof(IDWriteFactory); if(!SUCCEEDED(WinErr= DWriteCreateFactory(Type,guid,reinterpret_cast<IUnknown>(&pDWriteFactory))) { Err= Error(ERR_DIRECTX,"D2DCreateWriteFactory: Unable to create DirectWrite factory. [%X]",WinErr); } return(Err); }

3. ID2D1RenderTarget *pRT: This is the interface used to draw everything to the graphic "surface". The final render target for a window:

   int D2DGetWndRT(HWND hWnd, ID2D1HwndRenderTarget *&pRT, FLOAT *pPxlScaler) { int Err= ERR_OK; HRESULT WinErr; RECT rWnd; GetClientRect(hWnd,&rWnd); if(IsErr(Err= D2DGetFactory())) return(Err); const D2D1_RENDER_TARGET_PROPERTIES Prop= RenderTargetProperties(); D2D1_HWND_RENDER_TARGET_PROPERTIES WndProp= HwndRenderTargetProperties(hWnd,SizeU(RWID(rWnd),RHGT(rWnd))); //NOTE: CreateHwndRenderTarget() is not available for Microsoft Store programs. // I would need to use Device and DeviceContext instead. if(!SUCCEEDED(WinErr= pD2DFactory->CreateHwndRenderTarget(Prop,WndProp,&pWndRT))) return(Error(ERR_SYSCREATE,"D2DGetWndRT: Unable to create window RT. [%X]",WinErr)); if(pPxlScaler) { D2D1_SIZE_F PixelSz= pWndRT->GetSize(); //DIP units *pPxlScaler= (FLOAT)PixelSz.width/(FLOAT)RWID(rWnd); //Scales dialog units to DIP units. } return(Err); }

   Once I have the window RT, I can create compatible render targets that draw onto offscreen bitmaps.

   ID2D1BitmapRenderTarget *pImgRT; ID2D1Bitmap *pImgBM; if(!SUCCEEDED(WinErr= pWndRT->CreateCompatibleRenderTarget(size,&pImgRT))) { Warn(ERR_DIRECTX,"Unable to create offscreen render target. [%X]",WinErr); } else { pImgRT->GetBitmap(&pImgBM); }

4. IDWriteTextFormat *pFmt: Describes the text font, alignment, etc.

   int D2DCreateText(IDWriteTextFormat *&pFmt, FLOAT Hgt, const WCHAR *Font) { int Err= ERR_OK; HRESULT WinErr; if(!pDWriteFactory && !SUCCEEDED(WinErr= DWriteCreateFactory(DWRITE_FACTORY_TYPE_SHARED,__uuidof(IDWriteFactory),reinterpret_cast<IUnknown**>(&pDWriteFactory)))) return(Error(ERR_SYSCREATE,"D2DCreateText: Unable to create DWriteFactory [%X]",WinErr)); DWRITE_FONT_WEIGHT Weight= DWRITE_FONT_WEIGHT_NORMAL; DWRITE_FONT_STYLE Style= DWRITE_FONT_STYLE_NORMAL; DWRITE_FONT_STRETCH Stretch= DWRITE_FONT_STRETCH_NORMAL; if(!SUCCEEDED(WinErr= pDWriteFactory->CreateTextFormat(Font,0,Weight,Style,Stretch,Hgt,L"en-us",&pFmt))) return(Error(ERR_SYSCREATE,"D2DCreateText: Unable to create text '%S' [%X]",Font,WinErr)); return(Err); }

5. ID2D1SolidColorBrush *pbrFill: Describes the color and opacity of the brush.

   ID2D1SolidColorBrush *pbrBrush; pRT->CreateSolidColorBrush(ColorF(ColorF::Azure,0.75f),&pbrBrush);

Once all the prerequisites have been created, drawing the text is easy.

int DrawImage(D2D1RenderTarget *pRT, const WCHAR *Text) { int Err= ERR_OK; HRESULT WinErr; D2D1_RECT_F rText; rText.left= rClnt.left*PxlScaler; rText.top= rClnt.top*PxlScaler; rText.right= rClnt.right*PxlScaler; rText.bottom= rClnt.bottom*PxlScaler; pRT->BeginDraw(); pRT->Clear(); pRT->DrawTextW(Text,wcslen(Text),pFmt,rText,pbrText); if(!SUCCEEEDED(WinErr= pRT->EndDraw())) { Err= Warn(ERR_DIRECTX,"DrawImage: EndDraw() failed [%X]",WinErr); } return(Err); }

Getting Fancy

I can add an outline stroke to the text by implementing my own custom text render class by deriving the IDWriteTextRenderer class. This msdn page was enough to point me in the right direction, but lacked a lot of crucial details and the referenced example code seems to have been changed to a Windows Store version that doesn't use IDWriteTextRenderer at all. I found some random examples of DWrite code that might be helpful in the future.

Fortunately, the actual code is not too complex, but there are a lot of virtual functions that must be implemented or stubbed before it will even compile. I created a D2DCustomRender class that stubs in the virtual functions with code that returns ERROR_CALL_NOT_IMPLEMENTED.

I need to provide default or stub functions for:

• Constructor
• Destructor
• QueryInterface()
• AddRef()
• Release()
• IsPixelSnappingDisabled()
• GetCurrentTransform()
• GetPixelsPerDip()
• DrawGlyphRun()
• DrawUnderline()
• DrawStrikethrough()
• DrawInlineObject()

To implement a stroked outline, I just need to provide a working DrawGlyphRun() function.

1. I am provided:
   • Context pointer (unused)
   • Starting point (OriginX,OriginY)
   • Measuring mode (unused)
   • Glyph run
   • Glyph description (unused)
2. I will be using (temporarily):
   • ID2D1PathGeometry *pPath;
   • ID2D1TransformedGeometry *pPathX
   • ID2D1GeometrySink *pSink;
3. Create a path geometry for the glyph outlines.

   pD2DFactory->CreatePathGeometry(&pPath);

4. Create a GeometrySink to receive the geometry.

   pPath->Open(&pSink);

5. Call GetGlyphRunOutline() to extract the glyph outlines into the path geometry.

   pGlyph->fontFace->GetGlyphRunOutline(...)

6. Close the geometry sink.

   pSink->Close()

7. Create a translation matrix to transform the draw operations to the requested text location.

   Matrix3x2F xform= Matrix3x2F::Identity(); xform= xform*Matrix3x2F::Translation(SizeF(OriginX,OriginY));

8. Create a transformed version of the outline path.

   pD2DFactory-&gtCreateTransformedGeometry(pPath,&pPathX);

9. Fill the geometry and draw the stroke.

   pRT->FillGeometry(pPathX,pbrFill); pRT->DrawGeometry(pPathX,pbrStroke,StrokeWidth);

10. Clean up

    SafeRelease(pPath); SafeRelease(pPathX); SafeRelease(pSink);

The final step is to provide a simple API to draw the text.

An example:

And it all works!

Now that I have access to the text outline, I could implement other fancy features like extrusions, drop shadows, etc.