Direct2D (36) : RenderTarget.DrawText() 与 IDWriteTextFormat

TDirect2DCanvas 提供了两种输出文本的方法：TextOut()、TextRect()，因太过高级，基本没有实用价值。

TDirect2DCanvas.RenderTarget 有三种输出文本的方法：DrawText()、DrawTextLayout()、DrawGlyphRun()。
DrawText() 对文本格式的控制能力类似 TMemo；
DrawTextLayout() 对文本格式的控制能力类似 TRichEdit；
DrawGlyphRun() 可以完成更复杂的字形输出。
另外 DirectWrite 还有其它文本输出方法，如回调 IDWriteTextRenderer 接口。

---

TDirect2DCanvas 的 TextOut()、TextRect() 都是简单调用了 TDirect2DCanvas.RenderTarget.DrawTextLayout()，
TDirect2DCanvas.RenderTarget.DrawText() 在 Direct2D.pas 中并没有出现。

使用 TDirect2DCanvas.RenderTarget.DrawText() 主要就是通过 IDWriteTextFormat 设置文本格式。

---

procedure DrawText(

  &string: PWCHAR;                          //文本

  stringLength: UINT;                       //文本长度

  const textFormat: IDWriteTextFormat;      //文本格式

  const layoutRect: D2D1_RECT_F;            //布局矩形

  const defaultForegroundBrush: ID2D1Brush; //前景画刷

  options: TD2D1DrawTextOptions;            //见下(参数6)；默认值 D2D1_DRAW_TEXT_OPTIONS_NONE;

  measuringMode: TDWriteMeasuringMode       //见下(参数7)；默认值 DWRITE_MEASURING_MODE_NATURAL

); stdcall;



{参数6}

options: TD2D1DrawTextOptions {指定是禁用文本对齐还是启用剪切到布局矩形，可使用按位组合值}

D2D1_DRAW_TEXT_OPTIONS_NO_SNAP = 1; //文本不垂直对齐到像素边界。建议对要进行动画处理的文本采用此设置。

D2D1_DRAW_TEXT_OPTIONS_CLIP    = 2; //文本剪切到布局矩形。

D2D1_DRAW_TEXT_OPTIONS_NONE    = 0; //文本垂直对齐到像素边界，但是不剪切到布局矩形。



{参数7}

measuringMode: TDWriteMeasuringMode {指示用于文本布局的度量方法}

DWRITE_MEASURING_MODE_NATURAL     = 0; //指定使用字符理想度量(其值与当前显示分辨率无关)对文本进行度量。

DWRITE_MEASURING_MODE_GDI_CLASSIC = 1; //指定使用与字符显示兼容的度量(其值针对当前显示分辨率进行了优化)对文本进行度量。

DWRITE_MEASURING_MODE_GDI_NATURAL = 2; //指定使用与 GDI 文本度量(使用通过 CLEARTYPE_NATURAL_QUALITY 创建的字体)相同的字符显示度量对文本进行度量。





{IDWriteTextFormat 接口的方法}

IDWriteTextFormat.GetFlowDirection        //获取文本行的排列方向。

IDWriteTextFormat.GetFontCollection       //获取当前字体集合。

IDWriteTextFormat.GetFontFamilyName       //获取字体系列名称的副本。

IDWriteTextFormat.GetFontFamilyNameLength //获取字体系列名称的长度。

IDWriteTextFormat.GetFontSize             //获取字体高度(以 em 单位)。

IDWriteTextFormat.GetFontStretch          //获取文本的字体拉伸方式。

IDWriteTextFormat.GetFontStyle            //获取文本的字体样式

IDWriteTextFormat.GetFontWeight           //获取文本的字体粗细

IDWriteTextFormat.GetIncrementalTabStop   //获取增量制表位的位置

IDWriteTextFormat.GetLineSpacing          //获取多行文本段落的行距调整设置

IDWriteTextFormat.GetLocaleName           //获取文本中区域设置名称的副本

IDWriteTextFormat.GetLocaleNameLength     //获取文本中区域设置名称的长度

IDWriteTextFormat.GetParagraphAlignment   //获取相对于布局框的顶部边缘和底部边缘的段落对齐选项

IDWriteTextFormat.GetReadingDirection     //获取段落中文本的当前读取方向

IDWriteTextFormat.GetTextAlignment        //获取相对于布局框的前端边缘和后端边缘的文本对齐选项

IDWriteTextFormat.GetTrimming             //获取溢出布局框的文本的剪裁选项

IDWriteTextFormat.GetWordWrapping         //获取自动换行选项

IDWriteTextFormat.SetFlowDirection        //设置段落排列方向

IDWriteTextFormat.SetIncrementalTabStop   //设置两个相邻制表位之间的固定距离

IDWriteTextFormat.SetLineSpacing          //设置行距

IDWriteTextFormat.SetParagraphAlignment   //设置相对于布局框的顶部边缘和底部边缘的段落对齐选项

IDWriteTextFormat.SetReadingDirection     //设置段落读取方向

IDWriteTextFormat.SetTextAlignment        //设置段落中文本的对齐选项(相对于布局框的前端边缘和后端边缘)

IDWriteTextFormat.SetTrimming             //设置溢出布局宽度的文本的剪裁选项

IDWriteTextFormat.SetWordWrapping         //设置自动换行选项

---

测试代码：

---

uses Direct2D, D2D1;



procedure TForm1.FormPaint(Sender: TObject);

var

  cvs: TDirect2DCanvas;

  str: string;

  iTextFormat: IDWriteTextFormat;

  iSolidColorBrush: ID2D1SolidColorBrush;

begin

  str := 'Hello World using DirectWrite!';



  {建立 IDWriteTextFormat 对象}

  DWriteFactory.CreateTextFormat(

    'Arial Black',              //字体名称

    nil,                        //字体集合指针, nil 表示使用系统字体集合

    DWRITE_FONT_WEIGHT_NORMAL,  //字体粗细

    DWRITE_FONT_STYLE_NORMAL,   //字体样式

    DWRITE_FONT_STRETCH_NORMAL, //字体拉伸

    48.0,                       //字体逻辑大小, 单位 DIP(1/96英寸)

    'en-us',                    //区域名称, 如 zh-CN

    iTextFormat                 //输出 IDWriteTextFormat 接口对象

  );

  iTextFormat.SetTextAlignment(DWRITE_TEXT_ALIGNMENT_CENTER);           //水平居中

  iTextFormat.SetParagraphAlignment(DWRITE_PARAGRAPH_ALIGNMENT_CENTER); //段落居中



  cvs := TDirect2DCanvas.Create(Canvas, ClientRect);

  cvs.RenderTarget.CreateSolidColorBrush(D2D1ColorF(clRed), nil, iSolidColorBrush);

  cvs.RenderTarget.BeginDraw;

  cvs.RenderTarget.Clear(D2D1ColorF(clWhite));

  cvs.RenderTarget.DrawText(PWideChar(str), Length(str), iTextFormat, ClientRect, iSolidColorBrush);

  cvs.RenderTarget.EndDraw();

  cvs.Free;

end;



procedure TForm1.FormResize(Sender: TObject);

begin

  Repaint;

end;

---

效果图：




调整 DWriteFactory.CreateTextFormat() 个别参数的效果：

---