ScriptShape 関数 (usp10.h)

[アーティクル]
03/13/2024

Unicode 実行のグリフとビジュアル属性を生成します。

構文

HRESULT ScriptShape(
  [in]      HDC             hdc,
  [in, out] SCRIPT_CACHE    *psc,
  [in]      const WCHAR     *pwcChars,
  [in]      int             cChars,
  [in]      int             cMaxGlyphs,
  [in, out] SCRIPT_ANALYSIS *psa,
  [out]     WORD            *pwOutGlyphs,
  [out]     WORD            *pwLogClust,
  [out]     SCRIPT_VISATTR  *psva,
  [out]     int             *pcGlyphs
);

パラメーター

[in] hdc

任意。デバイスコンテキストを処理します。詳細については、「キャッシュ」を参照してください。

[in, out] psc

スクリプトキャッシュを識別する SCRIPT_CACHE 構造体へのポインター。

[in] pwcChars

実行を定義する Unicode 文字の配列へのポインター。

[in] cChars

Unicode 実行の文字数。

[in] cMaxGlyphs

生成するグリフの最大数と pwOutGlyphs の長さ。妥当な値は (1.5 * cChars + 16)ですが、状況によってはこの値が不十分な場合があります。詳細については、「解説」を参照してください。

[in, out] psa

ScriptItemize の以前の呼び出しの結果を含む、実行のSCRIPT_ANALYSIS構造体へのポインター。

[out] pwOutGlyphs

この関数が cMaxGlyphs で示されるサイズのグリフの配列を取得するバッファーへのポインター。

[out] pwLogClust

この関数が論理クラスター情報の配列を取得するバッファーへのポインター。各配列要素は、Unicode 文字の配列内の文字に対応します。したがって、この配列には cChars で示される要素の数があります。各要素の値は、実行の最初のグリフから、対応する文字を含むクラスター内の最初のグリフまでのオフセットです。 fRTL メンバーがSCRIPT_ANALYSIS構造体で TRUE に設定されている場合、配列の読み取り時に要素が減少します。

[out] psva

この関数がビジュアル属性情報を含む SCRIPT_VISATTR 構造体の配列を取得するバッファーへのポインター。各グリフにはビジュアル属性が 1 つしかないため、この配列には cMaxGlyphs で示される要素の数があります。

[out] pcGlyphs

この関数が pwOutGlyphs で示されているグリフの数を取得する場所へのポインター。

戻り値

処理が正常に終了した場合は 0 を返します。関数が成功しない場合は、0 以外の HRESULT 値を返します。すべてのエラーケースで、すべての出力パラメーターの内容は未定義です。

エラーの戻り値は次のとおりです。

E_OUTOFMEMORY。 cMaxGlyphs で示される出力バッファーの長さが不十分です。
E_PENDING。 psc パラメーターで指定されたスクリプトキャッシュには、文字列を整形するための十分な情報が含まれていません。また、デバイスコンテキストが NULL として渡されているため、関数は整形プロセスを完了できません。アプリケーションは、実行に対して適切なデバイスコンテキストを設定し、 hdc の適切な値と他のすべてのパラメーターを同じにして、この関数を再度呼び出す必要があります。
USP_E_SCRIPT_NOT_IN_FONT。デバイスコンテキストに対応するフォントでは、 pwcChars によって示される実行に必要なスクリプトはサポートされていません。アプリケーションは、 ScriptGetCMap または別の関数を使用してフォントを選択する別のフォントを選択する必要があります。

注釈

この関数が通常呼び出されるコンテキストについては、「 Uniscribe でテキストを表示する」を参照してください。

この関数がE_OUTOFMEMORYを返す場合、十分な大きさのバッファーが提供されるまで、アプリケーションは ScriptShape を 繰り返し呼び出し、出力バッファーが連続して大きくなる可能性があります。コードポイントによって生成されるグリフの数は、スクリプトとフォントによって異なります。単純なスクリプトの場合、Unicode コードポイントによって 1 つのグリフが生成される場合があります。ただし、複雑なスクリプトフォントは、コンポーネントから文字を構築し、文字の数倍のグリフを生成する場合があります。また、無効な文字表現などの特殊なケースがあり、無効なシーケンスを表すために余分なグリフが追加されます。したがって、 pwOutGlyphs によって示されるバッファーのサイズに対する妥当な推測は、文字バッファーの長さの 1.5 倍に加えて、まれなケース (たとえば、無効なシーケンス表現など) に対して 16 個のグリフを追加します。

フォントまたはオペレーティングシステムがグリフインデックスをサポートできない場合、この関数はSCRIPT_ANALYSIS構造体の fNoGlyphIndex メンバーを設定できます。

アプリケーションは ScriptShape を 呼び出して、フォントが特定の文字列内の文字をサポートしているかどうかを判断できます。関数がS_OKを返す場合、アプリケーションは不足しているグリフの出力をチェックする必要があります。 SCRIPT_ANALYSIS構造体で fLogicalOrder が TRUE に設定されている場合、関数は常に元の Unicode 文字と同じ順序でグリフを生成します。 fLogicalOrder が FALSE に設定されている場合、この関数は右から左に並んだ項目を逆の順序で生成するため、ExtTextOut を呼び出す前に ScriptTextOut を元に戻す必要はありません。

SCRIPT_ANALYSISの eScript メンバーが SCRIPT_UNDEFINED に設定されている場合、シェイプは無効になります。この場合、 ScriptShape はフォント cmap テーブルにあるグリフを表示します。テーブルにグリフがない場合、関数はグリフが見つからないことを示します。

ScriptShape は、実行内でクラスターを一様にシーケンスし、クラスター内でグリフを一様にシーケンスします。 ScriptItemize の SCRIPT_ANALYSIS の fRTL メンバーの値を使用して、シーケンス処理を左から右または右から左に識別します。

大事なWindows 8以降: Windows 7 で実行する機能を維持するには、Uniscribe を使用するモジュールで、ライブラリリストで gdi32.lib の前に Usp10.lib を指定する必要があります。

例

次の例は、ScriptShape が文字配列 (pwcChars) とグリフ配列 (pwOutGlyphs) から論理クラスター配列 (pwLogClust) を生成する方法を示しています。実行には 4 つのクラスターがあります。

最初のクラスター: 1 つのグリフで表される 1 つの文字
2 番目のクラスター: 3 つのグリフで表される 1 文字
3 番目のクラスター: 1 つのグリフで表される 3 つの文字
4 番目のクラスター: 3 つのグリフで表される 2 つの文字

文字配列。c<n>u<m> はクラスター n、Unicode コードポイント m を意味します。

|c1u1 |c2u1 |c3u1 c3u2 c3u3 |c4u1 c4u2 |

グリフ配列。ここで、c<n>g<m> はクラスター n、グリフ m を意味します。

|c1g1 |c2g1 c2g2 c2g3 |c3g1 |c4g1 c4g2 c4g3 |

クラスター配列、つまり、文字を含むクラスターへのオフセット (グリフ単位)。

|0 |1 |4 4 4 |5 5 |

要件

要件	値
サポートされている最小のクライアント	Windows 2000 Professional [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows 2000 Server [デスクトップアプリのみ]
対象プラットフォーム	Windows
ヘッダー	usp10.h
Library	Usp10.lib
[DLL]	Usp10.dll