ホーム › Graphics.DirectWrite › IDWriteTextAnalyzer
IDWriteTextAnalyzer
COM公式ドキュメント
アラビア語などの言語に対する双方向 (bidi) サポート、改行位置の決定、グリフの配置、数字の置換といった、複雑なスクリプト処理のために、さまざまなテキストプロパティを解析します。
メソッド 7
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
vtbl 3 HRESULT AnalyzeScript(IDWriteTextAnalysisSource* analysisSource, DWORD textPosition, DWORD textLength, IDWriteTextAnalysisSink* analysisSink)
テキスト範囲をスクリプト境界について解析します。ソースからテキスト属性を読み取り、Unicode スクリプト ID をシンクコールバック SetScript に報告します。
| analysisSource | IDWriteTextAnalysisSource* | in | 解析対象のソースオブジェクトへのポインター。 |
| textPosition | DWORD | in | ソースオブジェクト内の開始テキスト位置。 |
| textLength | DWORD | in | 解析するテキストの長さ。 |
| analysisSink | IDWriteTextAnalysisSink* | in | テキスト解析を受け取るシンクコールバックオブジェクトへのポインター。 |
戻り値
Type: HRESULT
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
vtbl 4 HRESULT AnalyzeBidi(IDWriteTextAnalysisSource* analysisSource, DWORD textPosition, DWORD textLength, IDWriteTextAnalysisSink* analysisSink)
テキスト範囲をスクリプトの方向性について解析します。ソースから属性を読み取り、レベルをシンクコールバック SetBidiLevel に報告します。
| analysisSource | IDWriteTextAnalysisSource* | in | 解析対象のソースオブジェクトへのポインター。 |
| textPosition | DWORD | in | ソースオブジェクト内の開始テキスト位置。 |
| textLength | DWORD | in | 解析するテキストの長さ。 |
| analysisSink | IDWriteTextAnalysisSink* | in | テキスト解析を受け取るシンクコールバックオブジェクトへのポインター。 |
戻り値
Type: HRESULT
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
この関数は複数の段落を扱えますが、テキスト範囲が段落の途中を任意に分割しないようにしてください。そうしないと、Bidi アルゴリズムは段落全体に適用されることを前提としているため、返されるレベルが正しくならない可能性があります。
vtbl 5 HRESULT AnalyzeNumberSubstitution(IDWriteTextAnalysisSource* analysisSource, DWORD textPosition, DWORD textLength, IDWriteTextAnalysisSink* analysisSink)
テキスト範囲を、数字の置換が適用可能なスパンについて解析します。ソースから属性を読み取り、置換可能な範囲をシンクコールバック SetNumberSubstitution に報告します。
| analysisSource | IDWriteTextAnalysisSource* | in | 解析対象のソースオブジェクト。 |
| textPosition | DWORD | in | ソースオブジェクト内の開始位置。 |
| textLength | DWORD | in | 解析する長さ。 |
| analysisSink | IDWriteTextAnalysisSink* | in | テキスト解析を受け取るシンクコールバックオブジェクトへのポインター。 |
戻り値
Type: HRESULT
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
この関数は数字の置換が異なる複数の範囲を扱えますが、テキスト範囲が数字の途中を任意に分割しないようにしてください。そうしないと、数字が別々に扱われ、間に挟まれる区切り記号が変換されなくなります。
vtbl 6 HRESULT AnalyzeLineBreakpoints(IDWriteTextAnalysisSource* analysisSource, DWORD textPosition, DWORD textLength, IDWriteTextAnalysisSink* analysisSink)
テキスト範囲を、改行の候補位置について解析します。ソースから属性を読み取り、改行の候補位置をシンクコールバック SetLineBreakpoints に報告します。
| analysisSource | IDWriteTextAnalysisSource* | in | 解析対象のソースオブジェクトへのポインター。 |
| textPosition | DWORD | in | ソースオブジェクト内の開始テキスト位置。 |
| textLength | DWORD | in | 解析するテキストの長さ。 |
| analysisSink | IDWriteTextAnalysisSink* | in | テキスト解析を受け取るシンクコールバックオブジェクトへのポインター。 |
戻り値
Type: HRESULT
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
この関数は複数の段落を扱えますが、指定したテキストスパンが一つのまとまりとみなされる場合を除き、テキスト範囲が段落の途中を任意に分割しないようにしてください。そうしないと、先頭および末尾の文字について返されるプロパティが、不適切に改行を許可してしまいます。
vtbl 7 HRESULT GetGlyphs(LPWSTR textString, DWORD textLength, IDWriteFontFace* fontFace, BOOL isSideways, BOOL isRightToLeft, DWRITE_SCRIPT_ANALYSIS* scriptAnalysis, LPWSTR localeName, IDWriteNumberSubstitution* numberSubstitution, DWRITE_TYPOGRAPHIC_FEATURES** features, DWORD* featureRangeLengths, DWORD featureRanges, DWORD maxGlyphCount, WORD* clusterMap, DWRITE_SHAPING_TEXT_PROPERTIES* textProps, WORD* glyphIndices, DWRITE_SHAPING_GLYPH_PROPERTIES* glyphProps, DWORD* actualGlyphCount)
入力テキスト文字列を解析し、フォントおよび書記体系のレンダリング規則に従って、グリフの集合と関連するグリフデータにマッピングします。
| textString | LPWSTR | in | グリフに変換する文字の配列。 |
| textLength | DWORD | in | textString の長さ。 |
| fontFace | IDWriteFontFace* | in | 出力グリフのソースとなるフォントフェイス。 |
| isSideways | BOOL | in | テキストを縦方向に描画する場合に TRUE を設定するブールフラグ。 |
| isRightToLeft | BOOL | in | 右から左へのテキストの場合に TRUE を設定するブールフラグ。 |
| scriptAnalysis | DWRITE_SCRIPT_ANALYSIS* | in | AnalyzeScript 呼び出しによるスクリプト解析結果へのポインター。 |
| localeName | LPWSTR | inoptional | グリフを選択する際に使用するロケール。たとえば、同じ文字でも ja-jp と zh-chs とで異なるグリフにマッピングされる場合があります。これが NULL の場合は、スクリプトに基づく既定のマッピングが使用されます。 |
| numberSubstitution | IDWriteNumberSubstitution* | inoptional | AnalyzeNumberSubstitution から得られた結果に応じて、数字および関連する数値文字に適切なグリフを選択する、省略可能な数字置換へのポインター。NULL を渡すと、置換が不要であり、数字には既定のグリフを割り当てるべきであることを示します。 |
| features | DWRITE_TYPOGRAPHIC_FEATURES** | inoptional | 各フィーチャー範囲で使用する組版フィーチャーの集合へのポインターの配列。 |
| featureRangeLengths | DWORD* | inoptional | 各フィーチャー範囲の長さ (文字単位)。すべての長さの合計は textLength と等しくなる必要があります。 |
| featureRanges | DWORD | in | フィーチャー範囲の数。 |
| maxGlyphCount | DWORD | in | 返すことができるグリフの最大数。 |
| clusterMap | WORD* | out | このメソッドが返るときに、文字範囲からグリフ範囲へのマッピングが格納されます。 |
| textProps | DWRITE_SHAPING_TEXT_PROPERTIES* | out | このメソッドが返るときに、各文字のシェーピングプロパティを含む構造体の配列へのポインターが格納されます。 |
| glyphIndices | WORD* | out | 出力されるグリフインデックス。 |
| glyphProps | DWRITE_SHAPING_GLYPH_PROPERTIES* | out | このメソッドが返るときに、各出力グリフのシェーピングプロパティを含む構造体の配列へのポインターが格納されます。 |
| actualGlyphCount | DWORD* | out | このメソッドが返るときに、呼び出しが成功した場合は実際に返されたグリフの数が格納されます。 |
戻り値
Type: HRESULT
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
文字からグリフへのマッピングは、一般に多対多であることに注意してください。グリフ単位の出力バッファーの推奨見積もりは (3 * textLength / 2 + 16) です。これで十分であることは保証されません。
actualGlyphCount パラメーターの値は、呼び出しが成功した場合にのみ有効です。maxGlyphCount が十分な大きさでない場合は、HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) が返されます。アプリケーションは、より大きなバッファーを割り当てて再試行する必要があります。
vtbl 8 HRESULT GetGlyphPlacements(LPWSTR textString, WORD* clusterMap, DWRITE_SHAPING_TEXT_PROPERTIES* textProps, DWORD textLength, WORD* glyphIndices, DWRITE_SHAPING_GLYPH_PROPERTIES* glyphProps, DWORD glyphCount, IDWriteFontFace* fontFace, FLOAT fontEmSize, BOOL isSideways, BOOL isRightToLeft, DWRITE_SCRIPT_ANALYSIS* scriptAnalysis, LPWSTR localeName, DWRITE_TYPOGRAPHIC_FEATURES** features, DWORD* featureRangeLengths, DWORD featureRanges, FLOAT* glyphAdvances, DWRITE_GLYPH_OFFSET* glyphOffsets)
GetGlyphs メソッドから出力されたグリフを、フォントおよび書記体系のレンダリング規則に従って配置します。
| textString | LPWSTR | in | グリフの元となった元の文字列を含む文字の配列。 |
| clusterMap | WORD* | in | 文字範囲からグリフ範囲へのマッピングへのポインター。これは GetGlyphs によって返されます。 |
| textProps | DWRITE_SHAPING_TEXT_PROPERTIES* | inout | 各文字のシェーピングプロパティを含む構造体の配列へのポインター。この構造体は GetGlyphs によって返されます。 |
| textLength | DWORD | in | textString のテキストの長さ。 |
| glyphIndices | WORD* | in | GetGlyphs によって返されるグリフインデックスの配列。 |
| glyphProps | DWRITE_SHAPING_GLYPH_PROPERTIES* | in | GetGlyphs によって返される各グリフのシェーピングプロパティを含む構造体の配列へのポインター。 |
| glyphCount | DWORD | in | GetGlyphs から返されるグリフの数。 |
| fontFace | IDWriteFontFace* | in | 出力グリフのソースとなるフォントフェイスへのポインター。 |
| fontEmSize | FLOAT | in | 論理フォントサイズ (DIP 単位)。 |
| isSideways | BOOL | in | テキストを縦方向に描画する場合に TRUE を設定するブールフラグ。 |
| isRightToLeft | BOOL | in | 右から左へのテキストの場合に TRUE を設定するブールフラグ。 |
| scriptAnalysis | DWRITE_SCRIPT_ANALYSIS* | in | AnalyzeScript 呼び出しによるスクリプト解析結果へのポインター。 |
| localeName | LPWSTR | inoptional | グリフを選択する際に使用するロケールを含む文字の配列。たとえば、同じ文字でも ja-jp と zh-chs とで異なるグリフにマッピングされる場合があります。これが NULL の場合は、スクリプトに基づく既定のマッピングが使用されます。 |
| features | DWRITE_TYPOGRAPHIC_FEATURES** | inoptional | 各フィーチャー範囲で使用する組版フィーチャーの集合へのポインターの配列。 |
| featureRangeLengths | DWORD* | inoptional | 各フィーチャー範囲の長さ (文字単位)。すべての長さの合計は textLength と等しくなる必要があります。 |
| featureRanges | DWORD | in | フィーチャー範囲の数。 |
| glyphAdvances | FLOAT* | out | このメソッドが返るときに、各グリフの送り幅 (advance width) が格納されます。 |
| glyphOffsets | DWRITE_GLYPH_OFFSET* | out | このメソッドが返るときに、各グリフの原点のオフセットが格納されます。 |
戻り値
Type: HRESULT
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
vtbl 9 HRESULT GetGdiCompatibleGlyphPlacements(LPWSTR textString, WORD* clusterMap, DWRITE_SHAPING_TEXT_PROPERTIES* textProps, DWORD textLength, WORD* glyphIndices, DWRITE_SHAPING_GLYPH_PROPERTIES* glyphProps, DWORD glyphCount, IDWriteFontFace* fontFace, FLOAT fontEmSize, FLOAT pixelsPerDip, DWRITE_MATRIX* transform, BOOL useGdiNatural, BOOL isSideways, BOOL isRightToLeft, DWRITE_SCRIPT_ANALYSIS* scriptAnalysis, LPWSTR localeName, DWRITE_TYPOGRAPHIC_FEATURES** features, DWORD* featureRangeLengths, DWORD featureRanges, FLOAT* glyphAdvances, DWRITE_GLYPH_OFFSET* glyphOffsets)
GetGlyphs メソッドから出力されたグリフを、フォントおよび書記体系のレンダリング規則に従って配置します。
| textString | LPWSTR | in | グリフの元となった元の文字列を含む文字の配列。 |
| clusterMap | WORD* | in | 文字範囲からグリフ範囲へのマッピングへのポインター。これは GetGlyphs によって返されます。 |
| textProps | DWRITE_SHAPING_TEXT_PROPERTIES* | in | 各文字のシェーピングプロパティを含む構造体の配列へのポインター。この構造体は GetGlyphs によって返されます。 |
| textLength | DWORD | in | textString のテキストの長さ。 |
| glyphIndices | WORD* | in | GetGlyphs によって返されるグリフインデックスの配列。 |
| glyphProps | DWRITE_SHAPING_GLYPH_PROPERTIES* | in | GetGlyphs によって返される各グリフのシェーピングプロパティを含む構造体の配列へのポインター。 |
| glyphCount | DWORD | in | GetGlyphs から返されるグリフの数。 |
| fontFace | IDWriteFontFace* | in | 出力グリフのソースとなるフォントフェイスへのポインター。 |
| fontEmSize | FLOAT | in | 論理フォントサイズ (DIP 単位)。 |
| pixelsPerDip | FLOAT | in | DIP あたりの物理ピクセル数。 |
| transform | DWRITE_MATRIX* | inoptional | グリフおよびその位置に適用される省略可能な変換。この変換は、フォントサイズと pixelsPerDip によって指定されるスケーリングの後に適用されます。 |
| useGdiNatural | BOOL | in | FALSE に設定すると、メトリックは GDI のエイリアステキストのメトリックと同じになります。TRUE に設定すると、メトリックは CLEARTYPE_NATURAL_QUALITY で作成されたフォントを使用して GDI で計測されたテキストのメトリックと同じになります。 |
| isSideways | BOOL | in | テキストを縦方向に描画する場合に TRUE を設定するブールフラグ。 |
| isRightToLeft | BOOL | in | 右から左へのテキストの場合に TRUE を設定するブールフラグ。 |
| scriptAnalysis | DWRITE_SCRIPT_ANALYSIS* | in | AnalyzeScript 呼び出しによるスクリプト解析結果へのポインター。 |
| localeName | LPWSTR | inoptional | グリフを選択する際に使用するロケールを含む文字の配列。たとえば、同じ文字でも ja-jp と zh-chs とで異なるグリフにマッピングされる場合があります。これが NULL の場合は、スクリプトに基づく既定のマッピングが使用されます。 |
| features | DWRITE_TYPOGRAPHIC_FEATURES** | inoptional | 各フィーチャー範囲で使用する組版フィーチャーの集合へのポインターの配列。 |
| featureRangeLengths | DWORD* | inoptional | 各フィーチャー範囲の長さ (文字単位)。すべての長さの合計は textLength と等しくなる必要があります。 |
| featureRanges | DWORD | in | フィーチャー範囲の数。 |
| glyphAdvances | FLOAT* | out | このメソッドが返るときに、各グリフの送り幅 (advance width) が格納されます。 |
| glyphOffsets | DWRITE_GLYPH_OFFSET* | out | このメソッドが返るときに、各グリフの原点のオフセットが格納されます。 |
戻り値
Type: HRESULT
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
出力引数:
#define global IID_IDWriteTextAnalyzer "{B7E6163E-7F46-43B4-84B3-E4E6249C365D}" #usecom global IDWriteTextAnalyzer IID_IDWriteTextAnalyzer "{}" #comfunc global IDWriteTextAnalyzer_AnalyzeScript 3 sptr,int,int,sptr #comfunc global IDWriteTextAnalyzer_AnalyzeBidi 4 sptr,int,int,sptr #comfunc global IDWriteTextAnalyzer_AnalyzeNumberSubstitution 5 sptr,int,int,sptr #comfunc global IDWriteTextAnalyzer_AnalyzeLineBreakpoints 6 sptr,int,int,sptr #comfunc global IDWriteTextAnalyzer_GetGlyphs 7 wstr,int,sptr,int,int,var,wstr,sptr,var,var,int,int,var,var,var,var,var #comfunc global IDWriteTextAnalyzer_GetGlyphPlacements 8 wstr,var,var,int,var,var,int,sptr,float,int,int,var,wstr,var,var,int,var,var #comfunc global IDWriteTextAnalyzer_GetGdiCompatibleGlyphPlacements 9 wstr,var,var,int,var,var,int,sptr,float,float,var,int,int,int,var,wstr,var,var,int,var,var ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IDWriteTextAnalyzer "{B7E6163E-7F46-43B4-84B3-E4E6249C365D}" #usecom global IDWriteTextAnalyzer IID_IDWriteTextAnalyzer "{}" #comfunc global IDWriteTextAnalyzer_AnalyzeScript 3 sptr,int,int,sptr #comfunc global IDWriteTextAnalyzer_AnalyzeBidi 4 sptr,int,int,sptr #comfunc global IDWriteTextAnalyzer_AnalyzeNumberSubstitution 5 sptr,int,int,sptr #comfunc global IDWriteTextAnalyzer_AnalyzeLineBreakpoints 6 sptr,int,int,sptr #comfunc global IDWriteTextAnalyzer_GetGlyphs 7 wstr,int,sptr,int,int,sptr,wstr,sptr,sptr,sptr,int,int,sptr,sptr,sptr,sptr,sptr #comfunc global IDWriteTextAnalyzer_GetGlyphPlacements 8 wstr,sptr,sptr,int,sptr,sptr,int,sptr,float,int,int,sptr,wstr,sptr,sptr,int,sptr,sptr #comfunc global IDWriteTextAnalyzer_GetGdiCompatibleGlyphPlacements 9 wstr,sptr,sptr,int,sptr,sptr,int,sptr,float,float,sptr,int,int,int,sptr,wstr,sptr,sptr,int,sptr,sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。